前言¶
在 DeepSeek Harness（DSH）会话里做人工审阅，常见有两类摩擦：审阅进程会长时间阻塞，而 bash 调用往往更早超时，进程被推到后台后若被终止，已写的备注可能丢失且会话里没有记录；另外 DSH 会话启动时 PATH 往往只有 /usr/bin:/bin:/usr/sbin:/sbin，装在 ~/.local/bin 的 plannotator 可能找不到，审阅根本起不来。
dsh-plannotator（npm 包名 plannotator-dsh，仓库 martyartem/dsh-plannotator）是维护者 martyartem 发布的客户端类 DSH 插件：在 Harness 里打开 Plannotator 浏览器界面，审阅单个文件、文件夹或网页，人类提交后把标注以普通对话消息送回当前会话，便于智能体在同一聊天里继续处理。社区目录页：skillhub.cn/plugins/martyartem/dsh-plannotator（独立站点，与 DeepSeek / 幻方无官方从属关系）。
这是什么¶
插件定位可以用 README 里的一句话概括：在 DeepSeek Harness 中通过 Plannotator 浏览器 UI 审阅文件、文件夹或网页，标注以对话消息形式回到 agent。
实现上分为 Host 半（lib/index.js：注册命令与 HTTP 路由、解析 CLI 与工作区、后台启动 Plannotator、读取决策记录并写回会话）和 Browser 半（lib/client.js：在文档预览等处注入 Review 按钮，不依赖额外打包器）。对外表面很集中：侧栏一个 Review 入口、Composer 一条 /plannotator 命令、两条 HTTP 路由，无额外 flags。
当前版本 0.1.0，许可证 MIT。
核心功能¶
界面与命令¶
| 入口 | 作用 |
|---|---|
| 文档预览页眉 / 右侧边栏 Review | 对当前屏幕上的文件发起审阅；若 Plannotator 不接受的类型（PDF、图片、Office 等），则改为审阅所在文件夹，避免按钮无效 |
/plannotator <file\|folder\|url> |
与 Review 相同的审阅，从输入框启动，也是 agent 的非阻塞入口 |
/plannotator |
审阅本会话工作区目录 |
/plannotate |
上述命令别名 |
人类在 Plannotator 中提交后，决策记录（--json）在开启 autoFollowup（默认 true）时会作为带 source.kind: plugin:plannotator-dsh 的用户消息写回对话，agent 可在同一会话里跟进。
与「直接跑 plannotator」的差异¶
插件会在后台启动审阅并立即返回链接，而不是让 DSH 调用长时间阻塞；同时自行解析 plannotator 可执行文件：插件配置 → 环境变量 PLANNOTATOR_BIN → PATH → 常见安装路径（如 ~/.local/bin、/usr/local/bin、/opt/homebrew/bin 等）。未找到 CLI 时插件仍可加载，并提示如何指定路径。
HTTP 路由（Browser 半调用 Host，不直接 import 服务）¶
| 路由 | 用途 |
|---|---|
GET /plannotator/review?target=<path\|url>[&session=<id>] |
后台启动审阅，返回 { ok, url, label, gate } |
POST /plannotator/log |
将客户端日志转发到插件日志 |
环境与依赖¶
安装或启用前请核对 README 与仓库源码、许可证（MIT）。
| 依赖 | 要求 |
|---|---|
| DeepSeek Harness | >=0.1.0-rc.5（见 package.json 中 dsh.compatibility） |
| Node（Host 半） | >=20，无额外 npm 运行时依赖 |
| Plannotator CLI | 需符合文档约定：annotate <target> --json、就绪文件 PLANNOTATOR_READY_FILE、stdout 决策记录，以及 PLANNOTATOR_ORIGIN、PLANNOTATOR_PORT 等 |
安装与启用¶
通过 Harness 插件管理器¶
在应用内打开 Plugins，安装该仓库地址，然后重启应用：
https://github.com/martyartem/dsh-plannotator
npm 包名为 plannotator-dsh，Git 仓库名为 dsh-plannotator。
从本地 checkout 以 link 方式安装（开发）¶
若需在 ~/.dsh 外 clone 并通过 link 挂到 profile，README 给出的示例为：clone 到任意目录后，在 ~/.dsh/profiles/<profile>/package.json 中加入 link: 依赖并在 dsh.profile.bundles 里包含 plannotator-dsh，再重启；回滚可用 scripts/uninstall.sh [profile] [--purge]。具体 JSON 片段以仓库 README 为准。
配置¶
在 profile 的 patch 层（cordis.patch.yml）中覆盖插件项 plannotator-dsh，用户 patch 在 DSH 升级后仍会保留。示例：
- id: plannotator-dsh
name: plannotator-dsh
config:
gate: true
timeoutMs: 1800000
常用配置项（默认值以 README 表格为准）：
| 键 | 默认 | 含义 |
|---|---|---|
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 |
插件日志目录 |
日志文件：~/.dsh/storages/plannotator-dsh/plannotator-dsh.log。
典型用法¶
1、确保本机已安装 Plannotator CLI，且 DSH 版本满足 >=0.1.0-rc.5，并完成插件安装与重启。
2、在 Composer 中指定目标，例如审阅单个文件、目录或 URL（语法以 Plannotator CLI 为准）：
/plannotator ./docs/README.md
/plannotator /path/to/project
/plannotator https://example.com/doc
3、只审阅当前会话工作区时，可省略参数：
/plannotator
4、或在打开文档预览时点击 Review；后台会返回可打开的审阅 URL，提交后标注出现在对话中，agent 可据此修改或总结。
5、升级 DSH 或 Plannotator 后若行为异常，可按 README 建议查看日志关键行：
grep -E "loaded|apply:|registered|unavailable|steering failed" \
~/.dsh/storages/plannotator-dsh/plannotator-dsh.log | tail -12
例如 loaded …; binary=… 表示 Host 已加载并找到 CLI；steering failed 表示回写消息被拒绝；session … timed out 表示超过 timeoutMs 被停止。
适用场景与注意¶
适合谁：需要在 DSH 里做文档/代码/网页的人工标注，并希望标注结构化回到同一会话、由 agent 继续处理的团队或个人；依赖 Plannotator 浏览器 UI，而不是纯终端 diff。
权限与安全：插件以当前 DSH 进程权限运行，可启动本地审阅服务、读写工作区相关路径。安装前请阅读 GitHub 仓库 源码与 MIT 许可证，仅在信任维护者与依赖链的前提下启用。
工作区解析顺序（Host）：当前 agent 会话目录 → DSH_WORKSPACE_DIR / DSH_CWD → ctx.workspaceRegistry → 会话日志头中的 cwd → 最新会话 → Host 进程 cwd。多工作区并存时，应用 /plannotator 无参或显式传路径，避免审错目录。
结尾¶
dsh-plannotator 把 Plannotator 审阅嵌进 DSH 客户端：非阻塞启动、CLI 路径自愈、标注回写到对话，表面只有 Review 按钮与 /plannotator（及 /plannotate）一条命令线。进一步了解与 issue 见 GitHub；在 Harness 内安装时使用仓库 URL https://github.com/martyartem/dsh-plannotator。目录索引：https://www.skillhub.cn/plugins/martyartem/dsh-plannotator。
