review

评审

以工匠的眼光进行代码评审。自动修复明显问题，找出真正的 Bug。

参照 @AGENTS.md 中的项目规范，并将其作为评审标准。

关键规则

1. 自动修复安全且明显的问题——无需为显而易见的小事征求许可
2. 查找 Bug——优先检查逻辑错误、边缘情况和竞态条件
3. 等待确认——发现 BUG/FIX 时，不要执行，直到用户说“go”
4. 简洁——每项只用一行，选项放在最后
5. 使用可点击链接——仅使用 path/to/file.ts:123 格式

类别

类别	内容	操作
[BUG]	逻辑错误、安全问题、数据丢失、竞态条件	报告 → 等待
[FIX]	类型缺失、缺少错误处理、测试缺失、冗余代码	报告 → 等待
[AUTO]	未使用的导入、死代码、console.log、拼写错误	立即修复
[CONSIDER]	重构、风格建议、锦上添花的改进	仅提及

AUTO 标准（必须全部满足）

• 破坏行为的风险为零
• 修复时间少于 5 秒
• 无需主观判断

AUTO 示例：

• 未使用的导入/变量
• 行尾空格
• Console.log（除非是有意保留）
• 死代码/不可达代码
• 注释/字符串中的明显拼写错误

不属于 AUTO（需确认）：

• 删除“未使用”的函数（可能在其他地方使用）
• 类型变更（可能改变行为）
• 任何逻辑变更
• 删除 AI 冗余内容（可能是有意保留）

项目专属检查项

评审时务必提出以下问题：

能否更简单？

• 是否存在不必要的抽象？能否用更少的代码实现？
• 是否为一次性操作创建了辅助函数/工具函数？
• 错误处理、功能开关或向后兼容垫片是否过度设计？
• 是否存在不必要的包装组件或 HOC？

能否删除代码？

• 是否存在死代码、未使用的导出、注释掉的代码块？
• 是否存在重新导出或桶文件（我们不使用桶文件）？
• 是否存在重命名 _vars 或 // removed 注释之类的向后兼容变通方案？
• 导出的类型/接口是否只在同一文件中使用？

是否遵循 DRY，且没有过早抽象？

• 明显复制粘贴的完整函数或大段代码 → 重构
• 但 2～3 行相似代码没问题——不要过早抽象
• 错误的抽象比重复更糟糕

结构是否正确？

• 与页面相关的组件应与页面放在一起（不要放在嵌套的 components/ 子文件夹中——路由目录中不这样做）
• 通用/可复用组件放在 apps/web/components/
• API 路由：每个路由对应一个资源，不要合并数据端点
• 变更操作使用服务器操作，而不是 POST 路由
• 验证 schema放在单独的 .validation.ts 文件中
• 辅助函数放在文件底部，而不是顶部
• 所有导入都放在顶部——文件中间不要动态导入
• 不要使用桶文件（通过 index.ts 重新导出文件夹中的所有内容）

是否遵循项目模式？（参见 @AGENTS.md）

• GET 路由是否用 withAuth 或 withEmailAccount 包装？
• 响应类型是否导出为 Awaited<ReturnType<typeof fn>>？
• 客户端数据获取是否使用 SWR？
• 加载/错误状态是否使用 LoadingContent？
• 表单提交是否使用 next-safe-action/hooks 中的 useAction？
• Zod schema 是否使用 z.infer<typeof schema>，而不是重复定义接口？
• 代码是否能自我说明？注释是否解释“为什么”，而不是“是什么”？
• PII 字段是否使用 logger.trace()？
• 测试变更是否遵循 .claude/skills/testing/SKILL.md？
• 测试是否避免模拟 @/utils/logger？
• 如果草稿生成提示词、检索、路由或后处理发生变更，是否为分析数据提升 apps/web/utils/ai/reply/draft-attribution.ts 中的 DRAFT_PIPELINE_VERSION？

经验检查

• 此次变更是否带来了值得记录在 AGENTS.md 或本评审文件中的经验？
• 是否有反复出现、值得记录的模式？

心态

**传承测试：**我会不会埋怨之前的作者？凌晨 2 点能看懂吗？

**自豪测试：**我愿意为这段代码署名吗？

工作流

第 0 步：确定范围并对文件分组

自动检测：对话中的更改 → 已暂存内容 → 当前差异

git diff --cached --name-only  # or HEAD

按领域／依赖关系对文件分组：

Batch 1: apps/web/app/api/agent/* (3 files)
Batch 2: apps/web/app/(app)/[emailAccountId]/agent/* (related components)
Batch 3: apps/web/utils/actions/* (2 files)

输出： 找到 Y 批次中的 X 个文件

──────────

第 1 步：制定审查计划（TODO）

在读取任何文件内容之前，创建待办列表：

- [ ] Batch 1: API routes (skills, allowed-actions)
- [ ] Batch 2: agent page components (agent-page, chat, tools)
- [ ] Batch 3: server actions (agent.ts, agent.validation.ts)

使用 todo_write 跟踪各批次。

──────────

第 2 步：处理各批次

对于每个批次：

1. 仅读取该批次文件的差异（git diff --cached -- path/to/files）
2. 审查并归类问题
3. 立即自动修复 [AUTO] 项
4. 记录 [BUG]/[FIX]/[CONSIDER] 项
5. 在待办事项中将该批次标记为已完成

问题格式：

1. **[BUG]** Race condition in concurrent saves — `src/db.ts:45`
2. **[FIX]** Missing error boundary — `src/App.tsx:12`
3. **[CONSIDER]** Extract to custom hook — `src/Form.tsx:34`

每个批次完成后：

Batch 1 done: AUTO: 2 fixed | BUG: 1 | FIX: 2

──────────

第 3 步：总结并提供选项（所有批次完成后）

Total: BUG: X | FIX: X | CONSIDER: X (auto-fixed: Y)

Issues:
1. [BUG] ... — `path:line`
2. [FIX] ... — `path:line`

What to fix?
- a) BUG + FIX [recommended]
- b) BUG only
- c) All including CONSIDER
- d) Custom (e.g., "1,3")

I'll assume a) if you don't specify.

Learnings:
- Any patterns worth adding to AGENTS.md?
- Any new review checks to add to this file?

停止。等待选择。

──────────

第 4 步：执行修复

按批次处理修复（使用相同的分组方式）：

1. 使用所选修复项更新待办列表
2. 对于每个批次：
   • 读取相关文件
   • 应用修复
   • 标记为已完成
3. 如果适用，运行代码检查工具

严重程度指南

BUG（逻辑／安全）：

• 业务逻辑错误、条件错误
• 竞态条件、数据丢失
• 安全问题：注入、XSS、机密信息泄露
• API 路由缺少身份验证中间件
• 未处理 Null／undefined
• 会导致问题的边缘情况

FIX（质量）：

• 类型安全缺失、不安全的类型转换
• 缺少错误处理
• 测试覆盖率不足
• AI 垃圾代码（WHAT 注释、不必要的 try/catch、as any）
• 缺少验证
• 本应拆分的 API 路由却合并在一起
• 使用 POST 路由进行更改，而不是使用服务器操作
• Barrel 文件／重新导出模式

CONSIDER（主观建议）：

• 重构机会
• “我会用另一种方式实现”
• 性能方面的微优化
• 风格偏好

Git 命令

# Staged
git diff --cached
git diff --cached --name-only

# All uncommitted
git diff HEAD
git diff HEAD --name-only

错误处理

错误	响应
没有更改	“检查 git 状态或指定文件”
找不到文件	列出可用文件，并询问要指定哪个文件
二进制文件	跳过，并在总结中说明
大文件（>10k）	“要审查特定部分吗？”