flowzap-diagrams

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

FlowZap Diagram Skill

FlowZap 图表技能

Generate valid FlowZap Code (.fz) diagrams from natural-language descriptions, validate them, and return shareable playground URLs — all without leaving your coding agent.

从自然语言描述生成有效的FlowZap Code（.fz）图表，验证它们，并返回可分享的在线演示链接——全程无需离开你的代码代理工具。

When to use this skill

何时使用此技能

User asks for a workflow, flowchart, process diagram, or sequence diagram.
User pastes HTTP logs, OpenAPI specs, or code and wants them visualised.
User wants to compare two diagram versions (diff) or patch an existing diagram.

用户需要创建工作流、流程图、流程图表或序列图时
用户粘贴HTTP日志、OpenAPI规范或代码，希望将其可视化时
用户想要对比两个图表版本（差异对比）或修补现有图表时

MCP server setup (one-time)

MCP服务器设置（一次性操作）

If the FlowZap MCP server is not already configured, install it:

bash

undefined

如果尚未配置FlowZap MCP服务器，请按以下步骤安装：

bash

undefined

Claude Code

claude mcp add --transport stdio flowzap -- npx -y flowzap-mcp@1.3.5

Or add to .mcp.json / claude_desktop_config.json / cursor / windsurf config:

或添加到 .mcp.json / claude_desktop_config.json / cursor / windsurf 配置文件中：

{ "mcpServers": { "flowzap": { "command": "npx", "args": ["-y", "flowzap-mcp@1.3.5"] } } }


Compatible tools: Claude Desktop, Claude Code, Cursor, Windsurf, OpenAI Codex,
Warp, Zed, Cline, Roo Code, Continue.dev, Sourcegraph Cody.

**Not compatible (use public API instead):** Replit, Lovable.dev.

{ "mcpServers": { "flowzap": { "command": "npx", "args": ["-y", "flowzap-mcp@1.3.5"] } } }


兼容工具：Claude Desktop、Claude Code、Cursor、Windsurf、OpenAI Codex、Warp、Zed、Cline、Roo Code、Continue.dev、Sourcegraph Cody。

**不兼容工具（请改用公共API）：** Replit、Lovable.dev。

Available MCP tools

可用的MCP工具

Tool	Purpose
`flowzap_validate`	Check .fz syntax before sharing
`flowzap_create_playground`	Get a shareable playground URL
`flowzap_get_syntax`	Retrieve full DSL docs at runtime
`flowzap_export_graph`	Export diagram as structured JSON (lanes, nodes, edges)
`flowzap_artifact_to_diagram`	Parse HTTP logs / OpenAPI / code → diagram + playground URL
`flowzap_diff`	Structured diff between two .fz versions
`flowzap_apply_change`	Patch a diagram (insert/remove/update nodes/edges)

工具	用途
`flowzap_validate`	分享前检查.fz语法
`flowzap_create_playground`	获取可分享的在线演示链接
`flowzap_get_syntax`	运行时获取完整DSL文档
`flowzap_export_graph`	将图表导出为结构化JSON（泳道、节点、边）
`flowzap_artifact_to_diagram`	解析HTTP日志/OpenAPI/代码 → 生成图表+在线演示链接
`flowzap_diff`	两个.fz版本之间的结构化差异对比
`flowzap_apply_change`	修补图表（插入/删除/更新节点/边）

FlowZap Code DSL — quick reference

FlowZap Code DSL — 快速参考

FlowZap Code is not Mermaid, not PlantUML. It is a unique DSL.

FlowZap Code 不是 Mermaid，也不是 PlantUML。它是一种独特的DSL。

Shapes (only 4)

形状（仅4种）

Shape	Use for
`circle`	Start / End events
`rectangle`	Process steps / actions
`diamond`	Decisions (Yes/No branching)
`taskbox`	Assigned tasks ( `owner` , `description` , `system` )

形状	用途
`circle`	开始/结束事件
`rectangle`	流程步骤/操作
`diamond`	决策（是/否分支）
`taskbox`	分配的任务（ `owner` 、 `description` 、 `system` ）

Syntax rules

语法规则

Node IDs are globally unique, sequential, no gaps:
```
n1
```
,
```
n2
```
,
```
n3
```
…
Node attributes use colon:
```
label:"Text"
```
Edge labels use equals inside brackets:
```
[label="Text"]
```
Handles are required on every edge:
```
n1.handle(right) -> n2.handle(left)
```
Directions:
```
left
```
,
```
right
```
,
```
top
```
,
```
bottom
```
Cross-lane edges: prefix target with lane name:
```
sales.n5.handle(top)
```
Lane display label: one
```
# Label
```
comment right after opening brace
Loops:
```
loop [condition] n1 n2 n3
```
— flat, inside a lane block
Layout: prefer horizontal left→right; use top/bottom only for cross-lane hops

节点ID 全局唯一、连续无间隔：
```
n1
```
、
```
n2
```
、
```
n3
```
……
节点属性 使用冒号：
```
label:"Text"
```
边标签 在括号内使用等号：
```
[label="Text"]
```
每个边都必须包含句柄：
```
n1.handle(right) -> n2.handle(left)
```
方向：
```
left
```
、
```
right
```
、
```
top
```
、
```
bottom
```
跨泳道边：目标节点前添加泳道名称前缀：
```
sales.n5.handle(top)
```
泳道显示标签：在左大括号后添加一个
```
# Label
```
注释
循环：
```
loop [condition] n1 n2 n3
```
—— 平级放置在泳道块内部
布局：优先使用水平从左到右；仅在跨泳道跳转时使用上下方向

Gotchas — never do these

注意事项——切勿执行以下操作

Do NOT use
```
label="Text"
```
on nodes (must be
```
label:"Text"
```
).
Do NOT use
```
label:"Text"
```
on edges (must be
```
[label="Text"]
```
).
Do NOT skip node numbers (n1, n3 → invalid; must be n1, n2).
Do NOT omit lane prefix on cross-lane edges.
Do NOT output Mermaid, PlantUML, or any other syntax.
Do NOT add comments except the single
```
# Display Label
```
per lane.
Do NOT place
```
loop
```
outside a lane's braces.
Do NOT use a
```
taskbox
```
shape unless the user explicitly requests it.

不要在节点上使用
```
label="Text"
```
（必须是
```
label:"Text"
```
）
不要在边上使用
```
label:"Text"
```
（必须是
```
[label="Text"]
```
）
不要跳过节点编号（n1、n3 → 无效；必须是n1、n2）
跨泳道边不要省略泳道前缀
不要输出Mermaid、PlantUML或任何其他语法
除了每个泳道的单个
```
# 显示标签
```
注释外，不要添加其他注释
不要将
```
loop
```
放在泳道的大括号外部
除非用户明确要求，否则不要使用
```
taskbox
```
形状

Minimal templates

最小模板

Single lane:

process { # Process
n1: circle label:"Start"
n2: rectangle label:"Step"
n3: circle label:"End"
n1.handle(right) -> n2.handle(left)
n2.handle(right) -> n3.handle(left)
}

Two lanes with cross-lane edge:

user { # User
n1: circle label:"Start"
n2: rectangle label:"Submit"
n1.handle(right) -> n2.handle(left)
n2.handle(bottom) -> app.n3.handle(top) [label="Send"]
}

app { # App
n3: rectangle label:"Process"
n4: circle label:"Done"
n3.handle(right) -> n4.handle(left)
}

Decision branch:

flow { # Flow
n1: rectangle label:"Check"
n2: diamond label:"OK?"
n3: rectangle label:"Fix"
n4: rectangle label:"Proceed"
n1.handle(right) -> n2.handle(left)
n2.handle(bottom) -> n3.handle(top) [label="No"]
n2.handle(right) -> n4.handle(left) [label="Yes"]
}

For the full DSL specification and advanced multi-lane examples: See references/syntax.md

单泳道：

process { # 流程
n1: circle label:"开始"
n2: rectangle label:"步骤"
n3: circle label:"结束"
n1.handle(right) -> n2.handle(left)
n2.handle(right) -> n3.handle(left)
}

带跨泳道边的双泳道：

user { # 用户
n1: circle label:"开始"
n2: rectangle label:"提交"
n1.handle(right) -> n2.handle(left)
n2.handle(bottom) -> app.n3.handle(top) [label="发送"]
}

app { # 应用
n3: rectangle label:"处理"
n4: circle label:"完成"
n3.handle(right) -> n4.handle(left)
}

决策分支：

flow { # 流程
n1: rectangle label:"检查"
n2: diamond label:"是否正常？"
n3: rectangle label:"修复"
n4: rectangle label:"继续"
n1.handle(right) -> n2.handle(left)
n2.handle(bottom) -> n3.handle(top) [label="否"]
n2.handle(right) -> n4.handle(left) [label="是"]
}

完整DSL规范和高级多泳道示例：请查看 references/syntax.md

Workflow: how to generate a diagram

工作流：如何生成图表

Identify the actors/systems (→ lanes) and steps (→ nodes) from the user's description.
Write FlowZap Code following all rules above.
Call
```
flowzap_validate
```
to verify syntax.
If valid, call
```
flowzap_create_playground
```
to get a shareable URL.
Return the FlowZap Code and the playground URL to the user.
Always output only raw FlowZap Code when showing the diagram — no Markdown fences wrapping .fz content, no extra commentary mixed in.

从用户描述中识别参与者/系统（→ 泳道）和步骤（→ 节点）
按照上述所有规则编写FlowZap Code
调用
```
flowzap_validate
```
验证语法
如果验证通过，调用
```
flowzap_create_playground
```
获取可分享链接
向用户返回FlowZap Code 和在线演示链接
展示图表时，始终只输出原始FlowZap Code——不要用Markdown围栏包裹.fz内容，不要混入额外评论

Fallback: public API (no MCP)

备选方案：公共API（无需MCP）

If the MCP server is unavailable, use the public REST API (no auth required):

Validate:
```
POST /api/validate
```
with
```
{"code": "..."}
```
body

Create playground:

POST /api/playground/create

with

{"code": "..."}

body (5/min, 50/day)

Privacy: The flowzap.xyz API does not store user data. Sessions expire after 15 minutes.

Full API documentation: flowzap.xyz/docs/mcp

如果MCP服务器不可用，使用公共REST API（无需认证）：

验证：
```
POST /api/validate
```
，请求体为
```
{"code": "..."}
```
创建在线演示：
```
POST /api/playground/create
```
，请求体为
```
{"code": "..."}
```
（限制：每分钟5次，每天50次）

隐私说明： flowzap.xyz API不会存储用户数据。会话15分钟后过期。

完整API文档：flowzap.xyz/docs/mcp

flowzap-diagrams

Original

Translation

FlowZap Diagram Skill

FlowZap 图表技能

When to use this skill

何时使用此技能

MCP server setup (one-time)

MCP服务器设置（一次性操作）

Claude Code

Claude Code

Or add to .mcp.json / claude_desktop_config.json / cursor / windsurf config:

或添加到 .mcp.json / claude_desktop_config.json / cursor / windsurf 配置文件中：

Available MCP tools

可用的MCP工具

FlowZap Code DSL — quick reference

FlowZap Code DSL — 快速参考

Shapes (only 4)

形状（仅4种）

Syntax rules

语法规则

Gotchas — never do these

注意事项——切勿执行以下操作

Minimal templates

最小模板

Workflow: how to generate a diagram

工作流：如何生成图表

Fallback: public API (no MCP)

备选方案：公共API（无需MCP）

Further resources

更多资源