review-scoring

资源

scripts/
  validate-review.sh
  validate-fix.sh
references/
  scoring-examples.md

评审评分协议

此技能定义了 Work-Review-Fix-Check（WRFC）循环中使用的精确评分标准和评审格式。它确保对代码质量进行一致、量化的评估，并对评审结果进行确定性验证。

评分标准（1-10 分制）

每次评审都会从 10 个维度评估代码。每个维度的得分为 1 到 10 分：

• 1-3：存在严重缺陷和根本性问题
• 4-5：存在重大问题，未达到可接受标准
• 6-7：可以接受，但存在明显问题
• 8-9：质量良好，仅有少量问题
• 10：表现卓越，可用于生产环境

10 个维度

1. 正确性（权重：20%）

代码是否按预期运行？

评分标准：

• 10：逻辑无瑕疵，已处理所有边界情况，包含 null/undefined 检查，没有差一错误
• 7-9：遗漏少量边界情况，可添加一些防御性检查
• 4-6：常见路径中存在逻辑错误，缺少 null 检查，条件语句不正确
• 1-3：存在根本性逻辑错误，处理常见输入时崩溃，核心功能损坏

常见问题：

• 缺少 null/undefined 检查
• 循环/数组中的差一错误
• 布尔逻辑不正确
• 异步代码中的竞态条件
• 未处理的 Promise 拒绝

2. 完整性（权重：15%）

是否已完整实现所有内容？

评分标准：

• 10：功能已完整实现，没有 TODO、占位符或注释掉的代码
• 7-9：包含少量用于未来增强的 TODO 注释（非核心功能）
• 4-6：核心功能仅有存根或占位实现，缺少关键路径
• 1-3：大部分内容都是占位符，实现不完整，缺少主要功能

常见问题：

• 生产代码中包含 TODO 注释
• 占位函数返回硬编码值
• 缺少错误状态
• 表单验证不完整
• 使用模拟数据而不是真实 API 调用

3. 安全性（权重：15%）

是否已防止安全漏洞？

评分标准：

• 10：已验证输入，检查身份验证，未暴露机密，可防注入，已配置 CORS
• 7-9：存在少量安全加固机会（速率限制、额外日志记录）
• 4-6：缺少输入验证，某些路径可绕过身份验证检查，代码中包含机密
• 1-3：存在严重漏洞（SQL 注入、XSS、凭据泄露、无身份验证）

常见问题：

• 机密硬编码或提交到 git
• 缺少身份验证检查
• 通过字符串拼接造成 SQL 注入
• 通过 innerHTML 或 dangerouslySetInnerHTML 导致 XSS
• 在生产环境中将 CORS 设置为 *
• 缺少 CSRF 防护
• 客户端代码中包含敏感数据

4. 性能（权重：10%）

代码是否高效？

评分标准：

• 10：没有 N+1 查询，索引设置恰当，按需缓存，重新渲染经过优化
• 7-9：存在少量优化机会（记忆化、延迟加载）
• 4-6：存在 N+1 查询，缺少索引，存在不必要的重新渲染
• 1-3：存在严重性能问题（阻塞操作、内存泄漏、无限循环）

常见问题：

• N+1 数据库查询
• 缺少数据库索引
• 不必要的 React 重新渲染（缺少 useMemo/useCallback）
• 包体积过大（缺少代码拆分）
• 同步操作阻塞事件循环
• 内存泄漏（未清理事件监听器）

5. 规范（权重：10%）

代码是否遵循项目模式？

评分标准：

• 10：符合现有命名、文件结构、导入顺序和代码风格
• 7-9：存在少量风格不一致（格式、导入顺序）
• 4-6：命名规范不同、文件位置错误、模式不一致
• 1-3：完全无视项目规范，引入相互冲突的模式

常见问题：

• 命名不一致（camelCase 与 snake_case 混用）
• 文件位置错误（将组件放在 utils/ 中）
• 违反导入顺序
• 混用制表符和空格
• 错误处理模式与代码库其余部分不同

6. 可测试性（权重：10%）

是否存在有意义的测试？

评分标准：

• 10：测试全面，覆盖边缘情况，断言有意义，覆盖率高
• 7-9：存在测试，但遗漏了一些边缘情况或断言较弱
• 4-6：测试最少，仅覆盖正常路径，没有边缘情况
• 1-3：没有测试，或测试无法验证行为

常见问题：

• 完全没有测试
• 测试仅覆盖正常路径
• 测试没有断言（仅为冒烟测试）
• 缺少边缘情况覆盖
• 测试脆弱，依赖实现细节

7. 可读性（权重：5%）

是否易于理解？

评分标准：

• 10：命名清晰，抽象恰当，复杂逻辑有说明，代码自说明
• 7-9：整体清晰，少数变量名晦涩或复杂逻辑缺少说明
• 4-6：命名不佳，过于复杂，需要注释的地方缺少注释
• 1-3：难以理解，使用单字母变量，嵌套层级过深，没有说明

常见问题：

• 使用单字母变量名（循环计数器除外）
• 函数超过 50 行
• 嵌套超过 4 层
• 缩写晦涩难懂
• 复杂逻辑缺少解释性注释

8. 错误处理（权重：5%）

是否能妥善处理错误？

评分标准：

• 10：捕获所有错误，记录日志恰当，面向用户的提示清晰，不会静默失败
• 7-9：捕获了错误，但日志记录可以改进，部分提示较笼统
• 4-6：缺少一些 try/catch 块，存在静默失败，错误提示不佳
• 1-3：没有错误处理，遇到错误时崩溃，没有用户反馈

常见问题：

• 空 catch 块（静默失败）
• 通用错误提示（“出了点问题”）
• 未记录错误
• 未处理的 Promise 拒绝
• 没有面向用户的错误状态

9. 类型安全（权重：5%）

类型是否正确且全面？

评分标准：

• 10：类型准确，没有 any，恰当使用泛型，已启用严格模式
• 7-9：大部分代码都有类型标注，少数 any 类型附有待修复的 TODO 注释
• 4-6：存在许多 any 类型，没有验证的类型断言，类型标注宽松
• 1-3：禁用了 TypeScript，到处都是 any，类型断言掩盖错误

常见问题：

• 过度使用 any
• 未进行运行时验证的类型断言（as）
• 缺少返回类型注解
• 泛型约束不正确
• 禁用严格模式

10. 集成（权重：5%）

是否能与现有代码协同工作？

评分标准：

• 10：无缝集成，不会破坏现有功能，遵循 API 契约
• 7-9：少数集成点需要调整
• 4-6：破坏现有功能，违反 API 契约，或需要在其他地方进行大量更改
• 1-3：与现有系统不兼容，破坏多项功能

常见问题：

• 破坏公共 API 的变更
• 与现有认证流程不兼容
• 破坏其他功能（回归）
• 不使用共享工具（重复造轮子）
• 与现有状态管理冲突

总分计算

总分为 10 个维度的加权平均值：

Overall = (Correctness x 0.20) + 
          (Completeness x 0.15) + 
          (Security x 0.15) + 
          (Performance x 0.10) + 
          (Conventions x 0.10) + 
          (Testability x 0.10) + 
          (Readability x 0.05) + 
          (Error Handling x 0.05) + 
          (Type Safety x 0.05) + 
          (Integration x 0.05)

示例：

Correctness: 9
Completeness: 8
Security: 10
Performance: 7
Conventions: 9
Testability: 6
Readability: 8
Error Handling: 7
Type Safety: 9
Integration: 9

Overall = (9x0.20) + (8x0.15) + (10x0.15) + (7x0.10) + (9x0.10) + 
          (6x0.10) + (8x0.05) + (7x0.05) + (9x0.05) + (9x0.05)
        = 1.8 + 1.2 + 1.5 + 0.7 + 0.9 + 0.6 + 0.4 + 0.35 + 0.45 + 0.45
        = 8.35/10

通过/失败阈值

总分决定评审结论：

分数范围	结论	所需操作
>= 9.5	PASS	发布——已达到生产就绪状态
8.0-9.49	CONDITIONAL PASS	存在少量问题——修复后重新检查（8.0 为包含边界，无需全面重新评审）
6.0-7.9	FAIL	存在重大问题——修复后必须全面重新评审
低于 6.0	FAIL	需要大幅返工——修复后必须全面重新评审

关键维度规则：如果任何维度的得分低于 4，无论计算出的总分是多少，结论都自动为 FAIL。

必需的评审输出格式

每次评审都必须采用以下确切结构。验证脚本会检查这些章节。

## Review Summary
- **Overall Score**: X.X/10
- **Verdict**: PASS | CONDITIONAL PASS | FAIL
- **Files Reviewed**: [list of files]

## Dimension Scores
| Dimension | Score | Notes |
|-----------|-------|-------|
| Correctness | X/10 | [specific findings] |
| Completeness | X/10 | [specific findings] |
| Security | X/10 | [specific findings] |
| Performance | X/10 | [specific findings] |
| Conventions | X/10 | [specific findings] |
| Testability | X/10 | [specific findings] |
| Readability | X/10 | [specific findings] |
| Error Handling | X/10 | [specific findings] |
| Type Safety | X/10 | [specific findings] |
| Integration | X/10 | [specific findings] |

## Issues Found

### Critical (must fix)
- [FILE:LINE] Description of issue. Fix: [specific fix]
- [FILE:LINE] Description of issue. Fix: [specific fix]

### Major (should fix)
- [FILE:LINE] Description of issue. Fix: [specific fix]
- [FILE:LINE] Description of issue. Fix: [specific fix]

### Minor (nice to fix)
- [FILE:LINE] Description of issue. Fix: [specific fix]
- [FILE:LINE] Description of issue. Fix: [specific fix]

## What Was Done Well
- [specific positive observation with file reference]
- [specific positive observation with file reference]

格式要求

1. 总分：必须为数字（X.X/10 格式，保留一位小数）
2. 判定结果：必须与以下选项之一完全一致：PASS、CONDITIONAL PASS、FAIL
3. 维度评分：必须包含全部 10 个维度，并采用 X/10 格式；备注必须包含具体发现（不能使用“看起来不错”等泛泛表述）
4. 问题分类：每个问题都必须归入 Critical、Major 或 Minor 类别
5. FILE:LINE 引用：每个问题都必须引用具体的文件和行号
6. 修复建议：每个问题都必须包含具体的修复指导（说明要改什么、如何修改以及代码示例）
7. 做得好的方面：必须包含此部分，且至少列出一项积极评价

问题严重性指南

Critical：发布前必须修复。例如：

• 安全漏洞
• 数据损坏错误
• 身份验证绕过
• 常见输入导致崩溃
• 机密信息泄露

Major：发布前应修复。例如：

• 性能问题（N+1 查询）
• 重要路径缺少错误处理
• 无障碍问题
• 类型安全违规（过度使用 any）
• 影响可维护性的规范违规

Minor：可以修复，但不会阻碍发布。例如：

• 命名不够理想
• 复杂逻辑缺少注释
• 轻微的风格不一致
• 重构机会
• 测试断言较弱

注意：严重性可能取决于系统的风险背景（例如，在高规模系统中，性能问题可能属于 Critical）。

修复 Agent 要求

修复 Agent 收到审查报告后：

必须修复

1. 所有 Critical 问题——无一例外
2. 所有 Major 问题——无一例外
3. Minor 问题——除非编排器明确降低其优先级

必须记录

应用修复后，修复 Agent 必须生成：

## Fixes Applied

### Critical Issues Addressed
- [FILE:LINE] [Original issue] -> Fixed by: [what was changed]
- [FILE:LINE] [Original issue] -> Fixed by: [what was changed]

### Major Issues Addressed
- [FILE:LINE] [Original issue] -> Fixed by: [what was changed]

### Minor Issues Addressed
- [FILE:LINE] [Original issue] -> Fixed by: [what was changed]

### Issues Not Fixed
- [FILE:LINE] [Original issue] -> Reason: [why it wasn't fixed]

**Example**:
- [src/api/legacy.ts:45] Complex refactoring of legacy code -> Reason: Out of scope for this PR, tracked in ticket #1234

禁止行为

1. 不得声称已修复但未做更改：实际修改代码之前，不得将问题标记为已修复
2. 不得部分修复：必须彻底修复问题，或记录无法修复的原因
3. 不得静默跳过：跳过问题时，必须在“未修复的问题”中说明原因
4. 不得引入新问题：修复不应引入新错误（通过重新审查进行检查）

重新审查要求

应用修复后，重新审查者必须：

验证步骤

1. 检查每个先前标记的问题

   • 验证是否已应用修复
   • 验证修复是否真正解决了问题
   • 验证修复是否引入了新问题，或只是将问题转移到了其他地方

2. 重新评估所有维度

   • 不要直接照搬之前的评分
   • 从头评估当前状态：(a) 阅读修改过的文件；(b) 应用评分标准；(c) 根据当前状态评分
   • 记录分数变化（“安全性：6 -> 9”）

3. 识别新问题

   • 重新审查期间发现的问题属于新发现
   • 除非问题由修复直接导致，否则不计为回归问题
   • 使用相同的评分标准，将问题归类为 Critical、Major 或 Minor

重新审查输出格式

## Re-Review Summary
- **Overall Score**: X.X/10 (was Y.Y/10)
- **Verdict**: PASS | CONDITIONAL PASS | FAIL
- **Previous Issues**: X critical, Y major, Z minor
- **Issues Resolved**: X critical, Y major, Z minor
- **New Issues Found**: X critical, Y major, Z minor

## Dimension Score Changes
| Dimension | Previous | Current | Change |
|-----------|----------|---------|--------|
| Correctness | X/10 | X/10 | +/- X |
| [etc] | ... | ... | ... |

## Previous Issues - Resolution Status

### Critical Issues
- [RESOLVED] [FILE:LINE] [Original issue] -> RESOLVED
- [NOT FIXED] [FILE:LINE] [Original issue] -> NOT FIXED: [reason]

### Major Issues
- [RESOLVED] [FILE:LINE] [Original issue] -> RESOLVED

### Minor Issues
- [RESOLVED] [FILE:LINE] [Original issue] -> RESOLVED

## New Issues Found
[Use standard Critical/Major/Minor format]

WRFC 循环背景

此技能是 Work-Review-Fix-Check 循环的关键组件：

1. 工作：工程师实现功能
2. 审查：审查者应用此评分标准 -> 生成评分审查报告
3. 修复：修复 Agent 处理所有 Critical/Major 问题 -> 生成修复报告
4. 检查：重新审查者验证修复 -> 重新评分 -> 判断是否需要再进行一轮循环

编排器使用数字评分和判定结果来做出决策：

• PASS（9.5+）：退出循环，标记为已完成
• CONDITIONAL PASS（8.0-9.49）：再进行一轮快速修复和检查
• FAIL（<8.0）：再次进行完整的审查-修复-检查循环

应避免的常见评分错误

评分虚高

错误：存在重大问题时仍给出 8-9 分 正确：严格按评分标准评分——6-7 分表示“尚可，但存在明显问题”

严重性判定不一致

错误：将安全漏洞标记为“Major”而非“Critical” 正确：遵循严重性指南——身份验证绕过始终属于 Critical

缺少 FILE:LINE 引用

错误：“错误处理很差” 正确：“src/api/users.ts:42 - 空的 catch 块会静默吞掉错误”

修复建议含糊

错误：“修复类型安全问题” 正确：“将 any 替换为 User 类型，并使用 zod schema 添加运行时验证”

主观地扣留分数

错误：因为“领域复杂”或“低于完美”而给出 9.5 分，而不是 10 分 正确：如果未发现任何问题，分数就是 10 分。评分必须客观，且仅基于已识别、可操作的问题。10/10 始终可以达到，未发现任何缺陷时必须给出此分数。切勿因领域复杂性、代码新颖性或哲学上的谨慎等主观原因扣分。

忽略正面评价

错误：只列出问题 正确：也记录做得好的地方（鼓励良好模式）

结论不匹配

错误：总体评分为 7.2/10，结论为“通过” 正确：评分 7.2 → 结论为 FAIL（有条件通过的阈值为 8.0，通过的阈值为 9.5）

验证脚本

此技能包含确定性验证脚本：

• scripts/validate-review.sh：检查评审输出是否符合格式要求
• scripts/validate-fix.sh：检查修复 Agent 的输出是否解决了所有严重/主要问题

实现细节请参阅 scripts/ 目录。

快速参考

维度权重

Correctness:      20%  (most important)
Completeness:     15%
Security:         15%
Performance:      10%
Conventions:      10%
Testability:      10%
Readability:       5%
Error Handling:    5%
Type Safety:       5%
Integration:       5%

结论阈值

9.5+ -> PASS
8.0-9.49 -> CONDITIONAL PASS
6.0-7.9 -> FAIL
<6.0 -> FAIL (major rework)

问题严重程度

Critical: Security, crashes, data corruption -> MUST FIX
Major: Performance, missing features, poor practices -> SHOULD FIX
Minor: Style, optimization opportunities -> NICE TO FIX