Files
marqdo/doc/design/notebook-syntax.md
cflmy fb28eee62f feat(foreign): own view sessions and clear outputs
foreign.session returns a handle from ordinary kernel/cell tables; view consumes only the 会话 binding. Sessions live in host foreign_doc. Without 会话, view cells run stateless one-shot. Add /api/session/clear and a Clear outputs button for every view page; clearing keeps persistent kernel state.
2026-10-18 12:42:15 +08:00

11 KiB
Raw Permalink Blame History

文档原生 view cells 语法

状态 Decided;D1 解析已实现
日期 2026-10-17
层 Document(读取约定) + Runtime(校验)
相关 foreign-notebook-decisions.md · notebook-session.md · foreign-kernel.md · core-surface.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(或唯一入口对象)的体内,和代码单元并列:

# 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. 完整示例

# main

这份文档演示一个最小 view cells 文档:两个 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 没有任何约定表

# 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. 可读性规则(语法评审标准)

新增/修改任何 cell 表约定,必须满足:

  1. 先读人话:去掉执行语义后,表格仍像目录/清单。
  2. 不使用属性串:不写 kernel=…、class=…、JSON/YAML 元数据。
  3. 不隐藏意图:执行顺序、内核归属必须在一处可见。
  4. 不引入新标记:只用 # / 表格 / 反引号 / 既有代码面。
  5. 默认安全:表格只声明,不自动执行;只有 Run / Step 触发。
  6. 命名用领域词:分析、绘图、前端,不用 k1、default、stage2(除非确实是默认)。
  7. 说明列可选但推荐:给未来的读者/LLM 一点上下文。
  8. 错误可读:诊断要指出“哪个单元、哪个内核、哪一行、怎么修”。
  9. 中英对称:中文用中文列名,英文用英文列名;语义一一对应。
  10. 无表也能跑:约定表是增强,不是前置条件。

6. 诊断规范

情况 诊断(中文示例) 修复建议
内核名重复 内核表: 内核名「分析」重复(第 12、20 行) 改名或合并
会话引用未知内核 foreign.session: cell「汇总」引用了未声明的内核「分析」 在 kernels 表声明,或改用语言 id
会话引用未知单元 会话表: 找不到名为「清洗」的代码单元 检查 `清洗` = 绑定
单元重复 会话表: 单元「汇总」重复出现 每个单元只列一次
语言不匹配 会话表: 单元「前端」(node) 不能使用 python 内核「分析」 换内核或换语言
未入会话 (非错误)view 徽标:未入会话 需要时加一行
内核表为空 内核表: 至少声明一个内核,或删除该表使用默认内核 删除表或补行
会话表为空 会话表: 至少列出一个单元,或删除该表使用自动顺序 删除表或补行

原则:不静默忽略。读者必须知道为什么某个 cell 没跑。


7. 与 program execution 的关系

  • 内核表 / 会话表 只是传递给 foreign.session 的普通表变量,不是保留名。
  • marqdo run 仍然执行 # main 的程序语义;这两个表会被求值为普通数据。
  • run 的外联编排用显式 API(foreign.session_open / session_eval / call);foreign.session 句柄服务 view 的 cells 与一键 Run All。
  • 两者可以并存:
    • 文档用表描述“交互时怎么跑”;
    • # main 用显式调用描述“CI 时怎么跑”。
  • 如果两者冲突,以 run 的程序语义为准;cell 表只影响 view。

这样避免把“执行计划”变成第二套程序语义。


8. 状态桥的语法边界

v2 不为状态交换新增表格/注释。原因:

  • “什么时候送、什么时候取、送到哪个内核、赋值给哪个 Marqdo 变量”需要精确语义;
  • 若做成隐式表格动作,容易产生隐藏状态与顺序歧义;
  • v2 先用显式 API,把时序讲清楚:
    把 `数值表` 送进 `分析` 内核:
    **> 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. 实现落点

逻辑 位置
识别 会话 的 foreign.session 句柄 src/host/foreign_doc.rs
读取绑定值 AST Stmt::Assign + Expr::Table / Expr::List;或最近一次 run 的 bindings
校验名称/语言/重复/未入会话 同上;错误进入现有 Diagnostic
cell index(绑定名/行号/语言/source hash) 解析后的 Module 遍历
只读展示 view Structure:表渲染成普通表格 + 徽标
执行 Document Session API(见 notebook-session.md)

解析器本身不需要改。这是本设计最重要的约束:语法是既有标记的组合,不是新构造。