feat: update skills

2026-02-07 22:25:57 +08:00
parent 7546a56736
commit d876686a00
4 changed files with 816 additions and 0 deletions
--- a/skills/code-review-expert/references/checklists.md
+++ 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
--- a/skills/code-review-expert/references/context7-integration.md
+++ 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... |
--- a/skills/code-review-expert/references/report-template.md
+++ 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*
+```