yabo083/dsh-document-review

dsh-document-review

一个 DeepSeek Harness 插件，用于在本地浏览器中逐字审阅 Markdown 文档。

在渲染后的文档中选择文本，即可添加评论、建议替换或建议删除。浏览器从不编辑 Markdown 源文件；批注存储在一个集中的仅追加存储中，位于 ~/.dsh-document-review/annotations.jsonl，因此机器上任何位置的文件（工作区内或工作区外）的批注，都能通过一次工具调用被 agent 全部看到。

改编自 opencode-document-review——相同的审阅核心（HTTP 服务器、安全模型），但封装为面向 DSH 模型的工具，而非 OpenCode 工具，并将批注整合到一个集中存储中。

为什么

DSH agent 会大量撰写和编辑 Markdown——架构文档、ADR、README、计划。“逐字审阅这份文档”是一个自然的请求，但 DSH 之前没有相应的插件（已确认：截至 2026-08，市场上没有文档审阅/批注插件）。本插件填补了这一空白。

agent 在本地浏览器中打开文档；人类进行审阅并添加批注；agent 读取批注，并通过其常规的文件编辑工具应用更改。

工具

四个工具都注册在 ctx.tools 上，并面向模型：

| 工具 | 用途 |
|---|---|
| document_review_start | 为 Markdown 文件或目录启动或复用本地审阅会话（目录模式会审阅其中的每个 .md 文件）。返回浏览器 URL。 |
| document_review_list | 读取审阅批注（默认是未处理/待处理，或全部）。不带 path 时，返回机器上所有文档的全部批注——即 agent 在“审查完了你看下”之后所需的单次调用。包含源哈希过期信息。在目录模式下，汇总每个文档。 |
| document_review_update | 将评论（resolved/open）或建议（accepted/rejected/pending）标记为已处理。 |
| document_review_stop | 停止本地审阅会话。批注保留在集中存储中。 |

设置

配置遵循官方 DSH 插件模式：导出一个 Schemastery
Config schema，从 cordis.yml 配置（每个条目的 config: 块），并
额外将同一 schema 注册为 DSH 设置命名空间
（document-review），以便运行时覆盖。

在 harness Web profile 的 cordis.patch.yml 中，为
插件的条目添加一个 config 块：

- id: document-review
name: dsh-document-review
config:
preferredPort: 15600
idleTimeoutMinutes: 60
indexIgnore:
- node_modules
- .git
- dist

更改 config 块会通过 HMR 热替换插件。DSH 设置
用户文档（如果存在）会在 cordis.yml 基础配置之上覆盖各个键；如果没有，
则条目配置按原样生效。

页面内设置面板（审阅页面）

打开任意审阅页面，点击齿轮按钮（右上角）即可打开设置
具有两个层级的对话框：

- 全局设置 — 适用于每个工作区。持久化到
~/.dsh-document-review/config.json，分层叠加在 cordis.yml 基础之上。
- 当前工作区设置 — 仅适用于审阅页面所根植的工作区。持久化到
~/.dsh-document-review/workspace-configs.json
（以根路径为键），分层叠加在全局设置之上。

生效值 = 默认值 → cordis.yml → 全局设置 → 当前工作区设置。
索引限制立即生效（下次扫描）；端口和空闲超时值在下次会话启动时生效。恢复默认会清除当前层级的覆盖项。

| 键 | 默认值 | 作用 |
|---|---|---|
| preferredPort | 15580 | 审阅服务器首先尝试的端口；被占用时自动递增 |
| maxPortTries | 20 | 放弃前尝试的端口数 |
| idleTimeoutMinutes | 30 | 单例服务器自动关闭前的空闲时间 |
| openBrowserOnStart | true | 会话启动时打开审阅页面 |
| indexMaxRoots | 64 | 记住的文件名索引根目录数（LRU） |
| indexMaxEntries | 60000 | 文件名索引条目上限 |
| indexScanCooldownMs | 30000 | 对同一根目录进行完整重新扫描的最小间隔 |
| indexIgnore | node_modules, .git, dist, … | 索引、迁移和目录扫描时跳过的目录名 |

索引限制立即生效；端口和空闲超时值在下次会话启动时生效。

安装（已发布的包）

dsh plugin --profile web add dsh-document-review
dsh --profile web

该插件声明了 dsh.bundle（宿主工具 + HTTP 路由）和 dsh.client
（浏览器「审阅」面板）：审阅页面、面向模型的工具，以及
DSH 侧边栏中每个工作区的「文档审阅」菜单项都打包在同一个包中。

安装（开发）

从 DSH 仓库检出目录：

dsh web --patch /absolute/path/to/dsh-document-review/cordis.yml

打开 http://127.0.0.1:3080，并对智能体说：“逐字审阅 /path/to/file.md 处的文档。”

cordis.yml 覆盖层将插件插入 Web 配置文件。cordis.yml 中的路径必须是绝对路径；请编辑它以匹配你的检出位置。

浏览器审阅页面

审阅页面以只读方式渲染 Markdown。选择任意文本即可添加批注：

- 评论 — 不带替换内容的备注。
- 建议替换 — 为所选内容提议新文本。
- 建议删除 — 将所选内容标记为待删除。

批注显示在侧边面板中。每条批注都带有 textQuote 锚点和源文件的
SHA-256 哈希，因此智能体可以验证文档在审阅期间未被更改
（否则为 stale: true）。智能体通过 document_review_list 读回批注，
将更改应用到源文件，并将它们标记为已解决/已接受/已拒绝。

目录模式

将目录路径传给 document_review_start（或 HTTP 路由），即可在一个会话中审阅
多个 Markdown 文件：

- 页面列出每个 .md/.markdown 文件（递归、排序；跳过 node_modules、
.git 和构建输出目录；上限为 500 个文件）。
- 点击文件即可渲染；导航（后退/前进/面包屑/路径跳转）与单文件打开时使用的文件管理器 UI 相同。
- 每个文档都保留自己的 .review.jsonl 附属文件。
- document_review_update 接受一个 documentPath 参数（相对于目录的路径），用于定位特定文件的标注。

HTTP 路由（GUI 启动器）

客户端启动器调用宿主路由来启动审阅页面，无需模型：

GET  /api/v2/document-review/scan?path=   (compat; the page browses via /api/fs/list)
POST /api/v2/document-review/start
{ "path": "/abs/or/relative/path", "openBrowser": false }

start 返回 { reused, mode, documentPath, sidecarPath, url, documents }。
这两个路由都注册在 harness Web 服务器上（ctx.webServer，对于较旧的部署则回退到
httpServer），并且当 Web 服务器服务在此插件的 apply 之后绑定时，会以幂等方式重新注册。

在审阅页面内（端口 15580），设置对话框使用：

GET  /api/config                       (merged snapshot for this root)
POST /api/config/global                (write global overrides; needs review token)
POST /api/config/workspace             (write this root's overrides; needs review token)

浏览器启动器（客户端插件）

DSH 侧边栏中的每个工作区行都会在其省略号菜单中获得一个「文档审阅」条目：

- 打开某个工作区行的 ⋯ 菜单并选择 文档审阅，即可打开以该工作区目录为根目录的审阅页面（ctx.workspaces → 工作区 path）。
- 侧边栏没有暴露逐行插槽，因此该条目通过 MutationObserver 注入到门户菜单列表中，该观察器以工作区行菜单按钮（工作区“{name}”的操作 / Workspace actions for {name}）为键，该按钮仅存在于真实的工作区行上——未分组的分组会被跳过，会话行菜单永远不会获得该条目。
- 审阅服务器是一个单例——一个服务器，一个端口（15580，带备用端口），在多次打开之间复用。它在 30 分钟无流量后自动关闭，而页面在打开期间通过轻量级心跳使其保持存活，因此不会有端口被永久占用。
- 样式沿用 DSH 的 --dsw- 设计令牌，因此注入的菜单项在浅色和深色主题下都与宿主界面相匹配。

审阅页面——文件管理器浏览器 + 审阅

审阅页面是一个轻量级的双模式 UI：

- 文件浏览器（默认）：工具栏包含后退 / 前进 / 向上 / 刷新、历史记录下拉菜单，以及一个快速打开搜索框（VS Code 风格——按 Ctrl+P 聚焦）。面包屑从文件系统根目录经过「此电脑」层级（所有驱动器）延伸，因此你可以浏览机器上的任何位置——包括工作区之外的驱动器（例如工作区位于 E: 时，浏览 C: 上的 OneDrive）。目录和 Markdown 文件会被列出；点击目录进入该目录，点击文档打开审阅视图。工作区只是起点，而不是边界。
- 审阅视图：渲染后的文档，带有完整的批注 UI——选中文本即可评论/建议替换/建议删除；侧边面板列出批注，并提供定位、解决、接受和拒绝操作。
- 快速搜索由 Everything 风格的文件名索引提供支持（仅索引名称，绝不索引内容），其范围是你实际浏览过的目录，并持久化到 ~/.dsh-document-review/index-state.json。输入时会过滤内存中的名称映射（前缀优先于子串）；↑/↓ 导航，Enter 打开，Esc 关闭。常见的噪声目录（node_modules、.git、dist、cache、点开头的条目等）以及 .review.jsonl 附属文件会被跳过。
- 后退/前进历史记录是前端栈（Alt+← / Alt+→、鼠标侧键以及 🕘 下拉菜单都可用），因此导航永远不会触及服务器。
- 状态点显示单例服务器的健康状态；如果它空闲退出，刷新页面即可重启它。

页面在单例服务器上使用以下 API：

GET  /api/health              单例状态（根目录、文档数量）；心跳目标
GET  /api/fs/list?path=  一个目录：子目录 + Markdown 文件、面包屑祖先、父级；
::computer 列出所有驱动器（「此电脑」层级）
GET  /api/fs/search?q=     在持久化的文件名索引上进行快速搜索（最多 50 个命中）
GET  /api/document?path= 渲染一个 Markdown 文档 + 其批注
POST /api/annotations         添加一条批注（需要 X-Review-Token）
PATCH /api/annotations/:id    更新一条批注的状态（需要 X-Review-Token）
DELETE /api/annotations/:id   永久删除一条批注（需要 X-Review-Token）

数据契约

- 当前操作系统用户可读取的任何显式绝对 .md 或 .markdown 路径都可以被审阅。
- 相对路径从代理的当前工作目录解析。
- 审阅记录存放在一个中心化的仅追加 JSONL 存储中：~/.dsh-document-review/annotations.jsonl。
- 状态更新会追加一条具有相同批注 ID 的新记录；读取时按 ID 去重，最新记录优先。
- 删除一条批注会重写存储并移除该批注（物理删除）。
- 来自旧版本的旧式 .review.jsonl 附属文件会在首次启动时自动导入并移除。
- 记录包含引用锚点、源 SHA-256 哈希、状态、时间戳以及可选替换文本。
- 源文件变更由代理通过常规 DSH 文件编辑工具应用，而不是由浏览器应用。

安全

HTTP 服务器仅绑定到 127.0.0.1，验证回环 Host 和同源请求，使用随机写入令牌，禁用 CORS，并提供所选的 Markdown 渲染、单层目录列表和捆绑的静态资源。浏览器仅列出目录名称并读取 Markdown 文件；其他所有文件系统表面均关闭。存储写入使用跨进程锁，并拒绝符号链接附属文件。

结构

dsh-document-review/
├── src/
│   ├── index.ts          DSH 宿主入口：ctx.tools 上的 4 个工具 + HTTP 启动路由 + Config schema
│   ├── config.ts         Schemastery Config schema + 默认值（cordis.yml + DSH 设置）
│   ├── review.ts         审阅核心：HTTP 服务器、中央 JSONL 存储、安全性
│   ├── web-server.ts     ctx.webServer 路由的最小结构化类型
│   └── client/
│       └── index.tsx     浏览器入口：每个 Workspace 的「审阅」按钮（dsh.client）
├── public/
│   ├── index.html        审阅页面外壳
│   ├── app.js            选择 → 标注 UI（文件 + 目录模式）
│   └── styles.css        审阅页面样式
├── cordis.patch.yml      捆绑补丁：插入插件行（dsh plugin add）
├── cordis.yml            DSH Web 开发覆盖层（编辑路径以匹配你的位置）
├── tsconfig.json         宿主程序（src/，排除 src/client）
├── tsconfig.client.json  浏览器程序（src/client，jsx: react-jsx）
├── tsdown.config.ts      客户端捆绑构建（DSH __ModuleLoader__ 协议）
├── scripts/copy-assets.mjs
├── package.json
└── README.md

构建

npm install          # 开发工具（tsdown、lightningcss、react、typescript）
npm run build        # 宿主 tsc → lib/，客户端 tsc → lib/client/，tsdown → lib/client.js
npm run check        # 对两个程序进行类型检查而不输出

客户端捆绑包以 CJS 闭包工厂产物形式输出：
window.__ModuleLoader__.load({ id: "dsh-document-review", factory: (require) => … })
其中 react、react-dom 以及其他平台模块通过
外壳的冻结模块表解析，与 DSH 自身的 packages/client/ui- 捆绑包完全一致。

许可证

MIT