Agent Hypervisor 版本演进实战解析执行环、Saga 补偿与命令拒绝清单三大里程碑agent-governance-toolkit【免费下载链接】agent-governance-toolkitAI Agent Governance Toolkit — Policy enforcement, zero-trust identity, execution sandboxing, and reliability engineering for autonomous AI agents. Covers 10/10 OWASP Agentic Top 10.项目地址: https://gitcode.com/GitHub_Trending/ag/agent-governance-toolkitAgent Hypervisor 是 agent-governance-toolkit 仓库中的AI Agent 运行时监督器它用执行环Execution Rings、会话隔离、Saga 补偿、抗篡改审计与 Kill Switch 等机制为共享会话中的多 Agent 提供运行时治理。本文以 agent-hypervisor 的 CHANGELOG 为主体逐版本拆解 1.0.0、2.0.0、2.1.0 三个里程碑的全部变更条目并对照当前仓库源码rings/enforcer.py、sandbox/init.py、pyproject.toml 等验证每条变更的实际落地形态帮助读者建立对该包版本演进的完整认知并掌握其中关键机制尤其是 2.1.0 的命令拒绝清单的源码级实现细节。一、先读版本地图CHANGELOG 记录的三个里程碑CHANGELOG.md 共记录了三次重要发布全部变更条目如下表所示这是本文的骨架后续章节逐条展开版本日期变更主题1.0.02026-02-20核心运行时核心编排器、共享会话对象SSO、4 执行环、连带责任引擎、Saga 编排器、审计轨迹、可逆性注册表、事务历史验证器、三类集成适配器2.0.02026-02-20六大维度深化可观测性事件总线、因果 Trace、执行环增强动态提权、环继承、越权检测、责任体系故障归因、隔离管理器、责任账本、Saga 增强并行扇出、检查点、声明式 DSL、会话增强版本计数器、资源锁、隔离级别、安全限速器、Kill Switch2.1.02026-06-15命令拒绝清单强制RingEnforcer.check_command()、CommandCheckResult数据结构、21 个新边界测试需要特别注意的一个事实CHANGELOG 的最后一条记录停留在 2.1.02026-06-15而当前源码已声明版本5.0.0见 src/hypervisor/init.py 中的__version__ 5.0.0与 pyproject.toml。这说明该包在 2.1.0 之后经历了进一步的包整合且 CHANGELOG 未随后续大版本持续追加条目——这也是理解该包当前定位的关键背景详见第五节。二、1.0.0核心运行时地基2026-02-201.0.0 是 Agent Hypervisor 从 Agent OS 中抽离为独立包的起始版本。CHANGELOG 列出的完整能力清单如下核心 Hypervisor 编排器负责会话生命周期管理共享会话对象SSO, Shared Session Object带 VFS虚拟文件系统、快照与一致性模式4 级执行环模型Ring 0 Root → Ring 3 Sandbox基于eff_score信任分自动分配连带责任引擎Joint Liability Engine含担保sponsorship、保证金bonding与比例化惩罚proportional penaltySaga 编排器带步骤超时、重试与逆序补偿审计留痕Audit-Logged Trail含 delta 捕获、承诺引擎commitment engine与临时数据 GC可逆性注册表Reversibility Registry维护 execute/undo API 映射与 4 级可逆性级别事务历史验证器Transaction History Verifier基于 DID 的信任验证集成适配器Protocol-based零硬依赖Nexus 适配器 —— 信任分解析与缓存Verification 适配器 —— 行为漂移检测与严重度阈值IATP 适配器 —— 能力清单capability manifest解析与信任提示184 个测试单元、集成与场景测试性能基准全流水线 268μs交互式 Demoexamples/demo.py展示全部 5 个子系统。从当前源码结构看这些能力大多仍能在仓库中找到对应模块src/hypervisor/core.pyHypervisor顶层编排器、session/sso.pySharedSessionObject/SessionVFS、audit/delta.pyDeltaEngine、reversibility/registry.py、verification/history.py以及 integrations/ 下的nexus_adapter.py、verification_adapter.py、iatp_adapter.py三个适配器文件。这些模块均被 src/hypervisor/init.py 的__all__导出如Hypervisor、SharedSessionObject、ReversibilityRegistry、TransactionHistoryVerifier。2.1 一次典型会话的调用流程1.0 地基之上下面这段快速上手代码继承自包 README 的 Quick Startpip install agent-governance-toolkit-core安装完整走了一遍 1.0.0 奠定的核心路径创建会话 → 按信任分入环 → 执行受治理的 Saga → 终止会话并返回审计根哈希from hypervisor import Hypervisor, SessionConfig, ConsistencyMode hv Hypervisor() # 创建带治理的隔离会话 session hv.create_session( configSessionConfig(enable_auditTrue), creator_diddid:mesh:admin, ) # Agent 加入环级别按信任分自动分配 ring hv.join_session( session.sso.session_id, did:mesh:agent-1, sigma_raw0.85, ) # RING_2_STANDARD受信任 Agent # 激活会话并执行受治理的 Saga hv.activate_session(session.sso.session_id) saga session.saga.create_saga(session.sso.session_id) step session.saga.add_step( saga.saga_id, draft_email, did:mesh:agent-1, execute_api/api/draft, undo_api/api/undo-draft, timeout_seconds30, max_retries2, ) result await session.saga.execute_step( saga.saga_id, step.step_id, executordraft_email, ) # 终止会话返回抗篡改审计根哈希 hash_root hv.terminate_session(session.sso.session_id)环分配的阈值规则README 中明确、并被 2.0.0 的环增强机制沿用为eff_score 0.95且具备共识consensus→RING_1_PRIVILEGEDeff_score 0.60→RING_2_STANDARD其余情况 →RING_3_SANDBOX未知 Agent 的默认档。会话生命周期状态为CREATED - HANDSHAKING - ACTIVE - TERMINATING - ARCHIVED。三、2.0.0六大维度的深度强化2026-02-202.0.0 与 1.0.0 同日记录是功能量最大的一次发布。CHANGELOG 将其划分为六个类别共 14 项新增能力下面逐类展开并对照源码。3.1 可观测性Observability结构化事件总线observability/event_bus.pyappend-only 事件存储提供类型化事件、pub/sub 与多索引查询按事件类型、Agent、会话、时间范围因果 Trace IDobservability/causal_trace.py分布式追踪编码完整的 spawn/delegation 树而非仅仅是关联 ID。源码验证两个文件均存在于 src/hypervisor/observability/顶层包导出HypervisorEventBus、EventType、HypervisorEvent、CausalTraceId。该目录还包含 README 中提到的 Prometheus 指标采集器prometheus_collector.py与 OpenTelemetry span 导出器saga_span_exporter.py。3.2 执行环增强Ring Improvements动态环提权rings/elevation.py带 TTL 的临时特权升级类似带过期时间的sudo支持自动过期与手动吊销环继承子 Agent 继承父 Agent 环 - 1防止通过 spawn 提权环越权检测器rings/breach_detector.py对环调用模式做滑动窗口异常评分HIGH/CRITICAL 严重度触发熔断circuit breaker。源码验证rings/elevation.py 定义了RingElevationManagerrings/breach_detector.py 定义了RingBreachDetector二者均在顶层__all__中导出。环提权的实际用法继承自 README 配置章节from hypervisor import ExecutionRing, RingElevationManager elevation_mgr RingElevationManager() # 请求临时 Ring 1 访问TTL 默认 300s上限 3600s elevation elevation_mgr.request_elevation( agent_diddid:mesh:agent-1, session_idsession.sso.session_id, current_ringExecutionRing.RING_2_STANDARD, target_ringExecutionRing.RING_1_PRIVILEGED, ttl_seconds300, # 5 分钟后自动过期 attestationsigned-by-sre, # Ring 1 必需 reasondeploy-approval, trust_score0.96, ) # 提前吊销如需要 elevation_mgr.revoke_elevation(elevation.elevation_id) # 周期调用使已过期的提权失效 elevation_mgr.tick()提权约束仅当 Agent 信任分达到目标环阈值时才授予Ring 1 额外要求 attestation 字符串Ring 0 永远不能通过标准 API 授予。越权检测的严重度分档为NONE | LOW | MEDIUM | HIGH | CRITICAL检测到 HIGH/CRITICAL 可触发自动降级或 Kill Switch。3.3 责任体系增强Liability Improvements故障日志liability/attribution.py受 Shapley 值启发的比例化故障评分取代二元的有罪/无罪判定隔离管理器liability/quarantine.py终止前先做只读隔离保留取证数据带超时的自动释放持久化责任账本liability/ledger.py按 Agent 维护历史风险评分与准入决策admit / probation / deny。从源码结构看当前src/hypervisor/目录下没有独立的liability/子目录可以推断这些责任能力在后续包整合中被并入其他模块或与agent-governance-toolkit-core合并维护。CHANGELOG 中仍可查证的遗留痕迹是 Kill Switch 的终止原因集合中包含quarantine_timeout隔离期超时未解决见 security/kill_switch.py 相关测试 tests/test_kill_switch.py。3.4 Saga 增强Saga Improvements并行扇出saga/fan_out.py并发分支执行支持ALL_MUST_SUCCEED、MAJORITY_MUST_SUCCEED、ANY_MUST_SUCCEED三种汇聚策略执行检查点saga/checkpoint.py捕获达成了什么目标而非仅状态快照支持部分重放而不必重跑已完成的副作用声明式 Saga DSLsaga/dsl.py用 dict/YAML 声明 Saga 拓扑带校验、扇出支持与SagaStep转换。同样从源码结构看当前 saga/ 目录仅保留orchestrator.py与state_machine.py导出SagaOrchestrator、SagaTimeoutError、SagaState、StepState扇出、检查点、DSL 三个独立模块未在当前树中保留为独立文件。Saga 的核心补偿语义失败后按逆序补偿已提交步骤仍由SagaOrchestrator承载其调用方式见 1.0.0 示例中的add_step(..., undo_api...)。3.5 会话增强Session Improvements版本计数器session/vector_clock.py强制因果一致性、拒绝过期写stale-write rejection、读取时自动合并资源锁session/intent_locks.pyREAD / WRITE / EXCLUSIVE 三种锁声明带争用检测与基于等待图wait-for graph的锁超时防死锁隔离级别session/isolation.py按 Saga 粒度提供SNAPSHOT、READ_COMMITTED、SERIALIZABLE低风险 Saga 可跳过协调开销。源码验证session/vector_clock.pyVectorClock、CausalViolationError与 session/isolation.pyIsolationLevel均存在且被顶层导出intent_locks.py未在当前树中保留为独立文件与 3.3/3.4 节的观察一致。配套测试为 tests/test_session_isolation.py 与 tests/unit/test_session.py。3.6 安全控制SecurityAgent 限速器security/rate_limiter.py按 Agent × 环的令牌桶限速限流可配置、令牌自动回充Kill Switchsecurity/kill_switch.py优雅终止 Agent并将执行中的 Saga 步骤移交给替补 Agent。源码验证security/rate_limiter.py 定义AgentRateLimiter与RateLimitExceededsecurity/kill_switch.py 定义KillSwitch与KillResult。默认按环限流值为速率 tokens/s突发容量环默认限流说明Ring 0 (Root)(100.0, 200.0)管理操作最高吞吐Ring 1 (Privileged)(50.0, 100.0)受信 Agent 高吞吐Ring 2 (Standard)(20.0, 40.0)中等吞吐Ring 3 (Sandbox)(5.0, 10.0)受限吞吐Kill Switch 用法与六种终止原因继承自 README 配置章节与源码KillReason枚举一致from hypervisor import KillSwitch from hypervisor.security.kill_switch import KillReason kill_switch KillSwitch() # 终止一个行为异常的 Agent result kill_switch.kill( agent_diddid:mesh:rogue-agent, session_idsession.sso.session_id, reasonKillReason.RING_BREACH, ) # result.handoffs: 移交给替补 Agent 的执行中 Saga 步骤 # result.compensation_triggered: 活跃 Saga 是否触发了补偿终止原因枚举behavioral_drift行为偏离预期模式、rate_limit超过限流阈值、ring_breach尝试越权访问环、manual操作员主动终止、quarantine_timeout隔离超时、session_timeout会话超过最长时限。3.7 2.0.0 的量化指标CHANGELOG 的 Changed 部分给出三个数字可作为版本演进的量化锚点包版本升至 2.0.0公共导出从 28 个增至58 个当前 src/hypervisor/init.py 的__all__仍保留约 40 个稳定导出如Hypervisor、RingEnforcer、KillSwitch、SagaOrchestrator测试数从 184 增至326 个。当前测试树分布在 tests/unit/如test_ring_enforcement.py、test_observability.py、test_session.py与 tests/integration/端到端与场景测试。四、2.1.0命令拒绝清单强制2026-06-15这是 CHANGELOG 的最新条目也是本文重点解析的增量。它包含三项变更命令拒绝清单强制rings/enforcer.py新增RingEnforcer.check_command()方法针对全局DENIED_COMMANDS列表做子进程命令校验采用不区分大小写匹配并剥离 shell 元字符以防止注入绕过CommandCheckResult数据结构包含allowed、reason、command、matched_denylist_entry四个字段给出结构化的校验结论行为联动与测试hypervisor.sandbox中的DENIED_COMMANDS从此在运行时经由RingEnforcer强制执行新增 21 个针对拒绝清单边界情况的测试大小写变化、空白、注入尝试、部分匹配、大输入。4.1 全局拒绝清单 DENIED_COMMANDS 全貌DENIED_COMMANDS定义在 src/hypervisor/sandbox/init.pyL50-L79共 23 条按攻击向量分五类类别条目被禁原因网络抓取工具curl,wget,ftp,telnet主要的数据外泄 / C2 通道裸套接字 / 代理工具nc,ncat,netcat,socat,nmap,tcpdump可绕过网络策略替代解释器perl,ruby,python2可执行任意代码编译器工具链gcc,g,make,cc运行时可生成新可执行文件Shellbash,sh,dash,zsh,ksh,fish可派生绕过环强制的子 shell同文件还定义了沙箱容器的最小 PATH 常量MINIMAL_SANDBOX_PATH /usr/local/sandbox/binL21只保留python3/python两个二进制ALLOWED_BINARIES。源码注释明确说明PATH 钉扎pinning与文件系统层面的二进制移除见 docker/Dockerfile.sandbox是纵深防御的两层而非二选一——即使拒绝清单被绕过绝对路径也找不到这些二进制。对应冒烟测试 tests/unit/test_sandbox_path.py 断言对每个拒绝条目shutil.which(cmd, pathMINIMAL_SANDBOX_PATH)均返回None。4.2 check_command 的五步校验算法对照 rings/enforcer.py 中check_command()L236-L292的实现完整校验流程为空值拒绝command为None或空串时直接返回allowedFalsereason 为 Empty or None command is not allowed提取基础命令先strip()再取第一个空白分隔的 token即curl -X POST会取curl纯空白命令同样被拒绝Command contains no executable name剥离尾部 shell 元字符base_command.rstrip(;|)——curl;与curl都会被归一成curl堵住拼接型注入绕过L273小写归一base_command.lower()使CURL、Curl等大小写变体无法绕过精确匹配拒绝清单与DENIED_COMMANDS逐项做大小写不敏感的全等比较注意是精确匹配而非子串匹配命中则返回allowedFalse并带上命中的清单条目。# 核心匹配逻辑enforcer.py L278-L285 的简化呈现 for denied_cmd in DENIED_COMMANDS: if base_command_lower denied_cmd.lower(): return CommandCheckResult( allowedFalse, reasonfCommand {base_command} is denied by sandbox policy, commandbase_command, matched_denylist_entrydenied_cmd, )CommandCheckResultL106-L120的四个字段语义allowed是否放行、reason人类可读结论、command被检查的基础命令名不含参数、matched_denylist_entry命中的清单条目放行时为None。这个结论 命中项的结构化返回使审计日志可以直接记录哪条策略拦了这个命令。拒绝清单与执行环体系的关系由 rings/enforcer.py 顶部的from hypervisor.sandbox import DENIED_COMMANDS导入L19坐实这正是 CHANGELOG Changed 条目DENIED_COMMANDS现在在运行时经由RingEnforcer强制执行的落地点。RingEnforcer同时承担环级资源约束RING_CONSTRAINTS将每个环映射到网络 / 文件系统 / 子进程 / 工具并发上限如 Ring 3 禁止网络与子进程、max_concurrent_tools2命令拒绝清单是其子进程维度的最后一道闸。4.3 测试证据21 个新增测试落在 tests/unit/test_command_denylist.py。从该文件可见的断言覆盖包括DENIED_COMMANDS常量存在且非空核心条目curl、wget、bash、sh在列安全命令python3、ls、cat放行逐类拒绝断言网络工具nc/ncat/netcat/socat/nmap/tcpdump/ftp/telnet、Shellbash/sh/zsh/fish/ksh/dash、编译器gcc/g/cc/make、替代解释器perl/ruby/python2。CHANGELOG 提到的其余边界维度大小写变体、空白处理、注入元字符、部分匹配、大输入同样在该文件内验证。运行方式继承自 README Test Suite 章节pytest tests/ -v # 全量测试 pytest tests/unit/test_command_denylist.py -v # 仅拒绝清单测试五、版本现状CHANGELOG 终点与源码 5.0.0 的落差阅读这份 CHANGELOG 时最容易产生的疑问是为什么源码已经是 5.0.0 而日志停在 2.1.0。结合仓库中的多处证据可以准确描述当前状态pyproject.toml 声明version 5.0.0description为 Deprecated. Previously published as agent-hypervisor. Install agent-governance-toolkit-core instead.运行时依赖仅为agent-governance-toolkit-core5.0.0,6.0发布出去的 wheel 是一个纯依赖的弃用桩[tool.hatch.build.targets.wheel]中bypass-selection true使 wheel 不打包任何源码只做重定向src/hypervisor/init.py 在 import 时发出DeprecationWarning提示改用agent-governance-toolkit-core仓库内该目录的src/与tests/仍保留为事实来源由 CI 通过可编辑安装的-core包持续跑测pyproject.toml 注释中明确说明devextra 的存在原因恢复pytest tests/收集所需的 fastapi/pydantic/jsonschema 等测试依赖。因此对新项目的正确姿势是pip install agent-governance-toolkit-core后从hypervisor顶层包导入如上文 2.1 节的 quickstart而不是安装已弃用的独立包。这也解释了为什么 2.0.0 条目中的部分模块liability、saga fan_out/checkpoint/dsl、intent_locks在当前树中查无独立文件——包整合后这些能力被纳入统一的agent-governance-toolkit-core维护体系而 CHANGELOG 保留了它们最初引入时的历史记载。六、验证与延伸入口围绕本次版本演进仓库内可直接使用的验证与深入材料测试套件tests/unit/含test_ring_enforcement.py、test_command_denylist.py、test_observability.py等 18 个单元文件与 tests/integration/e2e 与场景测试微基准python benchmarks/bench_hypervisor.py覆盖环计算、delta 审计捕获、会话生命周期与 Saga 执行结果见 benchmarks/results/BENCHMARKS.mdREST APIuvicorn hypervisor.api.server:app启动 FastAPI 服务端点分组见 src/hypervisor/api/server.pySwagger 文档在http://localhost:8000/docs配置参考会话参数、环阈值、提权 TTL、Saga 步骤参数、Kill Switch 与越权检测的完整参数表见 README.md 的 Configuration Reference 章节沙箱镜像构建说明docs/sandbox-image.md 与 docker/Dockerfile.sandbox。七、小结Agent Hypervisor 的 CHANGELOG 勾勒出一条清晰的演进线1.0.0 用执行环、SSO 隔离、Saga 补偿、审计留痕与连带责任引擎搭起Agent 虚拟机的地基2.0.0 在可观测性事件总线 因果 Trace、环动态管理TTL 提权 越权熔断、会话一致性向量时钟 隔离级别与安全控制令牌桶限速 Kill Switch六个维度上全面加厚测试规模从 184 翻倍到 3262.1.0 则以RingEnforcer.check_command()与 23 条DENIED_COMMANDS清单补上了子进程命令注入这一环——元字符剥离、小写归一、精确匹配三重手法加上 PATH 钉扎的纵深防御配合 21 个边界测试形成完整闭环。需要注意的是该包当前源码已演进至 5.0.0 并作为弃用桩并入agent-governance-toolkit-coreCHANGELOG 所记载的能力现在应通过hypervisor顶层包由 -core 提供使用理解这份版本记录是掌握该仓库运行时治理子系统来龙去脉的最短路径。【免费下载链接】agent-governance-toolkitAI Agent Governance Toolkit — Policy enforcement, zero-trust identity, execution sandboxing, and reliability engineering for autonomous AI agents. Covers 10/10 OWASP Agentic Top 10.项目地址: https://gitcode.com/GitHub_Trending/ag/agent-governance-toolkit创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考