# 外联内核 · 文档会话 · 决策记录 | | | |---|---| | 状态 | **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` 编排;结果可重复。 - **View cells(交互面)**:`view` 中按 cell 执行、单步、切换内核、查看状态。适合探索,不默认写入文档;不是第二个 CLI 模式。 - 两者共享同一个内核运行时与同一套 cell 索引;view cells 是 program execution 的**交互镜头**,不是替代品。 理由:如果让 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` - View cells 的输出默认只在 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,各自开独立设计文档,不塞进本文件。