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.
11 KiB
11 KiB
文档原生 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 表约定,必须满足:
- 先读人话:去掉执行语义后,表格仍像目录/清单。
- 不使用属性串:不写
kernel=…、class=…、JSON/YAML 元数据。 - 不隐藏意图:执行顺序、内核归属必须在一处可见。
- 不引入新标记:只用
#/ 表格 / 反引号 / 既有代码面。 - 默认安全:表格只声明,不自动执行;只有 Run / Step 触发。
- 命名用领域词:
分析、绘图、前端,不用k1、default、stage2(除非确实是默认)。 - 说明列可选但推荐:给未来的读者/LLM 一点上下文。
- 错误可读:诊断要指出“哪个单元、哪个内核、哪一行、怎么修”。
- 中英对称:中文用中文列名,英文用英文列名;语义一一对应。
- 无表也能跑:约定表是增强,不是前置条件。
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)
共享表:| 内核变量 | Marqdo 变量 | 方向 | 说明 |,每次单元执行前送入、后取回。- 每个 cell 的“运行条件/依赖”列:
依赖列声明上游单元。 - 内核别名:
内核表的名称可被use或短名引用。 - 多文件会话:跨
.mq.md的共享内核(默认仍隔离)。 - 语言特定的“会话能力”列(是否支持持久、是否支持行级调试)。
任何一项都要先过 §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) |
解析器本身不需要改。这是本设计最重要的约束:语法是既有标记的组合,不是新构造。