Files
marqdo/doc/design/foreign-v3.md
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

20 KiB
Executable File
Raw Permalink Blame History

外联运行时 v3 — 能力缺口与深化设计(Proposed)

状态 Proposed;尚未实现
日期 2026-10-18
层 Runtime(foreign)· Document(foreign.session)· View(投影)
相关 foreign-kernel.md · notebook-session.md · foreign-v2.md · stdlib-writeback.md · view-static-interactive.md
核心表面 Δ 无增删:不新增 Markdown 标记、不新增 notebook CLI

本文只定义设计,不承诺已实现。当前基线是 v1.5.0 之后的本地工作:foreign.session 句柄、多内核、values 初始化、view 控制、静态执行与显式 writeback 已可用;本文处理仍然缺失的能力。


1. 设计约束

v3 必须继续满足以下约束,否则不进入实现:

  1. 外联库拥有内核与状态:foreign 管理内核、会话、cell 计划、输入、输出、journal 和生命周期。view 只消费句柄,不拥有第二套运行时。
  2. 表与围栏是值:内核表、单元表、输入表、值表 都是普通 Marqdo 值;没有保留表名,没有新增标记。
  3. 单一执行语义:run 是规范执行;view 是同一文档的交互投影;静态导出是同一会话的快照,不另写解释器。
  4. 没有 Notebook 模式:没有 marqdo notebook,没有 In/Out,没有“普通 view / notebook view”两套布局。
  5. 显式 I/O:Marqdo 值通过 values / session_set 传递;程序 stdin 是单独概念,不能伪装成 marqdo_input。
  6. 显式持久化:默认不改源码;writeback 必须由文档显式调用,或由用户显式选择策略。
  7. 安全默认值:执行受 capability 控制;输入/输出有界;不反序列化任意对象;跨文档共享必须显式开启。

2. 基线:现在已经有什么

能力 状态
foreign.run / run_lang / invoke / probe 已实现
foreign.call / call_many / JSON 进出 / 并行 已实现
session_open / eval / set / get / names / close / list 已实现
foreign.session kernels= cells= values= 已实现
多内核 view 会话、cell 顺序、内核归属 已实现
Marqdo 表通过 values 传入多个内核 已实现
无 会话 时无状态 cells 已实现
view 每 cell 内核选择 / Clean / Run 已实现
静态导出执行 cells 并嵌入真实输出 已实现
静态页 session summary、内核归属、多内核展示 已实现
显式 writeback.record 已实现(库能力)
静态页按钮的“不可执行”提示 已实现

2.1 实施状态(2026-10-18)

ID 状态 备注
G1/G2 ✅ 已实现 session eval raw stdin;foreign.session inputs=;per-cell UI;Python/Node 测试
G5 ✅ 基本实现 session_interrupt + view Interrupt;Python SIGINT 保留会话;Node 进程可能被终止
G4 ✅ 已实现(API) add/remove/set-value + generation;view 尚未提供 add/remove UI
G6 ✅ 已实现(API) export/import/replay JSON snapshot;view/CLI 尚未做文件封装
G9 ✅ 已实现(CLI/API 基础) view capture + view output --snapshot;source hash 校验
G3 ✅ 边界已实现 顶层 plan;嵌套 plan 诊断
G10 ✅ 显式 persist /api/session/cell/persist + view Persist;不自动写源码
G7/G8 📌 已移出当前目标 设计保留,后续版本再开发

3. 缺口清单

ID 缺口 优先级 当前行为 目标
G1 持久内核 raw stdin P0 持久内核只有 marqdo_input 程序 stdin 与控制协议分离
G2 每 cell 独立 stdin P0 页面级 Cell stdin,Run All 共用一个输入 cell 级输入表 + UI
G3 动态 plan P2 只读顶层 会话 明确边界,或受控动态
G4 运行时更新 plan P1 values 只在打开时初始化 显式 session 变更 API
G5 kernel interrupt P0 只能等超时/杀进程组 可中断当前 eval
G6 状态持久化 / replay P1 journal/dirty 只在内存 导出/恢复/replay
G7 跨文档内核 P2 每文档独立 显式 scope/空间
G8 非 Python/Node 持久内核 P3 Go 等一次性执行 LangSpec 会话适配器
G9 live → static 输入捕获 P0 静态构建不捕获临时 stdin 显式 snapshot 捕获
G10 自动 writeback P2 必须显式调用 显式策略下的“运行后写回”

4. 统一模型

4.1 会话句柄

foreign.session 返回的句柄是一个普通 Marqdo 值,建议稳定形状:

{
  kind: "foreign-session",
  id: "<session-id>",
  document: "<entry-source-hash>",
  status: "created | ready | running | interrupted | dirty | closed",
  kernels: [...],
  cells: [...],
  inputs: [...],
  values: [...],
  generation: 1
}

view 只读这些字段;任何执行操作都通过 foreign 的 host API。句柄不是第二套运行时。

4.2 三种输入

必须严格区分:

输入 目标 形态 当前
values 内核变量 Marqdo 值 → JSON copy 已实现
input marqdo_input JSON 值 已实现(低层)
stdin 程序 stdin 原始文本/字节 仅无状态 cell 有

v3 不允许把 raw stdin 偷偷塞进 marqdo_input;两者语义不同。

4.3 每 cell 输入表

不新增标记,仍然使用普通表:

`单元输入` =
| 单元 | stdin | input |
|------|-------|-------|
| 计算 | hello | {rate: 0.08} |
| 复核 |       | {check: true} |

foreign.session 增加可选参数:

foreign.session kernels=... cells=... values=... inputs=`单元输入`

规则:

  • stdin 只给该 cell 的程序 stdin;
  • input 只给该 cell 的 marqdo_input;
  • 空值表示不提供;
  • 输入大小有上限,超限显式报错;
  • 静态导出使用同一张表,因此 view 与静态快照可以一致。

4.4 执行流水线

evaluate 会话 handle
  → open kernels
  → apply values
  → apply cell inputs
  → run cell
  → record {stdout, stderr, input_echo, result}
  → next cell

失败不终止整个 Run All;错误写入 cell record,journal 保留。


5. G1/G2:持久内核 stdin 与每 cell 输入

5.1 问题

当前持久内核的 worker 用 stdin 传输 JSON 控制协议,因此程序自己的 stdin 不可用;marqdo_input 只是 JSON 变量,不是 stdin。

5.2 方案 A(推荐):控制通道与程序 stdin 分离

  • Unix:父进程创建 socketpair(或两个 pipe),worker 通过 fd 3/4 读写控制帧;程序 stdin 使用单独的 pipe。
  • Windows:named pipe 或可继承的匿名 pipe 作为控制通道;程序 stdin 单独 pipe。
  • worker 协议升级为 protocol: 2:
    • 控制帧:eval / set / get / interrupt / close
    • eval 帧可带 stdin(UTF-8)或 stdin_b64(二进制,后续)
  • Python worker:每次 eval 前把 sys.stdin 替换为 io.TextIOWrapper/StringIO,eval 后恢复控制通道;用户代码读到的是真正的 stdin。
  • Node worker:控制 readline 移到控制 pipe;每次 eval 把 process.stdin 替换为 PassThrough/Readable,eval 后恢复。
  • 超时/中断关闭该次 stdin,不污染下一次 eval。

5.3 方案 B(降级):只支持 input

如果控制通道暂不实现,持久内核只支持 input,并显式拒绝 raw stdin:

persistent kernel stdin is unavailable; use input= or stateless cells

不能静默把 stdin 变成 marqdo_input。

5.4 方案 C:stdin cell 降级为一次性

持久会话中遇到 raw stdin 时,用一次性进程执行该 cell;明确标记 state: none,不假装内核态连续。

5.5 UI 与静态

  • view:每个代码卡提供 Cell stdin 小输入框,或者页面级输入表;推荐每 cell,因为它们经常不同。
  • 静态:读取 inputs 表;没有输入时显示“requires stdin”说明,而不是 traceback。
  • Run All 使用每 cell 的输入;不再把一个页面级 stdin 复制给所有 cell。

5.6 验收

  • Python 与 Node 持久内核都能读取真实 stdin;
  • 同一个 cell 连续 eval 不串输入;
  • 超时/中断后下一次 eval 仍可读 stdin;
  • 无状态 cell 行为不变;
  • 静态快照使用相同输入表,结果与 live 一致(在相同输入下)。

6. G3:动态 plan 的边界

6.1 问题

foreign.session 目前只识别 entry 顶层的 会话 绑定。分支、函数、运行时循环中定义的 plan 不会被 view 发现。

6.2 设计决定(建议)

v3 不支持任意控制流中的 plan。 这是有意的语义边界:

  • plan 是文档的声明,不是程序运行时的副作用;
  • view 不应为了找 plan 而执行 # main;
  • 避免 view 再次长出一套“运行程序再猜计划”的隐式逻辑。

允许的动态形式:

  • 顶层赋值右侧的纯表达式,包括引入的纯函数;
  • foreign.session 的 tables/values 可以由顶层表函数计算;
  • 运行时变化通过 G4 的显式 session API 完成。

不支持:

  • ## 函数内部的 plan;
  • if/while 分支里的 plan;
  • 依赖 # main 副作用才能得到的 plan。

6.3 诊断

如果源码中出现非顶层 foreign.session,给出:

foreign.session: plan must be a top-level binding (会话 = > foreign.session ...)

而不是静默降级为无状态。


7. G4:运行时更新 plan

7.1 目标

已打开的 view session 允许用户显式修改 cell 归属、增加/移除 cell、更新内核变量;所有修改都要可追踪。

7.2 API

foreign.session_assign session=<handle> cell="计算" kernel="复核"
foreign.session_add_cell session=<handle> cell="新单元" kernel="分析"
foreign.session_remove_cell session=<handle> cell="旧单元"
foreign.session_set_value session=<handle> kernel="分析" name="rate" value=0.08

所有操作:

  • 校验 cell/kernel 语言;
  • 递增 generation;
  • 写入 journal(kind=plan_change / value_change);
  • 标记受影响 cell 为 dirty;
  • 失败不改变 handle。

7.3 View

  • 内核下拉复用 session_assign;
  • 增加/删除 cell 放在显式菜单,不做隐式拖拽写入源码;
  • UI 显示 generation / dirty 状态。

7.4 静态

静态快照不执行变更;它记录变更后的 plan,或在构建时执行一次并固化。


8. G5:kernel interrupt

8.1 API

foreign.session_interrupt id=<session-id>

8.2 行为

  • 控制通道发送 interrupt;
  • worker 取消当前 eval,返回 {ok:false, interrupted:true};
  • 保留已完成的值和 journal;
  • 状态从 running → interrupted;
  • 下一次 eval 可以继续使用内核(除非进程已损坏);
  • 超时继续作为最后一道防线。

8.3 View

  • 工具栏增加 Interrupt;执行中的 cell 显示 interrupted;
  • 不自动重跑;
  • 静态导出没有 interrupt(快照不执行)。

8.4 跨平台

Unix:进程组信号 + 控制帧;Windows:控制帧 + taskkill /T fallback。两者都必须有测试。


9. G6:状态持久化与 replay

9.1 不做的事

  • 不做 Python pickle / Node 堆快照;
  • 不做任意对象反序列化;
  • 不把内核内存默认写进 .mq.md。

9.2 显式快照

foreign.session_export session=<handle> path=".marqdo/sessions/doc-1.json"
foreign.session_import path=".marqdo/sessions/doc-1.json"

快照只包含:

{
  version: 1,
  document_hash: "...",
  plan_hash: "...",
  kernels: [{name, lang, cmd, values: {...}}],
  cells: [{name, kernel, status, last_ok, last_error}],
  journal: [...],
  inputs: [...]
}

值只允许 JSON 可表达的 Marqdo 值;不可序列化的值显式失败。

9.3 replay

foreign.session_replay path="..." verify=True

按 journal 顺序重放 cell + inputs,比较 stdout/status;差异写入 report。replay 不覆盖原 journal,除非显式 append。

9.4 存储

  • 默认目录 .marqdo/sessions/(gitignore 可选);
  • 用户可通过 path 放到受控目录;
  • 不默认提交,不默认写源码。

10. G7:跨文档内核(Deferred / future)

状态:已移出 v3 当前实现目标。 本节设计保留,作为后续版本(v4 或独立 session-scope 工作)的输入;当前不承诺 API 或兼容性。

10.1 原则

  • 默认每文档独立;
  • 跨文档必须显式 scope= / space=;
  • 不自动按变量名或路径共享。

10.2 API

foreign.session_open lang="python" scope="shared:analytics"
foreign.session_list scope="shared:analytics"
foreign.session_close id=... scope=...
  • scope 注册表由 foreign runtime 管理;
  • 同名冲突报错,不覆盖;
  • view 只能打开当前文档声明允许的 scope;
  • 生命周期由 owner/refcount 管理,最后一个引用关闭时清理。

10.3 安全

  • 跨文档共享可能违反文档隔离,必须 capability + 显式配置;
  • journal 标记 scope;
  • 静态导出默认不打开跨文档 scope。

11. G8:非 Python/Node 持久内核(Deferred / future)

状态:已移出 v3 当前实现目标。 本节设计保留,等待目标语言与 worker 适配器确定后再实现;当前不承诺 API。

11.1 模型

不是所有语言都需要持久内核。LangSpec 增加能力标志:

session: none | protocol_v2
  • none:只能 run / invoke 一次性;
  • protocol_v2:实现控制通道与 eval 协议,可以 session_open。

11.2 适配器

Go 等语言通过一个薄 worker 实现:

control frame: eval {code, stdin, input}
result frame: {ok, stdout, stderr, result, error}

不允许“看起来像持久内核、实际每次重启”的假实现。

11.3 失败语义

  • session_open 对 session: none 的语言明确报错;
  • foreign.session 的 plan 只能使用支持 session 的语言;
  • 静态/无状态仍可使用一次性执行。

12. G9:live → static 输入捕获

12.1 问题

静态构建在构建环境执行,无法知道用户在 live view 中临时输入的 stdin;同一文档的结果可能不同。

12.2 设计

增加显式的“捕获快照”:

view → Capture snapshot → .marqdo/snapshots/<doc>.view.json

快照内容:

  • document source hash;
  • session plan(kernels/cells/values);
  • 每 cell 的 stdin/input;
  • 每 cell 的 stdout/stderr/status;
  • journal 摘要、语言/解释器版本;
  • 捕获时间。

静态导出:

marqdo view output --snapshot .marqdo/snapshots/doc.view.json

优先使用快照中的记录,校验 source hash,不重新执行;若 hash 不匹配,显式失败或 --execute 重跑。

12.3 安全/隐私

  • 快照可能包含 secrets;默认不提交、不发布;
  • 提供 redact 字段/正则;
  • 静态页面只发布脱敏后的快照。

12.4 验收

  • live 中成功的结果可以在静态页面原样显示;
  • 不捕获内核内存,只捕获输入/输出/状态;
  • 没有快照时回退到构建时执行,行为明确。

13. G10:自动 writeback

13.1 原则

“自动”必须是用户显式选择的策略,不是默认副作用。

13.2 API

foreign.session persist=`写回策略`

策略表:

`写回策略` =
| 单元 | key |
|------|-----|
| 计算 | total |
| 复核 | check |

或 view 的 Persist results 按钮:将当前 cell 结果写到 writeback.record key=...。

13.3 语义

  • 默认不写源码;
  • 显式策略只在 用户点击 Persist 或 marqdo run --writeback 时执行;
  • 静态构建默认不写回;--writeback 必须显式;
  • writeback 只支持 JSON 可表达值;
  • 写入位置/格式仍由 writeback 库决定。

13.4 与静态快照的关系

  • 静态快照是只读发布;
  • writeback 是源码内的活结果;
  • 两者可以共存,但不能互相隐式触发。

14. API / 端点汇总

14.1 新增 foreign 函数

foreign.session inputs=
foreign.session_assign
foreign.session_add_cell
foreign.session_remove_cell
foreign.session_set_value
foreign.session_interrupt
foreign.session_export
foreign.session_import
foreign.session_replay
foreign.session_open scope=
foreign.session_list scope=

14.2 View API

POST /api/session/cell/run      { cell, stdin }
POST /api/session/run_all       { restart, inputs? }
POST /api/session/cell/clear
POST /api/session/plan/assign
POST /api/session/plan/add
POST /api/session/plan/remove
POST /api/session/plan/value
POST /api/session/interrupt
POST /api/session/snapshot/capture

所有端点只操作 foreign 句柄;view 不直接读写内核。

14.3 CLI

marqdo view output --snapshot FILE
marqdo view output --execute
marqdo view output --no-exec
marqdo run --writeback

不新增 marqdo notebook。


15. 语义矩阵

能力 run view static
foreign.session plan 作为普通值执行 消费句柄 可执行或快照
raw stdin 支持(一次性/session) 每 cell inputs 表/快照
interrupt 无 UI 可调用 不可用
state export 可调用 可显式导出 不导出或快照
cross-doc(deferred) 设计保留 设计保留 设计保留
writeback --writeback 显式按钮 默认不写

16. 实施顺序

P0(先做,直接影响真实使用)

  1. G1/G2 stdin:控制通道 + 每 cell 输入表 + UI。
  2. G5 interrupt:避免只能等超时。
  3. G9 snapshot capture:解决 live/static 不一致。

P1

  1. G4 runtime plan updates。
  2. G6 export/replay。

P2

  1. G3 dynamic plan 边界:按第 6 节,只做顶层纯表达式;任意控制流不承诺。
  2. G10 explicit writeback policy。

Deferred(不在当前目标)

  • G7 cross-document scope:设计保留,后续版本再开发。
  • G8 non-Python/Node persistent adapters:设计保留,等待目标语言与 worker。

17. 测试设计

单元

  • stdin 协议:空输入、大输入、超时、中断、连续 eval;
  • 每 cell 输入隔离;
  • 返回值锚定在调用点(已修复的 CallFrame.call_line);
  • 表格不产生 call chip(已修复);
  • plan top-level 诊断;
  • session generation / dirty;
  • export/import/replay 校验。

集成

  • Python 持久内核读 sys.stdin;
  • Node 持久内核读 process.stdin;
  • view Run All 使用每 cell 输入;
  • interrupt 后下一次 eval 正常;
  • static snapshot 与 live 结果一致;
  • snapshot hash 不匹配显式失败;
  • cross-doc scope 冲突/清理;
  • Go 一次性 vs 持久能力诊断;
  • writeback 只显式写入。

静态

  • 输出无 traceback;
  • 没有输入时显示说明而非伪造;
  • 多内核 controls 显示;
  • writeback slot 单块、暗色主题;
  • 静态按钮提示。

18. 兼容与迁移

  • 现有 foreign.session kernels= cells= values= 保持兼容;
  • 新 inputs= 可选;
  • session_open 旧协议继续可用;v2 控制通道通过 handshake 协商;
  • 旧页面没有 inputs 时仍按空 stdin 执行/显示说明;
  • 不修改已发布的 v1.5.0 tag;v3 以新版本发布。

19. 需要拍板的决策

  1. G1:是否接受控制通道与程序 stdin 分离的协议改造?否则只能保留 input,不能宣称 raw stdin。
  2. G3:是否接受“plan 必须是顶层声明”的边界?若不接受,需要定义 view 可安全调用的 plan 入口,风险更高。
  3. G6:状态快照只允许 JSON 值,是否可接受?不做任意对象序列化。
  4. G9:快照文件是否默认放在 .marqdo/snapshots/ 且不提交?涉及 secrets。
  5. G10:自动 writeback 是否只允许显式按钮/flag,而不是每次运行自动写源码?

20. 当前目标范围

v3 当前实现目标为:G1、G2、G3、G4、G5、G6、G9、G10。

G7、G8 已移出当前目标,但设计文档保留在本文件第 10、11 节,供后续开发;它们不计入 v3 完成条件,也不影响现有 API 的兼容性承诺。

21. 非目标

  • 不新增 Markdown 标记;
  • 不新增 notebook CLI/模式;
  • 不把任意内核内存序列化;
  • 不默认修改 .mq.md;
  • 不自动镜像变量;
  • 不把 view 变成第二套解释器;
  • 不把“未实现”伪装成支持。