备注鉴于之前写了一篇关于企业传统项目AI时代的架构演进我后续也一直在思考结合公司当前业务以及企业当前项目怎么基于机构演进进一步形成一套企业级底座规范。然后看了几篇技术文档说当前架构图都由AI画了那架构师该做什么我想我以这个系列文章进行答复主要还是怎么以架构思维让AI辅助来解决当前企业项目中存在的或者需要兼容且符合公司发展的技术优化和管理问题。系列整个有3-4篇文章进行迭代都是基于前一版基础上进行升级。最终实操并验证规范让AI开发一套完整的企业级底座项目。最后会开源放到github上。欢迎大家指正摘要当 AI Coding Agent 开始真正承担编码、测试与发布工作传统的给人看的架构文档正在失效。本文解读一套可执行的企业级架构规范它以五层架构为骨架以 API / SPI / Adapter 为约束机制以机器可读的 Architecture Contract 为执法依据让任何模型、任何 AI Agent 都能在同一套规则下完成从需求到发布的全链路工程活动。最终目标是——Human defines intent; AI executes engineering.关键词AI-Native 架构Enterprise FoundationAgent 治理Architecture as CodeAI Coding一、为什么需要一份可执行的架构规范过去十几年企业架构文档的标准结局是评审会通过、束之高阁、代码走样。根本原因在于这类文档的读者是人——而人的注意力是有限的约束是柔性的。但 AI Coding 改变了博弈结构。当编码者从人变成Agent约束方式必须随之升级对人靠 Code Review 和团队默契对 AI只能靠机器可读的契约 自动化的校验器。因此一份合格的企业级架构规范必须同时是三样东西Architecture Specification——说清楚系统分层与职责边界Engineering Contract——规定什么允许、什么禁止可被机器校验AI Implementation Specification——让其他团队、其他模型、其他 AI Coding Agent 无需口头交接即可直接执行。它必须回答一系列硬问题系统分几层、每层负责什么、第三方技术放在哪里、业务代码允许依赖什么、LangChain4j / Spring AI / AgentScope / MCP / Langfuse 各自是什么定位、AI 如何工作、如何测试监控审计、以及——如何让 AI 根据规范自动生成业务系统而不是自行发明架构。二、核心思想能力优先而不是 Provider 优先传统企业架构早已验证过一个模式CacheService统一 API ↓ Cache SPI技术替换点 ↓ Redis Adapter隔离 SDK ↓ Redis具体 Provider这套思想对 AI 架构完全适用且更为迫切ModelService统一模型 API ↓ Model SPI Model Router ↓ Qwen / OpenAI / Anthropic / Local Adapter ↓ 具体模型模型、Agent Framework、向量数据库、消息队列、缓存、云平台都只是能力的实现者而不是企业应用架构本身。这是本规范与直接把 LangChain4j / Spring AI / AgentScope 当作整个企业 AI 架构的根本区别。框架会过时、模型会涨价、云商会更换而能力抽象层应当屹立不动。当然规范也明确反对另一个极端不是为了架构漂亮给每个业务类都建 SPI。SPI 的存在理由是三件事——技术替换、平台治理、第三方隔离。每一条抽象都必须能回答我换得起吗、管得住吗、隔得开吗。三、总体架构五层划分整套体系划分为五层自底向上依次为基础设施、企业基础能力、AI 基础能力、横切平台与 AI 研发平台层级名称核心职责L5AI Dev Platform需求 / 架构 / 设计 / 任务 / 编码 / 测试 / Review / 构建 / 发布L4Cross-Cutting Platform安全、租户、治理、审计、可观测、策略、成本、韧性L3Enterprise AI Foundation模型、Agent、工作流、工具、MCP、知识、RAG、记忆、Prompt、评估、AI 可观测、AI 安全L2Enterprise FoundationWeb、RPC、认证、缓存、消息、存储、注册配置、调度、审计L1Infrastructure云、K8s、数据库、Redis、MQ、OSS、向量库、搜索、LLM Provider其中 L2 与 L3 是能力沉淀的主体。以 Java 生态为例Enterprise Foundation 由foundation-core、foundation-web、foundation-cache、foundation-mq等一系列独立模块构成Enterprise AI Foundation 则由ai-model、ai-agent、ai-rag、ai-memory、ai-evaluation等模块构成。所有第三方技术Nacos、Kafka、OSS、LangChain4j、Langfuse只允许以Adapter 模块的形式存在——例如foundation-adapter-redis、ai-adapter-langchain4j、ai-adapter-langfuse。值得强调的是foundation-*与ai-*的分工本质上是确定性与非确定性的边界L2 管确定性工程能力L3 管非确定性的智能能力而 L4 为两者统一施加安全、治理与成本约束。四、AI 能力的六个关键抽象规范对 AI 基础能力给出了明确的接口定义与依赖规则此处提炼六个最关键的抽象。4.1 Model业务代码永远看不到 LLM SDKpublic interface ModelService { ModelResponse chat(ModelRequest request); }ModelRequest至少承载model、messages、systemPrompt、temperature、maxTokens、tools、structuredOutput、streaming、metadata、traceContext、tenantContext。业务禁止直接出现OpenAIClient、DashScopeClient、AnthropicClient——Provider SDK 越过ModelService进入业务代码即视为架构违规。模型路由Model Router是平台能力而非业务负担按能力、成本、延迟、可用性、地域、数据等级、租户、Provider 健康状态选择模型并内置Primary → Fallback → Emergency三级链路。4.2 Agent 与 Workflow必须分开这是规范中最富实践色彩的判断之一。Workflow 是确定性的流程编排Agent 是非确定性的智能决策与执行两者不能强行设计成一个万能 Agent工作流适合查询客户 → 查询订单 → 调用 Agent → 人工审批 → 发送消息这类可预期路径Agent 适合Reason → Select Tool → Execute → Observe → Reason的循环决策。业务统一依赖AgentService接口由 Adapter 层对接 LangChain4j、SAA、AgentScope 或自研实现。Agent 自身至少具备Model、Instruction、Tool、Memory、Context、Policy、Trace、Approval、Timeout、Retry——其中 Approval 与 Policy 的存在决定了 Agent 能否进入生产环境。4.3 Decision独立于 Agent 的能力public interface DecisionService { DecisionResult decide(DecisionContext context); }Decision 可由规则、决策表、LLM、Agent 或外部规则引擎实现。规范给出的命题简洁而重要Agent 可以参与决策但 Decision 不等于 Agent。把审批流误建成 Agent 自由发挥是企业 AI 应用最常见的事故来源之一。4.4 Tool每一次执行都过闸Tool 统一为ToolService来源可以是 Java 方法、HTTP、RPC、SQL、MCP 或外部 API。无论来源执行链都必须经过Authentication → Authorization → Policy → Risk Check → Approval → Execution → Audit4.5 MCP是协议不是架构规范为 MCP 给出了冷静的定位MCP 是 AI Tool / Context 的标准化协议不是企业系统的统一 API。企业系统对外默认仍是 HTTPS REST OpenAPI JSONAI 与工具/上下文之间走 MCP。二者不是二选一而是各就其位。4.6 Knowledge / RAG / Memory三个容易混淆的概念RAG 是标准流水线Parse → Chunk → Embedding → Index → Retrieve → Rerank → Context → LLM业务统一依赖KnowledgeService、RetrievalService、EmbeddingService禁止直碰 Milvus、pgvector、ES SDK。而Knowledge ≠ MemoryKnowledge 是外部知识Memory 是 Agent / 用户 / 会话 / 任务的状态与历史分为会话记忆、语义记忆、任务记忆、Agent 状态与长期记忆五类。两者混为一谈是多轮 Agent 系统后期不可维护的主因之一。五、工程化配套Prompt、评估与可观测规范把三项软实践提升为硬要求Prompt 即资源。Prompt 必须具备 ID、版本、变量、Owner、状态与评估记录生产 Prompt 的修改要走 Draft → Testing → Evaluation → Approval → Production 的流水线而不是在代码里改个字符串直接上线。Evaluation 即门槛。AI 系统必须围绕正确性、相关性、 groundedness有据可查、安全性、工具调用准确率、格式遵从、延迟与成本建立评估且评估数据集必须版本化。没有评估的模型升级等价于盲飞。观测即承诺。在传统 Logs / Metrics / Trace / Audit 之外AI 系统必须增加 LLM Trace、Agent Trace、Tool Trace、MCP Trace、RAG Trace、Prompt、Token、Cost、Evaluation、Feedback 十个维度并以traceId → agentRunId → llmCallId / toolCallId / retrievalId / evaluationId串成统一链路。特别地Langfuse 被明确约束为 Observability SPI 的一个 Adapter而不是企业的业务 API——今日选 Langfuse明日换自建平台业务代码零改动。六、AI Coding规范如何约束 Agent这套架构的最终消费者是 AI Dev Platform。完整研发流程如下流程中有三个设计细节值得单独强调其一Unknown Must Stop。Requirement Agent 面对模糊需求时的行为准则是未知 → 不能猜 → 阻塞 → 询问 → 确认 → 继续。AI 绝不能以一般企业系统都是这么设计的为由自行决定业务规则。其二Human Approval 是硬关卡。设计文档未获批准WAITING_APPROVAL → APPROVED任务不允许流入 Coding。人的职责被重新定义为业务目标、业务规则、约束、验收与审批。其三Architecture Validator 是执法者。它以机器可读的 Contract 为准绳自动检查依赖方向、禁用 SDK、API/数据库契约、安全规则、Foundation 使用方式与测试覆盖。例如规范声明Domain MUST NOT depend on Redis那么 Domain 层出现RedisTemplate的那一刻构建即失败——架构约束从文档建议变成编译门槛。配套地规范要求架构契约必须机器可读# spec/architecture.yaml rules: domain: forbidden: [spring, redis, kafka, mysql] business: forbidden: [direct-llm-sdk, direct-vector-sdk] ai: required: [enterprise-ai-foundation]所有公共能力登记进 Capability Catalog名称、类型、接口、Provider、版本、状态。Coding Agent 新增能力前必须先查目录能复用就不重造确属公共能力才评估进入 Foundation。七、治理、安全与成本AI 时代的横切面规范将治理扩展到九个维度API、模型、Agent、工具、Prompt、知识、数据与成本治理并要求 AI 资源Agent、Model、Prompt、Knowledge、Memory、Tool、Quota、Cost、Evaluation、Observability全部按Tenant → Organization → User → Role → Permission隔离。AI 安全在传统 RBAC / ABAC / 租户隔离之上新增七类威胁建模Prompt Injection、Tool Abuse、数据外泄、未授权工具、未授权知识、上下文泄漏、租户泄漏、不安全输出。数据层面Prompt、LLM Output、Document、Memory、Tool 参数均可能属于敏感数据必须支持脱敏、加密、留存策略与访问控制——禁止无条件将所有 Prompt / Response 写入第三方平台。成本即一等公民Token、模型、Embedding、Agent、工具、租户、项目成本全量统计并可按租户、用户、应用、Agent、模型、工具、项目、环境八个维度下钻。AI FinOps 不是月底对账而是运行时配额与熔断的一部分。八、反模式清单十六条军规规范以负面清单的方式总结了最常见的架构错误每一条都对应着真实的企业事故巨型 Foundation Jarenterprise-all-in-one.jar一个万能 Agent包办一切用 MCP 取代全部 HTTP API4–6. 让 LangChain4j / SAA / AgentScope 成为顶层架构让 Langfuse 成为业务 APIProvider SDK 直接进入业务代码AI Dev Platform 作为业务运行时依赖行业业务规则进入公共 FoundationAI 自己猜业务规则只有 Markdown、没有机器可读 Contract没有 Architecture Validator编译成功就认为开发完成AI 私自修改架构所有能力过度 SPI 化。九、最终全景与落地路径最终架构全景如下依赖方向自上而下严格单向AI Dev Platform 生成 Business Application业务依赖 Enterprise Foundation、Enterprise AI Foundation 与 Cross-Cutting Platform三者之下是 SPI / Adapter 与 Infrastructure。任何一层都可独立替换实现任何 Provider 都可被拔出。落地分六个阶段推进先做foundation-core与ai-core契约、上下文、错误、链路再补齐 Web/RPC/缓存/消息等基础能力随后建设可观测与韧性继而交付模型/工具/Agent/RAG 等 AI 能力然后落地租户、策略与成本治理最后构建 AI Dev Platform。AI Dev Platform 的 MVP 也分三步走先跑通需求 → 设计 → 人工确认 → 任务拆分 → AI Coding → 校验再实现自动测试与自动修复闭环最终贯通需求 → 发布全链路。结语这套架构不是 Spring AI 架构不是 LangChain4j 架构也不是 AgentScope 架构——它是企业能力架构 AI 能力架构 治理与可观测架构 AI 软件工程架构。框架与模型只是能力的实现方式而规范本身行业无关行业业务订单、会计、保险、医疗、制造、税务规则永远构建于底座之上而底座只沉淀跨行业、跨项目、能力稳定、技术可替换的部分。当架构规范从给人读的 PPT进化为给 AI 执行的契约架构师的产出物也随之改变不再是图纸而是规则、校验器与能力目录。这可能正是 AI 时代软件工程最重要的范式转移——Human defines intent; AI executes engineering.本文基于《企业级 AI-Native 软件底座架构规范》整理撰写文中图示为规范核心机制的可视化重绘。