Metadata-Version: 2.4
Name: xdsdk-upgrade
Version: 0.5.0
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"

# 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

```bash
pip install xdsdk-upgrade
```

### 2. 选你用的 LLM agent

#### 选项 A: Claude Code

```bash
xdsdk-upgrade install-skill --engine ue   # 拷 Skill 到 ~/.claude/skills/
cd /path/to/your-ue-project
claude
```
输入触发词："升级 XDSDK 到 v7"

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

```bash
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 也能跑机械改动：
```bash
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）

```bash
# 扫描项目，看升级影响面
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 知识库**用的，接入方不需要：

```bash
# 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 团队，会在下个工具版本修复。
