Files
cflmy 9331af78e2 release(2.8.0): 合入 CHANGELOG/README/发版说明/skills prove 任务;CI 链接指向 doc/releases
- 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。
2026-11-18 10:29:26 +08:00

22 KiB
Executable File
Raw Permalink Blame History

markup, title, description, import
markup title description import
occlusion lib/外联 通过本机解释器运行绑定的代码围栏与内联源码
table
lib/table.mq.md

通过本机解释器运行绑定的代码围栏与内联源码。

向外部语言进程与会话明确传递数据。

能力与边界:语言已配置不代表解释器已安装。执行接口提供退出码、超时和输出限额,需要 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=实际)*。