PR / 分支变更梳理

面向代码 reviewer，先从真实 diff 还原需求与实现边界，再判断是否有超出需求的改动、过度复杂的整理、测试与模块化风险、以及与相近代码不一致的风格。

基本原则

默认输出中文。
以 checked-out 代码和 diff 为准，不只复述 PR 标题或描述。
优先回答“这次到底改了什么、为什么有用、影响到哪里、哪里不像同一个需求应该带上的改动”。
不默认提交 review、批准、请求修改或推送代码；用户明确要求后才执行 GitHub 写操作。
不修改工作区代码；如为了 review 需要切分实验或临时命令，只做只读检查。
保留用户已有改动。切换 PR 前必须检查 git status --short，遇到未提交改动时先说明风险并让用户决定，不要自行 stash、reset 或 checkout 覆盖。

入口判断

如果用户给了 PR URL 或编号：
- 用 gh pr view <pr> 获取 number,title,body,author,headRefName,baseRefName,files,additions,deletions,commits。
- 按用户要求用 gh pr checkout <pr> 切到该 PR 分支。
- git fetch upstream main，默认用 upstream/main...HEAD 做审查基准。
- 如果 PR 的 baseRefName 不是 main，在报告里明确说明，并根据上下文决定是否同时补充 upstream/<baseRefName>...HEAD 的对比。
如果用户没有给 PR，只说当前分支：
- 确认当前分支名：git branch --show-current。
- git fetch upstream main。
- 使用 git diff upstream/main...HEAD 和相关统计作为审查基准。
如果当前分支就是 main 或 diff 为空：
- 明确说明没有可分析的分支差异，必要时检查是否需要比较其他 base。

信息收集

优先用这些命令建立全局视角：

git status --short
git branch --show-current
git fetch upstream main
git diff --stat upstream/main...HEAD
git diff --name-status upstream/main...HEAD
git log --oneline --decorate upstream/main..HEAD

再按文件类型深入：

git diff upstream/main...HEAD -- <path>
git diff --word-diff=color upstream/main...HEAD -- <path>
rg -n "关键函数|关键类型|关键字段" <相关目录>

检查需求来源时优先读取：

PR 标题、正文、commit message。
新增或修改的 API schema、数据库 schema、工作流节点定义、配置默认值、权限判断。
与变更文件相邻的旧实现或同类功能实现。
测试文件与缺失测试的高风险路径。

审查维度

1. 需求变更说明

需要用 reviewer 能快速理解的方式说明：

本次变更解决什么问题，给用户、管理员、开发者或系统运行带来什么作用。
核心行为从什么变成什么。
对外接口、数据结构、配置、权限、计费、工作流运行时、前端交互是否变化。
关键实现路径：入口在哪里，主要处理逻辑在哪里，最终落到哪些模块。

不要只列文件名。每个关键文件都要说明它承担的行为变化。

2. 是否超出需求影响范围

重点找这些信号：

与需求无关的格式化、重命名、移动文件、依赖升级、批量整理。
修改共享类型、全局工具、公共组件、运行时核心逻辑，但需求只需要局部修复。
同一个分支混入多个独立需求或历史清理。
行为改动被伪装成重构，导致旧路径兼容性、默认值、继承语义或保存边界改变。
删除兼容逻辑、改变错误处理、日志、权限、缓存、并发策略，但 PR 描述未解释。

结论要区分：

合理扩散：为了实现需求必须改的上下游。
可疑越界：看起来和需求无关，需要作者拆分或解释。
高风险越界：可能导致回归，应要求拆出或补测试。

3. 代码质量

检查是否：

存在重复逻辑、临时硬编码、过长函数、混合多层职责。
可以被独立模块化测试，但实际写在 UI、API route 或分支逻辑里导致难测。
缺少边界条件、异常路径、空值、旧数据兼容、并发或幂等处理。
没有把契约放在正确边界，例如 FastGPT API 入参应使用 parseApiInput，共享 schema 应放在 packages/global/openapi 或相应共享层。
测试只覆盖 happy path，或者新增核心逻辑没有对应单测。

评价质量时给出具体文件和函数，不要泛泛说“需要优化”。

4. 代码风格与相近功能一致性

对比相邻实现，而不是只按个人偏好判断：

API route、service、schema、hook、组件、i18n、错误处理、日志、权限判断是否沿用附近模式。
i18n 调用必须使用可被清理脚本静态识别的 key：不要写 t(`ns:key_${value}`)、t(prefix + value)、t(variableKey) 或 t(condition ? 'ns:a' : 'ns:b') 这类动态/表达式 key；有限枚举应拆成显式分支或静态映射，并在最终调用处保留 t('ns:literal_key') 形式。改动后要检查对应语言包 key 是否齐全，避免清理脚本误删或运行时裸显 key。
前端交互、Chakra UI 组件组织、状态命名、弹窗/表单/列表布局是否与同模块一致。
后端命名、目录分层、模型访问、事务/队列/缓存写法是否与同类代码一致。
注释是否解释设计原因，尤其是导出函数、核心业务函数、复杂 helper；避免无意义逐行注释。
是否引入与项目习惯不一致的新抽象、新工具或新依赖。

深挖方法

对每个核心改动至少做一次“调用链闭环”：

从入口找触发点：页面、API route、worker、workflow dispatcher、service 方法或配置加载。
追到状态/数据落点：数据库、缓存、请求体、响应体、运行时变量、前端 store。
找相近功能：同目录同类 route、同类组件、同类工作流节点、同类模型配置。
对比旧行为：用 git show upstream/main:<path> 或 git diff 确认不是误读。
判断测试：现有测试是否覆盖这条路径；没有测试时说明缺口与风险。

如果发现大规模重构，先识别“纯移动/纯重命名/格式化”和“真实行为改动”，避免把噪音当成需求。

输出格式

最终报告优先用以下结构，按风险高低组织，不要写冗长总结报告：

## 需求变更

- ...

## 关键实现路径

- `path/to/file.ts`: ...

## 影响范围与越界判断

- 合理扩散: ...
- 可疑越界: ...
- 高风险越界: ...

## 代码质量

- [风险等级] `path/to/file.ts`: 问题、原因、建议。

## 代码风格一致性

- ...

## 测试与验证缺口

- ...

## 需要作者确认的问题

- ...

问题项必须尽量带文件路径和行号。没有发现问题时也要明确写“未发现明显越界/质量/风格问题”，并列出仍未覆盖的验证盲区。

pr-change-analysis