# dsh-notebook-v2 体验修复 v6 —— 计划（待独立评审）

> 用户反馈（2026-11-04，第 6 轮真机）：md 渲染不对 / 打开要手输工作目录 / Shift-Enter 不自动运行 /
> cell 之间没有新增按钮 / 其他同类问题 / 大纲要像 VS Code（md 各级标题 + 函数定义）。
> 附加要求：广泛参考现成 Jupyter 软件，并论证「为什么不直接把 VS Code 的 Jupyter 插件搬过来」。

---

## 0. 结论先行：六条反馈 → 根因 → 修法

| # | 用户原话 | 实测根因（已核实，不是猜） | 修法 |
|---|---|---|---|
| 1 | md 渲染有问题，没有常规 md 渲染 | ① markdown 是**手写正则渲染器** `markdownLite`（client.js:528）：无嵌套列表、无任务列表、无 `---`、无内联 HTML、无硬换行；标题字号 `20 - level*2` → h1=18px、**h6=8px**（几乎看不见）。② **KaTeX 只有 JS 没有 CSS**：`grep katex.min.css lib/cm-vendor.js lib/client.js` = 0 命中 → 所有公式必然错版（无字体、无间距）。③ 表格对齐标记、围栏语言、图片相对路径全部没处理。 | 引入成熟渲染器 `marked`（MIT，原生 GFM：表格/任务列表/删除线/自动链接/嵌套列表）+ `dompurify` 消毒 + **KaTeX CSS 与字体**打进 vendor；新增 `renderMarkdown(src)` → sanitize 后 HTML；`nb2-md` 作用域样式表（对齐 GitHub/Jupyter 视觉）；相对路径图片走新端点 `/nb2/file`。`markdownLite` 保留为 vendor 缺失时兜底。 |
| 2 | 打开应直接看工作区里的 notebook，却要我输工作目录 | `workspaceRoot()`（index.js:104）取 `ctx.get("sandboxPolicy").workspaceRoot`，拿不到就回落 `process.cwd()`。**实测运行中进程的默认 cwd = `C:\Users\ASUS\.dsh\profiles\desktop`**（不是工作区）。而「打开」只有一个绝对路径输入框，没有浏览能力。 | ① 默认目录改成**会话自己的工作目录**：`ctx.agents.get(sid)` → `ctx.workingDirectory.get(agent.session)`，退 `workingDirectory.defaultDirectory`，再退 `sandboxPolicy.workspaceRoot`。② 新端点 `GET /nb2/notebooks?sid&dir&depth` 递归列举 `.ipynb`（跳过 `.git/node_modules/.venv/__pycache__` 等，深度≤4，上限 500 条）。③ 「＋打开」改为 **picker**：搜索框 + 相对路径/修改时间/大小列表 + ↑↓ Enter + 「手输路径…」兜底。 |
| 3 | 左 shift+enter 没有自动运行 | 三处独立缺口：**a)** `CellView.onKeyDown` 在 `if (h2.inControl) return` 处提前返回 —— 焦点落在格内任意按钮/下拉（点过 ▶ 就会）后，所有 Enter 组合键全死；**b)** 焦点在面板空白/标签条/cell 列表（无编辑器、无容器）时**根本没有任何处理器**接收事件；**c)** 最后一格 Shift-Enter 不会像 VS Code 那样自动补一个新格，用户感觉「按了没反应」。 | ① 面板根节点加 **capture 阶段 keydown**，统一分发 `Shift/Ctrl/Alt/CtrlShift-Enter`；命中 `.cm-editor` 或文本输入框才放行给下层。② `CellView` 的 Enter 组合判断提到 `inControl` 之前。③ 运行后 select-below 并**聚焦下一格编辑器**；最后一格则新建一格再聚焦。④ 补 VS Code 的 `Ctrl-Shift-Enter`（上方插入并运行）。 |
| 4 | cell 下方 / cell 之间有没有新增按钮 | 只有顶部工具栏的 `＋ 代码 / ＋ MD / ＋ SH`，且**只追加到末尾**；没有「在某格之后插入」的可见入口。 | 新增 `CellDivider`：每个 cell 之前、之后、列表末尾都有，hover/选中态显示 `＋ 代码` `＋ 文本`；点击 = 在该处插入并**自动聚焦新格编辑器**。 |
| 5 | 其他同类问题 | 见 §2 排查清单（10 条，已逐条定位） | 逐条修（表格里标 P0/P1/不做） |
| 6 | 大纲要像 VS Code：`#`/`##`/`###` + 函数定义 | `buildOutline`（client.js:160）只做 markdown `#` 标题 + 每格首行，**没有任何代码符号**；UI 是扁平列表，不可折叠、无过滤、点击不聚焦。 | ① 代码符号用 **`@lezer/python`**（已随 `@codemirror/lang-python` 打进 vendor，**零额外体积**）解析出 `FunctionDefinition` / `ClassDefinition`（实测可取到 name 与位置），按缩进建树、带行号。② markdown 支持 ATX + setext，跳过围栏。③ UI：可折叠树 + 过滤框 + 当前格高亮 + 点击跳转并聚焦 + 记住展开态。④ 纯函数 + 单测。 |

---

## 1. 「为什么不直接把 VS Code 的 Jupyter 插件搬过来」

这是本轮最值得先讲清楚的一条，因为它决定后面所有取舍。

### 1.1 为什么搬不动（不是不想）

| vscode-jupyter 的层 | 依赖 | 能否搬 |
|---|---|---|
| 扩展激活 / 命令 / 状态栏 | VS Code **extension host** + `vscode` 模块 | ❌ 没有扩展宿主 |
| cell 交互、焦点、工具栏、虚拟滚动 | VS Code **Notebook API**（`vscode.NotebookCellData`、`NotebookCellList`、`CellFocusMode`、`INotebookExecutionStateService`） | ❌ 这是 VS Code workbench 内部实现，不是插件代码 |
| 编辑器 | **Monaco**（`CodeCell.setModel`、编辑器池、`CodeCellRenderer.renderTemplate`） | ❌ 我们用的是 CM6（且 Monaco 101MB + worker，见既有决策） |
| 输出渲染 | `vscode-notebook-renderer` API + **webview** 隔离 | ❌ 需要 VS Code 的 renderer 通信层 |
| 内核协议 | `jupyterlab/services`-style 纯 TS + `nbformat` | ✅ **我们已经等价拥有**（sidecar 走 jupyter_client 的 Jupyter messaging） |
| 输出 MIME 处理 / nbformat 归一 | 纯 TS 逻辑（`src/kernels/execution/helpers.ts`） | ✅ 语义已抄（`translateStreamOutput` → 我们的 stream 合并、`raises-exception` 继续） |

**一句话**：vscode-jupyter 里「用户看得见的那 80%」是 VS Code 平台代码（workbench + Monaco + webview renderer），插件本体是接线员。搬插件 = 搬一具没有骨架的身体。

### 1.2 真正该复用的三样东西（本轮就用）

1. **协议层**：已经是标准 Jupyter messaging（不发愁）。
2. **渲染层**：`marked` + `dompurify` + `katex`（JupyterLab 的 rendermime 其实也是这条链路的同族：`markdown-it` + `DOMPurify` + KaTeX，只是它绑 `@lumino/*`）。
3. **符号层**：VS Code 的 Outline 来自 LSP `documentSymbol`；我们没有 LSP，但 `@lezer/python` 是货真价实的 Python 语法树，**已经在包里**，比正则准、比 LSP 轻。

### 1.3 为什么不引 JupyterLab 的 rendermime
`@jupyterlab/rendermime` 与其 markdown 渲染器依赖 `@lumino/widgets` / `@jupyterlab/apputils` 的 DI 容器，
塞进 DSH 客户端插件（只能 `require` 白名单模块）需要连带一套 Lumino widget 生命周期；而它内部用的就是
`markdown-it` + `DOMPurify` + `katex`。**直接用它依赖的那三件，比搬它自己便宜一个数量级。**

### 1.4 边界（明确不做）
ipywidgets（`jupyter-js-widgets` 需要 comm + 前端模型，独立工程）、调试器、Monaco、LSP 级类型诊断。

---

## 2. 「其他同类问题」排查清单（已定位，逐条处置）

| # | 问题 | 定位 | 处置 |
|---|---|---|---|
| 5.1 | 新增 cell 后**不聚焦**，用户得再点一下才能打字 | `addCell` 只 `setSelected`（client.js:2458） | **P0** 新增 `focusReq` 机制：插入后聚焦该格编辑器 |
| 5.2 | 工具栏行 2 挤了 11 个按钮，`＋代码/＋MD/＋SH` 语义与分隔线按钮重复 | client.js:3254-3306 | **P0** 分组 + 溢出到 `⋯`；分隔线按钮保留（它是「末尾追加」的语义） |
| 5.3 | 大纲点击只 `setSelected` + 滚动，**不聚焦** | client.js:3488-3495 | **P0** 跳转后聚焦该格（markdown 则滚动到位） |
| 5.4 | 空 notebook 空态只有一个「新建一格」 | client.js:3536-3543 | **P0** 空态给 `＋ 代码` / `＋ Markdown` 两个大按钮 |
| 5.5 | `.cm-scroller { maxHeight: 60vh }` 可能在长 cell 里产生**双滚动条** | client.js:1056 | **P1** 改为不限制高度（外层列表已滚动），仅在超长时才限 |
| 5.6 | 输出区没有「复制」按钮（只能拖选） | `OutputBlockView` | **P1** hover 显示 ⧉ 复制（纯文本输出） |
| 5.7 | markdown 渲染区点击进编辑后光标位置不稳定 | `enterEdit` + `setTimeout(0)` | **P1** 进编辑后把光标放到点击行（粗略按 offsetY 估算） |
| 5.8 | 「内核 unknown」时无解释 | 行 3 状态 | **P1** 文案改为「内核未启动（点运行即启动）」 |
| 5.9 | `window.prompt/confirm/alert` 禁用扫描 | 已有测试 | **保持绿**（新增代码不得引入） |
| 5.10 | markdown cell 的 `完成` 按钮 / 双击进编辑两套入口不一致 | client.js:2175 | **P1** 统一：渲染区单击进编辑、双击也进、Esc 退出 |

---

## 3. 文件改动清单（预估）

### 宿主半 `lib/index.js`（+~180 行）
- `defaultCwdFor(sid)`：`agents.get(sid)` → `workingDirectory.get(agent.session)` → `workingDirectory.defaultDirectory` → `sandboxPolicy.workspaceRoot` → `process.cwd()`；**替换现有 `workspaceRoot()` 的三处调用点（263/516/657/951）**，并保留 `workspaceRoot()` 作为最后兜底。
- 新路由 `notebooks/list`：`{ sid, dir?, depth? }` → `{ root, cwd, entries:[{path, rel, mtime, size}] }`；`node:fs` 递归，跳过黑名单目录，上限 500。
- 新路由 `file`：`{ base, path }`（base = notebook 所在目录）→ 只允许读 `base` 子树内的**图片/文本**（png/jpg/gif/webp/svg），带 `mime` 与 `Cache-Control`；防目录穿越（`resolve` 后必须 `startsWith(base + sep)`）。
- `katex.css` 路由：与 `vendor.js` 同款，提供 `lib/katex.css`。

### 客户端 `lib/client.js`（+~700 行 / 改 ~150 行）
- 新增：`renderMarkdown()` / `ensureKatexCss()` / `nb2MdCss` / `NotebookPicker` / `CellDivider` / `MarkdownView` / `panelKeydown` 分发器 / `buildOutlineV2`。
- 改：`buildOutline`（→ 树 + 符号）、`CellView`（keydown 顺序、hover 工具栏、聚焦 request）、`addCell`（聚焦）、打开入口、工具栏分组、空态。

### 构建 `scripts/build-cm-vendor.mjs` + `scripts/cm-entry.js`
- `cm-entry.js` 增：`export { marked } from "marked"`、`export { default as DOMPurify } from "dompurify"`、`export { parser as pythonParser } from "@lezer/python"`。
- 新脚本步骤：生成 `lib/katex.css`（`katex.min.css` + 20 个 woff2 内联为 base64；预估 23KB + 348KB ≈ 371KB）。
- 依赖：优先把 `marked`/`dompurify` **显式写进 `<profile>/.nb2-build/package.json` 并 `npm i`**（可复现）；装不上则退回从 profile `node_modules` 解析（构建期依赖，产物已提交进仓库，运行时零依赖）。

### 测试
- `test/outline.mjs`（新）：Lezer 符号抽取（函数/类/嵌套/async/decorator/语法错误容错）、markdown 标题（ATX/setext/围栏跳过）、树结构。
- `test/markdown.mjs`（新）：`marked` 渲染快照（表格/任务列表/嵌套列表/围栏/代码高亮钩子）、`DOMPurify` 必须清掉 `<script>`/`onerror`、相对图片改写。

> ⚠️ 注意：`marked`/`DOMPurify` 在**客户端包**里，纯函数测试需要一个能加载 vendor 的壳。
> 方案：把 markdown 渲染拆成「纯文本 → HTML 字符串」的 `lib/md.js`（宿主侧可 import，纯 ESM，无 DOM 依赖，
> 消毒通过 `DOMPurify` 的 jsdom 替身或在测试里用 stub），客户端 `require` 不到时用 vendor 的。
> **待评审确认这条拆分是否值得**（否则 markdown 测试只能跳过）。
- `test/client-logic.mjs` +：`panelKeydown` 分发矩阵（编辑器中放行 / 按钮上仍触发 / 输入框放行 / 最后一格补新格）。
- `test/smoke-client.mjs` +：静态树断言 `＋ 代码` / `＋ 文本` / picker / 大纲过滤框存在。
- `test/smoke.mjs` +：`notebooks/list` 真 HTTP（临时目录造 3 个 .ipynb）、`file` 目录穿越必须 403/404。

---

## 4. 风险与回滚

| 风险 | 缓解 |
|---|---|
| vendor 增大（现 721KB → 预估 ~760KB + katex.css 371KB） | katex.css 独立文件、按需 `<link>`；vendor 只在打开 notebook 面板时加载 |
| `marked` 依赖 better-sidebar 的传递依赖 | 显式装进 `.nb2-build`；构建脚本缺依赖时**明确报错**而不是产出半成品 |
| 安全性：渲染原始 HTML | 全部过 `DOMPurify`（禁 `script/iframe/on*`），图片端点限制在 notebook 目录子树 |
| 按键抢占宿主快捷键 | 面板级 keydown 只处理 **Enter 组合**；命中 `.cm-editor` / `input` / `textarea` / `select` 一律放行 |
| 宿主半不热加载 | 改完必须重启桌面版；客户端半刷新页面即可（既有结论） |
| 回滚 | 全部改动在 `dsh-notebook-v2`；`scripts/uninstall.mjs` 一条命令摘除；`.ipynb` 数据不动 |

---

## 5. 实施顺序（每步可独立验证）

1. **P0-A 宿主**：`defaultCwdFor` + `notebooks/list` + `file` + `katex.css` 路由 → `test/smoke.mjs` 过半。
2. **P0-B 构建**：vendor 加 marked/dompurify/lezer-parser + 生成 katex.css → 体积与加载验证。
3. **P0-C 渲染**：`renderMarkdown` + `nb2-md` 样式 + 图片改写 + 兜底 → `test/markdown.mjs`。
4. **P0-D 打开**：picker UI 接 `notebooks/list`。
5. **P0-E 键盘**：面板级分发器 + CellView 顺序 + 聚焦下一格 + 最后一格补格 → `client-logic` 矩阵。
6. **P0-F 增格**：`CellDivider` + 插入后聚焦。
7. **P0-G 大纲**：Lezer 符号 + 树 UI + 过滤 + 跳转聚焦 → `test/outline.mjs`。
8. **P1 清单**：§2 的 5.5–5.8、5.10。
9. **收尾**：`test/all.mjs` 全绿 → 请用户重启桌面版 → `/nb2/health` 确认新码 → 真机点验。

---

## 6. 明确不做
ipywidgets、调试器、Monaco/LSP、拖拽重排 cell、多窗口分离、Notebook diff。

---

## 7. 事实核查与原型证据（2026-11-04 本条线亲自实测，不是推断）

| # | 计划里的假设 | 实测结果 | 对计划的影响 |
|---|---|---|---|
| 7.1 | 需要 `npm i marked/dompurify` | **不需要联网**：`~/.dsh/profiles/desktop/.nb2-build/node_modules` 已有 `marked@18.1.3`、`dompurify@3.4.17`、`katex@0.16.11`、`marked-katex-extension`；profile 的 `node_modules` 里也有一份，且 `@lezer/python` 可解析 | 构建脚本按「.nb2-build 优先 → profile 兜底」解析，缺依赖必须硬失败 |
| 7.2 | KaTeX 只有 JS 没有 CSS | 确认：`grep -c 'katex.min.css\|@font-face' lib/cm-vendor.js lib/client.js` = **0 / 0**；但 `renderToString` 已在 vendor 里（katex JS 早打进去了） | 只缺 CSS + 字体。`katex.min.css` 23,335B；woff2 20 个、254KB → base64 约 348KB |
| 7.3 | md 与公式要两套处理 | 实测 `marked.use(markedKatexExtension({throwOnError:false}))` 一次产出 `<table>`、`<input type=checkbox>`、`<span class=katex>` | 一个 marked 实例同时解决 GFM + 数学，**不再自己写 `$$` 正则** |
| 7.4 | Lezer 能取到函数/类 | 确认。`iterate({enter})` 给出 `FunctionDefinition`/`ClassDefinition`/`VariableName`；`FunctionDefinition@21-76` 的 span **含函数体**，函数名要取该节点内**第一个 `VariableName` 子节点**；嵌套 `def`、`async def` 都是独立节点（正好建树） | 大纲按「节点 span 起点所在行」排序，名字取子节点，async 靠节点文本前缀判断 |
| 7.5 | 默认目录取 `agents.get(sid)` → `workingDirectory.get(agent.session)` | 宿主服务签名核对无误：`workingDirectory.get(session: Session): string`、`readonly defaultDirectory: string`、`agents.get(id: SessionId): Agent \| undefined` 全存在 | 取法可行；另发现 `directoryPickerController` 有 `@Remote list(path)/pick()`，留作后续增强，本轮不依赖 |
| 7.6 | 把 markdown 拆到 `lib/md.js`（原 §3 的测试建议） | **作废**：`lib/client.js` 是 `__ModuleLoader__.load({id, factory})` 的自包含 CJS 工厂，**不能 import 兄弟文件**；测试壳（`test/client-logic.mjs`）用 React 桩加载它 | md/outline 纯逻辑**内联在 client.js**，经 `__internals` 暴露；测试用 `CM` 桩注入 marked/lezer。**不新增 `lib/md.js`** |
| 7.7 | 基线是否健康 | `node test/all.mjs` **全绿**（28 个 `nb_*` 工具、多标签、执行/中断/重启、变量留存、语义等价读写） | 改动必须保持这套绿 |
| 7.8 | 改完怎么生效 | `/nb2/health` → `{ok:true, version:"0.1.0"}`；profile 的 `node_modules/dsh-notebook-v2` 是**指向本仓库的 symlink** | 宿主半：`plugin_manager set_plugin` 重挂即生效；客户端半：刷新页面 |

补充实测（原计划没写、但影响实现）：

- 宿主路由是**单条 prefix `/nb2` + 手动分发**：`route = url.pathname.replace(/^\/nb2\/?/, "")`，
  `vendor.js` 在 `readJson` 之前特殊返回，`sid = body.sid || url.searchParams.get("sid") || "default"`。
  新路由就挂在这个 handler 里，不新注册 route。
- `test/_load.mjs` 把 `lib/*.js` **逐个复制**到临时目录再加载 → 新模块若带裸 import（`marked`）会在临时目录解析失败。
  这是 7.6 判定的直接原因，也约束宿主半**不得**在运行时 import third-party 包。

---

## 8. 实施契约（拆工边界，评审请重点挑这里的漏洞）

| 归属 | 写哪些文件 | 内容 |
|---|---|---|
| **host-build** | `lib/index.js`、`scripts/cm-entry.js`、`scripts/build-cm-vendor.mjs`、`lib/katex.css`(生成)、`test/smoke.mjs` | `defaultCwdFor(sid)`；`GET /nb2/notebooks`；`GET /nb2/file`；`GET /nb2/katex.css`；vendor 增 `marked`/`DOMPurify`/`pythonParser` 导出 |
| **client-ui** | `lib/client.js`、`test/client-logic.mjs`、`test/smoke-client.mjs`、`test/markdown.mjs`、`test/outline.mjs` | `renderMarkdown` / `NotebookPicker` / `CellDivider` / `panelKeydown` 分发器 / `buildOutlineV2` / 聚焦机制 / §2 的 P1 清单 |
| **Lead** | `test/all.mjs`、`docs/*`、本计划 | 集成、跑全测、diff 复核、真机验收 |

### 8.1 跨半契约（两边必须严格对齐，评审重点）

```text
vendor：window.CM 新增 3 个符号
  CM.marked        —— marked 实例（已 use markedKatexExtension），可直接 .parse(src)
  CM.DOMPurify     —— 消毒器（.sanitize(html, {...})）
  CM.pythonParser  —— @lezer/python 的 parser（.parse(src) → Tree）
  CM.katex         —— 已在（renderToString）

路由（都在 /nb2 前缀下，GET，query 取参）
  GET /nb2/notebooks?sid=&dir=&depth=   → { ok, root, cwd, dir, entries:[{path, rel, dir, mtime, size}] }
       · dir 缺省 = defaultCwdFor(sid)；只列 .ipynb + 子目录；跳过 .git/node_modules/.venv/__pycache__/.ipynb_checkpoints 等
       · depth 上限 4（默认 2）；entries 上限 500；越出 root 的目录不列
  GET /nb2/file?base=&path=             → 二进制（png/jpg/gif/webp/svg）或文本，Content-Type 按扩展名
       · realpath(base) 与 realpath(path) 都解析后，path 必须仍在 base 子树内，否则 403
  GET /nb2/katex.css                    → text/css（lib/katex.css，字体已 base64 内联）
```

### 8.2 判定口径（避免"改完看不出来"）

- 「md 渲染对了」的判据：表格有 `<table>`、任务列表有 checkbox、`$$` 有 `.katex` 且**字号/间距正常**（CSS 到位）、
  嵌套列表缩进正确、`---` 是分割线、h1–h6 字号是**阶梯**而不是 h6=8px。
- 「打开不用输目录」的判据：点「＋打开」直接看到当前工作区的 .ipynb 列表（含子目录），↑↓ 选中 Enter 打开；
  手输路径降级为兜底入口。
- 「Shift-Enter 自动运行」的判据：焦点在**编辑器 / cell 容器 / 工具栏按钮 / 面板空白**四种位置，Shift-Enter 都能跑；
  跑完焦点落到下一格编辑器；最后一格则自动补一格并聚焦。
- 「增格按钮」的判据：鼠标移到**任意两个 cell 之间**出现 `＋ 代码`/`＋ 文本`，点击插入并聚焦。
- 「大纲像 VS Code」的判据：树形（可折叠）、md 各级标题 + **Python 函数/类定义**（带行号）、有过滤框、点击跳转并聚焦。

### 8.3 验收顺序

1. `node scripts/build-cm-vendor.mjs` 产出 vendor + `lib/katex.css`（体积与符号自检）；
2. `node test/all.mjs` 全绿（含新增 markdown/outline/键盘矩阵/路由测试）；
3. 重挂宿主半 → `curl /nb2/notebooks`、`/nb2/katex.css`、`/nb2/file` 实测；
4. 刷新页面 → 真机点验 §8.2 五条判据。

---

## 9. 独立评审结论与修正（2026-11-04，只读 subagent）

**结论：需改计划后开工（不需重做）。** 方向对，但 7 条阻断项、其中 2 条会造成真故障（1 条安全、1 条测试必红）。

### 9.1 阻断项 → 处置

| # | 评审发现（均有实测证据） | 处置（已采纳） |
|---|---|---|
| B1 | **`/nb2/notebooks` 早被占用**（`index.js:824` 返回 `{ok,tabs,active}`，真机 curl 确认）。新列举路由同名 → 要么 5 处老断言全红，要么死代码 | 新路由改名 **`/nb2/fs/list`**，老路由不动 |
| B2 | **`/nb2/file?base=` 校验恒真**（base 由客户端传 = 客户端自选子树 = 任意本地文件可读）。另实测：裸 `startsWith` 漏 `ws-evil`；`realpath` **不规范化大小写**导致合法路径被误拒 | base **服务端推导**（活动 notebook 目录 → `defaultCwdFor`）；`path.relative` 判定 + win32 大小写折叠；扩展名白名单；svg 加 CSP `sandbox` + `nosniff`；ENOENT→404 |
| B3 | `ipynb.js:215/222` 用裸 `readFile(path)`，以 `process.cwd()`（=profile 目录）解析 → picker 传 rel 必 ENOENT，「另存为」会写进 profile | handler 内 `notebook/open|save|saveAs` 统一 `resolve(defaultCwdFor(sid), path)`；saveAs 禁止落 profile 根 |
| B4 | `sandboxPolicy.workspaceRoot` 实测取不到（否则 cwd 不会是 profile）；全仓从未用过 `ctx.agents` | 一律 `ctx.get(...)` + 逐级 try/catch（服务缺失不抛）；**`/nb2/health` 增 `dirSource`/`dir`**，一条 curl 即可判定 |
| B5 | `test/_load.mjs` 只复制 `.js` → `lib/katex/**` 进不了临时包，CSS 断言必 404 | Lead 已改：`_load.mjs` 递归复制 `lib/katex/`，并给 `makeCtx` 加 `agents`/`workingDirectory` 注入 |
| B6 | Node 无 DOM：`DOMPurify.sanitize === undefined`、未装 jsdom | 测试用**假 sanitize 探针**断言「调用 + 配置正确」；真消毒行为留浏览器手测；**不装 jsdom** |
| B7 | **第 3 条主因定错**：`1983` 先 return，`1985` 的 `inControl` 在编辑态不可达；编辑器内 Shift-Enter 由 `client.js:1022` 的 CM keymap 正常处理 | 主因改写为：**`onRunBelow` 只 `runCell`+`setSelected` 不聚焦下一格**（3579-3583）+ **面板根节点零 handler**；`inControl` 降为「点过 ▶ 就没反应」的次要缺陷 |

### 9.2 采纳的建议改

- **katex 字体不全量 base64**：`katex.min.css` 里有 **60 个 `url()`**（woff2/woff/ttf 三份）。改为只保留 woff2（20 个，约 254KB），改写为绝对路径 `/nb2/fonts/X.woff2`，`immutable` 缓存，浏览器按需惰性下载（典型文档只用 8 个）。
- **分发器必须 `if (e.defaultPrevented) return`**：`2899-2913` 的 AI 条在 window capture 只 `preventDefault` 不 `stopPropagation`，否则会「接受 AI 改动」+「把旧代码又跑一遍」双触发。
- **不新增 Ctrl-Shift-Enter**：VS Code 真实键位是 Shift-Enter（跑+下移）/ Ctrl-Enter（原地）/ Alt-Enter（跑+下方插入），Alt-Enter 已在 `1025` 绑好。
- **`@lezer/python` 不写进 `.nb2-build/package.json`**：让它上溯用 profile 那份（与 `lang-python@6.2.1` 共用），否则打出第二份 lezer。
- **`CM.DOMPurify` 可能是工厂**：必须 `typeof .sanitize === "function"` 守卫，不满足就回落 `markdownLite`（纯 `h()` 构造，天然安全），绝不把未消毒 HTML 交给两处 `dangerouslySetInnerHTML`。
- **`marked.parse` 按 source 缓存**（上限 ~200）+ 超大 md 先显源码，避免 App 级重绘卡主线程。
- **测试可测性**：抽 `decideCellKey` / `nextRunTarget` / `renderMarkdown` / `rewriteImgSrc` / `buildOutlineV2` 进 `__internals`（ReactStub 的 `useState` 无状态、`useEffect` 空实现，组件树里测不到键盘与聚焦）。

### 9.3 新增 P0（评审指出的遗漏）

**内核 cwd 跟随 notebook 目录** —— 这是用户第 2 条的**另一半**：用 picker 打开工作区 notebook 后，内核仍在 profile 目录启动，`read_csv("data.csv")` 必失败。
处置：`notebook/open` 成功后把会话 cwd 设为 notebook 目录（用户显式 `notebook/setCwd` 过则不动，`cwdExplicit` 标记）；`notebook/new` 用 `defaultCwdFor`。

### 9.4 事实修正（评审纠正了 §0 的几条推断）

| 原计划说法 | 实际 |
|---|---|
| markdown「表格/围栏语言全没处理」 | 表格有（578-594）、围栏语言记进 `data-lang`（573）；**真正严重的是图片不渲染**（536 的正则把 `![alt](src)` 拆成 `!` + 链接） |
| 公式错版「只归 CSS」 | md cell 的 **`$$` 块级公式根本没被解析**（536 只认单行 `$..$`），光加 CSS 修不好 |
| 「没有某格之后插入的入口」 | 有 `▶+`（2173，运行并在下方插入）；缺的是**插入空 cell** 的入口 |
| 「三处调用点」 | 四处（263/516/657/951） |
| §2 5.2「分隔线按钮与 ＋代码 重复」 | 全仓无「分隔线按钮」，该行所述不存在 |
| Ctrl+S 未实现 | **已实现**（`1026` Mod-s），不要重复加 |

### 9.5 未采纳（留待后续轮次）

`runCell` 并发保护（连按重复入队）、保存路径常驻显示、多标签切换焦点恢复、粘贴多行自动拆格、变量面板。
理由：不在用户本轮 6 条内；先保证 6 条 + P0 闭环。

### 9.6 关于「为什么不直接把 VS Code 的 Jupyter 插件搬过来」（补强）

用户原话问的就是这条，§1 只论证了 JupyterLab rendermime，漏了最直接的一问：**能不能直接复用 `dsh-better-sidebar` 的 markdown 渲染器**？
评审核实：**不能**。它的渲染器在它自己的 `lib/client.js` 里、没有挂到 `window`，而 DSH 客户端插件是**隔离的自包含 CJS 工厂**（`client.js:135-137`，测试桩对非 `react` 直接抛错），跨包 import 不可能。
所以只剩两条路：抄它的实现思路（我们这轮走的：marked + DOMPurify + KaTeX 三件套）或自己重写。这也反过来印证 §1.1 的结论：vscode-jupyter 里用户看得见的 80% 是 VS Code 平台代码，不是可搬的插件代码。