EventCatalog：把架构文档变成 AI Agent 能读懂的活文档

一句话讲清楚它是什么

想象你接手了一个由 30 个微服务组成的电商系统。老系统里有一堆 Confluence 页面，写着"订单服务会发布 OrderCreated 事件"，但没人敢保证这句话在今天还成立——文档和代码，已经分家两年了。

EventCatalog 就是来治这个病的。它的做法有点反常识：不放wiki页面，而是用"积木块"来搭架构。积木块包括领域（Domain，业务边界）、系统（System）、资源（Resource，比如服务、消息、数据库），以及贴在资源上的契约（Schema：OpenAPI / AsyncAPI / Protobuf / JSON Schema / Avro）、ADR 架构决策记录和负责人。你把架构写成 MDX 文件放进 Git 仓库，它自动渲染成一个可以点、可以搜、可以画图的网站。

这被称为 docs-as-code：文档不是写完就烂在某个 wiki 里，而是像代码一样走 PR 评审、进版本控制、跟着 CI 一起跑。

它的 AI 味到底有多浓

这是 2026 年最关键的变化。EventCatalog v5 明确把"让 AI Agent 读懂你的架构"当成主线，而不是事后加的插件。

具体有六条路径：

1. 内置 MCP Server —— 这是最实用的一条。你的 Claude、ChatGPT、VS Code 通过 MCP 连上目录，就能用只读工具查资源、看 Schema、追消息的生产者消费者、分析变更影响。工具是只读且带 title 的，客户端可以自动放行。更妙的是支持作用域连接：只把某个领域或系统的子图暴露给 Agent，不泄漏全局信息。
2. AI Chat 内置助手 —— 直接在目录网站里用自然语言问架构问题。
3. EventCatalog Agent —— CI/CD 里的机器人，每次 PR 自动更新受影响文档并给你开 PR，还能做破坏性变更检测。
4. llms.txt / schemas.txt —— 给 AI 工具的机器可读索引。
5. AI Skills —— 一组可安装的技能包，帮 Agent 管理目录。
6. MCP Apps 生态 —— 支持 @mcp-b/webmcp-polyfill，在 Claude / ChatGPT / VS Code 里直接把架构图当交互式可视化组件打开，而不是退化成一堆 Mermaid 文本。

背后的技术逻辑其实不复杂：EventCatalog 把架构解析成一张内部图谱（graph），这张图谱天然就是给 LLM 用的上下文。文档和代码一样，是 agent 最好的知识底座。

架构三档细节

它的可视化分三层，这个设计比大多数架构图工具务实：

层级	看到什么	回答什么问题
L1	领域、系统及其关系	有哪些业务边界和系统？依赖关系如何？
L2	系统内的服务与数据存储	系统内部跑什么？和什么通信？
L3	L2 + 消息与通道	服务之间流转什么消息？走哪个 topic？

技术栈上它是 Astro + React 的 SSR 应用，TypeScript 主导（约 967 万字节），配合 MDX 支持自定义组件。仓库是 pnpm workspace + Turborepo 管理的 monorepo，11 个包：core、sdk、cli、connectors、exporters、linter、diff、visualiser、fitness、breaking-changes、create-eventcatalog。测试用 Vitest 单测 + Playwright E2E 双层保障。GitHub 上约 4600 次提交、69 位 all-contributors 参与，官方称已创建超过 40000 个 catalog。

上手成本

门槛低到有点不像一个 BSL 许可的企业级产品：

npx @eventcatalog/create-eventcatalog@latest my-catalog

一条命令，目录建好，http://localhost:3000 就能开始写。生产环境有官方 Dockerfile（core 包内 Dockerfile.server、studio-web 的 Dockerfile、deploy/demo 的 Dockerfile）和 fly.toml 配置，部署到 Fly.io 这类容器平台是标准路径。资源需求很轻：2GB 内存、1GB 磁盘，不需要 GPU，Node 20+ 即可。

必须说清楚的局限

第一，许可证变了，这是选型时最该先看的一件事。 v4 及之前是 MIT，永久开源。v5 之后改为 BSL 1.1（Business Source License），官方自己都明确写了"source-available，不是开源，OSI 不认"。免费使用的门槛是：个人自用、年收入低于 1000 万美元且融资低于 1000 万美元、记录公共开源项目、学校教学科研、以及 60 天评估期。超出这些就要按团队数买商业授权——Team 档 5995 美元/年起（5 个团队以内），最高 Division 档 19995 美元/年，Enterprise 从 24995 美元/年起。

有意思的是"生产使用"的定义非常严：只要团队、承包商或**自动化系统（包括 AI Agent）**依赖这个目录来理解或治理系统，就算生产使用，哪怕目录只在内部、哪怕只是"内部使用"。在 CI 里构建或校验目录也算。所以想拿去省钱，得先算清楚自己公司的营收和融资额。

第二，v5 之前后断裂明显。 联邦（federation，把多个团队的目录拼成一张全局视图）在免费档可用，付费档变成 Enterprise 专属。企业版的 OAuth2、RBAC、Schema 治理能力也一并被划走。

第三，免费使用必须主动确认。 官方明确提示：如果你的组织有政策不允许使用 source-available 软件，v4 是给你的选择，没有额外的豁免流程。

第四，它是"架构文档工具"，不是"API 文档工具"。 它不做 OpenAPI 调试、不做请求模拟、不要期望它替代 Swagger UI 或 Redoc。

为什么值得关注

EventCatalog 代表了一个很清晰的趋势：文档工具正在从"给人读"转向"给人和 Agent 同时读"。MCP Server、llms.txt、CI Agent、Skills——这些不是把 AI 当成花哨的聊天框贴上去，而是重新设计了整个文档的信息架构，让架构图谱本身成为 Agent 的可查询接口。

Mermaid 图对人类很友好，但 Agent 读不懂；结构化的 JSON 对 Agent 友好，但人类读不下去。EventCatalog 的做法是：底层存 MDX（对人类友好、对 Agent 可解析），顶层渲染成三种粒度的图（对人类友好），同时开一个 MCP 接口把同一份数据喂给 Agent。这个"一份数据、三种消费方式"的结构，可能是架构文档类工具未来几年的标准答案。

创始人 David Boyne 在 v5 博客里说得直接："从 v5 开始，每个版本发布四年后都会变成 MIT。" 这是承诺，但也只是承诺——BSL 的四年延迟转换在开源史上并不是没有翻车先例。

对团队来说，最实际的问题是：你们的架构文档现在还活着吗？ 如果答案有点勉强，那 EventCatalog 值得先花半天做个 POC 试试——反正 60 天评估期免费。

适合谁

• 有 5 个以上微服务、文档已经开始腐烂的中大型团队
• 正在往 Claude / ChatGPT 里灌架构上下文的 AI 工程团队
• 想让 AI Agent 自动维护文档的团队（CI Agent + PR 流程）
• 已经在用 EventDriven Architecture、AsyncAPI、DDD 的团队（概念现成）

不适合谁

• 单体小项目、三个服务的创业团队（杀鸡用牛刀）
• 年营收超 1000 万美元且不愿付费的组织（除非采购流程走通）
• 需要 API 在线调试、需要 APM 链路追踪的组织（范畴不同）