AI Flowchart Studio 如何使用 Gemini 将自然语言转换为可编辑流程图？

AI Flowchart Studio 使用 Gemini 先判断自然语言是否适合转换为流程图，再提取节点与边的结构化数据，随后由本地代码生成 Mermaid 语法并在浏览器中渲染。用户需要提供 Gemini API 密钥或使用部署方配置的服务端密钥，生成后可以手动增删节点、调整方向和主题，并导出 Mermaid、SVG 或 PNG。

开始前需要准备什么

• 现代浏览器。
• 可用的 Gemini API 密钥，或已配置服务端密钥的部署实例。
• 适合流程图表达的自然语言说明。
• 对密钥使用、数据传输和第三方模型调用的授权。

项目采用 BYOK（Bring Your Own Key，自带密钥）方式。当前前端会把用户填写的密钥保存在浏览器 LocalStorage，并在生成请求中通过 X-Gemini-API-Key 请求头发送给后端；后端再用该密钥调用 Gemini。

“密钥保存在本地”不等于密钥只在本机使用。生成时密钥和提示词都会经过应用后端，并由后端访问 Gemini。敏感环境应先审查部署实例、传输加密和代码版本。

在线生成的基本步骤

1. 打开 AI Flowchart Studio。
2. 进入设置并填写 Gemini API 密钥。
3. 在提示框描述流程。
4. 点击生成并观察阶段状态。
5. 检查生成的图表和 Mermaid 代码。
6. 在手动模式中修正节点与连接。
7. 选择主题、方向并导出。

提示词应该包含哪些信息

提示词至少应说明开始事件、处理步骤、判断条件、分支去向和结束状态：

Create a flowchart for a support ticket workflow.
Start when a customer submits a ticket.
Validate required fields, then classify severity.
Critical tickets page the on-call engineer.
Normal tickets enter the support queue.
After a fix, ask the customer to verify.
If verification fails, return to investigation.
If verification succeeds, close the ticket.
Label every decision branch.

项目当前生成的是流程图，不应把它当作任意 UML、BPMN 或数据可视化生成器。输入应能拆成节点与有向边。

四阶段流水线如何工作

阶段一：请求判定

Orchestrator 接收用户提示，判断内容是否适合转换为流程图。过于模糊或无关的输入会返回说明，而不是继续生成。

阶段二：逻辑解析

Logic Parser 调用 Gemini，把文本整理成结构化节点和边。节点包含 ID、标签和形状，边包含起点、终点和可选标签。

{
  "nodes": [
    {"id": "node_1", "label": "Receive ticket", "shape": "round"},
    {"id": "node_2", "label": "Critical?", "shape": "diamond"}
  ],
  "edges": [
    {"source_id": "node_1", "target_id": "node_2", "label": null}
  ]
}

阶段三：Mermaid 生成

生成阶段并不再次调用模型，而是用 mermaid-py 把已验证的数据模型转换为 Mermaid 代码。矩形表示普通步骤，菱形表示判断，圆角形状表示开始或结束。

阶段四：基础检查

当前代码中的 Validator 只检查生成结果是否存在且长度不小于 10 个字符。它没有调用 Mermaid 解析器进行完整语法验证，因此不能保证所有输出都能正确渲染。

为什么节点 ID 不能使用保留词

逻辑解析提示明确要求不要把 start、end、graph、flowchart 或 subgraph 用作节点 ID，因为它们可能与 Mermaid 关键字冲突。

稳定做法是使用带前缀的短 ID：

node_start
step_validate
decision_severity
action_page_oncall
node_closed

显示标签可以使用自然语言，ID 则应保持唯一、简短和稳定。

后端如何接收生成请求

前端向 /api/generate 发送 POST 请求，JSON 中包含 prompt，用户密钥放在请求头。后端使用 Server-Sent Events（SSE）依次返回分析、结构提取、代码生成和检查状态。

POST /api/generate
Content-Type: application/json
X-Gemini-API-Key: your-key

{"prompt": "Create a ticket workflow..."}

不要在日志、截图或错误报告中保留真实密钥。示例中的值只表示请求结构。

服务端密钥回退如何工作

后端优先使用浏览器请求头提供的密钥；如果没有，则读取服务器环境变量 GEMINI_API_KEY。部署方若要求严格 BYOK，不应配置服务端回退密钥。

共享服务端密钥会带来配额、滥用和成本控制问题，还需要身份认证、速率限制和审计。当前简单生成接口不应直接无保护地暴露到公网。

如何检查生成结果

1. 确认所有输入步骤都有对应节点。
2. 检查判断节点是否使用菱形。
3. 检查每个判断的所有出口及标签。
4. 沿主路径和失败路径走到终点。
5. 确认不存在孤立节点或错误回路。
6. 查看 Mermaid 是否真实渲染成功。
7. 确认 AI 没有发明输入中不存在的规则。

后端返回“完成”不替代浏览器渲染测试，更不替代业务走查。

如何手动编辑流程图

项目提供手动构建能力，可以添加节点、建立连接和编辑形状。适合修正少量 AI 输出错误：

• 补充遗漏的判断出口。
• 修改节点标签。
• 删除重复节点。
• 修正错误连接。
• 选择从上到下或从左到右布局。
• 应用 Dark、Light、Forest 或 Neutral 主题。

撤销与重做有哪些边界

当前前端实现维护最多 50 个撤销状态，快照包括节点、连接、Mermaid 代码、方向和主题。它适合短期编辑回退，不等于长期版本历史。

清空整个流程时界面明确提示无法撤销。重要修改前应保存项目或复制 Mermaid 代码，不能只依赖撤销栈。

本地项目如何保存

README 说明最多可在浏览器本地管理 5 个项目。节点、连接、项目和密钥都依赖 LocalStorage，因此：

• 清理站点数据可能删除项目。
• 换浏览器或设备不会自动同步。
• 无痕模式关闭后数据可能消失。
• 同源脚本漏洞可能读取本地密钥。
• 重要项目仍应导出 Mermaid 或 SVG 备份。

如何选择图表方向

Top-Down 适合决策树和分支较多的流程，Left-to-Right 适合线性工作流和幻灯片。切换方向后要重新检查连线交叉、长标签和画布边界。

方向变化只改变布局，不应改变节点和边。若切换后业务关系发生变化，应检查生成或手动状态转换逻辑。

如何选择主题

主题应服务于交付环境：

• Light 适合普通文档和打印。
• Dark 适合暗色演示，但要检查投影对比度。
• Forest 适合需要明显绿色层次的图表。
• Neutral 适合减少装饰、突出结构。

颜色不应成为唯一语义。成功、失败和判断还应由标签和形状表达。

如何导出 Mermaid 代码

Mermaid 文本最适合后续编辑、版本控制和技术文档。导出后应在独立渲染器中打开，确认代码没有依赖当前页面状态。

graph TD
    node_1([Receive ticket]) --> node_2{Critical?}
    node_2 -- Yes --> node_3[Page on-call]
    node_2 -- No --> node_4[Enter support queue]

如何导出 SVG 和 PNG

SVG 适合无损缩放、网页和设计排版；PNG 适合聊天、工单和固定尺寸文档。项目会从当前 Mermaid SVG 生成导出结果，PNG 使用放大渲染提高质量。

下载后检查：

• 四周是否裁切。
• 节点文字是否溢出。
• 箭头和标签是否清晰。
• 主题背景是否符合目标环境。
• 导出文件是否对应最终源代码。

隐私说明应该如何准确理解

仓库说明应用服务器不持久化用户密钥、提示或生成结果，项目和设置保存在浏览器。但在生成期间，提示词和用户密钥仍会传给后端，后端再请求 Gemini。

是否真正不记录数据还取决于实际部署代码、代理、平台日志和 Gemini 服务政策。敏感流程不应仅根据 README 承诺直接上传，应完成独立审查。

API 密钥应该如何保护

• 为该用途创建独立密钥，不复用高权限凭据。
• 设置可用的配额和预算限制。
• 只在可信部署中输入密钥。
• 使用后按需要从浏览器存储中删除。
• 怀疑泄露时立即撤销并轮换。
• 不要把密钥提交到仓库或截图。

自托管需要哪些组件

当前仓库由静态前端和 FastAPI 后端组成。后端依赖 FastAPI、Uvicorn、Gunicorn、Google Gen AI SDK、Pydantic、python-dotenv 和 mermaid-py。

部署时至少要配置：

• FRONTEND_URL，限制允许的 CORS 来源。
• 可选的 GEMINI_API_KEY 服务端回退。
• TLS、认证、限流和请求大小限制。
• 日志脱敏和密钥过滤。
• 健康检查与生成超时。

代码默认允许来源为通配符，不适合直接作为带凭据的生产配置。应指定实际前端来源，并验证跨域凭据策略。

常见故障如何排查

提示 Prompt is required

请求体没有 prompt 或内容为空。确认前端输入不是只有空格，并检查 JSON 字段名。

提示没有 Gemini API Key

请求头未携带用户密钥，服务器也没有配置环境变量。重新检查设置、浏览器存储和部署环境。

生成阶段长时间停住

检查 SSE 连接、后端冷启动、Gemini 配额、网络超时和浏览器控制台。阶段状态能帮助确定卡在请求判定还是逻辑解析。

后端成功但页面无法渲染

当前 Validator 不执行完整 Mermaid 解析。查看返回代码和浏览器渲染错误，修复保留词、标签特殊字符、箭头或结构问题。

刷新后项目不见了

检查是否更换域名、浏览器或无痕会话，以及站点数据是否被清理。本地保存不等于云端备份。

最终验收清单

1. 提示词包含步骤、判断和终态。
2. 生成阶段状态全部完成。
3. Mermaid 在浏览器和独立渲染器中都能打开。
4. 节点、边和分支与真实流程一致。
5. 手动编辑没有破坏其他路径。
6. 密钥未出现在日志、截图或项目文件中。
7. 重要项目已经导出源代码备份。
8. PNG 或 SVG 在目标环境中清晰完整。

总结

AI Flowchart Studio 的实际链路是 Gemini 判断与解析自然语言、Pydantic 约束节点和边、mermaid-py 生成语法、浏览器完成渲染。生成结果可以继续手动编辑并导出多种格式，但当前后端只做基础非空检查，不能替代 Mermaid 解析和业务验证。使用 BYOK 时还要理解密钥会随生成请求经过后端，做好部署审查、配额限制、密钥轮换和源文件备份。