Add skills code review agent example

Author: douzhenyu

docs/skills_code_review_agent/ARCHITECTURE.md

@@ -0,0 +1,54 @@
+# CR Agent 实现阶段 Spec 总览
+
+把整体架构(见 `../ARCHITECTURE.md`)拆成 **7 个可交付阶段(P0–P6)**,每阶段一份 spec,标明目标、前置依赖、交付物、接口契约、验收标准(Definition of Done)。团队可按阶段并行推进、按阶段验收。
+
+## 阶段总览
+
+| 阶段 | 名称 | 关键交付物 | 前置依赖 | 并行机会 |
+|------|------|-----------|----------|----------|
+| P0 | 基础设施 | `schema.sql` + `storage.py` + `init_db.py` | 无 | — |
+| P1 | 输入与 Skill | `parse_diff.py` + `SKILL.md` + `skill_load` | P0 | P2 规则文档可并行 |
+| P2 | 规则引擎 | 6 类规则 + `run_checks.py` + `mask_secrets.py` | P1 | 规则文档与 P1 并行 |
+| P3 | 沙箱与 Filter | `runtime.py` + `policy.py` + `governance.py` | P2 | sandbox 与 filter 内部并行 |
+| P4 | 去重结构化 | `dedupe.py` + finding 组装 | P2, P3 | — |
+| P5 | 编排与报告 | `agent.py` + 报告生成 + dry-run | P0–P4 | — |
+| P6 | 测试验收 | 8 fixtures + `test_cr_agent.py` | P5 | — |
+
+## 依赖关系
+
+```
+P0 → P1 → P2 → P3 → P4 → P5 → P6
+            │        │
+   规则文档可与 P1 并行
+                     │
+            sandbox 与 filter 可内部并行
+```
+
+主线串行,两处并行:
+- **P2 规则文档**纯文本编写,不依赖解析器,可与 P1 同时启动。
+- **P3 sandbox runtime** 与 **filter 治理**职责正交(一个管执行隔离,一个管前置决策),可两人并行实现,最后在 P3 末尾集成。
+
+## 里程碑
+
+| 里程碑 | 完成判据 |
+|--------|----------|
+| P0 完成 | 可建库、可 CRUD、按 task_id join 查询 |
+| P3 完成 | 沙箱能带约束跑脚本,Filter 能拦截高风险脚本 |
+| P5 完成 | 完整链路 dry-run 跑通,产出 `review_report.json` + `.md` |
+| P6 完成 | 8 条样本全过,验收标准 8 条达标 |
+
+## Spec 文件清单
+
+- [`phase-0-foundation.md`](phase-0-foundation.md) — 基础设施层
+- [`phase-1-input-skill.md`](phase-1-input-skill.md) — 输入与 Skill 加载
+- [`phase-2-rules-engine.md`](phase-2-rules-engine.md) — 规则引擎
+- [`phase-3-sandbox-filter.md`](phase-3-sandbox-filter.md) — 沙箱与 Filter
+- [`phase-4-dedupe-structuring.md`](phase-4-dedupe-structuring.md) — 去重结构化
+- [`phase-5-orchestration-report.md`](phase-5-orchestration-report.md) — 编排与报告
+- [`phase-6-test-acceptance.md`](phase-6-test-acceptance.md) — 测试与验收
+
+## 阶段交付建议
+
+- 每个 spec 的 **接口契约**是跨阶段协作的硬约束,改动需同步上下游。
+- 每个 spec 的 **验收标准(DoD)**是该阶段完成的判定,未达标不进入下一阶段。
+- **风险与注意事项**列了该阶段最容易踩的坑,实现前先看。

docs/skills_code_review_agent/specs/README.md

@@ -0,0 +1,92 @@
+# Phase 0 — 基础设施层 (Foundation)
+
+> 里程碑阶段。建立数据库 schema 和存储抽象层,为所有后续阶段提供持久化基础。
+
+## 阶段目标
+
+实现七表 schema 和 `ReviewStore` 存储接口。所有后续阶段(P1–P6)都依赖本阶段的接口来落库。本阶段完成后,数据库可建、可写、可按 `task_id` join 查询。
+
+## 前置依赖
+
+无。本阶段是整条流水线的起点。
+
+## 交付物
+
+| 文件 | 职责 |
+|------|------|
+| `db/schema.sql` | 七表建表 DDL + 索引 |
+| `db/storage.py` | `ReviewStore` 抽象 + `SQLiteStore` 实现 |
+| `db/init_db.py` | 初始化脚本(建库 + 建表) |
+
+## 接口契约
+
+### 数据库表
+
+七表定义见 `../ARCHITECTURE.md` 第 5.2 节 DDL。表清单:`review_task` / `input_diff` / `sandbox_run` / `finding` / `filter_block` / `monitor_summary` / `review_report`。
+
+### ReviewStore 接口(`storage.py`)
+
+```python
+from typing import Protocol
+
+class ReviewStore(Protocol):
+    # —— task 生命周期 ——
+    def create_task(self, input_type: str, input_ref: str, mode: str) -> str: ...
+    def update_task_status(self, task_id: str, status: str,
+                           total_duration_ms: int | None = None) -> None: ...
+
+    # —— 子表写入(均返回记录 id)——
+    def add_input_diff(self, task_id, file_path, sha256,
+                       hunk_count, line_count, summary) -> str: ...
+    def add_sandbox_run(self, task_id, runtime, script, status,
+                        duration_ms, exit_code, output_bytes,
+                        timed_out, masked_count) -> str: ...
+    def add_finding(self, task_id, severity, category, file, line,
+                    title, evidence, recommendation, confidence,
+                    source, bucket) -> str: ...
+    def add_filter_block(self, task_id, reason, target,
+                         decision, detail) -> str: ...
+    def set_monitor_summary(self, task_id, summary: dict) -> None: ...
+    def set_report(self, task_id, json_path, md_path, summary) -> str: ...
+
+    # —— 查询 ——
+    def get_task(self, task_id: str) -> dict: ...
+        # join 返回完整记录:
+        # {task, input_diffs[], sandbox_runs[],
+        #  findings[], filter_blocks[], monitor_summary, report}
+```
+
+### SQLiteStore 实现要点
+
+- 连接:`sqlite3.connect(db_path)`,`row_factory = sqlite3.Row`
+- 切换后端:只需新实现同一 Protocol(如 `PostgresStore`),上层无感
+- 事务:单条写入自动 commit;批量 finding 用 `executemany`
+- id 生成:`uuid4().hex`
+
+## 实现要点
+
+- `schema.sql` 全部用 `CREATE TABLE IF NOT EXISTS`,可重复执行
+- 索引 `idx_finding_dedup (task_id, file, line, category)` 必须建,直接服务 P4 去重
+- `monitor_summary.exception_types` 存 JSON 字符串(如 `{"timeout":2,"oom":1}`)
+- `sandbox_run.timed_out` 用 INTEGER 0/1(SQLite 无原生 bool)
+- `finding.confidence` 用 REAL(浮点)
+
+## 验收标准 (DoD)
+
+- [ ] `init_db.py` 能建库建表,重复执行不报错
+- [ ] `create_task` 返回 task_id,`update_task_status` 可改状态
+- [ ] 七个 `add_*` / `set_*` 方法可写入对应表
+- [ ] `get_task(task_id)` 能 join 返回完整记录(task + input_diffs + sandbox_runs + findings + filter_blocks + monitor_summary + report)
+- [ ] `SQLiteStore` 实现同一 Protocol,后续可替换为其他 SQL 后端而不改上层
+
+## 风险与注意事项
+
+- **SQLite 并发写**:单文件 SQLite 写锁粒度大,生产高并发需切 Postgres。接口已预留,实现时不要在 Protocol 里暴露 SQLite 特有 API。
+- **大 diff 的 input_diff 行数**:`summary` 字段存摘要(文件数/hunk 数/行数),**不存全量 diff**。
+- **finding 批量插入**:单次评审可能产数百条 finding,用 `executemany` 而非循环单插。
+- **外键约束**:SQLite 默认关闭外键,`init_db` 需 `PRAGMA foreign_keys = ON`。
+
+## 关联文件
+
+- 上游契约:`../ARCHITECTURE.md` 第 5 节(schema + ER)
+- 下游消费:P1–P6 全部阶段(都调 `ReviewStore`)

docs/skills_code_review_agent/specs/phase-0-foundation.md

@@ -0,0 +1,122 @@
+# Phase 1 — 输入与 Skill 加载
+
+> 把原始 diff 变成结构化 ChangeSet,并加载 code-review Skill 的规则清单与脚本目录。
+
+## 阶段目标
+
+实现 unified diff 解析器和 Skill 加载器。产出 `ChangeSet`(文件/hunk/行号)和 `RuleSet`(规则 + 脚本清单),供 P2 规则引擎和 P3 沙箱消费。
+
+## 前置依赖
+
+- **P0**:`ReviewStore` 可用(解析结果写入 `input_diff` 表)
+
+## 交付物
+
+| 文件 | 职责 |
+|------|------|
+| `skills/code-review/SKILL.md` | Skill 契约 frontmatter |
+| `skills/code-review/scripts/parse_diff.py` | unified diff → `ChangeSet` |
+| `agent.py` 内 `skill_load()` | 读 SKILL.md → 规则 + 脚本 + 沙箱配置 |
+
+## 接口契约
+
+### ChangeSet 数据结构
+
+```python
+@dataclass
+class DiffLine:
+    type: str               # "add" | "del" | "ctx"
+    content: str
+    new_line_no: int | None # add/ctx 行有,del 行为 None
+
+@dataclass
+class Hunk:
+    old_start: int
+    new_start: int
+    old_count: int
+    new_count: int
+    lines: list[DiffLine]
+
+@dataclass
+class ChangedFile:
+    path: str
+    status: str             # "added" | "modified" | "deleted"
+    hunks: list[Hunk]
+
+@dataclass
+class ChangeSet:
+    files: list[ChangedFile]
+```
+
+### parse_diff 接口
+
+```python
+def parse_diff(diff_text: str) -> ChangeSet: ...
+```
+
+支持标准 unified diff:
+```
+diff --git a/foo.py b/foo.py
++++ b/foo.py
+@@ -10,3 +10,4 @@
+ context line
+-old line
++new line
++added line
+```
+
+行号规则:`new_line_no` 从 `+c`(`@@ -a,b +c,d @@`)开始递增,只在 **add / ctx** 行赋值,del 行为 None。
+
+### skill_load 接口
+
+```python
+def skill_load(skill_dir: str) -> dict:
+    return {
+        "name": "code-review",
+        "rules": ["rules/security.md", ...],     # rules/*.md
+        "scripts": ["scripts/run_checks.py", ...], # scripts/*.py
+        "sandbox_config": {
+            "default_runtime": "container",
+            "fallback": "local",
+            "timeout_s": 30,
+            "max_output_bytes": 1048576,
+            "env_whitelist": ["PATH", "HOME", "LANG"]
+        }
+    }
+```
+
+### SKILL.md frontmatter
+
+见 `../ARCHITECTURE.md` 第 7.1 节。
+
+## 实现要点
+
+- 解析 `@@ -a,b +c,d @@`:正则 `^@@ -(\d+),?(\d*) \+(\d+),?(\d*) @@`
+- 多文件分割:按 `diff --git` 或 `+++ b/` 行切分
+- `skill_load` 用 `yaml` 解析 frontmatter(`---` 之间)
+- 脚本清单只收集 `scripts/*.py`,规则清单只收集 `rules/*.md`
+- repo-path 模式:调 `git diff HEAD`(已暂存+未暂存),需在 `agent.py` 处理
+
+## 验收标准 (DoD)
+
+- [ ] `parse_diff` 能解析标准 unified diff,正确提取文件/hunk/行号
+- [ ] add 行的 `new_line_no` 正确(用已知 diff 对照测试)
+- [ ] `skill_load` 能读 SKILL.md frontmatter,产出 `rules` + `scripts` + `sandbox_config`
+- [ ] `ChangeSet` 可落库:file_path / sha256 / hunk_count / line_count / summary 写入 `input_diff` 表
+- [ ] 支持 `--diff-file` / `--repo-path` / fixture 三种输入
+
+## 风险与注意事项
+
+- **git diff 格式变种**:binary 文件、rename、mode change 需容错跳过,不报错。
+- **大 diff 性能**:行级解析,避免全量字符串复制;用生成器/迭代器处理行。
+- **repo-path 模式**:`git diff` 取 unstaged 还是 `git diff HEAD` 需明确,建议默认 `HEAD`(含已暂存)。
+- **空 diff**:返回空 `ChangeSet`,不报错(对应 P6 的"无问题 diff"样本)。
+
+## 并行机会
+
+P2 的规则文档(`rules/*.md`)是纯文本,不依赖解析器,可由另一人与本阶段同时编写。
+
+## 关联文件
+
+- 上游:用户输入(diff 文件 / repo / fixture)
+- 下游:P2(ChangeSet 喂规则引擎)、P3(脚本清单喂 Filter)

docs/skills_code_review_agent/specs/phase-1-input-skill.md

@@ -0,0 +1,105 @@
+# Phase 2 — 规则引擎
+
+> 实现 6 类规则文档与匹配脚本,把 ChangeSet 变成原始诊断列表,并提供敏感信息脱敏。
+
+## 阶段目标
+
+实现 6 类规则(超出要求的 4 类)和 `run_checks.py` 规则匹配器,产出 `RawFinding` 列表;实现 `mask_secrets.py` 敏感信息脱敏。本阶段产出的是**未去重、未分流**的原始诊断,交 P4 处理。
+
+## 前置依赖
+
+- **P1**:`ChangeSet` + `RuleSet` 可用
+
+## 交付物
+
+| 文件 | 职责 |
+|------|------|
+| `skills/code-review/rules/security.md` | 安全风险规则 |
+| `skills/code-review/rules/async_errors.md` | 异步错误规则 |
+| `skills/code-review/rules/resource_leak.md` | 资源泄漏规则 |
+| `skills/code-review/rules/missing_tests.md` | 测试缺失规则 |
+| `skills/code-review/rules/sensitive_info.md` | 敏感信息规则 |
+| `skills/code-review/rules/db_lifecycle.md` | 数据库生命周期规则 |
+| `skills/code-review/scripts/run_checks.py` | 规则匹配 → `RawFinding` |
+| `skills/code-review/scripts/mask_secrets.py` | 敏感信息脱敏 |
+
+## 接口契约
+
+### RawFinding 结构
+
+```python
+@dataclass
+class RawFinding:
+    category: str          # security|async|resource|tests|sensitive|db
+    file: str
+    line: int
+    title: str
+    evidence: str
+    severity_hint: str     # critical|high|medium|low (规则建议,最终 severity 在 P4 定)
+    confidence: float      # 0.0-1.0
+    source: str = "rule"   # rule|sandbox|llm
+```
+
+### run_checks 接口
+
+```python
+def run_checks(changeset: ChangeSet, ruleset: dict) -> list[RawFinding]: ...
+```
+
+读取 `ruleset["rules"]` 的规则文档,对 `changeset` 的 **add 行**做模式匹配 / AST 分析,产出 `RawFinding` 列表。
+
+### mask_secrets 接口
+
+```python
+def mask_secrets(text: str) -> tuple[str, int]:
+    """返回 (脱敏后文本, 命中数)"""
+```
+
+### 六类规则覆盖
+
+| 规则文档 | 覆盖问题 | 检测方式 | severity_hint |
+|----------|----------|----------|---------------|
+| `security.md` | SQL 注入 / 命令注入 / 硬编码密钥 / 不安全反序列化 | 静态模式 + (沙箱)semgrep | critical / high |
+| `async_errors.md` | 未 await 协程 / 未处理 rejection / async 资源泄漏 | AST 解析 | high / medium |
+| `resource_leak.md` | 未关闭文件连接 / try 无 finally | AST + 控制流 | high / medium |
+| `missing_tests.md` | 新增公开函数无对应测试 | diff 关联分析 | low |
+| `sensitive_info.md` | 明文 API key / token / password | 正则 + 熵值 | critical |
+| `db_lifecycle.md` | 连接未关闭 / 事务未提交回滚 / 连接池泄漏 | AST | high / medium |
+
+## 实现要点
+
+- **规则文档格式**:每条规则含 `id` / `pattern` / `severity_hint` / `confidence` / `description`
+- **只分析 add 行**:del 行是删除的代码,不报新问题
+- **confidence 由匹配强度决定**:精确模式 0.9,模糊/启发式 0.6
+- **mask_secrets 正则集**:
+  - `AKIA[0-9A-Z]{16}`(AWS key)
+  - `sk-[a-zA-Z0-9]{20,}`(OpenAI)
+  - `ghp_[a-zA-Z0-9]{36}`(GitHub token)
+  - `password\s*=\s*['"].*['"]`
+  - `-----BEGIN .* PRIVATE KEY-----`
+- **熵值检测**:连续高熵字符串(疑似密钥)Shannon entropy > 4.5
+- **脱敏替换**:命中片段替换为 `***REDACTED***`
+
+## 验收标准 (DoD)
+
+- [ ] 6 类规则文档齐全,每类至少 3 条具体规则
+- [ ] `run_checks` 对每类规则的样本 diff 能检出对应问题
+- [ ] `RawFinding` 字段齐全,`confidence` 合理
+- [ ] `mask_secrets` 能脱敏常见密钥格式,`masked_count` 正确
+- [ ] 无问题的 diff 产出空列表(不误报,对应 P6 的"无问题 diff"样本)
+
+## 风险与注意事项
+
+- **误报控制**:模式匹配易误报,`confidence` 偏低让 P4 分流到 `warnings`,避免污染高置信 findings。
+- **AST 解析依赖**:Python 用 `ast` 模块;其他语言可降级为模式匹配。
+- **性能**:大 diff 行数多,规则匹配用编译后的正则(`re.compile`)。
+- **规则文档可读性**:文档要让人能读懂规则意图,不只是机器格式。
+
+## 并行机会
+
+规则文档(`rules/*.md`)是纯文本,不依赖解析器,可与 P1 并行编写。
+
+## 关联文件
+
+- 上游:P1 `ChangeSet` + `RuleSet`
+- 下游:P3(脚本在沙箱跑)、P4(`RawFinding` 喂去重)