前言¶
DeepSeek Harness (DSH) 處於高頻迭代期，插件 API 經常發生破壞性變更。官方通常不維護 CHANGELOG.md，社區 Discussions 中的說明依賴人工撰寫，存在覆蓋不全和滯後的問題。
dsh-watcher 是一個 API 面自動比對引擎，用於升級前一條命令看清依賴的 API 與配置字段是否變更、變更範圍及具體影響。它以官方倉庫的 git 歷史和 docs/cordis-api / docs/subsystems 文檔層作爲事實源，提供 AST 級別的差異分析。
核心功能¶
dsh-watcher 提供以下核心能力：
* AST-level breaking-change diff：對插件 API 面進行語法級別的破壞性變更檢測。
* Plugin impact analysis：分析變更對你的插件源碼產生的具體影響。
* Daily feedback radar：彙總官方 Discussions 和全站 issues/PR 的每日摘要。
* Agent skill：提供升級前比對的規程，Agent 可按規程執行。
* CI watch：支持 CI 環境，定期監控官方倉庫並自動生成報告。
安裝與啓用¶
作爲 DSH 插件安裝，主進程入口會將隨包的 skill 註冊到 ctx.skills：
dsh plugin --profile web add github:2DogsLee/dsh-watcher
前置條件：
* 本地需要有 DeepSeek Harness 官方倉庫的 checkout，路徑需包含 docs/cordis-api 和 docs/subsystems。
* 本插件僅包含規程，實際運行的腳本需要克隆本倉庫。
啓用方式：
安裝後重啓 DSH。當需要升級 DSH 或插件報接口錯誤時，Agent 可按規程先運行比對再修改代碼。
典型用法¶
- 配置官方倉庫路徑（一次性配置）：
$env:DSH_CHECKOUT = "D:\path\to\deepseek-harness-checkout"
- 執行版本比對：
./scripts/diff-api.ps1 -From dsh-v0.1.7-rc.2 -To dsh-v0.2.0-rc.2
- 查看報告：
- 人類閱讀：
archive/0.1.7-rc.2_to_0.2.0-rc.2/report.md - 機器讀取：
archive/0.1.7-rc.2_to_0.2.0-rc.2/report.json
- 人類閱讀：
破壞性判定啓發式¶
當前採用保守啓發式規則，寧報 warning 不漏報 breaking。主要判定信號如下：
| 信號 | 級別 |
|---|---|
| 包被刪除 / 從 workspace 移除 | breaking |
| 導出符號被刪除 | breaking |
docs/cordis-api / docs/subsystems 文檔刪除或改名 |
breaking |
| 插件配置字段被刪除 / 配置包從 config-catalog 移除 | breaking |
| settings schema 字段刪除/改名 | breaking |
| 官方新增 upgrade-guide 條目 | warning |
| 文檔大改（>30% 行變化） | warning |
| exports map / 包級變化需人工確認 | warning |
| 新增包/導出/文檔/配置字段 | info |
注意事項¶
- 保守策略：該工具旨在減少漏報，因此可能會產生部分誤報。如遇誤報，建議通過提 issue 反饋以收緊規則。
- 環境要求：比對與掃描腳本需要完整克隆本倉庫，Skill 僅包含規程說明。
- 許可證：MIT License。
