xdsdk-upgrade 0.5.0

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

xdsdk-upgrade

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

目标：游戏接入方拿到工具就能在自己的项目里跑完整升级流程，0 编译错误交付。

支持的 LLM agent：

• ✅ Claude Code — 通过 ~/.claude/skills/ 自动触发 Skill
• ✅ Codex / Cursor / Cline — 通过 AGENTS.md 引导
• ✅ 任何 LLM — 直接用 CLI + 读 markdown 知识库

---

一、接入方使用（游戏侧）

1. 装 CLI

pip install xdsdk-upgrade

2. 选你用的 LLM agent

选项 A: Claude Code

xdsdk-upgrade install-skill --engine ue   # 拷 Skill 到 ~/.claude/skills/
cd /path/to/your-ue-project
claude

输入触发词："升级 XDSDK 到 v7"

选项 B: Codex / Cursor / Cline / 其他通用 agent

cd /path/to/your-ue-project
xdsdk-upgrade install-agents-md --project . --engine ue   # 生成 AGENTS.md
codex   # 或 cursor / cline

输入："升级 XDSDK 到 v7" （agent 自动读 AGENTS.md，里面引用了完整 examples/SKILL/breaking_changes 文档绝对路径）

选项 C: 直接 CLI（无 agent）

不用 LLM 也能跑机械改动：

xdsdk-upgrade apply --project /path/to/project \
  --replace-sdk-plugins --target-sdk-plugins /path/to/v7-sdk/Plugins \
  --comment-deprecated
xdsdk-upgrade scan --project /path/to/project   # 看哪些还要人工改

3. 直接 CLI 调用（不走 Claude）

# 扫描项目，看升级影响面
xdsdk-upgrade scan --project /path/to/project

# 一键应用机械改动（替换 plugin + AST 改名 + 自动注释）
xdsdk-upgrade apply --project /path/to/project \
  --replace-sdk-plugins --target-sdk-plugins /path/to/v7-sdk/Plugins \
  --comment-deprecated

# 完工后自检
xdsdk-upgrade verify-scope --project /path/to/project \
  --target-sdk-plugins /path/to/v7-sdk/Plugins
xdsdk-upgrade scan --project /path/to/project   # 看 residue.total_residue 是否为 0

# 生成升级报告
xdsdk-upgrade report --project /path/to/project --xd-version 7.X.Y

4. 子命令清单

命令	用途
scan	预扫升级影响面 + 残留检测
apply	执行机械改动（plugin 替换 / AST rename / 自动注释）
report	生成 UPGRADE_REPORT.md
verify-scope	审计是否越界改了 SDK plugin 自身
ci-check	CI 检测 v6 残留（exit 1 = 还有残留）
list-sdk-plugins	列出 SDK plugin 名单（接入方按此判断哪些目录禁改）
dashboard	多项目批量统计 markdown
batch	同时扫多个项目

---

二、SDK 团队工具（内部维护）

tools/ 下三个工具是 SDK 团队生成 yaml/examples 知识库用的，接入方不需要：

# 1. 从 v6/v7 git ref 生成 breaking change 列表
python -m tools.generate_ue_diff \
  --repo /path/to/xdsdk-6.0-ue \
  --from-ref origin/master --to-ref origin/v7/master \
  --output /tmp/diff

# 2. 从 demo 抽取真实 API 用法
python -m tools.extract_api_usages \
  --repo /path/to/xdsdk-6.0-ue \
  --ref origin/v7/master \
  --pattern "FXDGPayment::PayWithParams"

# 3. 整合上述 + 现有 yaml 输出缺口报告
python -m tools.build_api_compat \
  --diff-json /tmp/diff/diff_raw.json \
  --current-yaml rules/ue/v6_to_v7.yaml \
  --repo /path/to/xdsdk-6.0-ue \
  --output /tmp/api_compat

接入方机器不需要 v7 SDK git 仓库——所有规则数据通过 pip 包内置 rules/ue/v6_to_v7.yaml 分发。

---

三、架构

xdsdk-upgrade (pip 包)
├── cli.py                       # 接入方主入口
├── tools/
│   ├── cpp_rename.py            # UE C++ AST 改名（method/class/include + add_include + type_includes）
│   ├── comment_out.py           # 自动注释废弃 API（含多行整块 + dangling 检测）
│   ├── uplugin_check.py         # .uplugin 解析
│   ├── deps_check.py            # .Build.cs / .uplugin 依赖检测
│   ├── manifest_edit.py         # Unity Packages/manifest.json 编辑
│   ├── code_rename.py           # Unity C# AST 改名
│   ├── field_rename.py          # Unity C# 字段改名
│   ├── generate_report.py       # UPGRADE_REPORT.md 生成
│   └── (SDK 团队工具) generate_ue_diff / extract_api_usages / build_api_compat
└── rules/
    ├── ue/v6_to_v7.yaml         # UE 升级规则（数据驱动）
    └── unity/v6_to_v7.yaml      # Unity 升级规则

Skill 文档另装（~/.claude/skills/xdsdk-upgrade-ue-v6-to-v7/）：

• SKILL.md — Skill 触发 + 11 步流程
• examples.md — v6/v7 用法对照模板（25 个 case）
• breaking_changes.md — 完整 breaking change 清单
• api_reference_v7.md — v7 公开 API 路径速查

---

四、SDK 版本绑定

当前规则覆盖 XDSDK v7.X.Y。SDK 团队发新版本时同步更新 yaml + examples。

接入方使用工具时，把工具版本和 v7 SDK 版本对齐（如果工具版本 0.4.x → 对应 v7.6.x 规则）。

---

五、报问题 / 反馈

发现：

• yaml 规则错误（v7 真实 API 跟工具描述不一致）
• examples 模板生成的代码编译错
• Skill 没按 example 改导致漏改

→ 把编译错误日志 + 文件:行号反馈给 SDK 团队，会在下个工具版本修复。