catalog-documentation-creator

EventCatalog 文档创建器

按照项目约定和最佳实践生成格式规范的 EventCatalog 文档文件。

说明

步骤 1：查找或创建用户的目录

生成任何文件之前，先询问用户：“您已经有 EventCatalog 项目了吗？还是想创建一个新项目？”

如果他们已经有目录：

• 询问：“您的 EventCatalog 项目在哪里？” — 可能是：
  • 他们克隆到本地的仓库（例如，~/projects/my-catalog/）
  • 他们计算机上的某个文件夹
  • 目录位于子目录中的单体仓库
• 检查是否存在 eventcatalog.config.js 文件或已知目录（systems/、services/、agents/、events/、domains/、adrs/、data-products/、entities/ 等），以确认这看起来像一个 EventCatalog 项目
• 阅读现有结构，了解他们使用的是嵌套式（domains/services/agents/events）还是扁平式（顶层 services/、agents/、events/）组织方式

如果他们还没有目录：

• 询问他们想在哪里创建目录（默认：当前目录）
• 运行以下命令来搭建一个新的空目录：

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

  （将 my-catalog 替换为用户偏好的名称）
• 这会创建一个结构正确、可直接使用的 EventCatalog 项目
• 所有生成的文档文件都放在这个新目录中

重要：所有生成的文件都必须写入用户的目录，而不能只显示出来。务必询问他们想在哪里记录资源，切勿自行假设。

步骤 2：了解用户想要记录的内容

询问用户想要记录什么。常见场景包括：

• 单个服务或 Agent 及其消息
• 将服务、容器、流、实体、参与者和相关系统组合在一起的系统
• 事件、命令或查询
• 包含嵌套服务的完整领域
• 跨服务和 Agent 的业务流
• 通道（Kafka 主题、RabbitMQ 队列等）
• 容器（数据库、缓存、队列）
• 架构决策记录（ADR）
• 用于分析、报告、ML 特征或运营数据输出的数据产品
• 领域实体或聚合
• 可重复使用的图表资源

生成文档之前，收集以下信息：

• 资源名称和用途
• 版本（新资源默认为 0.0.1）
• 记录系统时的系统边界、范围（internal 或 external）、参与者、关系和包含的资源
• 消息关系（发送/接收哪些消息）
• 通道路由（消息通过哪些通道流动）
• 容器（服务会从哪些数据库/缓存读取数据或向其中写入数据）
• ADR 链接（决策适用于哪些资源，以及它是否取代/修订了其他 ADR）
• 数据产品沿袭关系（输入、输出、契约、新鲜度/SLA 预期）
• 实体和关系（标识符、属性、引用、聚合根）
• 图表表示法（Mermaid、PlantUML 或其他受支持的围栏图表格式）
• 记录 Agent 时的模型/提供商和工具
• 适用时的架构格式（JSON Schema、Avro、Protobuf）

如果用户指向某个代码库（而非目录），请分析其中的服务、Agent、消息、架构和关系，然后生成对应的目录文档。

步骤 3：检查现有目录

如果目录中已有资源，请阅读现有文件以了解：

• 命名约定（PascalCase ID？kebab-case？）
• 文件夹结构（按领域嵌套还是平铺？）
• 已定义的所有者/团队
• 使用的徽章样式和模式
• 使用的架构格式（JSON Schema、Avro 等）

新文档应遵循这些现有约定。

如果用户已连接 EventCatalog MCP 服务：

1. 使用 getResources 查看目录中已有的内容
2. 使用 getResource 查看现有条目采用的约定（命名模式、所有者格式、徽章样式）
3. 使用 findResourcesByOwner 推荐一致的所有权归属
4. 使用 getSchemaForResource 匹配现有架构格式

这样可以确保新文档与目录中的现有内容保持一致。

步骤 4：生成文档

按照资源专属参考资料生成文件。根据资源类型查阅相应的参考文件：

• references/services.md — 包含发送/接收、通道路由和容器的服务
• references/systems.md — 包含范围、服务、容器、流程、实体、参与者和系统关系的系统
• references/agents.md — 包含模型元数据、工具、发送/接收、容器和流程的 Agent
• references/events.md — 包含架构、负载示例、生产者/使用者代码的事件
• references/commands.md — 包含 REST 操作和架构的命令
• references/queries.md — 包含 REST 操作和响应架构的查询
• references/domains.md — 包含子域、服务和业务上下文的域
• references/flows.md — 包含步骤、分支和外部系统的业务流程
• references/channels.md — 包含路由、协议和参数的通道
• references/containers.md — 包含数据分类的容器（数据库、缓存、队列）
• references/adrs.md — 包含状态、日期、决策者、适用范围和关系的架构决策记录
• references/data-products.md — 包含输入、输出、数据契约、血缘和 SLA 的数据产品
• references/entities.md — 包含标识符、属性、关系和聚合根的 DDD/领域实体
• references/diagrams.md — 可复用的图表资源（Mermaid、PlantUML、架构图）
• references/ubiquitous-language.md — 各域的通用语言术语（DDD 术语表/词典）
• references/teams-and-users.md — 团队和用户（所有权）
• references/components.md — 组件（NodeGraph、Schema、Mermaid、Tabs 等）和资源引用（[[type|Name]] Wiki 风格链接）
• references/supporting-collections.md — 变更日志、资源文档、自定义文档、架构和 Studio 设计

每个资源文件都必须包含：

• 位于 --- 分隔符之间的有效 YAML 前置元数据
• 符合现有目录惯例的 id 字段
• 易于理解的显示名称 name
• 语义化版本字符串 version
• 简洁的 1–2 句描述 summary
• 至少包含一个团队或用户的 owners（默认情况下，如果资源缺少 summary 或所有者，EventCatalog 检查器将报错）

重要：只能使用参考文件中记录的前置元数据字段。任何未知的顶层键都会导致构建失败（Unknown property "tags". Custom properties must start with "x-"）。自定义元数据应放在以 x- 为前缀的键中（例如 x-tier: gold），并使用 <CustomProperties /> 或 <CustomProperty name="x-tier" /> 在正文中呈现。

重要：版本化资源（systems、services、agents、events、commands、queries、domains、flows、channels、containers、ADRs、data products、entities、diagrams）的文件名始终使用 index.mdx。团队和用户直接使用 {id}.mdx 文件。变更日志使用 changelog.mdx 或 changelog.md。通用语言使用 ubiquitous-language.mdx。资源的较早版本归档在该资源内部的 versioned/{version}/index.mdx 文件夹中（例如 events/OrderCreated/versioned/0.0.1/index.mdx），最新版本放在资源根目录下。按照嵌套结构模式，将文件放在正确的文件夹路径中：

domains/{DomainName}/systems/{SystemName}/index.mdx
domains/{DomainName}/systems/{SystemName}/services/{ServiceName}/index.mdx
domains/{DomainName}/systems/{SystemName}/containers/{ContainerName}/index.mdx
domains/{DomainName}/services/{ServiceName}/events/{EventName}/index.mdx
domains/{DomainName}/agents/{AgentName}/index.mdx
domains/{DomainName}/data-products/{DataProductName}/index.mdx
domains/{DomainName}/entities/{EntityName}/index.mdx
domains/{DomainName}/diagrams/{DiagramName}/index.mdx

如果目录采用扁平结构，也可以使用扁平结构：

systems/{SystemName}/index.mdx
services/{ServiceName}/index.mdx
agents/{AgentName}/index.mdx
events/{EventName}/index.mdx
adrs/{adr-id}/index.mdx
data-products/{DataProductName}/index.mdx
entities/{EntityName}/index.mdx
diagrams/{DiagramName}/index.mdx

不要直接生成 schemas 集合条目。应从事件、命令或查询生成或引用架构文件，并使用 schemaPath 或 schemas；EventCatalog 会根据这些引用创建 schemas 集合。除非用户明确提供来自 EventCatalog Studio 的 .ecstudio 内容，否则不要自行编写 designs。

第 5 步：验证输出

向用户呈现文件之前，请验证：

• YAML frontmatter 两侧都有 --- 分隔符
• 每个 frontmatter 键都已针对相应资源类型记录，或带有 x- 前缀
• 所有 id 字段保持一致（不含空格，并与文件夹名称相符）
• 所有 version 字段都是有效的 semver 字符串（例如，0.0.1）
• sends/receives 中的所有消息引用都包含 id，并可选包含 version
• System 的 services、containers、flows、entities、relationships 和领域的 systems 引用都包含 id，并可选包含 version
• System 的 scope 为 internal 或 external，actor 的 direction 为 inbound 或 outbound
• Channel 路由在 sends/receives 中正确使用 to/from 字段
• schemaPath 引用的 Schema 文件确实存在或会生成
• 已包含用于架构可视化的 <NodeGraph /> 组件
• Owner ID 引用目录中真实存在的团队/用户

常见模式

记录处理消息的服务

当用户说“记录我的支付服务，该服务接收 OrderCreated 事件并发送 PaymentProcessed 事件”时：

1. 生成服务的 index.mdx，包含 receives 和 sends 数组
2. 如果消息通过 Channel 流动，则为 sends/receives 添加 to/from 字段
3. 如果目录中尚不存在每个事件的 index.mdx，则生成相应文件
4. 在服务正文中包含 <NodeGraph />，以展示消息流
5. 如果服务拥有重要的领域对象，则生成相关实体
6. 为每条消息添加示例负载部分
7. 将文件放在正确的嵌套文件夹结构中

记录系统

当用户描述一项功能、子系统、产品功能或外部系统时：

1. 判断该系统应放在某个领域内（domains/{Domain}/systems/{System}/index.mdx），还是应放在目录根目录下（systems/{System}/index.mdx），因为它是共享的、外部的，或不归任何一个领域所有
2. 生成系统的 index.mdx，并在已知的情况下包含 scope、owners，以及对其 services、containers、flows、entities 和 diagrams 的引用
3. 为指向其他系统的单向链接添加 relationships，并为边设置简短的 label
4. 为人员、角色或外部参与方添加 actors；当 actor 与系统交互时使用 direction: inbound，当系统主动联系 actor 时使用 direction: outbound
5. 包含 <ContextDiagram />，以展示参与方和系统间关系
6. 包含 <NodeGraph />，以展示系统内的资源
7. 如果嵌套资源归该系统所有，则在系统文件夹下生成这些资源，例如 domains/{Domain}/systems/{System}/services/{Service}/index.mdx
8. 如果系统嵌套在某个领域下，则将其添加到该领域的 systems frontmatter 中。嵌套在领域内的每个系统都必须在该领域的 index.mdx 中被引用：

   systems:
     - id: cart-system
       version: 1.0.0
     - id: promotion-system
       version: 1.0.0
   

9. 如果 ADR 适用于系统边界、持久化、集成模式或所有权模型，则通过 appliesTo: [{ type: system, id: ... }] 添加链接

记录 Agent

当用户说“记录我的支持 Agent，它会读取订单数据并使用 Zendesk”时：

1. 生成 Agent 的 index.mdx，并在已知的情况下包含 model、tools、receives/sends、readsFrom/writesTo 和 flows
2. 生成或引用 Agent 消费或产出的事件/命令/查询
3. 为 Agent 读取或写入的数据存储生成容器
4. 记录工具时包含 <AgentTools />
5. 包含 <NodeGraph />，使 Agent 出现在架构可视化中
6. 如果 Agent 属于某个领域，则将其添加到该领域的 agents frontmatter 中

记录领域

重要：领域必须至少包含一个系统、服务或 Agent。绝不要创建空领域。如果用户描述了一个领域，请确保识别并为其生成系统、服务或 Agent。

当用户想要记录一个完整领域时：

1. 识别属于此领域的系统、服务和 Agent。如果用户没有指定，请询问他们：“此领域包含哪些系统、服务或 Agent？”不要创建空领域。
2. 生成领域的 index.mdx，其中 systems 字段列出每个系统，services 字段列出每个直接隶属于该领域的服务，agents 字段列出每个直接隶属于该领域的 Agent
3. 当 entities、data-products、flows 和 diagrams 资源直接隶属于该领域时，添加这些字段
4. 在领域内生成每个系统、服务和 Agent
5. 生成服务和 Agent 引用的每条消息
6. 如果用户描述了实体、数据产品、图表和通道，则生成这些内容
7. 使用嵌套文件夹结构：domains/{Domain}/systems/{System}/、domains/{Domain}/systems/{System}/services/{Service}/events/{Event}/、domains/{Domain}/services/{Service}/events/{Event}/、domains/{Domain}/agents/{Agent}/、domains/{Domain}/entities/{Entity}/ 和 domains/{Domain}/data-products/{DataProduct}/
8. 从服务名称、Agent 名称、事件／命令名称、实体和业务流程中提取领域专属术语，为该领域生成 ubiquitous-language.mdx 文件。将其放在 domains/{Domain}/ubiquitous-language.mdx。格式和示例请参阅 references/ubiquitous-language.md。
9. 重要：生成所有文件后，验证领域的 frontmatter 中的 systems 字段列出了每个系统，services 列出了每个直接隶属于该领域的服务，agents 列出了每个直接隶属于该领域的 Agent。直接创建在领域下的每个系统、服务或 Agent 都必须在领域的 index.mdx 中引用：

   systems:
     - id: CheckoutSystem
   services:
     - id: OrdersService
     - id: InventoryService
     - id: PaymentService
   agents:
     - id: OrderSupportAgent
   

   如果系统、服务或 Agent 嵌套在领域文件夹中，但未列在领域的 frontmatter 中，它就不会显示为该领域的一部分。务必仔细核对。

记录 ADR

当用户描述一项架构决策时：

1. 生成 adrs/{adr-id}/index.mdx
2. 使用受支持的状态之一：proposed、accepted、rejected、deprecated 或 superseded
3. 添加 date，格式为 YYYY-MM-DD
4. 在已知的情况下，使用现有团队／用户 ID 填写 decisionMakers 和 owners
5. 使用 appliesTo 将决策关联到受影响的资源（system、service、event、domain、flow、data-product、entity 等）
6. 使用 supersedes、supersededBy、amends、amendedBy 或 related 将 ADR 相互关联
7. 使用 Context、Decision 和 Consequences 组织正文

记录数据产品

当用户描述分析、报告、BI、ML 特征或派生运营数据时：

1. 生成 data-products/{DataProductName}/index.mdx，或将其嵌套在相关领域／子领域下
2. 为上游消息、服务、容器、通道或其他资源添加 inputs
3. 为生成的消息、服务、容器、通道或契约添加 outputs
4. 如果某个输出有数据契约，请添加 contract.path、contract.name 和 contract.type
5. 添加 <NodeGraph /> 以及任何相关契约文件的 <SchemaViewer />
6. 记录数据血缘、时效性、所有权、访问模式和 SLA

编写实体文档

当用户描述带有属性的领域模型、聚合、数据对象或业务概念时：

1. 根据目录结构生成 entities/{EntityName}/index.mdx、domains/{Domain}/entities/{EntityName}/index.mdx 或 services/{Service}/entities/{EntityName}/index.mdx
2. 适用时添加 identifier 和 aggregateRoot: true
3. 添加 properties，包含 name、type、required 和 description
4. 使用 references、referencesIdentifier 和 relationType 表示与其他实体的关系
5. 在正文中加入 <EntityPropertiesTable /> 以渲染属性表
6. 在领域或服务的 frontmatter 中通过 entities 链接实体

编写图表文档

当用户提供或要求可复用的架构图、时序图、流程图或模型图时：

1. 生成 diagrams/{DiagramName}/index.mdx，或将其嵌套在相关领域／子领域下
2. 添加 id、name、version 和 summary
3. 在正文中使用围栏代码块添加图表，语言标记为 mermaid、plantuml 或其他受支持的图表类型
4. 使用 frontmatter 字段 diagrams，在相关资源中引用该图表

编写业务流程文档

当用户描述多步骤流程时：

1. 识别不同的步骤（用户操作、服务调用、消息交换、外部系统）
2. 生成包含 steps 数组的流程 index.mdx
3. 每个步骤包含 id、可选的 title（默认为其指向对象的名称），以及最多一个资源键：message、service、agent、system、channel、flow、container、dataProduct、actor、custom 或 externalSystem。不要设置 type（该字段会被忽略）。各步骤的结构请参见 references/flows.md
4. 使用 next_step 或 next_steps 连接步骤以表示分支（同一步骤中不能同时使用两者）
5. 仅允许使用文档中定义的步骤键；自定义步骤键必须以 x- 开头

编写通道路由文档

当用户描述消息如何流经基础设施时：

1. 生成包含 routes 的通道 index.mdx 文件，以定义通道到通道的路由
2. 更新服务或 Agent 的 sends／receives，添加指向通道的 to／from 字段
3. 完整图景应展示：服务或 Agent 发送 → 通道 → 路由至 → 通道 → 服务或 Agent 接收

质量检查清单

• 花时间彻底完成检查
• 质量比速度更重要
• 不要跳过验证步骤

向用户交付文档前，请根据此清单检查每个文件：

1. Frontmatter 在 --- 分隔符之间包含有效的 YAML
2. id 与文件夹名称一致
3. 不包含未知的 frontmatter 键——只能使用已记录的字段，或以 x- 为前缀的自定义字段
4. version 是有效的 semver 字符串
5. summary 简洁且有意义（不是泛泛而谈）
6. 消息关系（sends/receives）包含 id
7. 通道路由（to/from）引用有效的通道 ID
8. 如果资源具有图关系，正文应包含 <NodeGraph /> 以进行可视化
9. Schema 引用指向真实文件
10. 文件夹结构遵循目录约定
11. 不存在重复资源（已与现有目录核对）
12. 有版本的资源使用 index.mdx（或遵循目录中现有的 .md/.mdx 约定）；团队和用户使用 {id}.mdx；变更日志使用 changelog.mdx/changelog.md
13. 每个领域至少包含一个系统、服务或 Agent——绝不创建空领域
14. 领域的 systems、services 和 agents frontmatter 应列出属于该领域的所有直接系统、服务和 Agent
15. 如果存在嵌套资源，领域的 entities、data-products、flows 和 diagrams frontmatter 应列出这些资源
16. 每个领域都应有一个 ubiquitous-language.mdx 文件，其中包含从服务、Agent、事件、命令、实体、数据产品和业务流程中提取的相关领域术语
17. ADR 应具有有效的状态、日期、已知的决策者，以及受影响资源的 appliesTo 引用
18. 生成系统时，系统的 scope、关系指针和参与者方向应有效
19. 生成数据产品时，outputs.contract.path 中引用的数据产品契约文件必须存在

故障排除

可视化工具中未显示消息

如果生成的事件/命令未显示在服务或 Agent 节点图中：

• 确认服务或 Agent 的 frontmatter 中的 sends/receives 数组引用了消息的确切 id
• 确保消息有自己的 index.mdx 文件

Schema 未渲染

如果 <Schema /> 或 <SchemaViewer /> 组件显示错误：

• 确认 frontmatter 中的 schemaPath 指向与 index.mdx 位于同一目录下的文件
• 检查 Schema 文件是否为有效的 JSON/Avro/Protobuf

未识别文件夹结构

如果资源未显示在 EventCatalog 中：

• 确认文件名恰好为 index.mdx 或 index.md（而不是 INDEX.mdx 或 readme.md）
• 较旧版本必须位于 {resource}/versioned/{version}/index.mdx
• 确认文件夹位于可识别的集合目录中（systems/、services/、agents/、events/、domains/ 等）

系统上下文图未显示参与者或关系

如果 <ContextDiagram /> 未显示预期的系统上下文：

• 确认系统 frontmatter 中包含 relationships 或 actors
• 确认 relationships 指向有效的系统 ID，且每个关系都有 label（没有标签的关系不会绘制连线）
• 确认参与者的 direction 为 inbound 或 outbound
• 如果正在查看领域上下文图，确认领域的 systems frontmatter 引用了相关系统

构建因 Unknown property 失败

• frontmatter 中包含资源 Schema 未定义的键。请移除该键、修正拼写，或为其添加 x- 前缀并重命名

通道路由不可见

如果可视化工具中未显示通道连接：

• 确认通道 frontmatter 中的 routes 字段引用了有效的通道 ID
• 确认服务或 Agent 的 sends/receives 中的 to/from 字段引用了有效的通道 ID