- 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。
178 lines
6.0 KiB
Markdown
Executable File
178 lines
6.0 KiB
Markdown
Executable File
# 文档会话路线图(D0–D5)
|
||
|
||
| | |
|
||
|---|---|
|
||
| 状态 | **D1–D3 已落地(首版);D4–D5 待做** |
|
||
| 日期 | 2026-10-17 |
|
||
| 层 | Runtime + Document(view 服务端 / 前端) |
|
||
| 相关 | [notebook-session.md](../design/notebook-session.md) · [notebook-syntax.md](../design/notebook-syntax.md) · [foreign-kernel.md](../design/foreign-kernel.md) · [foreign-v2.md](foreign-v2.md) · [foreign-notebook-decisions.md](../research/foreign-notebook-decisions.md) |
|
||
| 核心表面 Δ | 无 |
|
||
|
||
> F 层让“外部语言能持久运行”;D 层让“文档里的多个 cell 像 notebook 一样共享状态、单步、切换内核”。两层分开验收。
|
||
|
||
---
|
||
|
||
## 0. 依赖
|
||
|
||
- **F3**:Python / Node 持久内核。
|
||
- **F3.5**:`session_set/get/names`。
|
||
- 现有 `DebugController`(Marqdo 语句单步)。
|
||
- 现有 `writeback` / `annot` / view 结构。
|
||
|
||
没有 F3/F3.5,D2 只能做一次性 Run,不是共享状态。
|
||
|
||
---
|
||
|
||
## 1. 阶段总览
|
||
|
||
| 阶段 | 内容 | 估算 |
|
||
|---|---|---|
|
||
| **D0** | 设计/语法/决策文档 | 已完成 |
|
||
| **D1** | `src/notebook/`:cell index、表解析、session 结构、诊断 | 2–3 天 |
|
||
| **D2** | 服务端 API:open/close/cell run/step/run_all/restart/interrupt | 3–4 天 |
|
||
| **D3** | view UI:工具栏、cell 徽标、kernel 下拉、状态面板、journal | 3–4 天 |
|
||
| **D4** | statement step、dirty/stale、writeback | 2–3 天 |
|
||
| **D5** | replay、持久化、并发优化、测试补全、发布 | 2–3 天 |
|
||
|
||
---
|
||
|
||
## 2. D1 — Cell index 与表解析
|
||
|
||
### 内容
|
||
|
||
- 新模块 `src/notebook/`:
|
||
- `cell.rs`:从 AST 提取绑定名代码围栏;id/name/lang/line/source hash。
|
||
- `syntax.rs`:读取 `内核表` / `会话表`;中英列名。
|
||
- `session.rs`:`DocumentSession` 结构、kernel registry、value store、journal。
|
||
- `diag.rs`:重复/未知/语言不匹配/未入会话诊断。
|
||
- 自动模式:无表 → 文档顺序 + 默认内核。
|
||
- 解析器不改;只遍历 `Module.functions` + `Stmt::Assign { value: Expr::Code }`。
|
||
- 测试:单元 + `tests/notebook/*.mq.md`。
|
||
|
||
### 验收
|
||
|
||
- 两个 Python cell + 一个会话表 → cells 顺序、kernel 归属正确。
|
||
- 无表 → 自动顺序。
|
||
- 未知内核/未知单元/重复/语言不匹配 → 可读诊断。
|
||
- 未绑定围栏不进入 cell index。
|
||
|
||
---
|
||
|
||
## 3. D2 — 服务端 API
|
||
|
||
### 内容
|
||
|
||
- `src/view/notebook_api.rs`(或 `view/session_api.rs`):
|
||
- open / close / reload
|
||
- cell run / step / run_all
|
||
- kernel restart / interrupt / assign
|
||
- state list / push / pull
|
||
- journal
|
||
- Session 存储:`OnceLock<Mutex<HashMap<String, Arc<DocumentSession>>>>`(类似 debug sessions)。
|
||
- 每个文档一个 session;key = 相对路径。
|
||
- 执行线程:cell 执行不阻塞 HTTP;响应返回记录;SSE/EventBus 可选。
|
||
- 错误统一 JSON。
|
||
|
||
### 验收
|
||
|
||
- open 返回 cells/kernels/journal。
|
||
- cell run:never→running→clean/error;状态更新。
|
||
- step:按会话顺序执行下一个。
|
||
- run_all:按顺序;restart 选项。
|
||
- 同 kernel 串行;不同 kernel 可并行。
|
||
- close/drop kill 所有 kernel。
|
||
- API 单测/集成测试。
|
||
|
||
---
|
||
|
||
## 4. D3 — View UI
|
||
|
||
### 内容
|
||
|
||
- 工具栏:Run All / Restart & Run All / Step Cell / Step Statement / Kernel 状态 / Restart / Interrupt / State / Journal。
|
||
- Code card:
|
||
- 状态徽标(never/clean/dirty/stale/error/running/unlisted)
|
||
- kernel 下拉
|
||
- Run / Step
|
||
- 输出区(stdout/stderr/result/truncated)
|
||
- 执行序号 / 耗时
|
||
- 状态面板:
|
||
- Marqdo 值 / kernel 变量分栏
|
||
- Push / Pull / Refresh
|
||
- Secret 打码、大对象摘要
|
||
- Journal 面板:表格 + 跳转 + 导出。
|
||
- 键盘:Ctrl/Cmd+Enter、Shift+Enter、F5、F10。
|
||
- 静态导出的 Run 仍隐藏。
|
||
|
||
### 验收
|
||
|
||
- 手工冒烟:两个 Python cell 共享 `x`;切换 kernel 后隔离;Restart 清状态。
|
||
- 状态面板 Push/Pull。
|
||
- 错误 cell 红色徽标 + stderr。
|
||
- 页面刷新后 session 仍在(服务端内存)。
|
||
|
||
---
|
||
|
||
## 5. D4 — Statement step / dirty / writeback
|
||
|
||
### 内容
|
||
|
||
- Statement step:复用 `DebugController`,与 DocumentSession 关联;暂停点显示变量。
|
||
- dirty:reload 后 source hash 变化。
|
||
- stale:按会话顺序,上游变更 → 下游 stale(v2 近似)。
|
||
- writeback:单 cell / 全部;`<!-- marqdo-out -->`;不自动。
|
||
- 运行历史 / 执行序号。
|
||
|
||
### 验收
|
||
|
||
- Statement step 在 view 中可用;外联调用原子完成。
|
||
- 编辑 cell → dirty;Run All 后 clean。
|
||
- 上游变更 → 下游 stale。
|
||
- 显式 writeback 写入文档;不自动改文件。
|
||
|
||
---
|
||
|
||
## 6. D5 — Replay / 持久化 / 发布
|
||
|
||
### 内容
|
||
|
||
- Journal replay:新 kernel,按 journal 顺序/输入 hash 重放;比较 stdout/result hash;divergence 报告。
|
||
- 可选持久化 `.marqdo/sessions/<doc-hash>.json`(kernel/cell 归属/journal/value store 摘要;默认 git 忽略)。
|
||
- 并发优化:不同 kernel 并行;同 kernel 串行。
|
||
- 测试补全;文档;catalog;CHANGELOG。
|
||
- 版本:D 层随 1.5.x。
|
||
|
||
### 验收
|
||
|
||
- Replay 能复现 clean 会话;dirty 输入给出 divergence。
|
||
- 关闭/重启服务无进程泄漏。
|
||
- 文档完整;金样例绿。
|
||
|
||
---
|
||
|
||
## 7. 测试矩阵
|
||
|
||
| 测试 | 断言 |
|
||
|---|---|
|
||
| `notebook/kernels.mq.md` | 内核表/会话表解析 |
|
||
| `notebook/auto-session.mq.md` | 无表自动顺序 |
|
||
| `notebook/shared-state.mq.md` | 同 kernel 共享变量 |
|
||
| `notebook/isolated-kernels.mq.md` | 不同 kernel 隔离 |
|
||
| `notebook/step.mq.md` | cell step 顺序 |
|
||
| `notebook/state-bridge.mq.md` | Marqdo ↔ kernel 推拉 |
|
||
| `notebook/dirty.mq.md` | 编辑 → dirty/stale |
|
||
| `notebook/invalid-*.mq.md` | 诊断 |
|
||
| API 集成 | open/run/step/run_all/restart/interrupt/close |
|
||
| 安全 | exec=false、cwd 越界、超时、Secret 打码 |
|
||
|
||
依赖 node 为主;python 条件跳过。
|
||
|
||
---
|
||
|
||
## 8. 完成定义
|
||
|
||
- D1–D4 验收;D5 可选(replay/持久化)。
|
||
- 文档会话与 F 层联调通过。
|
||
- 手工 view 冒烟:共享状态 / 单步 / 切换 / 状态面板 / journal。
|
||
- 测试绿;文档更新;提交推送。
|