2. 项目的核心机制拆解到底解决的是什么问题在动手写代码之前我先后试过三条路线第一条是在Coze/扣子这类商业化平台里用现成的Agent编排受限于平台自身的托管环境换一个Agent框架就全部作废第二条是直接调大模型API把自然语言翻译成Mermaid代码但从上下文里看生成的图基本停留在“能看”的层次离“高可读”差距非常大第三条就是现在这个思路——把图形逻辑抽象成一套Token级协议再让模型在协议约束下输出也就是我在项目里实现的skill-easy-code-flow-skill。这里需要先解释一下外界容易误会的地方项目名的skill不是传统意义上的小工具包而是当前AI Agent生态里比较时髦的“技能插件”概念。以Claude Agent SDK这类框架为例一个skill就是一目录文件里面写清楚触发条件、输入输出约定、处理流程和示例Agent在运行时根据用户描述自动加载并执行它。我做的这个包本质上是一份“教Agent如何把一段业务规则描述渲染成结构化流程图”的Skill。那为什么需要专门做这么一层协议因为大模型直接输出Mermaid或PlantUML代码有三大通病。第一节点命名含糊经常出现“A1”“B2”这种无意义标识读者根本不知道这个节点在描述什么业务动作第二主流程和备选流程搅在一起异常分支全部塞进主通道图一拉就乱第三缺少对业务语义的建模比如判断条件是绿灯还是红灯、动作是同步还是异步完全是随机发挥。easy-code-flow-skill要做的就是把“业务描述”和“流程图语义”之间那一层薄薄的胶水固化下来。从使用场景看这个skill能覆盖三类人群。第一类是产品经理写PRD时候顺手把需求转成流程图评审会上直接投影比口述清楚一百倍第二类是研发同学接手老项目时拿上一段业务描述快速画出时序/流程脉络比啃源代码快得多第三类是技术文档写手把操作手册里的文字步骤自动渲染成图配在文档里可读性提升巨大。我近期在公司内部推广后反馈里提到最多的就是“开会前用两分钟生成一张图省掉了一个小时的‘我刚才说的那段逻辑你听明白了吗’”。3. 整体设计思路与技术选型为什么是Mermaid、为什么在Agent层做协议3.1 为什么选择Mermaid作为目标渲染语言市面上所见即所得的绘图工具有很多Draw.io、Excalidraw、ProcessOn每一种都很成熟。但easy-code-flow-skill最核心的定位不是“再做一个画图软件”而是“让AI能稳定产出可维护的图源文件”所以目标语言必须是纯文本、可版本化、能嵌入文档体系的方案。Mermaid在这一点上几乎没有对手语法足够简单社区生态庞大GitHub原生支持渲染Notion、飞书、语雀都能直接识别。选PlantUML也可以但PlantUML的强项其实是UML完整建模纯业务流程图场景下Mermaid的graph TD/LR已经满足80%需求。Mermaid也不是没有坑。最大的坑是图形版本兼容性每次Mermaid的minor版本升级经常有语法细节变化旧版本画的图在新版本渲染器上可能布局全乱。所以我在skill的配置文件里强制了版本号主版本锁定在11.x且在输出头部写入%%{init: {theme:base, themeVariables: {primaryColor:#f4f4f4}}}%%尽可能减少不同渲染器默认主题带来的不确定性。3.2 Agent层协议相比直接调Prompt的优越性很多开发者一听到“让AI生成流程图”第一反应是我能靠一段Prompt就能解决何必再包一层skill。最初我也这么想但实际测试了将近两百条业务描述之后发现Prompt方案有一个致命的不可控点Prompts的引导是靠文字而文字对模型的软约束力比想象中弱。同样一句话“请生成Mermaid代码”有些模型输出的是graph TD有些直接输出flowchart有些在节点里加br/有些乱用引号。解决这个问题的方式就是协议化。我在skill里定义了一套流程语义中间层先让模型把输入文本解析成结构化数据节点再把这些节点映射成Mermaid图形语法。中间层的结构类似这样{ nodes: [ {id:n1, type:start, label:用户发起申请, desc:移动端/PC端均可}, {id:n2, type:action, label:校验用户身份, desc:调用统一认证服务}, {id:n3, type:decision, label:身份是否有效, yes:n4, no:n5} ], flows: [ {from:n1,to:n2,label:}, {from:n2,to:n3,label:} ] }模型只需要把业务文本转化成这个JSON再做一个极轻量的模板渲染流程图就出来了。这样做有三个好处第一模型做的是格式化的信息抽取远比直接生成Mermaid代码更稳定第二中间层可以人工干预发现某条业务逻辑解析错了改JSON比改Mermaid好改第三这个JSON可以复用于其他渲染目标比如后续想支持Graphviz或Sequence图套一层新模板即可底层解析逻辑完全不动。我选这个方案是在踩了无数次Prompt直接生成的坑之后定下来的稳定性提升非常明显。3.3 Skill整体的目录结构设计项目本身是开源的目录结构简单清晰每一个文件都有自己的职责easy-code-flow-skill/ ├── SKILL.md # Skill的描述文件Agent依赖它识别触发条件 ├── config.json # 渲染参数、版本锁定、风格默认值 ├── assets/ │ └── templates/ │ ├── flow_template.mmd # 主模板业务流程图 │ ├── sequence_template.mmd # 副模板时序图扩展用 ├── skillsnake.py # 核心解析脚本 └── examples/ ├── simple_order.md # 示例输入一句话描述订单流程 └── complex_approval.md # 示例输入复杂审批流SKILL.md是入口里面写了触发条件、输入输出约定、处理流程还放了两三个few-shot例子用来告诉Agent“什么情况下调用这个skill”。这里要特别强调一点与普通工具函数不同Agent的skill不能只靠描述文件让模型理解它必须给模型看到足够的输入输出示例模型的执行准确率会因此大幅提升。这一点我在具体使用中验证过加了示例之后成功率从60%跳到了90%以上。4. 实操全流程从克隆仓库到画出第一张高可读流程图4.1 环境准备与安装步骤这个项目依赖的是Python 3.9以上的环境以及Mermaid CLI用于本地渲染验证。如果你的机器上没有装过直接用下面的命令安装# 安装Python依赖 pip install pydantic typer # 安装Mermaid CLImacOS下建议直接brew安装 brew install mermaid-cli # 克隆项目仓库 git clone https://github.com/yourname/easy-code-flow-skill.git cd easy-code-flow-skill安装过程本身不复杂但有一个很容易被忽略的点Mermaid CLI在首次执行时会把Chromium一起拉到本地网络不好的场景下容易卡在下载Chromium这一步。我在README里写了一个替代方案如果遇到这个问题直接用系统的npx -y mermaid-js/mermaid-cli走npm渠道安装不要用brew的版本。4.2 让Agent加载Skill并生成流程图这里拿我最常用的Claude Agent SDK环境举例。在安装完项目后你可以这样定义一个Agentfrom claude_agent_sdk import Agent agent Agent( nameflow-builder, instructions你是业务流程图专家。当用户描述一段业务流程时优先调用easy_code_flow_skill来生成结构化流程图。, skills[path/to/easy-code-flow-skill] ) resp agent.run(帮我画一个用户下单到发货的完整流程) print(resp.output)当Agent识别到用户输入是“画图”“流程”“时序”这类关键词时会自动加载skill目录读取SKILL.md中的执行逻辑再调用skillsnake.py解析描述文本。输出的最终结果会以代码块形式给出本流程包含5个核心节点其中2个为判断节点。 mermaid flowchart TD A[用户下单] -- B{库存校验} B -- 有货 -- C[生成订单] -- D[推送仓库] -- E[发货完成] B -- 无货 -- F[提示用户缺货] -- E我在这个示例里故意保留了一个重要的细节你在输出里看到的并不是只有Mermaid代码在代码块之前还会有一段简短的中文说明。这段说明是一开始就在prompt里就定义好的“可读性摘要”它帮助读者快速定位流程重点特别适合在PRD评审、会议同步这类场景中直接贴出来用。后面我会详细解释这个设计的来龙去脉。4.3 默认参数和自定义风格项目核心的config.json里暴露了这几个可调参数参数默认值说明templateflowchart TD渲染方向TD表示自上而下LR表示从左到右theme_variablesprimaryColor: #f4f4f4主题色可按照团队规范调整show_legendtrue是否在流程图下方生成图例说明include_summarytrue是否输出节点摘要max_node_count20节点数量上限超过则提示拆分max_node_count这个参数我在实际使用中踩过坑。一开始我没做限制结果有一名用户把一整段“财务年度审计流程”喂了进来生成了75个节点的大图。节点一多Mermaid的自适应布局直接失效渲染出来的图乱成一团。所以后来我加了这个限制同时让skill在节点超过上限时自动提示“业务描述可以拆分为多个子流程建议以‘主线分支’方式输入”。这本身也是一种设计取舍流程图不是字典高可读性一定意味着低密度。5. 高可读性从何而来隐藏在代码与Prompt里的细节设计5.1 节点命名与注释策略很多AI生成的流程图“难看”不是画得不对而是节点里全是基础动作描述缺少语义维度。easy-code-flow-skill里针对这个问题做了三层约束。第一层是节点命名规范化所有动作节点必须采用“动词宾语”的结构“用户下单”“发送通知”“更新库存”这类描述天然可读第二层是判断节点的标签必须写“条件是X”而不是只有“X”这样在图上看到B{库存校验}时读者能立刻关联到它是从哪个环节进入分支的第三层是给每个节点附加一个desc字段在生成Mermaid时可以自动转成注释或悬浮文本这个字段在纯图上不体现但如果你导出成HTML或者用支持tooltip的渲染器鼠标悬停就能看到完整解释。以“用户下单”这条流程为例输入用户下单 输出 - 库存校验通过 → 生成订单 → 推送仓库 → 发货完成 - 库存校验失败 → 提示用户缺货 → 流程结束最终生成的Mermaid代码里包含完整注释flowchart TD A[用户下单br/small移动端/PC端均可/small] -- B{库存校验} B -- 有货 -- C[生成订单] B -- 无货 -- F[提示用户缺货] C -- D[推送仓库] D -- E[发货完成]5.2 分支路径的颜色与样式规则可读性不仅靠语义也靠视觉。Mermaid支持在节点上直接定义style我在模板里内置了一套颜色约定开始节点用浅绿色动作节点用浅蓝色判断节点用浅黄色异常/终止节点用浅红色。这套规则虽然是人为定的但非常符合人类对流程图颜色的直觉——看到红色自然知道是错误分支看到黄色自然知道要决策。除了节点颜色分支路径上我也做了处理。Mermaid的默认样式对“是/否”分支的边没有特殊渲染但我的模板中会把yes边强制加粗no边保持普通线条。你观察高可读的流程图判断节点的出口线一定是主分支比次分支更显眼这一步对阅读体验的影响比大部分人想象中大得多。5.3 副输出的“数据清单”在easy-code-flow-skill的早期版本中我只输出一张图后来在给团队内做内测时收到了这样一个反馈“图是清楚了可我想快速知道一共有几个判断节点、几个异常路径有没有统计”于是我在后续版本中增加了“数据清单”副输出。即在生成Mermaid代码的同时还会输出一张Markdown表格节点类型数量说明开始节点1用户下单动作节点4校验、生成、推送、发货判断节点1库存校验异常路径1缺货提示这张表格在图评审、代码走查、测试用例整理时特别有用。比如测试工程师拿到这个表格可以按“判断节点”逐条拆用例项目经理拿到这个表格可以快速评估流程复杂度。把“数据清单”作为副输出是“高可读性”从图像层面延伸到数据层面的关键一步也直接提升了这个skill在真实工作流里的适用性。6. 实战案例完整拆解“请假审批流”的产出过程6.1 准备一段典型业务描述为了更直观地展示项目的使用效果我拿一段比较常见的“请假审批流程”作为输入来走一遍完整链路。这段业务描述的复杂度属于日常工作中经常会遇到的类型包含多级审批、条件分支、驳回和超时处理。员工提交请假申请系统判断请假天数。小于等于3天由直属主管审批超过3天需要部门经理加签。主管审批通过后流程结束请假生效审批不通过则直接退回流程结束。部门经理审批同样有通过和不通过两个结果。同时系统会在请假生效后自动发送邮件通知人事部门备案。这样一段描述如果让人手工画基本需要5到10分钟而且不同人画出来的结构可能有差异。但如果交给easy-code-flow-skill模型会先解析出这样的节点树[ {id:n1,type:start,label:员工提交请假申请}, {id:n2,type:decision,label:请假天数是否≤3天}, {id:n3,type:action,label:直属主管审批}, {id:n4,type:decision,label:审批是否通过}, {id:n5,type:action,label:请假生效并通知HR}, {id:n6,type:action,label:部门经理审批}, {id:n7,type:end,label:流程结束} ]6.2 生成结果与人工优化skill内部处理完成后输出的Mermaid代码是flowchart TD A[员工提交请假申请] -- B{请假天数≤3天?} B -- 是 -- C[直属主管审批] C -- D{审批通过?} D -- 是 -- E[请假生效并通知HR] D -- 否 -- F[流程结束] B -- 否 -- G[部门经理加签] G -- H{加签通过?} H -- 是 -- E H -- 否 -- F这张图的协调性很好但人工审计时仍会发现一个小问题部门经理加签这个节点后缺少“加签通过后”的明确动作流程直接跳到了请假生效。这在业务上说得通但在图例上少了一个“加签通过”的中间节点阅读者心里会咯噔一下“咦加签通过了然后呢”。针对这种情况我会手动补一个动作节点变成“加签通过→审批结果汇总→请假生效”。不要觉得这是skill不够聪明实际上这说明“AI生成流程图”永远需要一个人类兜底的环节。工具负责把80%的时间节省掉剩余20%的边界修正恰恰是保证高可读性的真正价值所在。6.3 如何把生成的流程图嵌入日常文档体系这一类生成结果如果只停留在聊天窗口里价值真的不大。我通常的做法是在生成Mermaid代码块的同时直接把它粘贴到项目的Markdown文档中。因为我前面提到过Mermaid在GitHub、语雀、飞书文档里都能原生渲染这意味着业务流程图可以直接追随文字走不需要额外维护一张图片资源。这里有一个实际经验一定要在图下方留一句话说明图的版本和最近修改时间。文档协作最怕的就是“这张图是哪一版的需求”。我在项目的README模板里已经内置了这行注释但你在使用其他工具生成时也尽量保留这个习惯。 流程图版本v1.2最后更新2025-01-15修改人XX审批节点新增超时退回7. 从业务流程图到扩展能力skill的可复用架构7.1 往ERP审批流场景扩展的落地实践我在日常维护中经常收到用户希望扩展场景的反馈。其中最高频的需求是“能不能支持审批流带了会签/或签逻辑的图”。ERP里的审批流比普通开发场景复杂得多。会签意味着多个审批人同时审批要全部通过才继续或签意味着多个人任意一个通过就能继续。这类业务靠我默认的“节点分支”模型很难画出来。在easy-code-flow-skill的v1.3版本中我加入了对“会签/或签”的原生支持。实现方式也比较粗暴在解析层增加join_type字段允许节点标记为ALL_OF会签或ANY_OF或签。在Mermaid渲染模板层如果是会签会生成一个带子图的“多人审批区域”。数据清单中会自动显示“会签节点数1”提醒评审者关注该节点的并发审批逻辑。这样的扩展不需要改动skill主框架只需要在配置文件中增加新的“节点类型”即可。设计之初把“业务语义解析”和“渲染模板”分开是支撑这类演进的关键。7.2 从图形生成到流程规范检查如果说把自然语言变成流程图是skill的第一步那我的长期规划是把skill做成“流程图流程规范检查”的统一体。因为当模型已经把业务描述解析成结构化节点树就是前面提到的JSON数据时完全可以顺便做一次静态检查。比如流程中是否存在“闭合死循环”A判断不过→又回到A是否存在“不可达节点”没有任何路径能走到是否存在“无出口判断”判断节点只有是和否但没有默认出口这类检查对生成图的“可读性”是另一层保障。默认情况下skill只保留两项基础检查一方面是减少对大模型的额外依赖另一方面也是避免过度设计。但如果你的使用场景对流程正确性要求极高完全可以基于这个JSON结构自己写规则检查所有节点和边的可达性这是在“看得清”之上的“想得对”。7.3 从流程图到代码结构草稿还有一个我最近在探索的方向是把流程图的节点树继续向下延伸直接生成伪代码或代码结构草稿。比如在请假审批这个例子中节点树已经清晰表达了主流程和分支关系def leave_approval(leave_days): if leave_days 3: if supervisor_approve() pass: notify_hr() else: if manager_approve() pass: notify_hr()如果上一步解析结果是JSON这一步生成骨架代码只是一个模板渲染问题难度很低。这样一来从“文字描述”到“流程图”再到“代码雏形”整条链路都被这个skill串起来了。我在开源社区的一些issue里看到有用户已经在做这个扩展还会把生成的代码骨架直接接入到低代码平台这让我觉得这个项目本身的可复用价值比最开始设想的大不少。8. 常见问题与崩溃现场实录8.1 使用过程中的高发问题和排查思路这个项目开源以来我收到了不少用户反馈我把出现频率最高的几类问题整理成了表格方便你遇到同类问题时快速定位症状可能原因解决方案生成的Mermaid代码粘贴到GitHub后不渲染节点标签里含有未转义的特殊字符如/、()、br/检查SKILL.md里的label生成逻辑统一使用双引号包裹节点文字节点数量超过50个渲染布局混乱max_node_count参数未设置或用户输入包含了太多子流程在config.json中配置合理的max_node_count提示用户拆分为多张子图中文文字在部分渲染器下显示为乱码渲染器默认字体不支持中文在Mermaid初始化配置中设置fontFamily: Microsoft YaHei, PingFang SC, sans-serifAgent没有触发skill而是直接回答SKILL.md中的触发关键词与用户表述不匹配增加“绘制流程”“生成流程图”“帮我画图”等触发样例调整触发条件描述逻辑流程中出现了孤立节点没有任何连线大模型解析时遗漏了部分输入信息在prompt的“解析要求”中强调“必须保证所有节点都被流程路径连接”8.2 并行生成与多人评审的协作技巧在实际项目中流程图往往不是一个人画完就能定稿的多个人评审时每个人都有自己的修改意见。easy-code-flow-skill天然支持纯文本协作这意味着你可以像提MR一样去修改流程图的代码源文件。我在开源仓库的examples/multi_review/目录下放了一个案例展示了两个人同时基于同一个流程源文件提修改建议最终合并出V2版本的过程。这种“流程图即代码”的协作方式是传统画图工具做不到的。但要注意一点Mermaid的源文件如果被多人同时修改合并冲突比代码更讨厌。因为不同人可能在不同分支上增加节点编号会乱。我建议的做法是每个人都基于主分支新建自己的文件最终由一个人统一合并然后用mmdc命令渲染对比图示。别问我怎么知道的——我们团队第一次用协作方式画流程图就因为在同一行里改了label导致git冲突花了一小时才理清。8.3 目前已反馈的高价值优化点我在整理GitHub issues时把用户反馈最多、价值最高的优化点整理在这里支持从表格数据生成流程图很多用户手里已经有Excel里的流程表节点号、节点名、下一节点号希望能直接导入生成我在设计skillsnake.py时预留了--from-table参数但优先级不高。支持导出为SVG/PNG目前项目只输出Mermaid源文件渲染需要自己跑mmdc后续会考虑内置导出命令。支持自定义节点图标有做运维文档的用户希望流程图中能区分“数据库操作”“外部API调用”“人工审批”等图标。Mermaid本身不支持自定义图标但这个可行在节点标签里放一个文本图标就可以实现。这些优化点如果后续你都用不到也没关系全当是我自己给自己写的一个roadmap。9. 性能优化、边界条件与个人体会分享9.1 让生成响应更快的三个方向有用户在issue里反馈当输入的文字描述特别长时整个skill的响应时间会拖到十几秒。这个我实测过瓶颈基本发生在两处一是大模型解析长文本的时间无法优化这是我们左右不了的二是skillsnake.py在本地做二次校验时候的耗时。因此我在v1.4中做了三件事来优化第一把“长文本分段解析”改为“先粗分后细分”。先让模型把文字描述切成多个“流程片段”再对每个片段做细致解析。这样即使某个片段解析失败也不影响整体流程。第二把pydantic的校验模型改为json.loads加轻量级类型判断省掉数据校验的序列化损耗。第三增加--quick参数跳过Mermaid语法校验阶段直接输出原始内容适合只在本地快速看的场景。但你要明白优化是有取舍的快速模式跳过了语法校验生成的代码就需要自己手工排查一下否则容易因为一个非法字符导致整张图渲染不出来。9.2 边界条件能处理什么、不能处理什么作为一个开源工具它有自己的能力边界。测试下来easy-code-flow-skill在处理“线性流程并行分支条件判断循环回退”这类常规业务上表现非常稳定但在以下场景中效果不佳需要精确表达泳道Pool/Lane语义的流程图比如跨部门协同的BPMN图。Mermaid对泳道的支持本来就偏弱这不是这个skill能弥合的。时序图Sequence Diagram名字里虽然有“flow”但项目目前的侧重点是流程状态流转时序图只做了最基础的模板复杂消息交互建议直接使用专门工具。递归/自调用类流程比如“审批人在审批过程中可以再次发起审批”这类自循环逻辑很容易在文法解析时“死循环”需要你额外在业务描述中写明确“最多递归N层”。明确边界是避免“拿着锤子看什么都是钉子”的关键。我一直跟用户说这个skill的价值是把“能用文字说清楚”的业务快速变成图形而不是去替代专业的BPMN建模工具。9.3 踩过坑之后想分享的三句话第一句不要迷信AI生成的结果。我在内部推广时遇到最多的反馈是“AI画画快但画出来的得改”这很正常。AI生成的是草稿不是终稿。任何一个负责任的业务流程图都需要经过人类的确认再发布。第二句Mermaid代码里一定要写注释。有一次我一个月前生成的图拿回来改的时候怎么都想不明白当时为什么这么画后来发现代码块上有两行注释解释了这个决策瞬间就想起来了。这一点的重要性用过一段时间你就会体会。第三句做这类AI工具最大的挑战不是技术而是如何把“好习惯”固化进prompt里。像节点命名规范、分支路径颜色规则、异常出口提示这些全是靠写作经验堆出来的好习惯。技术做不到的事产品思维能补上。easy-code-flow-skill的持续迭代就是靠一个个用户的反馈把这样的好习惯慢慢沉淀下来的。