name	pr-review-merge
description	PR 审查、测试、修复、合并全流程。从创建集成分支到最终通过 GitHub Squash Merge 合并。使用场景：审查 PR 代码、运行 GUT 测试、修复问题、合并提交。

PR Review & Merge Workflow

审查从 GitHub 获取的 PR 分支，确认代码质量后通过 GitHub Squash Merge 合并，PR 自动关闭。

前置条件

已通过 git fetch origin 'refs/pull/*/head:refs/remotes/origin/pr/*' 获取 PR refs
GUT 测试框架已安装（addons/gut/）
了解该 PR 的 GitHub 描述（通过 gh 或网页获取）

完整工作流

Step 1：初始化集成分支

git checkout main
git checkout -b integration/pr-review

如果分支已存在：

git checkout main
git branch -D integration/pr-review
git checkout -b integration/pr-review

Step 2：合并 PR 到集成分支

git merge origin/pr/<number> --no-edit

解决冲突后：

git add <resolved-files>
git commit --no-edit

Step 3：全面审查代码

对每个变更文件逐项检查：

3a. 功能完整性

新增功能是否形成闭环（策略→工具→UI→文档）
参数校验是否完整（缺省值、边界值）
错误处理是否恰当

3b. 测试覆盖 对照变更文件逐项检查测试覆盖，使用矩阵记录：

变更文件	变更内容	对应测试文件	覆盖状态
`xxx.gd`	具体变更	`test_xxx.gd`	✅/❌

检查要点：

新增函数 → 有对应测试用例
修改逻辑 → 边界条件测试
导出变量 → get_script_property_list() 断言
Schema 变更 → 新参数在 input_schema 中可查

3c. 代码规范

检查清单：

snake_case 变量/方法命名
PascalCase 类名
类型提示完整
@export 变量有 setter 时调用 notify_property_list_changed()
UI toggle handler 调用 _debounce_save()（持久化）
extends "res://addons/gut/test.gd"（GUT 测试）
无硬编码路径/Token
错误提示中包含具体参数名

3d. 多语言适配（UI 变更必检） 涉及 UI 新增/修改文本时：

UI 控件的 .text 通过 _tr(key) 赋值，而非硬编码字符串
翻译文件 mcp_panel.csv 新增了对应的 key 行
_refresh_translations() 对新增控件做了翻译刷新
英文（en）和中文（zh）两列均有翻译内容

3e. 重复代码检查

跨文件的重复函数 → 提取到共享模块
魔法字符串 → 定义为常量

Step 4：运行 GUT 测试

& "f:/Godot/Godot_v4.6.1-stable_win64.exe" --headless --path "F:/gitProjects/Godot-MCP-Native" -s addons/gut/gut_cmdln.gd -gdir=res://test/unit/ -ginclude_subdirs -gexit

验收标准：

0 failures、0 errors
新增测试全部通过

Step 5：修复发现的问题

记录问题分级：

🔴 阻断级：功能错误、架构问题、测试失败——在 GitHub PR 上 Request Changes 退回作者
🟡 小修复：缺 _debounce_save()、硬编码字符串、缺少翻译 key 等——审查者直接推送到 PR head 分支修复
📝 记录级：CI 集成缺失、代码重复等——记录到文档待后续处理

小修复推送流程

# 1. 基于 PR head 分支创建修复分支
git checkout -b fix/pr<number>-review-fixes origin/pr/<number>

# 2. 修改代码、运行测试验证

# 3. 推送到 PR 的 head 分支（需 collaborator 权限）
git push origin fix/pr<number>-review-fixes:<PR_head_branch>

# 4. 回到集成分支重新合并验证
git checkout integration/pr-review
git merge origin/pr/<number>

阻断问题退回流程

# 通过 GitHub 提交 Review（Request Changes）
gh pr review <number> --request-changes --body "审查意见..."

# PR 作者修复并 push 后，重新从 Step 2 开始

Step 6：记录审查文档

创建审查文档到 docs/debugging/：

docs/debugging/pr<number>-<feature>-review-<date>.md

文档模板：

# PR #N <标题> 审查报告

**日期：** <yyyy-mm-dd>
**审查分支：** integration/pr-review

## 1. GUT 测试结果
| 指标 | 数值 |
## 2. 已修复的问题
### 问题 N：<描述> ✅
**文件：** 路径:行号
**修复：** 说明
## 3. 已记录的问题
### 问题 N：<描述> 🔶
## 4. 测试覆盖率矩阵
| 变更文件 | 测试覆盖 | 状态 |
## 5. 审查结论

Step 7：通过 GitHub Squash Merge 合并

推荐方式：GitHub Squash Merge，确保 PR 自动关闭并有合并记录。

# 方式一：gh CLI（推荐）
gh pr merge <number> --squash --subject "<type>: <中文标题>"

# 方式二：GitHub 网页
# 在 PR 页面点击 "Squash and merge"

优点：

PR 自动关闭并关联到合并记录
修复代码有 commit 归属（来自 PR head 分支）
GitHub 保留完整的审查和合并历史

备选：本地 Squash（仅限无 GitHub 权限时）

git checkout main
git pull origin main
git merge --squash integration/pr-review
git commit
git push origin main
# 注意：此方式不会关闭 GitHub PR，需手动 Close

Step 8：验证 main & 清理

# 重新运行全量 GUT 测试确认 0 failures

# 清理本地分支
git branch -D integration/pr-review
git branch -D fix/pr<number>-review-fixes  # 如有

提交信息规范：

第一行：feat/fix/refactor: <概括>
空一行
主体：逐项列出变更（中英文均可，保持项目一致）

示例：

feat: 新增 Vibe Coding 免打扰模式

新增功能：
- 新增 XXX 策略类
- N 个工具入口添加策略检查
- 插件导出新变量

配套修改：
- 文档更新
- 新增 GUT 测试 N 个
- 修复 XX 持久化问题

常用命令速查

操作	命令
获取 PR refs	`git fetch origin 'refs/pull//head:refs/remotes/origin/pr/'`
查看 PR diff stat	`git diff --stat origin/main...origin/pr/<N>`
查看 PR unique commits	`git log origin/main..origin/pr/<N> --oneline --no-merges`
创建集成分支	`git checkout -b integration/pr-review origin/main`
合并 PR 到集成分支	`git merge origin/pr/<N>`
运行 GUT 测试	`& "f:/Godot/Godot_v4.6.1-stable_win64.exe" --headless --path "F:/gitProjects/Godot-MCP-Native" -s addons/gut/gut_cmdln.gd -gdir=res://test/unit/ -ginclude_subdirs -gexit`
GitHub Squash Merge	`gh pr merge <N> --squash --subject "<type>: <标题>"`
Request Changes	`gh pr review <N> --request-changes --body "意见..."`
Approve PR	`gh pr review <N> --approve --body "审查通过"`
推送修复到 PR 分支	`git push origin fix/pr<N>-review-fixes:<PR_head_branch>`
清理集成分支	`git branch -D integration/pr-review`

测试覆盖矩阵模板

变更文件	变更内容	对应测试	状态
`file1.gd`	新增 X 功能	`test_file1.gd` — test_X	✅
`file2.gd`	修改 Y 逻辑	`test_file2.gd` — test_Y	✅
`file3.gd`	UI 变更	无（UI 手动测试）	⚠️