gabrielmoreira 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`: 问题、原因、建议。
## 代码风格一致性
- ...
## 测试与验证缺口
- ...
## 需要作者确认的问题
- ...
问题项必须尽量带文件路径和行号。没有发现问题时也要明确写“未发现明显越界/质量/风格问题”，并列出仍未覆盖的验证盲区。