c4-to-eventcatalog

C4 转 EventCatalog

概述

将 C4 模型映射到 EventCatalog 资源，同时保留架构意图，避免将其扁平化。先生成一份便于评审的 .c4-eventcatalog-plan.md，然后在用户批准映射后，使用 catalog-documentation-creator 生成或更新实际的目录文件。

加载参考资料

映射 C4 模型前，务必先阅读 references/c4-mapping.md。

生成文件时，阅读相关的 ../catalog-documentation-creator/references/ 文件：

• domains.md、systems.md、services.md、agents.md
• events.md、commands.md、queries.md
• channels.md、containers.md、flows.md
• 若涉及 NodeGraph、Mermaid、wiki 链接、架构和 MDX 组件，请阅读 components.md
• 若模型包含值得保留为独立图表的视图，请阅读 diagrams.md

工作流

按顺序执行以下阶段。

1. 定位输入

如果用户未提供 C4 源文件，请向其索取。支持 Structurizr DSL/JSON、LikeC4（.c4）、C4-PlantUML、Mermaid C4、Markdown 架构文档或图片图表。提醒用户，源文本比仅有图片的提取结果更可靠。

如果源文件是 LikeC4，且目录中包含 .c4 文件并已安装 likec4 包，EventCatalog 也可以通过 <LikeC4View viewId="..." /> 直接渲染其视图。询问用户是否希望在映射后的资源正文中嵌入相关视图，并同时生成资源。

询问用户是否有 EventCatalog 项目。如果有，请索取路径，并验证 eventcatalog.config.js 或已知资源目录。如果没有，请说明将在移交阶段通过 catalog-documentation-creator 搭建项目框架。

2. 清点现有目录

如果目录已存在，在提出更改建议前先检查：

• 判断目录采用扁平结构还是按域嵌套的结构。
• 记录现有资源的 ID、名称、版本、所有者和关系。
• 记录命名风格、架构格式、所有者约定、徽章和域的使用方式。
• 对于 C4 模型中不存在的现有目录资源，将其标记为 investigate，而不是待删除项。

3. 解析 C4 模型

提取：

• 人员和外部系统
• 软件系统
• 容器，包括应用、服务、Agent、数据库、队列和浏览器/移动客户端
• 仅提取跨越所有权、部署、数据或消息边界的组件
• 关系、协议、技术、标签、描述和视图
• 应转换为工作流的动态视图或叙述场景
• 消息名称、主题、队列、API、命令、查询、事件和架构引用

保留证据。对于源文件，尽可能引用文件路径和行号；对于图表，引用图表/视图名称和元素 ID。

4. 映射并协调

使用 references/c4-mapping.md，将每个 C4 元素映射为以下类型之一：domain、system（内部系统或 scope: external）、系统 actor、系统 relationship、service、agent、event、command、query、channel、container、flow、resource 正文中的 document，或 needs user decision。

对于现有目录，为每个映射项分配一种状态：new、update、unchanged 或 investigate。

5. 只询问结构性问题

一次只问一个问题。每个问题都必须包含：

• 推荐答案
• 得出该答案的证据
• 对生成的 EventCatalog 资源造成的影响

只询问会影响结构的决策：域边界、哪些软件系统属于内部或外部、可部署服务边界、Agent 分类、关系属于事件/命令/查询/API 调用中的哪一种、基础设施节点应归类为通道还是数据容器，以及是否更新现有资源。不要就文案、摘要或装饰性元数据反复询问用户。

6. 编写计划

如果目录中存在 catalog，则在该目录下编写 .c4-eventcatalog-plan.md；否则，将其放在提供的 C4 源文件旁边或当前工作目录中。纳入 references/c4-mapping.md 中的模板：源、决策、资源映射、关系、要创建或更新的文件，以及待解决的问题。

生成 catalog 文件前，请用户批准计划。

7. 生成 catalog 文件

获得批准后，使用 catalog-documentation-creator 创建或更新文件。仅加载获批计划中涉及的资源对应的 EventCatalog 参考文件。遵循目标 catalog 的现有结构；更新现有资源时，必须保留或协调用户内容，绝不直接覆盖。

质量规则

• 默认不要为每个 C4 框创建一个 EventCatalog 资源。应根据职责、部署、归属、消息流和 EventCatalog 的实用性进行映射。
• 不要创建空域。每个域至少必须包含一个系统、子域、服务或 Agent。
• 不要将每个 C4 组件都建模为 EventCatalog 资源。大多数组件应放在父级服务正文、Mermaid 图或流程中。
• 优先使用明确标注的 C4 关系，而不是推断消息类型。如果关系标签含义不明确，请标记为 needs user decision。
• ID 应与 catalog 保持一致。如果要创建新的 catalog，除非用户另有指定，否则业务资源优先使用 PascalCase 资源 ID。
• 保留现有 catalog 内容。添加、更新或标记差异；不要删除。
• 如果相关 EventCatalog 参考文件有建议，应通过交接技能在生成的资源中包含 <NodeGraph />。