dsh-api-watch

DSH（DeepSeek Harness）插件 API 面的自动化比对引擎 + 变更档案 + Agent Skill。 目标：让第三方插件开发者在升级 DSH 之前，一条命令看清「我依赖的 API 变了没有、坏在哪里、怎么改」。

为什么需要

DSH 处于高频迭代期（0.1.x → 0.2.x），插件 API 经常破坏性变更，但官方：

• 不维护 CHANGELOG.md；
• Discussions 里的破坏性变更说明靠社区人肉撰写，覆盖不全、时滞不定。

而官方 checkout 的 git 历史 + docs/cordis-api / docs/subsystems 文档层是最准的事实源。 本项目把它自动化。

组成

dsh-api-watch/
├── skill/SKILL.md            # Agent Skill 入口：升级前比对的规程
├── scripts/
│   ├── diff-api.ps1          # 核心：对比两个 dsh ref 的插件 API 面，产出 json + md 报告
│   ├── scan-plugin.ps1       # 拿报告扫你的插件源码，产出「改动点/风险点」影响分析
│   └── detect-breaking.ps1   # CI 门禁：读 report.json，按严重级别给退出码
├── scripts/radar.ps1         # 反馈雷达：官方 Discussions + 全站 issues/PR 每日摘要
├── registry.json             # 你的插件 → 依赖的 API 面 声明清单（v1 过滤 + 扫描共用）
├── archive/                  # CI 自动维护：每版本对一份 impact report
├── docs/
│   ├── architecture.md       # 架构与方案（必读）
│   └── api-surface.md        # 「插件 API 面」的范围定义
└── .github/workflows/watch.yml  # 定期盯官方 repo，出新 tag 自动生成报告并提交

安装

作为 DSH 插件安装（主进程入口会把随包的 dsh-api-watch skill 注册到 ctx.skills）：

dsh plugin --profile web add github:2DogsLee/dsh-watcher

仅安装 skill

手动安装（复制目录）：

git clone https://github.com/2DogsLee/dsh-watcher.git
Copy-Item dsh-watcher/skill "$env:USERPROFILE\.dsh\skills\dsh-api-watch" -Recurse

或一键拉取单个 SKILL.md：

New-Item -ItemType Directory -Force -Path "$env:USERPROFILE\.dsh\skills\dsh-api-watch" | Out-Null
irm https://raw.githubusercontent.com/2DogsLee/dsh-watcher/main/skill/SKILL.md -OutFile "$env:USERPROFILE\.dsh\skills\dsh-api-watch\SKILL.md"

安装后重启 DSH，说「升级 DSH 前帮我做升级影响分析」即触发规程。 注意：比对与扫描需要本地有官方 checkout 和本仓库脚本，skill 只含规程——建议整个仓库 clone 后使用，并让 Agent 知道 $TOOL 路径。

每日情报

• 逐版本插件 API 面报告：Releases（随官方新 tag 自动发布）
• 每日反馈雷达（官方 Discussions + 全站 issues/PR，★ 为通用插件相关条目）：archive/radar/digest.md

快速使用

# 1. 配置官方 checkout 路径（一次性）
$env:DSH_CHECKOUT = "D:\path\to\deepseek-harness-checkout"

# 2. 比对两个版本
./scripts/diff-api.ps1 -From dsh-v0.1.7-rc.2 -To dsh-v0.2.0-rc.2

# 3. 读报告
#    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 （机读，可接 CI 门禁）

作为 skill 使用

把本仓库 clone 到任意位置，在你的 AGENTS.md / skill 目录里引用 skill/SKILL.md。 DSH Agent 会在「升级 DSH / 插件报接口错误」时按规程先跑比对再动手改代码。

CI 自动跟进（fork 即用）

.github/workflows/watch.yml 每天（可配）拉官方 repo 的新 tag，自动生成上一稳定版 → 新版的 报告并 commit 到 archive/，同时发 GitHub Release。零人工维护。

破坏性判定（当前启发式）

信号	级别
包被删除 / 从 workspace 移除	breaking
导出符号（export）被删除	breaking
docs/cordis-api / docs/subsystems 文档删除或改名	breaking
插件配置字段被删除 / 配置包从 config-catalog 移除	breaking（cordis.yml/settings 里写的这些字段将失效）
settings schema 字段删除/改名	breaking
官方新增 upgrade-guide 条目	warning（上游承认存在需迁移的变更）
文档大改（>30% 行变化）	warning
exports map / 包级变化需人工确认	warning
新增包/导出/文档/配置字段	info

启发式刻意保守：宁报 warning 不漏报 breaking，但每条 breaking 都附 diff 位置供人工确认。 误报请提 issue，我们会收紧规则。

License

MIT