Host exposes oracle journals as language values with refuse/copy gates; bytecode and foreign session paths get modularized; applications and verification replay-policy sources land with Lake builds ignored. Co-authored-by: Cursor <cursoragent@cursor.com>
562 lines
22 KiB
Markdown
562 lines
22 KiB
Markdown
# 文档会话(View Cells)
|
||
|
||
## 2026-11-02:并发控制与完整历史 v5
|
||
|
||
以下为当前实现;后文保留首版设计与当时的状态表。
|
||
|
||
- HTTP `kernel/interrupt` 查找已存在的会话,经独立控制器发送请求,不等待单元执行锁或其他文档的初始化。未打开、尚在初始化的会话返回错误,不启动新内核。已加载文档的源码文件被删除后仍可取消正在执行的单元。
|
||
- 内核的中断能力绑定其持有的子进程,并在回收前撤销;旧能力不能指向后来启动的内核。引导阶段的取消被暂存,收到 ready 后投递。逻辑取消输入会合并重复信号;投递错误明确返回。Windows 尚无对应的保状态中断实现。
|
||
- 取消使 Run All 在当前单元结束后停止,返回实际 `ran`、`remaining` 和 `cancelled`;不会继续运行后续单元。内核没有退出时,取消前已发生的状态修改保留。close 撤销 API 会话,重新打开不会激活旧引用。
|
||
- 完整历史 v5 将并发取消作为所在操作的 `controls` 输入记录:操作起点之后的微秒偏移及各内核的真实接收结果。严格回放按输入重新投递并重新观察回执;操作先结束时撤销剩余定时请求,不能流入下一操作。实际回执或观察不匹配就报告差异。v4 无控制输入的历史仍可检查;v4 中出现 controls 字段会被拒绝。
|
||
- 严格检查先完成纯验证,再启动回放内核。实际执行中,每次协议请求必须先与预期请求一致;实际回复和每个单元的观察、批次结果也立即比较。首个差异后停止依赖后缀,包括同一个 Run All 内的后续单元。未执行的观察标记 `compared=false`,不冒充已比较的第二个差异。
|
||
|
||
快照导出支持可选 `compact:true`。默认仍为完整 JSON;紧凑格式
|
||
`marqdo.history.dag` v1 对相同子值做自底向上共享,整数使用十进制文本、
|
||
浮点数保存 IEEE 位模式,保留映射顺序和全部历史字段。导入和严格回放会自动
|
||
识别格式。SHA-256 校验只检测内容一致性,不提供来源认证。
|
||
解码要求规范节点、向后引用、全部可达和唯一键,并在展开前检查最多
|
||
1,000,000 个节点、8,000,000 个展开值、512 MiB 保守展开预算、128 层深度;
|
||
展开后再次检查安全值域。此格式减少导出字节数,尚未减少录制时内存,也不保证更快。
|
||
|
||
实际取消实验覆盖 Unix 上同步 Python/Node 持久会话;不能推导任意外部代码均有界停止。
|
||
[Python 3.14 信号文档](https://docs.python.org/3.14/library/signal.html#execution-of-python-signal-handlers)
|
||
说明纯 C 计算可延迟信号处理;
|
||
[Node 22.22.1 vm 文档](https://nodejs.org/download/release/v22.22.1/docs/api/vm.html#timeout-interactions-with-asynchronous-tasks-and-promises)
|
||
说明异步任务可能逃出同步求值的中断范围。完整源码 elaboration、控制适配器、
|
||
真实时钟与信号调度到形式模型的 refinement 仍需完成,不能以这些测试代替。
|
||
|
||
相关实现:`foreign_session/control.rs`、`foreign_doc/control.rs`、
|
||
`foreign_doc/packing.rs`、`foreign_doc/replay.rs` 与 `view/notebook_api.rs`。
|
||
真实 TCP/HTTP 取消、逐单元副作用屏障和独立快照消费记录位于论文
|
||
`PLDI/experiments/reviewer-v5/`。
|
||
|
||
| | |
|
||
|---|---|
|
||
| 状态 | **D1–D3 首版已实现;D4/D5 待做** |
|
||
| 日期 | 2026-10-17 |
|
||
| 层 | Runtime + Document(view 服务端 / 交互单元) |
|
||
| 相关 | [notebook-syntax.md](notebook-syntax.md) · [foreign-kernel.md](foreign-kernel.md) · [foreign-notebook-decisions.md](../research/foreign-notebook-decisions.md) · [view.md](view.md) · [view-debug.md](view-debug.md) · [stdlib-subtask.md](stdlib-subtask.md) |
|
||
| 核心表面 Δ | 无(读取既有 AST 与表格) |
|
||
|
||
> 文档会话是 view 背后的交互单元运行时:它记住哪些 cell、在哪个内核、按什么顺序执行、状态是什么、结果是否过期。它不是第二个 CLI 模式——`marqdo view` 是唯一的交互面,`marqdo run` 是规范执行。
|
||
|
||
---
|
||
|
||
## 1. 目标
|
||
|
||
1. **像 Jupyter 一样即时**:点一个 cell 就执行,状态保留。
|
||
2. **不像 Jupyter 一样隐藏**:执行顺序、内核归属、状态、过期情况都可查。
|
||
3. **不破坏 Marqdo 程序语义**:`marqdo run` 仍是规范执行;view 会话是交互镜头。
|
||
4. **Git 友好**:状态/输出不默认写进 `.mq.md`。
|
||
5. **多语言**:命名内核 + 显式状态桥。
|
||
6. **可复现**:Run All / journal / dirty / stale / replay。
|
||
|
||
---
|
||
|
||
## 1.1 实施状态(2026-10-18)
|
||
|
||
| 能力 | 状态 | 位置 |
|
||
|---|---|---|
|
||
| `foreign.session` 句柄(kernels/cells 表参数) | ✅ | `lib/foreign.mq.md` · `src/host/foreign_doc.rs` |
|
||
| cell plan 求值 | ✅ 解释器求值 `会话` 绑定;不扫描源码行、不认保留表名 | `src/interp.rs` · `src/host/foreign_doc.rs` |
|
||
| cell index(绑定名 / 行号 / source hash) | ✅ | 同上 |
|
||
| 命名内核 + 默认内核 + 语言校验 | ✅ | 同上 |
|
||
| 同内核共享 / 跨内核隔离 | ✅ | Node 金样例 + 单测 |
|
||
| `run_cell` / `step` / `run_all(restart)` | ✅ | `DocumentSession` |
|
||
| `restart_kernel` / `assign_kernel` | ✅ | 同上 |
|
||
| `kernel/interrupt` | 待做 | — |
|
||
| 状态桥 `push` / `pull` / `state_list` | ✅ | `DocumentSession` + `foreign_session` |
|
||
| journal(记录 + API + Journal 按钮) | ✅ | `DocumentSession::journal_json` · view |
|
||
| view 工具栏 / 状态徽标 / 内核下拉 / 状态表单 | ✅ | `src/view/html.rs` |
|
||
| `POST /api/session/*` | ✅(含 `reload`) | `src/view/notebook_api.rs` |
|
||
| cell step | ✅ | 同上 |
|
||
| Marqdo statement step | ✅(view 工具栏 Debug → 同一 view 服务的 `/debug`;`/api/debug/*`) | `src/debug` · `src/view/debug_api.rs` |
|
||
| dirty/stale 自动检测 | 部分(reload → dirty;assign → dirty;stale 传播待做) | `src/host/foreign_doc.rs` |
|
||
| writeback 集成 | 待做 | `writeback` |
|
||
| replay / 持久化 | 待做 | — |
|
||
| Python 会话 | ✅(本机无 python,CI/用户机条件测试) | `src/host/foreign_session.rs` |
|
||
| Node 会话 | ✅ | 同上 |
|
||
|
||
首版刻意不做:把状态写进 `.mq.md`、自动镜像变量、foreign 行级 debug、跨文档共享内核。
|
||
|
||
---
|
||
|
||
## 2. 两个执行面(不是两个 CLI 模式)
|
||
|
||
### 2.1 Program execution(规范)
|
||
|
||
- 入口:`marqdo run doc.mq.md` / CI / `view` 的 `Run document`。
|
||
- 执行:`# main` 程序语义;外联通过显式 `foreign.session_open/eval/call` 编排。
|
||
- 状态:一次运行内有效;运行结束进程退出(除非显式持久内核)。
|
||
- 结果:可复现;是文档的“真理”。
|
||
|
||
### 2.2 View cells(交互)
|
||
|
||
- 入口:`marqdo view doc.mq.md` → 文档单元(cell)控制。
|
||
- 执行:按 `会话表`(或自动顺序)逐 cell 执行。
|
||
- 状态:内核持久;可切换、重启、单步。
|
||
- 结果:默认临时显示;可显式 writeback。
|
||
- 不是“真理”:是探索界面;需要复现时用 Run All 或把编排写进 `# main`。
|
||
|
||
### 2.3 两者关系
|
||
|
||
```text
|
||
.mq.md
|
||
/ \
|
||
Program run View cells
|
||
(canonical) (interactive)
|
||
\ /
|
||
Document Session
|
||
├── cell index
|
||
├── kernel registry
|
||
├── journal
|
||
└── state panel
|
||
```
|
||
|
||
- 共享 cell index 与 kernel registry。
|
||
- `run` 不消费视图会话;`view` 只在文档绑定 `会话 = > foreign.session ...` 时提供持久 cell 控制;无 `会话` 时 cells 无状态一次性执行。
|
||
- 冲突时以 `run` 的程序语义为准;view cells 不改变文档语义。
|
||
|
||
---
|
||
|
||
## 3. 文档会话模型
|
||
|
||
```text
|
||
DocumentSession
|
||
├── doc_path / doc_hash
|
||
├── cells: Vec<Cell>
|
||
│ ├── id (name / anon@line)
|
||
│ ├── name (binding)
|
||
│ ├── lang
|
||
│ ├── line_start / line_end
|
||
│ ├── source_hash
|
||
│ ├── kernel (resolved)
|
||
│ └── status: never | clean | dirty | stale | error | running
|
||
├── kernels: KernelRegistry
|
||
│ ├── name → ForeignSession
|
||
│ └── default per language
|
||
├── value_store: HashMap<String, Value> // Marqdo 侧会话值
|
||
├── journal: Vec<ExecutionRecord>
|
||
├── created_ms / last_active_ms
|
||
└── surface: program | view
|
||
```
|
||
|
||
### 3.1 Cell
|
||
|
||
- 只有**绑定名**的代码围栏才是 cell:
|
||
```markdown
|
||
`加载` =
|
||
```python
|
||
...
|
||
```
|
||
```
|
||
- 未绑定围栏仍是叙述,不是 cell。
|
||
- `id`:优先绑定名;匿名围栏用 `anon@<line>`(不进入会话表)。
|
||
- 同名 cell 重复 → 诊断;会话表按名字引用。
|
||
- `source_hash` 用于 dirty 判断。
|
||
- `line_start/line_end` 用于定位;编辑后重建索引。
|
||
|
||
### 3.2 Cell index 构建
|
||
|
||
1. 读取/解析文档(现有 `parse_source` / `load_module`)。
|
||
2. 遍历 AST,找 `Stmt::Assign { name, value: Expr::Code(c) }`。
|
||
3. 记录 name、lang、source、span、source hash。
|
||
4. 通过解释器求值 `会话` 绑定(`foreign.session` 返回的句柄,含简单依赖);不扫描源码行、不认保留表名(见 [notebook-syntax.md](notebook-syntax.md))。
|
||
5. 解析 kernel 声明与 cell 归属;校验;生成诊断。
|
||
6. 生成执行顺序:
|
||
- 有会话表 → 行顺序;
|
||
- 无 → 文档顺序。
|
||
7. 未入会话的 cell → 状态 `unlisted`,UI 显示徽标。
|
||
|
||
### 3.3 Kernel registry
|
||
|
||
- key:`<document_id>:<kernel_name>`。
|
||
- 默认:`default:python`、`default:node`,按需启动。
|
||
- 命名:来自 `内核表`,首次执行时启动。
|
||
- 状态:`idle | starting | ready | busy | dead`。
|
||
- 同一 kernel 的 cell 严格串行;不同 kernel 可并行。
|
||
- 重启:kill + 清空状态 + 重新启动;cell 状态变 `never`。
|
||
- 关闭:kill + 移除。
|
||
|
||
### 3.4 Value store(Marqdo 侧会话值)
|
||
|
||
- 保存可从 Marqdo 推入内核的值(来自最近一次 Program run 的 bindings,或用户手动输入)。
|
||
- 也保存从内核取回的值(`session_get` / 状态面板 Pull)。
|
||
- 不是解释器 Env 的实时镜像;它是会话层的**值缓存**。
|
||
- 注入解释器:未来通过 `SessionEnv` 或显式变量赋值;v2 不做隐式注入。
|
||
- 用途:
|
||
- 状态面板显示;
|
||
- Push 到内核;
|
||
- 作为 `session_set` 的值来源;
|
||
- journal 记录。
|
||
|
||
### 3.5 Journal
|
||
|
||
每次执行追加一条:
|
||
|
||
```json
|
||
{
|
||
"seq": 3,
|
||
"cell": "汇总",
|
||
"kernel": "分析",
|
||
"lang": "python",
|
||
"ok": true,
|
||
"code": 0,
|
||
"ms": 42,
|
||
"source_hash": "…",
|
||
"stdout_hash": "…",
|
||
"result_hash": "…",
|
||
"started_ms": 1760000000000,
|
||
"error": ""
|
||
}
|
||
```
|
||
|
||
用途:
|
||
|
||
- 执行序号 / 顺序;
|
||
- dirty/stale 判断;
|
||
- replay;
|
||
- 视图显示;
|
||
- 调试(“为什么这个 cell 有值”)。
|
||
|
||
存储:内存 + 可选 `.marqdo/sessions/<doc-hash>.json`(默认 git 忽略)。
|
||
|
||
---
|
||
|
||
## 4. 执行语义
|
||
|
||
### 4.1 操作
|
||
|
||
| 操作 | 语义 |
|
||
|---|---|
|
||
| **Run cell** | 执行选中的 cell;必要时启动/复用 kernel |
|
||
| **Run above** | 按会话顺序执行到选中 cell(含) |
|
||
| **Run all** | 按会话顺序执行全部;可选 `restart` |
|
||
| **Step next cell** | 执行会话顺序中的下一个未执行/选中 cell |
|
||
| **Step next statement** | Marqdo 语句级单步(DebugController) |
|
||
| **Restart kernel** | kill + 重建;cell 状态 `never` |
|
||
| **Interrupt** | kill 当前 cell 进程组;kernel 标记 dead 或重启 |
|
||
| **Reset session** | 关闭所有 kernel,清 journal / value store |
|
||
|
||
### 4.2 执行一个 cell
|
||
|
||
```text
|
||
resolve cell -> resolve kernel
|
||
-> ensure kernel ready
|
||
-> [送入?] 显式 bridge 由文档代码/UI 负责
|
||
-> foreign.session_eval(kernel, source, input?)
|
||
-> record -> update cell status
|
||
-> [取回?] 由文档代码/UI 负责
|
||
-> journal append
|
||
-> view update
|
||
```
|
||
|
||
- 默认 cwd = 文档目录;env = kernel env。
|
||
- 输出:stdout / stderr / result / ms / truncated。
|
||
- 失败:cell 状态 `error`;journal 记录;不自动重试。
|
||
- 同一 kernel 串行;UI 禁用并发 Run。
|
||
|
||
### 4.3 Step 语义
|
||
|
||
| 类型 | 行为 |
|
||
|---|---|
|
||
| **Cell step** | 执行下一个会话 cell;状态保留 |
|
||
| **Marqdo statement step** | 执行下一条 Marqdo 语句;遇到 `foreign.session_eval` 时整个外联调用原子完成 |
|
||
| **Foreign line step** | 不做;未来 DAP |
|
||
|
||
- Cell step 是 view cells 的主单步。
|
||
- Statement step 复用 `DebugController`;需要把 debug session 与 DocumentSession 关联。
|
||
- 两者可以互相切换:cell step 到某个 Marqdo cell 后可 statement step;语句执行完回到 cell 边界。
|
||
|
||
### 4.4 中断
|
||
|
||
- `Interrupt`:向当前 kernel 进程组发 SIGINT/SIGKILL;记录 `interrupted`。
|
||
- 若 kernel 状态不确定 → 标记 dead;建议 restart。
|
||
- 不允许“中断后继续用同一 kernel”除非确认状态。
|
||
|
||
### 4.5 并发
|
||
|
||
- 同一 kernel:一次一个 cell。
|
||
- 不同 kernel:可并行(例如 Python 分析与 Node 前端)。
|
||
- `Run all` 默认按会话顺序串行;可配置“按 kernel 并行、按依赖串行”(后续)。
|
||
- 并发上限沿用 foreign(32)。
|
||
|
||
---
|
||
|
||
## 5. 状态桥(会话层)
|
||
|
||
### 5.1 显式 API
|
||
|
||
文档代码:
|
||
|
||
```markdown
|
||
把 `数值表` 送进 `分析` 内核:
|
||
**> foreign.session_set id="分析" name="xs" value=`数值表`**
|
||
|
||
从 `分析` 内核取回 `mean`:
|
||
**`均值` = > foreign.session_get id="分析" name="mean"**
|
||
```
|
||
|
||
### 5.2 状态面板
|
||
|
||
- 左侧:Marqdo 侧值(最近 Program run bindings + value store)。
|
||
- 右侧:每个 kernel 的变量(`session_names` + 按需 `session_get`)。
|
||
- 操作:
|
||
- Push:选 Marqdo 值 → kernel 变量;
|
||
- Pull:选 kernel 变量 → value store / 显示;
|
||
- Refresh;
|
||
- 复制名称/值。
|
||
- Secret 打码;大对象显示摘要(类型/长度/repr 截断)。
|
||
|
||
### 5.3 自动镜像
|
||
|
||
- v2 不做。
|
||
- 后续 `mirror`:`mq_` 前缀、白名单、按值拷贝、默认关。
|
||
- 原因见 [decisions](../research/foreign-notebook-decisions.md) §1-F。
|
||
|
||
### 5.4 类型
|
||
|
||
- JSON 拷贝;复杂对象需 `to_dict` / JSON。
|
||
- 大对象:v2 显示摘要;传输用文件/DB。
|
||
- 未来:Arrow / Parquet / 共享文件句柄。
|
||
|
||
---
|
||
|
||
## 6. Dirty / Stale / Run All
|
||
|
||
### 6.1 定义
|
||
|
||
| 状态 | 条件 |
|
||
|---|---|
|
||
| `never` | 未执行 |
|
||
| `clean` | 上次执行成功后源码未变 |
|
||
| `dirty` | 源码 hash 变了 |
|
||
| `stale` | 上游 cell 变了(依赖图;v2 先按会话顺序近似) |
|
||
| `error` | 上次执行失败 |
|
||
| `running` | 正在执行 |
|
||
| `unlisted` | 不在会话表 |
|
||
|
||
### 6.2 依赖
|
||
|
||
- v2:会话表行顺序 + 简单规则:
|
||
- 若上游 cell 的 source_hash 变了,下游标 `stale`;
|
||
- 若 kernel 重启,全部 `never`。
|
||
- v2.1:变量级依赖图(静态分析 + bridge 表),精确 stale。
|
||
- 不假装 Jupyter 的“隐藏顺序”:顺序就是表/文档顺序。
|
||
|
||
### 6.3 Run All
|
||
|
||
- 默认:按会话顺序执行;可选 `restart=true`。
|
||
- 规范执行:**restart + run all**;UI 明确按钮 `Restart & Run All`。
|
||
- 未重启时:显示“当前 kernel 有历史状态”警告。
|
||
- 执行后:生成 session summary(ok/fail/耗时/跳过的 cell)。
|
||
|
||
### 6.4 Replay
|
||
|
||
- 用 journal 的顺序和输入 hash,在新 kernel 上重放;
|
||
- 比较 stdout/result hash;
|
||
- 输出 divergence 报告。
|
||
- v2 可选;至少保留 journal 以便未来实现。
|
||
|
||
---
|
||
|
||
## 7. 输出与文档
|
||
|
||
### 7.1 默认
|
||
|
||
- View cells 输出只在 view 中显示;不写 `.mq.md`。
|
||
- 关闭/刷新后可通过 journal 恢复最近结果(若 session 持久化)。
|
||
- 不写 execution_count 到文档。
|
||
|
||
### 7.2 显式 writeback
|
||
|
||
- 复用 `lib/writeback` 的 `<!-- marqdo-out … -->`。
|
||
- cell 输出锚点:cell 名 + 行号;写入位置在围栏之后,或文档末尾的“输出”区。
|
||
- 可选:
|
||
- 单 cell 写回;
|
||
- 全部写回;
|
||
- 只写回文本/数值,不写复杂对象。
|
||
- Git 友好:输出是普通 Markdown 注释块;可 diff、可忽略。
|
||
|
||
### 7.3 不写回
|
||
|
||
- 避免 Jupyter 的 `.ipynb` 输出噪声。
|
||
- 需要分享结果时,导出 HTML / 静态 view,而不是改源文件。
|
||
|
||
---
|
||
|
||
## 8. View 交互
|
||
|
||
### 8.1 工具栏
|
||
|
||
```text
|
||
[Run All] [Restart & Run All] [Step Cell] [Step Statement]
|
||
Kernel: [分析 ▾] Status: ready [Restart] [Interrupt]
|
||
[State] [Journal] [Writeback ▾]
|
||
```
|
||
|
||
### 8.2 每个 code card
|
||
|
||
```text
|
||
`加载` python · kernel 分析 · run #3 · 42ms · clean
|
||
[Run] [Step] [Kernel ▾] [State] [Copy output]
|
||
```
|
||
|
||
- 状态徽标:`never` / `clean` / `dirty` / `stale` / `error` / `running` / `unlisted`。
|
||
- 输出区:stdout / stderr / result / 截断提示。
|
||
- 内核下拉:切换归属;不迁移状态;提示需要重跑。
|
||
- `Step` = 执行此 cell(cell step)。
|
||
|
||
### 8.3 状态面板
|
||
|
||
- Marqdo / kernel 分栏。
|
||
- Push/Pull。
|
||
- Secret 打码。
|
||
- 大对象摘要 + 复制 JSON。
|
||
|
||
### 8.4 Journal 面板
|
||
|
||
- 表格:seq / cell / kernel / ok / ms / 时间 / 错误。
|
||
- 点击跳转 cell。
|
||
- 导出 JSON。
|
||
|
||
### 8.5 键盘
|
||
|
||
- `Ctrl/Cmd + Enter`:Run cell。
|
||
- `Shift + Enter`:Run cell + 下一个。
|
||
- `Alt + Enter`:Run cell + 插入?不做。
|
||
- `F10`:Step statement(与 debug 一致)。
|
||
- `F5`:Run All。
|
||
|
||
---
|
||
|
||
## 9. 服务端 API
|
||
|
||
所有 API 以文档相对路径 + session id 定位;session 内存驻留,进程退出即失。
|
||
|
||
| 方法 | 路径 | 作用 |
|
||
|---|---|---|
|
||
| POST | `/api/session/open` | 打开文档会话,返回 cells / kernels / journal |
|
||
| POST | `/api/session/close` | 关闭会话,kill 所有 kernel |
|
||
| POST | `/api/session/reload` | 重新解析文档,保留 kernel(标记 dirty) |
|
||
| POST | `/api/session/cell/run` | 执行指定 cell |
|
||
| POST | `/api/session/cell/step` | 执行下一个 cell |
|
||
| POST | `/api/session/run_all` | 按会话顺序执行;`restart` 可选 |
|
||
| POST | `/api/session/kernel/restart` | 重启指定 kernel |
|
||
| POST | `/api/session/kernel/interrupt` | 中断当前 cell |
|
||
| POST | `/api/session/kernel/assign` | 改 cell 的 kernel 归属(会话内) |
|
||
| POST | `/api/session/state/list` | Marqdo / kernel 变量列表 |
|
||
| POST | `/api/session/state/push` | Marqdo 值 → kernel |
|
||
| POST | `/api/session/state/pull` | kernel 变量 → value store |
|
||
| POST | `/api/debug/*` + `/debug` | Marqdo 语句单步(Debug 按钮,复用 debugger) |
|
||
| POST | `/api/session/writeback` | 显式写回 cell 输出 |
|
||
| POST | `/api/session/journal` | 执行日志 |
|
||
| GET | `/api/session` | 当前会话摘要 |
|
||
|
||
响应统一:`{ok, session, ...}`;错误 `{ok:false, error, code?}`。
|
||
|
||
---
|
||
|
||
## 10. 生命周期与持久化
|
||
|
||
- Session key:`<root>/<doc_rel>`;每个文档一个。
|
||
- 打开:解析、建 cell index、按需启动 kernel。
|
||
- 空闲超时:默认 30 分钟关闭(可配置)。
|
||
- 文档关闭 / 服务退出:kill 所有 kernel。
|
||
- 文件变更:view 刷新时 `reload`;cell hash 变化 → dirty;kernel 保留。
|
||
- 持久化(可选):
|
||
- `.marqdo/sessions/<doc-hash>.json`:kernel 名称/语言、cell 归属、journal、value store 摘要;
|
||
- 默认 git 忽略;
|
||
- 不持久化进程状态 / 大对象。
|
||
- 不把 session 状态写进 `.mq.md`。
|
||
|
||
---
|
||
|
||
## 11. 安全
|
||
|
||
| 项 | 策略 |
|
||
|---|---|
|
||
| exec | 所有 kernel 启动/执行检查 `allow_exec`;沙箱拒绝 |
|
||
| 生命周期 | 每文档;关闭/drop kill;不跨文档 |
|
||
| cwd | 文档目录 / `fs_root`;越界拒绝 |
|
||
| 输出 | 有界;截断标记 |
|
||
| 超时 | cell 级;进程组 kill |
|
||
| 中断 | 杀进程组;kernel 标记 dead |
|
||
| Secret | 状态面板打码;JSON 不默认暴露 |
|
||
| 未信任文档 | 不自动打开会话;必须显式 Run |
|
||
| 并发 | 同 kernel 串行;不同 kernel 上限 32 |
|
||
| writeback | 显式;路径沙箱;不自动改文档 |
|
||
|
||
---
|
||
|
||
## 12. 测试
|
||
|
||
### 12.1 服务端
|
||
|
||
- cell index:绑定名/行号/lang/source hash;未绑定围栏排除。
|
||
- 会话解析:foreign.session 句柄/自动模式/重复/未知/语言不匹配。
|
||
- 会话:open/close/reload;kernel 启动/重启/中断。
|
||
- cell run:状态机 never→running→clean/error;dirty/stale。
|
||
- step:cell step 顺序;statement step 与 debug 联动。
|
||
- state:push/pull/list;Secret 打码;大对象摘要。
|
||
- journal:顺序、hash、失败。
|
||
- 并发:同 kernel 串行;不同 kernel 并行。
|
||
- 安全:exec=false 拒绝;cwd 越界;超时。
|
||
|
||
### 12.2 金样例
|
||
|
||
- `tests/notebook/kernels.mq.md`:foreign.session 句柄。
|
||
- `tests/notebook/shared-state.mq.md`:两个 Python cell 共享 `x`。
|
||
- `tests/notebook/step.mq.md`:cell step 顺序。
|
||
- `tests/notebook/state-bridge.mq.md`:Marqdo ↔ Python 推拉。
|
||
- `tests/notebook/invalid-*.mq.md`:诊断。
|
||
- 依赖:node 为主,python 条件跳过。
|
||
|
||
### 12.3 UI
|
||
|
||
- 手工冒烟:Run cell / Step / Run All / Restart / State Push/Pull / Journal。
|
||
- 不引入前端测试框架;用服务端 API + 静态检查。
|
||
|
||
---
|
||
|
||
## 13. 与 Jupyter 对照
|
||
|
||
| 维度 | Jupyter | Document Session |
|
||
|---|---|---|
|
||
| 源 | `.ipynb` | `.mq.md` |
|
||
| 执行顺序 | 隐藏的 `In[n]` | 会话表 / 文档顺序 / journal |
|
||
| 状态 | 隐藏 kernel | kernel + value store + 状态面板 |
|
||
| 多语言 | 一文档一 kernel | 命名内核 + 每 cell 归属 |
|
||
| 单步 | cell | cell + statement |
|
||
| 复现 | 手动 | Restart & Run All + journal + replay |
|
||
| Git | 输出/计数噪声 | 源码干净;输出显式 |
|
||
| 知识 | 无 | OKF / catalog |
|
||
| 调试 | 语言 pdb | Marqdo 断点 + cell 级;行级后续 |
|
||
|
||
---
|
||
|
||
## 14. 实现顺序(D 层)
|
||
|
||
| 阶段 | 内容 |
|
||
|---|---|
|
||
| D0 | 设计/语法/决策文档(本文件) |
|
||
| D1 | `src/host/foreign_doc.rs`:cell index、foreign.session 句柄、session 结构、诊断 |
|
||
| D2 | 服务端 API:open/close/cell run/step/run_all/restart/interrupt |
|
||
| D3 | view UI:工具栏、cell 徽标、kernel 下拉、状态面板、journal |
|
||
| D4 | statement step 接入;dirty/stale;writeback |
|
||
| D5 | replay / 持久化 / 并发优化 / 测试补全 |
|
||
|
||
依赖 F 层:F3 持久内核、F3.5 状态桥先完成,D2 才能工作。
|
||
|
||
---
|
||
|
||
## 15. 明确不做(v2)
|
||
|
||
- Foreign line-level step。
|
||
- 自动镜像变量。
|
||
- 跨文档共享 kernel。
|
||
- 全进程快照。
|
||
- 自动执行 cell。
|
||
- 把 session 状态写进 `.mq.md`。
|
||
- 前端 SPA 框架重写;沿用现有 HTML/JS。
|