前言¶
在 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。
