v0.1.0-alpha.1

v0.1.0-alpha.1

English | 简体中文

English

What is this?

This repo teaches AI coding agents (Claude Code, Codex, Gemini, etc.) how to upgrade dsh plugins when dsh itself releases a new version. It is a collection of 5 skills plus a community-maintained version corridor: for each dsh version pair, we write migration cards that record what broke, why it broke, and how to fix it — each card pinned to exact source tags.

What do you get in this release?

• 30 migration cards covering the full corridor 0.1.1-rc.1 → 0.1.1-rc.2 (3 cards) → 0.1.2-alpha.1 (20 cards) → 0.1.2-alpha.2 (7 cards)
• 12 corridor-level recipes (R-01R-07, R-10R-12) for cross-version problems that single cards don't cover: running old and new dsh side by side, recording a failure baseline before you migrate, retrying boot races, the type-drift ledger, and a safety rule for when the plugin you are upgrading is part of the host you are running on
• 5 skills:
  • plugin-upgrade — decides how to migrate your plugin, step by step
  • plugin-write — writes new plugins, with naming rules and a central name-registry query
  • plugin-test — picks the right test level, plus a Docker smoke runner
  • plugin-release — release checks, including an executable verify-release guard
  • dsh-upgrade-audit — audits what changed between two dsh versions
• A central plugin registry (dsh-plugin-registry) so new plugins can reserve names and avoid collisions

Why is this an alpha?

All cards were verified against dsh 0.1.2-alpha.2. When dsh ships 0.1.2 final, we need to re-check every card against the final tags before calling this stable. Recipe numbers R-08 and R-09 are reserved for community contributions already in review.

How do I use it?

npx skills add oh-my-dsh/dsh-plugin-upgrade-skill

Verified

Every merge passed the repo's own checks (card schema, corridor integrity, manifest consistency) on Node 22 and 24. A full container-based validation (reproducing the pending (waiting for service: apiProxy) failure of an old plugin on dsh 0.1.2-alpha.2, then migrating it successfully) is documented in docs/validation-report-2026-08-30.md.

Contributors

hikariming, ccch1mneyyy (Chimney), whiteicey, Chris Yang, yejiming, Nagi-ovo (Jesse Zhang), taekchef (changfenhuang), t4wefan, zp-home, AdamPlatin123, Alex, notnotype, SenmuuuuW, titanwings (Tianyi Zhou), huiliyi37, lhh010, goatliamia, william-jin-cmu — plus tianyicui, who started the upstream discussion (#5120) that kicked this off, and everyone who shared real migration pain points.

---

简体中文

这是什么？

这个仓库教 AI 编程助手（Claude Code、Codex、Gemini 等）在 dsh 升级后怎么改插件。它包含 5 个 skill，外加一条社区维护的版本走廊：每个 dsh 版本区间配一组迁移卡，写清什么坏了、为什么坏、怎么修——每张卡都锚定精确的源码 tag。

这个版本里有什么？

• 30 张迁移卡，覆盖完整走廊 0.1.1-rc.1 → 0.1.1-rc.2（3 张）→ 0.1.2-alpha.1（20 张）→ 0.1.2-alpha.2（7 张）
• 12 条走廊层配方（R-01R-07、R-10R-12），处理单张卡覆盖不了的跨版本问题：新旧 dsh 共存、迁移前先记录失败基线、启动竞态重试、类型漂移清单，以及"你升级的插件可能就是当前运行宿主的一部分"这条安全红线
• 5 个 skill：
  • plugin-upgrade——判断你的插件该怎么迁移，一步步执行
  • plugin-write——写新插件，带命名规则和中央注册表查重
  • plugin-test——选对测试层级，附带 Docker 冒烟测试
  • plugin-release——发布检查，含可执行的 verify-release 守卫
  • dsh-upgrade-audit——审计两个 dsh 版本之间变了什么
• 中央插件注册表（dsh-plugin-registry），新插件可以预留名字、避免撞名

为什么叫 alpha？

所有卡片都按 dsh 0.1.2-alpha.2 核对过。dsh 0.1.2 正式版发布后，我们要按正式 tag 逐张复核，复核完才敢叫稳定版。R-08、R-09 两个编号预留给正在审核的社区贡献。

怎么用？

npx skills add oh-my-dsh/dsh-plugin-upgrade-skill

验证情况

每次合入都过了仓库自检（卡片格式、走廊完整性、清单一致性），CI 跑 Node 22 和 24 双版本。我们还做了完整的容器验证：先在 dsh 0.1.2-alpha.2 上复现旧插件的 pending (waiting for service: apiProxy) 启动失败，再按卡片迁移成功，报告全文在 docs/validation-report-2026-08-30.md。

贡献者

hikariming、ccch1mneyyy（Chimney）、whiteicey、Chris Yang、yejiming、Nagi-ovo（Jesse Zhang）、taekchef（changfenhuang）、t4wefan、zp-home、AdamPlatin123、Alex、notnotype、SenmuuuuW、titanwings（Tianyi Zhou）、huiliyi37、lhh010、goatliamia、william-jin-cmu——还有上游 discussion #5120 的发起者 tianyicui，以及所有分享过真实迁移踩坑记录的同学。