> ## Content Index
> Fetch the complete content index at: https://www.hubwiz.com/blog/llms.txt
> Use this file to discover other available public pages before exploring further.

# 让 AI 智能体”理解“你的微服务
- URL: https://www.hubwiz.com/blog/let-ai-agents-understand-your-microservices/
- Published: 2026-06-09T07:19:49.000Z
- Updated: 2026-10-13T15:20:27.000Z
- Description: 一份面向初学者的 AI Agent 知识库指南，以及三种方法的对决测试：纯 Markdown、Graph-RAG 和基于 MCP 工具的图知识库。
- Author: admin
- Tags: AGENT, KNOWLEDGE BASE, #Import 2026-10-14 14:41

在编写代码之前，一个优秀的 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.created`

对人类来说很好。所以我们把这些文档都丢给 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](https://github.com/TheGanesh/sdd-knowledgebase-evaluation?ref=hubwiz.com)。

要点总结：

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

---

原文链接: [Teaching an AI Agent to Know Your Microservices: Markdown, RAG, and Graph Knowledge Bases](https://freedium-mirror.cfd/https://medium.com/@kandisa.ganesh/teaching-an-ai-agent-to-know-your-microservices-markdown-rag-and-graph-knowledge-bases-3aa729868af3?ref=hubwiz.com)

汇智网翻译整理，转载请标明出处

> **这是「Agent / MCP」专题的一部分。**完整地图见：[Agent / MCP / 自动化完全指南](https://www.hubwiz.com/blog/agent-stack/)