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.
306 lines
11 KiB
Markdown
306 lines
11 KiB
Markdown
# 文档原生 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)) |
|
||
|
||
解析器本身**不需要改**。这是本设计最重要的约束:语法是既有标记的组合,不是新构造。
|