flow-wizard

流程文档向导

一项交互式对话技能，按步骤、分章节引导用户在 EventCatalog 中记录业务流程，同时交叉参考其现有目录资源。

说明

步骤 1：找到用户的目录

首先，你需要找到用户的 EventCatalog 项目，以便交叉参考现有资源。

询问：“你有可以让我查看的 EventCatalog 项目吗？如果有，项目在哪里？”

• 如果用户提供了路径，请检查 eventcatalog.config.js 或已知目录（services/、agents/、events/、domains/、systems/、flows/），确认这是一个 EventCatalog 项目。
• 如果用户已连接 EventCatalog MCP 服务，请使用 getResources 发现目录中的内容。
• 如果用户没有项目，也没关系——你可以将步骤记录为纯文本描述，不添加资源引用。请告知他们仍然可以创建有用的流程，之后再添加资源链接。

找到项目后，扫描目录并建立现有资源清单：

• 读取现有服务、Agent、事件、命令、查询、域、系统、通道、容器（数据存储）、数据产品和流程
• 记录它们的 ID、名称和版本——用户逐步描述流程时，你将用这些信息推荐匹配项

步骤 2：询问用户想记录什么流程

询问：“你想记录什么流程？请描述要记录的端到端过程。”

让用户用自己的话描述流程。示例：

• “用户注册后收到欢迎邮件，并被添加到我们的 CRM”
• “用户下单后处理付款、预留库存，最后发货”
• “客户提交支持工单后，工单会经过分类、分配给 Agent，最后得到解决”
• “支持 Agent 收到订单事件后，查找订单上下文并更新支持案例”

根据用户的描述，将流程拆分成若干章节（高层阶段）。将这些章节呈现给用户确认：

回答示例：

根据你的描述，我大致梳理出以下章节：

1. 用户注册 — 用户注册
2. 欢迎沟通 — 发送欢迎邮件
3. CRM 集成 — 将用户添加到 CRM

这样对吗？我们会逐一详细梳理。你可以随时添加、删除或重新排列章节。

等待用户确认后再继续。

步骤 3：逐一梳理每个章节

一次只梳理一个章节。对于每个章节，询问用户具体会发生什么。由用户主导对话——你跟随其节奏。

对于每个章节，可以这样询问：

“我们先从［章节名称］开始。这里会发生什么？由谁或什么触发？结果是什么？”

随着用户描述具体情况，你需要：

A. 识别步骤类型

根据描述，判断此部分涉及哪种或哪些步骤。每个步骤只能属于以下一种类型（具体格式请参阅 references/flows.md）：

• Actor — 某个人或角色执行某项操作（例如：“用户点击注册”，“管理员批准”）
• Service — 架构中的某个服务处理某项事务（例如：“我们的身份验证服务处理注册”）
• Agent — AI Agent 进行推理、调用工具或自动执行部分流程（例如：“退款 Agent 审查该案例”）
• Message — 交换事件、命令或查询（例如：“触发了一个 UserRegistered 事件”）
• Channel — 消息传输的通道（当这点很重要时），例如：“消息发送到 orders Kafka 主题”
• System — 整个系统参与其中，无论是内部还是外部系统（例如：“计费平台处理此事”）
• Container — 读取或写入数据存储（例如：“我们将其保存到 orders 数据库”）
• Data product — 生成或使用分析型数据产品
• Sub-flow — 流程转交给另一个有文档记录的流程（例如：“然后启动退款流程”）
• External System — 目录中未收录的第三方系统（例如：“我们调用 Stripe 处理付款”，“Twilio 发送短信”）
• Custom — 其他值得绘制的内容（例如：人工审核、UI、定时作业）
• Plain step — 不指向任何对象的带标题方框（例如：“取消请求被拒绝”）

单个部分可能会生成多个步骤（例如：用户操作触发一条命令，该命令由某个服务处理，而该服务又发出一个事件）。一个步骤不能同时属于两种类型——“服务发出事件”是两个步骤。

B. 交叉检索目录

对于用户描述的每个步骤，在其 EventCatalog（如果可用）中搜索匹配的资源：

1. 服务 — 用户提到的服务是否存在于目录中？按名称、ID 或相近词搜索。
2. Agent — 用户提到的 AI Agent、助手、copilot 或自主工作者是否存在于目录中？
3. 事件／命令／查询 — 用户描述的消息是否与已有文档匹配？查找完全匹配和相近匹配（例如，用户说“order created event” → 搜索 OrderCreated、OrderPlaced 等）。
4. 通道 — 是否有与此消息流转方式相关的通道？
5. 系统 — 这是有文档记录的系统吗（包括带有 scope: external 的外部系统，例如 Stripe）？如果是，优先使用 system 步骤，而不是 externalSystem。
6. 容器／数据产品 — 用户提到的数据存储或数据产品是否有文档记录？
7. 领域 — 此步骤是否属于有文档记录的领域？

如果找到匹配项，告知用户：

我在你的目录中找到了一个名为 [ResourceName]（版本 [version]）的 [resource type]，看起来与此匹配。你想在此步骤中引用它吗？

如果用户回答是，则在流程步骤中使用该资源实际的 id 和 version。

如果找到多个可能的匹配项，请列出来让用户选择：

我找到了几个可能与描述匹配的资源：

• OrderCreated（事件，v1.0.0）—“下新订单时发出”
• OrderPlaced（事件，v0.0.1）—“结账完成时发布”

哪一个符合你的情况？还是说这是一个新资源？

如果没有找到匹配项，完全没问题，但不要指向不存在的资源。指向缺失资源的 service、agent、message、channel、system、container、dataProduct 或 flow 会导致代码检查工具失败（refs/resource-exists，默认情况下属于错误）。询问用户希望如何处理：

• 先创建资源 — 使用 catalog-documentation-creator 技能为其编写文档，然后让步骤指向它。适用于确实存在的服务、Agent 和消息。
• 不使用指针描述 — 使用纯标题步骤（id + title + summary），或使用带图标的 custom 步骤。适用于暂时不想编写文档的内容。
• 如果是人员／角色，请使用 actor
• 如果是目录中没有的第三方工具／API，请使用 externalSystem

告知用户：“我在你的目录中没有找到这个资源。我会先[创建它／将其描述为纯步骤]。之后你可以为完整资源编写文档，再让此步骤指向它。”

C. 转到下一部分前确认当前部分

处理完一个部分后，总结该部分已记录的内容，并请用户确认，然后再进入下一部分。

示例：

以下是我为 Payment Processing 记录的内容：

1. 已发送 ProcessPayment 命令（匹配到你已有的 ProcessPayment 命令 v0.0.1）
2. PaymentService 处理付款（匹配到你已有的 PaymentService v1.2.0）
3. FraudReviewAgent 审查欺诈信号（匹配到你已有的 FraudReviewAgent v0.0.1）
4. 调用外部系统 Stripe 扣款
5. 已发出 PaymentProcessed 事件（目录中尚无此事件——要我先创建它，还是暂时将其描述为纯步骤？）

看起来正确吗？还有什么需要补充或修改的吗？

第 4 步：处理分支和边缘情况

逐节梳理时，留意以下情况：

• 分支路径 —“如果付款成功，我们就继续；如果失败，我们就通知用户”

  • 提问：“这里似乎有一个决策点。可能有哪些路径？”
  • 将这些路径记录为复数形式的 next_steps，并为每个分支添加标签

• 循环 —“如果外部调用失败，服务会重试”

  • 将其记录为一个步骤，并通过 next_step 引用前面的步骤

• 错误/失败路径 —“如果验证失败，我们就返回错误”

  • 这些是终止步骤，或分支到通知/错误处理步骤

• 并行路径 —“付款处理期间，我们也会预留库存”

  • 将其记录为从共同步骤分出的独立分支，并使用 next_steps

检测到分支时，请明确向用户确认这些路径：

“这里似乎有一个分岔点。在[步骤]之后，可能发生以下情况：

1. [成功路径] → 继续到[下一节]
2. [失败路径] → [后续处理]

是这样吗？还有其他结果吗？”

第 5 步：构建流程摘要

梳理完所有章节后，在生成文件之前，先提供完整的流程摘要：

以下是完整流程：[流程名称]

1. [步骤 1 摘要] → [步骤 2]
2. [步骤 2 摘要] → [步骤 3]
3. [步骤 3 摘要] → 分支到[步骤 4a]或[步骤 4b] ...

从你的目录中匹配到的资源：[匹配到的资源列表] 新资源（尚未加入目录）：[未匹配项列表]

准备好生成流程文件了吗？

第 6 步：生成流程文件

用户确认后，按照 references/flows.md 中的格式生成流程 index.mdx 文件。

生成规则：

1. 使用用户的目录。若保存位置不明确，请询问应将流程保存在哪里：flows/{FlowName}/index.mdx、domains/{Domain}/flows/{FlowName}/index.mdx，或根据目录结构放在系统下（systems/{System}/flows/{FlowName}/index.mdx）。如果流程属于某个领域或系统，还要将其添加到该领域或系统的 flows frontmatter 中——仅有文件夹并不能建立关联。

2. 对于已匹配的资源（已在目录中找到），使用目录中的确切 id 和 version。title 是可选的——默认使用资源名称，因此只有在其他标签更合适时才设置：

   - id: "payment_processing"
     service:
       id: "PaymentService"
       version: "1.2.0"
   

   Agent 步骤使用 agent 字段：

   - id: "fraud_review"
     agent:
       id: "FraudReviewAgent"
       version: "0.0.1"
   

   channel、system、container、data product 和子流程步骤在 channel、system、container、dataProduct 或 flow 下使用相同的 { id, version } 结构。

3. 对于用户选择暂不创建的未匹配资源，使用普通步骤（不带指针）或 custom 步骤：

   - id: "send_welcome_email"
     title: "Send Welcome Email"
     summary: "WelcomeEmailRequested is sent (not documented yet)"
   

4. 对于参与者，使用角色或人物设定的名称：

   - id: "user_initiates_signup"
     title: "User Signs Up"
     actor:
       name: "Customer"
   

5. 对于外部系统，如果已知，请填写名称、摘要和 URL：

   - id: "stripe_charges_card"
     title: "Stripe Payment"
     externalSystem:
       name: "Stripe"
       summary: "Third-party payment processor"
       url: "https://stripe.com"
   

6. 根据实际情况，使用 next_step 或 next_steps 连接所有步骤。

7. 终止步骤（流程结束或分支结束）不应包含 next_step。

8. 正文应为 <NodeGraph />。

   不要在步骤中添加 type 字段（该字段会被忽略），自定义步骤元数据应放在 x- 键中——未知键会导致构建失败。

9. 新流程的 version 设为 0.0.1。

10. 撰写有意义的 summary，描述端到端业务流程。

步骤 7：验证并写入

写入文件之前：

1. 验证流程中的所有步骤 ID 都是唯一的
2. 验证所有 next_step / next_steps 引用都指向有效的步骤 ID，并且没有步骤同时包含这两者
3. 验证每个指针都与目录中的资源 ID 匹配（如果设置了版本，也要匹配版本）
4. 验证没有步骤同时指向两个对象，并且不存在未知键（自定义键必须以 x- 开头）
5. 验证 YAML frontmatter 有效
6. 验证正文中包含 <NodeGraph />

将文件写入用户的目录。如果目录中有 lint 脚本（通过 create-eventcatalog 创建的目录会运行 eventcatalog-linter），请运行 npm run lint 并修复其报告的问题。

写入后，告知用户：

• 文件的保存位置
• 从其目录中匹配到的资源
• 新建／未匹配的资源——建议他们稍后使用 catalog-documentation-creator 技能记录这些资源，尤其是新的 Agent
• 他们可以运行开发服务器，在 EventCatalog 中查看流程可视化，并在流程页面按域、系统或团队分组（也可以使用 <Flow id="..." lanes="team" /> 打开按团队分组的视图）

对话指南

• 由用户主导。 你负责提问和引导，但由用户用自己的话描述流程。不要假设或编造步骤。
• 一次讨论一个部分。 不要急着推进。确认每个部分后再继续。
• 积极寻找匹配项。 找到与目录资源匹配的内容时，主动提出建议，但始终让用户决定。
• 如实说明未匹配项。 如果目录中没有匹配项，请直说，并以描述性方式记录。
• 保持对话自然。 这是一个引导式流程，不是要填写的表单。自然、灵活地回应。
• 提出建议，而非强行规定。 如果用户的描述与步骤类型不完全匹配，请提出你认为合适的类型并询问是否正确。
• 妥善处理复杂情况。 如果流程变得复杂（有很多分支或循环），请定期帮助用户梳理并总结。

搜索目录

搜索匹配资源时，请使用以下策略：

1. 精确 ID 匹配——搜索提到的确切名称（例如，“OrdersService” → 查找 OrdersService）
2. 模糊匹配——搜索变体（例如，“orders service” → 尝试 OrdersService、OrderService、orders-service）
3. 语义匹配——如果用户说“处理付款的东西”，请搜索名称或摘要中包含“payment”的服务
4. 按类型浏览——如果你知道它是一个事件，请专门搜索事件
5. Agent 相关词——如果用户说“助手”“副驾驶”“工作器”“审阅者”或“Agent”，请先搜索 agents/，再将其视为外部系统

如果 EventCatalog MCP 服务可用：

• 使用 getResources 列出所有资源
• 使用 getResource 获取特定资源的详细信息
• 使用 findResourcesByOwner 按团队探索资源

如果直接读取文件系统：

• 查看 services/、agents/、events/、commands/、queries/、domains/、systems/、flows/、channels/、containers/、data-products/ 目录（这些目录也可能嵌套在域和系统目录下）
• 阅读 index.mdx 文件，检查 id、name、version 和 summary 字段

质量检查清单

交付流程文件前：

1. 每个步骤都有唯一的 id
2. 每个步骤都有清晰的标签，即 title，或名称易读的资源指针（默认将其作为标题）
3. 每个步骤至多表示一种事物（actor、service、agent、message、channel、system、container、dataProduct、flow、custom 或 externalSystem），且没有 type 字段
4. 所有 next_step 和 next_steps 引用都指向流程中的有效步骤 ID
5. 没有孤立步骤（除分支外，每个步骤都能从第一步到达）
6. 每个指针都与目录中的资源匹配（不能使用占位符，否则 refs/resource-exists 检查会失败）
7. 流程有明确的起点（第一步）和至少一个终止步骤（没有 next_step）
8. YAML frontmatter 格式有效，并使用 --- 分隔
9. 文件名为 index.mdx
10. 正文中包含 <NodeGraph />
11. version 是有效的 semver 字符串
12. summary 有意义地描述业务流程