xdsdk-upgrade 0.6.4

XDSDK v6→v7 升级工具：Skill + CLI + AST 工具链

xdsdk-upgrade

XDSDK v6 -> v7 升级 Skill，覆盖 Unity 和 UE (Unreal Engine) 项目。

这个项目的主体不是一个给接入方直接操作的 CLI，而是一套给 Claude Code / Codex 使用的升级 Skill。CLI、YAML 规则和 examples 是 Skill 的配套能力，用来做项目预扫、机械化改动、残留检测和升级报告。

适用场景

当游戏项目需要把 XDSDK 从 6.x 升级到 7.x 时，在项目目录启动 Claude Code 或 Codex，让 agent 按 Skill 执行升级。

Skill 会协助完成：

• 识别 Unity / UE 项目的 XDSDK v6 接入方式
• 执行可机械化的改动，例如 package/plugin 替换、using/include 清理、方法/类型/字段重命名
• 根据 YAML 规则和 examples 处理常见 breaking changes
• 把无法安全自动改写的调用点整理成 review 清单
• 生成升级报告，辅助开发者继续编译、运行和验证

它不适合作为无人值守的自动化升级入口，也不承诺自动消除所有编译错误。最终仍需要开发者在本地编译项目、运行测试，并按报告处理业务语义变化。

安装

pip install xdsdk-upgrade
xdsdk-upgrade install-skill --engine all

默认会安装到：

• ~/.claude/skills/ for Claude Code
• ~/.codex/skills/ for Codex

只安装某一端：

xdsdk-upgrade install-skill --engine unity --target codex
xdsdk-upgrade install-skill --engine ue --target claude

使用

进入要升级的项目目录，启动 agent。

Unity：

cd /path/to/unity-project
codex   # 或 claude

UE：

cd /path/to/ue-project
codex   # 或 claude

然后对 agent 说：

升级 XDSDK 到 v7

Skill 会根据当前项目类型选择 Unity 或 UE 的升级流程。底层的 scan / apply / report / ci-check 等 CLI 命令由 Skill 在需要时调用，接入方通常不需要直接执行。

重要边界

• 所有 v7 API 调用都应以项目本地 SDK 头文件 / 源码为准，不能凭经验猜。
• SDK 自身文件不应被逐文件手改；Unity package 或 UE plugin 应按发布产物整体替换。
• UE 的签名变化、业务语义变化和编译错误不能只靠 grep 判断，必须结合编译结果和 review 清单处理。
• CLI 是 Skill 的辅助工具，不建议把它单独包装成一键自动化升级流程。

反馈

升级中遇到以下问题时，把编译错误日志 + 文件:行号 + 相关调用代码反馈给 SDK 团队：

• v7 API 跟 Skill / examples 描述不一致
• 模板生成的代码编译失败
• Agent 漏改、误改或无法判断替代方案

SDK 团队会把确认后的差异补回规则、examples 或 CLI 工具。