Welcome to FlowZap dear Business Process Maniacs!

FlowZap 推出全新 .fz 扩展名：面向序列图和 AI 原生工作流的真正“图即代码”

2025/11/20

Tags: FlowZap Code, .fz, Diagrams as Code, 序列图, AI

Jules Kovac

Jules Kovac

Business Analyst, Founder

FlowZap 推出全新 .fz 扩展名：面向序列图和 AI 原生工作流的真正“图即代码”

FlowZap 推出了三项紧密相关的功能：全新的 .fz 文件格式、图表编辑器中的 保存为 .fz 和 加载 .fz 操作，以及一个供您的 /docs/ 文件夹使用的、面向 LLM 的 flowzap-code-guidelines.md 文件。它们共同将 FlowZap 转变为一个实用的序列图“图即代码（Diagrams as Code）”平台——特别是对于使用 Cursor、Windsurf、Warp 或 Google AI Studio 等 AI 编码工具的开发者而言。

所有渲染仍然在 FlowZap web 应用程序中进行：.fz 文件仅包含 FlowZap Code 文本，当您在 flowzap.xyz 上加载它们时即可实现可视化。

“图即代码”的真正含义

从本质上讲，图即代码 意味着您用文本描述图表，将该文本存储在版本控制（通常是 Git）中，并使用工具按需渲染可视化图表。您不再需要在 GUI 中手动绘制框和箭头，而是：

  • 在代码库中将图表定义编写为简单的文本文件。
  • 像提交和审查任何其他源文件一样提交和审查它们。
  • 随时从该文本重新生成可视化图表。

这种方法使图表与代码库保持同步，通过拉取请求（Pull Request）使更改可审查，并自然地与“文档即代码（docs-as-code）”实践集成。FlowZap 的 .fz 格式和 FlowZap Code 语言专为将这些优势带给工作流和序列图而设计。

.fz 文件格式：文本优先的序列图

新的 .fz 格式是一个纯文本、UTF-8 文件，仅 包含 FlowZap Code——没有嵌入的图像或二进制数据。.fz 文件是图表的唯一真实来源；FlowZap 读取它并从同一文本渲染工作流视图和序列视图。

主要特点：

  • 纯文本：易于在任何编辑器（VS Code、Cursor、Windsurf 等）中编辑，易于在 Git 中进行差异比较。
  • 每个文件一个图表：每个 .fz 描述一个图表，通常存储在 /docs/ 下。
  • 全局唯一的节点 ID：n1、n2……在所有泳道中唯一，以便图表引擎可以明确地映射步骤。
  • 严格但简单的语法：泳道、节点、边和循环使用一种小巧、一致的 DSL 编写，易于 LLM 遵循。

一个微小的例子：

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

要渲染此内容，您将 .fz 文件加载到 FlowZap 中；应用程序会处理布局和可视化。

在 FlowZap 中保存为 .fz 和加载 .fz

为了使其具有实用性，FlowZap 的图表 UI 现在提供了两个核心操作：

  • 将此 FlowZap Code 保存为 .fz 文件 您可以从任何图表导出底层的 FlowZap Code 为 .fz 文本文件。典型的模式是将其保存到项目中的 /docs/ 或 /architecture/ 文件夹中，以便进行版本控制。
  • 加载 .fz 文件 在编辑器中，您可以从本机将 .fz 文件加载到 FlowZap，它将渲染相应的图表。唯一的要求是该文件包含有效的 FlowZap Code。

几点重要的澄清：

  • FlowZap 不会 直接扫描您的 GitHub 或 GitLab 代码库。
  • 您（开发者）通过编辑器和 Git 控制 .fz 文件；FlowZap 读取您选择上传的任何 .fz 文件。
  • 您使用 LLM 生成、提交并在以后下载的任何 .fz 文件都可以加载到 FlowZap 中进行可视化和进一步编辑。

这使得架构保持简单：Git 仍然是您的真实来源；FlowZap 仍然是您的可视化引擎。

flowzap-code-guidelines.md：面向 LLM 的语法指南

为了使 .fz 在 AI 优先的编码环境中实用，FlowZap 提供了一份官方的、针对 LLM 优化的指南，位于：

https://github.com/flowzap-xyz/code/blob/main/flowzap-code-guidelines.md

这个想法很简单：

  • 您将此文件复制到项目的 /docs/ 文件夹中。
  • 在 Cursor、Windsurf、Warp 或 Google AI Studio 等工具中，您向 LLM 发出提示，例如： “参考 docs/flowzap-code-guidelines.md 并仅为身份验证流程输出 FlowZap Code。”
  • LLM 使用该指南作为其风格和语法权威，并生成有效的 FlowZap Code，您将其保存为 auth.fz。

指南文件包括：

  • FlowZap Code 语法的精确描述（泳道、节点、边、循环）。
  • 清晰的 Do / Don’t（做/不做）示例（例如，节点的 label:"Text" 与 边的 [label="Text"]）。
  • 用于单泳道流程、多泳道交互、决策、循环和任务框的最小模板。
  • 提示技巧，以便人类可以引导 LLM 获得正确的输出。

由于语法小巧且一致，LLM 仅凭这一个文件作为上下文即可达到很高的准确性。

FlowZap 的工作流如何符合“图即代码”最佳实践

FlowZap 的 .fz 工作流符合普遍接受的“图即代码”模式：

  1. 文本在代码库中，视觉在工具中 .fz 文件位于 Git 代码库中的 /docs/ 或类似位置；它们只是文本。您将它们作为代码库的一部分进行编辑，并使用 FlowZap 作为专门的渲染器。
  2. 版本控制的图表 因为 .fz 是纯文本，所以对图表的每次更改都是一次 Git 更改：
    • 您可以在拉取请求上审查差异（diffs）。
    • 您可以像代码一样对图表更改进行分支、合并和还原。
    • 您可以确切地看到您的身份验证或结账流程是如何随着时间的推移而演变的。
  3. 文档即代码（Docs-as-code）对齐 已经使用 docs-as-code（MkDocs、Docusaurus、Sphinx 等）的团队可以将 .fz 视为 /docs/ 中的任何其他源工件。随着时间的推移，如果您想在 HTML 文档中获得静态图像，您可以编写脚本导出或截图。
  4. AI 辅助创作 您无需手动编写每一行 FlowZap Code，而是提示 LLM，它会读取 flowzap-code-guidelines.md 并为您生成 .fz 文件。这就是“vibe coding”循环：
    • 用自然语言描述流程。
    • 获取返回的 FlowZap Code。
    • 保存为 .fz 并加载到 FlowZap 中。
  5. 两种视图的单一真实来源 因为 FlowZap 可以从同一 FlowZap Code 显示工作流视图和序列视图，所以您避免了重复的图表。一个 .fz 文件同时成为业务流程图和技术交互图。

示例：从提示到图表

对于典型开发者来说，工作流如下所示：

  1. 将指南放入您的代码库 将 flowzap-code-guidelines.md 复制到 /docs/。
  2. 使用您的 AI 编码助手 在 Cursor 或 Windsurf 或其他工具中，运行类似以下的提示： “参考 docs/flowzap-code-guidelines.md 并仅为用户登录流程输出 FlowZap Code：用户输入凭据，App 验证，服务器检查数据库，成功或错误（最多重试 3 次）。”
  3. 创建 .fz 文件 将 LLM 的响应保存为 docs/authentication.fz 并将其提交到您的代码库。
  4. 在 FlowZap 中渲染它 在浏览器中打开 FlowZap，点击 加载 .fz 文件，选择 authentication.fz，并查看从您的文本生成的工作流和序列视图。

以后的代码更改影响了流程？通过另一个提示更新您的 .fz（“修改此 FlowZap Code 以添加 OAuth”）并将其重新加载到 FlowZap 中。

为什么这对序列图和 AI 工作流很重要

大多数现有的“图即代码”工具要么是：

  • 通用的（PlantUML、Mermaid），语法较重且双视图支持有限，要么
  • 专注于基础设施/架构而不是端到端的业务流程。

FlowZap 走了一条不同的路：

  • 它专注于 工作流和序列图——您关心的用于认证、支付、审批和 AI 代理交互的流程。
  • 它提供了一个 简单的 DSL，非 UML 专家也能快速掌握。
  • 它自然地融入 AI 辅助 开发，LLM 可以按需编写或更新 .fz 文件。

如果您的团队已经在 Git 中存储代码、文档和基础设施定义，.fz 和 FlowZap Code 让您可以将序列图添加到同一个可重复的工作流中——而无需放弃非技术利益相关者所需的视觉清晰度。

几分钟内即可入门

要在您自己的项目中尝试此操作：

  1. 将 flowzap-code-guidelines.md 从 https://github.com/flowzap-xyz/code/blob/main/flowzap-code-guidelines.md 添加到您的 /docs/ 文件夹中。
  2. 要求您的 LLM（Cursor、Windsurf、Warp 等）生成一个简单流程的 FlowZap Code，并引用该文件。
  3. 将结果保存为 /docs/ 下的 something.fz。
  4. 转到 flowzap.xyz，打开图表编辑器，并使用 加载 .fz 文件 进行可视化。

从那里开始，随着系统的发展，您可以同时迭代代码和图表。

Inspirations:

返回所有博客文章