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