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.
8.4 KiB
8.4 KiB
外联内核 v2 路线图(F0–F4)
| 状态 | F0–F3.5 已落地;F4 进行中 |
| 日期 | 2026-10-17 |
| 层 | Runtime |
| 相关 | foreign-kernel.md · notebook-session.md · notebook-syntax.md · foreign-notebook-decisions.md · stdlib-foreign.md · notebook-session.md(D 层路线) |
| 核心表面 Δ | 无 |
本路线图只覆盖 F:外联内核运行时。共享状态 / 单步 / 切换内核的文档侧在 notebook-session.md(D 层)。
0. 现状与目标
v1:set_cmd / run / run_lang / langs;临时文件 + 子进程 + stdout 文本;无状态、无结构化结果、无 exec 门禁、无有界 IO、无进程组清理。
v2 目标:安全、可发现、结构化、可持久、可并行,并成为 D 层文档会话的可靠底座。
1. 阶段总览
| 阶段 | 内容 | 估算 | 可独立发版 |
|---|---|---|---|
| F0 | 执行内核与安全:Job/Execution、exec 门禁、有界 IO、进程组、invoke 记录、view 诊断 |
2–3 天 | 是 |
| F1 | 语言注册与发现:registry、15 预设、probe、register/unset、配置、venv | 2–3 天 | 是 |
| F2 | JSON 桥与并行:call/call_many、run_many、output/result | 2–3 天 | 是 |
| F3 | 持久内核:Python/Node session_open/eval/close/list | 3–4 天 | 是 |
| F3.5 | 状态桥:session_set/get/names | 1–2 天 | 是 |
| F4 | 打磨、文档、catalog、CHANGELOG、1.5.0 | 1–2 天 | 1.5.0 |
D 层(文档会话)从 F3.5 完成后开始;不要把 D 层塞进 F 层。
2. F0 — 执行内核与安全
内容
src/host/foreign.rs重构:Job:lang/source/stdin/input/env/cwd/timeout/args/output/max_output/cmd/keep。Execution:stdout/stderr/raw bytes/exit/ms/timed_out/truncated/error。ForeignEnv:cwd/fs_root/specs/caps 快照(供并行)。
exec门禁:run/invoke/run_many/probe/session_*统一检查。- 有界 IO:读线程保留前 N 字节、继续排空;
truncated。 - stdin 写线程;EPIPE 忽略。
- 超时:进程组 kill(Unix
process_group(0)+kill(-pid);Windowstaskkill /T /F)。 - shell-like argv 切分(引号/转义)。
invoke+ 稳定记录。run/run_lang增加env/cwd/timeout/args/max_output。- view
/api/foreign-run返回完整记录;JS 显示 stderr / exit / ms。 set_cmdL1 补args。
验收
- 既有
lib_foreign_*/lib_subtask_foreign绿(python 可用时)。 - 新增 node/bash 金样例:非 0 退出、stderr、超时、env/cwd、截断。
exec=false拒绝。cargo test绿;release build;wasm check。
主要文件
src/host/foreign.rs · src/host/mod.rs · src/host/subtask.rs · src/view/mod.rs · src/view/html.rs · src/view/debug_page.rs · Cargo.toml · tests/gold.rs · tests/lib/foreign-*.mq.md。
3. F1 — 语言注册与发现
内容
src/foreign/registry.rs(纯逻辑):- 15 预设、别名、扩展名、版本参数、会话能力。
- 模板占位符
{file}/{dir}/{base}/{inline}/{lang}/{cwd}。 - venv 探测、PATH 查找、shell-like 切分、配置解析。
HostContext:foreign_specs、foreign_config_loaded。probe缓存(可选)。
- API:
probe/langs/register/unset/load_config。 - 配置:
.marqdo/foreign.toml+MARQDO_FOREIGN_CONFIG;优先级见设计。 MARQDO_FOREIGN_<LANG>支持 JSON 数组与引号。subtask继承注册/配置。
验收
probe对 node / bash 给出 path + version;缺失语言ok=false不 panic。- 配置可把
python指向 venv;模板可跑go run(若本机有 go)。 langs含预设;unset回退预设。- 单元测试:切分、模板、别名、扩展名。
4. F2 — JSON 桥与并行
内容
call/call_many;invoke的input/output/result/result_error。Value ↔ JSON复用host::json;bytesbase64。run_many并行引擎:ForeignEnv快照、线程上限 32、结果同序、单项 panic 隔离。call_many全跑完再报错(清理所有子进程)。- 文档:Python / Node JSON 样板。
验收
call单列表 → map,mean 为 Num;嵌套 list/map 往返。run_many顺序稳定;单项失败不影响其它项。- 大输入(>8 KiB)走
MARQDO_INPUT_FILE。 - 并发上限与超时生效。
5. F3 — 持久内核
内容
src/host/foreign_session.rs:- Python / Node bootstrap(嵌入式常量)。
- 启动、reader/writer、严格串行、超时、崩溃、drop 清理。
session_open/session_eval/session_close/session_list。
- 会话记录:与 invoke 同形 +
id/alive。 - 会话环境:cwd / env / cmd;
MARQDO_*。 HostContext字段(cfg exec-host)+ Drop。
验收
- Node:
let x=41→x+1→ 42;console.log捕获;异常不杀会话。 - Python:同(有 python 时)。
- 超时 → kill +
alive=false;close/drop 无遗留进程。 - 会话与
subtask边界:不继承。
6. F3.5 — 状态桥
内容
session_set/session_get/session_names。- 值:Marqdo → JSON → kernel;kernel → JSON → Marqdo。
- 名称校验;Secret 规则;错误可读。
- 与
session_eval同一线路,严格串行。 - L1 文档 + 金样例。
验收
- Node:
session_set xs=[1,2,3],session_eval sum(xs)→ 6;session_get取回。 - 复杂嵌套 map/list 往返。
- 不存在变量 → None + 可读诊断。
- 非 JSON 可序列化 → 错误说明。
7. F4 — 打磨与发布
history(可选)/cache(可选,默认关)。- view 命令记忆 / Ctrl+Enter / 错误分块。
lib/foreign.mq.md/lib/外联.mq.md全量。public/stdlib/*示例。- catalog 重新生成;CHANGELOG;版本 1.5.0。
- 性能:空跑、100 次调用、会话 vs 一次性。
验收
- 新函数全部有中文/英文文档与示例。
marqdo catalog、public/构建通过。- 手工 view Run 一个 node 卡片,显示 stdout/stderr/exit/ms。
8. 测试矩阵
当前环境:node / bash / sh / perl 可用,python3 不可用。新金样例以 node + bash 为主;python 用
python_available()条件跳过。
| 测试 | 依赖 | 断言 |
|---|---|---|
| 既有 3 个 foreign 用例 | python | 兼容 |
foreign-invoke |
node | 记录字段 |
foreign-env-cwd |
node | env/cwd/MARQDO_* |
foreign-timeout |
node | timed_out |
foreign-call-json |
node | 类型往返 |
foreign-call-many / run-many |
node | 顺序/隔离 |
foreign-session |
node | 跨 eval |
foreign-session-set-get |
node | 状态桥 |
foreign-session-timeout |
node | alive=false |
foreign-probe |
node | path/version |
foreign-register |
node | 模板 |
foreign-config |
node | 配置 |
foreign-stdout-stderr |
bash | 成功也有 stderr |
foreign-caps |
无 | 拒绝 |
| 单元测试 | 无 | 切分/模板/别名/JSON |
Windows:python_available / bash_available 守卫;进程组 taskkill 分支编译通过。
9. 兼容性
run/run_lang/set_cmd/langs兼容;只增可选参数。run成功仍返回 stdout;非 0 仍报错。- 大输出从“报错”改为“截断 + truncated”(更安全;CHANGELOG 写明)。
langs扩展为预设 ∪ 注册 ∪ 配置。- HostFn id 末尾追加(196+)。
- 无核心表面 Δ。
10. 风险
| 风险 | 缓解 |
|---|---|
| 会话协议脆弱 | 原始 stdout;-u;超时 kill;测试;文档限制 |
| 并行进程过多 | 默认 4 / 上限 32;超时;输出上限 |
| 配置优先级难记 | 设计文档固定表;probe 显示实际 path |
| 模板 shell 注入 | 默认不 shell;路径引擎生成;文档警示 |
| 大输出截断改变 v1 行为 | CHANGELOG;truncated 可检测 |
| wasm 编译 | 新字段 cfg 隔离;registry 纯逻辑 |
11. 完成定义
- F0–F3.5 全部验收。
cargo test绿;release build;wasm check。- 文档/CHANGELOG/catalog 更新。
- 提交并推送。
- 进入 D 层(notebook-session.md)。