Files
marqdo/doc/roadmap/notebook-session.md
cflmy 0f2c12b636 feat(notebook): link statement debugger from view
Expose /debug and /api/debug/* on the live view server; add a notebook Debug button so Marqdo statement stepping is reachable from the same page/session as cell stepping.
2026-10-18 01:44:05 +08:00

178 lines
6.0 KiB
Markdown
Raw Permalink 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.
# 文档会话路线图(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。
- 测试绿;文档更新;提交推送。