diff --git a/skills/code-review-expert/SKILL.md b/skills/code-review-expert/SKILL.md new file mode 100644 index 00000000..67a31bd6 --- /dev/null +++ b/skills/code-review-expert/SKILL.md @@ -0,0 +1,251 @@ +--- +name: code-review-expert +description: > + 通用代码审核专家 — 基于 git worktree 隔离的多 Agent 并行代码审核系统,集成 Context7 MCP 三重验证对抗代码幻觉。 + 语言无关,适用于任意技术栈(Go, Python, JS/TS, Rust, Java, C# 等)。 + Use when: (1) 用户要求代码审核、code review、安全审计、性能审查, + (2) 用户说"审核代码"、"review"、"检查代码质量"、"安全检查", + (3) 用户要求对 PR、分支、目录或文件做全面质量检查, + (4) 用户提到"代码审核专家"或"/code-review-expert"。 + 五大审核维度:安全合规、架构设计、性能资源、可靠性数据完整性、代码质量可观测性。 + 自动创建 5 个 git worktree 隔离环境,派发 5 个专项子 Agent 并行审核, + 通过 Context7 MCP 拉取最新官方文档验证 API 用法,消除 LLM 幻觉, + 汇总后生成结构化 Markdown 审核报告,最终自动清理所有 worktree。 +--- + +# Universal Code Review Expert + +基于 git worktree 隔离 + 5 子 Agent 并行 + Context7 反幻觉验证的通用代码审核系统。 + +## Guardrails + +- **只读审核**,绝不修改源代码,写入仅限报告文件 +- **语言无关**,通过代码模式识别而非编译发现问题 +- 每个子 Agent 在独立 **git worktree** 中工作 +- 审核结束后**无条件清理**所有 worktree(即使中途出错) +- 问题必须给出**具体 `file:line`**,不接受泛泛而谈 +- 涉及第三方库 API 的发现必须通过 **Context7 MCP** 验证,严禁凭记忆断言 API 状态 +- 文件 > 500 个时自动启用**采样策略** +- **上下文保护**:严格遵循下方 Context Budget Control 规则,防止 200K 上下文耗尽 + +## Context Budget Control (上下文预算管理) + +> **核心问题**:5 个子 Agent 并行审核时,每个 Agent 读取大量文件会快速耗尽 200K 上下文,导致审核卡住或失败。 + +### 预算分配策略 + +主 Agent 在 Phase 0 必须计算上下文预算,并分配给子 Agent: + +``` +总可用上下文 ≈ 180K tokens(预留 20K 给主 Agent 汇总) +每个子 Agent 预算 = 180K / 5 = 36K tokens +每个子 Agent 可读取的文件数 ≈ 36K / 平均文件大小 +``` + +### 七项强制规则 + +1. **文件分片不重叠**:每个文件只分配给**一个主要维度**(按文件类型/路径自动判断),不要多维度重复审核同一文件。高风险文件(auth、crypto、payment)例外,可分配给最多 2 个维度。 + +2. **单文件读取上限**:子 Agent 读取单个文件时,使用 `Read` 工具的 `limit` 参数,每次最多读取 **300 行**。超过 300 行的文件分段读取,仅审核关键段落。 + +3. **子 Agent prompt 精简**:传递给子 Agent 的 prompt 只包含: + - 该维度的**精简检查清单**(不要传全部 170 项,只传该维度的 ~30 项) + - 文件列表(路径即可,不包含内容) + - C7 缓存中**该维度相关的**部分(不传全量缓存) + - 输出格式模板(一次,不重复) + +4. **结果输出精简**:子 Agent 找到问题后只输出 JSON Lines,**不要**输出解释性文字、思考过程或总结。完成后只输出 status 行。 + +5. **子 Agent max_turns 限制**:每个子 Agent 使用 `max_turns` 参数限制最大轮次: + - 文件数 ≤ 10: `max_turns=15` + - 文件数 11-30: `max_turns=25` + - 文件数 31-60: `max_turns=40` + - 文件数 > 60: `max_turns=50` + +6. **大仓库自动降级**: + - 文件数 > 200:减为 **3 个子 Agent**(安全+可靠性、架构+性能、质量+可观测性) + - 文件数 > 500:减为 **2 个子 Agent**(安全重点、质量重点)+ 采样 30% + - 文件数 > 1000:单 Agent 串行 + 采样 15% + 仅审核变更文件 + +7. **子 Agent 使用 `run_in_background`**:所有子 Agent Task 调用设置 `run_in_background=true`,主 Agent 通过 Read 工具轮询 output_file 获取结果,避免子 Agent 的完整输出回填到主 Agent 上下文。 + +### 文件分配算法 + +按文件路径/后缀自动分配到主要维度: + +| 模式 | 主维度 | 辅助维度(仅高风险文件) | +|------|--------|----------------------| +| `*auth*`, `*login*`, `*jwt*`, `*oauth*`, `*crypto*`, `*secret*` | Security | Reliability | +| `*route*`, `*controller*`, `*handler*`, `*middleware*`, `*service*` | Architecture | - | +| `*cache*`, `*pool*`, `*buffer*`, `*queue*`, `*worker*` | Performance | - | +| `*db*`, `*model*`, `*migration*`, `*transaction*` | Reliability | Performance | +| `*test*`, `*spec*`, `*log*`, `*metric*`, `*config*`, `*deploy*` | Quality | - | +| 其余文件 | 按目录轮询分配到 5 个维度 | - | + +### 主 Agent 汇总时的上下文控制 + +Phase 3 汇总时,主 Agent **不要**重新读取子 Agent 审核过的文件。仅基于子 Agent 输出的 JSON Lines 进行: +- 去重合并 +- 严重等级排序 +- Context7 交叉验证(仅对 critical/high 且未验证的少数发现) +- 填充报告模板 + +--- + +## Workflow + +### Phase 0 — Scope Determination + +1. **确定审核范围**(按优先级): + - 用户指定的文件/目录 + - 未提交变更:`git diff --name-only` + `git diff --cached --name-only` + - 未推送提交:`git log origin/{main}..HEAD --name-only --pretty=format:""` + - 全仓库(启用采样:变更文件 → 高风险目录 → 入口文件 → 其余 30% 采样) + +2. **收集项目元信息**:语言构成、目录结构、文件数量 + +3. **生成会话 ID**: + ```bash + SESSION_ID="cr-$(date +%Y%m%d-%H%M%S)-$(openssl rand -hex 4)" + WORKTREE_BASE="/tmp/${SESSION_ID}" + ``` + +4. 将文件分配给 5 个审核维度(每个文件可被多维度审核) + +### Phase 0.5 — Context7 Documentation Warm-up (反幻觉第一重) + +> 详细流程见 [references/context7-integration.md](references/context7-integration.md) + +1. 扫描依赖清单(go.mod, package.json, requirements.txt, Cargo.toml, pom.xml 等) +2. 提取核心直接依赖,按优先级筛选最多 **10 个关键库**: + - P0 框架核心(web 框架、ORM)→ P1 安全相关 → P2 高频 import → P3 其余 +3. 对每个库调用 `resolve-library-id` → `get-library-docs`(每库 ≤ 5000 tokens) +4. 构建 **C7 知识缓存 JSON**,传递给所有子 Agent +5. **降级**:Context7 不可用时跳过,报告标注 "未经官方文档验证" + +### Phase 1 — Worktree Creation + +```bash +CURRENT_COMMIT=$(git rev-parse HEAD) +for dim in security architecture performance reliability quality; do + git worktree add "${WORKTREE_BASE}/${dim}" "${CURRENT_COMMIT}" --detach +done +``` + +### Phase 2 — Parallel Sub-Agent Dispatch (反幻觉第二重) + +**在一条消息中发出所有 Task 调用**(`subagent_type: general-purpose`),**必须设置**: +- `run_in_background: true` — 子 Agent 后台运行,结果写入 output_file,避免回填主 Agent 上下文 +- `max_turns` — 按文件数量设置(见 Context Budget Control) +- `model: "sonnet"` — 子 Agent 使用 sonnet 模型降低延迟和 token 消耗 + +Agent 数量根据文件规模自动调整(见 Context Budget Control 大仓库降级规则)。 + +每个 Agent 收到: + +| 参数 | 内容 | +|------|------| +| worktree 路径 | `${WORKTREE_BASE}/{dimension}` | +| 文件列表 | 该维度**独占分配**的文件(不重叠) | +| 检查清单 | 该维度对应的精简清单(~30 项,非全量 170 项) | +| C7 缓存 | 仅该维度相关的库文档摘要 | +| 输出格式 | JSON Lines(见下方) | +| 文件读取限制 | 单文件最多 300 行,使用 Read 的 limit 参数 | + +每个发现输出一行 JSON: +```json +{ + "dimension": "security", + "severity": "critical|high|medium|low|info", + "file": "path/to/file.go", + "line": 42, + "rule": "SEC-001", + "title": "SQL Injection", + "description": "详细描述", + "suggestion": "修复建议(含代码片段)", + "confidence": "high|medium|low", + "c7_verified": true, + "verification_method": "c7_cache|c7_realtime|model_knowledge", + "references": ["CWE-89"] +} +``` + +**关键规则**: +- 涉及第三方库 API 的发现,未经 Context7 验证时 `confidence` 不得为 `high` +- `verification_method == "model_knowledge"` 的发现自动降一级置信度 +- 每个子 Agent 最多消耗分配的 Context7 查询预算 +- 完成后输出:`{"status":"complete","dimension":"...","files_reviewed":N,"issues_found":N,"c7_queries_used":N}` + +### Phase 3 — Aggregation + Cross-Validation (反幻觉第三重) + +1. 等待所有子 Agent 完成 +2. 合并 findings,按 severity 排序 +3. **Context7 交叉验证**: + - 筛选 `c7_verified==false` 且 severity 为 critical/high 的 API 相关发现 + - 主 Agent 独立调用 Context7 验证 + - 验证通过 → 保留 | 验证失败 → 降级或删除(标记 `c7_invalidated`) +4. 去重(同一 file:line 合并) +5. 生成报告到 `code-review-report.md`(模板见 [references/report-template.md](references/report-template.md)) + +### Phase 4 — Cleanup (必须执行) + +```bash +for dim in security architecture performance reliability quality; do + git worktree remove "${WORKTREE_BASE}/${dim}" --force 2>/dev/null +done +git worktree prune +rm -rf "${WORKTREE_BASE}" +``` + +> 即使前面步骤失败也**必须执行**此清理。 + +## Severity Classification + +| 等级 | 标签 | 定义 | +|------|------|------| +| P0 | `critical` | 已存在的安全漏洞或必然导致数据丢失/崩溃 | +| P1 | `high` | 高概率触发的严重问题或重大性能缺陷 | +| P2 | `medium` | 可能触发的问题或明显设计缺陷 | +| P3 | `low` | 代码质量问题,不直接影响运行 | +| P4 | `info` | 优化建议或最佳实践提醒 | + +置信度:`high` / `medium` / `low`,低置信度须说明原因。 + +## Five Review Dimensions + +每个维度对应一个子 Agent,详细检查清单见 [references/checklists.md](references/checklists.md): + +1. **Security & Compliance** — 注入漏洞(10 类)、认证授权、密钥泄露、密码学、依赖安全、隐私保护 +2. **Architecture & Design** — SOLID 原则、架构模式、API 设计、错误策略、模块边界 +3. **Performance & Resource** — 算法复杂度、数据库性能、内存管理、并发性能、I/O、缓存、资源泄漏 +4. **Reliability & Data Integrity** — 错误处理、空值安全、并发安全、事务一致性、超时重试、边界条件、优雅关闭 +5. **Code Quality & Observability** — 复杂度、重复、命名、死代码、测试质量、日志、可观测性、构建部署 + +## Context7 Anti-Hallucination Overview + +> 详细集成文档见 [references/context7-integration.md](references/context7-integration.md) + +三重验证防御 5 类 LLM 幻觉: + +| 幻觉类型 | 说明 | 防御层 | +|----------|------|--------| +| API 幻觉 | 错误断言函数签名 | 第一重 + 第二重 | +| 废弃幻觉 | 错误标记仍在用的 API 为 deprecated | 第二重 + 第三重 | +| 不存在幻觉 | 声称新增 API 不存在 | 第一重 + 第二重 | +| 参数幻觉 | 错误描述参数类型/默认值 | 第二重实时查 | +| 版本混淆 | 混淆不同版本 API 行为 | 第一重版本锚定 | + +验证覆盖度评级:`FULL` (100% API 发现已验证) > `PARTIAL` (50%+) > `LIMITED` (<50%) > `NONE` + +## Error Handling + +- 某个子 Agent 失败:继续汇总其他结果,报告标注不完整维度 +- git worktree 创建失败:`git worktree prune` 重试 → 仍失败则回退串行模式 +- Context7 不可用:跳过验证阶段,报告标注 "未经官方文档验证" +- 所有情况下 **Phase 4 清理必须执行** + +## Resources + +- **[references/checklists.md](references/checklists.md)** — 5 个子 Agent 的完整检查清单 (~170 项) +- **[references/context7-integration.md](references/context7-integration.md)** — Context7 MCP 集成详细流程、缓存格式、查询规范 +- **[references/report-template.md](references/report-template.md)** — 审核报告 Markdown 模板 diff --git a/skills/code-review-expert/references/checklists.md b/skills/code-review-expert/references/checklists.md new file mode 100644 index 00000000..ad3a9e33 --- /dev/null +++ b/skills/code-review-expert/references/checklists.md @@ -0,0 +1,252 @@ +# Sub-Agent Review Checklists + +5 个子 Agent 的完整检查清单。每个子 Agent 在独立 git worktree 中工作。 + +--- + +## Agent 1: Security & Compliance (安全与合规) + +### 1.1 Injection (注入漏洞) +- SQL 注入:字符串拼接 SQL、未使用参数化查询 +- 命令注入:exec/system/os.Command/subprocess 拼接用户输入 +- XSS:未转义的用户输入写入 HTML/DOM +- XXE:XML 解析器未禁用外部实体 +- SSRF:用户可控 URL 用于服务端请求,缺少白名单 +- LDAP 注入:LDAP 查询拼接用户输入 +- SSTI:用户输入直接传入模板引擎 +- 路径穿越:文件操作中未校验 `../` +- Header 注入:HTTP 响应头拼接用户输入 (CRLF) +- Log 注入:日志中拼接未净化的用户输入 + +### 1.2 Authentication & Authorization +- 缺少认证:敏感 API 端点未要求身份验证 +- 越权访问:缺少资源归属校验(水平越权) +- 权限提升:普通用户可执行管理员操作(垂直越权) +- 会话管理:Session fixation、不安全 cookie、缺少超时 +- JWT:弱签名算法 (none/HS256)、未验证签名、token 泄露 +- OAuth:开放重定向、state 缺失、token 存储不安全 +- 默认凭证:代码中预设的用户名密码 + +### 1.3 Secrets & Sensitive Data +- 硬编码密钥:API key、密码、token、连接字符串写在源码 +- 密钥泄露:.env 提交版本控制、明文密码 +- 日志泄露:敏感数据出现在日志/错误信息中 +- API 响应泄露:接口返回超出必要范围的用户数据 +- 错误信息泄露:堆栈、内部路径、数据库结构暴露 + +### 1.4 Cryptography +- 弱哈希:MD5/SHA1 用于密码或安全场景 +- 不安全随机数:math/rand 替代 CSPRNG +- ECB 模式:AES-ECB 等不安全加密模式 +- 硬编码 IV/Salt +- 缺少完整性校验:加密但未做 HMAC/AEAD + +### 1.5 Dependency Security +- 已知漏洞:依赖清单中的 CVE +- 过时依赖:已停止维护的库 +- 依赖来源:非官方源、typosquatting +- 许可证合规:GPL 等传染性许可证混入商业项目 + +### 1.6 Privacy & Data Protection +- PII 未加密存储或传输 +- 缺少数据过期/删除机制 +- 跨境传输未考虑地域合规 + +--- + +## Agent 2: Architecture & Design (架构与设计) + +### 2.1 Design Principles +- SRP:类/函数/模块承担过多职责 +- OCP:修改核心逻辑而非通过扩展点添加 +- LSP:子类/实现违反父类/接口契约 +- ISP:接口过大,强迫实现不需要的方法 +- DIP:高层模块直接依赖低层实现 + +### 2.2 Architectural Patterns +- 分层违规:跨层直接调用 +- 循环依赖:包/模块间循环引用 +- 上帝对象:单类承载过多数据和行为 +- 过度抽象:不必要的工厂/策略/装饰器 +- 模式误用:强行套用不适合的设计模式 +- 配置管理:硬编码环境相关值 + +### 2.3 API Design +- 一致性:同系统 API 风格不一致 +- 向后兼容:破坏性变更未版本控制 +- 幂等性:写操作缺少幂等保证 +- 批量操作:逐条处理导致 N+1 网络请求 +- 分页:大列表缺少分页/游标 +- 错误响应:格式不统一、缺少错误码 + +### 2.4 Error Handling Strategy +- 错误传播:底层错误未包装丢失上下文 +- 错误类型:字符串替代结构化错误 +- 恢复策略:缺少重试/降级/断路器 +- 边界处理:系统边界缺少防御性检查 + +### 2.5 Module Boundaries +- 接口定义:模块间通过实现而非接口通信 +- 数据共享:模块间共享可变数据结构 +- 事件/消息:同步调用链过长 +- 领域模型:贫血模型、逻辑散落 Service 层 + +--- + +## Agent 3: Performance & Resource (性能与资源) + +### 3.1 Algorithm & Data Structure +- 热路径上 O(n^2) 或更高复杂度 +- 不当数据结构:线性查找替代哈希 +- 循环内重复计算 +- 不必要的排序/遍历 + +### 3.2 Database Performance +- N+1 查询:循环内逐条查询 +- 缺少索引:WHERE/JOIN 字段未建索引 +- 全表扫描 +- 大事务持锁过久 +- 连接池未配置或配置不当 +- SELECT * 替代指定字段 + +### 3.3 Memory Management +- 内存泄漏:未释放引用、全局缓存无上限 +- 循环内创建大对象/切片 +- 未使用缓冲 I/O、一次性读取大文件 +- 循环内字符串拼接 +- 高频对象未使用池化 + +### 3.4 Concurrency Performance +- 全局锁替代细粒度锁 +- 热点资源锁竞争 +- 无限制创建 goroutine/线程 +- 对只读数据加锁 +- 无缓冲通道导致阻塞 + +### 3.5 I/O Performance +- 异步上下文中阻塞调用 +- HTTP 客户端未复用连接 +- 大响应未压缩 +- 大数据一次性加载替代流式 + +### 3.6 Caching +- 频繁重复计算/查询未缓存 +- 缓存穿透:不存在 key 反复查 DB +- 缓存雪崩:大量 key 同时过期 +- 更新后未失效缓存 +- 无界缓存导致 OOM + +### 3.7 Resource Leaks +- 文件句柄:打开未关闭 +- HTTP response body 未关闭 +- 数据库查询结果集未关闭 +- Timer/Ticker/订阅未取消 +- Goroutine/线程启动后永不退出 + +--- + +## Agent 4: Reliability & Data Integrity (可靠性与数据完整性) + +### 4.1 Error Handling +- 静默吞错:空 catch、忽略返回 error +- 泛型 catch:catch(Exception e) +- 错误消息缺少上下文 (who/what/why) +- 库代码中 panic/os.Exit +- 关键路径缺少 recover/降级 + +### 4.2 Null Safety +- 空指针解引用:未检查 nil/null +- Optional/Maybe 未正确解包 +- 空集合直接取下标 +- 长链式调用中环节返回 null + +### 4.3 Concurrency Safety +- 数据竞争:无保护读写共享变量 +- 死锁:多锁嵌套、不一致加锁顺序 +- check-then-act 未加锁 +- 非线程安全 Map 并发使用 +- 向已关闭 channel 发送数据 + +### 4.4 Transaction & Consistency +- 多步数据库操作未包裹事务 +- 不恰当的事务隔离级别 +- 跨服务缺少补偿/Saga +- 异步处理缺少确认/重试 +- 重试产生重复数据 + +### 4.5 Timeout & Retry +- HTTP/DB/RPC 调用未设超时 +- 无限重试或缺少退避 +- 调用链超时未传递/收缩 +- 缺少断路器保护 + +### 4.6 Boundary Conditions +- 整数溢出:大数、类型截断 +- 浮点精度:金额用浮点数 +- 时区未明确 +- UTF-8 多字节未处理 +- 空集合边界 +- 并发 first/last、空队列竞态 + +### 4.7 Graceful Shutdown +- 缺少 SIGTERM/SIGINT 处理 +- 关闭时未等待进行中请求 +- 未释放 DB 连接、文件句柄 +- 内存中待写数据丢失 + +--- + +## Agent 5: Code Quality & Observability (代码质量与可观测性) + +### 5.1 Complexity +- 函数圈复杂度 > 15 +- 深层嵌套 > 4 层 +- 函数超过 100 行 +- 参数超过 5 个 +- 单文件超过 500 行 + +### 5.2 Duplication +- 大段相似代码 > 10 行 +- 相同业务逻辑多处独立实现 +- 魔法数字/字符串多处出现 + +### 5.3 Naming & Readability +- 不符合语言惯例的命名 +- 含义模糊:data/info/temp/result +- 同一概念不同命名 +- 布尔命名不是 is/has/can/should +- 不通用缩写降低可读性 + +### 5.4 Dead Code & Tech Debt +- 未调用的函数、未使用的变量/导入 +- 被注释的代码块 +- TODO/FIXME/HACK 遗留 +- 使用 deprecated API + +### 5.5 Test Quality +- 关键业务路径缺少测试 +- 断言仅检查"不报错" +- 缺少边界和异常路径测试 +- 测试间隐式依赖 +- 过度 mock +- 依赖时间/网络等外部状态 + +### 5.6 Logging +- 关键决策点缺少日志 +- ERROR 级别用于非错误场景 +- 字符串拼接而非结构化日志 +- 日志含密码/token/PII +- 热路径过度日志 + +### 5.7 Observability +- 缺少业务指标(请求量、延迟、错误率) +- 跨服务缺少 trace ID +- 缺少 liveness/readiness 探针 +- 关键故障路径缺少告警 + +### 5.8 Build & Deploy +- 构建结果依赖环境状态 +- 缺少 lock 文件 +- 开发/生产配置差异未文档化 +- 迁移脚本缺少回滚方案 +- 大功能上线缺少 feature flag diff --git a/skills/code-review-expert/references/context7-integration.md b/skills/code-review-expert/references/context7-integration.md new file mode 100644 index 00000000..6d14f8b1 --- /dev/null +++ b/skills/code-review-expert/references/context7-integration.md @@ -0,0 +1,169 @@ +# Context7 MCP Anti-Hallucination Integration + +## Overview + +Context7 MCP 提供两个工具,用于拉取第三方库的最新官方文档,消除 LLM 训练数据时效性导致的代码审核幻觉。 + +## Tools + +### resolve-library-id + +``` +输入: libraryName (如 "gin", "gorm", "react", "express") +输出: Context7 兼容的 library ID (如 "/gin-gonic/gin") +``` + +- 必须在 `get-library-docs` 之前调用 +- 用户已提供 `/org/project` 格式 ID 时可跳过 +- 解析失败则记录到 `c7_failures`,跳过该库 + +### get-library-docs + +``` +输入: + - context7CompatibleLibraryID: 从 resolve-library-id 获取 + - topic (可选): 聚焦主题 (如 "middleware", "hooks", "query") + - tokens (可选): 最大返回 token 数 (默认 5000) +``` + +- 每个库每次审核最多调用 **3 次** +- 优先用 `topic` 缩小范围 +- 缓存首次查询结果,后续复用 + +## Three-Layer Verification + +### Layer 1: Pre-Review Warm-up (Phase 0.5) + +在审核开始前预热文档缓存: + +1. **扫描依赖清单**: + ```bash + for f in go.mod package.json requirements.txt Pipfile pyproject.toml \ + Cargo.toml Gemfile pom.xml build.gradle composer.json mix.exs \ + pubspec.yaml *.csproj; do + [ -f "$f" ] && echo "FOUND: $f" + done + ``` + +2. **提取直接依赖**(按语言): + - Go: `go.mod` require 块(排除 `// indirect`) + - Node: `package.json` 的 `dependencies` + - Python: `requirements.txt` 或 `pyproject.toml` 的 `[project.dependencies]` + - Rust: `Cargo.toml` 的 `[dependencies]` + - Java: `pom.xml` 或 `build.gradle` 的 implementation 依赖 + +3. **优先级筛选**(最多 10 个库): + - P0 框架核心:Web 框架、ORM、核心运行时 + - P1 安全相关:认证库、加密库、JWT 库 + - P2 高频使用:import 次数最多的库 + - P3 其余依赖 + +4. **批量查询 Context7**: + ``` + 对每个库: + id = resolve-library-id(libraryName) + 如果失败 → 记录到 c7_failures, 跳过 + docs = get-library-docs(id, topic="核心 API 概览", tokens=5000) + 缓存到 C7 知识缓存 + queries_remaining[库名] = 2 + ``` + +5. **构建缓存 JSON**: + ```json + { + "session_id": "cr-20260207-143000-a1b2c3d4", + "libraries": { + "gin": { + "context7_id": "/gin-gonic/gin", + "docs_summary": "...(API 摘要)...", + "key_apis": ["gin.Context", "gin.Engine"], + "tokens_used": 5000 + } + }, + "queries_remaining": { "gin": 2 }, + "c7_failures": [] + } + ``` + +> 多个 `resolve-library-id` 可并行调用。 + +### Layer 2: In-Review Realtime Verification (Phase 2) + +子 Agent 审核代码时的实时验证规则: + +**必须验证的场景**: +1. 认为某个 API 调用方式错误 → 查 C7 确认当前版本签名 +2. 认为某个 API 已废弃 → 查 C7 确认 deprecated 状态 +3. 认为代码缺少某库提供的安全/性能特性 → 查 C7 确认该特性存在 +4. 认为代码写法不兼容某版本 → 查 C7 拉取对应版本文档 + +**查询优先级**: +1. 先查 C7 知识缓存(Phase 0.5 预热结果) +2. 缓存未命中 → 调用 `get-library-docs(id, topic="{具体 API 名}")` +3. 遵守每库 3 次查询上限 + +**标注字段**: +```json +{ + "c7_verified": true, + "c7_source": "gin.Context.JSON() accepts int status code and any interface{}", + "verification_method": "c7_cache" +} +``` + +`verification_method` 取值: +- `c7_cache` — 从预热缓存验证 +- `c7_realtime` — 实时调用 Context7 验证 +- `model_knowledge` — 未使用 Context7(置信度自动降一级) + +### Layer 3: Post-Review Cross-Validation (Phase 3) + +主 Agent 汇总时的最终验证: + +``` +对于每个 finding: + 如果 c7_verified == false 且 severity in [critical, high]: + 如果涉及第三方库 API: + docs = get-library-docs(libraryID, topic="{相关 API}") + 如果文档支持 Agent 判断 → c7_verified = true, 保留 + 如果文档与 Agent 矛盾 → 降级为 info 或删除, 标记 c7_invalidated + 如果 Context7 无数据 → 保留, 标注 unverifiable + 否则 (纯逻辑问题): + 跳过 C7 验证, 保持原判断 +``` + +**强制规则**:`verification_method == "model_knowledge"` 的 critical/high API 相关发现,未完成交叉验证则自动降级为 medium。 + +## Degradation Strategy + +| 场景 | 行为 | +|------|------| +| Context7 MCP 未配置 | 跳过所有 C7 阶段,报告标注 NONE 覆盖度 | +| 网络超时 | 重试 1 次,仍失败则跳过该库 | +| `resolve-library-id` 失败 | 记录到 `c7_failures`,跳过该库 | +| 查询配额耗尽 | 使用已缓存的最佳信息 | +| 子 Agent 中 C7 调用失败 | 标注 `verification_method: "model_knowledge"`,降低置信度 | + +## Report Section: Verification Statistics + +审核报告中包含的 Context7 统计节: + +| 指标 | 说明 | +|------|------| +| 检测到的依赖库总数 | 项目直接依赖数 | +| C7 成功解析的库 | resolve-library-id 成功数 | +| C7 解析失败的库 | 失败列表 | +| Pre-Review 查询次数 | Phase 0.5 的 get-library-docs 调用数 | +| In-Review 查询次数 | Phase 2 子 Agent 的实时查询总数 | +| Post-Review 查询次数 | Phase 3 交叉验证查询数 | +| C7 验证通过的发现数 | c7_verified == true | +| C7 纠正的误判数 | c7_invalidated 标记数 | +| 验证覆盖度评级 | FULL / PARTIAL / LIMITED / NONE | + +## Anti-Hallucination Corrections Table + +报告中记录被 Context7 纠正的误判: + +| # | Agent | 原 Severity | 原 Title | 纠正原因 | C7 Source | +|---|-------|------------|---------|---------|-----------| +| 1 | Security | high | API deprecated | C7 文档显示该 API 在 v2.x 中仍为 stable | /lib/docs... | diff --git a/skills/code-review-expert/references/report-template.md b/skills/code-review-expert/references/report-template.md new file mode 100644 index 00000000..82649826 --- /dev/null +++ b/skills/code-review-expert/references/report-template.md @@ -0,0 +1,144 @@ +# Code Review Report Template + +审核报告保存到项目根目录的 `code-review-report.md`,使用以下模板: + +--- + +```markdown +# Code Review Report + +**Project:** {PROJECT_NAME} +**Branch:** {BRANCH} +**Commit:** {COMMIT_SHA} +**Date:** {DATE} +**Scope:** {SCOPE_DESCRIPTION} +**Files Reviewed:** {TOTAL_FILES} + +--- + +## Executive Summary + +| 等级 | 数量 | 占比 | +|------|------|------| +| Critical (P0) | {N} | {%} | +| High (P1) | {N} | {%} | +| Medium (P2) | {N} | {%} | +| Low (P3) | {N} | {%} | +| Info (P4) | {N} | {%} | +| **Total** | **{N}** | **100%** | + +**Overall Risk:** {HIGH/MEDIUM/LOW} — {一句话总结} +**C7 Verification:** {FULL/PARTIAL/LIMITED/NONE} + +--- + +## Critical Issues (P0) — Immediate Action Required + +### [{RULE}] {TITLE} +- **File:** `{FILE}:{LINE}` +- **Dimension:** {DIMENSION} +- **Confidence:** {CONFIDENCE} | **C7 Verified:** {YES/NO} +- **Description:** {DESCRIPTION} +- **Suggestion:** + ```{lang} + {CODE_SUGGESTION} + ``` +- **References:** {REFERENCES} + +--- + +## High Issues (P1) — Fix Before Next Release + +{同上格式} + +--- + +## Medium Issues (P2) — Plan to Fix + +{同上格式} + +--- + +## Low Issues (P3) — Nice to Fix + +| # | Rule | File:Line | Title | Confidence | +|---|------|-----------|-------|------------| +| 1 | {RULE} | `{FILE}:{LINE}` | {TITLE} | {CONF} | + +--- + +## Info (P4) — Suggestions + +| # | File:Line | Suggestion | +|---|-----------|------------| +| 1 | `{FILE}:{LINE}` | {SUGGESTION} | + +--- + +## Hotspot Analysis + +| Rank | File | Issues | Critical | High | Medium | +|------|------|--------|----------|------|--------| +| 1 | {FILE} | {N} | {N} | {N} | {N} | + +--- + +## Dimension Summary + +| 维度 | 文件数 | 问题数 | Critical | High | +|------|--------|--------|----------|------| +| Security & Compliance | {N} | {N} | {N} | {N} | +| Architecture & Design | {N} | {N} | {N} | {N} | +| Performance & Resource | {N} | {N} | {N} | {N} | +| Reliability & Data | {N} | {N} | {N} | {N} | +| Quality & Observability | {N} | {N} | {N} | {N} | + +--- + +## Context7 Verification Statistics + +| 指标 | 数值 | +|------|------| +| 依赖库总数 | {N} | +| C7 成功解析 | {N} | +| C7 解析失败 | {N} ({FAILED_LIBS}) | +| Pre-Review 查询 | {N} | +| In-Review 查询 | {N} | +| Post-Review 查询 | {N} | +| C7 验证通过 | {N} ({%}) | +| C7 纠正误判 | {N} | +| 覆盖度评级 | {FULL/PARTIAL/LIMITED/NONE} | + +### Anti-Hallucination Corrections + +| # | Agent | 原 Severity | Title | 纠正原因 | C7 Source | +|---|-------|------------|-------|---------|-----------| +| 1 | {AGENT} | {SEV} | {TITLE} | {REASON} | {SOURCE} | + +--- + +## Recommendations + +### Immediate Actions (This Sprint) +1. {P0/P1 对应行动项} + +### Short-term (Next 2-3 Sprints) +1. {P2 对应行动项} + +### Long-term +1. {架构级改进} + +--- + +## Methodology + +- **Type:** Multi-agent parallel review + Context7 anti-hallucination +- **Agents:** Security, Architecture, Performance, Reliability, Quality +- **Isolation:** Independent git worktrees per agent +- **Verification:** Context7 three-layer (warm-up → realtime → cross-validation) +- **Policy:** API findings ≥ high require C7 verification; unverified auto-downgraded + +--- + +*Generated by Code Review Expert — Universal Multi-Agent Code Review System with Context7 Anti-Hallucination* +```