分解一座冰山：后端系统「AI 知识库体系」建设实践（长文干货）

在上一篇讨论《后端系统 AI Friendly 设计》时，文章开篇就强调过一个判断：后端系统要想真正进入 AI Friendly 状态，不能只停留在“代码写得清楚一点”、“README 多补一点”、“接口注释完整一点”这种层面。这些当然重要，但它们解决的更多是“人和 AI 能不能读懂局部代码”的问题，而不是“AI 能不能在一个复杂系统里做出正确的工程判断”。

真正的问题是：当 AI Agent 接到一个需求时，它到底知不知道这个系统的边界在哪里？知不知道哪些接口不能破坏兼容？知不知道这张表的某个字段虽然看起来没人用，但其实是下游离线任务每天凌晨要扫的？知不知道某个 MQ Topic 的 schema 不能随便改，因为三个历史服务还在消费老格式？知不知道某个模块虽然代码很旧，但它是交易链路里的关键兜底逻辑，动了之后不是单测过了就能上线？

这就是后端系统 AI Friendly 化真正麻烦的地方。

AI 不是完全看不懂代码，恰恰相反，今天的大模型读代码、解释代码、补测试、做局部修改，能力已经相当强了。问题在于，后端系统里的很多关键知识并不直接存在于代码中，或者虽然存在于代码中，但分散在不同仓库、不同配置、不同历史 PR、不同口头约定里。

人类工程师靠长期经验、团队沟通和线上事故记忆来补全这些上下文；AI Agent 没有这些“组织记忆”，它只能读取你明确给它的东西。

所以，“知识库怎么选”这个问题，表面上是工具选型，实际上是一个更底层的问题：我们到底要把哪些系统知识显式化，显式化之后又应该以什么形态交给 AI 使用？

如果只是为了新人 onboarding，一份自动生成的 Markdown Wiki 可能就够了。如果是为了跨服务影响分析、尤其是跨服务的技术方案设计，那就需要服务图谱、依赖关系、上下游调用链。

如果是为了让 AI 安全修改代码，那就还需要有明确的约束、红线、任务路由和验证标准。不同问题对应不同知识形态，不能混在一起讨论，更不能用一个“大而全知识库”幻想解决所有问题。

这也是本文想讨论的核心：后端系统 AI Friendly 化落地时，知识库怎么设计，如何有效利用这座知识的大山，挖出冰山藏在水下的 90% 部分，让 AI 从 coworker 真正走向 agentic operator。

2.1 为什么技术方案设计如此重要

在实践中反复面对的问题：无论是 CoWorker 形式的 AI Coding，还是 7x24小时AI 全自动规划的 Agentic Operator Coding ，在完整的研发流程中，技术方案设计是最关键的一环。方案质量直接决定了后续编码执行和交付的正确性。

这个判断可能看起来很传统。技术方案设计在没有 AI 的年代就很重要，这有什么新鲜的？新鲜之处在于：AI 时代放大了方案质量的杠杆效应，而且放大的倍数远超直觉。

一. AI 的执行速度放大了错误的传播速度：

一个人类工程师方向走偏，可能半天才写了几百行代码，拉个 PR 被同事 review 时就能被拉回来。损失可控。但一个 AI Agent 在错误方案的指引下，10 分钟可以完成一个涉及 5 个文件、3 个接口、2 张数据库表的完整变更。等你发现方向错了，回滚成本已经是人工编码的好几倍。更麻烦的是，这种错误往往不是语法错误，也不是单测一定能抓住的错误，而是“业务理解错了”“边界改错了”“兼容性破坏了”“下游影响漏了”。

二. AI 的默认行为是“忠实执行”，不是“质疑方案”：

给一个 senior 工程师一份有问题的需求，他会说“这里有矛盾”“这个方案会引入循环依赖”“你少考虑了并发场景”“这个接口以前不能这么改”。这种质疑能力是经验积累的结果。AI 当前不是完全没有质疑能力，它会在形式上指出一些明显的逻辑冲突，但对于那些需要系统全局理解才能发现的问题，比如“这个设计会导致下游服务超时”“这个字段看起来可删但其实影响离线对账”“这个状态机不能绕过人工审核”，它往往直接执行，而不是主动停下来质疑。

三. AI Coding 的核心价值是让 AI 处理执行细节。

但这个价值有一个隐含前提：执行方向必须正确。如果你把大量节省下来的编码时间，又花在 debug、回滚、返工、解释线上异常上，净效率提升可能趋近于零。很多团队反馈“用了 AI 好像也没快多少”，细究原因，往往不是 AI 编码能力差，可能在技术方案设计环节就没做好。AI 很高效地写了很多“局部正确但整体错误”的代码，最后人还是要花时间收拾残局。

2.2 技术方案设计强依赖知识库

所以，AI Coding 时代的技术方案设计，不只是“写一份方案文档”，而是要先让 AI 拥有足够准确的系统上下文，这个上下文就是知识库—— 完善的知识库建设。

知识库至少要能回答这些问题：

当前系统架构长什么样？模块怎么分？职责边界在哪里？这个需求涉及哪些上下游系统？接口契约是什么？改了会影响谁？数据库 schema 是什么？哪些字段有业务约束？哪些表之间有隐含依赖？有没有类似历史变更可以参考？上次改类似功能时踩了什么坑？什么是红线？哪些操作在任何情况下都不允许？

人类工程师靠经验、沟通和历史记忆来获取这些信息。AI 呢？它需要一个结构化的、精确的、可按需加载的知识来源。

此外，“业务元语”对应的已有技术链路、技术方案是什么，也是能够极大提升技术方案设计效率、准确性的输。我们管这一层叫做“业务层”，主要做业务与架构之间的转换、映射；

我们要做的不只是“让 AI 能看懂代码”，更需要“让 AI 在设计方案和执行变更时拥有正确、完整、可验证的系统上下文”。

这样就有两个问题显而易见：1. 知识库应该包含哪些内容？2. 知识库如何承载和加载？

2.3 知识库贯穿 AI Coding 全流程

在讨论「知识库 to 技术方案」之前，需要先把一个问题讲清楚：知识库并不是只在 AI 写代码之前用一下，也不是一个放在旁边、需要时搜索几段内容的 RAG 文档库。对于 AI Coding 来说，知识库应该贯穿从需求理解、现状分析、方案设计、编码执行、验证测试到 Review 交付的整个流程。

如果把 7x24小时的 AI/Agentic Coding 拆开来看，它其实不是“AI 自动写代码”这么简单。它至少包含几个连续动作：先理解需求，再识别业务概念，再找到这些业务概念对应的系统、模块、接口、表和消息；然后分析改动范围，判断影响哪些上下游；再形成技术方案，确定怎么改、改哪里、不改哪里；最后才进入编码、测试、Review 和交付。任何一个环节缺上下文，后面的执行都会变形。

• 在需求理解阶段：知识库帮助 AI 理解“业务元语”。比如需求里说“退款体验优化”“权益冻结”“履约异常补偿”“订单逆向链路”，这些词对业务同学来说是自然语言，但对 AI 来说，如果没有业务知识和业务到系统的映射，它只能按字面猜。它可能知道 refund 是退款，却不知道这个团队里的退款到底涉及订单状态、支付单状态、履约状态、财务对账、客服工单还是风控策略。业务层知识的价值，就是把这些业务词翻译成系统可以识别的技术对象和链路。

• 在现状分析和影响分析阶段：知识库帮助 AI 回到真实系统。一个需求到底改一个服务，还是改多个服务？是改接口，还是改状态机？是改同步链路，还是改异步消息？是否影响下游消费方？是否会破坏老版本客户端兼容？这些问题不能只靠 AI 看当前仓库回答。它需要架构层知识，需要服务依赖关系，需要上下游调用图谱，需要历史实践，也需要知道这个系统过去为什么这样设计。没有这些知识，AI 很容易做出“单仓库内看起来合理，但放到全链路里不合理”的方案。

• 在技术方案设计阶段：知识库的价值会被进一步放大。因为方案设计不是简单地列几个代码文件，而是要确定改动边界、数据流、状态流、兼容策略、异常处理、灰度方式和验证范围。这个阶段最怕的是 AI 给出一个形式完整但上下文错误的方案：文档看起来很像技术方案，里面也有接口、表结构、流程图和测试计划，但关键系统漏了，核心约束没提，下游影响没分析，历史兼容没考虑。这样的方案越完整，反而越危险，因为它会给后续编码执行制造一种“方向已经确定”的错觉。

• 在编码执行阶段：知识库不再只是帮助 AI “理解系统”，更是需要开始约束 AI “如何行动”。哪些目录可以改，哪些模块不能跨层调用，哪些字段不能删，哪些接口只能新增不能改语义，哪些状态流转必须保持幂等，哪些中间件使用方式必须遵守团队规范，这些都需要提前显式化。否则 AI 很容易写出功能上能跑、工程上却不符合系统规则的代码。

• 在验证测试阶段：知识库还要回答“怎么证明这次修改是安全的”。不同类型的改动，对应的验证方式不一样。新增 API 需要关注接口契约和兼容性；修改数据库需要关注迁移、回滚和历史数据；修改 MQ 消息需要关注生产者、消费者和重复消费；修改状态机需要关注主流程、逆向流程和异常分支。如果知识库里没有这些验证规则，AI 往往只会跑最容易跑的单测，然后给出一个“测试通过”的结论，但这个结论未必覆盖真正的风险。

所以，知识库在 AI Coding 里的角色，不应该被理解成“给 AI 搜索答案的资料库”，而应该理解成一套贯穿全流程的系统上下文。它既提供事实，也提供映射；既提供约束，也提供验证标准；既帮助 AI 理解业务和系统，也帮助 AI 在执行时不要越界。

更重要的是，知识库不是一次性输入，而应该形成闭环。每一次技术方案评审中发现的遗漏，每一次 Code Review 中指出的风险，每一次线上问题暴露出的隐性依赖，每一次历史兼容带来的特殊处理，都应该反向沉淀回知识库。否则知识库会很快变成一份“看起来完整、实际上过期”的文档，而 AI 最怕的不是没有上下文，而是拿到了错误的上下文。

因此，从 AI Coding 的角度看，知识库的作用贯穿全流程，但其中最关键的放大点，仍然是技术方案设计。因为需求理解、现状分析、影响分析、编码执行和验证测试，最终都会收敛到一个问题上：这次到底应该怎么改。技术方案一旦错了，后面所有高效执行都会变成高效返工。

那么知识库具体应该如何建设呢 ？具体目标是什么呢？

3.1 建设目标

知识库（knowledge base）在整个AI Coding 全链路中的建设目标，主要是基于其核心价值、影响范围来思考的，如果从典型的互联网架构思维来衡量的话，我认为主要有以下几个方面的指标可以用来衡量：

• 内容全面性：在做技术方案设计、AI Coding 的时候，知识库的内容是否足够全面。尤其面对后端有几十个微服务的前提下，知识库是否能反馈系统全貌，对于技术方案设计有非常大的作用。比如本来已经存在了一个微服务可以根据经纬度获取用户POI，如果知识库里漏掉了这一点，可能AI 就会重新设计开发一个同样的API；

• 内容准确性：知识库的内容准确性，在AI 时代已经被大幅提高了—— 大量的知识库都是依赖AI 生成，比人类自己的梳理提效了很多，准确性也提高了很多。但是仍然有一些痛点就是“技术元语定义重复”，比如“订单”—— 比如对于外卖系统来讲，用户创建的外卖单叫做订单，骑手接单的“配送单”也可以叫订单，二者本质上是两个不同实体。在提及订单的时候，到底是指哪一个订单呢？类似的歧义场景如何处理，也是很多时候落地要额外关注的。此外，在代码有变更后，知识库内容是否及时联动更新了，也是一个很重要的事情。

• 内容召回效率和质量：这个召回主要是指在技术方案调研、技术方案设计阶段，经常会涉及到跨多个代码仓库的知识召回等，这个时候召回准确率也和query 优化、召回引擎有很大关系。比如大模型的上下文窗口size 虽然有几百KB 甚至MB 级别，但实际上很多时候有效注意力往往集中在前几十个KB。

所以，知识库建设的目标需要紧密围绕上面几个方向展开。

3.2 知识库的分层设计

经过调研走访，我们发现很多团队在知识库建设层面、知识库做技术方案设计层面都有一些共性的挑战：

• 产品需求 to 技术链路转换瓶颈：产品的PRD 需求文档往往是以“用户界面”为切入点进行描述的，但是用户界面到后端API 还是需要一个转换过程—— 某一个界面请求了哪几个后端的关键API，分别用于渲染界面中的哪部分内容，这部分知识的缺失是阻碍“产品PRD文档 to 技术方案设计” 非常大的一个拦路虎；

• 跨越多层多系统时的系统事实与约束：在大型互联网项目中，往往一个用户请求要穿透多层后端微服务、对应每个微服务中也处理不同的逻辑。具体到本次需求，需要在哪一层的哪一个微服务中开发 —— 这就依赖大量的链路知识检索、架构约束、系统约束等知识。

• 知识检索增强RAG：大模型会话窗口 context length 是有限的，不可能把所有上下游系统的所有知识都放到一个context window 或者 session 中，也需要“按需加载”或者“只加载最相关的上下文” —— 大家经常用的 RAG 就是解决这一个问题的主要思路。在知识库的建设过程中，这个能力是基本能力之一。

• 单一系统内的知识全面性、抽象程度：在经历了上面几层业务转化、链路转化等过程之后，在实际的coding 阶段更依赖单一微服务系统内的知识库的质量。比如一个高质量的知识库，能够按照业界经典的DDD 或者三色建模法等经典方法论，把系统代码进行抽象，这除了解决优雅性问题以外，也能够把系统代码架构和约束、设计理念等大幅度可见，对AI coding 是非常有帮助的。

针对这些大家遇到的现状和问题，我们在设计和实践过程中，把知识库进行了分层，倾向于拆成如下四层：业务层、架构层、系统层、基建层。

3.2.1 业务层：让 AI 知道“为什么改”和“业务落在哪里”

业务层是最容易被技术团队低估的一层。很多人讨论 AI Coding，会直接从代码仓库、接口文档、数据库表开始，但真实的研发过程不是从代码开始的，而是从业务问题开始的。

业务层至少包含三类知识：业务知识、业务与架构映射、历史实践。

• 业务知识：解决的是“这个系统到底在服务什么业务”的问题。比如订单、支付、履约、权益、库存、风控、对账，这些业务概念分别是什么意思，有哪些核心规则，哪些状态变化是正常的，哪些操作是高风险的。如果 AI 只看代码，它也许能读懂 order_status 有几个枚举值，但它未必知道“已支付未履约”在业务上意味着什么，也未必知道某个状态为什么不能直接跳转。

• 业务与架构映射：解决的是“业务概念最终落在哪些系统、模块、接口、表和消息上”的问题。这一块非常关键，也是很多知识库最容易缺失的地方。一个需求说“优化退款体验”，听起来是业务需求，但落到系统上，可能涉及订单服务、支付服务、履约服务、客服系统、财务对账、消息通知、风控策略都有和退款相关的能力支持，退款操作的业务流程对应到技术系统，首先请求的API 是什么？对应的同步API 是什么？异步API 是什么？AI 如果不知道这些映射关系，就很容易把一个跨系统需求误判成单服务局部修改。

• 历史实践：解决的是“过去为什么这么做”的问题。比如对于一个平台化系统，每次做新的定制能力接入的时候，开发的代码基本都是类似的分层、类似的模块，用历史实践的方式沉淀技术方案，给AI 作为参考，针对同类问题就可以很高效的产出技术方案、降低技术方案的影响风险等。比如还有很多后端系统里都有一些看起来不优雅的设计：一个多余的字段、一段兼容老逻辑的代码、一个特殊的兜底判断、一个不能删除的 MQ 消费分支。新人容易觉得它脏，AI 更容易觉得它可以被重构掉。但这些东西背后可能是历史事故、灰度兼容、老版本客户端、下游依赖、合规要求或者业务妥协。

这也是为什么我觉得业务层里的“业务与架构映射”和“历史实践”值得重点标出来。它们往往不在代码里，不在自动生成文档里，也不在接口定义里，但它们直接影响技术方案设计是否正确。

3.2.2 架构层：让 AI 知道“系统之间怎么协作”

架构层解决的是系统之间的分工、调用、依赖和治理问题。它包括 架构 / 分层 / 链路事实、架构约束、服务治理。

架构 / 分层 / 链路事实，回答的是“系统怎么组织”的问题。比如一个业务链路从网关进入后，会经过哪些服务；每个服务负责什么；哪些是核心链路，哪些是旁路链路；哪些模块属于领域层，哪些属于应用层，哪些只是适配层；哪些接口是同步调用，哪些是异步消息；哪些数据是强一致，哪些数据允许最终一致。

• 架构知识/事实：对技术方案设计非常重要。因为 AI 如果只看当前仓库，很容易出现“局部最优”的方案：在当前服务里改起来很顺，但放到整体链路里就不合理。比如某个逻辑应该在订单服务里做，AI 却改到了网关层；某个校验应该靠领域对象保证，AI 却散落在多个 Controller 里；某个异步链路应该通过 MQ 解耦，AI 却新增了一个同步 RPC 调用。这些问题不是代码能力问题，而是架构上下文不足。

• 架构约束：回答的是“系统设计上不允许怎么做”的问题。比如核心链路不能新增强依赖，交易链路不能引入不稳定外部服务，某些接口只能由聚合服务调用，某些服务不能反向依赖上游，某些数据只能通过领域事件同步，不能跨库直查。架构约束和代码规范不一样，它约束的是系统之间的关系和依赖方向。

• 服务治理：更偏运行时和组织治理。比如服务等级、超时配置、重试策略、熔断降级、限流规则、接口负责人、依赖 owner、SLA、灰度策略、监控告警。这些信息不一定直接影响代码怎么写，但会影响方案能不能上线、风险是否可控、出了问题能不能快速定位。

从选型角度看，需要有一个架构层来理解系统之间的关系，比如通过服务图谱、上下游依赖、接口调用、项目元数据，帮助 AI 和工程师回答“改这个服务会影响谁”“有没有现成能力可以复用”“这个接口被哪些上游调用”。这类知识不是普通 CodeWiki 最擅长的，因为它跨越了单个仓库，需要从微服务生态里看关系。

所以，架构层的核心价值不是解释代码，而是帮助 AI 做影响分析和服务寻址。它决定了技术方案设计的前半段是否靠谱：需求到底应该改哪些系统，影响哪些上下游，边界应该切在哪里。

3.2.3 系统层：让 AI 知道“这个服务内部怎么改才安全”

系统层是单个服务内部最核心的 AI Friendly 知识层。它包括 系统事实、系统约束、验证 / 测试。

• 系统事实：解决的是“这个服务内部有什么”的问题。比如模块划分、核心领域对象、主要 API、数据库表、缓存 Key、MQ Topic、定时任务、核心流程、状态机、配置项。这些信息是 AI 理解单个仓库的基础。没有系统事实，AI 就只能在代码里临时搜索，看到哪改哪，很难形成完整判断。

• 系统约束：解决的是“这个服务内部什么不能随便改”的问题。比如 public API 字段不能删除，数据库字段只能新增不能改语义，某个状态机流转必须经过特定校验，某个历史兼容逻辑不能删除，某个模块禁止大规模重构，某些目录只能通过适配层访问，某些写操作必须保证幂等。系统约束是 AI Coding 中最关键、也最容易缺失的知识。

• 历史实践：在单个系统内，历史做某一类型的需求，主要使用什么方案，这对AI 做技术方案设计有非常大的参考意义。在事实层面，和“业务层”的历史实践是一样的意义，只是辐射的scope 不同；

• 验证 / 测试：解决的是“怎么证明改对了”的问题。很多 AI 修改代码的问题，不是完全不能跑，而是验证方式太弱。新增接口要不要契约测试？修改数据库要不要迁移验证？改状态机要不要跑核心流程用例？改 MQ schema 要不要验证生产者和消费者兼容？改缓存逻辑要不要验证穿透、击穿和失效策略？这些都需要明确。否则 AI 很可能只跑了几个单测，就以为任务完成了。

这一层里，CodeWiki 和 service-knowledge-generate 都有价值，但侧重点不同。

CodeWiki 更适合生成和维护系统事实。它能低成本把项目概览、模块说明、API、数据模型、核心流程自动整理出来，帮助人和 AI 快速理解系统。

service-knowledge-generate 更适合把系统约束和验证规则结构化。它不只是告诉 AI “这个系统是什么”，还要告诉 AI “面对某类任务必须读哪些上下文、哪些地方不能动、做完以后必须怎么验证”。所以它不是 CodeWiki 的简单替代，而是更偏 AI 执行阶段的约束型知识库。

这也是为什么图里把“系统事实”和“系统约束”放在一起重点标出来。单个服务内部的 AI Friendly 化，最关键的不是把所有代码都解释一遍，而是把“事实 + 约束 + 验证”这三件事组织好。AI 只有知道系统事实，才能理解怎么改；只有知道系统约束，才能知道不能怎么改；只有知道验证方式，才能证明改动是安全的。

3.2.4 基建层：让 AI 知道“底座规则是什么”

基建层是很多文章里容易被一笔带过的部分，但在后端系统里，它其实非常重要。它包括 中间件知识、代码规范约束、工程规范等。

• 中间件知识：对于常见的 Redis、Kafka 等中间件基础使用知识，当前很多大模型都已经进行了内化，所以这些开源或者行业标准级别的中间件知识不太需要放到知识库中。这里知识库中的中间件知识指的是团队如何使用数据库、Redis、Kafka、RocketMQ、ES、配置中心、注册中心、任务调度、对象存储、日志监控等基础设施。这里不只是“Redis 是什么”“Kafka 怎么用”这种通用知识，而是本团队、本系统里的使用约定。比如 Redis Key 怎么命名，缓存过期时间怎么设，是否允许缓存空值，MQ Topic 命名规则是什么，消息是否要求幂等，数据库分库分表规则是什么，大字段能不能进主表，慢查询阈值是多少。

• 代码规范约束：解决的是“代码应该按什么方式组织”的问题。比如分层结构、命名规范、异常处理方式、日志规范、DTO / DO / Entity 的边界、依赖注入方式、事务边界、单测目录、Mock 方式。这些知识看起来比较底层，但它直接影响 AI 生成代码是否符合团队风格。如果没有这层约束，AI 很容易写出“功能能跑，但不像这个团队写的代码”。

• 工程规范：内容更广，包括依赖管理、发布流程、配置变更、灰度要求、安全扫描、监控埋点、报警规则、回滚策略等。这些东西可能不在业务代码里，却决定了代码能不能安全上线。对于这部分建设，不同规模的互联网公司或者软件公司可以有自己的适配标准。大型互联网公司对于稳定性、标准化要求高并能够适度接受迭代效率的降低，则规范类要求会更强更多；而中小型互联网公司对于业务迭代效率要求更高，反而在稳定性、标准化要求可能会更低，则工程规范类要求可能相对偏少。选择适合自己企业、业务复杂度的建设标准即可。

基建层的价值在于，它给 AI 提供工程底座。AI 不是只要写出业务逻辑就算完成任务，它写出的代码还要符合团队工程习惯，符合中间件使用方式，符合发布和运维要求。尤其是在大型互联网系统里，很多线上问题并不是业务逻辑错了，而是超时、重试、缓存、消息幂等、数据库性能、日志监控这些底座规则没处理好。

4.1 Ontology 本体论

在我们做知识库方案调研的时候，首先去了解了一下业界比较前沿或者在AI 领域比较领先的企业方案。

Palantir 推崇了  Ontology （本体论）的方法论，如下图。

更多内容可见 Palantir 官网对于 ontology 的一些论述设计： https://www.palantir.com/docs/foundry/ontology/overview 

注：此配图来自 Palantir 官网

Ontology（本体）的概念并不新，几十年前就有了，也不是软件工程独有，主要是用来定义领域知识的体系化描述的。在软件工程/AI 领域指对特定领域概念、属性及关系的形式化、显式且可共享的规范说明，是构建知识图谱、实现机器推理与语义互操作的“语义骨架”；在哲学中则指研究“存在本质”的分支学科（本体论）。

核心定义与内涵

• 本质：共享概念模型的形式化规范说明（Formal explicit specification of a shared conceptualization）。

• 四大特征：概念化（抽象领域结构）、明确性（消除歧义）、形式化（机器可读）、共享性（群体共识）。

• 构成要素：类（Class）、属性（Property）、关系（Relation）、公理/约束（Axiom/Constraint）、实例（Instance）。

• 哲学 vs 计算：大写 Ontology 常指哲学“本体论”；小写 ontology 在 IT 语境下特指“知识本体”，侧重工程落地 。

本体与知识图谱的关键区别

主要应用场景

• 语义网与数据集成：统一多源异构数据标准，解决“同名异义”或“同义异名”问题 。

• AI 智能体与决策：为 LLM 提供可解释的业务逻辑框架，支撑从“概率猜测”到“确定性执行”的跨越（如 Palantir Ontology 可直连业务系统执行动作）。

• 知识工程：作为知识图谱的底层schema，指导数据抽取、清洗与推理规则构建。

• 行业标准：用于自动驾驶（如 OpenX）、医疗、金融等领域的标准化描述与互操作 。

主要定义

Ontology 经常被描述为「企业数字孪生」，但这个说法太大，也太容易让人误解。更准确的理解是：Ontology 定义了一种协议，让系统把自己的业务对象、属性、关系、动作和权限，以统一方式暴露出来。

它的核心要素可以拆成四类。

一、 Data：每个系统贡献自己的数据，映射为 Ontology 中的对象、属性和链接。比如订单是对象，订单金额、支付状态、创建时间是属性，订单和用户、商家、履约单之间的关系是链接。

二、 Logic：业务规则、模型、算法、计算逻辑可以绑定到对象上。AI 不只是看到“订单”这个对象，还能知道围绕订单有哪些计算能力，比如风险评估、库存预测、履约优化等。

三、 Action：决策执行被建模为原子化操作，支持模拟、审批和写回。也就是说，Ontology 不只是让 AI 读系统，而是让 AI 知道这个业务世界里“可以做哪些动作”。

四、 Security：权限不是事后补丁，而是和对象、属性、动作绑定在一起。不同人、不同 Agent、不同场景下，能看到什么、能改什么、能执行什么动作，都应该有动态权限控制。

Ontology 的本体思想还是非常经典的思想：如果每个系统都按同一种结构暴露自己的能力，那么跨系统发现、组合、编排就从一个私有 API 适配问题，变成了标准化建模问题。

传统 API 文档告诉 AI：“这个接口怎么调”。

Ontology 更进一步告诉 AI：“这个业务世界里有哪些对象，对象之间有什么关系，对象上允许做哪些动作，动作执行前需要满足什么权限和约束。”这就是它和普通 Wiki 最大的不同。Wiki 偏解释系统，Ontology 偏建模系统；Wiki 偏阅读，Ontology 偏行动。

4.2  KBase （ Code Wiki ）平台

KBase  是阿里集团内部的中心化代码知识 CodeWiki 平台。调研下来，它的核心能力：给一个代码仓库，用 AI 自动生成一份全面的 Markdown Wiki，并且可以自己定义生成时机、生成内容等。

它的运作方式大致是：选择仓库和分支，触发生成，支持 monorepo 子目录；AI 分析代码后输出 Markdown 页面（LLM Wiki），包括项目概览、模块划分、核心流程、API 说明、数据模型等；代码推送后可以增量更新，变动较大时降级为全量更新；通过 MCP 工具提供 AI 访问能力；同时支持 BM25 和语义向量两种搜索方式。

从存储形态看，CodeWiki 通常在云端平台，与代码仓库解耦。它独立生成、独立更新、独立存储。格式是 Markdown 自然语言，人机双用，人能读，AI 也能用。

这类工具的现实价值也比较大，尤其是在新人 onboarding、跨团队协作、陌生系统理解、快速概念定位这些场景里。

新人入职第一天，如果能看到一份自动生成的系统概览，至少不用完全靠“找人问”和“翻代码猜”。跨团队协作时，需要了解一个陌生服务，也不用先约对方团队开会，搜一下 CodeWiki 就能拿到基本答案。要找某个业务概念在哪实现，语义搜索通常比手动 grep 效率高得多。

CodeWiki 最大的优势是零成本接入和自动维护。对很多团队来说，只要仓库有代码可读权限，就可以生成一份基本可用的系统 Wiki。你不需要额外组织人力，也不需要工程师专门维护文档。对于“想让系统变得 AI Friendly，但暂时没有额外人力投入”的团队来说，这是非常现实的第一步。

但从 AI Coding 的角度看，CodeWiki 默认的生成策略也有一些结构性限制。

一、自然语言的解析：在AI 执行过程中确定性不如结构化数据。当 AI 需要做判断，而不只是理解时，从一段 Markdown 中提取隐含约束的准确率，通常低于从 YAML 字段里直接读取。比如“这个接口不能修改字段语义”，写在 Markdown 里是一句话，写在结构化 policy 里则可以变成明确规则。

二、云端存储可能存在一致性延迟：如果开发者刚提交了 breaking change，AI 在更新窗口内基于过期 Wiki 做决策，就可能产生问题。对于普通理解场景，这个问题不一定严重；但对于自动修改代码和生成方案，这个延迟需要拉齐到完整的AI coding 生产历程中进行评估。当然，这也是云端代码知识库都会遇到的一个现实挑战。

三、对业务定制支持偏弱： 从了解来看，CodeWiki 的核心定位是“代码即事实”，所以主要是尊重代码事实，因此开放的业务定制能力偏弱。

4.3 知识检索平台

在实际调研中，发现多个团队有独立建设自己的“知识检索引擎”、或基于 kbase 的 RAG 能力做了本地 agent 检索增强。主要用在以下几个方面比较多：

一、需求调研：尤其在大型互联网公司系统架构比较复杂，链路深度比较大的的时候，一个需求到底涉及到多少个系统，哪些能力在哪些系统里是已经具备的。比如针对一个打车系统，司机接单这个操作到底经过了几层系统、几层风控、每一层系统分别做了什么能力和策略或者拦截？如果想加一个新策略加到哪一层的哪个系统合适？对于新员工熟悉系统，也比较有价值。

二、技术方案设计和工作量评估：与需求调研类似，在针对产品需求的技术方案设计、工作量评估的时候也同样涉及到对上下游系统、链路、性能等进行了解和穿透调研。一个需求涉及到的系统改造半径，对应的改造风险、工作量评估，往往也需要链路上各种系统事实知识。

三、线上问题排查：如在前文《后端系统 AI Friendly 设计》提到，在将来严谨意义的 7x24 小时场景下，大部分的线上报警排查、分析、处理也都会AI 化。AI 处理和排查的时候同样需要跨系统、串通完整链路的系统知识，比如从网关入口、到实际的API 层微服务、到下游领域服务、到中间件RT 情况等等。对应的agent 需要在具有全面的系统架构事实、runtime 事实的前提下，才能做出具体的问题分析和预警干预处理。

针对知识检索需要的系统链路、架构事实部分，集团的Aone（CI/CD平台）、监控报警平台等都有对应的 MCP 能力可以支持调用，同时再以 Code as Wiki、 API as Wiki/SKILL、到 Architecture as Wiki 等知识进行辅助，梳理清晰的系统现状是相对简单的事情。

更实用的其实是检索能力平台化，我们也看到有一些不同的团队都针对检索能力做了自己的定制，比如下文的 aitom 等。

经过上面的系统性分层设计，以及解决方案调研，接下来就是各层知识库的落地阶段。

5.1 业务层

在上文第3节中已经聊到了业务层的主要作用、设计思考和思路，具体在落地实践的过程中，具体要落成什么样子呢？

这里提供一个我们的实现示例，可以供大家参考。

业务知识库不应只是业务文档的集合，而应该帮助 AI 完成从产品需求、业务场景到技术链路的转换，使 AI 能够理解业务元语、识别业务边界、定位相关系统，并在技术方案设计过程中获得必要的历史经验和设计约束。

围绕这一目标，我们将每个业务 Business 的知识库划分为几个主要部分：

business/├── index.md├── meta/│   └── index.md├── principle/│   ├── index.md│   ├── timeout.md│   ├── idempotency.md│   ├── consistency.md│   ├── degradation.md│   └── compatibility.md├── scenario/│   ├── index.md│   └── scenario-*.md├── practice/│   ├── index.md│   └── practice-*.md└── history/    └── history-YYYYMMDD.md

根目录的 index.md
作为全局入口和索引文件，用来对内容进行 general 介绍和 indexing；

meta 用于存储领域内的业务元语、核心业务对象、概念边界和关键业务规则。例如，在订单领域中，需要明确“交易订单”“支付单”“配送单”等概念分别代表什么，它们之间是什么关系，以及哪些概念虽然在日常沟通中可能都被简称为“订单”，但在技术设计中不能混用。

业务元语数量通常不会特别多，因此初期可以集中维护在 meta/index.md 中。为了便于 AI 精确引用和检索，每个业务元语应具有稳定的名称或标识，并说明其定义、别名、非同义词、业务边界、关联概念和核心规则。当领域逐渐复杂、单文件内容过大时，再进一步拆分即可。

principle 用于存放当前领域中跨多个业务场景复用的核心设计原则。它描述的不是某一个具体页面或接口的调用链，而是架构师在该领域设计系统时需要长期坚持的关键考虑，例如：

• 全链路超时预算如何分配；

• 多系统之间采用何种一致性与补偿策略；

• 哪些链路允许降级，哪些链路必须失败；

• API、消息和状态语义如何保持向后兼容；

• 核心链路和旁路链路如何划分；

• 状态聚合和展示状态应遵循哪些原则。

例如，对于订单列表页和订单详情页，商品图片、营销标签等信息可能允许降级，而订单主体信息通常属于不可降级的核心数据。这类原则如果分别写在每个场景中，不仅会造成重复，也容易在长期维护中产生不一致。因此，将其抽象到 principle 中，再由不同场景进行引用，更有利于保持领域设计的一致性。

需要注意的是，principle 只承载当前业务领域特有、跨场景复用的设计原则。数据库、Redis、MQ、日志、发布流程等公司或团队级通用规范，仍应主要沉淀在基建层，避免每个业务 Business 重复维护一套相同知识。

scenario是业务场景与技术链路转换的核心目录。这里的场景主要从用户、产品或业务视角出发，例如订单列表页、订单详情页、退款详情页、提交订单页，或者一个不依赖具体页面的完整业务使用场景。

每个场景首先描述其业务目标、使用者、展示内容和业务边界，然后继续拆解场景中的具体功能和用户操作。例如，订单列表页可能包含：

• 查询和展示订单列表；

• 点击进入订单详情；

• 删除订单；

• 再次购买；

• 申请退款。

针对每一项操作，场景文档需要继续描述：

• 业务语义；

• 前置条件；

• 客户端请求的 API；

• 网关和聚合服务入口；

• 内部领域服务调用链路；

• 涉及的下游系统；

• 数据变化；

• 同步和异步事件；

• 异常、降级和补偿方式；

• 关联的 meta、principle 和历史实践。

例如，“删除订单”在产品界面上只是一个按钮，但在业务语义上可能并不代表物理删除订单数据，而是将订单从当前用户的订单列表中隐藏。因此场景文档需要明确：客户端请求哪个 API，订单服务如何校验订单归属和订单状态，是否需要查询退款及履约状态，最终修改的是订单主表还是用户与订单的展示关系，以及客服、对账和离线数据是否仍然可以查询该订单。

通过这种组织方式，scenario 实际上建立了一条从产品界面和用户操作到后端技术实现的转换链路：

产品页面或业务场景    ↓页面功能和用户操作    ↓业务语义与前置条件    ↓客户端 API    ↓网关或聚合服务    ↓内部领域服务    ↓下游系统、数据与消息

scenario/index.md 作为场景入口和路由索引。当场景数量较少（比如少于20个场景）、内容较轻时，可以将多个场景直接维护在一个文件中；当场景数量增加，或者某个场景需要频繁更新、被独立引用、具有独立 Owner 时，可以拆分为单独文件，由 index.md 维护场景名称、业务关键词、核心功能和文档链接。

这里不建议将“20 个场景”理解为严格的拆分标准。数量可以作为一个简单参考，但更重要的判断依据是文件大小、内容复杂度、更新频率和独立引用需求。

practice 用于记录历史设计和历史实践。它关注的不只是“过去做过什么”，更重要的是解释“过去为什么这样做”“哪些经验可以复用”“哪些坑不能再踩”。

实践内容可以包括：

• 某类需求的标准改造模式；

• 某次重要架构或业务决策；

• 历史兼容设计；

• 线上事故暴露出的隐性约束；

• 某类需求通常会影响的系统范围；

• 某种方案适用和不适用的条件。

例如，在新增一种订单状态时，历史实践可能提醒 AI：除了修改订单服务状态机，还需要检查客户端状态映射、客服系统、消息消费者、离线数仓和对账逻辑。实践知识的价值不只是提供一个可以复制的旧方案，而是帮助 AI 判断某个历史方案在当前场景下是否仍然适用。

history 用于记录知识库自身的生成和变更历史，例如某一天由谁、通过哪个 Skill、基于哪些资料生成或更新了哪些文件，经过了谁的审核，以及当前还有哪些未确认事项。

需要明确区分 practice 和 history：

• practice 承载对未来技术方案仍有指导意义的业务和架构知识；

• history 只记录知识库本身何时、由谁、以什么方式发生了变化。

history 中保存的应该只是 log 而不是具体知识本身。

在具体文件格式上，我们倾向于使用带索引结构的 Markdown。Markdown 对产品、业务、研发和架构师都比较友好，也便于人工审核和持续修正。同时，可以在文件头部增加 YAML Front Matter，用于描述文档 ID、类型、领域、Owner、状态、更新时间和关联对象等结构化信息。

例如：

---id: scenario.order-list-pagetype: business_scenariodomain: orderowner: order-domain-teamstatus: verifiedrelated_meta:  - trade_orderrelated_principles:  - timeout  - degradationupdated_at: 2026-07-15---

正文继续采用 Markdown 描述业务背景、流程、调用链和设计考虑。这样既保留了文档对人类的可读性，也为 AI 检索、路由、过滤和按需加载提供了必要的结构化信息。

从整体关系来看，可以将这几个目录理解为：

meta定义业务世界中有哪些概念，这些概念分别是什么意思scenario定义具体业务场景如何运行，以及业务操作如何转换为技术链路practice定义历史上类似问题如何处理、为什么这样处理，以及有哪些经验教训principle定义该领域跨场景需要长期遵守的核心设计原则history记录知识库自身的生成、审核和变更过程

以上结构是我们结合实际业务层知识库建设过程，给出的一种参考实践。主要是对业务知识、业务与架构映射以及历史实践三类内容的设计思考，但并不意味着这是一套需要所有团队强制遵守的标准。

不同团队的业务复杂度、文档体系、系统架构和 AI Coding 工作流都不相同。有的团队可能更适合以页面场景组织知识，有的团队可能更适合以用户旅程、业务流程或业务能力组织；有的团队会将 Markdown 存放在代码仓库中，有的团队则更适合存放在中心化知识平台中。

因此，这里的目录结构、文件命名和拆分方式，更多是一种可落地、可讨论、可持续演进的实践示例。团队可以直接参考，也可以结合自身情况调整，并持续提出改进建议。真正重要的不是目录名称是否完全一致，而是业务层知识能否帮助 AI 准确回答以下问题：

• 需求中的业务概念是什么意思；

• 当前需求发生在哪个业务场景；

• 页面功能和用户操作对应哪些后端 API 与系统链路；

• 技术方案需要遵守哪些跨场景设计原则；

• 历史上类似问题如何处理，曾经发生过哪些风险；

• 当前知识是否经过确认，能否安全地作为 AI 行动依据。

只要能够持续提升这些问题的回答质量，业务层知识库的建设就产生了实际价值。

这一层知识在平台化存储和检索能力实现实现层面，我们目前使用 kbase 承载。主要是方便人为编辑、人工查看和干预。按照“分领域知识库”的维度来进行组织和维护，比如手车互联、驾车导航、停车推荐等等关联度比较低的场景，分别维护自己的知识库。

5.2 架构层 （aitom平台）

这一层，我们采用的是 aitom 平台：https://aitom.amap-inc.com/

aitom 是高德出行后端团队，面向AI Native 时代打造的 AI 平台型基建， aitom 最关键的价值有三个（更多能力持续扩展中）：

一、服务能力的 Skill 化：

把每个后端服务的对外接口包装为 AI 技能。每个 Skill 包含一组相关 API、接入指南、质检文档。AI Agent 安装技能后，就可以通过自然语言调用对应服务能力。这和 Ontology “把能力结构化暴露”的思路是一致的，只是粒度更接近后端服务和接口，而不是完整企业级业务对象体系。

二、服务间调用图谱：

通过 aitom graph  可以查看任何项目的上下游依赖：谁调了我，我调了谁，用什么协议，是 HTTP 还是 HSF，具体哪个接口，超时时间多久。这一点很关键。很多技术方案设计最怕的不是不知道怎么改代码，而是不知道改完影响谁。有了服务图谱，影响分析就不再完全依赖人肉问同事。

三、架构约束：

这部分是我们正在扩展的能力，就是对于跨多个后端系统的技术方案调研、技术方案设计来讲，除了要有架构知识以外，还要有架构约束。 架构约束可以指定核心链路有哪些、系统分级和链路分级是什么，哪些系统是高危系统改动前需要人工确认等等。

aitom 把我们各个领域、跨领域的几百个微服务，以及链路比较清晰的进行了知识化治理，并建立了比较强大的检索能力，非常方便大家做需求调研、技术方案调研阶段，进行检索、熟悉不同的后端系统以及对应系统职责、领域边界等等。

甚至aitom 也在深入系统内部，把核心的 DTO 和 Index 能够暴露出来，某种程度来讲，相当于某种程度上起到了Palantir ontology 的 OSDK 作用。

从我们的调研和走访来看，这一层检索能力，是大家的刚需，每个团队基本都有自己的解决方案和建设。

也有一些团队采用集成 kbase 搜索，自己本地做cache 或者增强的方式实现。

5.3 系统层  service-knowledge-generate

在这一层的实践上，其实我们花了很多功夫，有一个非常重要的考虑就是“微服务的系统知识库不能只是Code Wiki”，单个系统的知识库，需要对系统内部实体事实、API 事实、安全约束等等……各方面进行清晰的定义和描述，这是指导 AI Coding 阶段最重要的细节知识。

5.3.1 问题和挑战

站在软件行业和互联网后端微服务开发的角度来看， 有没有统一的一种标准来构建这种知识库呢？

我们发现当前市面上的大多数工具都是以CodeWiki （LLM Wiki 生成）为主，而且产出物大多数是 Markdown 文件为主。

我们认为理想的这款知识库工具应该具备如下目标：

• 标准化：

1. 行业标准化：我们需要一套站在行业的高度和角度能够有行业普适的、行业相对容易认可的标准化方案。在语义层面看来，这种“共同语言”既有利于人类工程师理解，也有利于大模型理解—— 毕竟大模型本身也是基于人类知识进行蒸馏的能力。无论从产出物的结构、产出物的内容形式等方面，都要考虑“行业标准化”的问题。

2. 团队标准化：每个工程师按自己的理解写一份“AI 知识文档”。有人写 Markdown 长文，有人写 JSON，有人在代码注释里堆信息，有人在钉钉文档里维护接口说明，有人在 README 里写红线。结果是什么？每个 AI Agent 或 Coding 工具都需要针对每个项目单独适配。团队换人后没人知道知识库组织逻辑。AI 工具链无法复用，这个仓库的知识格式和那个仓库完全不同。没有统一完成标准，也不知道知识库建到什么程度算“够了”。这在早期探索阶段可以接受，但如果 Agentic Coding（7x24小时的自动化Coding） 要大规模落地，一定会带来比较大的额外成本。

• 不同规模的系统的适配：这其中涉及到另一个问题，就是不同规模的微服务差别比较大。中小规模的微服务可能只有100多个程序文件，3万行左右代码；而大型微服务通常会有300-700个程序文件，代码也往往在5万行以上。针对不同代码规模、不同业务规模的系统，这个工具需要都能比较好的适配；

• 人工干预和校验能力：尤其对于“约束”部分，在我们的实践中发现当前大模型已经足够强大，能够根据业务语义、代码语义、fanout 等维度比较好的识别出来一些高危代码和分层。但是有一些比如公司隐形约束、监管需求等，仍然需要人工去进行约束和干涉。所以，具体的产出物本身应该也为“人工干涉/校验”保留一定的入口和扩展性能力。

• 大模型友好 AI Friendly，这里分为两个方面：

1. 大模型生成友好：这里有一个典型的问题就是“记忆压缩处理”容易造成知识遗漏。经常用大模型的同学都知道，一个大模型对话窗口能够接收的会话大小是有限的。当输入内容过多的时候，很容易触发“记忆压缩”，而记忆压缩就意味着会话有损，如何保障在知识库生成的过程中，即使记忆压缩也不会导致输出结果受损呢？

2. 大模型使用友好：目前大多数code wiki 级别的产出都是以自然语言markdown 文件为主，这种文件本身的结构性相对是比较差的，往往需要大模型去做结构化提取和理解。通过对 palantir ontology 相关方法论的一些调研和实践，我们发现 palantir 推荐的 YAML 格式（或者 TOML 文件）对大模型还是比较友好的，所以我们也倾向于在后续知识库中采用类似的文件格式。

5.3.2 知识库的设计思路和方法论思考

基于以上调研和业界方法论思考，我们研发了自己的知识库生成SKILL： service-knowledge-generate 

service-knowledge-generate 的结构并不是凭空发明，它背后其实综合了多个成熟的软件工程方法论。

• 领域驱动设计：也就是 DDD，体现在 object 目录里。核心领域对象、聚合根、值对象、生命周期、不变量，都应该被显式记录。对于后端系统来说，领域对象不是普通数据结构，它承载了业务约束。比如订单、支付单、履约单、账户、权益、库存，这些对象的状态和流转规则往往比接口本身更重要。

• 微服务架构原则：体现在 system、api、downstream 这些目录里。服务边界必须清楚，系统要声明“我是谁、我负责什么、我不负责什么”。API 契约要显式化，不能只靠代码签名。下游依赖也要显式管理，否则 AI 很容易只看到当前仓库，看不到外部影响。

• 实体建模与状态机：体现在 object 文件的状态流转里。核心实体的状态机是系统中最高风险的部分之一。状态从 created 到 paid，再到 fulfilled、cancelled、refunded，每一次流转都可能有前置条件和副作用。如果 AI 不理解状态机，只按局部代码改，很容易引入绕过校验、重复执行、状态不一致等问题。

• 基础设施即代码的思想：体现在 infrastructure 目录里。数据库、MQ、缓存、定时任务、配置项，不应该只活在运维脑子里，也不应该只散落在代码和平台配置中。它们需要被显式声明，并附带业务语义。尤其是数据库字段和 MQ schema，很多线上问题都来自“看起来只是改个字段，其实破坏了上下游契约”。

• 安全与合规：体现在 policy 目录里。风险分级不能完全靠 AI 主观判断，应该有启发式规则和人工确认机制。红线、禁止项、审批要求、停止条件，都要显式列出。比如 confirmed: false 就意味着这条知识还没有被人确认，Agent 不能把它当作强事实使用。

• 测试金字塔：体现在 test 目录里。不是简单写一句“跑测试”，而是明确不同变更类型对应什么测试范围。新增 API 要跑契约测试，修改数据库要跑迁移验证和回归测试，修改状态机要跑核心流程测试，修改 MQ schema 要跑生产者和消费者兼容性验证。

这些方法论本来就存在，只是过去主要服务于人类工程师。service-knowledge-generate 的意义，是把这些工程方法论重新整理成 AI Agent 可消费的知识结构。它不是创造新概念，而是把老经验变成新协议。

它的核心架构可以拆成2类文件。

第一类是 AGENTS.md，也可以理解为 Bootloader。它放在仓库根目录，告诉 Agent 去哪里加载知识、以什么顺序工作、什么不能做。它不应该复制大量正文，而是要短、清楚、权威，像一个入口说明。

第二类是 .knowledge/ 目录下的 yaml 文件。

比如以入口文件 index.yaml 为例，也就是路由中心。它定义了整个知识库的索引结构，同时也按常见的开发任务 task 类型定义必读文件清单：

knowledge_base:  name: "alibaba-*-*"  version: "1.0.0"  generated_at: "2026-07-07T07:15:00Z"  repository:    branch: "test/knowledge-20260707-skg"    commit: "391fc2989729cfd68650f7db90d2d498b370936d"# 全局 indexcatalog:  system: ".knowledge/system/"  object: ".knowledge/object/"  api: ".knowledge/api/"  downstream: ".knowledge/downstream/"  infrastructure: ".knowledge/infrastructure/"  flow: ".knowledge/flow/"  test: ".knowledge/test/"  policy: ".knowledge/policy/"task_routes:  add_api:    required:      - api/public_api.yaml      - api/api_compatibility.yaml      - test/test.yaml      - policy/policy.yaml  modify_database:    required:      - infrastructure/database_schema.yaml      - test/test.yaml      - policy/policy.yaml  fix_bug:    required:      - flow/      - test/test.yaml      - policy/policy.yaml

整个SKILL 最终查无典型文件树示例：

AGENTS.md.knowledge├── api // 对内对外 api │   ├── api_compatibility.yaml│   └── public_api.yaml├── downstream   // 下游依赖梳理│   ├── feature_service.yaml│   ├── route_service.yaml│   └── search_service.yaml├── flow   // 核心业务 flow 梳理，这一层是独立设计，完全可以脱离MVC 等代码架构存在│   ├── park_point_management.yaml│   ├── reach_radar_recommend.yaml│   ├── reach_support_recommend.yaml│   └── v2_scene_recommend.yaml├── generated   // 历史生成报告│   ├── README.md│   ├── latest.md│   └── report-20260616-100000.md├── index.yaml // 全局yaml 索引文件├── infrastructure     // 基础架构以来层，比如 database 、mq 等│   ├── database_schema.yaml│   └── message_queue.yaml├── object      // 系统内核心实体定义│   ├── park_point.yaml│   ├── reach_radar.yaml│   └── reach_scene.yaml├── policy      // 代码开发约束，可以初步自动识别│   └── policy.yaml├── system      // 上下游、技术栈、系统简介等│   ├── architecture.yaml│   ├── card.yaml│   └── tech_stack.yaml└── test     // 测试用例等    └── test.yaml

5.4 基建层

如前文3 所述，基建层更多的是中间件知识、代码规范、工程规范、CI/CD 等，具有以下特点：

一、大多偏静态知识：

比如CD 阶段，代码发布的MCP、灰度策略等，大多在团队内部是可以拉齐复用的。

二、更新频率相对比较低：

以代码规范为例，这种内容一般是常年不更新的，代码规范是一种类似“法理、法条”级别的约束，“法”本身是不会经常变化的。

三、作用于不同的研发阶段：

比如代码规范主要作用于coding 阶段，比如CI 知识更多的是集团的内的CI 系统流程与代码规范关系不大等等。不同阶段的知识关联度很多都比较低。

四、结构性偏低：

不同于“系统层知识库”具有强结构化、强状态的实体、状态机形式的定义。基建层的知识往往真的就是“知识”本身，甚至难以成为“数据”—— 因此结构化也比较低。

这部分知识库，我们最终采用和 “业务层”相同的方式存储，以 kbase 作为知识库承载，通过对应的MCP 或者 prompt 作用于实际的开发流程。

5.5 总览

这里还要特别提醒一个坑：AI Friendly 不是把所有东西都文档化。

很多团队一听要给 AI 建知识库，就开始焦虑：是不是要把每个函数、每个类、每个接口、每个工具方法都写一遍说明？如果这么做，基本很快就会失败。因为没人愿意维护，也没必要维护。更重要的是，大量低价值文档反而会干扰 AI 判断，让它在真正关键的信息之外消耗上下文和注意力。

真正值得显式化的知识，一般有三个特征：高复用、高风险、高隐性。

• 高复用：是指经常被多个需求、多个系统、多个团队反复使用的知识。比如公共 API、核心领域对象、通用业务流程、下游依赖、测试策略、公共中间件使用方式。这类知识一旦沉淀好，后续每一次技术方案设计和 AI Coding 都能复用，ROI 很高。

• 高风险：是指改错后后果严重的知识。比如交易状态机、支付流程、资金对账、权限系统、核心数据库表、MQ schema、风控策略、降级兜底逻辑。这些地方即使代码量不大，也应该优先显式化。因为 AI 最容易在“局部看起来合理”的地方做出危险修改，而高风险模块恰恰不能只看局部。

• 高隐性：是指代码里看不出来，或者很难从代码中稳定推断出来的知识。比如历史兼容原因、线上事故教训、审批规则、组织红线、特殊业务约束。很多系统里的关键约束，不是代码结构本身能表达出来的，而是来自团队经验和历史背景。人类工程师可能靠记忆知道不能动，AI 如果没有被明确告知，就只能猜。

这里必须划一条线：模型再强，也无法推断不存在的信息。

“这个 API 字段是公司级红线不能删除”，这不是一个能从代码中稳定推断出来的知识。代码里可能有 100 个字段，模型没有任何线索知道哪些是绝对不能删的。

“修改状态机必须经过人工审批”，这也不是代码能告诉你的。它是组织决策，是流程约束。

“变更超过 3 张表的 DDL 必须发起变更单”，同理。

这些信息的共同特点是：它们是规范性的，不是描述性的。它们不存在于代码中，只存在于人的脑子里、团队约定里、事故复盘里，或者某个分散文档里。如果没有人把它们显式化，任何模型都推断不出来。

所以，适合优先显式化的内容包括：服务边界、核心领域对象、状态机、API 兼容性规则、数据库表业务语义、MQ 事件契约、下游依赖、风险红线、测试策略。

不适合优先显式化的内容包括：普通工具函数说明、从代码一眼能读出来的实现细节、经常变化但没有业务约束的临时代码、低风险 CRUD 的重复描述。

换句话说，AI Friendly 的关键不是文档越多越好，而是把那些 AI 容易猜错、人类又经常忘记、改错代价很高 的知识显式化。

文档只是知识的载体，不是目标本身。真正有价值的 AI 知识库，不是信息堆得足够多，而是能够在关键时刻告诉 AI：这里是什么、为什么这样设计、哪里不能动、改完以后怎么证明是安全的。

以上这些思路，是我们对微服务系统知识库的分层拆解，这些拆解核心还是为了 AI Friendly。

除了这些知识库以外，在真正生成对应的技术研发场景流程，各个环节也需要一定的SKILL 进行流程调度和约束等。

所以，我们需要不断的去维护知识库的准确性（或者通过git hook 等工具做自动化维护机制）、不断地优化SKILL 本身的流程调度能力等。

不过随着基础大模型快速迭代，当前主流强基模已经展现出一个高阶能力：自主编排多个工具。

具体表现是，当你给一个基于强基模的 AI Agent 同时接入 aitom MCP、kbase MCP 和本地文件读取能力时，它能够自主决定：先用  kbase 做业务知识转换分析，看看业务元语描述应该转换为哪些具体的技术系统链路 ；再用 aitom 搜索对应的API 和链路，理解核心流程；最后读取 .knowledge/policy.yaml 检查约束，判断这个修改风险等级是什么。

它不需要你预先写死“先做 A 再做 B”的工作流。模型自己能判断什么时候需要什么信息，然后主动去取。大模型在很好的理解了这些知识和代码结构后，自己也能够很好的按照这种标准进行产出、自己维护知识库。

这意味着什么？

意味着哪怕我们的知识库建设不是很强大、哪怕我们的流程编排不是很强大，不断进化的基模可能都可以很好的理解和包容这些不完善的内容。

也意味着以上我们的知识库架构设计的大部分内容可能在不久的将来会被大模型内化成自身能力，大模型天然就可以产出和阅读比较复杂的业务、架构、系统、代码知识。

包括我们在和其他事业部、事业群的同事讨论的过程中，也有同学提到，自己辛苦做的平台化能力或者一些标准化的SKILL ，可能没多久大模型天然就内化支持了，感觉自己做了无用功。

其实，我是乐于见到那一天的，因为我们和大模型不是竞争关系，而是合作伙伴关系。大模型内化的能力越强，人类工程师需要做得事情就会越少，这其实是一件好事儿—— 我们真正的目标是 AI Native 的 7x24 小时生产。

所以，今天做知识库建设，并不是和未来的大模型能力赛跑，而是在把团队的业务理解、架构经验、系统约束和工程规范显式化。哪怕未来模型更强，这些显式知识也不会浪费；它们会从“喂给 AI 的上下文”，逐渐变成“组织工程能力的结构化资产”。