前言¶
DSH 的理念是「一切皆插件」，一個 profile 的最終行爲通常來自多組 patch 層疊加。問題在於，某些配置錯誤不會讓 dsh 啓動失敗，而是讓配置靜默不生效。dsh-doctor 是 asdf17128 維護的健康檢查工具，用於檢查 DeepSeek Harness（dsh）profile 中被補丁丟掉、失效或未被加載的配置項。下面介紹它的檢查範圍、用法和需要注意的邊界。
這是什麼¶
dsh-doctor 的定位是：Health check for your DeepSeek Harness (dsh) profile — finds config fields your patches silently dropped, dead patches, and unmaintained plugins.
它可以用兩種方式使用：
- 作爲命令行工具，直接檢查一個 dsh profile。
- 作爲 dsh 插件安裝到 profile，註冊
config_doctor工具。
許可證爲 MIT。
核心檢查項¶
dsh-doctor 會檢查以下類型的問題：
config-clobber：補丁整體替換某個 entry 的config後，未重寫的默認字段丟失。dead-patch：補丁指向不存在的 entry id，導致補丁不生效。tool-collision：兩個掛載插件註冊相同工具名，導致 dsh 拒絕啓動。plugin-not-mounted：已安裝但從未被加載的插件。plugin-stale：180 天以上無 npm 發佈的第三方插件。entry-removed：補丁層移除的 shipped entry。entry-toggled/entry-added：與 shipped profile 的其他差異，作爲 info 提示。
先做基本檢查，再用 --explain 查看當前 profile 樹，是比較順手的使用順序。
工作原理¶
dsh-doctor 通過 dsh 自己的配置合成結果做差分：
dsh --profile <p> --dump-config
dsh --profile <p> --dump-default-config
第一條命令給出實際啓動的 profile 樹，第二條命令給出不帶用戶層的默認樹。dsh-doctor 將兩者差異歸因到用戶補丁層。檢查過程中不會啓動插件，也不會評估配置中的 !!js 表達式。
安裝與啓用¶
作爲命令行工具，可以直接運行：
npx dsh-doctor
如果要作爲 DSH 插件安裝到 web profile：
dsh plugin --profile web add github:asdf17128/dsh-doctor
安裝後，它會在該 profile 註冊 config_doctor 工具。移除時使用：
dsh plugin --profile web remove dsh-doctor
典型用法¶
常用命令如下。
基本檢查：
npx dsh-doctor
檢查另一個 profile：
npx dsh-doctor --profile headless
查看 profile 樹：
npx dsh-doctor --explain
--explain 會描述 profile 樹中的 active、disabled、conditional 等狀態。對於 disabled: 爲 !!js 表達式的 entry，報告會將其標爲 conditional，因爲實際啓用狀態取決於啓動機器，而不是檢查時求值。
輸出與運行選項：
npx dsh-doctor --verbose
npx dsh-doctor --json
npx dsh-doctor --offline
npx dsh-doctor --quiet
如果確認需要修復合併丟失字段：
npx dsh-doctor --fix
–fix 的邊界¶
--fix 會寫入文件。它只將被標記的丟失字段重新寫入同一個 config 塊，並在寫入前創建 .bak。dead-patch 不會自動修復，因爲重命名還是刪除由用戶決定。
退出碼¶
0：乾淨或僅警告。1：至少一個錯誤。2：無法檢查。
經過上面的步驟，可以在本地工作流中根據退出碼判斷是否需要繼續處理。
適用場景與注意¶
適合：
- 維護 DSH profile 的智能體開發者。
- 在 dsh 版本變更後確認 patch 是否仍有效。
- 需要把 profile 配置問題作爲錯誤信號處理的工作流。
注意：
- 需要 Node 18+ 和可用的
dsh；優先使用本地node_modules/.bin/dsh，否則使用PATH中的dsh。 - 已驗證兼容
@deepseek-ai/dsh 0.1.0-rc.5。dsh 處於開發者預覽，並可能引入破壞性變更。 --fix會寫入文件，但只寫入被標記的config塊，並先創建.bak。- 在尚無 profile 的
$DSH_HOME上運行，可能由 dsh 創建profiles/<name>/模板目錄。 - 作爲 DSH 插件安裝並啓用後，它運行在當前 dsh 進程可用的權限範圍內。安裝前應檢查源碼，並確認 MIT 許可證符合你的使用要求。
鏈接¶
GitHub：https://github.com/asdf17128/dsh-doctor
目錄頁：資料未給出具體 URL，避免拼造；可在 DSH 社區目錄中搜索 dsh-doctor。
