cr-code-gate

cr-code-gate

Code Review 流水线的第二道门控：代码质量静态门控子 Agent。 由 spec-driven-dev 的 code_review 阶段在 cr-commit-check 通过后调用， 对 diff 进行结构性问题扫描，参照 Sentry 工程实践的必检项分类。

调用契约

输入（由 Orchestrator 注入上下文）

Orchestrator 调用示例（OpenCode Sub-Agent 格式）：

invoke_skill: cr-code-gate
with:
  us_id: "US042"
  iter_id: "iter_003"
  git_diff: "<diff output>"
  iter_summary_path: "requirements/US042/docs/iteration_summary/current_iter.md"
  coding_standards_path: "auxiliary/coding_standards.md"

输出（写回 Orchestrator）

{
  "agent": "cr-code-gate",
  "verdict": "PASS | WARN | FAIL",
  "h_count": 0,
  "m_count": 0,
  "l_count": 0,
  "findings": [
    {
      "id": "GK-01",
      "logaf": "h",
      "result": "PASS | FAIL | WARN",
      "file": "src/foo.py:42",
      "description": "…",
      "suggestion": "…"
    }
  ]
}

执行协议

Step 0 — 发出启动检查点

[AGENT:cr-code-gate] START  us_id={us_id}  iter_id={iter_id}

Step 1 — 读取上下文

1. 解析 git_diff，提取所有变更文件和具体行变更。
2. 读取 current_iter.md，检索是否有架构/Schema 变更的 senior 确认记录（供 GK-08 使用）。
3. 读取 coding_standards.md，获取项目命名与规范约定（供 GK-10 使用）。

Step 2 — 逐项执行门控检查

对 diff 中每一个变更文件/代码块执行以下 10 项检查：

门控检查项

h 级（任意一项命中 → 整体 FAIL）

GK-01 · 运行时异常

• 数组 / 切片越界访问（未校验长度）
• 空指针 / nil 解引用（未做 nil check）
• 未捕获的异常 / error 被静默丢弃（_ = err）
• goroutine / async 中 panic 未 recover

GK-02 · 性能瓶颈

• 无界循环内嵌套 DB 查询（N+1 问题）
• 算法复杂度 O(n²) 或更高且 n 无上界
• 大对象（> 1 MB）在请求热路径中进行 JSON 序列化/反序列化
• 无缓存的重复计算

GK-03 · 安全漏洞

• SQL / NoSQL 注入（字符串拼接构造查询）
• XSS（未转义的用户输入直接输出到 HTML）
• 硬编码密钥、Token、密码（含正则 (api_key|secret|password|token)\s*=\s*['"][^'"]+['"]）
• 不安全的反序列化（pickle.loads、eval、exec 处理用户数据）
• 路径遍历（../ 未过滤的文件路径拼接）

GK-04 · 权限 / 访问控制缺失

• 新增 API 端点缺少鉴权装饰器 / 中间件
• 删除操作未校验资源所有权
• 管理员接口对普通用户可访问

GK-05 · API 破坏性变更

• 公开 REST / GraphQL 字段被重命名或删除
• 必填参数的默认值被移除
• 响应 Schema 中字段类型变更（如 string → int）

GK-06 · 意外行为修改

• 变更触及了本次迭代 scope 之外的既有逻辑
• 全局常量 / 配置默认值被修改
• 共享工具函数语义变更（影响其他调用方）

m 级（命中 → WARN，记录后可继续）

GK-07 · 测试覆盖不足

• 新增的业务逻辑没有对应的单元测试
• 测试用例中存在 if/for 分支，可能掩盖测试本身的缺陷
• 缺少模拟权限场景的测试（正向 + 越权拒绝）

GK-08 · 重大架构 / Schema 变更未审批

• 引入新的外部框架或库依赖
• 数据库字段新增 / 删除 / 类型变更
• JSON Schema 或 protobuf 定义变更
• 以上任意情形在 current_iter.md 中无 senior 确认记录

l 级（命中 → INFO，可选修复）

GK-09 · 多余或遗留代码

• 已注释掉的代码块（连续 3 行以上）
• 调试语句（print()、console.log()、fmt.Println()、System.out.println()）
• 标注日期超过当前迭代开始日期 30 天的 TODO / FIXME

GK-10 · 命名与规范一致性

• 变量 / 函数 / 文件 / 指标命名与 coding_standards.md 约定不一致
• 文件名大小写与现有同目录文件风格不符
• logger / metric 命名不遵循项目既有前缀约定

Step 3 — 输出逐条发现

每条发现使用统一格式：

[{logaf}] {GK-ID} | 文件: {path}:{line} | 问题: {描述} | 建议: {可操作方案}

示例：

[h] GK-03 | 文件: src/auth/handler.py:47 | 问题: API Key 硬编码在源文件 | 建议: 改为 os.getenv("API_KEY")，在 .env.example 添加占位符
[h] GK-01 | 文件: src/db/query.py:83    | 问题: result[0] 访问前未检查列表长度 | 建议: 改为 result[0] if result else None
[m] GK-07 | 文件: tests/test_auth.py     | 问题: 缺少越权访问的拒绝场景测试 | 建议: 新增 test_access_denied_for_non_owner
[l] GK-09 | 文件: src/utils/parser.py:12 | 问题: 注释掉的旧代码块 | 建议: 删除或移至 CHANGELOG

Step 4 — 返回结构化结果

{
  "agent": "cr-code-gate",
  "verdict": "FAIL",
  "h_count": 2,
  "m_count": 1,
  "l_count": 1,
  "findings": [
    {
      "id": "GK-03", "logaf": "h", "result": "FAIL",
      "file": "src/auth/handler.py:47",
      "description": "API Key 硬编码",
      "suggestion": "改为 os.getenv('API_KEY')"
    }
  ]
}

Step 5 — 发出结束检查点

[AGENT:cr-code-gate] DONE  verdict=PASS|WARN|FAIL  h={N}  m={N}  l={N}

裁决规则

禁止行为

• 禁止对 h 级问题降级为 m 或 l，即使代码作者附有解释。
• 禁止对 diff 之外的既有代码发起检查（只扫描本次变更行）。
• 禁止在 git_diff 为空时静默通过，应报告 GK-06 INFO（本次无代码变更）。
• 禁止自动修改任何源文件，只输出建议和修复指引。