edward-guard — AI 编程 Agent 外部控制平面：跨轮状态引擎 + 确定性规则 + 语义评分 + 签名审计

技能简介

edward（包名 edward-guard）是给无人值守 AI 编程 Agent 的外部监督层。CI 任务、夜间批跑、定时作业里的 Agent 经常悄悄失败 —— 同一个坏测试重试 40 遍、3 点钟烧掉 8 美元 token 没人按停、对错误目录执行 rm -rf、写到本不该碰的文件。Edward 坐在 Agent 与 runtime 之间，监听事件流、跨轮次构建 agent 实际在做什么的画面，在画面失真时介入 —— PAUSE（可恢复） / CANCEL / BLOCK —— 每个决策都附签名收据供审计。在 StepShield（NeurIPS 2026，9,429 轨迹 / 216 held-out）上，Edward 规则层结合 local 4B 评分模型可达 100% 检测 budget bleed / infinite loop / convergence stall，EIR₃ 时序指标 0.78，决策成本仅 $0.00002 / 次。

核心能力

• 跨轮状态引擎：维护滑动窗口的 tool call 列表、文件修改记录、经过时间，识别只在轨迹整体形状中显现的失败模式
• 三种介入动作：PAUSE（human-resumable，可挂起 / 恢复）、CANCEL（终止 + 收据）、BLOCK（拒绝执行危险操作）
• 确定性规则层：白名单 / 黑名单 / 路径正则 / 命令前缀 / 退出码阈值，零延迟
• 本地语义评分：4B 模型（on your GPU）或云端 Jev 1.13（TypeSafe），单 batched call 评估当前轨迹是否仍在合理目标内
• 签名收据：每次介入都附 ECDSA 签名，含时间戳 / 触发规则 / 状态快照，用于事后审计
• 四种典型失败场景：budget bleed（token 持续燃烧）、infinite loop（同 tool call 重复）、convergence stall（无进展卡死）、dangerous command（rm -rf / 写敏感路径）
• 人可恢复干预：PAUSE 不会丢失上下文，运维人员审核后 RESUME 即可继续
• 零运行时依赖：仅 Python 标准库，可离线部署

安装配置

# 基础安装
pip install edward-guard

# 本地 4B 评分模型（推荐，可选）
pip install edward-guard[local-judge]

# 云端 Jev 评分（可选，需 API key）
pip install edward-guard[cloud-judge]

环境变量：EDWARD_RULES_PATH（YAML / JSON 规则文件路径）、EDWARD_JUDGE（local / cloud / none）、EDWARD_AUDIT_LOG（签名收据输出路径）、EDWARD_VERBOSITY（silent / info / debug）。Python 3.11+。

使用步骤

1. 编写规则文件 edward-rules.yaml，定义白名单 / 黑名单 / 路径正则 / token 预算阈值
2. 在 Agent 启动脚本中用 edward.wrap(agent_callable) 包裹 agent 主循环
3. 启动 agent，Edward 在后台监听事件流
4. 触发介入时 Edward 打印结构化日志（含签名收据）并按规则动作
5. 用 edward audit 命令回放签名收据，验证每个决策的触发原因
6. 用 edward replay 重放历史轨迹对比不同规则集的检出率

适用场景

• CI 中的 AI Agent：PR 检查、自动化重构、长跑测试，避免 token 失控
• 夜间批跑作业：定时生成的代码 / 文档 / 报告，需要异常时挂起而不是烧光预算
• 多 Agent 协同：监督多个 agent 同时跑，避免互相干扰或资源争抢
• 金融 / 医疗高风险领域：任何写操作前必须经过规则层 + 语义层双重验证
• A/B 测试不同评分模型：在同一轨迹上对比 local 4B vs Jev vs 不评分
• StepShield 基准评估：在 9,429 轨迹上验证规则 + 评分组合的 EIR₃ 时序指标

适用人群

• DevOps / Platform 工程师：在 CI / CD 中部署 AI Agent 需安全护栏
• AI Agent 框架开发者：为自己的 runtime 加上跨轮监督能力
• 安全 / 合规团队：审计 AI Agent 的每个写操作 / 危险命令
• 独立开发者：跑夜间任务时不想半夜被 token 账单惊醒
• 研究员：在 StepShield 等基准上对比不同时序检测算法

工作原理

Edward 的核心是跨轮状态引擎：维护滑动窗口的工具调用列表、文件修改哈希集合、token 累计消耗、时间戳等。每收到一个新事件，先走确定性规则层（白名单 / 黑名单 / 阈值），命中即直接介入；未命中则交给语义评分模型（local 4B 或云端 Jev），由其评估当前轨迹是否仍在合理目标内。语义层输出 proceed / pause / block 三态之一，Edward 据此执行 PAUSE / CANCEL / BLOCK。规则层单独存在时只能检出 7.4% 的违规（漏掉 silent corruption）；加上 local 4B 后 recall 达 58.3%，EIR₃ 0.78（vs GPT-4.1-mini judge 0.89）；换 Jev 1.13 后 EIR₃ 提升至 0.91 但 FPR 也升到 10.2%。每个介入都生成签名收据 {timestamp, rule_id, state_hash, signature} 写入审计日志，可用 edward audit 回放。

官方链接

• PyPI：https://pypi.org/project/edward-guard/
• GitHub：https://github.com/VeridicalTech/Edward
• Benchmark 文档：https://github.com/VeridicalTech/Edward/blob/main/BENCHMARK.md
• StepShield 基准：https://github.com/glo26/stepshield（NeurIPS 2026，9,429 轨迹）
• Changelog：https://github.com/VeridicalTech/Edward/blob/main/CHANGELOG.md
• License：MIT