企业官网建设流程全解析

在编写代码之前，一个优秀的 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直接查询图。MCP（Model Context Protocol）只是“AI 可以调用的工具”的一个标准。在 Spring AI 中，一个工具就是一个注解：

@Tool(description = "如果这个 API / 主题 / 服务发生变化，谁受影响？") public Object get_dependents(String ref) { ... } // ref = "topic:order.created"

Agent 调用它并得到精确、可重复的答案——影响是计算出来的，不是猜出来的：

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。

要点总结：

1. 在规格驱动开发中，知识库决定了规格说明的上限。在责怪 Agent 之前，先修复知识库。
2. “这会影响到什么？”是一个图问题—— 用图来回答，而不是通过阅读或嵌入段落。
3. MCP 将图查找变成了 Agent 可以调用的工具—— 在 Spring AI 中，只需一个@Tool注解。
4. 从代码中构建知识库，而不是手工维护—— 生成的视图不会过时，而且你能得到公平的对比。
5. 测量你的知识库；不要假设它没问题。完整性、误报率和可重复性都是可以评分的——一个下午就能搞定。

原文链接：让 AI 智能体”理解“你的微服务 - 汇智网