企业官网建设流程全解析

Agent Governance Toolkit v4 策略语言移除指南：ACS v5 单一契约迁移、渐进式绞杀与零基线 Ratchet

【免费下载链接】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

导读

本文围绕 Agent Governance Toolkit（AGT）中「v4 策略语言移除（v4 policy-language removal）」这一核心技术演进展开，系统讲解 AGT 如何将遗留的 v4 意图式策略语言（GovernancePolicy、PatternType、PolicyInterceptor等）逐步淘汰，使 ACS（v5）策略层成为工具包中唯一的策略契约。你将掌握：v4 与 v5 的符号级对应关系、从governance.yaml时代走向 AGT-MANIFEST-1.0 清单时代的字段处置方法、scripts/check_v4_ratchet.py严格棘轮（ratchet）机制的实现原理与命令行用法，以及从阶段 0 到阶段 6 的完整分阶段迁移路径。

本文以 v4-removal.md 为骨架，结合仓库中scripts/check_v4_ratchet.py、scripts/v4_ratchet_baseline.json、agent-governance-python/agt-policies/src/agt/cli/下的迁移工具源码等证据展开。对 v4 用户而言，这是一次破坏性变更（breaking change），迁移路径是单向的：v4 工程只能转换为 v5 ACS 清单，无法回退。

一、为什么移除 v4 策略语言

AGT 正在移除遗留的 v4 策略语言，目标很明确：让 ACS（v5）策略层成为工具包中唯一的策略契约。v4 的构造只允许存活在一个地方——单向迁移工具（one-way migration tool）内部，该工具把 v4 工程转换为 v5 ACS 清单。

从仓库中的 ratchet 脚本文档可以看出这一战略定位的完整表述（check_v4_ratchet.py）：

"Phase 0 of removing the legacy v4 policy language so the ACS (v5) policy layer is the only policy contract in the toolkit."

这意味着：

• 策略契约收敛：不再同时维护两套策略语言，避免语义漂移、双份维护成本和审计复杂度；
• 单向迁移：v4 构造仅存于迁移工具，运行时模块只接受 ACS 与 AGT 清单；
• 破坏性变更：v4 用户必须升级，且升级路径不可逆。

二、什么是 v4 策略语言：符号清单与 v5 对应关系

文档给出了完整的 v4 符号清单，明确每个符号的「原住地（Home）」与「v5 替代品（Replacement）」。下表是 v4 用户定位升级目标的核心地图：

仓库中的 ratchet 脚本（check_v4_ratchet.py）以UNAMBIGUOUS_SYMBOLS冻结集合的形式，把这些 v4 标识符逐一登记为「无歧义 v4 符号」，供全局计数。脚本中还包含更多 v4 时代的辅助符号，例如from_cedar、discover_policies、aca_config_from_policy、docker_config_from_policy、hyperlight_config_from_policy、mxc_config_from_policy、nono_config_from_policy、PolicyTemplates、compose_policies、override_policy等——它们同样是 v4 扫描范围的一部分。

三、v4 的唯一合法栖身地：单向迁移工具

v4 策略语言只允许存活在迁移工具内部。棘轮机制通过**显式允许清单（allowlist）**豁免迁移模块，而非豁免整个目录：

• 允许清单包含agent-governance-python/agt-policies/src/agt/cli/migrate.py及其同级模块；
• 后续将演进为独立的agt-v4-migrate发行包及其测试。

从仓库实际结构看，迁移工具的载体已落地为：

• agent-governance-python/agt-policies/src/agt/cli/migrate.py—— 主迁移命令；
• agent-governance-python/agt-policies/src/agt/cli/_migrate_bridge.py—— 冻结的 v4 运行时桥（differential test 的参照实现）；
• agent-governance-python/agt-policies/src/agt/cli/_migrate_re2.py—— RE2 校验辅助；
• agent-governance-python/agt-policies/src/agt/cli/_migrate_resolution/—— 迁移期governance.yaml解析器（discover.py、merge.py、build.py、scope.py、errors.py），对应文档 Phase 4 中「resolver 及其契约、测试只存活于agt.cli._migrate_resolution」的表述；
• agent-governance-python/agt-policies/src/agt/cli/__main__.py—— CLI 入口。

迁移工具的语义约束：

• 只读一次：读取 v4 工程一次，输出扁平化的 ACS 清单加 bundles；
• 运行时不受影响：运行时模块只接受 ACS 与 AGT 清单；
• 组合用原生语法：策略组合使用原生 ACSextends，不再由迁移工具合成运行时策略。

四、分阶段移除计划：内部绞杀 + 原子化公开破坏性发布

移除以「内部绞杀者（strangler）」模式运行，最后通过一次原子化的公开破坏性发布完成切换。六阶段全景如下：

阶段 0：语义清单与棘轮

scripts/check_v4_ratchet.py是阶段 0 的核心交付物，它按文件对每个存活的 v4 符号做清单统计，并强制执行严格棘轮：任何变更不得新增 v4 用法、v4 标记不得移入新文件、每个符号的计数不得上升。

脚本的检测能力（与 check_v4_ratchet.py 的 docstring 一致）非常细致：

• Python 检测基于 AST 且感知 import：普通字符串和注释永远不计入，避免误计数；
• 计数对象：类与函数定义、别名导入及其使用、关键字与参数名、__all__条目、复合字符串注解、以及被动态导入 /getattr/mock.patch使用的语义字符串常量——因此计数不可能在未真正删除的情况下下降；
• 歧义名处理：与无关代码冲突的名字（ExecutionContext、PolicyEvaluator）只有在「从合格 v4 模块绑定」「通过 v4 模块别名访问」或「在规范 v4 文件中定义并使用」时才计数，相对导入会按当前模块解析，从而不会误伤外来同名代码；
• Markdown 要求：对歧义名需要限定 v4 上下文才计数；
• 失败闭合：任何无法解码或解析的 Python 文件直接导致 gate 失败（fail closed）；
• Rust / TypeScript：使用标识符边界（identifier-boundary）的 token 匹配；
• Markdown 与规范层：从统一词表（one vocabulary）扫描；每个 YAML / YML / JSON 文件都要检查完整的 v4PolicyDocument与PolicyDefaultsschema，并带显式的 ACS、Kubernetes、AgentMesh 信任策略排除项；
• governance.yaml/governance.yml：无论内容如何都计数，从而让文档、spec 与策略数据的清除义务对零门（zero gate）可见；
• 结构性检查：窄范围的结构检查还能捕获「改名后的意图策略解释器」——即把 blocked patterns、工具列表、预算、pattern 模式组合在一起的改名实现。

命令行用法（与 check_v4_ratchet.py 一致，另支持--json输出）：

python scripts/check_v4_ratchet.py # 对照基线执行 gate python scripts/check_v4_ratchet.py --report # 查看清单，不执行 gate python scripts/check_v4_ratchet.py --json # 机器可读输出 python scripts/check_v4_ratchet.py --update-baseline # 在真实减少后更新基线 python scripts/check_v4_ratchet.py --update-baseline --allow-baseline-increase # 显式放行扫描语义变更

scripts/v4_ratchet_baseline.json是提交到仓库的基线文件。--update-baseline拒绝批准计数上升，除非显式传入--allow-baseline-increase（仅用于刻意的扫描器语义变更）。迁移允许清单会被登记与报告，但永远不会计入棘轮计数。

该 gate 及其单元测试与 lint 通过.github/workflows/v4-removal-ratchet.yml在每次 Pull Request 上运行。仓库中的 test_check_v4_ratchet.py 即该 gate 的单元测试。阶段 6 的最终 gate 会把非迁移总量（含规范性 spec）驱动到零。

阶段 1：原生契约

AgentControl构造与清单表示

AgentControl.from_path(str(...))是规范的运行时构造函数，接收文件系统路径。路径自带其父目录作为来源信息（provenance），因此相对的 bundle、data、prompt、Cedar 与extends引用都相对清单解析，而不是相对当前工作目录。其他构造方式：

• AgentControl.from_native—— 清单已在内存中时使用；
• AgentControl.from_url—— 远程场景；
• AgentControl.from_manifest_chain—— 分层（layered）场景。

解析后的清单是AGT-MANIFEST-1.0 的无损表示：执行结构校验，并保留 policy、tool、annotator、resolver 与 host extension 字段。它不接受意图级字段（max_tokens、allowed_tools、blocked_patterns），也从不合成策略或绑定。适配器兼容性由独立的AdapterManifestContract预检负责。静态预检要求已解析的清单，因为extends父级可能提供必需的干预点或工具。

关于limits段有一个重要安全原则：模型保留 AGT 的limits段，但运行时构造会拒绝它，直到 Python SDK 能够强制执行这些值——静默接受一个无法强制执行的安上限是不允许的。

评估结果与错误契约

AgentControl.evaluate_intervention_point(...)返回不可变的InterventionPointResult：

• verdict携带decision、reason、message、transform、evidence、result_labels；
• 结果本身携带transformed_policy_target、transformed_policy_target_applied、input_identity、enforced_identity；
• 审计信封使用 schemaagt.policy_evaluation.v1；
• ACS 目前不在InterventionPointResult上暴露policy_id或rule_id，因此这两个字段不出现在契约中，调用方不得从reason_code推断它们；
• 策略作者编写的message仍属于受限审计细节（restricted audit detail）。

错误契约方面，PolicyViolationError.from_evaluation_result(...)会发出稳定的、消毒后的公开消息，而不是把策略内容或用户内容复制进异常文本——这直接服务于防止敏感信息泄漏。

现有的AgentControl(...)、evaluate_intervention_point(...)、EvaluationResult在阶段 2 之前仍作为临时的桥接专用兼容表面存在，阶段 6 会整体移除。

适配器强制契约（Adapter enforcement contract）

GovernancePolicy字段处置表

迁移工具必须要么精确翻译每个策略字段，要么拒绝转换并给出人工复核发现（manual-review finding）。仅宿主管辖的字段必须显式移入宿主配置，不得静默丢弃。

阶段 2：提取边界

HostSession现在拥有单个会话的SnapshotBuilder、计数器与原生干预点调用：

• 在执行前预留尝试的工具调用，使被拒绝与失败的尝试也消耗预算；
• 在post_model_call之后记录模型 token；
• 只序列化计数器变更；
• AgentControl保持无会话状态，在阶段 1 回调线程安全契约下可共享。

v4 运行时桥把快照构建与评估委托给原生会话，自身只保留：v4 翻译、结果转换、宿主预算回退、审批回退、以及两处默认允许改写（default-permit rewrites）。现有适配器暂时禁用原生计数器计费，避免在阶段 3 脱离ExecutionContext之前重复计数。

单向GovernancePolicy翻译器位于agt.cli下，没有运行时导入路径。它接受：

• 精确字面量字段；
• 精确的PatternType.SUBSTRING、PatternType.REGEX、PatternType.GLOB形式。

以下情况一律拒绝迁移：动态表达式、宿主专属设置、非法 pattern、不支持的字段、以及已存在的输出。生成的清单在原子写入前用validate_manifest校验。差分测试将每个受支持构造与冻结的运行时桥对比，确保默认值与边界语义在过渡期不漂移。细节要点：

• REGEX 与 GLOB 使用 OPA 的 Go RE2 校验器（仓库中对应实现见agent-governance-python/agt-policies/src/agt/cli/_migrate_re2.py）；
• GLOB 使用 RE2 的\z结束锚点，而非 Python 不支持的\Z；
• 构造函数与治理链迁移都拒绝覆盖已存在的清单、bundle 与备份。

阶段 3：适配器切换

17 个桥接框架适配器现在接受公开的原生runtime参数，并把 model、tool、stream、output 干预点路由到NativeAdapterRuntime与HostSession。涉及框架：A2A、Agent Shield、Anthropic、AutoGen、Bedrock、CrewAI、Gemini、Google ADK、Guardrails、LangChain、LlamaIndex、MAF、Mistral、OpenAI、PydanticAI、Semantic Kernel、Smolagents。它们不再通过AdapterRuntimeBridge或BridgeResult导入与评估，唯一残留的_v5_runtime_bridge依赖是临时策略兼容边的构造函数选择器。

特殊命名说明：Agent Shield 使用agt_runtime参数名，因为其既有位置参数runtime指的是 Agent Shield SDK 对象。

原生拒绝（native denials）会把evaluation_result与agt.policy_evaluation.v1审计记录附加到PolicyViolationError；临时策略边仍附加check_result，由一个共享结果 dispatcher 选择。两条路径中 transform 均为原生对象。运行时拥有审批配置：适配器可以省略approval_resolver或重复相同回调以支持过渡代码，但不同回调会在构造时被拒绝。

旧policy与私有_runtime参数仅用于让开发树在阶段 6 的公开破坏性切换前保持绿色。便捷包装器也接受runtime，但其策略路径不是原生默认，会随兼容桥一起移除。OpenAI Agents SDK 与 LangGraph 现在暴露原生运行时钩子路径，同时在宿主侧保留 checkpoint、handoff、审计与包装行为。

阶段 4：运行时清理

• 运行时治理文件夹发现已被移除；resolver、其契约与测试只存活于agt.cli._migrate_resolution（仓库中对应discover.py、merge.py、build.py、scope.py、errors.py）；
• AgentControl不再接受resolution_root；agt.manifest_resolution不对外公开；OPA 场景测试工具不再从governance.yaml合成运行时策略；
• 原生组合使用 ACSextends；
• Rust 核心与 SDK 奇偶校验 fixtures 不再暴露迁移专用的runtime_error:resolution_*变体；迁移命令私有保留等价诊断用于报告生成；
• OpenAI Agents SDK 钩子在给定runtime时通过NativeAdapterRuntime评估输入、工具调用、工具结果与输出；LangGraph 原生评估节点状态与工具调用，并对运行时清单加已注册工具哈希做指纹（fingerprint）；非策略语义（handoff 限制、checkpoint 元数据、节点包装、审计事件）仍归宿主所有。

阶段 5：语言与打包重写

• Rust 的FrameworkGovernanceAdapter现在接受原生AgentControl、Manifest与显式FrameworkHostConfig；已移除的本地策略与 pattern 类型不再导出；遗留形状的 YAML 直接清单校验失败，不再做进程内翻译；
• Mastra 包现在依赖 Node ACS 包，每个工具调用都委托给AgentControl.runTool；信任与防篡改审计仍是 Mastra 中间件；策略决策、transform、审批与工具目录全部来自 ACS 清单；
• 合并后的 Python core wheel 声明依赖agt-policies（因为强制包含原生适配器模块）；wheel 检查门会构建两个产物、校验依赖元数据、确认原生会话/运行时模块与迁移 Rego 资源已打包，并拒绝公开的manifest_resolution包。

阶段 6：原子化移除

公开兼容切换会移除：运行时桥、中心GovernancePolicy契约、兼容结果与决策类型、遗留策略加载器与后端、运行时文件夹解析。框架适配器现在要求原生 ACS 运行时；原生拒绝使用规范PolicyViolationError并保留结构化PolicyEvaluation。

• 旧意图策略字段不再有运行时实现；
• Haystack 集成的本地检查器等框架本地策略解释器被删除而非改名；
• 转换支持只保留在agt.cli下（单向迁移命令）；
• AgentMesh Wire Protocol 策略引擎是独立保留的产品：其 Python 实现与 TypeScript、Go、.NET 移植版使用 AgentMesh 规则 schema 与跨语言奇偶校验测试，不是被移除意图策略契约的适配器，也不在这次迁移范围内；
• 最终棘轮基线在迁移允许清单之外归零；结构检查同时检测改名的意图策略解释器，并区分保留的 AgentMesh 规则文档与被移除的策略数据。

五、迁移实操路径：v4 用户该怎么做

结合文档与仓库中的迁移工具（agent-governance-python/agt-policies/src/agt/cli/），v4 用户的推荐路径如下：

1. 盘点现状：先运行python scripts/check_v4_ratchet.py --report查看当前 v4 符号的完整清单，确认工程中所有GovernancePolicy、PolicyDocument、governance.yaml等 v4 构造的位置与数量；
2. 转换策略意图：对照上文「GovernancePolicy字段处置表」，把每个字段映射到 v5 目标——策略语义进 ACS 清单（metadata.name、policies.type: cedar、显式 Rego），宿主管辖的字段（预算、并发、超时、审计、checkpoint、backpressure）移入显式宿主配置；
3. 执行单向迁移：通过agt.cli的迁移命令（见migrate.py与__main__.py）读取 v4 工程，生成扁平 ACS 清单与 bundles；只支持精确字面量字段与SUBSTRING/REGEX/GLOB三种 pattern 形式，动态表达式与宿主设置会被拒绝并要求人工复核；
4. 验证产物：确认生成的清单通过validate_manifest校验、没有覆盖既有清单与备份；GLOB pattern 使用的是 RE2\z锚点而非 Python\Z，需注意 pattern 写法差异；
5. 切换适配器：框架适配器传入原生runtime（Agent Shield 用agt_runtime），模型、工具、流与输出干预点自动走NativeAdapterRuntime与HostSession；
6. 回归与收敛：利用差分测试确保默认值与边界语义与冻结的运行时桥一致；最终配合阶段 6 的原子化发布，把棘轮基线收敛到零。

六、给 v4 用户的兼容性提示

• 这是一次破坏性变更：阶段 6 之后运行时不再提供任何 v4 兼容表面，policy与私有_runtime参数、EvaluationResult兼容类型、to_v4_check_result等全部移除；
• 不要试图保留governance.yaml：运行时文件夹解析已被移除，任何governance.yaml/governance.yml文件在棘轮扫描中都会被计数，属于必须清除的对象；
• 策略组合使用原生extends：不要再依赖迁移器或运行时合成策略层次；
• AgentMesh Wire Protocol 策略引擎不受影响：它使用独立的 AgentMesh 规则 schema，不属于本次迁移范围；
• 验证途径：ratchet 门在每次 Pull Request 运行（.github/workflows/v4-removal-ratchet.yml），单元测试见 test_check_v4_ratchet.py，基线见 v4_ratchet_baseline.json；迁移工具的差分与迁移测试可参考agent-governance-python/agt-policies/tests/下的测试用例。

七、结语

v4 策略语言移除是 AGT 走向单一策略契约的关键一步：它用一个 AST 级、跨语言、对文档与 YAML/JSON 数据全覆盖的严格棘轮，把「消灭 v4」变成可度量的工程约束；又用「迁移工具 + 差分测试 + 允许清单」为存量 v4 用户提供了唯一受支持的出口。整个演进以内部绞杀推进、以原子化发布收尾，最终把运行时收敛到 ACS 清单这一唯一事实来源。对 v4 用户而言，理解字段处置表、尽早盘点并执行单向迁移，是平滑过渡到 v5 世界的前提。

【免费下载链接】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