- CHANGELOG.md:v2.8.0 条目(中英双语); - README.md:版本行 2.7.1→2.8.0 + 愿景第 6 条(知识可证明); - doc/releases/v2.8.0.md:双语发版说明(亮点/用法/已知限制); - skills/marqdo-dev/index.mq.md:新增 prove 任务(路径/目录模式/ require_lean/json;参数用 + 行声明升参,check 与 narrative-ratio 通过); - 设计文档 §12.5 标记已合入;发版链接统一指向 doc/releases/v2.8.0.md。
22 KiB
Executable File
markup, title, description, import
| markup | title | description | import | ||
|---|---|---|---|---|---|
| occlusion | lib/外联 | 通过本机解释器运行绑定的代码围栏与内联源码 |
|
通过本机解释器运行绑定的代码围栏与内联源码。
向外部语言进程与会话明确传递数据。
能力与边界:语言已配置不代表解释器已安装。执行接口提供退出码、超时和输出限额,需要 process.exec;持久会话由创建者负责关闭,不透明句柄不能伪造或 JSON 序列化。
本文件就是调用和开发手册:直接导入此文件,或用 marqdo call 按下面的函数标题调用。参数表说明类型和默认值;未填默认值的参数必须提供。返回表是渐进契约,后文说明失败与边界。
实现入口:src/host/foreign.rs
开发时保持中英文语义一致,先组合公开库;仅在 OS 或算法边界添加宿主原语并声明效应。修改后运行 marqdo check --narrative-ratio 本文件,并执行 tests/stdlib_tasks.rs 的真实任务。
设置命令
| 参数 | 类型 | 默认 | 说明 |
|---|---|---|---|
| 语言 | any | 必填 | 已注册的解释器语言标识,例如 node |
| 命令 | any | 必填 | 可执行命令或解释器覆盖配置 |
| 参数 | any | None | 传给命令或函数的实参列表 |
| 返回 | 类型 | 说明 |
|---|---|---|
| result | any | 为语言绑定解释器命令;可选附加参数 |
这里使用语言、命令、参数=None。
调用效应:pure。
为语言绑定解释器命令;可选附加参数。
完成后返回*[为语言绑定解释器命令;可选附加参数](> host_foreign_set_cmd lang=语言 cmd=命令 args=参数)*。
运行
| 参数 | 类型 | 默认 | 说明 |
|---|---|---|---|
| 代码 | any | 必填 | 已绑定的代码围栏值;内联文本请使用语言与源码参数 |
| 标准输入 | any | None | 写入子进程标准输入的文本 |
| 环境 | any | None | 传给子进程的环境变量与值记录 |
| 工作目录 | any | None | 子进程工作目录 |
| 超时 | any | None | 执行超时秒数;None 使用宿主默认值 |
| 参数 | any | None | 传给命令或函数的实参列表 |
| 最大输出 | any | None | 捕获输出的字节上限;None 使用宿主默认值 |
| 返回 | 类型 | 说明 |
|---|---|---|
| result | any | 运行已绑定的代码围栏值;可选标准输入、环境表、工作目录、超时(秒)、 附加参数与输出上限 |
这里使用代码、标准输入=None、环境=None、工作目录=None、超时=None、参数=None、最大输出=None。
调用效应:process.exec。
运行已绑定的代码围栏值;可选标准输入、环境表、工作目录、超时(秒)、 附加参数与输出上限。返回 stdout 文本;非 0 退出即报错。
调用例:[外联.运行] 代码=块
完成后返回*[运行已绑定的代码围栏值;可选标准输入、环境表、工作目录、超时(秒)、 附加参数与输出上限](> host_foreign_run code=代码 stdin=标准输入 env=环境 cwd=工作目录 timeout=超时 args=参数 max_output=最大输出)*。
按语言运行
| 参数 | 类型 | 默认 | 说明 |
|---|---|---|---|
| 语言 | any | 必填 | 已注册的解释器语言标识,例如 node |
| 源码 | any | 必填 | 交给指定解释器执行的源文本 |
| 标准输入 | any | None | 写入子进程标准输入的文本 |
| 环境 | any | None | 传给子进程的环境变量与值记录 |
| 工作目录 | any | None | 子进程工作目录 |
| 超时 | any | None | 执行超时秒数;None 使用宿主默认值 |
| 参数 | any | None | 传给命令或函数的实参列表 |
| 最大输出 | any | None | 捕获输出的字节上限;None 使用宿主默认值 |
| 返回 | 类型 | 说明 |
|---|---|---|
| result | any | 用语言运行源码文本;选项同“运行” |
这里使用语言、源码、标准输入=None、环境=None、工作目录=None、超时=None、参数=None、最大输出=None。
调用效应:process.exec。
用语言运行源码文本;选项同“运行”。
完成后返回*[用语言运行源码文本;选项同“运行”](> host_foreign_run_lang lang=语言 source=源码 stdin=标准输入 env=环境 cwd=工作目录 timeout=超时 args=参数 max_output=最大输出)*。
执行
| 参数 | 类型 | 默认 | 说明 |
|---|---|---|---|
| 代码 | any | None | 已绑定的代码围栏值;内联文本请使用语言与源码参数 |
| 语言 | any | None | 已注册的解释器语言标识,例如 node |
| 源码 | any | None | 交给指定解释器执行的源文本 |
| 标准输入 | any | None | 写入子进程标准输入的文本 |
| 输入 | any | None | 编码为 JSON 后写入标准输入的结构化值;不能与标准输入文本同时使用 |
| 环境 | any | None | 传给子进程的环境变量与值记录 |
| 工作目录 | any | None | 子进程工作目录 |
| 超时 | any | None | 执行超时秒数;None 使用宿主默认值 |
| 参数 | any | None | 传给命令或函数的实参列表 |
| 输出 | any | "auto" | 结果解码方式:auto、text、json 或 lines |
| 最大输出 | any | None | 捕获输出的字节上限;None 使用宿主默认值 |
| 命令 | any | None | 可执行命令或解释器覆盖配置 |
| 保留 | any | False | 是否保留生成的脚本以便检查 |
| 返回 | 类型 | 说明 |
|---|---|---|
| result | any | 运行代码或“语言+源码”,返回记录 map,而不是在进程失败时直接报错 |
这里使用代码=None、语言=None、源码=None、标准输入=None、输入=None、环境=None、工作目录=None、超时=None、参数=None、输出="auto"、最大输出=None、命令=None、保留=False。
调用效应:process.exec。
运行代码或“语言+源码”,返回记录 map,而不是在进程失败时直接报错。 字段:ok、code、stdout、stderr、ms、lang、cmd、timed_out、truncated、 result、result_error、error、script、cached。
输入 会编码为 JSON 写入 stdin(与 标准输入 互斥)。输出 可取
auto | text | json | lines。命令 仅本次覆盖解释器。
完成后返回*[运行代码或“语言+源码”,返回记录 map,而不是在进程失败时直接报错](> host_foreign_invoke code=代码 lang=语言 source=源码 stdin=标准输入 input=输入 env=环境 cwd=工作目录 timeout=超时 args=参数 output=输出 max_output=最大输出 cmd=命令 keep=保留)*。
探测
| 参数 | 类型 | 默认 | 说明 |
|---|---|---|---|
| 语言 | any | None | 已注册的解释器语言标识,例如 node |
| 返回 | 类型 | 说明 |
|---|---|---|
| result | any | 探测一个语言;省略语言时探测所有已知语言 |
这里使用语言=None。
调用效应:process.exec。
探测一个语言;省略语言时探测所有已知语言。返回 {lang, cmd, path, ok, version, error}(省略语言时是列表)。
完成后返回*[探测一个语言;省略语言时探测所有已知语言](> host_foreign_probe lang=语言)*。
注册
| 参数 | 类型 | 默认 | 说明 |
|---|---|---|---|
| 语言 | any | 必填 | 已注册的解释器语言标识,例如 node |
| 命令 | any | None | 可执行命令或解释器覆盖配置 |
| 参数 | any | None | 传给命令或函数的实参列表 |
| 模板 | any | None | 解释器启动模板 |
| 扩展名 | any | None | 临时脚本的文件扩展名 |
| 环境 | any | None | 传给子进程的环境变量与值记录 |
| 版本参数 | any | None | 查询解释器版本时使用的参数 |
| 返回 | 类型 | 说明 |
|---|---|---|
| result | any | 注册语言调用 |
这里使用语言、命令=None、参数=None、模板=None、扩展名=None、环境=None、版本参数=None。
调用效应:pure。
注册语言调用。提供命令(+参数)或模板(占位符 {file}、{dir}、{base}、{inline}、{lang}、{cwd});二者互斥。
完成后返回*[注册语言调用](> host_foreign_register lang=语言 cmd=命令 args=参数 template=模板 ext=扩展名 env=环境 version_args=版本参数)*。
注销
| 参数 | 类型 | 默认 | 说明 |
|---|---|---|---|
| 语言 | any | 必填 | 已注册的解释器语言标识,例如 node |
| 返回 | 类型 | 说明 |
|---|---|---|
| result | any | 移除进程内注册;预设 / 配置 / 环境变量仍然生效 |
这里使用语言。
调用效应:pure。
移除进程内注册;预设 / 配置 / 环境变量仍然生效。
完成后返回*[移除进程内注册;预设 / 配置 / 环境变量仍然生效](> host_foreign_unset lang=语言)*。
加载配置
| 参数 | 类型 | 默认 | 说明 |
|---|---|---|---|
| 路径 | any | None | 授权文件根目录内的路径 |
| 返回 | 类型 | 说明 |
|---|---|---|
| result | any | 加载 .marqdo/foreign.toml(或显式路径);返回读取到的语言表数量 |
这里使用路径=None。
调用效应:fs.read。
加载 .marqdo/foreign.toml(或显式路径);返回读取到的语言表数量。
完成后返回*[加载 .marqdo/foreign.toml(或显式路径);返回读取到的语言表数量](> host_foreign_load_config path=路径)*。
调用
| 参数 | 类型 | 默认 | 说明 |
|---|---|---|---|
| 代码 | any | None | 已绑定的代码围栏值;内联文本请使用语言与源码参数 |
| 语言 | any | None | 已注册的解释器语言标识,例如 node |
| 源码 | any | None | 交给指定解释器执行的源文本 |
| 输入 | any | None | 编码为 JSON 后写入标准输入的结构化值;不能与标准输入文本同时使用 |
| 标准输入 | any | None | 写入子进程标准输入的文本 |
| 环境 | any | None | 传给子进程的环境变量与值记录 |
| 工作目录 | any | None | 子进程工作目录 |
| 超时 | any | None | 执行超时秒数;None 使用宿主默认值 |
| 参数 | any | None | 传给命令或函数的实参列表 |
| 返回 | 类型 | 说明 |
|---|---|---|
| result | any | JSON 进 / JSON 出:把 输入 编码到 stdin,解析 stdout JSON 返回值 (stdout 为空 → None) |
这里使用代码=None、语言=None、源码=None、输入=None、标准输入=None、环境=None、工作目录=None、超时=None、参数=None。
调用效应:process.exec。
JSON 进 / JSON 出:把 输入 编码到 stdin,解析 stdout JSON 返回值
(stdout 为空 → None)。进程失败或 JSON 非法时报错。
完成后返回*[JSON 进 / JSON 出:把 输入 编码到 stdin,解析 stdout JSON 返回值 (stdout 为空 → None)](> host_foreign_call code=代码 lang=语言 source=源码 input=输入 stdin=标准输入 env=环境 cwd=工作目录 timeout=超时 args=参数)*。
批量运行
| 参数 | 类型 | 默认 | 说明 |
|---|---|---|---|
| 任务表 | any | 必填 | 按顺序排列的代码或语言与源码运行记录 |
| 并发 | any | 4 | 最大并发操作数 |
| 返回 | 类型 | 说明 |
|---|---|---|
| result | any | 并行运行一组代码值或 invoke 选项 map;按输入顺序返回记录 |
这里使用任务表、并发=4。
调用效应:process.exec。
并行运行一组代码值或 invoke 选项 map;按输入顺序返回记录。单项失败不影响其它项。
完成后返回*[并行运行一组代码值或 invoke 选项 map;按输入顺序返回记录](> host_foreign_run_many runs=任务表 concurrency=并发)*。
批量调用
| 参数 | 类型 | 默认 | 说明 |
|---|---|---|---|
| 输入表 | any | 必填 | 批量调用所用的输入值 |
| 代码 | any | None | 已绑定的代码围栏值;内联文本请使用语言与源码参数 |
| 语言 | any | None | 已注册的解释器语言标识,例如 node |
| 源码 | any | None | 交给指定解释器执行的源文本 |
| 命令 | any | None | 可执行命令或解释器覆盖配置 |
| 环境 | any | None | 传给子进程的环境变量与值记录 |
| 工作目录 | any | None | 子进程工作目录 |
| 超时 | any | None | 执行超时秒数;None 使用宿主默认值 |
| 参数 | any | None | 传给命令或函数的实参列表 |
| 最大输出 | any | None | 捕获输出的字节上限;None 使用宿主默认值 |
| 并发 | any | 4 | 最大并发操作数 |
| 返回 | 类型 | 说明 |
|---|---|---|
| result | any | 把同一段代码并行作用到每个输入;按输入顺序返回解析后的 JSON 结果 |
这里使用输入表、代码=None、语言=None、源码=None、命令=None、环境=None、工作目录=None、超时=None、参数=None、最大输出=None、并发=4。
调用效应:process.exec。
把同一段代码并行作用到每个输入;按输入顺序返回解析后的 JSON 结果。 全部结束后若任一项失败,报错并指出下标。
完成后返回*[把同一段代码并行作用到每个输入;按输入顺序返回解析后的 JSON 结果](> host_foreign_call_many inputs=输入表 code=代码 lang=语言 source=源码 cmd=命令 env=环境 cwd=工作目录 timeout=超时 args=参数 max_output=最大输出 concurrency=并发)*。
会话
| 参数 | 类型 | 默认 | 说明 |
|---|---|---|---|
| 内核表 | any | None | 声明内核名称、语言及可选运行设置的普通表格 |
| 单元表 | any | None | 把文档中绑定的代码单元路由到明确内核 |
| 值表 | any | None | 内核、变量名与原生值组成的行记录 |
| 输入表 | any | None | 可选的逐单元输入值 |
| 返回 | 类型 | 说明 |
|---|---|---|
| result | map | 普通视图计划,含 kind/kernels/cells/values/inputs 五个字段 |
View 约定把声明计划绑定到入口中的 会话,以区分普通记录和低层会话句柄。
普通 ## main 函数可同时被 call 调用和 View 索引;完整声明可参照原生报表示例。
这里使用内核表=None、单元表=None、值表=None、输入表=None,声明后续 View 使用的普通数据。返回记录的 kind 是 foreign-session,另外四个字段保留传入规格。这个纯函数不会启动解释器、创建活内核或读取另一个文件;实际执行由 View 消费计划与绑定代码围栏时发生。
内核行显式指定语言。推荐工作流先用 Marqdo 固有库完成计算,再只把真正缺失的本地化展示交给 Node Intl。值表把 JSON 安全的数据拷贝送入命名变量,同一内核中的单元共享状态,不同内核保持隔离。缺失或错误的运行规格仍由实际视图会话给出诊断,不能被一份声明记录证明为已执行成功。
返回的是可以被 marqdo call 序列化的计划。会话开启得到的活资源则需要在同一个可调用流程内完成借用和关闭,不能根据字符串标识重建句柄。原生报告例程中的 format_summary 展示了两次持久求值、真实错误出口和关闭责任。
计划 =
| kind | kernels | cells | values | inputs |
|---|---|---|---|---|
| "foreign-session" | 内核表 |
单元表 |
值表 |
输入表 |
明确这些视图输入后,我们返回计划。
会话开启
| 参数 | 类型 | 默认 | 说明 |
|---|---|---|---|
| 语言 | any | 必填 | 已注册的解释器语言标识,例如 node |
| 命令 | any | None | 可执行命令或解释器覆盖配置 |
| 环境 | any | None | 传给子进程的环境变量与值记录 |
| 工作目录 | any | None | 子进程工作目录 |
| 超时 | any | None | 执行超时秒数;None 使用宿主默认值 |
| 返回 | 类型 | 说明 |
|---|---|---|
| result | any | 启动持久的 Python / Node 内核,返回不能跨 JSON 重建的不透明句柄 |
这里使用语言、命令=None、环境=None、工作目录=None、超时=None。
调用效应:process.exec。
启动持久的 Python / Node 内核,返回不能跨 JSON 重建的不透明句柄。超时 是每次求值的默认超时。
完成后返回*[启动持久的 Python / Node 内核,返回不能跨 JSON 重建的不透明句柄](> host_foreign_session_open lang=语言 cmd=命令 env=环境 cwd=工作目录 timeout=超时)*。
会话求值
| 参数 | 类型 | 默认 | 说明 |
|---|---|---|---|
| 标识 | any | 必填 | 会话开启返回并保留在本进程内的原始不透明句柄 |
| 代码 | any | None | 已绑定的代码围栏值;内联文本请使用语言与源码参数 |
| 源码 | any | None | 交给指定解释器执行的源文本 |
| 输入 | any | None | 编码为 JSON 后写入标准输入的结构化值;不能与标准输入文本同时使用 |
| 标准输入 | any | None | 写入子进程标准输入的文本 |
| 超时 | any | None | 执行超时秒数;None 使用宿主默认值 |
| 返回 | 类型 | 说明 |
|---|---|---|
| result | any | 求值状态记录,含 ok/code/result/stdout/stderr/alive/timed_out/ms |
这里使用标识、代码=None、源码=None、输入=None、标准输入=None、超时=None。
调用效应:process.exec。
求值状态记录,含 ok/code/result/stdout/stderr/alive/timed_out/ms。
输入 会编码为 JSON 交给内核。
完成后返回*[求值状态记录,含 ok/code/result/stdout/stderr/alive/timed_out/ms](> host_foreign_session_eval id=标识 code=代码 source=源码 input=输入 stdin=标准输入 timeout=超时)*。
会话设值
| 参数 | 类型 | 默认 | 说明 |
|---|---|---|---|
| 标识 | any | 必填 | 会话开启返回并保留在本进程内的原始不透明句柄 |
| 名称 | any | 必填 | 要解析、注册或查找的名称 |
| 值 | any | 必填 | 待转换或保存的值;不会就地修改输入 |
| 返回 | 类型 | 说明 |
|---|---|---|
| result | any | 把一个 Marqdo 值写入内核变量(JSON 拷贝) |
这里使用标识、名称、值。
调用效应:process.exec。
把一个 Marqdo 值写入内核变量(JSON 拷贝)。
完成后返回*[把一个 Marqdo 值写入内核变量(JSON 拷贝)](> host_foreign_session_set id=标识 name=名称 value=值)*。
会话取值
| 参数 | 类型 | 默认 | 说明 |
|---|---|---|---|
| 标识 | any | 必填 | 会话开启返回并保留在本进程内的原始不透明句柄 |
| 名称 | any | 必填 | 要解析、注册或查找的名称 |
| 返回 | 类型 | 说明 |
|---|---|---|
| result | any | 把一个内核变量读成 Marqdo 值 |
这里使用标识、名称。
调用效应:process.exec。
把一个内核变量读成 Marqdo 值。
完成后返回*[把一个内核变量读成 Marqdo 值](> host_foreign_session_get id=标识 name=名称)*。
会话中断
| 参数 | 类型 | 默认 | 说明 |
|---|---|---|---|
| 标识 | any | 必填 | 会话开启返回并保留在本进程内的原始不透明句柄 |
| 返回 | 类型 | 说明 |
|---|---|---|
| result | any | 中断持久内核当前求值;worker 支持时,会话仍可用于下一次求值 |
这里使用标识。
调用效应:process.exec。
中断持久内核当前求值;worker 支持时,会话仍可用于下一次求值。
完成后返回*[中断持久内核当前求值;worker 支持时,会话仍可用于下一次求值](> host_foreign_session_interrupt id=标识)*。
会话变量
| 参数 | 类型 | 默认 | 说明 |
|---|---|---|---|
| 标识 | any | 必填 | 会话开启返回并保留在本进程内的原始不透明句柄 |
| 返回 | 类型 | 说明 |
|---|---|---|
| result | any | 列出内核变量名 |
这里使用标识。
调用效应:process.exec。
列出内核变量名。
完成后返回*[列出内核变量名](> host_foreign_session_names id=标识)*。
会话关闭
| 参数 | 类型 | 默认 | 说明 |
|---|---|---|---|
| 标识 | any | 必填 | 会话开启返回并保留在本进程内的原始不透明句柄 |
| 返回 | 类型 | 说明 |
|---|---|---|
| result | any | 终止并移除会话;返回是否存在 |
这里使用标识。
调用效应:process.exec。
终止并移除会话;返回是否存在。
完成后返回*[终止并移除会话;返回是否存在](> host_foreign_session_close id=标识)*。
会话表
| 返回 | 类型 | 说明 |
|---|---|---|
| result | any | 列出活动会话的 id/lang/cmd/evals/alive/started_ms |
调用效应:process.exec。
列出活动会话的 id/lang/cmd/evals/alive/started_ms。
完成后返回*列出活动会话的 id/lang/cmd/evals/alive/started_ms*。
语言表
| 返回 | 类型 | 说明 |
|---|---|---|
| result | any | 列出已配置的外联语言 |
调用效应:pure。
直接调用此函数:
marqdo call lib/外联.mq.md 语言表 --effects none --json
列出已配置的外联语言。
返回当前外联注册表里的语言配置,不会启动解释器;是否安装可执行程序应另用探测接口确认。
完成后返回*列出已配置的外联语言*。
观测日志
| 返回 | 类型 | 说明 |
|---|---|---|
| result | list | 返回本次文档执行中已接纳的 eval/get/decode 观测记录,包含 index、channel、value;开启、赋值和关闭不新增观测。 |
调用效应:pure。
返回本次文档执行中已接纳的 eval/get/decode 观测记录,包含 index、channel、value;开启、赋值和关闭不新增观测。
完成后返回*[返回本次文档执行中已接纳的 eval/get/decode 观测记录,包含 index、channel、value;开启、赋值和关闭不新增观测](> host_oracle_journal )*。
重放检查
| 参数 | 类型 | 默认 | 说明 |
|---|---|---|---|
| 预期 | list | 必填 | 重放比较所用的预期观测记录 |
| 实际 | list | 必填 | 重放比较所用的实际观测记录 |
| 返回 | 类型 | 说明 |
|---|---|---|
| result | map | 不执行外部代码地比较两份观测日志;返回是否一致、最早差异位置和对应记录。 |
这里使用预期、实际。
调用效应:pure。
不执行外部代码地比较两份观测日志;返回是否一致、最早差异位置和对应记录。
完成后返回*[不执行外部代码地比较两份观测日志;返回是否一致、最早差异位置和对应记录](> host_oracle_replay_check expected=预期 observed=实际)*。