diff --git a/doc/README.md b/doc/README.md index 3c38140..b73180d 100644 --- a/doc/README.md +++ b/doc/README.md @@ -48,7 +48,13 @@ | [roadmap/stdlib-mid.md](roadmap/stdlib-mid.md) | **Mid M1–M6 路线(done)** | | [roadmap/stdlib-mid2.md](roadmap/stdlib-mid2.md) | **Mid2 M7–M10 路线(规划)** | | [design/stdlib-math.md](design/stdlib-math.md) | **数学库(数值/随机/作图/轻量求解)** | -| [design/stdlib-foreign.md](design/stdlib-foreign.md) | **外联胶水(\`\`\`lang 具名块)— 已落地** | +| [design/stdlib-foreign.md](design/stdlib-foreign.md) | **外联胶水(\`\`\`lang 具名块)— v1 已落地** | +| [design/foreign-kernel.md](design/foreign-kernel.md) | **外联内核:持久内核 / JSON 桥 / 状态桥 / 安全** | +| [design/notebook-session.md](design/notebook-session.md) | **文档会话:cell / kernel / step / journal / 状态面板** | +| [design/notebook-syntax.md](design/notebook-syntax.md) | **文档原生 notebook 语法:内核表 / 会话表** | +| [research/foreign-notebook-decisions.md](research/foreign-notebook-decisions.md) | **外联 / notebook 决策记录(逐问逐答)** | +| [roadmap/foreign-v2.md](roadmap/foreign-v2.md) | **外联内核 v2 路线(F0–F4)** | +| [roadmap/notebook-session.md](roadmap/notebook-session.md) | **文档会话路线(D0–D5)** | | [design/ext-abi.md](design/ext-abi.md) | **原生插件 C ABI v1**(`lib/plugin`) | | [design/ext-llm.md](design/ext-llm.md) | **官方扩展 `ext/llm`(OpenAI 兼容)** | | [design/ext-agent.md](design/ext-agent.md) | **官方扩展 `ext/agent`(文档驱动:单步 / 多步工作簿 + 自写回;废弃 thin TOOL 循环)** | diff --git a/doc/design/foreign-kernel.md b/doc/design/foreign-kernel.md new file mode 100644 index 0000000..5a40c26 --- /dev/null +++ b/doc/design/foreign-kernel.md @@ -0,0 +1,434 @@ +# 外联内核(Foreign Kernel) + +| | | +|---|---| +| 状态 | **Decided(待实现)** | +| 日期 | 2026-10-17 | +| 层 | Runtime(`src/foreign/` · `src/host/foreign*` · `lib/foreign.mq.md`) | +| 相关 | [foreign-notebook-decisions.md](../research/foreign-notebook-decisions.md) · [notebook-syntax.md](notebook-syntax.md) · [notebook-session.md](notebook-session.md) · [stdlib-foreign.md](stdlib-foreign.md) · [stdlib-subtask.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](notebook-syntax.md)。 +- 文档会话 / cell 顺序 / journal / view UI → [notebook-session.md](notebook-session.md)。 +- Foreign → Marqdo 函数回调(v2 不做)。 +- 依赖安装(pip/npm)。 +- 远程 / 容器执行。 + +### 1.3 与相邻模块的区别 + +| 模块 | 生命周期 | 用途 | +|---|---|---| +| `foreign` | 一次性或持久 | 调外部语言;状态可选 | +| `subtask` | 一次性并发 | 后台任务、文件子任务、函数子任务 | +| `plugin` | 进程内 | 原生 C ABI 扩展 | +| `writeback` | 文档级 | 把输出写回 `.mq.md` | + +`subtask` 不管理持久状态;`foreign` 不管理文档执行顺序。 + +--- + +## 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,不需要 ``(整行或 JSON 数组)。 +4. 项目配置 `.marqdo/foreign.toml` / `MARQDO_FOREIGN_CONFIG`。 +5. 内置预设。 +6. 都没有 → 带修复建议的诊断。 + +Python 额外发现顺序(在预设层内): + +1. `VIRTUAL_ENV/bin/python`(Windows `Scripts/python.exe`); +2. `/.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`,路径由引擎生成(安全字符)。 + +配置示例: + +```toml +[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 中 ``;`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 ` | +| node | `node -e ` | +| 其它 | 报错:`lang=… has no session bootstrap; use run/invoke` | + +### 5.3 线路协议 + +stdin 每行一个 JSON 请求;原始 stdout 每行一个 JSON 响应: + +```json +{"id":1,"code":"x = 41","input":null} +{"id":2,"code":"x + 1","input":null} +``` + +```json +{"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 + +- 默认 `/.marqdo/tmp/foreign--/`;不可写 → 系统临时目录。 +- `MARQDO_FOREIGN_TMPDIR` 覆盖。 +- 脚本 `main.`;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 /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 外联。 diff --git a/doc/design/notebook-session.md b/doc/design/notebook-session.md new file mode 100644 index 0000000..982343f --- /dev/null +++ b/doc/design/notebook-session.md @@ -0,0 +1,503 @@ +# 文档会话(Document Session) + +| | | +|---|---| +| 状态 | **Decided(待实现)** | +| 日期 | 2026-10-17 | +| 层 | Runtime + Document(view 服务端 / notebook 交互) | +| 相关 | [notebook-syntax.md](notebook-syntax.md) · [foreign-kernel.md](foreign-kernel.md) · [foreign-notebook-decisions.md](../research/foreign-notebook-decisions.md) · [view.md](view.md) · [view-debug.md](view-debug.md) · [stdlib-subtask.md](stdlib-subtask.md) | +| 核心表面 Δ | 无(读取既有 AST 与表格) | + +> 文档会话是 view 背后的“notebook 运行时”:它记住哪些 cell、在哪个内核、按什么顺序执行、状态是什么、结果是否过期。 + +--- + +## 1. 目标 + +1. **像 Jupyter 一样即时**:点一个 cell 就执行,状态保留。 +2. **不像 Jupyter 一样隐藏**:执行顺序、内核归属、状态、过期情况都可查。 +3. **不破坏 Marqdo 程序语义**:`marqdo run` 仍是规范执行;view 会话是交互镜头。 +4. **Git 友好**:状态/输出不默认写进 `.mq.md`。 +5. **多语言**:命名内核 + 显式状态桥。 +6. **可复现**:Run All / journal / dirty / stale / replay。 + +--- + +## 2. 两种执行模式 + +### 2.1 Program mode(规范) + +- 入口:`marqdo run doc.mq.md` / CI / `view` 的 `Run document`。 +- 执行:`# main` 程序语义;外联通过显式 `foreign.session_open/eval/call` 编排。 +- 状态:一次运行内有效;运行结束进程退出(除非显式持久内核)。 +- 结果:可复现;是文档的“真理”。 + +### 2.2 Notebook mode(交互) + +- 入口:`marqdo view doc.mq.md` → Session 面板。 +- 执行:按 `会话表`(或自动顺序)逐 cell 执行。 +- 状态:内核持久;可切换、重启、单步。 +- 结果:默认临时显示;可显式 writeback。 +- 不是“真理”:是探索界面;需要复现时用 Run All 或把编排写进 `# main`。 + +### 2.3 两者关系 + +```text + .mq.md + / \ + Program mode Notebook mode + (canonical) (interactive) + \ / + Document Session + ├── cell index + ├── kernel registry + ├── journal + └── state panel +``` + +- 共享 cell index 与 kernel registry。 +- Program mode 可以不使用 notebook 表;Notebook mode 可以使用。 +- 冲突时以 Program mode 为准;Notebook mode 不改变文档语义。 + +--- + +## 3. 文档会话模型 + +```text +DocumentSession +├── doc_path / doc_hash +├── cells: Vec +│ ├── id (name / anon@line) +│ ├── name (binding) +│ ├── lang +│ ├── line_start / line_end +│ ├── source_hash +│ ├── kernel (resolved) +│ └── status: never | clean | dirty | stale | error | running +├── kernels: KernelRegistry +│ ├── name → ForeignSession +│ └── default per language +├── value_store: HashMap // Marqdo 侧会话值 +├── journal: Vec +├── created_ms / last_active_ms +└── mode: program | notebook +``` + +### 3.1 Cell + +- 只有**绑定名**的代码围栏才是 cell: + ```markdown + `加载` = + ```python + ... + ``` + ``` +- 未绑定围栏仍是叙述,不是 cell。 +- `id`:优先绑定名;匿名围栏用 `anon@`(不进入会话表)。 +- 同名 cell 重复 → 诊断;会话表按名字引用。 +- `source_hash` 用于 dirty 判断。 +- `line_start/line_end` 用于定位;编辑后重建索引。 + +### 3.2 Cell index 构建 + +1. 读取/解析文档(现有 `parse_source` / `load_module`)。 +2. 遍历 AST,找 `Stmt::Assign { name, value: Expr::Code(c) }`。 +3. 记录 name、lang、source、span、source hash。 +4. 读取 `内核表` / `会话表` 绑定(见 [notebook-syntax.md](notebook-syntax.md))。 +5. 解析 kernel 声明与 cell 归属;校验;生成诊断。 +6. 生成执行顺序: + - 有会话表 → 行顺序; + - 无 → 文档顺序。 +7. 未入会话的 cell → 状态 `unlisted`,UI 显示徽标。 + +### 3.3 Kernel registry + +- key:`:`。 +- 默认:`default:python`、`default:node`,按需启动。 +- 命名:来自 `内核表`,首次执行时启动。 +- 状态:`idle | starting | ready | busy | dead`。 +- 同一 kernel 的 cell 严格串行;不同 kernel 可并行。 +- 重启:kill + 清空状态 + 重新启动;cell 状态变 `never`。 +- 关闭:kill + 移除。 + +### 3.4 Value store(Marqdo 侧会话值) + +- 保存可从 Marqdo 推入内核的值(来自最近一次 Program run 的 bindings,或用户手动输入)。 +- 也保存从内核取回的值(`session_get` / 状态面板 Pull)。 +- 不是解释器 Env 的实时镜像;它是会话层的**值缓存**。 +- 注入解释器:未来通过 `SessionEnv` 或显式变量赋值;v2 不做隐式注入。 +- 用途: + - 状态面板显示; + - Push 到内核; + - 作为 `session_set` 的值来源; + - journal 记录。 + +### 3.5 Journal + +每次执行追加一条: + +```json +{ + "seq": 3, + "cell": "汇总", + "kernel": "分析", + "lang": "python", + "ok": true, + "code": 0, + "ms": 42, + "source_hash": "…", + "stdout_hash": "…", + "result_hash": "…", + "started_ms": 1760000000000, + "error": "" +} +``` + +用途: + +- 执行序号 / 顺序; +- dirty/stale 判断; +- replay; +- 视图显示; +- 调试(“为什么这个 cell 有值”)。 + +存储:内存 + 可选 `.marqdo/sessions/.json`(默认 git 忽略)。 + +--- + +## 4. 执行语义 + +### 4.1 操作 + +| 操作 | 语义 | +|---|---| +| **Run cell** | 执行选中的 cell;必要时启动/复用 kernel | +| **Run above** | 按会话顺序执行到选中 cell(含) | +| **Run all** | 按会话顺序执行全部;可选 `restart` | +| **Step next cell** | 执行会话顺序中的下一个未执行/选中 cell | +| **Step next statement** | Marqdo 语句级单步(DebugController) | +| **Restart kernel** | kill + 重建;cell 状态 `never` | +| **Interrupt** | kill 当前 cell 进程组;kernel 标记 dead 或重启 | +| **Reset session** | 关闭所有 kernel,清 journal / value store | + +### 4.2 执行一个 cell + +```text +resolve cell -> resolve kernel + -> ensure kernel ready + -> [送入?] 显式 bridge 由文档代码/UI 负责 + -> foreign.session_eval(kernel, source, input?) + -> record -> update cell status + -> [取回?] 由文档代码/UI 负责 + -> journal append + -> view update +``` + +- 默认 cwd = 文档目录;env = kernel env。 +- 输出:stdout / stderr / result / ms / truncated。 +- 失败:cell 状态 `error`;journal 记录;不自动重试。 +- 同一 kernel 串行;UI 禁用并发 Run。 + +### 4.3 Step 语义 + +| 类型 | 行为 | +|---|---| +| **Cell step** | 执行下一个会话 cell;状态保留 | +| **Marqdo statement step** | 执行下一条 Marqdo 语句;遇到 `foreign.session_eval` 时整个外联调用原子完成 | +| **Foreign line step** | 不做;未来 DAP | + +- Cell step 是 Notebook mode 的主单步。 +- Statement step 复用 `DebugController`;需要把 debug session 与 DocumentSession 关联。 +- 两者可以互相切换:cell step 到某个 Marqdo cell 后可 statement step;语句执行完回到 cell 边界。 + +### 4.4 中断 + +- `Interrupt`:向当前 kernel 进程组发 SIGINT/SIGKILL;记录 `interrupted`。 +- 若 kernel 状态不确定 → 标记 dead;建议 restart。 +- 不允许“中断后继续用同一 kernel”除非确认状态。 + +### 4.5 并发 + +- 同一 kernel:一次一个 cell。 +- 不同 kernel:可并行(例如 Python 分析与 Node 前端)。 +- `Run all` 默认按会话顺序串行;可配置“按 kernel 并行、按依赖串行”(后续)。 +- 并发上限沿用 foreign(32)。 + +--- + +## 5. 状态桥(会话层) + +### 5.1 显式 API + +文档代码: + +```markdown +把 `数值表` 送进 `分析` 内核: +**> foreign.session_set id="分析" name="xs" value=`数值表`** + +从 `分析` 内核取回 `mean`: +**`均值` = > foreign.session_get id="分析" name="mean"** +``` + +### 5.2 状态面板 + +- 左侧:Marqdo 侧值(最近 Program run bindings + value store)。 +- 右侧:每个 kernel 的变量(`session_names` + 按需 `session_get`)。 +- 操作: + - Push:选 Marqdo 值 → kernel 变量; + - Pull:选 kernel 变量 → value store / 显示; + - Refresh; + - 复制名称/值。 +- Secret 打码;大对象显示摘要(类型/长度/repr 截断)。 + +### 5.3 自动镜像 + +- v2 不做。 +- 后续 `mirror`:`mq_` 前缀、白名单、按值拷贝、默认关。 +- 原因见 [decisions](../research/foreign-notebook-decisions.md) §1-F。 + +### 5.4 类型 + +- JSON 拷贝;复杂对象需 `to_dict` / JSON。 +- 大对象:v2 显示摘要;传输用文件/DB。 +- 未来:Arrow / Parquet / 共享文件句柄。 + +--- + +## 6. Dirty / Stale / Run All + +### 6.1 定义 + +| 状态 | 条件 | +|---|---| +| `never` | 未执行 | +| `clean` | 上次执行成功后源码未变 | +| `dirty` | 源码 hash 变了 | +| `stale` | 上游 cell 变了(依赖图;v2 先按会话顺序近似) | +| `error` | 上次执行失败 | +| `running` | 正在执行 | +| `unlisted` | 不在会话表 | + +### 6.2 依赖 + +- v2:会话表行顺序 + 简单规则: + - 若上游 cell 的 source_hash 变了,下游标 `stale`; + - 若 kernel 重启,全部 `never`。 +- v2.1:变量级依赖图(静态分析 + bridge 表),精确 stale。 +- 不假装 Jupyter 的“隐藏顺序”:顺序就是表/文档顺序。 + +### 6.3 Run All + +- 默认:按会话顺序执行;可选 `restart=true`。 +- 规范执行:**restart + run all**;UI 明确按钮 `Restart & Run All`。 +- 未重启时:显示“当前 kernel 有历史状态”警告。 +- 执行后:生成 session summary(ok/fail/耗时/跳过的 cell)。 + +### 6.4 Replay + +- 用 journal 的顺序和输入 hash,在新 kernel 上重放; +- 比较 stdout/result hash; +- 输出 divergence 报告。 +- v2 可选;至少保留 journal 以便未来实现。 + +--- + +## 7. 输出与文档 + +### 7.1 默认 + +- Notebook mode 输出只在 view 中显示;不写 `.mq.md`。 +- 关闭/刷新后可通过 journal 恢复最近结果(若 session 持久化)。 +- 不写 execution_count 到文档。 + +### 7.2 显式 writeback + +- 复用 `lib/writeback` 的 ``。 +- cell 输出锚点:cell 名 + 行号;写入位置在围栏之后,或文档末尾的“输出”区。 +- 可选: + - 单 cell 写回; + - 全部写回; + - 只写回文本/数值,不写复杂对象。 +- Git 友好:输出是普通 Markdown 注释块;可 diff、可忽略。 + +### 7.3 不写回 + +- 避免 Jupyter 的 `.ipynb` 输出噪声。 +- 需要分享结果时,导出 HTML / 静态 view,而不是改源文件。 + +--- + +## 8. View 交互 + +### 8.1 工具栏 + +```text +[Run All] [Restart & Run All] [Step Cell] [Step Statement] +Kernel: [分析 ▾] Status: ready [Restart] [Interrupt] +[State] [Journal] [Writeback ▾] +``` + +### 8.2 每个 code card + +```text +`加载` python · kernel 分析 · run #3 · 42ms · clean +[Run] [Step] [Kernel ▾] [State] [Copy output] +``` + +- 状态徽标:`never` / `clean` / `dirty` / `stale` / `error` / `running` / `unlisted`。 +- 输出区:stdout / stderr / result / 截断提示。 +- 内核下拉:切换归属;不迁移状态;提示需要重跑。 +- `Step` = 执行此 cell(cell step)。 + +### 8.3 状态面板 + +- Marqdo / kernel 分栏。 +- Push/Pull。 +- Secret 打码。 +- 大对象摘要 + 复制 JSON。 + +### 8.4 Journal 面板 + +- 表格:seq / cell / kernel / ok / ms / 时间 / 错误。 +- 点击跳转 cell。 +- 导出 JSON。 + +### 8.5 键盘 + +- `Ctrl/Cmd + Enter`:Run cell。 +- `Shift + Enter`:Run cell + 下一个。 +- `Alt + Enter`:Run cell + 插入?不做。 +- `F10`:Step statement(与 debug 一致)。 +- `F5`:Run All。 + +--- + +## 9. 服务端 API + +所有 API 以文档相对路径 + session id 定位;session 内存驻留,进程退出即失。 + +| 方法 | 路径 | 作用 | +|---|---|---| +| POST | `/api/session/open` | 打开文档会话,返回 cells / kernels / journal | +| POST | `/api/session/close` | 关闭会话,kill 所有 kernel | +| POST | `/api/session/reload` | 重新解析文档,保留 kernel(标记 dirty) | +| POST | `/api/session/cell/run` | 执行指定 cell | +| POST | `/api/session/cell/step` | 执行下一个 cell | +| POST | `/api/session/run_all` | 按会话顺序执行;`restart` 可选 | +| POST | `/api/session/kernel/restart` | 重启指定 kernel | +| POST | `/api/session/kernel/interrupt` | 中断当前 cell | +| POST | `/api/session/kernel/assign` | 改 cell 的 kernel 归属(会话内) | +| POST | `/api/session/state/list` | Marqdo / kernel 变量列表 | +| POST | `/api/session/state/push` | Marqdo 值 → kernel | +| POST | `/api/session/state/pull` | kernel 变量 → value store | +| POST | `/api/session/statement/step` | Marqdo 语句单步(复用 debug) | +| POST | `/api/session/writeback` | 显式写回 cell 输出 | +| GET | `/api/session/journal` | 执行日志 | +| GET | `/api/session` | 当前会话摘要 | + +响应统一:`{ok, session, ...}`;错误 `{ok:false, error, code?}`。 + +--- + +## 10. 生命周期与持久化 + +- Session key:`/`;每个文档一个。 +- 打开:解析、建 cell index、按需启动 kernel。 +- 空闲超时:默认 30 分钟关闭(可配置)。 +- 文档关闭 / 服务退出:kill 所有 kernel。 +- 文件变更:view 刷新时 `reload`;cell hash 变化 → dirty;kernel 保留。 +- 持久化(可选): + - `.marqdo/sessions/.json`:kernel 名称/语言、cell 归属、journal、value store 摘要; + - 默认 git 忽略; + - 不持久化进程状态 / 大对象。 +- 不把 session 状态写进 `.mq.md`。 + +--- + +## 11. 安全 + +| 项 | 策略 | +|---|---| +| exec | 所有 kernel 启动/执行检查 `allow_exec`;沙箱拒绝 | +| 生命周期 | 每文档;关闭/drop kill;不跨文档 | +| cwd | 文档目录 / `fs_root`;越界拒绝 | +| 输出 | 有界;截断标记 | +| 超时 | cell 级;进程组 kill | +| 中断 | 杀进程组;kernel 标记 dead | +| Secret | 状态面板打码;JSON 不默认暴露 | +| 未信任文档 | 不自动打开会话;必须显式 Run | +| 并发 | 同 kernel 串行;不同 kernel 上限 32 | +| writeback | 显式;路径沙箱;不自动改文档 | + +--- + +## 12. 测试 + +### 12.1 服务端 + +- cell index:绑定名/行号/lang/source hash;未绑定围栏排除。 +- 表解析:内核表/会话表/自动模式/重复/未知/语言不匹配。 +- 会话:open/close/reload;kernel 启动/重启/中断。 +- cell run:状态机 never→running→clean/error;dirty/stale。 +- step:cell step 顺序;statement step 与 debug 联动。 +- state:push/pull/list;Secret 打码;大对象摘要。 +- journal:顺序、hash、失败。 +- 并发:同 kernel 串行;不同 kernel 并行。 +- 安全:exec=false 拒绝;cwd 越界;超时。 + +### 12.2 金样例 + +- `tests/notebook/kernels.mq.md`:内核表/会话表。 +- `tests/notebook/shared-state.mq.md`:两个 Python cell 共享 `x`。 +- `tests/notebook/step.mq.md`:cell step 顺序。 +- `tests/notebook/state-bridge.mq.md`:Marqdo ↔ Python 推拉。 +- `tests/notebook/invalid-*.mq.md`:诊断。 +- 依赖:node 为主,python 条件跳过。 + +### 12.3 UI + +- 手工冒烟:Run cell / Step / Run All / Restart / State Push/Pull / Journal。 +- 不引入前端测试框架;用服务端 API + 静态检查。 + +--- + +## 13. 与 Jupyter 对照 + +| 维度 | Jupyter | Document Session | +|---|---|---| +| 源 | `.ipynb` | `.mq.md` | +| 执行顺序 | 隐藏的 `In[n]` | 会话表 / 文档顺序 / journal | +| 状态 | 隐藏 kernel | kernel + value store + 状态面板 | +| 多语言 | 一 notebook 一 kernel | 命名内核 + 每 cell 归属 | +| 单步 | cell | cell + statement | +| 复现 | 手动 | Restart & Run All + journal + replay | +| Git | 输出/计数噪声 | 源码干净;输出显式 | +| 知识 | 无 | OKF / catalog | +| 调试 | 语言 pdb | Marqdo 断点 + cell 级;行级后续 | + +--- + +## 14. 实现顺序(D 层) + +| 阶段 | 内容 | +|---|---| +| D0 | 设计/语法/决策文档(本文件) | +| D1 | `src/notebook/`:cell index、表解析、session 结构、诊断 | +| D2 | 服务端 API:open/close/cell run/step/run_all/restart/interrupt | +| D3 | view UI:工具栏、cell 徽标、kernel 下拉、状态面板、journal | +| D4 | statement step 接入;dirty/stale;writeback | +| D5 | replay / 持久化 / 并发优化 / 测试补全 | + +依赖 F 层:F3 持久内核、F3.5 状态桥先完成,D2 才能工作。 + +--- + +## 15. 明确不做(v2) + +- Foreign line-level step。 +- 自动镜像变量。 +- 跨文档共享 kernel。 +- 全进程快照。 +- 自动执行 cell。 +- 把 session 状态写进 `.mq.md`。 +- 前端 SPA 框架重写;沿用现有 HTML/JS。 diff --git a/doc/design/notebook-syntax.md b/doc/design/notebook-syntax.md new file mode 100644 index 0000000..feb77b5 --- /dev/null +++ b/doc/design/notebook-syntax.md @@ -0,0 +1,305 @@ +# 文档原生 Notebook 语法 + +| | | +|---|---| +| 状态 | **Decided(v2 目标)** | +| 日期 | 2026-10-17 | +| 层 | Document(读取约定) + Runtime(校验) | +| 相关 | [foreign-notebook-decisions.md](../research/foreign-notebook-decisions.md) · [notebook-session.md](notebook-session.md) · [foreign-kernel.md](foreign-kernel.md) · [core-surface.md](core-surface.md) · [layers.md](layers.md) | +| 核心表面 Δ | **无**——不新增标记;只用既有 `# main` / 赋值 / 表格 / 反引号 | + +> 目标:让“这段代码在哪个内核里、按什么顺序执行、和谁共享状态”像目录一样可读,而不是像 IDE 配置一样可读。 + +--- + +## 1. 为什么不用围栏元数据 + +Jupyter 的 cell 元数据、VS Code 的 `kernel=`、YAML 的 `kernels:` 都属于**代码/编辑器思维**: + +- 读者看到的是一行属性,不是一段知识; +- 属性藏在围栏 info string 或 JSON 里,Markdown 预览看不见意图; +- 一旦加 `kernel=`,它就是 Language 层语法,需要 ADR、core-surface 增行; +- 同一个文档的执行计划被拆散到每个围栏,无法一眼总览。 + +Marqdo 的选择: + +> **执行计划本身是一张表。表是文档的一部分,人先读表,机器再读表。** + +这不是新语法。GFM 表已经是集合,`` `名` = `` + 表已经是数据绑定;我们只约定两个**数据表的名字**。 + +--- + +## 2. 两个约定数据表 + +它们放在 `# main`(或唯一入口对象)的体内,和代码单元并列: + +```markdown +# main + +`内核表` = + +| 名称 | 语言 | 命令 | 说明 | +|------|------|------|------| +| 分析 | python | | 读取与清洗数据 | +| 绘图 | python | | 独立环境 | + +`会话表` = + +| 单元 | 内核 | 说明 | +|------|------|------| +| 加载 | 分析 | 读取原始数据 | +| 清洗 | 分析 | 处理缺失值 | +| 汇总 | 分析 | 按城市聚合 | +| 绘图 | 绘图 | 输出 SVG | +``` + +为什么是“绑定的表”,不是 `# 外联内核` 对象: + +- `#` 是对象/函数;把元数据做成顶层对象会把文档拆成多个作用域,code fence 会被困在对象里。 +- 绑定表是入口体内的**数据**,与 cell 同一作用域;不执行、不改变控制流。 +- View / 文档会话读取 AST 中的绑定值,不需要执行文档。 +- 解析器零改动。 + +### 2.1 `内核表` / `kernels` + +| 列 | 必填 | 含义 | +|---|---|---| +| `名称` / `Name` | ✅ | 内核名,供 `会话表` 引用;建议用领域词(分析/绘图/前端) | +| `语言` / `Language` | ✅ | 预设 id 或已注册语言:`python` / `node` / … | +| `命令` / `Command` | 可选 | 覆盖解释器命令;空白 = 预设 / `set_cmd` / 配置 / 环境变量 | +| `说明` / `Notes` | 可选 | 给人读的一句话;不影响执行 | + +规则: + +- 名称在文件内唯一;重复 → 诊断。 +- 语言不支持会话时,内核仍可声明,但只能执行一次性 cell;`session_*` 报错。 +- `命令` 只写可执行文件;参数请用 `.marqdo/foreign.toml` 或 `session_open`。 +- 没有 `内核表`:每种语言自动一个 `default` 内核。 +- 声明了内核但 `会话表` 没引用:允许,只是没有被使用。 + +### 2.2 `会话表` / `session` + +| 列 | 必填 | 含义 | +|---|---|---| +| `单元` / `Cell` | ✅ | 代码围栏的绑定名(`` `加载` = `` 后面的名字),表格里**不写反引号** | +| `内核` / `Kernel` | ✅ | `内核表` 中的名称,或语言 id(`python` / `node`)表示该语言默认内核 | +| `说明` / `Notes` | 可选 | 给人读的一句话 | + +规则: + +- **行顺序 = 执行顺序**。这是 `Run All`、`Step`、`Run Above` 的规范顺序。 +- 只有列出的 cell 参与会话;未列出的代码围栏仍然显示,但标记为“未入会话”,Run All 不执行。 +- 没有 `会话表`:所有绑定名的代码围栏按**文档出现顺序**自动入会话,每种语言用默认内核。 +- `单元` 必须对应一个已绑定名的代码围栏;找不到 → 诊断。 +- 同名 cell 重复出现 → 诊断;建议一个名字只绑一个围栏。 +- `内核` 未声明且不是语言 id → 诊断,列出已声明内核。 +- cell 的语言与内核语言不一致 → 诊断;别名等价(`python3`/`py` ↔ `python`)。 +- 表可以出现在 `# main` 体内任意位置;读者可以从表一眼看到执行计划。 + +### 2.3 为什么放在 `# main` 体内 + +- `# main` 是入口;cell 绑定与元数据表同一作用域。 +- `marqdo run` 会正常求值这两个表(得到 `List of Map`),没有副作用。 +- 文档会话从 AST / 最近一次运行的 bindings 读取它们;不需要新的解析路径。 +- 如果文档没有 `# main` 而是唯一 `#` 对象,同样适用。 + +--- + +## 3. 完整示例 + +````markdown +# main + +这份文档演示一个最小 notebook:两个 Python 单元共享 `分析` 内核, +一个绘图单元在隔离的 `绘图` 内核里运行。 + +`内核表` = + +| 名称 | 语言 | 命令 | 说明 | +|------|------|------|------| +| 分析 | python | | 数据读取与聚合 | +| 绘图 | python | | 独立绘图环境 | + +`会话表` = + +| 单元 | 内核 | 说明 | +|------|------|------| +| 加载 | 分析 | 读取原始数据 | +| 清洗 | 分析 | 处理缺失值 | +| 汇总 | 分析 | 按城市聚合 | +| 绘图 | 绘图 | 输出 SVG | + +`加载` = +```python +import json + +rows = [ + {"city": "上海", "value": 3}, + {"city": "北京", "value": 5}, +] +print(json.dumps(rows, ensure_ascii=False)) +``` + +`清洗` = +```python +rows = [r for r in rows if r["value"] > 0] +``` + +`汇总` = +```python +from collections import Counter + +counts = Counter(r["city"] for r in rows) +print(dict(counts)) +``` + +`绘图` = +```python +print("plot-ready") +``` + +`汇总` 和 `绘图` 分属两个内核;`绘图` 看不到 `rows`。 +需要共享时,用 Marqdo 显式把值送过去: + +**> foreign.session_set id="绘图" name="rows" value=`rows`** +```` + +读者即使不运行,也能从 `会话表` 读出:先加载、再清洗、再汇总,最后绘图;前三个共享 `分析`,绘图在 `绘图`。 + +--- + +## 4. 自动模式(没有表) + +### 4.1 没有任何约定表 + +````markdown +# main + +`分析` = +```python +x = 41 +``` + +`结论` = +```python +print(x + 1) +``` +```` + +解释: + +- 两个 cell 都是 `python`; +- 自动使用 `default:python` 内核(一个); +- 按文档顺序执行; +- 共享 `x`。 + +现有文档不需要改一行就能在 view 里 cell-by-cell 运行。 + +### 4.2 只有内核表 + +- 所有 cell 按文档顺序; +- 每种语言解析到该语言的 `default` 内核; +- 命名内核只有被 `会话表` 引用时才使用。 + +### 4.3 只有会话表 + +- `内核` 列只能写语言 id; +- 每个语言 id 解析到该语言默认内核; +- 未列出的 cell 不入会话。 + +--- + +## 5. 可读性规则(语法评审标准) + +新增/修改任何 notebook 语法,必须满足: + +1. **先读人话**:去掉执行语义后,表格仍像目录/清单。 +2. **不使用属性串**:不写 `kernel=…`、`class=…`、JSON/YAML 元数据。 +3. **不隐藏意图**:执行顺序、内核归属必须在一处可见。 +4. **不引入新标记**:只用 `#` / 表格 / 反引号 / 既有代码面。 +5. **默认安全**:表格只声明,不自动执行;只有 Run / Step 触发。 +6. **命名用领域词**:`分析`、`绘图`、`前端`,不用 `k1`、`default`、`stage2`(除非确实是默认)。 +7. **说明列可选但推荐**:给未来的读者/LLM 一点上下文。 +8. **错误可读**:诊断要指出“哪个单元、哪个内核、哪一行、怎么修”。 +9. **中英对称**:中文用中文列名,英文用英文列名;语义一一对应。 +10. **无表也能跑**:约定表是增强,不是前置条件。 + +--- + +## 6. 诊断规范 + +| 情况 | 诊断(中文示例) | 修复建议 | +|---|---|---| +| 内核名重复 | `内核表: 内核名「分析」重复(第 12、20 行)` | 改名或合并 | +| 会话引用未知内核 | `会话表: 单元「汇总」引用了未声明的内核「分析」` | 在 `内核表` 声明,或改用语言 id | +| 会话引用未知单元 | `会话表: 找不到名为「清洗」的代码单元` | 检查 `` `清洗` = `` 绑定 | +| 单元重复 | `会话表: 单元「汇总」重复出现` | 每个单元只列一次 | +| 语言不匹配 | `会话表: 单元「前端」(node) 不能使用 python 内核「分析」` | 换内核或换语言 | +| 未入会话 | (非错误)view 徽标:`未入会话` | 需要时加一行 | +| 内核表为空 | `内核表: 至少声明一个内核,或删除该表使用默认内核` | 删除表或补行 | +| 会话表为空 | `会话表: 至少列出一个单元,或删除该表使用自动顺序` | 删除表或补行 | + +原则:**不静默忽略**。读者必须知道为什么某个 cell 没跑。 + +--- + +## 7. 与 Program mode 的关系 + +- `内核表` / `会话表` 是**声明**,不是执行指令。 +- `marqdo run` 仍然执行 `# main` 的程序语义;这两个表会被求值为普通数据。 +- Program mode 的外联编排用显式 API(`foreign.session_open` / `session_eval` / `call`);表只服务 view 的 notebook 会话与一键 Run All。 +- 两种模式可以并存: + - 文档用表描述“交互时怎么跑”; + - `# main` 用显式调用描述“CI 时怎么跑”。 +- 如果两者冲突,以 Program mode 的程序语义为准;Notebook mode 的表只影响 view。 + +这样避免把“执行计划”变成第二套程序语义。 + +--- + +## 8. 状态桥的语法边界 + +v2 **不**为状态交换新增表格/注释。原因: + +- “什么时候送、什么时候取、送到哪个内核、赋值给哪个 Marqdo 变量”需要精确语义; +- 若做成隐式表格动作,容易产生隐藏状态与顺序歧义; +- v2 先用显式 API,把时序讲清楚: + ```markdown + 把 `数值表` 送进 `分析` 内核: + **> foreign.session_set id="分析" name="xs" value=`数值表`** + + 从 `分析` 内核取回 `mean`: + **`均值` = > foreign.session_get id="分析" name="mean"** + ``` +- view 提供状态面板与 Push/Pull 按钮,减少手写 API 的需要; +- 声明式 `共享表` 作为 v2.1 提案,等 session value store 与“每次单元执行前后”的时序稳定后再引入。 + +这不是降级:v2 的功能完整(可读可写、可推可拉),只是不用隐式语法承载时序。 + +--- + +## 9. 未来扩展(不承诺进 v2) + +1. `共享表`: + `| 内核变量 | Marqdo 变量 | 方向 | 说明 |`,每次单元执行前送入、后取回。 +2. 每个 cell 的“运行条件/依赖”列:`依赖` 列声明上游单元。 +3. 内核别名:`内核表` 的 `名称` 可被 `use` 或短名引用。 +4. 多文件会话:跨 `.mq.md` 的共享内核(默认仍隔离)。 +5. 语言特定的“会话能力”列(是否支持持久、是否支持行级调试)。 + +任何一项都要先过 §5 的可读性规则与 `core-surface` 检查。 + +--- + +## 10. 实现落点 + +| 逻辑 | 位置 | +|---|---| +| 识别 `内核表` / `会话表` 绑定 | `src/notebook/syntax.rs`(新) | +| 读取绑定值 | AST `Stmt::Assign` + `Expr::Table` / `Expr::List`;或最近一次 run 的 bindings | +| 校验名称/语言/重复/未入会话 | 同上;错误进入现有 Diagnostic | +| cell index(绑定名/行号/语言/source hash) | 解析后的 `Module` 遍历 | +| 只读展示 | view Structure:表渲染成普通表格 + 徽标 | +| 执行 | Document Session API(见 [notebook-session.md](notebook-session.md)) | + +解析器本身**不需要改**。这是本设计最重要的约束:语法是既有标记的组合,不是新构造。 diff --git a/doc/design/stdlib-foreign.md b/doc/design/stdlib-foreign.md index 743be92..1d0977b 100644 --- a/doc/design/stdlib-foreign.md +++ b/doc/design/stdlib-foreign.md @@ -2,9 +2,9 @@ | | | |---|---| -| 状态 | **已落地(v1)** | +| 状态 | **v1 已落地**;v2 设计见 [foreign-kernel.md](foreign-kernel.md) · [notebook-session.md](notebook-session.md) · [notebook-syntax.md](notebook-syntax.md) | | 日期 | 2026-08-06 | -| 相关 | [stdlib-modules.md](stdlib-modules.md) · [stdlib-math.md](stdlib-math.md)(公式同构绑定) | +| 相关 | [stdlib-modules.md](stdlib-modules.md) · [stdlib-math.md](stdlib-math.md)(公式同构绑定) · [foreign-kernel.md](foreign-kernel.md) · [notebook-session.md](notebook-session.md) · [roadmap/foreign-v2.md](../roadmap/foreign-v2.md) | --- diff --git a/doc/research/foreign-notebook-decisions.md b/doc/research/foreign-notebook-decisions.md new file mode 100644 index 0000000..5e0c33c --- /dev/null +++ b/doc/research/foreign-notebook-decisions.md @@ -0,0 +1,290 @@ +# 外联内核 · 文档会话 · 决策记录 + +| | | +|---|---| +| 状态 | **Decided(由用户授权代为拍板)** | +| 日期 | 2026-10-17 | +| 范围 | 外联库(`lib/foreign`)· 外联内核 · 文档会话 · view notebook 交互 | +| 相关 | [foreign-kernel.md](../design/foreign-kernel.md) · [notebook-session.md](../design/notebook-session.md) · [notebook-syntax.md](../design/notebook-syntax.md) · [foreign-v2.md](../roadmap/foreign-v2.md) · [notebook-session.md](../roadmap/notebook-session.md) | +| 核心表面 Δ | **无**——不新增 Markdown 标记;只使用既有 `#` / `##` / 表格 / 反引号 | + +> 本文件记录「为什么这样设计」。实现细节分别落在设计文档与路线图中;本文件不重复 API 表。 + +--- + +## 0. 背景与授权 + +用户的核心诉求: + +1. Marqdo 的本质是 **代码即文档、文档即知识库**;`.mq.md` 天生兼容 Markdown / OKF 知识库。 +2. 外联库的初衷是**对标 Jupyter**:让文档与代码并行有用;但 Jupyter 有 Git 难跟踪、隐藏状态、execution_count 噪声等问题,Marqdo 要解决并超越。 +3. `view` 模式天然适合这种交互(已有执行按钮、结构视图、writeback、trace)。 +4. 之前外联库功能太单一;接下来必须支持: + - 多个代码块共享外联状态; + - 单步执行; + - 切换哪些外联内核共享状态; + - Marqdo 的状态/变量被外联使用; + - 外联的状态/变量被 Marqdo 使用。 +5. 用户要求:**安全第一、效果最好、功能最强悍、不降级**;充分测试;每份讨论落成详细文档;文档提交并推送后再开发。 +6. 用户强调:**设计语法不要用代码思维**,语法要天然可读。 + +本文档 = 对该授权的决策记录。后续实现若与本文冲突,先改本文并说明理由。 + +--- + +## 1. 关键结论 + +### 结论 A:外联库不是“跑 Python 的函数”,而是多语言内核运行时 + +`lib/foreign` 的定位升级为: + +> **文档运行时与外部语言运行时之间的内核/会话层**:启动内核、执行代码单元、持久化状态、双向类型桥、生命周期与安全。 + +它不等同于 `subtask`(一次性并发任务),也不等同于 `writeback`(输出持久化)。 + +### 结论 B:Jupyter 级体验需要两层,不是一层 + +| 层 | 名称 | 责任 | +|---|---|---| +| **F** | Foreign Kernel Runtime | 内核进程、语言发现/注册、JSON 桥、会话、安全、记录 | +| **D** | Document Session | 文档会话、cell index、kernel 分配、单步、状态面板、执行日志、view 交互 | + +上一版 `foreign-v2` 只覆盖 F。共享状态 / 单步 / 切换内核属于 D。两层分开设计、分开验收。 + +### 结论 C:Hybrid 执行模型 + +- **Program mode(规范模式)**:`marqdo run` / CI / 可复现执行。文档是程序;外联通过显式 `foreign.session_*` / `call` 编排;结果可重复。 +- **Notebook mode(交互模式)**:`view` 中按 cell 执行、单步、切换内核、查看状态。适合探索,不默认写入文档。 +- 两者共享同一个内核运行时与同一套 cell 索引;Notebook mode 是 Program mode 的**交互镜头**,不是替代品。 + +理由:如果让 cell 执行取代文档程序语义,Marqdo 就退化成 Jupyter;如果只有 Program mode,就失去 Jupyter 的即时反馈。Hybrid 同时保留两者。 + +### 结论 D:命名内核;同内核共享,跨内核/跨语言显式传值 + +- 一个文档可以有多个命名内核:`py:分析`、`py:绘图`、`js:前端`。 +- 同一内核的 cell 共享全局状态。 +- 不同内核(即使同语言)默认隔离。 +- 不同语言不共享进程内存;只能通过 JSON / 文件 / DB 显式交换。 +- 默认每个文档、每种语言一个 `default` 内核;命名内核按需开启。 +- 跨文档默认隔离;全局内核以后再做。 + +### 结论 E:三种单步,分阶段实现 + +| 单步 | 含义 | 版本 | +|---|---|---| +| **Cell step** | 执行下一个代码单元,状态保留 | v2 必做 | +| **Marqdo statement step** | 逐条执行 Marqdo 语句,查看变量 | v2 复用现有 debugger | +| **Foreign line step** | 进入 Python/Node 逐行 | v2 不做;后续接 DAP/pdb/debugpy | + +- 外联 cell 在 statement step 中是原子操作。 +- “Step into foreign” 是独立项目,不能混入首版。 + +### 结论 F:显式状态桥优先,不做隐式自动镜像 + +- 默认通过 `session_set` / `session_get` / `call input` / `call result` 交换,JSON 拷贝。 +- 不默认把 Marqdo 变量自动注入 Python,也不默认把 Python 变量自动写回 Marqdo。 +- 原因:命名冲突、Secret 泄漏、类型丢失、隐式状态、不可复现、大对象拷贝。 +- 后续可选 `mirror=True`:只同步 `mq_` 前缀、白名单类型、按值拷贝,且默认关闭。 + +### 结论 G:不新增围栏元数据;用文档原生的“内核表 / 会话表” + +- 拒绝 ` ```python kernel=分析 `、`name=`、YAML kernel 配置、魔法注释。 +- 使用既有绑定表 + GFM 表格(放在 `# main` 体内,与 cell 同作用域): + - `内核表` / `kernels` + - `会话表` / `session` +- 表格是**声明**,不是自动执行;只有 Run / Step 触发。 +- 解析器不变,核心表面零增长;view/session 读取这两个约定绑定。 + +理由:`kernel=` 是 IDE 配置思维,破坏“代码即文档”;绑定表是文档目录/执行计划,人可读、机器可解析,且不把文档拆成多个对象作用域。 + +### 结论 H:输出默认临时,writeback 显式;状态不写进 `.mq.md` + +- Notebook mode 的输出默认只在 view 中显示,不修改文档。 +- 需要持久化时显式 writeback(沿用 ``),可 Git 跟踪、可忽略。 +- 执行日志放 `.marqdo/sessions/…`(默认 git 忽略)。 +- 不把 execution_count / kernel 状态 / base64 输出写进 `.mq.md`。 + +### 结论 I:首批会话语言 Python + Node + +- Python:Jupyter 的主场景,优先支持。 +- Node:v1 已有基础,且当前开发环境可用。 +- 15 个语言预设继续用于**一次性执行**;R / Julia / Ruby 等的持久会话通过自定义 bootstrap 逐步加入,不阻塞首版。 + +### 结论 J:v2 不做“外联回调 Marqdo 函数” + +- 状态/值双向:✅ +- Marqdo 代码作为源码文本传给外联:✅(外联按自己的语言执行) +- 外联代码调用 Marqdo `##` 函数:❌ v2;后续做 callback RPC(控制通道 + 重入 + 死锁处理)。 +- 原因:重入解释器、线程安全、死锁、安全面都远超首版范围;先把数据/状态桥做稳。 + +### 结论 K:安全与测试是一等公民 + +- 所有 spawn / probe / session 入口检查 `allow_exec`。 +- 进程组超时清理;有界 IO;stdin 写线程;输出上限;并发上限。 +- 每文档生命周期,关闭即 kill;跨文档不共享。 +- 测试:node + bash 为最小环境主路径;python 条件覆盖;单元测试覆盖切分/模板/JSON;金样例覆盖记录/超时/会话/并行/状态桥。 + +--- + +## 2. 逐问逐答(保留原始讨论颗粒度) + +### Q1:外联库是做什么的? + +**答**:它是文档的多语言执行总线,负责: + +1. 内核生命周期(启动/重启/中断/关闭/切换); +2. cell 执行(源码 → kernel → stdout/stderr/result); +3. 状态持久化(同一 kernel 的 cell 共享命名空间); +4. 类型桥(Marqdo Value ↔ JSON ↔ 语言对象); +5. 环境发现与配置(probe/register/venv/config); +6. 记录与安全(耗时、退出码、截断、cap、清理)。 + +它不负责:文档语法(Language)、UI 布局(Document)、知识目录(Catalog)。这些由相邻层提供。 + +### Q2:是否支持外联库共享状态? + +**答**:支持,但严格分层: + +- 同一 kernel:共享全局变量。 +- 同一语言不同 kernel:隔离。 +- 不同语言:不共享内存,只能显式传值。 +- Marqdo ↔ kernel:显式桥。 +- 跨文档:默认隔离。 + +### Q3:能否单步执行? + +**答**:能,但要定义清楚: + +- cell step:v2 做。 +- Marqdo statement step:现有 debugger 已有,v2 接入 view。 +- foreign line step:v2 不做;后续 DAP。 + +### Q4:能否切换哪几个外联库共享状态? + +**答**:能,用命名内核: + +- `py:分析` 下所有 cell 共享; +- `py:绘图` 隔离; +- 每个 cell 有 kernel 归属; +- 切换归属不迁移状态,需要重跑; +- 跨语言用显式桥。 + +### Q5:Marqdo 的代码/状态能否被外联使用?外联的状态/变量能否被 Marqdo 使用? + +**答**: + +- Marqdo 值 → 外联:`session_set` / `call input` / `session_eval input`;JSON 拷贝。 +- 外联值 → Marqdo:`session_get` / `call` 返回值;赋值。 +- Marqdo 代码 → 外联:作为源码文本传递;外联按自己的语言执行,不是 Marqdo 语义。 +- 外联代码 → Marqdo 函数:v2 不做,后续 callback RPC。 +- 自动镜像:v2 不做,后续可选。 + +### Q6:如何超越 Jupyter? + +**答**:不是“功能更多”,而是把 Jupyter 的隐藏面变成显式面: + +| Jupyter | Marqdo | +|---|---| +| `.ipynb` JSON 混入输出/execution_count | `.mq.md` 源码干净;输出可选 writeback | +| 隐藏 kernel 状态 | 内核 + 文档会话 + 状态面板 + journal | +| 一个 notebook 一个 kernel | 命名内核 + 每 cell 归属 + 显式桥 | +| 只有 cell step | cell step + statement step | +| 手动 Run All | restart & run all + dirty/stale + replay | +| 无知识目录 | OKF / catalog;cell 是可发现知识单元 | + +--- + +## 3. 被拒绝的方案 + +| 方案 | 为什么拒绝 | +|---|---| +| 围栏元数据 ` ```python kernel=分析 ` | Language 层变更;需 ADR;把文档语法变成 IDE 配置;破坏可读性 | +| YAML `kernels:` 配置 | 代码思维;与“文档即知识”冲突;表格已能表达 | +| 魔法 HTML 注释 `` | 不可见、易漂移、读者不可见;违背可读性 | +| 自然语言 prose 解析(“把 xs 送给分析内核”) | 非确定性;误触发;违背“叙述默认安全” | +| 隐式自动镜像变量 | 命名冲突、Secret 泄漏、类型丢失、不可复现 | +| 一个文档一个 kernel | 无法做多语言/隔离实验,正是 Jupyter 的局限 | +| 把状态/输出写进 `.mq.md` | Git 噪声;正是要解决的 Jupyter 问题 | +| cell 自动执行 | 违背“未标记即叙述/未调用即数据”;破坏安全默认 | +| v2 做 foreign→Marqdo callback | 重入/死锁/安全复杂;应先稳定数据桥 | + +--- + +## 4. 已锁定的实现边界 + +### v2 必做 + +- F0 安全执行内核 + `invoke` 记录 + `exec` 门禁 + 有界 IO + 进程组超时。 +- F1 语言注册/发现:15 预设、`probe`、`register`、`unset`、配置、venv。 +- F2 JSON 桥:`call` / `run_many` / `output` / `result`。 +- F3 持久内核:Python / Node `session_open/eval/close/list`。 +- F3.5 状态桥:`session_set/get/names`。 +- D1 文档会话服务端:cell index、kernel registry、journal、open/close。 +- D2 view notebook:内核选择、Run/Step/Run All/Restart、状态面板、dirty/stale。 +- D3 Marqdo statement step 接入 view。 +- D4 语法:`内核表` / `会话表` 解析与校验。 +- D5 测试、文档、catalog、CHANGELOG。 + +### v2 不做(明确记录,避免“降级”误解) + +- Foreign line-level step(接 DAP 是后续项目)。 +- Foreign → Marqdo 函数 callback。 +- 跨语言共享对象引用 / 共享内存。 +- 全进程快照(只做变量级 JSON 快照)。 +- 跨文档全局内核。 +- 自动安装依赖。 +- 浏览器 wasm 外联。 + +这些不是“砍掉”,而是**独立阶段**;v2 先把内核/会话/桥做稳。 + +--- + +## 5. 风险与对策 + +| 风险 | 对策 | +|---|---| +| 会话协议脆弱(原生 fd 输出、缓冲) | bootstrap 用原始 stdout;Python `-u`;Node 保存原始 write;超时 kill;文档标注限制 | +| 状态桥隐式化导致不可复现 | 默认显式;`mirror` 后续且默认关 | +| 多内核进程泄漏 | 每文档生命周期;Drop kill;进程组;session_close;测试 | +| 大对象 JSON 拷贝慢 | v2 明确拷贝语义;后续 Arrow/Parquet/文件句柄 | +| `内核表` / `会话表` 名称冲突 | 文档声明为保留绑定名;后续可用 frontmatter 指针重命名 | +| 表格行/单元不一致 | 明确诊断:未声明内核、重复单元、语言不匹配、未入会话 | +| 交互执行顺序混乱 | journal + dirty/stale + Run All canonical + 执行序号 | +| 安全(Secret/环境) | Secret 不进 JSON;env 显式交付;状态面板打码;exec cap | +| 测试环境无 Python | node/bash 主路径;python 条件测试;协议单测 | + +--- + +## 6. 术语表(统一中英文) + +| 中文 | English | 含义 | +|---|---|---| +| 外联内核 | foreign kernel | 外部语言进程 | +| 外联会话 | foreign session | 内核实例 + 命名空间 | +| 文档会话 | document session | Marqdo 状态 + 内核注册表 + journal | +| 代码单元 | cell | 绑定名的代码围栏 | +| 内核归属 | kernel assignment | cell → kernel | +| 状态桥 | state bridge | Marqdo 值 ↔ 内核变量 | +| 执行日志 | execution journal | 执行顺序/耗时/结果/hash | +| 新鲜 | clean | 源码未变且已成功执行 | +| 过期 | dirty | 源码变了,结果可能过期 | +| 失效 | stale | 上游依赖变了,需要重跑 | +| 规范执行 | canonical run | 重启后按会话表顺序 Run All | + +--- + +## 7. 决策时间线 + +1. 用户提出外联库对标 Jupyter、共享状态、单步、切换、双向使用。 +2. Agent 阅读 `src/host/foreign.rs`、`src/view`、`src/debug`、`src/host/subtask.rs`、`lib/foreign`、设计文档。 +3. Agent 回答:需要 F + D 两层;单步分三种;共享分三层;显式桥。 +4. 用户授权 Agent 拍板:安全、最强、不降级、充分测试、文档先行、提交推送后开发。 +5. Agent 锁定本文件 §1 的 A–K 结论,进入文档编写与实现。 + +--- + +## 8. 后续变更流程 + +- 任何与本文冲突的实现,先改本文并写明「变更理由 / 影响 / 迁移」。 +- 新增核心语法(任何新标记)必须走 `doc/adr/` + `core-surface.md`;本文所有语法均为既有标记的组合。 +- 新增会话语言、跨语言数据平面、callback RPC,各自开独立设计文档,不塞进本文件。 diff --git a/doc/roadmap/foreign-v2.md b/doc/roadmap/foreign-v2.md new file mode 100644 index 0000000..ee9b039 --- /dev/null +++ b/doc/roadmap/foreign-v2.md @@ -0,0 +1,226 @@ +# 外联内核 v2 路线图(F0–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_` 支持 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))。 diff --git a/doc/roadmap/notebook-session.md b/doc/roadmap/notebook-session.md new file mode 100644 index 0000000..38116ae --- /dev/null +++ b/doc/roadmap/notebook-session.md @@ -0,0 +1,177 @@ +# 文档会话路线图(D0–D5) + +| | | +|---|---| +| 状态 | **规划中(依赖 F3)** | +| 日期 | 2026-10-17 | +| 层 | Runtime + Document(view 服务端 / 前端) | +| 相关 | [notebook-session.md](../design/notebook-session.md) · [notebook-syntax.md](../design/notebook-syntax.md) · [foreign-kernel.md](../design/foreign-kernel.md) · [foreign-v2.md](foreign-v2.md) · [foreign-notebook-decisions.md](../research/foreign-notebook-decisions.md) | +| 核心表面 Δ | 无 | + +> F 层让“外部语言能持久运行”;D 层让“文档里的多个 cell 像 notebook 一样共享状态、单步、切换内核”。两层分开验收。 + +--- + +## 0. 依赖 + +- **F3**:Python / Node 持久内核。 +- **F3.5**:`session_set/get/names`。 +- 现有 `DebugController`(Marqdo 语句单步)。 +- 现有 `writeback` / `annot` / view 结构。 + +没有 F3/F3.5,D2 只能做一次性 Run,不是共享状态。 + +--- + +## 1. 阶段总览 + +| 阶段 | 内容 | 估算 | +|---|---|---| +| **D0** | 设计/语法/决策文档 | 已完成 | +| **D1** | `src/notebook/`:cell index、表解析、session 结构、诊断 | 2–3 天 | +| **D2** | 服务端 API:open/close/cell run/step/run_all/restart/interrupt | 3–4 天 | +| **D3** | view UI:工具栏、cell 徽标、kernel 下拉、状态面板、journal | 3–4 天 | +| **D4** | statement step、dirty/stale、writeback | 2–3 天 | +| **D5** | replay、持久化、并发优化、测试补全、发布 | 2–3 天 | + +--- + +## 2. D1 — Cell index 与表解析 + +### 内容 + +- 新模块 `src/notebook/`: + - `cell.rs`:从 AST 提取绑定名代码围栏;id/name/lang/line/source hash。 + - `syntax.rs`:读取 `内核表` / `会话表`;中英列名。 + - `session.rs`:`DocumentSession` 结构、kernel registry、value store、journal。 + - `diag.rs`:重复/未知/语言不匹配/未入会话诊断。 +- 自动模式:无表 → 文档顺序 + 默认内核。 +- 解析器不改;只遍历 `Module.functions` + `Stmt::Assign { value: Expr::Code }`。 +- 测试:单元 + `tests/notebook/*.mq.md`。 + +### 验收 + +- 两个 Python cell + 一个会话表 → cells 顺序、kernel 归属正确。 +- 无表 → 自动顺序。 +- 未知内核/未知单元/重复/语言不匹配 → 可读诊断。 +- 未绑定围栏不进入 cell index。 + +--- + +## 3. D2 — 服务端 API + +### 内容 + +- `src/view/notebook_api.rs`(或 `view/session_api.rs`): + - open / close / reload + - cell run / step / run_all + - kernel restart / interrupt / assign + - state list / push / pull + - journal +- Session 存储:`OnceLock>>>`(类似 debug sessions)。 +- 每个文档一个 session;key = 相对路径。 +- 执行线程:cell 执行不阻塞 HTTP;响应返回记录;SSE/EventBus 可选。 +- 错误统一 JSON。 + +### 验收 + +- open 返回 cells/kernels/journal。 +- cell run:never→running→clean/error;状态更新。 +- step:按会话顺序执行下一个。 +- run_all:按顺序;restart 选项。 +- 同 kernel 串行;不同 kernel 可并行。 +- close/drop kill 所有 kernel。 +- API 单测/集成测试。 + +--- + +## 4. D3 — View UI + +### 内容 + +- 工具栏:Run All / Restart & Run All / Step Cell / Step Statement / Kernel 状态 / Restart / Interrupt / State / Journal。 +- Code card: + - 状态徽标(never/clean/dirty/stale/error/running/unlisted) + - kernel 下拉 + - Run / Step + - 输出区(stdout/stderr/result/truncated) + - 执行序号 / 耗时 +- 状态面板: + - Marqdo 值 / kernel 变量分栏 + - Push / Pull / Refresh + - Secret 打码、大对象摘要 +- Journal 面板:表格 + 跳转 + 导出。 +- 键盘:Ctrl/Cmd+Enter、Shift+Enter、F5、F10。 +- 静态导出的 Run 仍隐藏。 + +### 验收 + +- 手工冒烟:两个 Python cell 共享 `x`;切换 kernel 后隔离;Restart 清状态。 +- 状态面板 Push/Pull。 +- 错误 cell 红色徽标 + stderr。 +- 页面刷新后 session 仍在(服务端内存)。 + +--- + +## 5. D4 — Statement step / dirty / writeback + +### 内容 + +- Statement step:复用 `DebugController`,与 DocumentSession 关联;暂停点显示变量。 +- dirty:reload 后 source hash 变化。 +- stale:按会话顺序,上游变更 → 下游 stale(v2 近似)。 +- writeback:单 cell / 全部;``;不自动。 +- 运行历史 / 执行序号。 + +### 验收 + +- Statement step 在 view 中可用;外联调用原子完成。 +- 编辑 cell → dirty;Run All 后 clean。 +- 上游变更 → 下游 stale。 +- 显式 writeback 写入文档;不自动改文件。 + +--- + +## 6. D5 — Replay / 持久化 / 发布 + +### 内容 + +- Journal replay:新 kernel,按 journal 顺序/输入 hash 重放;比较 stdout/result hash;divergence 报告。 +- 可选持久化 `.marqdo/sessions/.json`(kernel/cell 归属/journal/value store 摘要;默认 git 忽略)。 +- 并发优化:不同 kernel 并行;同 kernel 串行。 +- 测试补全;文档;catalog;CHANGELOG。 +- 版本:D 层随 1.5.x。 + +### 验收 + +- Replay 能复现 clean 会话;dirty 输入给出 divergence。 +- 关闭/重启服务无进程泄漏。 +- 文档完整;金样例绿。 + +--- + +## 7. 测试矩阵 + +| 测试 | 断言 | +|---|---| +| `notebook/kernels.mq.md` | 内核表/会话表解析 | +| `notebook/auto-session.mq.md` | 无表自动顺序 | +| `notebook/shared-state.mq.md` | 同 kernel 共享变量 | +| `notebook/isolated-kernels.mq.md` | 不同 kernel 隔离 | +| `notebook/step.mq.md` | cell step 顺序 | +| `notebook/state-bridge.mq.md` | Marqdo ↔ kernel 推拉 | +| `notebook/dirty.mq.md` | 编辑 → dirty/stale | +| `notebook/invalid-*.mq.md` | 诊断 | +| API 集成 | open/run/step/run_all/restart/interrupt/close | +| 安全 | exec=false、cwd 越界、超时、Secret 打码 | + +依赖 node 为主;python 条件跳过。 + +--- + +## 8. 完成定义 + +- D1–D4 验收;D5 可选(replay/持久化)。 +- 文档会话与 F 层联调通过。 +- 手工 view 冒烟:共享状态 / 单步 / 切换 / 状态面板 / journal。 +- 测试绿;文档更新;提交推送。