批注审查器 martyartem/dsh-plannotator

dsh-plannotator

英语 | 俄语

在 Plannotator 浏览器 UI 中审查文件、文件夹或网页——注释会作为对话中的普通消息返回给智能体。

version
license
tests
CI
DeepSeek Harness

为什么会有这个插件

当审查从 DSH 会话内部发起时，有两件事会造成阻碍，而且各自带来的麻烦还不一样。

| 阻碍因素 | 在你看来是什么样 | 这个插件做了什么 |
| 审查会阻塞调用 | 审查服务器会等待人类数分钟，而 DSH 的 bash 调用放弃得远早于此：进程被推到后台，而杀掉它会丢失你已经写下的笔记，且没有任何记录。 | 在后台启动审查，立即返回链接，并在人类提交后将决定送入对话。 |
| 找不到 plannotator | DSH 会话启动时带有 PATH=/usr/bin:/bin:/usr/sbin:/sbin，因此安装在 ~/.local/bin/plannotator 的程序不在其中——智能体看到 plannotator: command not found，审查永远不会启动。 | 自行解析 CLI：插件配置 → PLANNOTATOR_BIN → PATH → 已知安装位置。 |

功能

| 界面 | 位置 | 作用 |
| Review 按钮 | 文档预览头部，右侧边栏 | 启动对屏幕上文件的审查。Plannotator 会拒绝的文件（PDF、图片、Office、特殊后缀）将按其所在文件夹进行审查，因此该按钮永远不会成为死路。 |
| /plannotator | 输入框 | 同样的审查，从文本框启动——也是智能体的非阻塞入口点。 |
| /plannotator | 输入框 | 审查此会话的工作区文件夹。 |
| /plannotate | 输入框 | 别名。 |
| 已送达的注释 | 对话 | 决定记录（--json）会作为消息被引导回来，因此智能体可以在同一聊天中处理这些注释。 |

这就是全部界面：一个侧边栏席位、一个命令、两条 HTTP 路由，没有标志。

要求

- DeepSeek Harness >=0.1.0-rc.5（在 package.json 中声明）。
- Node >=20 用于宿主端。没有运行时依赖。
- Plannotator CLI 安装在插件能找到的某个位置：插件配置、PLANNOTATOR_BIN、 PATH，或 ~/.local/bin、/usr/local/bin、/opt/homebrew/bin、~/.bun/bin 之一， ~/.cargo/bin。没有它，插件仍会加载，并会说明如何将其指向 CLI。

安装

从 Harness 插件管理器安装

在应用中打开 Plugins，然后安装此仓库：

https://github.com/martyartem/dsh-plannotator

然后重启应用。npm 包名是 plannotator-dsh；仓库是 dsh-plannotator。

从本地检出安装

克隆到 ~/.dsh 之外的任意位置，并以 link 方式安装，这样编辑内容就能进入 profile：

git clone https://github.com/martyartem/dsh-plannotator ~/Projects/plannotator-dsh

将其添加到你的 profile（~/.dsh/profiles//package.json）并重启：

{
"dependencies": { "plannotator-dsh": "link:/Users/you/Projects/plannotator-dsh" },
"dsh": { "profile": { "bundles": ["…", "plannotator-dsh"] } }
}

scripts/uninstall.sh [profile] [--purge] 会回滚该操作。

配置

在你的 profile 的 patch 层（cordis.patch.yml）中设置值——用户 patch 层在 DSH 升级后仍会保留：

- id: plannotator-dsh
name: plannotator-dsh
config:
gate: true
timeoutMs: 1800000

| 键 | 默认值 | 含义 |
| binary | 自动检测 | plannotator CLI 的显式路径 |
| binaryFallbacks | 已知列表 | 额外的候选路径 |
| origin | dsh | 每次审查都会标记的 PLANNOTATOR_ORIGIN |
| gate | false | 为每次审查添加一个 Approve 按钮 |
| openBrowser | true | 让 Plannotator 打开浏览器标签页 |
| port | 随机 | 固定本地审查服务器端口 |
| timeoutMs | 900000 | 审查在被停止前可以保持打开多长时间 |
| readyTimeoutMs | 20000 | 等待本地服务器报告就绪的时间 |
| autoFollowup | true | 将注释引导回对话中 |
| debug | false | 同时将插件日志写入 stderr |
| dataDir | ~/.dsh/storages/plannotator-dsh | plannotator-dsh.log 所在位置 |

工作原理

- 宿主部分 — lib/index.js：注册命令和两个路由，解析 CLI 和工作区，在后台启动 Plannotator 进程，等待其就绪文件，然后从其 stdout 读取决策记录并将其引导到会话中。
- 浏览器部分 — lib/client.js：以宿主的模块加载器格式手写（window.__ModuleLoader__.load），因此它不需要打包器，并且只从平台
seed 表中使用 react。它通过 ctx.slots.inject(seat, () => ctx.slots.register(…)) 贡献自己的席位，
这是文档中说明的、独立于插件启动顺序的方式。
- HTTP 路由 — 浏览器部分从不导入宿主服务：

| 路由 | 用途 |
| GET /plannotator/review?target=[&session=] | 在后台启动审查，返回 { ok, url, label, gate } |
| POST /plannotator/log | 将客户端注释转发到插件日志 |

- 工作区解析，按顺序：活动 agent 的会话目录 → DSH_WORKSPACE_DIR / DSH_CWD → ctx.workspaceRegistry → 会话日志头部中的 cwd → 最新的会话 → 宿主进程的 cwd。
- 投递契约 —— 智能体收到的消息是一条 DSH UserMessage，包含该类型要求的每一个字段： id、role、content，以及由生产者拥有的 source.kind，其值为 plugin:plannotator-dsh。追加路径接受不带 id 的消息，但随后的恢复路径会拒绝整个会话（session event at seq N lacks an identified message），历史记录便停止加载。插件自行生成 id，离线测试套件断言该消息携带一个 id。

兼容性

| 依赖项 | 范围 |
| DeepSeek Harness | >=0.1.0-rc.5 |
| Node | >=20，仅使用内置模块 |
| Plannotator CLI | 文档化的契约：argv annotate --json、就绪文件（PLANNOTATOR_READY_FILE）、stdout 决策记录、PLANNOTATOR_ORIGIN、PLANNOTATOR_PORT |

故障排查

所有内容都会记录到 ~/.dsh/storages/plannotator-dsh/plannotator-dsh.log。在 DSH 或 Plannotator 升级后，这就是全部检查：

grep -E "loaded|apply:|registered|unavailable|steering failed" \
~/.dsh/storages/plannotator-dsh/plannotator-dsh.log | tail -12

| 行 | 含义 |
| loaded …; binary=… | 宿主加载了插件并找到了 CLI |
| registered /plannotator/review and /plannotator/log | HTTP 路由已就位 |
| client[info]: document preview action registered | Review 按钮的位置已存在 |
| document preview action unavailable: … | 该位置已被重命名或已不存在 |
| steering failed: … | 宿主拒绝了投递的消息 |
| session … timed out after … | 审查超过了 timeoutMs 并被停止 |

如果第一行缺失，说明插件根本没有加载——通常是宿主重命名了某个注入的服务。

开发

除了 Node 什么都不需要：无需安装步骤、无需打包器、无需启动配置文件。

npm test # 两个离线部分
node scripts/selftest.mjs # 宿主部分：35 项检查——解析、CLI/工作区解析、会话、路由
node scripts/client-test.mjs # 浏览器部分：12 项检查——打包产物形态、单一位置、冷启动竞态
node scripts/live-test.mjs # 针对真实的 Plannotator CLI 及其 HTTP API

lib/
index.js 宿主行：命令、HTTP 路由、智能体定位 command.js 输入 → Plannotator argv review.js 后台审查：就绪、决策、引导、超时 config.js 配置默认值、日志文件、辅助函数 binary.js 与 PATH 无关的 CLI 发现 workspace.js 相对目标解析所依据的目录 client.js 浏览器部分：文档预览 Review 位置 scripts/ 离线测试套件、实时冒烟测试、卸载辅助工具

说明与限制

- annotate 接受 markdown、纯文本配置/数据文件、HTML、URL 和文件夹。.env 会被 Plannotator 本身拒绝。
- Git diff、拉取请求和归档文件刻意不在这里：Plannotator CLI 直接覆盖了它们，而一个会阻塞数分钟的斜杠命令正是这个插件要避免的。
- 没有人完成的审查（进程被杀掉、机器休眠）不会产生任何决定；插件会如实说明，而不是假装审查为空。
- 插件从不抓取浏览器 UI：它只使用 CLI 文档化的 stdout 契约及其就绪文件。

许可证

MIT