Add skills code review agent example

Author: douzhenyu

examples/skills_code_review_agent/.env.example

@@ -0,0 +1,32 @@
+# Code Review Agent — LLM 配置样例（复制为 .env 后按需修改）
+#
+# 所有变量均为可选；缺省即降级为 FakeLlm（不调用任何模型）。
+# 支持任意 OpenAI 兼容端点：OpenAI / Azure OpenAI / 本地 vLLM / 内部 LLM 网关。
+
+# 是否启用真实 LLM 二次研判（也可通过 CLI --enable-llm 覆盖）
+# 取值：true | false
+LLM_ENABLED=false
+
+# 供应商标识（仅用于记录/诊断，不影响端点选择）
+LLM_PROVIDER=openai
+
+# 真实模型 API Key；留空 = 禁用真实模型
+LLM_API_KEY=
+
+# OpenAI 兼容的 Chat Completions 端点基址
+#   OpenAI:      https://api.openai.com/v1
+#   Azure:       https://<res>.openai.azure.com/openai
+#   本地 vLLM:   http://localhost:8000/v1
+LLM_BASE_URL=https://api.openai.com/v1
+
+# 模型名（对应端点上的 deployment / model id）
+LLM_MODEL=gpt-4o-mini
+
+# 采样温度（越低越确定，适合判定任务）
+LLM_TEMPERATURE=0.1
+
+# 单次响应最大 token 数
+LLM_MAX_TOKENS=1024
+
+# 请求超时（秒）
+LLM_TIMEOUT=30

examples/skills_code_review_agent/README.md

@@ -0,0 +1,234 @@
+# Code Review Agent
+
+> 基于 tRPC-Agent Skill 体系的自动代码评审 Agent 原型。输入 git diff / PR patch / 本地变更，输出结构化 findings，并将审查任务、拦截记录、监控摘要、结果写入 SQLite，支持评测、监控、回放。
+
+## 架构设计
+
+这个示例的目标不是让 LLM 直接评论代码，而是把可复用 Skill、沙箱执行、Filter 治理、结构化结果、持久化存储和监控审计串成一条可验证的代码评审链路。输入可以是 unified diff、PR patch 或本地 git 工作区变更；输出是结构化 findings、人工复核项、Filter 拦截摘要、沙箱执行摘要、监控指标和双格式报告。
+
+整体采用六层流水线。L1 输入解析层负责把 `--diff-file`、`--repo-path` 或 fixture 解析成 ChangeSet，提取文件、hunk、上下文和候选行号。L2 Skill 加载层通过 `skill_load` 读取 `skills/code-review/SKILL.md`、规则文档和脚本清单，让规则和执行入口从 Agent 编排中解耦。L3 Filter 治理层在任何脚本进入沙箱前做前置决策，拦截高风险脚本、禁止路径、非白名单网络访问和超预算执行，并把 `deny` / `needs_human_review` 写入数据库和报告。L4 沙箱执行层默认走 Container 或 Cube/E2B runtime，本地只作为开发与 dry-run fallback；每次执行都带超时、输出大小限制、环境变量白名单、脱敏和失败记录。L5 去重结构化层按 `(file, line, category)` 合并重复诊断，并根据置信度把结果分入 findings、warnings 或 needs_human_review。L6 存储输出层把 task、input diff、sandbox run、filter block、finding、monitor summary 和最终 report 写入 SQLite，并生成 `review_report.json` 与 `review_report.md`。
+
+数据流是单向的：CLI 输入先变成 ChangeSet，再加载 code-review Skill 和规则；脚本清单先过 Filter，允许后才进入沙箱执行；沙箱产出的原始诊断统一进入去重和分流；最终结果落库并渲染报告。异常分支也走同一条审计链：Filter 拒绝不会进入沙箱，但会记录拦截原因；沙箱超时、失败或输出截断不会让任务崩溃，而是记录失败并继续生成可查询报告；dry-run 使用 fake runner 跑同一套规则路径，保证没有真实模型 API Key 时也能验证解析、沙箱记录、落库和报告链路。
+
+数据库围绕 `review_task` 建模，其他表都通过 `task_id` 关联。`input_diff` 保存输入摘要，`sandbox_run` 保存 runtime、脚本、状态、耗时、退出码、输出大小、超时和脱敏数量，`finding` 保存结构化问题和 bucket，`filter_block` 保存治理拦截，`monitor_summary` 保存耗时、调用次数、拦截次数、severity 分布和异常类型分布，`review_report` 保存最终报告路径与摘要。这样按 task id 可以回放一次完整评审。
+
+Skill 本身只负责声明和承载可复用评审能力：`SKILL.md` 声明入口、规则列表和沙箱策略，`rules/` 覆盖安全风险、异步错误、资源泄漏、测试缺失、敏感信息泄漏、数据库连接或事务生命周期等类别，`scripts/` 提供 diff 解析、规则检查、去重和脱敏。Agent 编排层只负责加载 Skill、执行治理、调度沙箱、落库和渲染报告。
+
+监控审计贯穿全链路。每次 review 都记录总耗时、沙箱耗时、工具调用次数、Filter 拦截次数、finding 数量、严重级别分布和异常类型分布；这些字段同时进入数据库和报告，便于后续评测、监控和问题回放。
+
+### 目录结构
+
+```
+skills_code_review_agent/
+├── .env                  # 运行配置（LLM 等，安全默认，不提交密钥）
+├── .env.example          # 配置模板
+├── run_agent.py          # CLI 薄入口（load_dotenv → 调用 agent.agent.main）
+├── README.md
+├── agent/                # 所有内部模块
+│   ├── __init__.py
+│   ├── agent.py          # 编排管线（CLI 解析 + 六层流水线）
+│   ├── db/               # Phase-0 存储层（SQLite + ORM）
+│   ├── filters/          # Filter 治理（高危/禁路径/网络/预算）
+│   ├── llm/              # 可选真实 LLM 二次研判（默认关闭）
+│   ├── sandbox/          # 沙箱运行时（local/container/cube + 透明回退）
+│   └── telemetry/        # OTel 埋点
+├── skills/               # SDK skill 定义（FsSkillRepository 按 base_dir 加载）
+│   └── code-review/
+│       ├── SKILL.md
+│       ├── rules/        # 6 类规则文件 (security/async/resource/tests/sensitive/db)
+│       └── scripts/      # 静态分析脚本（run_checks/dedupe/mask_secrets/parse_diff）
+├── tests/                # 8 个测试文件，175 用例
+├── examples/             # 生成的报告产物
+└── docs/                 # 各阶段概述文档
+```
+
+---
+
+## 1. 运行环境
+
+必须使用隔离 venv（原因见下），不要用系统 Python：
+
+```bash
+# 隔离 venv（Windows 示例路径）
+VENV="C:/Users/douzhenyu/.workbuddy/binaries/python/envs/cr_agent/Scripts/python.exe"
+
+cd E:/agent/trpc-agent-python/examples/skills_code_review_agent
+```
+
+**关键依赖约束**：
+
+- 必须安装 `python-magic-bin`（不是 `python-magic`）。Windows 上缺 `magic1.dll` 会导致 SDK `import code_executors` 直接 segfault。
+- SDK 存储为 async 优先，所有存储 / 沙箱调用都要 `await`。
+- **路径用真实文件系统路径**，别用 Git Bash 的 `/tmp`（aiosqlite 在 Windows 上认不出，会静默失败）。
+
+依赖清单（核心）：`SQLAlchemy` `aiosqlite` `pydantic` `opentelemetry-sdk` `tzlocal` `PyYAML` `jinja2` `python-magic-bin` `docker`（可选，容器运行时预留）。
+
+---
+
+## 2. CLI 参数
+
+| 参数 | 必填 | 说明 | 默认 |
+|------|------|------|------|
+| `--diff-file PATH` | 三选一（互斥） | 解析一个 unified diff 文件 | — |
+| `--repo-path PATH` | 三选一 | 在仓库里跑 `git diff HEAD`（暂存 + 未暂存） | — |
+| `--fixture NAME` | 三选一 | 内置样本：`clean` / `security` | — |
+| `--skill-dir PATH` | 否 | code-review skill 目录 | `skills/code-review` |
+| `--db-path PATH` | 否 | SQLite 库路径 | `cr_agent.db` |
+| `--mode dry-run\|real` | 否 | 执行模式 | `dry-run` |
+| `--dry-run` | 否 | `--mode dry-run` 快捷 flag | — |
+| `--output-dir DIR` | 否 | `review_report.json` + `.md` 输出目录 | `.` |
+| `--telemetry` | 否 | 开启 OTel，span 打到 stdout | 关 |
+| `--print-changeset` | 否 | 额外打印解析后的 ChangeSet JSON | 关 |
+| `--require-sandbox` | 否 | real 模式强制使用 SKILL.md 声明的 `default_runtime`（如 `container`）；若不可用直接报错，不静默回退 `local` | 关 |
+| `--enable-llm` | 否 | 开启真实 LLM 二次研判（也可用 `.env` 的 `LLM_ENABLED`） | 关 |
+| `--llm-env PATH` | 否 | 指定 `.env` 文件路径（默认项目根 `.env`） | — |
+
+输入三选一是 **required** 的——不传任何一个会直接报错。
+
+---
+
+## 3. 两种模式
+
+| | dry-run | real |
+|---|---|---|
+| 执行方式 | 进程内直接 `import run_checks` | 按 `default_runtime` 选后端（先试 `container`，不可用时透明回退 `local`）|
+| 安全边界 | 不生效（没进沙箱） | 超时 / 输出上限 / env 白名单 / 脱敏全生效 |
+| Filter 治理 | 生效（deny 仍拦截） | 生效 |
+| 是否需要 Key | 否 | 否 |
+| 用途 | CI 预览、快速验证、评测 | 生产评审（**独立容器沙箱**，更隔离、更安全） |
+
+> **独立沙箱（PRD 强制）**：`real` 模式 + `default_runtime: container` 时，检查脚本在**全新 docker 容器**内执行——`network_mode=none`（无网络）、不继承宿主机环境变量、每次评审起一个容器用完即毁。这正是 PRD §6.2 要求的生产隔离方案，已在本机（docker 已装）实证：整条链路在容器内跑通、`sandbox_run.runtime` 记录为 `container`、密钥脱敏生效。
+> 加 `--require-sandbox` 可在生产环境**强制**该契约：请求 `container` 但不可用就直接报错，不静默降级到 `local`（local 仅作 dry-run / 开发 fallback，PRD 明确"不能作为生产方案"）。
+
+> 评审核心为**确定性静态分析引擎**（规则 + AST），**默认不调用任何 LLM / 模型 API**，因此两条路径默认都不需要 API Key。
+> 所谓 “real” 仅表示 “在隔离沙箱里执行” vs “直接进程内执行”。
+> 如需真实模型二次研判，见 [§4.5 LLM 二次研判（可选）](#45-llm-二次研判可选)；未配置时自动降级为 no-op，链路不受影响。
+
+---
+
+## 4. 配置改在哪
+
+**沙箱安全边界** → `skills/code-review/SKILL.md` 的 `sandbox:` frontmatter：
+
+```yaml
+sandbox:
+  default_runtime: container   # real 模式优先用容器；docker 不可用自动回退 local
+  fallback: local
+  timeout_s: 30                 # 超时秒数，超了降级为空
+  max_output_bytes: 1048576     # 1MB 输出上限，超出截断
+  env_whitelist: [PATH, HOME, LANG]   # 只透传这些环境变量进沙箱
+```
+
+**检测规则** → `skills/code-review/rules/*.md`（6 类：security / async_errors / resource_leak / missing_tests / sensitive_info / db_lifecycle）。改规则直接改这些 md，无需动代码。
+
+**脱敏正则** → `skills/code-review/scripts/mask_secrets.py`（AWS / OpenAI / GitHub / password / 私钥 / 连接串 + 熵检测）。
+
+---
+
+## 4.5 LLM 二次研判（可选）
+
+在 dedupe 之后、落库之前，可用**真实 LLM** 对低置信度的 `needs_human_review` 档位做二次研判：
+
+- **real（确认）** → 更新置信度、给 `source` 打 `llm` 标、把模型解释追加进 `recommendation`，并按新置信度重新分桶（≥0.8 进 findings / ≥0.6 进 warnings）。
+- **false_positive（误报）** → 直接丢弃。
+- **调用失败 / 无 Key / 未启用** → 自动降级为 no-op，原 findings 原样落库。
+
+### 配置（`.env`）
+
+复制 `.env.example` 为 `.env`，按需填写：
+
+```bash
+LLM_ENABLED=true                 # 或 CLI --enable-llm 临时开启
+LLM_API_KEY=sk-...               # 留空 = 禁用真实模型
+LLM_BASE_URL=https://api.openai.com/v1   # 任意 OpenAI 兼容端点（Azure/本地vLLM/内部网关）
+LLM_MODEL=gpt-4o-mini
+LLM_TEMPERATURE=0.1
+LLM_MAX_TOKENS=1024
+LLM_TIMEOUT=30
+```
+
+- 任意 OpenAI 兼容端点都能用：OpenAI、Azure OpenAI、**DeepSeek**（`https://api.deepseek.com`，`LLM_MODEL=deepseek-chat`）、本地 vLLM、内部 LLM 网关，只改 `LLM_BASE_URL` / `LLM_API_KEY`。
+- **无 Key 时完全不调用模型**，解析 / 沙箱 / 落库链路（含 `--dry-run`）照常工作，所有测试可无 Key 跑通。
+- 喂给模型的 diff 会先经 `mask_secrets` 脱敏，密钥不会外泄。
+- **已实证**（DeepSeek `deepseek-chat`）：低置信度 `needs_human_review` 项（规则 SEC005 `verify=False`，置信度 0.5）被模型研判为 `real`、置信度 0.95 → 提级进 `findings` 桶、`source` 标 `rule+llm`、解释写入 `recommendation`；高/中置信度项不受影响。验证 fixture 为 `llm_probe`。
+- 真实网络路径有门控集成测试 `tests/test_phase7_llm_live.py`：`CR_LLM_LIVE=1` 且有 `LLM_API_KEY` 时才跑，避免污染无 Key 的 CI。
+
+### 启用方式
+
+```bash
+# 方式一：.env 里 LLM_ENABLED=true 后直接跑
+$VENV run_agent.py --diff-file ./my_change.diff --mode real --db-path ./cr.db
+
+# 方式二：CLI 临时开启（覆盖 .env）
+$VENV run_agent.py --fixture security --enable-llm --llm-env ./path/to/.env
+```
+
+---
+
+## 5. 真实环境用法
+
+```bash
+# (A) 本地 diff 文件 → 生产沙箱模式，报告输出到 ./reports
+$VENV run_agent.py \
+  --diff-file ./my_change.diff \
+  --mode real \
+  --output-dir ./reports \
+  --db-path ./cr_prod.db
+
+# (B) 审一个 Git 仓库的未提交改动（CI 门禁，dry-run 够用）
+$VENV run_agent.py \
+  --repo-path /path/to/repo \
+  --dry-run \
+  --telemetry \
+  --db-path ./cr_ci.db
+
+# (C) 评测 / 演示用内置样本
+$VENV run_agent.py --fixture security --dry-run --output-dir ./out
+```
+
+跑完会生成：
+
+- `./reports/review_report.json` — 八段式结构化报告（机器可读）
+- `./reports/review_report.md` — 八段式报告（人读）
+- `cr_prod.db` 里写入 `review_task` / `input_diff` / `finding` / `sandbox_run` / `filter_block` / `monitor_summary` / `review_report`
+
+### 按 task_id 查询完整记录
+
+```python
+import sqlite3
+c = sqlite3.connect("cr_prod.db"); c.row_factory = sqlite3.Row
+t = c.execute("SELECT * FROM review_task WHERE id=?", (task_id,)).fetchone()
+findings = c.execute("SELECT * FROM finding WHERE task_id=?", (task_id,)).fetchall()
+# ... sandbox_run / filter_block / monitor_summary / review_report 同理
+```
+
+---
+
+## 6. 示例产物
+
+- [`examples/review_report.json`](./examples/review_report.json) — 一份真实的八段式报告样例（fixture=security 跑出）。
+
+---
+
+## 7. 已知边界
+
+- **容器隔离（独立沙箱，已实证）**：`ContainerRuntime` 是 SDK `ContainerClient` 的真实适配（docker 进程隔离，`network_mode=none`、不继承宿主机 env），`CubeRuntime` 是远程 Cube/E2B 的真实适配；两者在 docker/cube 不可用时抛 `RuntimeUnavailable`，由 agent 透明回退到 `LocalRuntime`（或 `--require-sandbox` 下直接报错）。`sandbox_run.runtime` 记录实际落地的后端（`local`/`container`/`cube`）。
+  - 本机 docker 已装，已端到端实证：整条 real 链路在容器内跑通、检出 + 脱敏生效、`runtime=container` 正确落库（见 `tests/test_phase3_container_sandbox.py`，docker 不可用时自动 skip）。
+  - 绕开 SDK `ContainerClient` 的 stdin 执行路径 bug（其 `_exec_run_with_stdin` 有 `self.container.container.id` 笔误 + 关闭 socket 后复用连接池报错）；本 runtime 改用 base64 把脚本与输入写进容器文件、再以容器内 `python x.py < _input.json` 重定向执行，全程走稳健的 no-stdin `exec_run` 分支。SDK 该笔误已就地修复（`trpc_agent_sdk/code_executors/container/_container_cli.py`）。
+- **并发**：多任务建议每条评审一个 `task_id`；不要多个进程写同一个 `.db` 文件。
+- **Windows 路径**：所有 `--db-path` / `--output-dir` / `--diff-file` 用正斜杠或盘符绝对路径。
+
+---
+
+## 8. 测试
+
+```bash
+# 全量回归（8 个阶段 + LLM + 容器沙箱）
+for p in phase0_foundation phase1_input_skill phase2_rules_engine \
+         phase3_sandbox_filter phase3_container_sandbox telemetry \
+         phase4_dedupe phase5_orchestration phase7_llm cr_agent; do
+  $VENV examples/skills_code_review_agent/tests/test_${p}.py
+done
+```
+
+当前累计 **178 用例 / 0 失败**（含 docker 门控的容器独立沙箱测试；无 docker 时该测试自动 skip）。

examples/skills_code_review_agent/agent/__init__.py

@@ -0,0 +1,27 @@
+"""Code Review Agent package.
+
+Thin re-export surface so callers can do::
+
+    import agent
+    await agent._async_main(ns)   # or agent.main(...)
+
+without reaching into ``agent.agent`` directly. The heavy lifting lives in
+``agent.agent`` (orchestration), with ``db/``, ``filters/``, ``llm/``,
+``sandbox/`` and ``telemetry/`` as sub-packages.
+"""
+
+from .agent import main
+from .agent import _async_main
+from .agent import skill_load
+from .agent import load_diff
+from .agent import persist_changeset
+from .agent import FIXTURES
+
+__all__ = [
+    "main",
+    "_async_main",
+    "skill_load",
+    "load_diff",
+    "persist_changeset",
+    "FIXTURES",
+]