xdsdk-upgrade 0.6.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 也能跑机械改动：

# 拉最新 v7 SDK 到本地缓存（不带 --version 自动用最新版）
xdsdk-upgrade fetch-sdk --engine ue
# 替换 + 改名 + 注释
xdsdk-upgrade apply --project /path/to/project \
  --replace-sdk-plugins --target-sdk-plugins ~/.xdsdk-cache/UE/<version>/Plugins \
  --comment-deprecated
xdsdk-upgrade scan --project /path/to/project   # 看哪些还要人工改

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

# 拉 v7 SDK
xdsdk-upgrade fetch-sdk --engine ue                  # 默认拉最新版
xdsdk-upgrade fetch-sdk --engine ue --version 7.5.0  # 拉指定版本
# OSS 上没该版本时自动 fallback 到最新；CI 想严格不 fallback 加 --strict-version

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

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

# 完工后自检
xdsdk-upgrade verify-scope --project /path/to/project \
  --target-sdk-plugins ~/.xdsdk-cache/UE/<version>/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 团队，会在下个工具版本修复。

---

六、发版流程（维护者）

PyPI 发版由 GitLab CI 自动触发（push tag 即可）：

# 1. 改 pyproject.toml 的 version
vim pyproject.toml          # version = "0.6.0"

# 2. commit + push
git add pyproject.toml
git commit -m "release: v0.6.0"
git push origin main

# 3. tag + push tag → 触发 publish-pypi job
git tag 0.6.0 -a -m "release 0.6.0"
git push origin 0.6.0

# 4. 等 CI 跑完（约 2-3 分钟），看 GitLab Pipelines 页面
# 5. 验证: pip install -U xdsdk-upgrade && xdsdk-upgrade --help

Tag 格式硬性约定：X.Y.Z（如 0.6.0，不带 v 前缀，跟其他 xdsdk-* repo 一致）。CI 会校验 tag 跟 pyproject version 字段完全相等。

version 语义：

• patch (0.5.0 → 0.5.1): bug fix、文档修正、yaml 字段补充
• minor (0.5.0 → 0.6.0): 新增 cli 子命令、新增 yaml 顶层段、Skill 流程变更
• major (0.x → 1.0): 暂时不用

前置 secrets（一次性，已配过则跳过）：在 GitLab → Settings → CI/CD → Variables 配 PYPI_TOKEN（masked + protected，project-scoped 来自 https://pypi.org/manage/account/token/）。

yaml _meta.latest_known_version 维护：SDK 团队每次发版会通过 tools/sync_sdk_release.py 自动 push 同步 commit 到 main，本工具维护者只需要在合适时机 bump version + tag 发版。