feat(examples): add sandboxed code review agent

[Wsp030914]

这次做了什么

这个 PR 新增一个基于 Skill 的代码审查 Agent 示例，支持统一 diff、文件列表、Git 工作区和内置 fixture 输入，并生成可查询的 JSON / Markdown 报告和 SQLite 审计记录。

示例包含确定性规则扫描、finding 去重、secret 脱敏、policy-gated sandbox 执行、fake-model、dry-run、8 个验收 fixture，以及覆盖输入解析、策略、沙箱、持久化和报告的测试。

Fixes #92

整体流程

flowchart LR
    A[Diff / File List / Git / Fixture 输入] --> B[输入解析与归一化]
    B --> C[Skill 规则扫描]
    C --> D[Finding 去重 / 分组 / 脱敏]
    D --> E[Policy Filter 审计执行计划]
    E --> F{Decision}
    F -->|allow| G[Container Sandbox 执行]
    F -->|deny / review| H[跳过执行并记录原因]
    G --> I[SQLite 审计持久化]
    H --> I
    I --> J[JSON / Markdown 报告]

Loading

为什么这样设计

这个示例的目标不是只演示一次模型 review，而是把代码审查拆成可以测试和审计的步骤：

• 输入必须先被解析成明确的 review 范围；
• 确定性规则先产出结构化 finding，减少对模型自由文本的依赖；
• sandbox 执行前必须经过 policy filter；
• denied 或需要人工复核的执行不会静默运行；
• 所有关键证据写入 SQLite，报告可以后续查询；
• secret 会在写入报告或数据库前脱敏。

输入与执行模式

支持四类输入：

• unified diff；
• UTF-8 file list；
• Git staged / worktree / revision range；
• 8 个内置 fixture。

默认 runtime 是 Container，Docker network_mode=none，只 staged 固定 Skill 文件和归一化后的 review 输入。Local runtime 仅作为开发 fallback，必须显式设置 TRPC_CODE_REVIEW_ALLOW_UNSAFE_LOCAL=1 才能使用。

fake-model 和 dry-run 模式都不需要模型 API Key，适合本地测试和 CI 验收。真实模型路径复用同一套 Skill、Filter、sandbox、storage 和 report 契约，模型凭据不会进入 sandbox 环境。

持久化与报告

SQLite 保存 task、Filter decision、sandbox run、finding 和 report 记录。show 命令可以按 task id 查询一次审查的持久化结果。

报告包含：

• findings 和需要人工复核的 warning；
• Filter 决策；
• sandbox 摘要和异常；
• metrics；
• 最终 conclusion。

验证范围

测试覆盖：

• fixture 验收；
• CLI 和输入解析；
• policy 与 sandbox 行为；
• report 生成；
• SQLite storage；
• fake-model / dry-run 路径；
• optional real Container integration。

建议重点 Review

希望维护者重点关注：

• 输入解析是否会扩大审查范围；
• Filter 是否严格早于 sandbox 执行；
• Container 与 Local runtime 的安全边界是否描述清楚；
• finding 去重、confidence routing 和脱敏是否合理；
• SQLite 聚合记录是否足够审计一次 review；
• 示例是否保持“不修改生产 API”的边界。

Release Notes

新增一个带 policy-gated sandbox、SQLite 审计和结构化报告的 Skills-based 代码审查 Agent 示例。

[helloopenworld]

AI Code Review

发现的问题

🚨 Critical

未发现 Critical 问题。

⚠️ Warning

• examples/skills_code_review_agent/agent/sandbox.py:316-338：成功路径下输出先截断再脱敏，可能突破字节上限

  • _normalize_result 中先用 _bounded_outputs 按 output_limit_bytes 截断 stdout/stderr/output，随后再 redact_text；而 _failure（sandbox.py:366）的顺序是先脱敏再截断。脱敏会把 ≥8 字符的密钥替换为 [REDACTED]/Bearer [REDACTED]（更长），导致最终持久化与上报的 stdout/stderr 略超 output_limit_bytes，破坏“bounded output”契约且无测试覆盖。建议统一为“先脱敏、后截断”或在脱敏后再做一次截断。

• tests/examples/skills_code_review_agent/test_acceptance.py:197-217：test_python_source_meets_static_limits 把 scan_rules.py 等技能脚本纳入 AST 复杂度/行数检查

  • 该静态限制测试遍历 EXAMPLE_ROOT.rglob("*.py")，其中包含 skills/code-review/scripts/scan_rules.py（442 行、含大型 RULES 元组）。若后续向扫描器追加规则使函数体增长，会直接阻塞 CI（MAX_FUNCTION_LINES/MAX_FUNCTION_STATEMENTS），把扫描器内部演进与示例源码风格约束耦合在一起。建议将技能脚本排除在静态限制范围外，或单独放宽其阈值。

💡 Suggestion

• examples/skills_code_review_agent/agent/sandbox.py:267-274：_within_budget 在 remaining <= 0 时手动 operation.close() 再抛 TimeoutError，依赖协程对象有 close 方法；可统一通过 asyncio.wait_for（对 remaining<=0 直接抛错）处理，减少分支、避免对底层 awaitable 形态的隐式假设。

总结

整体安全模型（固定 argv、摘要校验、路径白名单、网络隔离、fail-closed 过滤、脱敏）设计完整且测试覆盖较充分。未发现必须修复的阻塞问题；主要风险是成功路径下“截断后脱敏”可能使输出轻微超出声明上限，以及静态限制测试把技能脚本纳入 CI 门槛，建议修复。

测试建议

• 建议补一条成功路径测试：构造含真实密钥形态的 sandbox stdout，断言 _normalize_result 产出的 stdout+stderr+output 字节数 ≤ output_limit_bytes，覆盖“先截断后脱敏”的边界。

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
⚠️ Please upload report for BASE (main@6a2f7f9). Learn more about missing BASE report.

Additional details and impacted files

@@            Coverage Diff             @@
##             main        #243   +/-   ##
==========================================
  Coverage        ?   87.93985%           
==========================================
  Files           ?         482           
  Lines           ?       45157           
  Branches        ?           0           
==========================================
  Hits            ?       39711           
  Misses          ?        5446           
  Partials        ?           0           

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

[Wsp030914]

@codex review