merge: 合入最新 main（#353 agent-open-tools / #360 markdown-html-toc 等），解决 PR 合并性
# Conflicts: # src/client/EditorHost.tsx # tests/prefs.spec.ts
This commit is contained in:
HuanLinOTO
@@ -0,0 +1,96 @@
|
||||
# 设计：模型主动在侧边栏打开（`sidebar_open` 工具 + `agentOpenTools` 设置）
|
||||
|
||||
> 日期：2026-08-23 · 状态：已实现 · 仓库：omdsh-dev/DSH-better-sidebar
|
||||
|
||||
## 需求
|
||||
|
||||
新增一个侧边栏**全局设置**（Side card 设置页「常规」分组）：`agentOpenTools`，**默认关闭**。
|
||||
开启后向模型注入**一个**工具 `sidebar_open`，允许模型主动在**调用方会话**的侧边栏中打开：
|
||||
|
||||
- 本地**文件** → 内置 editor tab（按 path 去重，聚焦既有 tab）
|
||||
- 本地**文件夹** → 内置 editor tab 的**文件夹窗口**（文件树以该目录为根）
|
||||
- **HTTP(S) 网页** → 内置 browser tab（URL 预填）
|
||||
|
||||
## 关键决策
|
||||
|
||||
### 1. 作用域 = 调用方 agent 会话
|
||||
|
||||
与 `terminal_*` 工具一致：工具只绑定 `exec.agent.session.id`，模型不传 sessionId。
|
||||
子代理（或未激活会话）调用时若无客户端连接，打开请求排队，该会话侧边栏下次可见时重放。
|
||||
工具结果通过 `delivered` 如实报告「当前是否已推送到已连接的侧边栏视图」。
|
||||
|
||||
### 2. 投递通道：host→client WS 推送（无 ack 协议）
|
||||
|
||||
- 新增 WS 升级路由 `/sidebar/ws/agent-opens?sessionId=...`（与 `/sidebar/ws/agent-terminals` 同模式，过同一 trust fence）。
|
||||
- host 侧 `AgentOpenRegistry` 维护会话级队列 + 已连接视图集合：
|
||||
- `enqueue`：有订阅者 → 即时推送并**消费**（`delivered: true`）；无订阅者 → 保留队列（`delivered: false`）。
|
||||
- `attach`：注册订阅者并**重放**队列（消费即出队），返回 disposer（close/error 时退订）。
|
||||
- `drainAll`：特性关闭时丢弃未投递队列。
|
||||
- **消费即出队**是关键：browser tab 无 per-URL 去重，重连重放会铸造重复 tab；消费语义保证每个请求恰好推送一次。
|
||||
- 不加 ack 回执、不加 `/sidebar/api` 路由——结果的最佳努力语义（`delivered`）已足够，符合 KISS 与 terminal 先例。
|
||||
|
||||
### 3. `sidebar_open` 工具（唯一新增工具）
|
||||
|
||||
- 参数：`target`（必填：绝对/相对路径，或 http(s) URL）、`title`（可选：tab 标题）。
|
||||
- 执行流程：`throwIfAborted` → 分类 → 目标 tab 启用检查 → 入队 → 返回规范结果。
|
||||
- 分类规则：
|
||||
- `http://` / `https://`（大小写不敏感）→ `url`，默认标题 = hostname；
|
||||
- 其他 scheme（`file:` / `javascript:` / `vscode:` 等）→ 报错（Windows 盘符前缀 `C:\`/`C:/` 除外，它是路径不是 scheme）；
|
||||
- 本地路径 → 相对路径以会话 cwd（`sessionCwdOf`）解析为绝对路径，`stat` 定 `file`/`folder`；不存在/不可读 → 报错；
|
||||
- 目标 tab 类型被用户禁用（`tabsEnabled['editor'|'browser'] === false`）→ 报错并提示启用（避免客户端静默 no-op）。
|
||||
- 输出（canonical JSON，`render` 纯文本投影）：`{ kind, target, title, delivered }`。
|
||||
- 工具描述/错误消息为英文（与 8 个 `terminal_*` 一致）。
|
||||
|
||||
### 4. 文件夹窗口：editor tab 的 `meta.dir`
|
||||
|
||||
- 打开文件夹 = `openTab({ type: 'editor', path: <dir>, id: 'editor:'+<dir>, title, meta: { dir: true } })`。
|
||||
- EditorHost 识别 `meta.dir === true`：不进入 viewer 加载流程，渲染**全窗 TreePanel**（`cwd = tab.path`）；
|
||||
FileTree 根部即 `cwd`（`fs.tree` 接受绝对路径），搜索结果/上传仍受会话工作区约束（已知限制，见下）。
|
||||
- `meta` 为可持久化的 tab 状态（v0.12.0+），`sanitizeState` 原样保留——刷新后文件夹窗口恢复。
|
||||
- 折叠/展开、右键打开、拖拽上传等全部复用 TreePanel 既有能力。
|
||||
|
||||
### 5. 设置与门控
|
||||
|
||||
- 新 prefs 字段 `agentOpenTools: boolean`（`SidebarPrefs` + `PrefsSchema` + 客户端 `parsePrefs`），默认 `false`。
|
||||
- SideCardSection「常规」分组新增一行 Switch（标题/描述走新 locale key）。
|
||||
- host 门控完全拷贝 `agentTerminalTools` 的 `syncToolsGate` 模式：
|
||||
- 开启 → `registerOpenTool(...)`；关闭 → 注销工具 + `agentOpenRegistry.drainAll()`；
|
||||
- 一次 `scope.watch` 同时驱动两个门控（各持有自己的 disposer，互不干扰）；
|
||||
- 工具不依赖 node-pty，降级模式下也可用。
|
||||
- 客户端防御：Sidebar 的 agent-opens 推送订阅在 `prefs.agentOpenTools !== true` 时忽略消息（host 已门控，此为双保险）。
|
||||
|
||||
### 6. 与既有拦截开关的关系
|
||||
|
||||
- URL 打开**不受** `browserInterceptLinks` / `browserInterceptHttp` / `browserInterceptHttps` 约束——那是用户点击外链的接管开关；
|
||||
模型显式调用 `sidebar_open` 只受 browser tab 自身启用开关约束（openTab 既有 gating）。
|
||||
- 文件打开**不受** `interceptOpenPath` 影响（那是聊天点击路径的接管开关）。
|
||||
|
||||
## 既有模式复用（零新公共 API）
|
||||
|
||||
| 新事物 | 复用/镜像的既有模式 |
|
||||
|---|---|
|
||||
| `agentOpenTools` 门控 | `agentTerminalTools` 门控（settings seam `watch` → 注册/注销） |
|
||||
| `/sidebar/ws/agent-opens` | `/sidebar/ws/agent-terminals` 推送（升级注册、fence、每会话 attach） |
|
||||
| 客户端推送订阅 | Sidebar 的 agent-terminals effect（重连上限 `FAILURE_LIMIT`、防抖/清理） |
|
||||
| 文件/URL 打开 | `service.openFile` / `openTab({ type:'browser', url })`（link-intercept 同款） |
|
||||
| 文件夹窗口 | path-less explorer 的全窗 TreePanel 分支（仅根目录改为 `tab.path`） |
|
||||
|
||||
不新增 `BetterSidebarService` 方法；不改变任何现有路由协议。
|
||||
|
||||
## 已知限制
|
||||
|
||||
- **多浏览器窗口**：推送按「有订阅者即发送并消费」执行，多窗口同时连接时后连接的窗口不会收到已消费的请求
|
||||
（其本体状态由 localStorage 恢复——与 agent-terminals 的全量列表 fan-out 不同，属尽力而为语义）。
|
||||
- **文件夹窗口的全局搜索/上传**：TreePanel 的搜索盒仍以**会话 cwd** 为根（`fs.search` 是有意的工作区限定），
|
||||
目录内上传经 host 会话工作区校验（目录在 cwd 内可上传，cwd 外拒绝）。
|
||||
- **无 ack**：`delivered: true` 只表示「推送已发出」，客户端处理失败（罕见）不重试。
|
||||
- **关闭特性不清已打开 tab**：与 tab 启用开关语义一致，只注销工具并清空未投递队列。
|
||||
|
||||
## 测试覆盖
|
||||
|
||||
- `tests/agent-opens.spec.ts`（新）：注册表语义（排队/重放/消费/作用域隔离/drain/dispose）+ 工具行为
|
||||
（分类、相对路径、缺路径、非 http(s) scheme、tab 禁用、schema 校验、无 agent 错误）。
|
||||
- `tests/smoke.spec.ts`：WS 升级路由清单 + `settings.get` 默认值 + 独立 gating 测试（默认 off → 0 工具；on → 1；off → 注销）。
|
||||
- `tests/plugin-shape.spec.ts` / `tests/prefs.spec.ts`：schema/parse 默认值 + 全量 prefs 字面量。
|
||||
- `tests/editor-host.spec.tsx`：`meta.dir` 文件夹窗口（树以目录为根、无编辑器 chrome、不触发 viewer 加载）。
|
||||
- `tests/locales.spec.ts`：zh/en/ja 词典 key 集相等（自动覆盖新键）。
|
||||
@@ -0,0 +1,52 @@
|
||||
# Markdown 预览内嵌 HTML 渲染 + 目录大纲（TOC）设计
|
||||
|
||||
> 日期：2026-08-24
|
||||
> 状态：已实现
|
||||
> 范围：`dsh-better-sidebar` 插件，Markdown 文件预览（`TextEditor.tsx` preview 模式）；Sidechat 与其他渲染面**零改动**
|
||||
> 基线：复用 mermaid 预览（PR #164）确立的「检测切分 + 单次 MarkdownText 解析 + commit 后 DOM 手术」架构与安全姿势
|
||||
|
||||
## 1. 背景与问题
|
||||
|
||||
DSH 宿主的 `MarkdownText` 出于聊天安全把 raw HTML 按字面文本渲染（协议白名单、相对链接禁用、图片仅绝对 http(s)）。这对聊天是对的，但对**文件预览**是灾难：GitHub 风格的 README（本仓库自己的 README 即典型）大量使用内嵌 HTML——`<div align="center">` 徽章墙、`<details>` 折叠块内嵌 markdown、表格单元格里的 `<br/>`/`<sub>`/`<img>`、`<video>`/`<picture>`——预览时全部显示为源码文本。
|
||||
|
||||
用户需求（确认记录）：覆盖 Markdown 文件预览；块级 + 内联 HTML 都做；安全模型选 DOMPurify 白名单内联渲染（非沙箱 iframe）；TOC 选浮动按钮 + 弹出面板；Sidechat 暂不动；**不更换渲染器**（保住 MarkdownText 的 shiki 高亮 + KaTeX 数学 + GFM 表格）。
|
||||
|
||||
## 2. 方案
|
||||
|
||||
### 2.1 检测与切分：`src/client/markdown-html.ts`（纯函数）
|
||||
|
||||
- `splitHtmlBlocks(text)`：行扫描器把文档切成 `markdown | html` 段。HTML 段 = 围栏外的**块级标签行**（CommonMark type-6 名单 + `<summary>`，开或闭标签）开头、延伸到空行的连续行；`<!-- -->` 注释段在含 `-->` 的行结束。**围栏识别复用 `mermaid-blocks.ts` 导出的 fence 助手**——```html 围栏内的 `<div>` 示例不会被误切。段边界的空行是分隔符，被丢弃。
|
||||
- `analyzeHtmlSegment(source)`：段内标签 tokenizer（跳过注释，void/自闭合标签不进栈，错配闭标签按 HTML 解析器的隐式闭合弹出）归约为有序 parts：`html`（平衡的原始片段，渲染为消毒叶子）/ `open`（未闭合开标签 + 原始 attrs，成为包裹后续段的容器）/ `close`（多余闭标签，弹出一层）。
|
||||
- `collectReferenceDefinitions(segments)`：从 markdown 段收集 `[label]: dest` 行。**每个 markdown 段渲染时追加密全文档定义**——跨 HTML 段的 `[text][id]` 语义保真（追加副本在已含定义的段内因 first-match-wins 而惰性）。这是 mermaid 预览「单次解析」约束（引用定义跨 fence 解析，e2e 钉死）在切分渲染下的等价物。
|
||||
- `analyzeMarkdownHtml(text)`：整体入口，含 `hasInlineHtml` 廉价正则门（fence 内误报只多走增强路径，内联 pass 本身跳过代码块，无行为差异）。
|
||||
|
||||
### 2.2 渲染：`src/client/MarkdownHtml.tsx`
|
||||
|
||||
- **安全管线**（三个入口共用）：块叶子 / 内联文本 / 包裹开标签 attrs 全部过 DOMPurify（显式 `FORBID_TAGS: script/style/iframe/object/embed/form/input/button/select/textarea/meta/link/base/frame/frameset/applet` + `FORBID_ATTR: srcdoc/formaction`，叠加在默认白名单之上）；消毒后 DOM 遍历强制 `<a>` → `target=_blank rel=noopener noreferrer`；本地 `img/video/audio/source` 的 `src` 经 `resolveLocalMediaDest`（从 `markdown-images.ts` 抽出的共享助手）重写为 `/sidebar/file` 会话媒体 URL——与 markdown 图片重写同一信任围栏。包裹标签的 attrs 走「迷你文档消毒再读回」；`class/for` 映射 React 名，`style` 丢弃（React 需对象，不值得引入 CSS 解析器）；整标签被禁时容器透明（子内容照常渲染）。
|
||||
- **`MarkdownDocument` 段渲染状态机**：markdown 段 → `MarkdownSegment`；平衡 html 段 → `dangerouslySetInnerHTML` 叶子（`[data-dsh-html-segment]`）；`open`/`close` 部件驱动一个**跨段持久的帧栈**——`<details>` 开段把后续段降为自己的子元素，`</details>` 段弹栈（GitHub 线性 HTML 输出的同款嵌套）。顶层多余闭标签渲染为无（消毒器/解析器本就会丢弃）；文档结束仍开着的帧按浏览器解析器语义收口。消毒在 `useMemo` 内按段缓存。
|
||||
- **`MarkdownSegment` 内联替换**：段内含 mermaid fence 走现有 `LazyMermaidMarkdown`（chunk 逻辑不变），否则 `MarkdownText`；`useLayoutEffect` + **MutationObserver**（微任务去抖、幂等、跳过 `code/pre/.md-code-block/[data-mermaid-processed]/[data-html-inline]`）把含标签样式文本的文本节点整体消毒后包进 `<span data-html-inline>` 替换——纯散文（`a < b`）消毒后无元素子节点则原样保留；observer 覆盖懒 chunk 迟挂载、shiki 异步高亮等迟到内容。与 mermaid 换装同款「React 持有宿主树、只动叶子」姿势。
|
||||
- **接线（`TextEditor.tsx`）**：`analyzeMarkdownHtml` 发现块级或内联 HTML 才走 `MarkdownDocument`；**纯 markdown 文档走原路径原样**（无 HTML → 单次 `MarkdownText`/mermaid chunk，现有 e2e「单次解析」守卫继续成立——种子 md 文件不含 HTML，断言一字未改）。
|
||||
|
||||
### 2.3 TOC：`src/client/md-toc.tsx`
|
||||
|
||||
- 零高度 sticky 条（`position: sticky; top: 0; height: 0; pointer-events: none`，不占布局、滚动常驻）+ 右上角按钮 `[data-dsh-md-toc]`（≥3 个标题才出现）+ 弹出面板 `[data-dsh-md-toc-panel]`（按层级缩进、独立滚动、Esc 关闭）。
|
||||
- 标题从**渲染后的 DOM** 收集（h1–h6，含 HTML 段内标题），MutationObserver 重扫（签名比对防重渲染循环）。
|
||||
- 跳转：展开 `closest('details:not([open])')` → `scrollIntoView({behavior:'smooth'})` → CSS 动画高亮 1.2s。
|
||||
- **⚠️ 关键实现陷阱（本次踩坑）**：MdToc **不能**通过传入父容器 ref 定位——React 的 layout 阶段子先于父，子组件的 `useLayoutEffect` 执行时父 div 的 ref **尚未挂上**（实测 `containerRef.current === null`，且依赖数组恒定导致 effect 永不重跑，按钮永不出现；jsdom 单测传预填 ref 对象会掩盖此 bug，只有真实挂载 e2e 能抓到）。修复：MdToc 用**自身 bar div 的 ref**（自身 effect 前必然已挂）取 `parentElement` 作为容器——挂载契约「渲染为目标滚动容器的直接子元素」写入组件文档；bar 常驻渲染（零高度无副作用）以保证 ref 恒在。
|
||||
|
||||
### 2.4 依赖与产物
|
||||
|
||||
- `dompurify ^3.4`（已是 mermaid 的传递依赖，提升为直接依赖后 pnpm 去重单版本，零额外体积）随 editor chunk 内联，未新增 chunk。
|
||||
- 市场清单守卫合规（dependencies 无 `cordis`、无 install 脚本）。
|
||||
|
||||
## 3. 测试
|
||||
|
||||
- `tests/markdown-html.spec.ts`：切分器（21 例：块级标签成段/空行终止/注释段/闭标签段/围栏免疫/CommonMark 恢复/README details 三段形）+ tokenizer 平衡分析（9 例）+ 引用定义收集 + 内联门。
|
||||
- `tests/markdown-html-render.spec.tsx`：真实 `MarkdownText` 渲染——消毒叶子（script 剥除、a 加固、本地 src 重写）、details 跨段嵌套（fence 在 details 元素内、后续段是兄弟）、跨段引用定义解析、禁用标签容器透明、内联替换（表格单元格 `<br/>` 生效、代码块与 `a < b` 不动、内联本地 img 重写）。
|
||||
- `tests/md-toc.spec.tsx`：阈值门、标题收集、跳转（mock `scrollIntoView`、折叠祖先展开、高亮清除）、observer 迟到标题、Esc 关闭。
|
||||
- `tests/e2e/mount.e2e.ts`：新增 `readme-style.md` 种子（徽章 div 含 script、details 包 fence+标题、表格内联 `<br/>`、跨段引用定义）+ 探针（徽章 img 真实元素、无 script、details 嵌套、内联 br、引用解析、TOC 按钮→面板→跳转展开）。**现有 mermaid 探针与断言一字不动**（纯 markdown 文档零回归证明）。
|
||||
|
||||
## 4. 已知取舍（明确不做）
|
||||
|
||||
- GFM 脚注跨段不保（宿主本就把脚注渲染为纯文本）；`srcset` 不重写（实际只有远程 URL）；HTML 实体不解码；标题锚点 permalink、TOC 滚动联动高亮不做；Sidechat 不动；不换渲染器。
|
||||
- CommonMark HTML 块类型 1（script/pre/style/textarea 按闭标签终止）与类型 7（单行完整标签）不做专门处理——块级名单 + 空行终止已覆盖 README 级真实用法。
|
||||
Reference in New Issue
Block a user