agent-governance-toolkit 依赖治理实战ACS 验证 API 打包契约与 Cargo Lockfile 对齐【免费下载链接】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本篇技术指南以仓库 docs/dependency-audits/2026-07-17-acs-validation-packaging.md 这份依赖审计记录为骨架完整还原一次典型的零新增依赖治理变更acs-generator收紧对 Python SDKagent-control-specification的依赖下限以及policy-engine/Cargo.lock清理未使用的pyo3-build-config旧条目。读完本文你将掌握如何判断一个依赖下限是否为有效安装契约、如何通过cargo --locked校验工作区锁文件一致性以及如何像本次审计一样输出包含安全相关性、破坏性变更评估与回滚计划的完整审计结论。审计背景一次聚焦打包契约 锁文件的依赖审计本次审计记录于2026-07-17位于仓库 docs/dependency-audits/ 审计系列目录下owner 为liamcrumm。审计对象是仓库内 vendored 的 Agent Control SpecificationACS技术栈位于 policy-engine/涉及两个组件acs-generatorACS 策略产物生成器一个用于从威胁描述生成 manifest、Rego 策略与评审报告的 CLI 工具policy-engine工作区一个包含core、sdk/python、sdk/rust、sdk/node及多个集成 crate 的 Cargo workspace见 policy-engine/Cargo.toml。审计的核心结论有两点且没有新增或升级任何第三方依赖变更对象变更内容性质acs-generator的 Python 依赖声明要求agent-control-specification0.3.1b1,0.4.0此前下限为0.3.1b0依赖下限收紧policy-engine/Cargo.lock移除未使用的pyo3-build-config 0.28.3条目锁文件清理这一零升级特点值得注意依赖审计并非只有升级依赖这一种动作修正错误的版本契约与清理锁文件残留同样是降低供应链风险、保证构建可复现性的重要手段。变更一acs-generator收紧对 Python SDK 的依赖下限为什么0.3.1b0不是有效的安装契约审计记录明确指出acs-generator现在要求agent-control-specification0.3.1b1,0.4.0。生成器导入的验证 API 由 Python SDK 在0.3.1b1中首次发布因此此前的0.3.1b0下限并不是一个有效的安装契约。这句话揭示了依赖治理中的一个关键概念——安装契约install contract与运行时契约的分离一个下限0.3.1b0如果对应的包版本可以成功安装那么它表面上成立但如果生成器实际import的 API 只在0.3.1b1才存在那么安装了0.3.1b0之后会在 import 阶段直接失败——这就是文档所说的not a valid install contract。换句话说依赖下限必须与代码实际使用的符号symbol的首次出现版本对齐而不是与某个能装上的版本对齐。0.3.1b1首次发布了 validation API所以下限必须至少提到0.3.1b1才能保证任何符合约束的解析结果都能在 import 时正常工作。validation API 的源码佐证Python SDK发行名为agent-control-specification见 policy-engine/sdk/python/pyproject.toml在 policy-engine/sdk/python/agent_control_specification/validation.py 中对外提供两类验证入口validate_acs_manifest(manifest: str) - ArtifactValidationResultvalidation.py#L71-L80验证一份完整或部分的 ACS manifest 字符串YAML/JSONvalidate_acs_artifacts(manifest, rego, *, opa_pathNone)validation.py#L83-L145将 manifest 与 Rego 模块一起送入共享的 Rust core做联合验证其中 Rego 可以传单个字符串或{模块名: 源码}字典还可通过opa_path指定自定义 OPA 可执行文件路径。两者均返回ArtifactValidationResult包含valid布尔值与诊断元组ValidationDiagnostic。ValidationDiagnosticvalidation.py#L12-L46携带component、code、message、source及可选的path、line、column、snippet字段可以直接映射进 CI 日志或 IDE 诊断面板。从实现看Python 侧只是薄封装真正校验逻辑位于_native.validate_manifest_artifact(...)/_native.validate_artifacts(...)即 Rust core对应 policy-engine/core/src/artifact_validation.rs通过 PyO3 绑定暴露。生成器如何消费 validation APIacs-generator是 CLI 化的策略产物生成器README 明确The generator is a CLI artifact-authoring utility见 policy-engine/generator/README.md。它在 policy-engine/generator/acs_generator/validation.py#L13 处直接执行from agent_control_specification import validate_acs_manifest并在validate_artifacts()policy-engine/generator/acs_generator/validation.py#L46-L70中编排了完整的生成后校验流水线_validate_schema(manifest_yaml)——用 SDK 携带的 manifest schema 做结构校验_validate_core(manifest_yaml)——调用核心语义校验_reject_deprecated_refs(rego)/_reject_legacy_effects(rego)——拒绝已废弃的生成策略输入键与旧式 effectopa shutil.which(opa)——若 OPA 不在PATH上则跳过 Rego 语法与求值校验并记录警告若启用--strict缺失 OPA 直接抛错_validate_opa(...)与_validate_regex_patterns(...)——用 OPA 求值生成的 Rego、并针对 OPA 的 RE2 实现校验生成的正则模式模式提取基于opa parse --format json的 AST 而非文本扫描。正因为第 1、2 步在 import 期与运行期都强依赖 SDK 的validation模块acs-generator的版本下限就必须锚定在该模块首次发布的0.3.1b1上。这一import 依赖即版本契约的结论也可以从生成器测试侧得到印证——policy-engine/generator/tests/test_generator.py 直接from acs_generator.validation import validate_artifacts并把校验纳入测试路径。当前仓库的演进快照需要说明的是审计记录的是2026-07-17当时的变更快照。当前仓库主干中SDK 与生成器已经继续同步演进policy-engine/sdk/python/pyproject.toml#L7 版本为0.4.0b0policy-engine/generator/pyproject.toml#L7 版本同为0.4.0b0其依赖声明pyproject.toml#L10-L13已更新为dependencies [ agent-control-specification0.4.0b0,0.5.0, pyyaml6.0, ]可以看到生成器版本号与其要求的下限始终保持同步收紧0.4.0b0对0.4.0b0这正是本次审计确立的下限锚定首次发布版本原则在后续发布中的持续执行。生成器升级到0.4.0b0还伴随一个语义变化它现在是CLI-only组件入口见 pyproject.toml#L18-L20 的acs-generate/acs两个 console script服务端如需校验既有 manifest 与 Rego 字符串应直接使用 Python SDK 的验证 API 而非生成器。变更二policy-engine/Cargo.lock清理未使用的pyo3-build-config 0.28.3残留条目的成因Python 绑定 crate 的依赖声明policy-engine/sdk/python/Cargo.toml#L23为pyo3 { version 0.29, features [extension-module, abi3-py311] } [build-dependencies] pyo3-build-config 0.29即当前 manifest 中pyo3与构建期依赖pyo3-build-config都指向 0.29 系列。而审计前Cargo.lock中残留了一个pyo3-build-config 0.28.3条目——可以推断这很可能是在此前从 PyO3 0.28 升级到 0.29 时未重新生成锁文件而遗留的孤儿条目它既没有被pyo3 0.29引用也不在任何 member 的依赖图内只是单纯占着 lockfile 的一个位置。重新生成工作区锁文件后该条目被移除。重新生成后的状态当前 policy-engine/Cargo.lock 中只保留了一条pyo3 0.29.0Cargo.lock#L2141-L2151其依赖列表中引用pyo3-build-configpyo3-build-config 0.29.0Cargo.lock#L2155-L2161。pyo3-build-config 0.28.3不再出现Python 绑定与它的构建依赖都在 PyO3 0.29 上保持一致。用cargo --locked校验一致性审计记录强调清理之后工作区通过了 Cargo 的--locked检查。--locked是 Cargo 的严格模式标志要求 Cargo 必须使用 lockfile 中记录的版本若 manifest 与 lockfile 存在任何不一致例如删除了某个依赖声明却未同步 lockfile命令会直接报错退出而不是静默更新锁文件。因此在 CI 中使用类似cargo check --locked --workspace --all-targets可以保证任何提交的 lockfile 都与 workspace manifest 完全同步这也是防止孤儿条目与漂移锁文件再次进入仓库的标准纪律。安全公告相关性评估依赖审计通常需要回答这次变更是否与安全公告相关。本记录的结论非常明确没有处理任何 CVE 或 RustSec 公告lockfile 变更只是移除一个未使用版本没有引入新包也没有改变当前生效的 PyO3 版本仍为 0.29Python 依赖下限的调整指向的是仓库自身的 MIT 许可 SDK 包agent-control-specificationlicense 声明见 policy-engine/sdk/python/pyproject.toml#L11而非某个第三方闭源或来源不明的发行物。这提醒我们并非每次依赖审计都必须与 CVE 挂钩。把移除未使用旧版本修正错误版本下限这类供应链卫生工作也纳入审计记录本身就是降低攻击面的做法——未使用的依赖条目越少被误解析、被投毒或被扫描器误报的机会就越小。破坏性变更风险评估审计将风险拆成两部分评估Lockfile 清理风险低。被移除的pyo3-build-config 0.28.3不在活动依赖图中任何 member 都不再引用它同时工作区在清理后通过cargo --locked校验证明没有破坏解析一致性。生成器版本契约收紧刻意变严。生成器升至0.4.0b0CLI-only同时要求 SDK0.3.1b1。表面看这是在升级要求实质是用略严格的下限预防一个本会在 import 时爆炸的安装组合——如果放任0.3.1b0下限存在解析器完全可能为生成器装上不含 validation API 的 SDK随后任何一次acs-generate init都会在导入validate_acs_manifest时崩溃。把失败提前到安装/解析阶段远好于让它发生在用户执行命令的时刻。两类风险的方向恰好相反锁文件清理是减法风险低依赖下限收紧是约束加法但换来的是安装期确定性。回滚计划审计记录给出了两条明确的操作指引Python 侧必须整体回滚回滚 Python 包版本与生成器依赖下限时必须同时进行。只回滚版本号而不回滚下限会重新制造0.3.1b0安装契约问题只回滚下限而不回滚版本则会产生声明与发布物不一致的包。不建议恢复pyo3-build-config 0.28.3锁条目审计明确说明在当前 workspace 下恢复该条目会迫使 lockfile 在cargo --locked下再次更新——也就是说一个回滚反而会制造一个新的不一致状态。对未使用条目的正确态度是让它留在历史里而不是复活它。可复用的依赖治理方法论从这份审计记录可以提炼出三条可迁移到任何项目的实践版本下限必须锚定符号首次出现版本依赖下限不是能装上的最低版本而是代码实际 import/调用的 API 首次发布的版本。写包时可以通过在 CI 中安装最低允许版本并跑一遍 import 冒烟测试来验证契约对应本仓库中生成器测试对validate_artifacts的覆盖。锁文件清理要伴随--locked纪律升级主依赖后应重新生成 workspace 锁文件并在 CI 中加入--locked检查杜绝孤儿条目和漂移锁文件反复出现。审计记录保持四段式结构变更与原因 → 安全公告相关性 → 破坏性变更风险 → 回滚计划。本记录docs/dependency-audits/2026-07-17-acs-validation-packaging.md本身就是一个可直接套用的模板仓库内同类记录见 docs/dependency-audits/。一次没有升级任何第三方依赖的审计照样可以通过修正版本契约、清理锁文件残留为整个 ACS 技术栈Python SDK、生成器、Rust 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），仅供参考 agent-governance-toolkit 依赖治理实战：ACS 验证 API 打包契约与 Cargo Lockfile 对齐
agent-governance-toolkit 依赖治理实战ACS 验证 API 打包契约与 Cargo Lockfile 对齐【免费下载链接】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本篇技术指南以仓库 docs/dependency-audits/2026-07-17-acs-validation-packaging.md 这份依赖审计记录为骨架完整还原一次典型的零新增依赖治理变更acs-generator收紧对 Python SDKagent-control-specification的依赖下限以及policy-engine/Cargo.lock清理未使用的pyo3-build-config旧条目。读完本文你将掌握如何判断一个依赖下限是否为有效安装契约、如何通过cargo --locked校验工作区锁文件一致性以及如何像本次审计一样输出包含安全相关性、破坏性变更评估与回滚计划的完整审计结论。审计背景一次聚焦打包契约 锁文件的依赖审计本次审计记录于2026-07-17位于仓库 docs/dependency-audits/ 审计系列目录下owner 为liamcrumm。审计对象是仓库内 vendored 的 Agent Control SpecificationACS技术栈位于 policy-engine/涉及两个组件acs-generatorACS 策略产物生成器一个用于从威胁描述生成 manifest、Rego 策略与评审报告的 CLI 工具policy-engine工作区一个包含core、sdk/python、sdk/rust、sdk/node及多个集成 crate 的 Cargo workspace见 policy-engine/Cargo.toml。审计的核心结论有两点且没有新增或升级任何第三方依赖变更对象变更内容性质acs-generator的 Python 依赖声明要求agent-control-specification0.3.1b1,0.4.0此前下限为0.3.1b0依赖下限收紧policy-engine/Cargo.lock移除未使用的pyo3-build-config 0.28.3条目锁文件清理这一零升级特点值得注意依赖审计并非只有升级依赖这一种动作修正错误的版本契约与清理锁文件残留同样是降低供应链风险、保证构建可复现性的重要手段。变更一acs-generator收紧对 Python SDK 的依赖下限为什么0.3.1b0不是有效的安装契约审计记录明确指出acs-generator现在要求agent-control-specification0.3.1b1,0.4.0。生成器导入的验证 API 由 Python SDK 在0.3.1b1中首次发布因此此前的0.3.1b0下限并不是一个有效的安装契约。这句话揭示了依赖治理中的一个关键概念——安装契约install contract与运行时契约的分离一个下限0.3.1b0如果对应的包版本可以成功安装那么它表面上成立但如果生成器实际import的 API 只在0.3.1b1才存在那么安装了0.3.1b0之后会在 import 阶段直接失败——这就是文档所说的not a valid install contract。换句话说依赖下限必须与代码实际使用的符号symbol的首次出现版本对齐而不是与某个能装上的版本对齐。0.3.1b1首次发布了 validation API所以下限必须至少提到0.3.1b1才能保证任何符合约束的解析结果都能在 import 时正常工作。validation API 的源码佐证Python SDK发行名为agent-control-specification见 policy-engine/sdk/python/pyproject.toml在 policy-engine/sdk/python/agent_control_specification/validation.py 中对外提供两类验证入口validate_acs_manifest(manifest: str) - ArtifactValidationResultvalidation.py#L71-L80验证一份完整或部分的 ACS manifest 字符串YAML/JSONvalidate_acs_artifacts(manifest, rego, *, opa_pathNone)validation.py#L83-L145将 manifest 与 Rego 模块一起送入共享的 Rust core做联合验证其中 Rego 可以传单个字符串或{模块名: 源码}字典还可通过opa_path指定自定义 OPA 可执行文件路径。两者均返回ArtifactValidationResult包含valid布尔值与诊断元组ValidationDiagnostic。ValidationDiagnosticvalidation.py#L12-L46携带component、code、message、source及可选的path、line、column、snippet字段可以直接映射进 CI 日志或 IDE 诊断面板。从实现看Python 侧只是薄封装真正校验逻辑位于_native.validate_manifest_artifact(...)/_native.validate_artifacts(...)即 Rust core对应 policy-engine/core/src/artifact_validation.rs通过 PyO3 绑定暴露。生成器如何消费 validation APIacs-generator是 CLI 化的策略产物生成器README 明确The generator is a CLI artifact-authoring utility见 policy-engine/generator/README.md。它在 policy-engine/generator/acs_generator/validation.py#L13 处直接执行from agent_control_specification import validate_acs_manifest并在validate_artifacts()policy-engine/generator/acs_generator/validation.py#L46-L70中编排了完整的生成后校验流水线_validate_schema(manifest_yaml)——用 SDK 携带的 manifest schema 做结构校验_validate_core(manifest_yaml)——调用核心语义校验_reject_deprecated_refs(rego)/_reject_legacy_effects(rego)——拒绝已废弃的生成策略输入键与旧式 effectopa shutil.which(opa)——若 OPA 不在PATH上则跳过 Rego 语法与求值校验并记录警告若启用--strict缺失 OPA 直接抛错_validate_opa(...)与_validate_regex_patterns(...)——用 OPA 求值生成的 Rego、并针对 OPA 的 RE2 实现校验生成的正则模式模式提取基于opa parse --format json的 AST 而非文本扫描。正因为第 1、2 步在 import 期与运行期都强依赖 SDK 的validation模块acs-generator的版本下限就必须锚定在该模块首次发布的0.3.1b1上。这一import 依赖即版本契约的结论也可以从生成器测试侧得到印证——policy-engine/generator/tests/test_generator.py 直接from acs_generator.validation import validate_artifacts并把校验纳入测试路径。当前仓库的演进快照需要说明的是审计记录的是2026-07-17当时的变更快照。当前仓库主干中SDK 与生成器已经继续同步演进policy-engine/sdk/python/pyproject.toml#L7 版本为0.4.0b0policy-engine/generator/pyproject.toml#L7 版本同为0.4.0b0其依赖声明pyproject.toml#L10-L13已更新为dependencies [ agent-control-specification0.4.0b0,0.5.0, pyyaml6.0, ]可以看到生成器版本号与其要求的下限始终保持同步收紧0.4.0b0对0.4.0b0这正是本次审计确立的下限锚定首次发布版本原则在后续发布中的持续执行。生成器升级到0.4.0b0还伴随一个语义变化它现在是CLI-only组件入口见 pyproject.toml#L18-L20 的acs-generate/acs两个 console script服务端如需校验既有 manifest 与 Rego 字符串应直接使用 Python SDK 的验证 API 而非生成器。变更二policy-engine/Cargo.lock清理未使用的pyo3-build-config 0.28.3残留条目的成因Python 绑定 crate 的依赖声明policy-engine/sdk/python/Cargo.toml#L23为pyo3 { version 0.29, features [extension-module, abi3-py311] } [build-dependencies] pyo3-build-config 0.29即当前 manifest 中pyo3与构建期依赖pyo3-build-config都指向 0.29 系列。而审计前Cargo.lock中残留了一个pyo3-build-config 0.28.3条目——可以推断这很可能是在此前从 PyO3 0.28 升级到 0.29 时未重新生成锁文件而遗留的孤儿条目它既没有被pyo3 0.29引用也不在任何 member 的依赖图内只是单纯占着 lockfile 的一个位置。重新生成工作区锁文件后该条目被移除。重新生成后的状态当前 policy-engine/Cargo.lock 中只保留了一条pyo3 0.29.0Cargo.lock#L2141-L2151其依赖列表中引用pyo3-build-configpyo3-build-config 0.29.0Cargo.lock#L2155-L2161。pyo3-build-config 0.28.3不再出现Python 绑定与它的构建依赖都在 PyO3 0.29 上保持一致。用cargo --locked校验一致性审计记录强调清理之后工作区通过了 Cargo 的--locked检查。--locked是 Cargo 的严格模式标志要求 Cargo 必须使用 lockfile 中记录的版本若 manifest 与 lockfile 存在任何不一致例如删除了某个依赖声明却未同步 lockfile命令会直接报错退出而不是静默更新锁文件。因此在 CI 中使用类似cargo check --locked --workspace --all-targets可以保证任何提交的 lockfile 都与 workspace manifest 完全同步这也是防止孤儿条目与漂移锁文件再次进入仓库的标准纪律。安全公告相关性评估依赖审计通常需要回答这次变更是否与安全公告相关。本记录的结论非常明确没有处理任何 CVE 或 RustSec 公告lockfile 变更只是移除一个未使用版本没有引入新包也没有改变当前生效的 PyO3 版本仍为 0.29Python 依赖下限的调整指向的是仓库自身的 MIT 许可 SDK 包agent-control-specificationlicense 声明见 policy-engine/sdk/python/pyproject.toml#L11而非某个第三方闭源或来源不明的发行物。这提醒我们并非每次依赖审计都必须与 CVE 挂钩。把移除未使用旧版本修正错误版本下限这类供应链卫生工作也纳入审计记录本身就是降低攻击面的做法——未使用的依赖条目越少被误解析、被投毒或被扫描器误报的机会就越小。破坏性变更风险评估审计将风险拆成两部分评估Lockfile 清理风险低。被移除的pyo3-build-config 0.28.3不在活动依赖图中任何 member 都不再引用它同时工作区在清理后通过cargo --locked校验证明没有破坏解析一致性。生成器版本契约收紧刻意变严。生成器升至0.4.0b0CLI-only同时要求 SDK0.3.1b1。表面看这是在升级要求实质是用略严格的下限预防一个本会在 import 时爆炸的安装组合——如果放任0.3.1b0下限存在解析器完全可能为生成器装上不含 validation API 的 SDK随后任何一次acs-generate init都会在导入validate_acs_manifest时崩溃。把失败提前到安装/解析阶段远好于让它发生在用户执行命令的时刻。两类风险的方向恰好相反锁文件清理是减法风险低依赖下限收紧是约束加法但换来的是安装期确定性。回滚计划审计记录给出了两条明确的操作指引Python 侧必须整体回滚回滚 Python 包版本与生成器依赖下限时必须同时进行。只回滚版本号而不回滚下限会重新制造0.3.1b0安装契约问题只回滚下限而不回滚版本则会产生声明与发布物不一致的包。不建议恢复pyo3-build-config 0.28.3锁条目审计明确说明在当前 workspace 下恢复该条目会迫使 lockfile 在cargo --locked下再次更新——也就是说一个回滚反而会制造一个新的不一致状态。对未使用条目的正确态度是让它留在历史里而不是复活它。可复用的依赖治理方法论从这份审计记录可以提炼出三条可迁移到任何项目的实践版本下限必须锚定符号首次出现版本依赖下限不是能装上的最低版本而是代码实际 import/调用的 API 首次发布的版本。写包时可以通过在 CI 中安装最低允许版本并跑一遍 import 冒烟测试来验证契约对应本仓库中生成器测试对validate_artifacts的覆盖。锁文件清理要伴随--locked纪律升级主依赖后应重新生成 workspace 锁文件并在 CI 中加入--locked检查杜绝孤儿条目和漂移锁文件反复出现。审计记录保持四段式结构变更与原因 → 安全公告相关性 → 破坏性变更风险 → 回滚计划。本记录docs/dependency-audits/2026-07-17-acs-validation-packaging.md本身就是一个可直接套用的模板仓库内同类记录见 docs/dependency-audits/。一次没有升级任何第三方依赖的审计照样可以通过修正版本契约、清理锁文件残留为整个 ACS 技术栈Python SDK、生成器、Rust 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），仅供参考