Dsh Create Upgrade Guide

---
name: dsh-create-upgrade-guide
description: "外部可见行为或已发布接口发生不兼容变化，或修改现有升级指南覆盖的功能时使用。"
---

# dsh-create-upgrade-guide

本 Skill 仅用于当前项目。用户授权、项目 AGENTS.md 和实际宿主能力优先。

## 是否需要指南

面向升级后会遇到外部可见破坏的用户：CLI/flags、配置键及有效值、持久数据、SDK/wire API、发布包名与入口。发现 break 就在同一变更中写，不拖到发布时。只供仓内使用且所有调用者同改的内部接口，不因改名自动新增指南。

先核对所属组件的实际发布版本、起点版本与目标版本、受影响用户及现有指南。指南描述一个明确升级区间，不能从根目录版本猜测可选包的版本，也不能把源码 HEAD 当成已发布安装。

## 内容与维护

复用项目现有文档位置；没有固定模板时用“变更 / 迁移”两段：

- 变更：谁受影响、旧行为、新行为、何时触发，不写长篇实现史。
- 迁移：按执行顺序给出前提/备份、确切文件/键/命令/符号、成功后的可观察结果，以及失败/中断时恢复办法。持久数据破坏或不可回退要在动作前说明；不要承诺不存在的自动迁移或 rollback。

详细理由链接现有决定/格式记录；重复机械操作优先用已有验证过的工具，不复制其实现到文档。保持常用路径简短，不套用 DSH 的固定目录、500 词 gate 或三文件格式。

同一未发布升级区间内再次修改该功能，更新同一指南；break 被撤销时清理对应未发布说明及入站引用。已经发布的历史指南保留其版本事实，新的变化进入新升级区间，不静默改写历史。双方文档按本项目双语规则同步。

## 验证

在获授权的隔离/可恢复环境中，从实际旧状态执行迁移到新状态并核对结果；涉及不可逆、生产或权限不足的命令不因“文档验收”自动执行。记录准确版本、命令、结果和未执行步骤。检查链接、配置键、接口名、双语含义与项目验证；指南写完不代表迁移已完成。

来源、适配边界和许可证见 [provenance.md](provenance.md)。