--- description: harness-review 的审查标准说明和输出报告完整模板。仅在需要理解审查标准或生成详细报告时读取。 --- # harness-review 参考 — 审查标准 ## 为什么需要审查 即使有 TDD 和场景覆盖，仍然可能遗漏一些只在"阅读代码"时才能发现的问题： - 违反架构约束（TDD 关注行为，不关注结构） - 安全漏洞（测试通常不会故意测试安全攻击） - 编码规范偏离（IDE 自动格式化可能产生不一致的风格） - 性能隐患（N+1 查询在单元测试中不起眼，但在生产环境是灾难） > 维度检查项的详细列表和重要性说明见 `checklist.md`，本文件保留"为什么需要审查"概述、严重级别判定标准和输出报告模板。 ## 严重级别判定标准 RED/YELLOW/OK 三态的判定原则——结论必须基于实际 diff 内容，不得凭印象；每条建议给出文件:行号 + 修复做法。 | 级别 | 判定原则 | 典型场景 | |:----:|------|------| | RED | 高风险，强烈建议处理——生产环境会直接造成损失或数据破坏 | 硬编码密码/Token/密钥；SQL 字符串拼接（注入）；新增接口无权限校验；删除/修改已发布接口字段或数据库字段；写操作无事务边界；业务层间循环依赖；接口层跨模块调用；对生产库执行写操作 | | YELLOW | 中低风险，建议处理——影响可维护性或存在隐患，但不会立即造成损失 | 数据类暴露不必要可变 setter（应改只读访问器）；控制台输出替代日志框架；集合返回 null 而非空集合；魔法值未定义常量；公共 API 无文档注释；N+1 查询；缺少索引；大事务；逐条 insert；新增非空字段；新增业务方法无对应单元测试 | | OK | 该维度在本次 diff 中无问题 | —— | **判定要点**： - 敏感信息（明文 token/密码/密钥）一律 RED，并在报告中以 `` 等占位符引用 - 占位符与脱敏做法遵循 `../protocols/sensitive-info-protocol.md`；结论须基于实际 diff 证据，见 `../protocols/evidence-based-reporting-protocol.md` - 安全维度的问题默认 RED（除非确属误报） - 兼容性维度：删除/修改已发布契约为 RED，新增字段提醒为 YELLOW - 测试维度：核心业务方法无任何测试覆盖为 YELLOW（建议补充），不判 RED（review 不阻塞） - 当界限模糊时，倾向 YELLOW 并在建议中说明判断依据，让用户决定 ## 输出报告完整模板 ```markdown ## 代码审查报告 — <功能名> ### 变更摘要 - 变更文件: N 个 | +xxx / -xxx - 评审模式: full | incremental（`harness_review.py diff-scope` 输出； full 时注明 reason，如 EXPANDED_SIGNALS:shared-state） ### 增量对账（mode=incremental 时必填） - 新增发现: N | 持续发现（id 同上轮 openFindings）: M | 消失（上轮未解决、本轮未复现且未重报）: K - 消失项须在报告中逐条说明去向（已修复 / 文件还原 / 锚点漂移待重报），防止漏审 ### 审查结果 | 维度 | RED 高风险 | YELLOW 中低风险 | OK 通过 | |------|:------:|:------:|:------:| | 架构 | 0 | 1 | 4 | | 安全 | 0 | 0 | 5 | | 编码规范 | 0 | 2 | 4 | | 兼容性 | 0 | 0 | 4 | | 测试 | 0 | 1 | 3 | | 性能 | 0 | 0 | 3 | ### RED 高风险建议（强烈建议处理） | # | 文件:行 | 维度 | 问题 | 建议 | 参考优先级 | |:--:|---------|------|------|------|:--------:| | （列出所有高风险问题） | ### YELLOW 中低风险建议（建议处理） | # | 文件:行 | 维度 | 问题 | 建议 | 参考优先级 | |:--:|---------|------|------|------|:--------:| | 1 | xxx:396 | 架构 | ... | ... | 建议优先处理 | | 2 | xxx:25 | 规范 | 数据类暴露可变 setter | 改为只读访问器 | 建议在 submit 前人工确认 | ### 规则对照 | 规则文件 | 结果 | |----------|:----:| | architecture.md | OK / FAIL | | 项目编码规范（按技术栈，示例：Java 项目的 `java-coding-standards.md`，前端项目按项目实际规则文件） | OK / FAIL | | 项目框架规范（按技术栈，示例：Java 项目的 `spring-boot-patterns.md`，其他技术栈按项目实际） | OK / FAIL | | testing-conventions.md | OK / FAIL | | database-safety.md | OK / FAIL | ### 总结 RED 高风险建议: N | YELLOW 中低风险建议: M | 仅供参考，不阻塞后续 harness 流程 ``` ## Fixback 输出关系 当审查报告包含 RED 或 YELLOW 问题时，执行 `protocols.md` 的 `review-fixback-protocol`，另行生成： ```text .harness/changes//reports/review/fixback-YYYYMMDD-HHmm.md ``` fixback 是给后续修复循环使用的结构化清单，不替代 review-report；无 RED/YELLOW 时记录跳过原因，不生成空文件。 ## CodeGraph Identity 合同（C12） 发出 `codegraph_explore` 前，必须从实际 `executionRoot` 构造并随查询记录以下 expected identity：`rootPath`、`worktreeId`（主 checkout 为 `null`）、`repositoryId`、`head`。 采纳返回源码前，必须校验响应中的： - `rootPath` 必须是当前 `executionRoot`（规范化后比较）；不可只比较 repositoryId - `worktreeId` 必须与当前 worktree 相同；主 checkout 必须为 `null` - `repositoryId` 必须与 `harness_paths.repository_identity(project_root)` 一致 - `head`（兼容 `indexedHead`）必须与当前 HEAD 一致 - `indexSnapshotAt`（兼容 `indexedAt`）必须存在 identity 不匹配时必须返回 `IDENTITY_MISMATCH`，包含 expected/actual 的完整 identity，且**不得采纳任何 CodeGraph 源码**；降级为 Grep/Glob + Read 实际 worktree。该状态不同于 index stale，不能以 stale warning 代替。 identity 匹配时正常使用 codegraph 结果。 校验函数： `harness_review.validate_codegraph_identity(response, expected_repository_id, expected_head, expected_root, expected_worktree_id)`。 Review 通过脚本入口执行该校验，例如： ```text python harness_review.py validate-codegraph-identity --input \ --execution-root --repository-id \ --head [--worktree-id ] ```