让 AI 智能体”理解“你的微服务

在编写代码之前一个优秀的 AI Agent 应该能回答关于某个功能的一个关键问题这个改动会影响到什么要回答这个问题Agent 需要一个知识库——它对你的服务的记忆。我基于同一组服务用三种不同的方式构建了知识库并进行了测试。一个可供 Agent 查询的图知识库击败了纯 Markdown 文档和语义搜索RAG因为“什么依赖于什么”本质上是一个图问题。1、每个改动开始时都会问的问题你在一个拥有大量微服务的平台上工作。一个新需求来了——“为订单添加一个忠诚度等级”——在写任何代码之前必须有人回答分布式系统中那个令人头疼的问题这到底会影响到什么哪些服务、哪些 API、哪些事件、哪些数据库。漏掉任何一个你都可能向一个服务推送了一个改动却悄无声息地破坏了三个跳转之外的另一个服务。越来越多地我们让 AI Agent 来回答这个问题——让它阅读需求并先写一份简短的规格说明这被称为规格驱动开发先写规格人工审批然后再开发。这是一个很棒的工作流。但它有一个决定一切的依赖项。2、究竟什么是“知识库”如果你在 AI 相关的讨论中听到“知识库”只是点头附和——这里有一个通俗的解释。知识库KB是系统为了做出决策而查找的事实集合。对于一个在你的平台上工作的 Agent 来说知识库就是它对你的所有服务的了解它们的 API、发布和消费的事件、它们调用的服务、它们拥有的数据。你可以把它想象成 Agent 对你架构的记忆。Agent 并没有在你的私有服务上训练过所以它无法凭空推理出这些信息。它会查阅知识库——就像你打开维基百科一样。没有知识库就没有推理能力。知识库薄弱推理能力就薄弱。3、为什么知识库才是真正的瓶颈Agent 生成的规格说明质量取决于它所掌握的信息。当你问“这个忠诚度功能会影响到什么”时如果知识库无法揭示改变一个事件会破坏下游的监听器规格说明就不会提到这一点——而这个工作流就会自信地推送一个破坏性变更。简而言之知识库决定了规格说明的上限。所以真正的问题不是“Agent 聪明吗”——而是*“我们的知识库是否具备让 Agent 找到影响范围的正确结构”*对于大多数团队来说答案是否定的。4、现在的痛点在哪里大多数团队将服务文档化为一堆README.md文件——每个服务一个用散文体写成“order-service 创建订单并发布一个order.created事件。它调用 inventory-service 来预留库存。”对人类来说很好。所以我们把这些文档都丢给 Agent让它评估一个功能的影响。然后它给出了一个自信但不完整的答案。一个具体的例子。功能在order.created事件中添加一个reservedQty字段。Agent 阅读了order-service.md看到“发布order.created”然后说“order-service 受影响。” ✅ 但是——谁消费了这个事件这个事实在 Agent 从未打开的另一页上所以它从未标记出消费者inventory-service也必须更改。这正是规格说明需要捕捉的东西但它漏掉了。这不是 Agent 笨。而是文档的结构不对。散文体没有“谁依赖我”这样的链接可以追踪。5、解决方案用图来思考而不是用页面转变在于将你的服务想象成一个小型的谁与谁交谈的图而不是一堆文档。现在“如果order.created变了谁会崩溃” 变成了一行代码就能回答的问题沿着consumes边追踪 → inventory-service。“谁调用了预留 API”——沿着边往另一个方向追踪。散文体隐藏的关系现在成了第一等公民。影响范围变成了查找而不是猜测。6、一个目录三种使用方式1. Markdown 文档—— 按服务生成的页面这样它们就不会过时。Agent 只是阅读散文。简单但它无法追踪“谁消费了这个”。2. Graph-RAG——RAG检索增强生成是给 LLM 提供新知识的标准技巧将每个事实转化为向量“嵌入”然后获取与问题最接近的那些——就像对提示词进行语义搜索。Graph-RAG增加了一步在检索之后沿着图跳一跳来拉入邻居调用者、事件的消费者。3. 图 MCP—— 跳过检索让 Agent直接查询图。MCPModel Context Protocol只是“AI 可以调用的工具”的一个标准。在 Spring AI 中一个工具就是一个注解Tool(description 如果这个 API / 主题 / 服务发生变化谁受影响) public Object get_dependents(String ref) { ... } // ref topic:order.createdAgent 调用它并得到精确、可重复的答案——影响是计算出来的不是猜出来的get_dependents(topic:order.created) → producers: [order-service], consumers: [inventory-service]7、测试相同的问题不许偷看公平评判两条规则让这次对比值得信赖Agent 只能看到知识库——永远看不到源代码。如果它能读代码我们就是在测试模型而不是知识库。AI 评判员对答案进行成对比较对照功能本身就像你比较两个 Pull Request 和一个工单一样。评判员从五个维度打分它是否找到了所有受影响的部分完整性是否避免了误报范围API 细节是否精确是否可重复规格说明是否可读8、结果图工具的方法赢了而且优势明显。另外两个亚军则以相反的方式失败Markdown 谨慎但盲目。它从不编造影响误报率为零但它漏掉了东西——它看到了事件的发布者却从未问谁消费了它。安全但不完整。Graph-RAG 过于积极。图的跳转找到了 diff 找到了 Markdown 遗漏的隐藏消费者和调用者——但在一些小型的、单服务的改动中它有时会拉入一个并未受影响的邻居。它找得更多但也会引发误报。图 MCP 则两者兼得—— 既完整又精确——因为它追踪的是真实的图而不是阅读散文或从相似性中猜测。一句话总结Markdown 遗漏RAG 过度图计算。9、你不必只选一个诚实的答案是将它们分层——它们都是从同一个目录生成的所以它们是不同的前门而不是竞争对手图 MCP作为“这会影响到什么”的引擎Markdown供人类阅读生成的所以不会过时Graph-RAG当问题比较模糊你想要召回率而非精确度时完整的项目——两个 Spring Boot 服务、三种知识库、测试功能和 AI 评判员——都在 GitHub 上github.com/ganesh/sdd-knowledgebase-evaluation。要点总结在规格驱动开发中知识库决定了规格说明的上限。在责怪 Agent 之前先修复知识库。“这会影响到什么”是一个图问题—— 用图来回答而不是通过阅读或嵌入段落。MCP 将图查找变成了 Agent 可以调用的工具—— 在 Spring AI 中只需一个Tool注解。从代码中构建知识库而不是手工维护—— 生成的视图不会过时而且你能得到公平的对比。测量你的知识库不要假设它没问题。完整性、误报率和可重复性都是可以评分的——一个下午就能搞定。原文链接让 AI 智能体”理解“你的微服务 - 汇智网