Files
marqdo/doc/roadmap/foreign-v2.md
T
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

227 lines
8.4 KiB
Markdown
Executable File
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 外联内核 v2 路线图(F0–F4)
| | |
|---|---|
| 状态 | **F0–F3.5 已落地;F4 进行中** |
| 日期 | 2026-10-17 |
| 层 | Runtime |
| 相关 | [foreign-kernel.md](../design/foreign-kernel.md) · [notebook-session.md](../design/notebook-session.md) · [notebook-syntax.md](../design/notebook-syntax.md) · [foreign-notebook-decisions.md](../research/foreign-notebook-decisions.md) · [stdlib-foreign.md](../design/stdlib-foreign.md) · [notebook-session.md](notebook-session.md)(D 层路线) |
| 核心表面 Δ | 无 |
> 本路线图只覆盖 **F:外联内核运行时**。共享状态 / 单步 / 切换内核的文档侧在 [notebook-session.md](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)`;Windows `taskkill /T /F`)。
- shell-like argv 切分(引号/转义)。
- `invoke` + 稳定记录。
- `run` / `run_lang` 增加 `env` / `cwd` / `timeout` / `args` / `max_output`。
- view `/api/foreign-run` 返回完整记录;JS 显示 stderr / exit / ms。
- `set_cmd` L1 补 `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`;`bytes` base64。
- `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](notebook-session.md))。