flow-wizard

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Flow Documentation Wizard

流程文档向导

An interactive, conversational skill that guides users through documenting business flows in EventCatalog — step by step, section by section — while cross-referencing their existing catalog resources.

这是一个交互式的对话式技能，可引导用户在EventCatalog中逐步、分节地记录业务流程，同时交叉引用其现有目录资源。

Instructions

操作说明

Step 1: Locate the User's Catalog

步骤1：定位用户的目录

Before anything else, you need to find the user's EventCatalog project so you can cross-reference existing resources.

Ask: "Do you have an EventCatalog project I can look at? If so, where is it?"

If they provide a path, verify it's an EventCatalog project by checking for
```
eventcatalog.config.js
```
or known directories (
```
services/
```
,
```
events/
```
,
```
domains/
```
,
```
flows/
```
).
If they have the EventCatalog MCP server connected, use
```
getResources
```
to discover what's in the catalog.
If they don't have one, that's fine — you'll document steps as plain text descriptions without resource references. Let them know they can still create a useful flow and add resource links later.

Once located, scan the catalog to build an inventory of existing resources:

Read existing services, events, commands, queries, domains, channels, and flows
Note their IDs, names, and versions — you'll use these to suggest matches as the user walks through their flow

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

询问：「你有可供查看的EventCatalog项目吗？如果有，它的位置在哪里？」

如果用户提供路径，通过检查是否存在
```
eventcatalog.config.js
```
文件或已知目录（
```
services/
```
、
```
events/
```
、
```
domains/
```
、
```
flows/
```
）来验证它是否为EventCatalog项目。
如果用户已连接EventCatalog MCP服务器，使用
```
getResources
```
来发现目录中的内容。
如果用户没有项目也没关系——你可以以纯文本描述的形式记录步骤，无需引用资源。告知用户他们仍可创建有用的流程，之后再添加资源链接。

定位到项目后，扫描目录以构建现有资源清单：

读取现有的服务、事件、命令、查询、领域、渠道和流程
记录它们的ID、名称和版本——在用户梳理流程时，你将用这些信息来建议匹配项

Step 2: Ask What Flow They Want to Document

步骤2：询问用户要记录的流程

Ask: "What flow would you like to document? Describe the end-to-end process you're trying to capture."

Let the user describe the flow in their own words. Examples:

"User signs up, gets a welcome email, and is added to our CRM"
"Order is placed, payment is processed, inventory is reserved, and the order is shipped"
"A customer submits a support ticket, it gets triaged, assigned to an agent, and resolved"

From their description, break the flow into sections (high-level stages). Present these sections back to the user for confirmation:

Example response:

Based on your description, I can see roughly these sections:

User Registration — the user signs up

Welcome Communication — welcome email is sent

CRM Integration — user is added to the CRM

Does that look right? We'll walk through each one in detail. Feel free to add, remove, or reorder sections.

Wait for confirmation before proceeding.

询问：「你想要记录什么流程？描述一下你想要捕捉的端到端过程。」

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

「用户注册、收到欢迎邮件并被添加到我们的CRM系统」
「下单、处理支付、预留库存并发货」
「客户提交支持工单、工单被分类、分配给Agent并解决」

根据用户的描述，将流程拆分为多个章节（高级阶段）。将这些章节反馈给用户确认：

示例回复：

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

用户注册——用户完成注册

欢迎沟通——发送欢迎邮件

CRM集成——用户被添加到CRM系统

这样是否正确？我们将逐一详细梳理。你可以添加、删除或调整章节顺序。

等待用户确认后再继续。

Step 3: Walk Through Each Section

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

Go through each section one at a time. For each section, ask the user to describe what happens. The user leads the conversation — you follow.

For each section, ask something like:

"Let's start with [Section Name]. What happens here? Who or what triggers it, and what happens as a result?"

As the user describes what happens, you need to:

逐个处理每个章节。对于每个章节，让用户描述具体发生的事情。用户主导对话——你配合引导。

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

「我们从[章节名称]开始。这里发生了什么？触发因素是什么，结果又是什么？」

用户描述过程时，你需要：

A. Identify the Step Type

A. 识别步骤类型

From their description, determine which flow step type(s) this section involves:

Actor — a person or role does something (e.g., "the user clicks sign up", "the admin approves")
Service — a service in their architecture processes something (e.g., "our auth service handles registration")
Message — an event, command, or query is exchanged (e.g., "a UserRegistered event is fired")
External System — a third-party system is involved (e.g., "we call Stripe for payment", "Twilio sends the SMS")

A single section may produce multiple steps (e.g., a user action triggers a command, which is handled by a service, which emits an event).

根据用户的描述，判断该章节涉及的流程步骤类型：

参与者（Actor）——某人或某个角色执行操作（例如：「用户点击注册」「管理员批准」）
服务（Service）——架构中的某个服务处理任务（例如：「我们的认证服务处理注册」）
消息（Message）——交换事件、命令或查询（例如：「触发UserRegistered事件」）
外部系统（External System）——涉及第三方系统（例如：「调用Stripe处理支付」「Twilio发送短信」）

单个章节可能包含多个步骤（例如：用户操作触发命令，由服务处理，进而发出事件）。

B. Cross-Reference the Catalog

B. 交叉引用目录

For each step the user describes, search their EventCatalog (if available) for matching resources:

Services — Does the service they mention exist in the catalog? Search by name, ID, or similar terms.
Events/Commands/Queries — Does the message they describe match something already documented? Look for exact matches and close matches (e.g., user says "order created event" → search for
```
OrderCreated
```
,
```
OrderPlaced
```
, etc.).
Channels — Are there channels relevant to how this message flows?
Domains — Does this step fall within a documented domain?

If you find a match, tell the user:

I found a [resource type] called
[ResourceName]
(version
[version]
) in your catalog that looks like it matches. Would you like to reference it in this step?

If they say yes, use the resource's actual

id

and

version

in the flow step.

If you find multiple possible matches, present them and let the user choose:

I found a few resources that might match what you're describing:
OrderCreated
(event, v1.0.0) — "Emitted when a new order is placed"
OrderPlaced
(event, v0.0.1) — "Published when checkout completes"
Which one fits, or is this something new?

If you find no match, that's perfectly fine. Document it as a descriptive step:

If it sounds like a service, use
```
service
```
type with a suggested ID and note it's not yet in the catalog
If it sounds like a message, use
```
message
```
type with a suggested ID
If it's a person/role, use
```
actor
```
type
If it's a third-party tool/API, use
```
externalSystem
```
type

Let the user know: "I didn't find this in your catalog. I'll document it as [step type] for now. You can create the full resource later if you'd like."

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

服务——用户提到的服务是否存在于目录中？按名称、ID或相似术语搜索。
事件/命令/查询——用户描述的消息是否与已记录的内容匹配？查找完全匹配和近似匹配（例如：用户说「订单创建事件」→ 搜索
```
OrderCreated
```
、
```
OrderPlaced
```
等）。
渠道——是否有与消息流转相关的渠道？
领域——该步骤是否属于已记录的领域？

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

我在你的目录中找到一个**[资源类型]**，名为
[ResourceName]
（版本
[version]
），看起来与描述匹配。你想要在本步骤中引用它吗？

如果用户同意，在流程步骤中使用该资源的实际

id

和

version

。

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

我找到几个可能匹配你描述的资源：
OrderCreated
（事件，v1.0.0）——「新订单下单时触发」
OrderPlaced
（事件，v0.0.1）——「结账完成时发布」
哪个更符合，还是这是一个新的资源？

如果没有找到匹配项也没关系。将其记录为描述性步骤：

如果听起来是服务，使用
```
service
```
类型并建议一个ID，同时注明它尚未在目录中
如果听起来是消息，使用
```
message
```
类型并建议一个ID
如果是人员/角色，使用
```
actor
```
类型
如果是第三方工具/API，使用
```
externalSystem
```
类型

告知用户：「我在你的目录中没有找到这个资源。我暂时将其记录为[步骤类型]。之后你可以创建完整的资源。」

C. Confirm Each Section Before Moving On

C. 确认每个章节后再进入下一个

After processing a section, summarize what you've captured for that section and ask the user to confirm before moving to the next one.

Example:

Here's what I've captured for Payment Processing:
ProcessPayment
command is sent (matched to your existing
ProcessPayment
command v0.0.1)
PaymentService
handles the payment (matched to your existing
PaymentService
v1.2.0)
Calls Stripe (external system) to charge the card
PaymentProcessed
event is emitted (not in your catalog yet — I'll use a placeholder)
Does that look right? Anything to add or change?

处理完一个章节后，总结已捕捉到的内容并请用户确认，再进入下一个章节。

示例：

这是我捕捉到的「支付处理」章节内容：
发送
ProcessPayment
命令（匹配你现有的
ProcessPayment
命令v0.0.1）
PaymentService
处理支付（匹配你现有的
PaymentService
v1.2.0）
调用Stripe（外部系统）收取费用
触发
PaymentProcessed
事件（尚未在你的目录中——我将使用占位符）
这样是否正确？有没有需要添加或修改的内容？

Step 4: Handle Branching and Edge Cases

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

As you walk through sections, watch for:

Branching paths — "If payment succeeds, we continue; if it fails, we notify the user"
- Ask: "It sounds like there's a decision point here. What are the possible paths?"
- Document these as
```
next_steps
```
  (plural) with labels for each branch
Loops — "The service retries if the external call fails"
- Document as a step that references back to an earlier step via
```
next_step
```
Error/failure paths — "If validation fails, we send back an error"
- These are terminal steps or branch to a notification/error handling step
Parallel paths — "While payment processes, we also reserve inventory"
- Document as separate branches from a common step using
```
next_steps
```

When you detect branching, explicitly confirm the paths with the user:

"It sounds like there's a fork here. After [step], these things could happen:

[Success path] → continues to [next section]

[Failure path] → [what happens]

Is that right? Are there other outcomes?"

梳理章节时，注意以下情况：

分支路径——「如果支付成功，我们继续；如果失败，通知用户」询问：「这里似乎有一个决策点。可能的路径有哪些？」 将这些路径记录为带标签的
```
next_steps
```
（复数）
循环——「如果外部调用失败，服务会重试」将其记录为通过
```
next_step
```
引用之前步骤的步骤
错误/失败路径——「如果验证失败，我们返回错误」这些是终端步骤或分支到通知/错误处理步骤
并行路径——「处理支付的同时，我们预留库存」使用
```
next_steps
```
将其记录为从公共步骤分出的独立分支

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

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

[成功路径] → 进入[下一章节]

[失败路径] → [具体操作]

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

Step 5: Build the Flow Summary

步骤5：生成流程摘要

After walking through all sections, present a complete summary of the flow before generating the file:

Here's the complete flow: [Flow Name]

[Step 1 summary] → [Step 2]

[Step 2 summary] → [Step 3]

[Step 3 summary] → branches to [Step 4a] or [Step 4b] ...

Resources matched from your catalog: [list of matched resources] New resources (not yet in catalog): [list of unmatched items]

Ready to generate the flow file?

梳理完所有章节后，在生成文件前展示完整的流程摘要：

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

[步骤1摘要] → [步骤2]

[步骤2摘要] → [步骤3]

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

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

准备生成流程文件了吗？

Step 6: Generate the Flow File

步骤6：生成流程文件

Once the user confirms, generate the flow

index.mdx

file following the format in

references/flows.md

Rules for generation:

Use the user's catalog directory. Ask where the flow should be saved if unclear — either
```
flows/{FlowName}/index.mdx
```
or
```
domains/{Domain}/flows/{FlowName}/index.mdx
```
depending on their catalog structure.

For matched resources (found in catalog), use the exact

id

and

version

from the catalog:

yaml

- id: "payment_processing"
  title: "Payment Service"
  service:
    id: "PaymentService"
    version: "1.2.0"

For unmatched resources (not in catalog), use descriptive IDs and version

0.0.1

yaml

- id: "send_welcome_email"
  title: "Send Welcome Email"
  message:
    id: "WelcomeEmailRequested"
    version: "0.0.1"

For actors, use the role or persona name:

yaml

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

For external systems, include name, summary, and URL if known:

yaml

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

Connect all steps with
```
next_step
```
or
```
next_steps
```
as appropriate.
Terminal steps (end of flow or end of a branch) should have no
```
next_step
```
.
The body should be
```
<NodeGraph />
```
.
Set
```
version
```
to
```
0.0.1
```
for new flows.
Write a meaningful
```
summary
```
that describes the end-to-end business process.

用户确认后，按照

references/flows.md

中的格式生成流程

index.mdx

文件。

生成规则：

使用用户的目录目录。如果不确定保存位置，询问用户——根据目录结构，保存到
```
flows/{FlowName}/index.mdx
```
或
```
domains/{Domain}/flows/{FlowName}/index.mdx
```
。

对于匹配的资源（在目录中找到的），使用目录中的精确

id

和

version

：

yaml

- id: "payment_processing"
  title: "Payment Service"
  service:
    id: "PaymentService"
    version: "1.2.0"

对于未匹配的资源（不在目录中），使用描述性ID和版本

0.0.1

：

yaml

- id: "send_welcome_email"
  title: "Send Welcome Email"
  message:
    id: "WelcomeEmailRequested"
    version: "0.0.1"

对于参与者（Actor），使用角色或用户画像名称：

yaml

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

对于外部系统，包含名称、摘要和已知的URL：

yaml

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

根据情况使用
```
next_step
```
或
```
next_steps
```
连接所有步骤。
终端步骤（流程结束或分支结束）不应包含
```
next_step
```
。
主体内容应为
```
<NodeGraph />
```
。
新流程的
```
version
```
设置为
```
0.0.1
```
。
撰写有意义的
```
summary
```
，描述端到端的业务流程。

Step 7: Validate and Write

步骤7：验证并写入文件

Before writing the file:

Verify all step IDs are unique within the flow
Verify all
```
next_step
```
/
```
next_steps
```
references point to valid step IDs
Verify matched resource IDs and versions are correct
Verify the YAML frontmatter is valid
Verify
```
<NodeGraph />
```
is in the body

Write the file to the user's catalog directory.

After writing, let the user know:

Where the file was saved
Which resources were matched from their catalog
Which resources are new/unmatched — suggest they can document these later using the
```
catalog-documentation-creator
```
skill
They can view the flow visualization in EventCatalog by running their dev server

写入文件前：

验证流程内所有步骤ID唯一
验证所有
```
next_step
```
/
```
next_steps
```
引用指向流程内有效的步骤ID
验证匹配资源的ID和版本正确
验证YAML前置内容有效
验证主体中包含
```
<NodeGraph />
```

写入完成后，告知用户：

文件保存位置
从目录中匹配的资源有哪些
哪些是新的/未匹配的资源——建议他们之后使用
```
catalog-documentation-creator
```
技能记录这些资源
他们可以通过运行开发服务器在EventCatalog中查看流程可视化效果

Conversation Guidelines

对话指南

The user leads. You ask questions and guide, but the user describes what happens in their own words. Don't assume or invent steps.
One section at a time. Don't rush ahead. Confirm each section before moving on.
Be helpful with matches. When you find catalog resources that match, proactively suggest them — but always let the user decide.
Be honest about misses. If nothing in the catalog matches, say so plainly and document it descriptively.
Keep it conversational. This is a guided walkthrough, not a form to fill out. Be natural and responsive.
Suggest, don't dictate. If the user's description doesn't perfectly map to a step type, suggest what you think fits and ask if that's right.
Handle complexity gracefully. If a flow gets complex (many branches, loops), help the user keep track by summarizing periodically.

用户主导。你负责提问和引导，但流程内容由用户自行描述。不要假设或编造步骤。
逐个章节处理。不要急于推进。确认每个章节后再进入下一个。
主动提供匹配建议。找到目录中匹配的资源时，主动向用户推荐，但最终决定权在用户手中。
如实告知未匹配情况。如果目录中没有匹配项，直接说明并以描述性方式记录。
保持对话自然。这是引导式梳理，不是填写表单。语气要自然、响应及时。
建议而非指令。如果用户的描述与步骤类型不完全匹配，提出你的建议并询问是否正确。
从容应对复杂情况。如果流程变得复杂（多个分支、循环），定期总结帮助用户跟踪进度。

Searching the Catalog

目录搜索策略

When searching for matching resources, use these strategies:

Exact ID match — search for the exact name mentioned (e.g., "OrdersService" → look for
```
OrdersService
```
)
Fuzzy match — search for variations (e.g., "orders service" → try
```
OrdersService
```
,
```
OrderService
```
,
```
orders-service
```
)
Semantic match — if the user says "the thing that handles payments", search for services with "payment" in the name or summary
Browse by type — if you know it's an event, search events specifically

If the EventCatalog MCP server is available:

Use
```
getResources
```
to list all resources
Use
```
getResource
```
to get details on a specific resource
Use
```
findResourcesByOwner
```
to explore resources by team

If reading the filesystem directly:

Look in

services/

events/

commands/

queries/

domains/

flows/

channels/

directories

Read
```
index.mdx
```
files to check
```
id
```
,
```
name
```
,
```
version
```
, and
```
summary
```
fields

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

精确ID匹配——搜索用户提到的精确名称（例如：「OrdersService」→ 查找
```
OrdersService
```
）
模糊匹配——搜索变体（例如：「orders service」→ 尝试
```
OrdersService
```
、
```
OrderService
```
、
```
orders-service
```
）
语义匹配——如果用户说「处理支付的服务」，搜索名称或摘要中包含「payment」的服务
按类型浏览——如果知道是事件，专门搜索事件

如果EventCatalog MCP服务器可用：

使用
```
getResources
```
列出所有资源
使用
```
getResource
```
获取特定资源的详细信息
使用
```
findResourcesByOwner
```
按团队浏览资源

如果直接读取文件系统：

查看

services/

、

events/

、

commands/

、

queries/

、

domains/

、

flows/

、

channels/

读取
```
index.mdx
```
文件以检查
```
id
```
、
```
name
```
、
```
version
```
和
```
summary
```
字段

Quality Checklist

质量检查清单

Before delivering the flow file:

Every step has a unique
```
id
```
Every step has a
```
title
```
Every step has exactly one type (
```
actor
```
,
```
service
```
,
```
message
```
, or
```
externalSystem
```
)
All
```
next_step
```
and
```
next_steps
```
references point to valid step IDs within the flow
No orphaned steps (every step is reachable from the first step, except via branching)
Matched resources use correct
```
id
```
and
```
version
```
from the catalog
The flow has a clear start (first step) and at least one terminal step (no
```
next_step
```
)
YAML frontmatter is valid with
```
---
```
delimiters
File is named
```
index.mdx
```
```
<NodeGraph />
```
is in the body
```
version
```
is a valid semver string
```
summary
```
describes the business process meaningfully

交付流程文件前：

每个步骤都有唯一的
```
id
```
每个步骤都有
```
title
```
每个步骤恰好属于一种类型（
```
actor
```
、
```
service
```
、
```
message
```
或
```
externalSystem
```
）
所有
```
next_step
```
和
```
next_steps
```
引用指向流程内有效的步骤ID
没有孤立步骤（除分支外，每个步骤都可从第一个步骤到达）
匹配资源使用目录中正确的
```
id
```
和
```
version
```
流程有明确的起点（第一个步骤）和至少一个终端步骤（无
```
next_step
```
）
YAML前置内容有效，包含
```
---
```
分隔符
文件名为
```
index.mdx
```
主体中包含
```
<NodeGraph />
```
```
version
```
是有效的语义化版本字符串
```
summary
```
有意义地描述了业务流程