前言¶
用 DeepSeek Harness（DSH）折騰插件久了，難免遇到這種情況：DSH 崩潰、啓動失敗，或者某個插件把 profile 改壞了。DSH 沒有內置 doctor 命令，多數時候只能對着報錯猜原因，靠重啓進程碰運氣，或者手動翻配置文件排查。
下面介紹的 dsh-doctor 就是針對這個問題：先只讀診斷，告訴你哪裏壞了、爲什麼；再分級修復，每一步改動都可逆；改壞了還能一鍵回滾。
這是什麼¶
dsh-doctor（@jorinyang/dsh-doctor，當前版本 0.3.2）是 jorinyang 維護的 DSH 插件，定位是「診斷 + 修復 + 回滾」一體化工具，同時也是一個運行時自愈服務。它採用 MIT 許可證，是獨立插件加獨立 CLI，不修改 DSH 核心，與 DSH 自帶命令不衝突。
核心功能¶
只讀診斷¶
提供 dsh_doctor 工具和 dsh-doctor CLI 兩種形態，做只讀檢查，覆蓋 9 大類，報告哪裏壞了、爲什麼，不會改動任何文件。
分級修復¶
對應工具是 dsh_doctor_fix，命令行是 dsh-doctor fix。修復分三檔範圍：
| 範圍 | 動作 | 風險 |
|---|---|---|
safe（默認） |
創建缺失目錄/文件、修復 allowBuilds 佔位符 | 低，僅涉及文件/配置 |
deps |
safe 全部 + pnpm install --fix-lockfile |
中，涉及網絡與依賴 |
full |
deps 全部 + 停止殘留進程（健康時跳過） | 較高，涉及進程終止 |
每次修復都會生成一個 journal，記錄每個改動的 undo 步驟。具體來說：覆蓋的文件會保存原始內容，回滾時恢復；新建的文件/目錄回滾時刪除（僅空目錄）；系統邊界操作（如 pnpm install、殺進程）會標記「需手動補償」。
回滾¶
對應工具是 dsh_doctor_rollback，命令行是 dsh-doctor rollback。回滾按 LIFO 逆序執行，恢復到修復前。rollback --list 可以列出所有修復日誌，rollback --id <id> 可以回滾指定的一條。
運行時自愈服務¶
除了離線 CLI，dsh-doctor 還以 Cordis 服務的形態接入運行中的 DSH：
- 通過
ctx.provide暴露診斷/修復/回滾 API 給其他插件（服務名dsh-doctor）； - 通過
ctx.on('internal/status')響應式監控插件生命週期，檢測到 FAILED 自動告警； - 通過
ctx.effect()聲明可逆效應，卸載無殘留。
也就是說，DSH 存活時它能動態診斷和監控，而不是隻能停機修。
自包含 CLI 與跨平臺¶
dsh-doctor 是自包含 CLI，不依賴 DSH 運行。即使 DSH 崩潰到插件都加載不了，也能直接執行 dsh-doctor fix。支持 Windows / macOS / Linux / fish，安裝後自動註冊到系統 PATH，也可用 dsh-doctor setup 手動註冊。
安裝與啓用¶
方式一，作爲 DSH 插件安裝，在 Agent 內使用：
dsh plugin --profile web add @jorinyang/dsh-doctor
dsh web
第一條命令從 npm 安裝插件，第二條重啓 dsh web 使其生效。
方式二，全局安裝 CLI，在命令行直接使用：
npm install -g @jorinyang/dsh-doctor
# 或者免安裝直接運行
npx @jorinyang/dsh-doctor
插件的 peerDependencies 爲 @deepseek-ai/cordis ^4.0.1-rc.1、@deepseek-ai/dsh-tools、@deepseek-ai/schemastery ^3.18.1-rc.1。
典型用法¶
最基礎的流程是先診斷、再修復：
dsh-doctor # 只讀診斷（默認行爲，別名 diagnose / check）
dsh-doctor fix # 修復（別名 repair）
診斷輸出長這樣（示例來自項目 README）：
DSH Diagnostic Report (profile: web, port: 3080)
DSH home: ~/.dsh
[OK] Node.js v24.15.0
[OK] pnpm 11.9.0
[OK] DSH 0.1.0-rc.6
...
[XX] bundle missing: some-broken-plugin
fix: Run pnpm install in profile dir
48 pass 0 fail 3 warn
回滾相關：
dsh-doctor rollback # 回滾最近一次修復
dsh-doctor rollback --list # 列出所有修復日誌
dsh-doctor rollback --id <id> # 回滾指定日誌
在 Agent 內使用時，直接在對話中告訴 agent：
運行 dsh_doctor # 診斷
用 safe 範圍運行 dsh_doctor_fix # 修復
運行 dsh_doctor_rollback # 需要時回滾
通用選項有三個：--profile <name> 指定 DSH profile（默認 web）、--port <number> 指定 Web 端口（默認 3080）、--scope <level> 指定修復範圍（safe / deps / full，默認 safe）。
關於範圍選擇，三檔是按風險遞進的：建議從 safe 開始，只動文件和配置；沒解決再升級到 deps 重裝依賴；最後才考慮 full 清理進程。
適用場景與注意¶
適合的人羣：經常折騰 DSH 插件和 profile 的開發者，尤其是需要保證 DSH 可用、不想在崩潰排查上耗時間的人。它不要求你讀懂報錯，診斷報告會直接給出問題點和修復建議。
使用前有幾點需要注意：
full範圍會終止殘留進程，執行前確認沒有正在運行的關鍵任務；- 系統邊界操作（如
pnpm install、殺進程）無法自動撤銷，journal 中會標記「需手動補償」，回滾後留意這類改動； - 插件以當前 dsh 進程的權限運行，安裝前建議檢查源碼與許可證。dsh-doctor 採用 MIT 許可證，源碼在 GitHub 上可以直接查看。
結尾¶
dsh-doctor 把 DSH 崩潰後的處理流程收斂成了三步：dsh-doctor 診斷、dsh-doctor fix 修復、dsh-doctor rollback 回滾，配合運行時自愈服務，讓「修壞了」這件事本身也可控。
項目主頁：https://github.com/jorinyang/dsh-doctor
社區目錄頁：https://www.skillhub.cn/plugins/jorinyang/dsh-doctor（社區目錄爲獨立站點，與 DeepSeek / 幻方無官方從屬關係）
