Files
marqdo/doc/design/notebook-syntax.md
T
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

306 lines
11 KiB
Markdown
Executable File
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 文档原生 view cells 语法
| | |
|---|---|
| 状态 | **Decided;D1 解析已实现** |
| 日期 | 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
这份文档演示一个最小 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 没有任何约定表
````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. 可读性规则(语法评审标准)
新增/修改任何 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,把时序讲清楚:
```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. 实现落点
| 逻辑 | 位置 |
|---|---|
| 识别 `会话` 的 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](notebook-session.md)) |
解析器本身**不需要改**。这是本设计最重要的约束:语法是既有标记的组合,不是新构造。