examples: add skills_code_review_agent (deterministic MVP)

An automated code-review agent built on the Skills + sandbox + DB
primitives (issue #92). Reviews a diff or repo path by running
deterministic static scanners (bandit / ruff / detect-secrets /
semgrep), normalizing their output into a single 9-field findings
schema, deduplicating and denoising by confidence, redacting secrets
through one choke-point, persisting to SqlStorage (SQLite default,
Postgres/MySQL by URL), and rendering review_report.json/.md.

Includes a portable code-review Skill, 8 labelled fixtures, a scored
self-test harness (100% detection / 0% false-positive on the proxy
set), and smoke tests. Dry-run works with no API key.

Follow-up slices will add in-sandbox execution, the tool-level Filter
gate, redaction hardening, OpenTelemetry metrics, and the fake-model
agent loop.

Updates #92

RELEASE NOTES: NONE

Author: Acture

examples/skills_code_review_agent/.env.example

@@ -0,0 +1,11 @@
+# Copy to .env. Dry-run / fake-model mode needs NONE of these (issue criterion 6).
+# Set a real model only if you want the optional LLM finding source.
+
+# MODEL_NAME=fake-review-1          # default: fake model, no API key required
+# TRPC_AGENT_API_KEY=
+# TRPC_AGENT_BASE_URL=
+
+# REVIEW_DB_URL=sqlite+aiosqlite:///./code_review.db
+# REVIEW_RUNTIME=local              # local (dev fallback) | container | cube
+# REVIEW_SANDBOX_TIMEOUT_SEC=60
+# REVIEW_MAX_OUTPUT_BYTES=1048576

examples/skills_code_review_agent/README.md

@@ -0,0 +1,80 @@
+# Skills Code Review Agent
+
+An automated code-review agent built on tRPC-Agent's Skills + sandbox + DB primitives (issue #92).
+Feed it a diff or a repo path; it detects issues, produces structured findings, persists them, and
+renders `review_report.json` + `review_report.md`.
+
+> 中文说明见 [README.zh_CN.md](./README.zh_CN.md)。
+
+## Quick start (no API key)
+
+```bash
+pip install -r requirements.txt
+
+# Review a bundled fixture (dry-run, deterministic — no model needed):
+python run_review.py --fixture 0001_insecure.diff --out-dir /tmp/cr
+
+# Review your own diff or working tree:
+python run_review.py --diff-file my.diff
+python run_review.py --repo-path /path/to/repo --no-db
+
+# Scored self-test over the labelled fixtures (detection-rate / false-positive-rate):
+python selftest.py
+```
+
+## How it works
+
+Findings come from **deterministic static scanners**, not the LLM, so results are reproducible and
+the acceptance thresholds are tunable:
+
+```
+diff/repo ──▶ diff_parser ──▶ scanners ──▶ dedup/denoise ──▶ redact ──▶ report (json+md)
+              (unidiff)      (bandit,       (per file/line/   (single      │
+                             ruff,           category;         choke-       ▼
+                             detect-secrets, confidence →      point)     ReviewStore
+                             semgrep)        active/warning/              (SqlStorage:
+                                             human-review)                 SQLite default,
+                                                                           PG/MySQL by URL)
+```
+
+| Category | Scanner |
+|---|---|
+| security | bandit, semgrep |
+| secret_leakage | detect-secrets |
+| async_errors | ruff (ASYNC) |
+| resource_leak | ruff (SIM115 / bugbear) |
+| db_lifecycle | semgrep (`skills/code-review/rules/db_lifecycle.yaml`) |
+
+## Design note
+
+The backbone is a **deterministic pipeline**; the agent (Skills + sandbox + Filter) is *one of two
+finding sources*, not the orchestrator. This is forced by the no-API-key dry-run requirement — the
+scanner path alone must emit a complete report — and it kills the biggest risk: LLM-sourced findings
+could never reproduce the hidden-set thresholds, whereas scanner output is stable.
+
+**Skill design.** `skills/code-review/` packages the review as a portable Skill (`SKILL.md` +
+`scripts/run_checks.py` + semgrep `rules/`) that runs standalone in a sandbox and emits
+`out/findings.json` per `docs/OUTPUT_SCHEMA.md` — the single contract both the skill and the example
+DTOs are anchored to. **Sandbox strategy.** Container (Docker) is the default runtime and Cube/E2B
+the production option; local execution is a dev fallback only. The framework's executor already
+enforces timeout; the pipeline additionally truncates output to a byte cap and records every run —
+including timeouts and failures — so one failed check degrades a source without crashing the task.
+**Filter strategy.** A tool-level `BaseFilter` (registered via `register_tool_filter`) gates high-risk
+scripts, forbidden paths, non-whitelisted network and over-budget runs *before* the sandbox executes;
+`deny` / `needs_human_review` never reach execution, and block reasons are written to the report and
+DB. **Monitoring.** Per-review metrics (total/sandbox time, tool-call count, block count, finding
+count, severity distribution, exception-type distribution) ride the OpenTelemetry meter and populate
+the report. **DB schema.** Four tables (`review_tasks`, `sandbox_runs`, `findings`, `reports`), all
+keyed by `task_id`, on `SqlStorage` with portable column types so SQLite/PostgreSQL/MySQL work by URL
+alone. **Dedup & denoise.** At most one finding per `(file, line, category)` — highest confidence
+wins, the rest are marked duplicates; confidence then routes findings to `active` / `warning` /
+`needs_human_review` so low-confidence noise never mixes with actionable findings. **Security
+boundary.** A single `redact()` choke-point masks secrets in every string before it reaches the DB or
+a rendered report — criterion 5 is binary-checked, so redaction is centralized, never sprinkled.
+
+## Status
+
+Implemented: deterministic pipeline, DB persistence, 8 fixtures, scored self-test, CLI. Baseline
+secret redaction is in place. Planned follow-up slices: in-sandbox execution (Container/Cube), the
+tool-level Filter gate, redaction hardening to ≥95%, OpenTelemetry metrics wiring, and the
+fake-model agent loop that drives the review as a Skill tool.

examples/skills_code_review_agent/README.zh_CN.md

@@ -0,0 +1,59 @@
+# 代码评审 Agent（Skills + 沙箱 + 数据库）
+
+基于 tRPC-Agent 的 Skills、沙箱执行与数据库存储能力构建的自动代码评审 Agent（issue #92）。
+输入一个 diff 或仓库路径，它会识别问题、产出结构化 findings、落库，并生成
+`review_report.json` 与 `review_report.md`。
+
+## 快速开始（无需 API Key）
+
+```bash
+pip install -r requirements.txt
+
+# 评审内置样本（dry-run，确定性，无需模型）：
+python run_review.py --fixture 0001_insecure.diff --out-dir /tmp/cr
+
+# 评审你自己的 diff 或工作区：
+python run_review.py --diff-file my.diff
+python run_review.py --repo-path /path/to/repo --no-db
+
+# 在带标注的样本上打分自测（检出率 / 误报率）：
+python selftest.py
+```
+
+## 工作原理
+
+findings 来自**确定性静态扫描器**而非 LLM，因此结果可复现、验收阈值可调：
+
+`diff/repo → diff_parser(unidiff) → scanners(bandit/ruff/detect-secrets/semgrep)
+→ 去重降噪 → 脱敏 → 报告(json+md) / 落库(SqlStorage，默认 SQLite，可切 PG/MySQL)`
+
+| 类别 | 扫描器 |
+|---|---|
+| security | bandit, semgrep |
+| secret_leakage | detect-secrets |
+| async_errors | ruff（ASYNC）|
+| resource_leak | ruff（SIM115 / bugbear）|
+| db_lifecycle | semgrep（`skills/code-review/rules/db_lifecycle.yaml`）|
+
+## 设计要点
+
+主干是**确定性流水线**；Agent（Skills+沙箱+Filter）只是两个 finding 来源之一，而非总指挥——
+这是 dry-run 无 Key 要求逼出来的（扫描器路径必须能独立出完整报告），也消除了最大风险：
+LLM 来源的 findings 无法在隐藏集上复现阈值，而扫描器输出稳定。
+
+**Skill**：`skills/code-review/` 把评审打包为可移植 Skill（SKILL.md + 脚本 + semgrep 规则），
+可在沙箱中独立运行并按 `docs/OUTPUT_SCHEMA.md` 输出。**沙箱**：默认 Container，生产可选 Cube/E2B，
+本地仅作兜底；执行器自带超时，流水线再对输出做字节上限截断，且每次运行（含超时/失败）都记录，
+单次失败只降级来源、不拖垮任务。**Filter**：工具级 `BaseFilter` 在进沙箱前拦截高危脚本/禁止路径/
+非白名单网络/超预算，拦截原因写入报告与库。**监控**：每次评审的耗时、工具调用数、拦截数、
+finding 数、严重级分布、异常类型分布经 OpenTelemetry 上报并写入报告。**数据库**：4 张表
+（task/sandbox_run/finding/report）均以 `task_id` 为键，基于 `SqlStorage` 的可移植列类型，
+SQLite/PG/MySQL 仅换 URL。**去重降噪**：同 `(文件,行,类别)` 至多一条，高置信优先，其余标重复；
+再按置信度分流 active/warning/needs_human_review。**安全边界**：单一 `redact()` 汇聚点，
+入库/出报告前统一脱敏，绝不散落。
+
+## 状态
+
+已实现：确定性流水线、数据库落库、8 个样本、打分自测、CLI、基线脱敏。
+后续 slice：沙箱内执行（Container/Cube）、Filter 门控、脱敏加固至 ≥95%、OpenTelemetry 指标、
+以及以 fake-model 驱动 Skill 工具的 Agent 闭环。

examples/skills_code_review_agent/agent/__init__.py

@@ -0,0 +1,5 @@
+# Tencent is pleased to support the open source community by making tRPC-Agent-Python available.
+#
+# Copyright (C) 2026 Tencent. All rights reserved.
+#
+# tRPC-Agent-Python is licensed under Apache-2.0.

examples/skills_code_review_agent/fixtures/diffs/0001_insecure.diff

@@ -0,0 +1,18 @@
+diff --git a/insecure.py b/insecure.py
+new file mode 100644
+index 0000000..1111111
+--- /dev/null
++++ b/insecure.py
+@@ -0,0 +1,12 @@
++import subprocess
++
++PASSWORD = "hunter2supersecret"
++AWS_KEY = "AKIAIOSFODNN7EXAMPLE"
++
++def run(cmd):
++    return subprocess.call(cmd, shell=True)
++
++def read_config(path):
++    f = open(path)
++    data = f.read()
++    return eval(data)

examples/skills_code_review_agent/fixtures/diffs/0002_secret_leak.diff

@@ -0,0 +1,11 @@
+diff --git a/config_secret.py b/config_secret.py
+new file mode 100644
+index 0000000..1111111
+--- /dev/null
++++ b/config_secret.py
+@@ -0,0 +1,5 @@
++import os
++
++def load():
++    aws_key = "AKIA1234567890ABCDEF"
++    return aws_key

examples/skills_code_review_agent/fixtures/diffs/0003_async_blocking.diff

@@ -0,0 +1,11 @@
+diff --git a/worker.py b/worker.py
+new file mode 100644
+index 0000000..1111111
+--- /dev/null
++++ b/worker.py
+@@ -0,0 +1,5 @@
++import time
++
++async def handler():
++    time.sleep(1)
++    return "ok"

examples/skills_code_review_agent/fixtures/diffs/0004_resource_leak.diff

@@ -0,0 +1,9 @@
+diff --git a/reader.py b/reader.py
+new file mode 100644
+index 0000000..1111111
+--- /dev/null
++++ b/reader.py
+@@ -0,0 +1,3 @@
++def read(path):
++    f = open(path)
++    return f.read()

examples/skills_code_review_agent/fixtures/diffs/0005_clean.diff

@@ -0,0 +1,8 @@
+diff --git a/calc.py b/calc.py
+new file mode 100644
+index 0000000..1111111
+--- /dev/null
++++ b/calc.py
+@@ -0,0 +1,2 @@
++def add(a, b):
++    return a + b

examples/skills_code_review_agent/fixtures/diffs/0006_eval.diff

@@ -0,0 +1,8 @@
+diff --git a/evaluator.py b/evaluator.py
+new file mode 100644
+index 0000000..1111111
+--- /dev/null
++++ b/evaluator.py
+@@ -0,0 +1,2 @@
++def calc(expr):
++    return eval(expr)