Agent Governance Hub

面向 Coding Agent 的运行时治理中枢。

这个项目给现有 Agent 系统补一层 Runtime Governance。它显式跟踪假设、证据、义务、风险、进度和失败路线，让系统在运行过程中知道：

• 什么时候该验证
• 什么时候该修正路线
• 什么时候该向人确认
• 什么信息必须跨 compact 和 resume 保留下来

为什么值得做

长链路 Coding Agent 任务里，真正难控的部分往往在过程状态：

• obligation 会丢
• 早期假设会污染后续步骤
• 已失败路线会被重复尝试
• compact 后关键结论会丢
• 风险动作可能在证据不足时被执行

这个仓库聚焦的是过程治理、状态恢复和可评测性。

项目定位

这个仓库关注长链路任务中的错误控制、状态持久化和路线修正。它在系统里承担的角色是：

• 它是控制面，不是执行面
• 它是治理层，不是答案生成器
• 它服务于已有 scaffold，而不是替代已有 scaffold

当前能力

• 运行时状态对象
  • Fact、Evidence、Hypothesis、Commitment、Risk、Progress、FailedRoute、GovernanceSnapshot
• 规则系统
  • 风险评估、义务满足、失败路线记忆、纠偏触发、最终审计
• 存储与恢复
  • jsonl ledger、json snapshot、事件回放
• 插件接入骨架
  • Claude Code 风格 hook
• 评测资产
  • micro-eval
  • Terminal-Bench 接入脚本
  • SWE-bench Lite 小切片

当前仓库里有什么

• core/
  • 中立治理核心，包括 schema、rulebook、risk、ledger、snapshot、replay
• plugin/
  • Claude Code 风格 hook 骨架
• adapters/
  • Codex、DyAgent 等运行时的适配说明
• docs/
  • 架构、技术方案、评测策略、Ark 接入说明
• benchmarks/
  • Terminal-Bench 与 SWE-bench 的接入说明和运行资产
• evals/
  • micro-eval、公开 benchmark overlay
• tests/
  • 核心逻辑、评测脚本、插件契约测试

快速开始

1. 创建评测环境

bash scripts/bench/setup_bench_env.sh
source .venv/bin/activate

2. 验证本地环境

python scripts/bench/ark_smoke_test.py
python -m unittest discover -s tests -v
python -m evals.micro.runner

3. 查看 Benchmark 命令

python scripts/bench/run_terminal_bench.py
python scripts/bench/run_tb_comparison.py --task-id hello-world

核心对象

治理层只跟踪一小组高价值状态：

• Fact
  • 来自工具、文件、日志、用户输入的可追溯事实
• Evidence
  • 对假设的支持或反驳
• Hypothesis
  • 可证伪的运行中假设
• Commitment
  • 后续必须交代的义务
• Risk
  • 当前执行风险和建议动作
• Progress
  • 是否真的获得了新信息
• FailedRoute
  • 不应再重复尝试的失败路线
• GovernanceSnapshot
  • compact-safe 的薄摘要

架构

系统分成三层：

1. Knowledge Plane 文档、spec、skills、流程知识。
2. Execution Plane 读文件、改代码、跑命令、看日志、与用户交互。
3. Runtime Governance Hub 观察事件、更新过程状态、决定 continue / verify / revise / ask / stop。

详细方案见：

• 架构文档
• 技术方案

评测策略

这个项目不是只看“最后任务有没有做对”，还要看“过程控制有没有变好”。

当前评测分三层：

• micro-eval
  • 仓库内快速验证治理规则
• Terminal-Bench
  • 主公开 benchmark，验证运行时治理是否改善真实 terminal agent 行为
• SWE-bench Lite / Verified
  • 次公开 benchmark，只做外部可比性补充

具体怎么跑见：

• 评测运行手册
• Benchmark 策略

Ark 与模型

当前仓库已经准备好了 Volcengine Ark 接入。模型与 endpoint 通过 .env.ark 配置：

• ARK_API_KEY
• ARK_BASE_URL
• ARK_MODEL

说明见：

• Ark 接入说明

当前状态

当前状态不是“只有空文档”，而是：

• 核心规则系统已实现
• replay / overlay / micro-eval 已实现
• Ark 已实测连通
• Terminal-Bench CLI 已安装
• SWE-bench Lite 32 题切片已生成
• 单元测试当前全通过

仓库导航

• 技术方案
• 评测运行手册
• Ark 接入说明
• Benchmark 总览
• 项目工作约定
• 贡献指南

下一步重点

• 继续把 Terminal-Bench 真正跑起来并沉淀 baseline / treatment 结果
• 把 governance overlay 挂到公开 benchmark 轨迹上
• 增强 typed event / decision / provenance / replay
• 增强多 agent 治理和可视化观测