AI编程助手+Skill：自动生成Mermaid流程图实战指南

最近跟几个做算法的朋友聊天发现大家都有同一个痛点画流程图。不管是论文里的算法流程图、项目里的业务流程图还是周报里的“模块关系图”手动拖拽、对齐、调样式一改需求就得重新排版非常消耗精力。这个场景一直有人想做自动化但通用的画图工具很难理解你脑子里的逻辑。直到 AI 编程助手普及配合一个被叫做Skill的机制情况才真正发生变化。这次我们来看一个很实用的玩法通过给 Claude Code、Codex、opencode 这类 AI 编程助手配置一个流程图 Skill让 Agent 直接理解你的业务描述自动生成 Mermaid 格式的流程图代码再渲染成图片。以后画流程图你只需要描述逻辑剩下的节点划分、连线、分支判断、样式布局全部交给 AI。如果你常跟复杂流程打交道这篇文章值得收藏。先说这个方案的核心特点:支持 Claude Code / Codex / opencode 等主流 AI 编程助手自动生成 Mermaid 语法可渲染成 PNG / SVG / 在线链接支持算法流程图、业务流程图、系统架构图、用户管理模块图等常见类型支持本地模型或云端 API无额外独立服务可以批量生成多个流程图适合文档整理和代码注释沉淀接下来我会带大家完成从 Skill 原理、环境配置、手写 Skill、功能测试到批量调用的完整闭环。最后给出一套常见问题排查清单和最佳实践。1. 核心能力速览能力项说明项目本质基于 AI 编程助手的 Skill 机制自动生成流程图的解决方案核心输入自然语言描述的业务流程、算法逻辑或系统交互核心输出Mermaid 流程图代码 / 渲染后的图片适用助手Claude Code、Codex CLI、opencode 等支持 Skill 的 Agent 工具硬件要求无独立 GPU 需求用云端 API 时只需联网显存占用不涉及独立模型推理无显存要求启动方式在 Agent 会话内通过触发词调用API 能力Agent 本身支持 API 模式可集成到脚本批量任务支持通过批处理脚本逐个调用 Agent 生成适合场景技术文档、算法讲解、系统设计、需求评审、教学课件关于“显存占用”这里要多说一句整个流程图 Skill 方案不像本地大模型那样需要加载权重而是让 Agent 调用现有模型生成文本代码。所以哪怕你的机器是 8G 内存的轻薄本只要能用命令行跑 Agent就能用上这个方案。2. Skill 的本质为什么它能搞定流程图2.1 Skill 是什么Skill 是最近 AI 编程助手圈子里很火的一个概念。它本质上是一个结构化的能力文件夹里面包含一份SKILL.md说明文件和若干辅助脚本、模板、示例。当你在对话中触发某个关键字时Agent 会读取这个文件夹里的说明按照预设流程执行任务。与传统 Prompt 相比Skill 的优势在于把复杂任务拆成可复用的步骤不用每次重复描述可以附带脚本让 Agent 自动处理文件读写、格式校验、渲染等操作支持团队共享一个 Skill 写好后其他人直接复制就能用和 MCP 的定位不同Skill 更像“内化的工作流指导”MCP 更像“外挂的工具接口”2.2 Skill 和 MCP 的区别热搜词里很多人问“agent skill 和 mcp 有什么区别”这里我给出一个比较直观的对比维度SkillMCP本质一套指令和流程模板一套工具/数据服务接口作用时机让 Agent 知道“怎么做”让 Agent 能调用外部能力是否需要独立服务不需要本地文件夹即可通常需要启动一个服务端典型场景按固定流程生成某种格式内容查询数据库、操作浏览器、调用第三方 API组合关系可以告诉 Agent 用哪个 MCP 工具为 Agent 提供工具能力画流程图这件事本质上需要的是“怎么组织节点、怎么描述关系、怎么输出标准 Mermaid”所以 Skill 是更直接的选择。如果你还想让 Agent 自动把流程图推送到企业微信或者保存到 Notion那可以再加一个 MCP 工具两者并不冲突。3. 环境准备与前置条件在开始手写 Skill 之前我先列一下需要准备的环境。这个方案属于轻量级工具链不需要 GPU不需要装 ComfyUI 这类重型服务。3.1 基础环境清单依赖项版本建议用途Node.js18 或 20 LTS运行 Claude Code / Codex CLI / opencodePython3.10执行渲染脚本或批量调用脚本AI 编程助手Claude Code / Codex CLI / opencode 任选Agent 运行环境Mermaid CLI可选最新稳定版本地渲染 Mermaid 为 PNG/SVGVS Code / Typora / draw.io 导入任意查看 Mermaid 效果3.2 安装 AI 编程助手因为 Skill 机制在不同工具里的路径略有差异这里以最通用的方式说明。以 Claude Code 为例# 安装 Claude Code CLI npm install -g anthropic-ai/claude-code # 检查版本 claude --version如果使用 Codex CLI则命令类似npm install -g openai/codex codex --versionopencode 的安装方式npm install -g opencode-ai opencode --version安装完成后先确保命令行能正常启动 Agent并完成登录或 API Key 配置。这一步是后续所有操作的前提。3.3 验证 Skill 目录不同工具识别 Skill 的目录不一样但思路相同。常见位置如下~/.claude/skills/ # Claude Code ~/.codex/skills/ # Codex CLI ~/.config/opencode/skills/ # opencode如果目录不存在手动创建即可。下面所有 Skill 文件都放在对应目录下。4. 手写一个 Flowchart Skill从零开始下面进入正题。我们不直接复制一个现成的 Skill而是把它拆开来看这样你以后也能自己写其他类型的 Skill。4.1 Skill 的目录结构一个标准的流程图 Skill 目录如下flowchart-skill/ ├── SKILL.md └── scripts/ ├── validate_mermaid.py └── render_mermaid.mjsSKILL.md是核心Agent 收到触发词后会先读这个文件。scripts目录放一些辅助脚本用来校验 Mermaid 语法和渲染成图片。4.2 SKILL.md 的写法先来看SKILL.md的完整示例--- name: flowchart description: 当用户需要绘制流程图、算法流程、业务流程、系统架构图时使用。自动生成 Mermaid 代码并可选渲染为图片。 --- # Flowchart Skill 你是一个流程图设计专家。你的任务是根据用户描述生成结构清晰、逻辑正确的 Mermaid 流程图。 ## 步骤 1. 分析用户输入的业务流程或算法逻辑 2. 识别关键步骤、判断分支、循环结构 3. 用 Mermaid 语法组织节点和连线 4. 输出完整的 mermaid 代码块 5. 如果用户要求渲染图片调用 scripts/render_mermaid.mjs 渲染 ## 输出格式 必须输出如下格式 mermaid graph TD A[开始] -- B{条件判断} B -- 是 -- C[处理流程] B -- 否 -- D[结束]注意事项节点文本要简洁避免超长句子判断节点使用菱形 {}处理节点使用方括号 []分支路径要标注清晰的条件文本如果逻辑中有循环用带条件标注的回边这个文件的关键是让 Agent 明白什么时候触发、按什么步骤做、输出什么格式、有什么约束。写清楚这四点一个 Skill 就能工作。 ### 4.3 校验脚本 Mermaid 语法有时候会因为节点文本里有特殊字符而渲染失败。为了减少返工我建议在 Skill 里放一个校验脚本。下面给出一个用 Python 写的简单检查脚本 python #!/usr/bin/env python3 # scripts/validate_mermaid.py import sys import re def validate_mermaid(code: str) - list: errors [] # 检查是否有 graph / flowchart 开头 if not re.search(r^(graph|flowchart)\s(TD|TB|LR|RL|BT), code, re.MULTILINE): errors.append(缺少有效的 graph/flowchart 方向声明) # 检查括号是否匹配 if code.count({) ! code.count(}): errors.append(花括号数量不匹配可能有判断节点书写错误) if code.count([) ! code.count(]): errors.append(方括号数量不匹配可能有节点文本书写错误) # 检查节点 ID 格式 for line in code.splitlines(): if -- in line and not re.search(r[A-Za-z0-9_]\s*(--[^]?-|--)\s*[A-Za-z0-9_], line): errors.append(f连线格式问题: {line}) return errors if __name__ __main__: content sys.stdin.read() errs validate_mermaid(content) if errs: print(校验失败) for err in errs: print(f - {err}) sys.exit(1) print(校验通过)这个脚本不追求覆盖所有 Mermaid 特性但能拦住最常见的括号不匹配、缺方向声明等问题对于提高批量生成的成功率很有帮助。4.4 渲染脚本如果希望 Skill 能直接输出 PNG 或 SVG可以借助 Mermaid CLI。下面是一个 Node.js 渲染脚本示例// scripts/render_mermaid.mjs import { execSync } from node:child_process; import fs from node:fs; import path from node:path; const input process.argv[2]; const output process.argv[3] || output.svg; const mmdPath path.join(process.cwd(), temp_diagram.mmd); fs.writeFileSync(mmdPath, input, utf-8); try { execSync(npx mermaid-js/mermaid-cli -i ${mmdPath} -o ${output}, { stdio: inherit }); console.log(渲染完成: ${output}); } finally { fs.unlinkSync(mmdPath); }这个脚本的核心思路把 Mermaid 代码写入临时文件调用mmdc渲染最后清理临时文件。实际使用时你可以让 Agent 直接执行这个脚本也可以自己手动跑。5. 功能测试与应用测试5.1 测试场景一算法流程图先来看一个经典场景用流程图说明反向传播算法的工作原理。这个来自热搜词也是很多模型训练相关文章里常见的配图。在 Agent 会话中输入调用 flowchart skill画一个反向传播算法的流程图Agent 会读取 Skill 定义按步骤工作。预期输出类似这样graph TD A[输入训练数据] -- B[前向传播计算输出] B -- C[计算损失函数] C -- D{损失是否满足要求?} D -- 否 -- E[反向传播计算梯度] E -- F[更新权重和偏置] F -- B D -- 是 -- G[模型训练完成]这个例子很好地展示了 Skill 的价值哪怕你没有提前画过任何节点只要描述清楚“反向传播”这个算法名Agent 就能根据自己的知识完成流程建模。判断成功的标准是流程图包含前向传播、损失计算、梯度计算、权重更新和循环回边循环逻辑用回边表示有明确的条件退出节点类型符合规范判断用菱形操作用方括号5.2 测试场景二业务流程图第二个场景是业务流程图以热搜词里的“用户管理模块流程图”为例。这类图在需求评审和系统设计里常出现用手动画图工具画起来非常繁琐。在 Agent 中输入调用 flowchart skill画一个用户管理模块的业务流程图预期输出可能包含用户注册、登录、权限校验、管理员操作、禁用用户等节点。大致结构如下graph TD A[用户访问系统] -- B[登录/注册] B -- C{身份验证是否通过?} C -- 否 -- D[提示错误并重试] C -- 是 -- E{权限角色判断} E -- 普通用户 -- F[个人中心/资料修改] E -- 管理员 -- G[用户列表管理] G -- H[禁用/解禁/重置密码] F -- I[退出登录] H -- I这个结果直接可以用于需求评审文档。相比手绘Agent 生成的版本有几个优点节点命名统一、分支条件明确、方便再次修改。5.3 测试场景三系统架构图第三种场景是系统架构图。虽然严格来说这不是“流程图”但 Skill 的步骤稍加扩展就能输出架构图。用户需求调用 flowchart skill画一个前后端分离的系统架构图Agent 生成的 Mermaid 可能是graph LR A[浏览器前端] --|HTTP/HTTPS| B[Nginx 网关] B -- C[后端 API 服务] C -- D[(数据库)] C -- E[缓存服务] C -- F[消息队列] F -- G[异步任务处理]这类图在技术方案文档里非常常见用 Skill 生成可以保持风格统一。5.4 测试流程总结不管什么类型的流程图都可以按下面这个标准流程走启动 Agentclaude、codex或opencode输入包含触发词和需求的描述Agent 读取 Skill 说明拆解步骤Agent 输出 Mermaid 代码块复制代码到 Typora / draw.io / VS Code 预览如果效果不对直接反馈“第二步和第三步之间的逻辑不完整”Agent 会迭代修改这个流程最大的优势是修改成本从“重画”降到了“改描述”。这是非常明显的效率提升。6. 接口 API 与批量任务流程图 Skill 不仅能用于交互式会话还能接入 API 和批量任务。下面两种方式比较常见。6.1 通过 Agent 的 Headless 模式调用Claude Code、Codex CLI 都支持非交互式模式。这意味着你可以写一个脚本把一系列需求传给 Agent让它逐个生成流程图。以 Claude Code 为例命令大致如下claude -p 调用 flowchart skill为以下需求生成 Mermaid 流程图用户注册流程包含邮箱验证和手机验证两个分支 --output-format json这个命令会直接输出结果不进入交互界面非常适合脚本调用。6.2 Python 批量调用示例结合热搜词里“批量任务”的诉求我给出一个 Python 批量生成流程图的通用脚本。注意实际命令需要按你选择的 Agent 工具调整。import subprocess import json import os import time tasks [ { name: user_register, description: 用户注册流程包含邮箱验证和手机验证两个分支, }, { name: order_payment, description: 订单支付流程包含余额不足时跳转到充值页面, }, { name: data_backup, description: 每日数据备份流程包含备份失败告警, }, ] output_dir ./flowcharts os.makedirs(output_dir, exist_okTrue) for task in tasks: print(f处理{task[name]}) prompt f调用 flowchart skill生成流程图。需求{task[description]} result subprocess.run( [claude, -p, prompt, --output-format, json], capture_outputTrue, textTrue, timeout120 ) if result.returncode ! 0: print(f失败{task[name]}错误{result.stderr}) continue output json.loads(result.stdout) # 提取 Mermaid 代码实际字段名需要按 Agent 输出调整 mermaid_code output.get(result, ) # 保存为 .mmd 文件 mmd_path os.path.join(output_dir, f{task[name]}.mmd) with open(mmd_path, w, encodingutf-8) as f: f.write(mermaid_code) print(f已保存{mmd_path}) time.sleep(2) # 避免请求过于频繁这个脚本的做法是准备一批流程图需求循环调用 Agent 生成 Mermaid 代码保存到本地 .mmd 文件后续再用渲染脚本统一转成图片需要注意Agent 的输出格式会因为工具版本不同而有差异。实际使用时要先跑一次确认返回的 JSON 字段名再调整解析逻辑。7. 资源占用与性能观察流程图 Skill 本身不依赖 GPU 推理所以它的“资源占用”和“性能”主要体现在三个方面Token 消耗、请求时长和渲染开销。7.1 Token 消耗生成一张中等复杂度的流程图通常只需要 500 到 1500 个 Token取决于节点数量和分支复杂度。纯文本输出对 Token 的占用很低真正消耗较多的是 Agent 启动时的系统提示词这部分通常由工具框架内置。如果使用云端 API可以重点关注每次请求的 Token 统计如果使用本地模型则可以通过 Agent 的调试日志观察。7.2 请求时长交互式会话中生成一张流程图一般在 10 秒到 30 秒之间。影响时长的因素包括模型接口响应速度输入描述的详细程度Agent 是否调用了 mermaid CLI 渲染网络延迟云端 API 场景批量生成时建议在每次请求之间加 1 到 2 秒的间隔避免触发限流。7.3 渲染开销Mermaid CLI 渲染本身很轻量在普通 CPU 上渲染一张 SVG 一般不超过 3 秒。如果渲染 PNG时间会稍长但也在可接受范围内。不需要独立 GPU。7.4 如何优化性能控制流程图节点数量一般不超过 20 个节点否则图和文本都会变得混乱优先输出 SVG矢量格式缩放不损失清晰度适合放进文档批量任务中使用缓存目录避免重复生成相同内容如果只是看效果直接用 Typora 或 draw.io 打开 .mmd 文件不一定要先渲染8. 常见问题与排查方法在实际使用中可能会遇到一些问题。下面整理成一张排查表问题现象可能原因排查方式解决方案Agent 没有触发 Skill触发词与 SKILL.md 中的 name/description 不匹配检查 SKILL.md 中的触发描述在描述中明确写出“流程图”“flowchart”等关键词生成的 Mermaid 在预览中渲染失败节点文本包含特殊字符或括号不匹配用 validate_mermaid.py 校验要求 Agent 重新生成或者手动修正特殊字符渲染脚本报错未安装 mermaid-cli 或 Node.js 版本过低检查npx mermaid-js/mermaid-cli --version执行npm install -g mermaid-js/mermaid-cliAgent 生成的节点数量过多输入描述过于宽泛在需求里指定“只画主要步骤不超过10个节点”让 Agent 按约束重新生成Skill 目录未生效目录路径不对或工具版本不支持查看 Agent 文档确认 Skills 目录位置移动到正确的目录并重启 Agent批量任务中部分出图失败单个请求超时或模型限流查看日志中的错误信息和状态码增加超时时间、重试机制或加大请求间隔输出变成了普通文字而非 mermaid 代码块Skill 未正确指导输出格式检查 SKILL.md 中是否写明了必须输出 mermaid 代码块在演示示例里放入完整的 mermaid 代码块流程图逻辑和业务理解不一致输入描述不够精确增加前置条件、异常分支说明拆分需求先画主干再补分支最常见的坑是Mermaid 渲染失败。Mermaid 对节点 ID 和文本内容有一定限制比如文本里包含英文括号、特殊符号时容易报错。解决方案很简单要求 Agent 在节点文本中尽量使用简洁中文不在节点里放复杂公式。第二个常见坑是Agent 没有按 Skill 的输出格式来。问题通常出在 SKILL.md 写得不够具体。好的做法是在 SKILL.md 中给出一个完整的 Mermaid 示例让 Agent 有参照。9. 最佳实践与使用建议9.1 从“最小可用”开始第一次写 Skill 不要追求大而全。先用一个最简单的SKILL.md只包含名称、描述和输出格式示例跑通整个流程。然后再逐步加入校验脚本、渲染脚本、特殊规则。这样即使出问题也很容易定位。9.2 把描述写成“需求蓝图”Agent 生成流程图的准确度很大程度上取决于你的描述质量。建议用以下模板组织输入调用 flowchart skill绘制以下流程 场景用户注册 入口用户提交手机号 步骤 1. 校验手机号格式 2. 发送短信验证码 3. 验证码校验 分支验证码错误则提示重新输入最多重试3次 成功注册成功跳转登录页 失败超过重试次数提示联系客服描述越接近需求蓝图Agent 生成的流程图越贴近你的预期。这比只说一句“画个注册流程图”要靠谱得多。9.3 分目录管理流程素材建议在项目里这样组织文件docs/ ├── flowcharts/ │ ├── source/ # 保存 .mmd 源文件 │ ├── svg/ # 渲染后的 SVG │ └── png/ # 渲染后的 PNG ├── prompts/ # 保存每次生成需求的提示词 └── skills/ # 自定义 Skill 备份这样做的目的是流程图需求会迭代很多次保留源文件和提示词方便后续修改和复盘。9.4 建立“先校验再渲染”的流水线在批量任务中一定不要跳过校验步骤。合理的流水线是生成 Mermaid 代码 - 校验语法 - 渲染 SVG - 渲染 PNG - 归档每次生成后先跑校验脚本校验通过再渲染可以显著降低返工成本。9.5 合规与安全边界流程图往往包含业务逻辑、系统架构、数据流转等内部信息。使用云端 Agent 时要注意以下几点不要输入公司敏感的业务数据和未公开的系统架构细节如果项目涉及内部系统建议使用支持本地模型的 Agent 工具发布到公开文档前检查流程图是否泄露了内部 IP、数据库名、服务端口等信息涉及他人设计的系统架构时应确认有无分享和复用的授权批量生成的需求描述中避免包含用户隐私字段如手机号、身份证号、真实姓名等流程图本身是文档内容但如果流程图描述的是真实业务系统和数据流那么在对外发布之前仍需做一次脱敏审查。10. 总结与下一步流程图 Skill 最值得尝试的点是把“画图”这个动作从手动拖拽变成了对话式描述而且输出的是可复用的 Mermaid 源码后续修改、版本管理、文档集成都非常方便。你先应该验证的第一件事是让 Agent 输出一个简单的 Mermaid 代码块确认你的工具能正常识别 Skill 目录。跑通之后再加校验脚本和渲染脚本形成完整闭环。最容易踩的坑是 SKILL.md 写得太泛。描述里没有明确“输出格式”和“触发条件”Agent 就很容易自由发挥导致生成结果不稳定。建议参考本文的示例把格式约束写死。后续可以扩展的方向有三个把 Skill 扩展到其他图表类型比如时序图、甘特图、状态机图把批量生成脚本接入项目文档工具提交代码时自动生成架构图把 Skill 与 MCP 结合让 Agent 在生成流程图后直接传给协作平台或文档系统如果你也在为手搓流程图浪费时间可以按这篇文章搭一套自己的 Skill。从最简版本开始跑通后你会明显感受到流程图的成本主要是“描述清楚问题”的成本而不是“画图”的成本。