Metadata-Version: 2.4
Name: xdsdk-upgrade
Version: 0.6.4
Summary: XDSDK v6→v7 升级工具：Skill + CLI + AST 工具链
Author-email: XD Global SDK Team <sdk@xd.com>
License: MIT
Project-URL: Homepage, https://git.gametaptap.com/xdpt/clientsdk/xdsdk-upgrade-tool
Project-URL: Issues, https://git.gametaptap.com/xdpt/clientsdk/xdsdk-upgrade-tool/-/issues
Keywords: xdsdk,ue,unity,upgrade,ast,claude-skill
Classifier: Development Status :: 4 - Beta
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Code Generators
Classifier: Operating System :: OS Independent
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Requires-Dist: pyyaml>=6.0
Requires-Dist: tree-sitter>=0.23
Requires-Dist: tree-sitter-c-sharp>=0.23
Requires-Dist: tree-sitter-cpp>=0.23
Provides-Extra: mcp
Requires-Dist: mcp>=1.0; extra == "mcp"
Provides-Extra: sync
Requires-Dist: ruamel.yaml>=0.18; extra == "sync"

# 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 清单
- 生成升级报告，辅助开发者继续编译、运行和验证

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

## 安装

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

默认会安装到：

- `~/.claude/skills/` for Claude Code
- `~/.codex/skills/` for Codex

只安装某一端：

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

## 使用

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

Unity：

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

UE：

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

然后对 agent 说：

```text
升级 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 工具。
