Files
marqdo/doc/design/foreign-kernel.md
T
cflmy 3001ed7ba5 feat(notebook): document session with shared kernels and view controls
D1/D2: 内核表/会话表 parsing, DocumentSession cell index, named/default kernels, shared state + isolation, run_cell/step/run_all/restart/assign, state bridge, journal, POST /api/session/*, and a live-view notebook bar with status badges, per-cell kernel selector, step/run-all and push/pull state form.
2026-10-18 01:39:36 +08:00

16 KiB
Raw Blame History

外联内核(Foreign Kernel)

状态 F0–F3.5 已实现
日期 2026-10-17
层 Runtime(src/foreign/ · src/host/foreign* · lib/foreign.mq.md)
相关 foreign-notebook-decisions.md · notebook-syntax.md · notebook-session.md · stdlib-foreign.md · stdlib-subtask.md
核心表面 Δ 无

外联内核 = 一个长期存活的外部语言进程 + 生命周期 + 类型桥 + 记录。它既能被 marqdo run 里的显式调用使用,也能被 view 的 notebook 会话使用。


1. 定位与边界

1.1 负责

  • 解释器发现、注册、配置、探测。
  • 一次性执行:临时脚本、stdin/stdout/stderr、超时、输出上限。
  • 持久内核:启动、求值、状态、关闭、列表。
  • 状态桥:session_set / session_get / session_names。
  • JSON 值桥:Marqdo Value ↔ JSON。
  • 结构化记录:ok/code/stdout/stderr/ms/timed_out/truncated/result/error。
  • 安全:exec 门禁、cwd 沙箱、进程组、并发/输出上限。
  • 视图诊断:代码卡片 Run 的完整结果。

1.2 不负责

  • 文档语法(内核表 / 会话表)→ notebook-syntax.md。
  • 文档会话 / cell 顺序 / journal / view UI → notebook-session.md。
  • Foreign → Marqdo 函数回调(v2 不做)。
  • 依赖安装(pip/npm)。
  • 远程 / 容器执行。

1.3 与相邻模块的区别

模块 生命周期 用途
foreign 一次性或持久 调外部语言;状态可选
subtask 一次性并发 后台任务、文件子任务、函数子任务
plugin 进程内 原生 C ABI 扩展
writeback 文档级 把输出写回 .mq.md

subtask 不管理持久状态;foreign 不管理文档执行顺序。


1.4 实施状态(2026-10-17)

阶段 状态 关键文件
F0 安全执行 / invoke 记录 ✅ src/host/foreign.rs
F1 预设 / probe / register / config ✅ src/foreign/registry.rs · src/host/foreign.rs
F2 JSON 桥 / run_many / call_many ✅ src/host/foreign.rs
F3 Python/Node 持久内核 ✅ src/host/foreign_session.rs
F3.5 session_set/get/names ✅ 同上
F4 history / view 打磨 / 发布 部分 —

测试:cargo test --lib foreign(11+)、cargo test --test gold lib_foreign(12,python 条件跳过)、tests/notebook/shared.mq.md 手工 view 验证。


2. 语言与内核模型

2.1 语言预设

lang 别名 默认命令 扩展名 版本探测 会话
python python3, py python3(Windows python) .py --version ✅
node javascript, js node .js -v ✅
deno — deno run .ts --version ❌
bun — bun .js --version ❌
ruby — ruby .rb --version ❌
perl — perl .pl --version ❌
php — php -r {inline} .php --version ❌
lua — lua .lua -v ❌
r rscript Rscript .R --version ❌
julia — julia .jl --version ❌
go — go run {file} .go version ❌
bash sh, shell bash .sh --version ❌
powershell pwsh, ps1 pwsh(Windows powershell) .ps1 --version ❌
sqlite sqlite3 sqlite3 .sql --version ❌
tsx typescript tsx .ts --version ❌

说明:

  • 预设只是默认值;注册 / 配置 / 环境变量整体覆盖。
  • 会话能力首批只有 Python / Node;其它语言一次性执行。
  • php 用 {inline},围栏里直接写 PHP,不需要 <?php。
  • deno 默认不给权限;需要时通过配置追加 --allow-*。

2.2 解析优先级

从高到低:

  1. 调用级 cmd(整行 argv,shell-like 切分)+ args(追加)。
  2. 进程内注册:register / set_cmd。
  3. 环境变量 MARQDO_FOREIGN_<LANG>(整行或 JSON 数组)。
  4. 项目配置 .marqdo/foreign.toml / MARQDO_FOREIGN_CONFIG。
  5. 内置预设。
  6. 都没有 → 带修复建议的诊断。

Python 额外发现顺序(在预设层内):

  1. VIRTUAL_ENV/bin/python(Windows Scripts/python.exe);
  2. <cwd>/.venv / venv / env;
  3. 入口目录与 fs_root 向上查找;
  4. PATH 的 python3 / python。

MARQDO_FOREIGN_NO_VENV=1 关闭 venv 探测;显式 cmd / set_cmd / MARQDO_FOREIGN_PYTHON 优先。

相对路径:配置里的 cmd 相对配置目录;注册 / set_cmd / 环境变量里的 cmd 相对 cwd。

2.3 注册与模板

register(lang, cmd?, args?, template?, ext?, env?, version_args?)。

模板占位符:

占位符 展开
{file} 临时脚本绝对路径
{dir} 临时目录
{base} 脚本文件名
{inline} 源码作为一个 argv;不写临时文件
{lang} 语言 id
{cwd} 实际工作目录

规则:

  • cmd 与 template 至少一个;都给 → 报错。
  • {file} 与 {inline} 不能同时出现。
  • 都没有时自动追加 {file}。
  • {inline} 超过 60 KiB → 报错并建议 {file}。
  • 模板不做 shell 转义;需要 shell 时显式写 bash -c,路径由引擎生成(安全字符)。

配置示例:

[python]
cmd = ".venv/bin/python"
args = ["-u"]

[go]
template = ["go", "run", "{file}"]

[rust]
template = ["bash", "-c", "rustc -O {file} -o {dir}/main && {dir}/main"]

[php]
template = ["php", "-r", "{inline}"]

3. 一次性执行

3.1 API

英文 中文 形参 结果
run 运行 code, 可选 stdin env cwd timeout args max_output stdout 文本(v1 兼容)
run_lang 按语言运行 lang, source, 可选同上 stdout 文本
invoke 执行 可选 code / lang+source / stdin / input / env / cwd / timeout / args / output / max_output / cmd / keep / cache 记录 map
call 调用 可选 code / lang+source / input / stdin / env / cwd / timeout / args 解析后的 JSON 值
run_many 批量运行 runs, 可选 concurrency 记录列表
call_many 批量调用 inputs, 可选 code / lang+source / cmd / env / cwd / timeout / args / max_output / concurrency 结果值列表

3.2 记录结构

invoke / run_many / session_eval 共用:

键 类型 含义
ok Bool exit=0 且未超时
code Int 退出码;未启动 / kill → -1
stdout Text 原始 stdout(可能截断)
stderr Text 原始 stderr(可能截断)
ms Int 墙钟毫秒
lang Text 实际语言
cmd Text 实际 argv
timed_out Bool 是否超时
truncated Bool stdout/stderr 是否截断
result 任意 / None 按 output 解析
result_error Text json 解析失败原因
error Text 启动 / 超时 / 策略原因
script Text keep=True 的脚本路径
cached Bool 缓存命中(P4)

session_eval 额外:id、alive。

3.3 输出模式

output= result
auto(默认) 尝试 JSON;失败 → None
text None
json 解析;失败 → result_error
lines 行列表
bytes stdout 原始字节的 base64

call 固定 JSON:空 stdout → None;非空非法 JSON → 错误。

3.4 失败语义

  • run / call:执行失败 → Err;错误包含语言、argv、退出码、stderr(截 4 KiB)、stdout 头。
  • invoke / run_many:执行失败 → 记录;只有参数非法 / 策略拒绝 → Err。
  • 输出过大:截断 + truncated=true,不再 OOM / 报错。

4. JSON 状态桥

4.1 值映射

Marqdo JSON
None null
Bool bool
Int number
Num number(NaN/Inf → null)
Text string
List array
Map object
Formula 矩阵 → 二维数组;其它 → 数字或字符串
Code 源码字符串
Secret JSON 中 <secret>;env 显式交付时取真实值

4.2 输入

  • input= → JSON;写 stdin;同时提供 MARQDO_INPUT(≤8 KiB)与 MARQDO_INPUT_FILE(任意大小)。
  • stdin= 文本与 input= 互斥。
  • 都不给 → stdin EOF。
  • 大输入走文件,避免环境变量大小限制。

4.3 输出

  • result 按 output 解析。
  • 原始 stdout/stderr 始终保留(截断到上限)。
  • call 返回解析值;invoke 返回记录。

4.4 类型限制

v2 是值拷贝,不是对象引用:

  • Python DataFrame / NumPy / Node 对象 → 需要先 to_dict / to_json / JSON.stringify。
  • 大对象传输成本高;后续考虑 Arrow / Parquet / 文件句柄。
  • Secret 不默认进入 JSON;需要 env 显式交付。

5. 持久内核与会话

5.1 API

英文 中文 形参 结果
session_open 会话开启 lang, 可选 cmd env cwd timeout 会话 id(Text)
session_eval 会话求值 id, 可选 code / source / input / timeout 记录(含 id/alive)
session_set 会话设值 id, name, value None
session_get 会话取值 id, name JSON 值 / None
session_names 会话变量 id 名称列表
session_close 会话关闭 id Bool
session_list 会话表 — map 列表

5.2 支持语言

语言 方式
python python3 -u -c <bootstrap>
node node -e <bootstrap>
其它 报错:lang=… has no session bootstrap; use run/invoke

5.3 线路协议

stdin 每行一个 JSON 请求;原始 stdout 每行一个 JSON 响应:

{"id":1,"code":"x = 41","input":null}
{"id":2,"code":"x + 1","input":null}
{"id":1,"ok":true,"stdout":"","stderr":"","result":null,"error":""}
{"id":2,"ok":true,"stdout":"","stderr":"","result":42,"error":""}
  • 同一会话严格串行:等到匹配响应后才发下一条。
  • 响应单行;JSON 转义换行。
  • 崩溃 / EOF → alive=false,会话移除。
  • 超时 → kill 会话(状态不可信)。

5.4 Python bootstrap

  • 保留原始 sys.stdout 写协议;用户输出用 redirect_stdout/stderr 捕获。
  • ast.parse:最后一条是表达式 → 先 exec 前面,再 eval 最后,作为 result。
  • 异常 → traceback.format_exc(limit=8),ok=false;会话继续。
  • input → 全局 marqdo_input。
  • 不可序列化 → default=str。

5.5 Node bootstrap

  • 保存原始 process.stdout.write 写协议。
  • eval 期间替换 console.* 与 process.stdout/stderr.write;结束后恢复。
  • vm.runInThisContext 保留全局状态;require 挂到 globalThis。
  • Promise → await;顶层 await 需用户包 (async()=>{…})()。
  • 序列化失败 → String(result)。

5.6 状态桥

  • session_set:值 → JSON → 请求 {"set": name, "value": ...} 或执行一段赋值。
  • session_get:请求 {"get": name} → JSON → Marqdo Value。
  • session_names:请求变量名列表。
  • 与 session_eval 同一线路协议;严格串行。
  • 名称必须是合法标识符;保留名(marqdo_input 等)另行文档。

5.7 生命周期

  • id 为 s1、s2…。
  • 每会话独立进程、cwd、env。
  • HostContext drop → 全部 kill + wait。
  • subtask 不继承会话。
  • 不跨文档共享。

6. 环境契约

变量 值
MARQDO_FOREIGN 1
MARQDO_FOREIGN_LANG 语言 id
MARQDO_FOREIGN_SCRIPT 脚本路径(文件模式)
MARQDO_FOREIGN_DIR 脚本目录
MARQDO_FOREIGN_CWD 实际 cwd
MARQDO_ENTRY 入口 .mq.md 路径
MARQDO_ENTRY_DIR 入口目录
MARQDO_INPUT input JSON(≤8 KiB)
MARQDO_INPUT_FILE input JSON 文件(任意大小)

语言默认:

  • Python:PYTHONUNBUFFERED=1、PYTHONIOENCODING=utf-8、PYTHONUTF8=1;PYTHONPATH 前插 cwd。
  • Node:NODE_PATH 前插 cwd(可选)。

env 是 map;值 as_display();Secret 取真实值(显式交付)。不主动清空父环境。


7. 临时文件与 cwd

  • 默认 <cwd>/.marqdo/tmp/foreign-<pid>-<nanos>/;不可写 → 系统临时目录。
  • MARQDO_FOREIGN_TMPDIR 覆盖。
  • 脚本 main.<ext>;Python 加 utf-8 声明。
  • 默认 cwd = 入口目录;调用级 cwd 经 resolve_path + fs_root 校验。
  • 成功/失败/超时都清理;keep=True 保留并回填 script。
  • Node 相对 require('./x') 相对脚本目录;需要项目相对路径时用 MARQDO_FOREIGN_CWD 或 {inline} 模板。

8. 超时、IO、进程组

  • timeout:秒,可小数;默认 10s;上限 3600s;<=0 报错。
  • 超时 kill 进程组:
    • Unix:process_group(0) + kill(-pid, SIGKILL);
    • Windows:taskkill /PID <pid> /T /F。
  • max_output:每流默认 1 MiB;范围 1 KiB–64 MiB;保留前 N 字节,余下丢弃并继续排空;truncated=true。
  • stdin 独立写线程,避免双向管道死锁;EPIPE 忽略。
  • stdout/stderr 两个读线程;UTF-8 lossy。
  • 记录原始字节(至上限)以支持 bytes 输出。

9. 安全

项 策略
能力门禁 run / invoke / probe / session_* 全部检查 allow_exec();沙箱 → 拒绝
shell 默认不经 shell;模板显式 bash -c 才走
cwd resolve_path + fs_root;越界拒绝
输出 有界读取 + 丢弃式排空
时间 上限 + 进程组 kill
并发 默认 4,上限 32
会话 每文档独立;关闭/drop 清理;超时即杀
Secret JSON 不默认暴露;env 显式;面板打码
wasm exec-host 关闭时全部返回清晰错误;langs 返回 []

10. 兼容性

  • run / run_lang / set_cmd / langs 既有调用可用。
  • run 成功仍返回 stdout(去一个尾换行);非 0 仍报错。
  • set_cmd 增加可选 args。
  • langs 扩展为「预设 ∪ 注册 ∪ 配置」;原集合是子集。
  • subtask 的 spawn code= / lang= 仍返回 stdout 文本。
  • HostFn id 只追加;字节码参数 < 255。
  • 无核心表面 Δ。

11. 测试矩阵

测试 依赖 断言
既有 foreign-python / run-lang / 外联-python python 兼容
foreign-invoke node ok/code/stdout/stderr/ms
foreign-env-cwd node env/cwd/MARQDO_*
foreign-timeout node timed_out, 无遗留进程
foreign-call-json node 嵌套 list/map 往返
foreign-call-many / run-many node 顺序/隔离/并发
foreign-session node(python 可选) 跨 eval 状态、异常不杀
foreign-session-set-get node 变量推拉
foreign-session-timeout node alive=false
foreign-probe node path/version/ok
foreign-register node 模板 {inline}
foreign-config node MARQDO_FOREIGN_CONFIG
foreign-caps 无 exec=false 拒绝
单元测试 无 shell 切分/模板/别名/JSON

当前环境无 Python:node + bash 为主;python 条件跳过;Windows 用 python_available() / bash_available() 守卫。


12. 实现落点

文件 内容
src/foreign/registry.rs 预设/别名/模板/venv/PATH/配置/shell 切分(纯逻辑)
src/host/foreign.rs Job/Execution/ForeignEnv;run/invoke/call/run_many/call_many;probe/register/unset/langs/load_config
src/host/foreign_session.rs Python/Node bootstrap;会话生命周期;set/get/names
src/host/dispatch.rs HostFn 追加
src/aliases.rs 参数别名
lib/foreign.mq.md / lib/外联.mq.md L1 API + 文档
src/view/mod.rs / html.rs / debug_page.rs Run 诊断;后续接文档会话
tests/gold.rs / tests/lib/foreign-*.mq.md 测试

13. 明确不做

  • Foreign line-level step。
  • Foreign → Marqdo 函数 callback。
  • 自动镜像变量。
  • 跨语言共享对象引用。
  • 全进程快照。
  • 自动安装依赖。
  • 浏览器 wasm 外联。