企业官网建设流程全解析

Agent Governance Toolkit 包合并提案解读：从 45 个 Python 包收敛到 5 个发行版的架构重构

【免费下载链接】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/package-consolidation/PROPOSAL.md 提出的 Python 包合并方案：为何这个仓库要从 45 个独立包收敛为 5 个顶层发行版、每个新发行版吸收哪些现有包、如何通过三阶段迁移保证老用户的pip install命令不中断。读完本文，你将掌握该仓库的包拓扑、每个新发行版的组成与安装方式、以及可复用的"stub 包 + 弃用警告 + 下架"迁移方法论。

一、问题背景：45 个包的维护成本与版本漂移信号

Agent Governance Toolkit 的 Python 生态（agent-governance-python/）在提案时（2026-05-23）共包含45 个 Python 包，横跨两个顶层分组：

• 核心包组（位于 agent-governance-python/ 下）：agent-compliance、agent-os、agent-runtime、agent-hypervisor、agent-sre、agent-sandbox等；
• 框架集成包组（位于 agent-governance-python/agentmesh-integrations/ 下）：langchain、crewai、openai-agents、langgraph、llamaindex、haystack、pydantic-ai 等 21 个适配器。

这些包中只有 11 个在 PyPI 上有实际下载流量，其余 34 个要么未发布、要么流量低到 pypistats 都无法统计。而维护方却要为 45 个pyproject.toml各自维护版本号、依赖锁定和 CI 任务——对月下载量不足 1000 的包来说，这种开销没有对应价值。

更关键的是版本漂移（version skew）预警：提案时所有包统一为 3.7.0，唯独cedarling-agentmesh停在 3.5.0，滞后 0.2 个版本。这正是包数量膨胀后手工批量升级版本号必然会出现的问题——今天只有一个包滞后，随着包继续增多，这种情况会反复发生。

二、数据依据：审计报告揭示的下载分布

PROPOSAL.md 引用了同目录下的 AUDIT.md 作为完整数据支撑。审计报告（2026-05-23）的核心发现如下：

仅 5 个包贡献了绝大部分下载量（pypistats 最近 30 天数据）：

框架集成包小而均匀：每个集成适配器月下载量在 500～760 之间，且都遵循相同的结构模式。用单一发行版的可选 extras 替代 21 个独立包，能显著削减发布开销，对用户几乎没有负面影响。

Agent OS 内核模块全部未发布：agent-os/modules/下的 10 个模块（message-bus、tool-registry、context、control-plane、memory、nexus、observability 等）在 PyPI 上都没有存在感，说明它们仍是内部内核原语，不适合外部消费。

命名前缀不统一：现有包混用agent_*、agentmesh_*、a2a_*、avp_*、cedarling_*、nostr_*等多种前缀，没有共享命名空间——这正是合并时要一并解决的问题。

三、目标结构：5 个顶层发行版

合并目标是把 45 个包收敛为5 个顶层发行版，框架集成作为单一集成包上的可选 extras，而不是 21 个独立包。

发行版 1：agent-governance-toolkit（推荐入口，保持现状）

该包已存在且已使用可选 extras，保持不变，成为唯一推荐的安装入口。extras 列表扩展至覆盖今天所有独立发布的集成：

pip install agent-governance-toolkit pip install agent-governance-toolkit[langchain] pip install agent-governance-toolkit[crewai] pip install agent-governance-toolkit[openai-agents] pip install agent-governance-toolkit[full]

在仓库当前实现中，这个入口的元数据定义于 agent-compliance/pyproject.toml：它把core、integrations、cli、protocols四个新发行版声明为可选依赖，并为langchain、crewai、openai-agents、langgraph、llamaindex、haystack、pydantic-ai、adk等框架各自声明了转发到 integrations 包的 extras；同时保留kernel、mesh、runtime、sre等旧 extras 用于向后兼容，full一次性拉起全部四个新发行版。

发行版 2：agent-governance-toolkit-core（运行时内核）

整合当前需要单独安装的运行时内核包，吸收：

• agent-os-kernel
• agentmesh-primitives
• agentmesh-runtime
• agent-hypervisor
• agentmesh-platform

它是策略引擎、信任评分、审计、身份与执行环（execution ring）层——即不借助 CLI 或框架适配器、纯编程方式治理 Agent 所需的全部能力。

仓库中的实现 agent-governance-toolkit-core/pyproject.toml 印证了这一设计：该发行版"没有自己的包目录"，而是通过 hatchling 的force-include机制把 5 个兄弟目录的源码直接打进同一个 wheel——agent_os、cmvk、caas、emk、iatp、amb_core、atr、agent_control_plane、nexus、mcp_kernel_server、agent_primitives、agent_runtime、hypervisor、agentmesh全部合并发布，并吸收了cmvk、iatp、amb、observability、mcp、api、blockchain、otel、redis、server、storage、langchain、grpc等来自原各包的 extras。

发行版 3：agent-governance-toolkit-integrations（框架适配器）

所有框架适配器的单一发行版，每个适配器作为可选 extra，用户只拉取自己需要的部分。吸收 agentmesh-integrations/ 下全部 21 个包，包括 langchain、crewai、openai-agents、langgraph、llamaindex、haystack、pydantic-ai、flowise、langflow、adk 等。

实现细节同样体现在 agent-governance-toolkit-integrations/pyproject.toml：该包零强制框架依赖，唯一硬依赖是agent-governance-toolkit-core，其余 15 个框架（langchain、crewai、openai-agents、langgraph、llamaindex、haystack、pydantic-ai、adk、openshell等）全部声明为 optional extras，适配器源码同样通过force-include从agentmesh-integrations/各子目录收编。

发行版 4：agent-governance-toolkit-cli（运维工具）

供运维人员在基础设施上安装的 CLI 工具与代理服务器，而非放进应用代码。吸收：

• agent-sre
• agent-sandbox
• agentmesh-mcp-proxy
• agentmesh-mcp-server
• agentmesh-mcp-trust

发行版 5：agent-governance-toolkit-protocols（协议实现）

可能存在 AGT 之外消费者的协议实现。吸收：

• agent-mcp-governance
• agentmesh-trust-protocol
• a2a-agentmesh
• agentmesh-mcp-receipts

之所以单独保留，是因为下游消费者有时会独立固定协议包的版本，他们并不想要完整的治理栈。

保持独立的包

以下 6 个包暂不合并，因其范围足够聚焦，拉入大发行版反而增加困惑：

• agent-discovery
• agentmesh-lightning
• agent-rag-governance
• agentmesh-drift
• agentmesh-observability
• agentmesh-marketplace

同时，agent-os/modules/下 10 个 Agent OS 内核模块（agentmesh-message-bus、agentmesh-tool-registry、agentmesh-context、agentmesh-control-plane、agentmesh-memory、agentmesh-nexus等）今天不发布，在出现清晰的外部使用场景之前保持内部状态，不进入第一轮合并。

四、命名统一：agent-governance-toolkit-*前缀

所有新包名统一使用agent-governance-toolkit-*前缀，一举解决现有包名横跨agent_*、agentmesh_*、avp_*、cedarling_*、nostr_*五种前缀、无共享命名空间的不一致问题。

五、什么不会改变：源码不动，只动打包元数据

• 源码不移动：agent-governance-python/下的目录布局保持不变；
• 只有打包元数据变化：被吸收包的pyproject.toml更新为声明其内容属于父发行版（这正是上面看到的 hatchlingforce-include机制）；
• 旧包名通过迁移计划变成瘦别名（thin aliases），具体见 MIGRATION.md。

六、迁移计划：三阶段保证零破坏

MIGRATION.md 给出了明确的迁移方法论，总原则是：任何现有安装命令都不应被破坏。今天 requirements 文件里写着agent-os-kernel或agentmesh-runtime的用户，合并后依然要能装到可用的包。

Phase 1：Stub 包（重定向安装）

在新发行版发布前，先以每个旧名字发布一个 stub 包，声明新包为唯一依赖。例如固定到agentmesh-runtime==3.7.0的用户会装到 stub，而 stub 会拉入agent-governance-toolkit-core，代码继续正常工作。

示例 stubpyproject.toml：

[project] name = "agentmesh-runtime" version = "4.0.0" description = "Deprecated. Replaced by agent-governance-toolkit-core." dependencies = ["agent-governance-toolkit-core>=4.0.0"]

关键约束：stub 必须与合并发行版的首次发布同时上线，避免出现"一方存在、另一方不存在"的窗口期。

Phase 2：弃用警告

stub 上线后，任何对旧包名的运行时导入都会发出DeprecationWarning并指向替代品：

import warnings warnings.warn( "agentmesh-runtime is deprecated. Use agent-governance-toolkit-core instead. " "See https://github.com/microsoft/agent-governance-toolkit/blob/main/docs/package-consolidation/MIGRATION.md", DeprecationWarning, stacklevel=2, )

警告随首个合并版本发布，并至少保留两个 minor 版本后才会把 stub 标记为不支持。

Phase 3：Stub 下架

经过两个 minor 版本周期（按 AGT 正常发布节奏约 6 个月），stub 从 PyPI 撤回（yank）。由于此前已有弃用警告，对近期跑过测试的开发者而言，移除不会意外。

包映射总表

注意：cedarling-agentmesh是唯一一个不提供 stub、直接移除的包——提案认为其能力已被原生 ACS Cedar 策略配置覆盖。

七、导入兼容与版本编号

导入路径必须保持稳定：当两个旧包合并进同一个发行版时，公开的 Python 模块名和类名不得改变——用户直接 import 的是类，而不是包元数据名。代码在发行版之间移动没问题，只要现有导入路径继续可用。

如果模块路径必须调整，则在旧位置添加兼容 shim：

# agentmesh/openai_agents_trust/__init__.py (compatibility shim) import warnings from agentmesh.integrations.openai_agents import * # noqa: F401, F403 warnings.warn( "agentmesh.openai_agents_trust is deprecated. Import from agentmesh.integrations.openai_agents.", DeprecationWarning, stacklevel=2, )

版本编号：合并后的发行版从4.0.0起步（提案时计划），major 号提升标志着结构重构，也给依赖管理工具明确的升级审查信号；重定向旧名的 stub 同样以 4.0.0 发布以保持一致。从仓库现状看，该方案在后续演进中已推进到 5.0.0（见 agent-governance-toolkit-core/pyproject.toml 与 agent-compliance/pyproject.toml 中的版本声明），extras 的命名与依赖方向与提案保持一致。

八、实施顺序与社区流程

上线顺序（Rollout Order）：

1. 先实现agent-governance-toolkit-core——它覆盖下载量最高、范围最清晰的包，并在同一时间发布所有被吸收进 core 的 stub；
2. core 稳定后，实现agent-governance-toolkit-integrations并同步发布其 stub；
3. 随后跟进agent-governance-toolkit-cli和agent-governance-toolkit-protocols；
4. 两个 minor 版本后，撤回 core 与 integrations 的 stub。

社区反馈期：按 RFC 流程，任何代码变更合并前都必须在 issue 上发起讨论，最小评审窗口为 7 天。这是一个治理提案，需要社区共识而非单方面执行。

九、仓库现状印证：合并方案已落地

值得强调的是，这套提案并非停留在纸面：在当前仓库中，5 个新发行版的目录（agent-governance-toolkit-core、agent-governance-toolkit-integrations、agent-governance-toolkit-cli、agent-governance-toolkit-protocols）均已存在于 agent-governance-python/，且 agent-governance-toolkit-core/pyproject.toml 的 hatchling 构建配置明确注释了"合并自 agent-os-kernel、agentmesh-primitives、agentmesh-runtime、agent-hypervisor、agentmesh-platform 的依赖"，agent-governance-toolkit-integrations/pyproject.toml 也完整收编了agentmesh-integrations/下的适配器源码。对于想深入了解数据细节和迁移全貌的读者，可继续查阅 AUDIT.md 与 MIGRATION.md 原文。

十、小结：这套方案的普适价值

Package Consolidation Proposal 的核心价值不仅在于把 45 个包收敛为 5 个，更在于它给出了一套可复制的多包仓库治理方法论：先用审计数据量化每个包的下载量与依赖关系，识别"高流量核心 + 低流量长尾"的分布结构；再按运行时内核、框架适配器、运维工具、协议实现四种定位设计合并边界；最后用"stub 重定向 + 弃用警告 + 延迟下架"三阶段迁移保证零破坏升级。任何面临包数量膨胀、版本漂移的 Python monorepo，都可以参照这套流程制定自己的合并提案。

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