企业级 AI Agent 源码交付二次开发架构实战：核心编排引擎与业务插件解耦、依赖隔离及版本升级策略

【企业智能体平台微内核三层物理架构】

• 1. 核心运行时引擎（Core Runtime Engine - core/）：
  由交付源码提供，负责通用基础设施：LLM 统一推理接入网关、ReAct 思考与行动执行循环、上下文滑动窗口与压缩治理、安全审查与提示词注入防御（Guardrails）、分布式分布式链路追踪（OpenTelemetry）以及基础配置管理。此目录设定为只读基线，严禁写入任何特定客户或垂直业务代码。
• 2. 插件服务提供者接口（Service Provider Interface - spi/）：
  纯抽象接口契约层。定义了智能体平台允许外部扩展的所有标准规范，包括工具定义接口（BaseTool）、技能复合包接口（BaseSkill）、上下文注入器（ContextEnricher）、推理前后置拦截器（ExecutionInterceptor）以及知识检索适配器（RetrieverAdapter）。
• 3. 企业业务扩展包（Custom Extensions - plugins/ 或独立 Repo）：
  由企业自研团队维护的独立代码模块。企业内部的 MES 工单助手、ERP 采购经办、财务报销风控等专属业务逻辑全部在此层实现，通过实现 SPI 接口契约挂载到核心引擎，绝不逆向依赖核心内部私有实现。

# 文件位置：custom_plugins/erp_plugin/tools.py
from bxagent.spi.tools import BaseTool, ToolMetadata, ToolResult
from pydantic import BaseModel, Field

class PurchaseOrderQueryInput(BaseModel):
    # 采购单号参数定义，严格校验格式
    order_id: str = Field(..., description="企业标准采购订单编号，格式如 PO-2026-XXXX")
    include_items: bool = Field(default=True, description="是否包含明细行商品信息")

class PurchaseOrderQueryTool(BaseTool):
    # 工具元数据声明，平台自动提取并构建 JSON Schema 挂载至大模型
    metadata = ToolMetadata(
        name="erp_purchase_order_query",
        description="查询企业私有 ERP 采购订单状态与物料行信息",
        version="1.2.0",
        category="erp_integration"
    )

    async def execute(self, params: PurchaseOrderQueryInput) -> ToolResult:
        # 执行业务系统调用，内置异常熔断与鉴权上下文透传
        raw_data = await self.client.get_order(params.order_id)
        return ToolResult.success(data=raw_data)

[project.entry-points."bxagent.plugins"]
erp_tools = "custom_plugins.erp_plugin.tools:PurchaseOrderQueryTool"
audit_interceptor = "custom_plugins.erp_plugin.interceptors:FinancialAuditInterceptor"

【基于 Git Vendor Branch 的四步无冲突合流法】

1. 建立干净的只读供应商分支（upstream-vendor）：
   该分支永远只接收原厂官方发布的纯净版本标签（如 v2.1.0、v2.2.0-hotfix），严禁在此分支上提交任何企业本地业务代码。
2. 建立企业专属主干分支（main-enterprise）：
   基于 upstream-vendor 初始化。企业二次开发的新增插件代码全部放置于外部目录（如 custom_plugins/）或通过 Git Submodule 挂载。
3. 升级合并演练分支（upgrade/v2.2.0）：
   当原厂发布新版本 v2.2.0 时，首先从 main-enterprise 拉出临时升级分支：
   git checkout -b upgrade/v2.2.0 main-enterprise
git merge upstream-vendor/v2.2.0
4. 三路合并验证与合入：
   由于核心代码未被业务逻辑侵入，Git 可以完成 95% 以上文件的无脑快进或三路合并（3-Way Merge）。剩余极少数与 SPI 接口变动相关的改动，经由升级分支上的自动化测试流水线充分验证后，再正式合入企业生产主干 main-enterprise。

【企业 AI Agent 源码二次开发工程检查清单】

• 架构分层底线：确认业务定制代码未修改 core/ 目录任何文件；所有定制工具与技能均通过标准 SPI 接口实现。
• 依赖环境隔离：涉及老旧中间件或专有 SDK 的插件，必须使用独立进程或 Sidecar 容器运行，不得强制修改全局依赖配置文件。
• 代码版本控制：建立独立的 upstream-vendor 分支同步原厂官方 Release；主开发分支 main-enterprise 严格通过临时升级分支进行合并演练。
• 拦截审计接入：所有涉及写操作（如发起采购单、修改工单状态）的业务插件，必须挂载安全拦截器与幂等性校验，确保具有人工二次审批或不可篡改的日志留痕。
• 离线测试覆盖：插件工程必须自带 Mock LLM 与 Mock 外部 API 的独立单元测试用例，确保断网脱机环境下单测通过率 100%。
• 平滑演进与回滚：每个发布版本的业务插件均具备独立的语义化版本号（SemVer）；插件加载器支持故障插件的动态秒级热卸载，保障平台底座持续稳定。