oadmin/sub2api
1
0
Fork 0
Code Issues Pull Requests 1 Actions 2 Packages Projects Releases Wiki Activity

feat: update skills

Browse Source
This commit is contained in:
yangjianbo
2026-02-07 22:25:57 +08:00
parent 7546a56736
commit d876686a00
4 changed files with 816 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

251
skills/code-review-expert/SKILL.md Normal file
View File

@@ -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 模板

252
skills/code-review-expert/references/checklists.md Normal file
View File

@@ -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

169
skills/code-review-expert/references/context7-integration.md Normal file
View File

@@ -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... |

144
skills/code-review-expert/references/report-template.md Normal file
View File

@@ -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*
```