DSH Plugin Upgrade Skill
简体中文 | English
教 AI 帮你升级 DSH 插件的 skill 集合，社区共建。
DSH（DeepSeek Harness） 是一个"所有功能都以插件形式存在"的 AI 运行框架。麻烦在于：DSH 每次发新版，老插件就可能启动不了。本仓库把已知的坑整理成 AI 读得懂的升级手册，让 Claude Code、Codex、Gemini 等 agent 帮你把插件安全迁到新版本，并用一套公开的 benchmark 检验这件事到底有没有做对。
📄 论文：Evaluating Agent Skills for Version-Specific Plugin Migration: A Retrospective Study（arXiv:2609.30120）。评估方法与主要发现见论文一节。
这个仓库里有什么
- 238 张升级说明卡：每张卡记录一个真实的坑——什么坏了、为什么坏、怎么修、信息来自哪个版本。按版本走廊排好序，覆盖 0.1.0-rc.8 → 0.2.1-rc.5，并在 rc.4 处分出 0.2.2-alpha.2 一支（其中 0.1.7-rc.1 → 0.1.7-rc.2 一段尚未成卡），每条边的卡数与状态见下方覆盖表。
- 13 条通用对策：与具体版本无关的坑（先备份、新旧共存、启动卡死怎么办等），集中在一份清单里。
- 12 个 skill：统一工作流负责选择与编排，另外十个分别负责查升级、直连官方升级指南做快速适配、写插件、测插件、发插件、对比两个版本、排查运行时故障、接入重依赖、宿主升级后巡检整批已装插件、把升级经验提取成考题；还有一个不含 DSH 专有知识的通用迁移方法论，用作对照实验的控制组。
- 65 道自动判分的考题（benchmark）：27 道笔试（读代码给答案）、38 道实操（真装 dsh 真跑插件），其中包含 dsh-web 与 dsh-data-agent 两次真实迁移。
- 一篇论文和完整的评估证据：从原始回答、逐条评分到跨模型复评全部公开可复算，见下方论文。
快速开始
使用 skills CLI（推荐）
一条命令装到它支持的 agent：
npx skills add oh-my-dsh/dsh-plugin-upgrade-skill
Claude Code
Marketplace 安装：
/plugin marketplace add oh-my-dsh/dsh-plugin-upgrade-skill
/plugin install dsh-plugin-upgrade-skill
**SSH 错误？**如果没有配置 GitHub SSH 密钥，使用 HTTPS URL：
/plugin marketplace add https://github.com/oh-my-dsh/dsh-plugin-upgrade-skill.git
/plugin install dsh-plugin-upgrade-skill
本地/开发模式：
git clone https://github.com/oh-my-dsh/dsh-plugin-upgrade-skill.git
claude --plugin-dir /path/to/dsh-plugin-upgrade-skill
Codex
先添加 marketplace，再在 Codex 的插件界面中安装/启用该插件：
# GitHub marketplace
codex plugin marketplace add oh-my-dsh/dsh-plugin-upgrade-skill
# 本地开发 marketplace
git clone https://github.com/oh-my-dsh/dsh-plugin-upgrade-skill.git
codex plugin marketplace add ./dsh-plugin-upgrade-skill
当前 Codex CLI 没有直接安装子命令；GitHub 与本地路径都通过 plugin marketplace add 注册。
Gemini CLI
直接从仓库或本地克隆安装：
# 从仓库
gemini skills install https://github.com/oh-my-dsh/dsh-plugin-upgrade-skill.git --path skills
# 本地
git clone https://github.com/oh-my-dsh/dsh-plugin-upgrade-skill.git
gemini skills install ./dsh-plugin-upgrade-skill/skills/
Cursor
将 skills/ 复制到 .cursor/skills/：
git clone https://github.com/oh-my-dsh/dsh-plugin-upgrade-skill.git
cp -r dsh-plugin-upgrade-skill/skills/* .cursor/skills/
怎么用
Claude Code 中按名字调用 skill（插件安装后带命名空间）：
/plugin-workflow
/dsh-plugin-upgrade-skill:plugin-workflow
/plugin-upgrade 0.1.2
/dsh-plugin-upgrade-skill:plugin-upgrade 0.1.2
首次只调用统一入口、尚未说明目标流程时，它会先列出 9 个工作流程和 14 项可选能力，推荐只读
health-check 但不会自动执行。回复流程编号或名称，并按需增减能力后，它才会生成阶段账本并开始：
选择 1
选择 compatibility-migration，加上 docker-smoke 和 browser-check
也可以直接在对话中提问（任意 agent），skill 按描述自动触发；只读检查直接给结果，升级或迁移会先出计划再等确认：
先检查这个 DSH 插件，让我选择要不要升级、测试、查云端命名或发布
我需要把插件从 0.1.1 升级到 0.1.2，有哪些破坏性变更？
帮我把 dsh-ads 这个插件升级到 dsh-v0.1.2-alpha.2
校验这个插件的命名并查询中央注册表；保留索引 URL 和 SHA-256，不要提交注册
naming-registry 默认执行离线命名校验和只读中央查询；中央注册仍是单独的外部发布步骤。
代理网络下使用 Node 24+ 的 node --use-env-proxy 运行查询，Node 20-23 不保证内置 fetch
自动读取代理环境变量。查询失败、索引超限或 v2 契约不合法都表示“未知/未检查”，不能解释为名称可用。
12 个 skill 各自管什么
升级卡覆盖到哪个版本了
| 版本区间 | 状态 | 说明卡 | 备注 |
|---|
| 0.1.0-rc.8 → 0.1.1-rc.1 | 📝 草稿 | v0.1.1-rc.1.md | 9 张草稿卡（vlln 插件迁移：repository 机制移除、strict inject、0812 服务改名等；走廊为 0810–0812 内测快照窗口的最近公开 tag 对齐，待上游复核） |
| 0.1.1-rc.1 → 0.1.1-rc.2 | ✅ 完成 | v0.1.1-rc.2.md | 3 张卡 |
| 0.1.1-rc.2 → 0.1.2-alpha.1 | ✅ 完成 | v0.1.2-alpha.1.md | 28 张卡 |
| 0.1.2-alpha.1 → 0.1.2-alpha.2 | ✅ 完成 | v0.1.2-alpha.2.md | 8 张卡 |
| 0.1.2-alpha.2 → 0.1.2-alpha.3 | ✅ 完成 | v0.1.2-alpha.3.md | 2 张卡（A3-01 新增 settings.plugin.item keyed-slot 设置卡能力；A3-02 移除可选 SQLite Session 持久化后端，opt-in 部署需旧版导出） |
| 0.1.2-alpha.3 → 0.1.2-alpha.4 | ✅ 完成 | v0.1.2-alpha.4.md | 6 张卡（report → send_message、Python 运行时包改名、Session.events 移除、seq 强类型、PTC workflow 与 base web_fetch 默认值；三台真宿主验证） |
| 0.1.2-alpha.4 → 0.1.2-alpha.5 | ✅ 完成 | v0.1.2-alpha.5.md | 3 张卡（storage 域 compatibleVersions 读兼容与 兜底；旧家升级拒启/标题丢失修复；storage 层复现核对） |
考题（benchmark）
benchmark/ 目录下有 65 道升级考题和自动判分，采用 Harbor 任务格式：每题一个自包含任务（自带 DSH 环境的容器 + 自动 verifier），harbor run -p benchmark/tasks/<题号> -a <agent> 即可得到 0~1 分。同一个 agent 装 skill 做一遍、不装做一遍，分差就是 skill 的实际效果。多个模型与 agent 的实测结果和完整报告列在 benchmark/README.md，报告原文在 benchmark/results/。
论文
我们把这个 skill 的评估写成了一篇回顾性研究：arXiv:2609.30120。它关注的问题是：分数提高了，是否说明迁移建议真的满足了目标版本的契约？
- 分数提升：在 16 道静态迁移诊断题、64 份回答上，挂载 skill 后平均得分从 93.83 升到 98.75（+4.92，95% 区间 [0.31, 10.86]）。提升集中在少数题目，8 组题两边都已满分。
- 契约层面的检查：把 328 条评分决策逐条对到版本契约，并用可执行探针复核，发现了评分本身的问题，例如一个会放过父目录的路径守卫仍拿到满分。分数高不等于建议正确。
- 跨模型复评：用另外两个模型家族（Claude Opus 5.5、GPT-5.5）在不知道分组、也看不到原分数的条件下重评全部 64 份回答，与原评审的一致率为 91.8% 和 95.7%，重算的提升为 +10.63 和 +6.09，方向一致、幅度随评审而变。
- 可复算：原始回答、评分、复核、复评协议与脚本都在仓库里，入口见 paper/。
局限（单一框架、静态诊断、尚无独立人工标注与对照组）在论文中如实说明，后续工作也已列出。
参考资源
项目里直接用
使用统一工作流时，把整个 skills/ 目录复制到项目里，因为 plugin-workflow 会把每个阶段交给另外五个 owning Skill。只需要升级能力时，也可以单独复制 skills/plugin-upgrade/：
<your-project>/.agents/skills/
├── plugin-workflow/
├── plugin-upgrade/
├── plugin-write/
├── plugin-test/
├── plugin-release/
└── dsh-upgrade-audit/
注意保留里面的 SKILL.md 和 references/ 文件夹，别只复制一个文件。也可以让 DSH 本地的 skill 加载方式直接指向本仓库的 skills/ 目录。
仓库目录
skills/<skill-name>/
├── SKILL.md # skill 的说明书（怎么触发、怎么干活）
├── references/ # 升级说明卡和详细资料
├── scripts/ # 可执行的小工具（含迁移规划器、工作流计划器和运行时验证器）
└── examples/ # 示例代码（只读，不要运行）
scripts/validate.mjs # 仓库自检
scripts/validate-manifests.mjs # 多 agent 清单自检
benchmark/ # 65 道考题 + 判分 + 验证报告
想贡献？
CI 分层、工作流组合回归和真实模型对照评测入口见
Skill CI 说明。参考答案测试通过不代表模型已正确使用 Skill。
- 按 skills/README.md 的规范写；
- 升级卡按 卡片格式 填；
- 跑两条自检命令，全绿再提 PR：
node scripts/validate.mjs
node scripts/validate-manifests.mjs
引用
如果本仓库或论文对你的工作有帮助，请引用：
@misc{liu2026evaluating,
title = {Evaluating Agent Skills for Version-Specific Plugin Migration: A Retrospective Study},
author = {Liu, Beiming and Li, Haihao and Chen, Minjie and Chen, Ning and Wang, Yiran and Ye, Jiming and Zhang, Puzhao and Wang, Tongtao and Gao, Sheng and Jin, William and Mu, Weihao and Liu, Chengzhi and Xia, Yucheng and Wang, Guangren and Fan, Chaoyang and Huang, Changfeng and Lin, Xunming and Shen, Yuanjie},
year = {2026},
eprint = {2609.30120},
archivePrefix = {arXiv},
primaryClass = {cs.SE},
url = {https://arxiv.org/abs/2609.30120}
}
致谢
论文作者与所有提交过 PR 的贡献者共同建设了本仓库，完整名单见 Contributors。
License
MIT
