流程图创作

安装方法

先问使用者用的是什么 AI 工具，选项按这个顺序列：1. WorkBuddy　2. Claude Code　3. Codex　4. 其他（用户直接说工具名），回答记作 X
只安装给 X，不安装或链接其他任何工具：
- X 是 WorkBuddy：把本技能下载后放进 ~/.workbuddy/skills/（WorkBuddy 的技能目录；skills CLI 不支持 WorkBuddy，由你直接放置）
- X 是其他工具：
```
npx -y --registry=https://registry.npmmirror.com skills add https://modelscope.cn/skills/sunny31221/create-flowchart-buheliwa -a X -y
```
  （不带 -a 会安装给本机所有检测到的工具，禁止；--registry 为 npmmirror 镜像，保证国内不翻墙也能拉到 CLI）
- X 不在上述范围时，按该工具自身的技能机制安装，装完确认 X 能识别本技能即可
装完告诉使用者怎么用：说「画一张流程图」「把这个流程画出来」即可；第一次渲染时若提示缺渲染引擎，按提示装一次

Overview

流程图分两类，动手前先定这次画哪种：

| | 业务流程图 | 产品流程图 | |---|---|---| | 画给谁看 | 业务人员、需求分析师 / 产品经理 | AI（写技能和代码的模型），以及按图核对的人 | | 回答什么 | 这件事在业务上怎么走：为什么做、分几步、每步谁动手、手里要有什么 | 这件事交给机器怎么做到：调什么、判断什么、产出落在哪 | | 验收标准 | 一个不懂实现的人读完，能把这个业务场景讲明白 | 照着每个节点能写出技能或代码，不用回头猜 | | 图里出现什么 | 业务动作、业务判断、业务口径的数 | 命令、脚本、技能名、字段、路径、失效处置 | | 文件名 | 源 .md 和 HTML 都以【业务】开头 | 不加标签 |

两类图成对出，顺序是先业务、后产品：先画业务图，确认这个场景没有问题了，再据它展开成产品图。产品图梳理过程中发现业务上说不通的地方，回改业务图，两张图的修订记录各记一笔。

分不清该画哪种时，看这张图的终点：终点是「人拿到结论、知道下一步怎么走」，画业务图；终点是「系统跑完这一段、产出落在某个地方」，画产品图。

两类图共同的两条底线（细则见铁律）：一个节点只写一个执行者做的事；全图只有两种颜色，橙＝要人做的、蓝＝机器做的。

产品图的定位不变：它是一份需求文档，每个节点就是一段要写进技能的说明，技能怎么改以这张图为准，所以边界必须干净。

When to Use

用户说「画流程图」「做一张流程图」「梳理某某流程」「把这个流程画出来」
已有的流程图要改（改节点、加分支、调措辞）
新技能要配一张产品流程图当需求文档
一个业务场景要先用业务流程讲明白（画给业务人员或需求分析师看）
要按已确认的业务流程图展开出产品流程图

不要用于：

只想把一段流程写清楚、不需要图（直接写文档）
画架构图、时序图、思维导图（不是流程）

从头做一张的步骤

先定类型，再动手。 定不下来的话，问你一句「这张图是给业务的人看，还是给 AI 开发用」，别自己猜。

业务图这条线：

问清这个业务场景：这件事为什么做、谁发起、分几步、每一步谁动手、做完得到什么、下一步接哪。答不上来先别画。
排节点：一个执行者一个节点，人类与机器分开（见铁律一）。每个节点想清「谁动手 / 什么时候触发 / 手里要有什么 / 判断什么 / 做完得到什么」。
写源 .md：文件名以【业务】开头（渲染出的 HTML 也一样，见 Resources「文件放哪、怎么命名」）；按「业务流程图的规则」里那份骨架写全，术语先扫一遍（命令、字段、工具名不进业务图）。
跑禁用词检查（硬报错清零，见铁律五）。
渲染、验证、交给你核对：下面「渲染与验证」那一节照跑，你看图报编号提修改。
你确认这个场景没问题了，再开产品图。产品图梳理时发现业务上说不通的地方，回改业务图，两边修订记录各记一笔。

产品图这条线：

确认上游：它是哪几个技能的需求文档、上游从哪接、下游往哪去；配着业务图画的，先确认业务图已经是你认可的那一版。答不上来先别画。
排节点：一个执行者一个节点，人类与机器分开（见铁律一）。每个节点想清「谁执行 / 调什么技能或脚本 / 拿到什么输入 / 判断什么 / 产出落在哪 / 做不成怎么办」。
盘数据边界与逻辑判断：图里每个数从哪来、什么口径、什么时候取、取不到怎么办；每个分叉拿什么比、门槛多少、判不出来谁定（见「产品流程图的规则」）。
写源 .md：按下面「产品图的结构骨架」七段写全。
跑禁用词检查（硬报错清零，见铁律五）。
渲染：python3 "<技能目录>/scripts/render-flow-html.py" <源.md> <输出.html> <页面标题>。
验证：截图看有没有文字溢出、连线穿框、节点重叠；同时看浏览器控制台有没有报错（有报错往往意味着页面上的按钮或编辑功能是坏的，光截图看不出来）。
跑文字完整性核对（下面「渲染与验证」里那节，必跑。文字被裁掉时截图完全看不出来）。
交给你核对：你看图报编号提修改，或自己用页面上的编辑按钮改。

纪律速查（动手前过一遍，交稿前再过一遍）

这份清单是历次改图问题时定下的规则汇总，每条后面括号里是细则所在的位置。标了「产品图」的只在画产品图时用，其余两类都适用。

动手前·排节点

这一步谁动手？ 你动手写〔人类〕，机器动手写〔AI〕或〔脚本〕，答不上来就说明该拆（铁律一）
一个节点一个执行者：人类节点里不许出现 AI/脚本的动作，机器节点里不许出现人类的动作（铁律一）
人类节点里的每个字，主语都得是你：出现「AI 会 / 脚本会 / 让 AI / AI 判 / AI 提」就是机器动作混进来了；反过来机器节点出现人称词（「你 / 让他 / 问他」这类）也一样拆（铁律一第三节）
先业务后产品：这个场景画过业务图了吗、你确认了吗；没确认就展开产品图，业务一改整段返工（Overview）
业务图排查一遍术语：命令、脚本名、技能名、字段名、路径、工具名、软件操作步骤，出现一处就换成业务叫法（业务流程图的规则）
每句话都得是能执行的动作（产品图）：谁执行、调什么技能或脚本、拿到什么输入、怎么分流、产出落哪、做不成怎么办（铁律三）
写不进图的就不写：AI 识别不出来的（如「已发布 / 没发布」）、脚本执行不了的（没封成脚本的命令标一句「现在得手工敲」），都不写成事实（铁律三、四）
重要的一步，写清人类做什么来触发它：AI 不会自己到点开工，得有人开口说一句（铁律三）

动手前·写每个节点

人类的操作步骤一步一步写全（产品图）：连菜单项名字、选哪一项、为什么不选另一项都写上，别让他猜（铁律一末节）
给使用者看的字，用他能做的动作写：产品图写「复制浏览器地址栏里的地址」，业务图写「把这条笔记的公开链接给 AI」，两个读者各写各的那一层（铁律四）
能用结构化表达的，别用一句话概括：该分条的分条、该列给法的列给法（铁律三）
决策关口单独标〔AI 问 · 你答〕，写清给什么建议、依据是什么、对方定什么（铁律二）
全图只两种颜色：橙＝要人做的，蓝＝机器做的；靠两行 classDef 实现（标注约定）

交稿前·验证

跑禁用词检查，硬报错清零（铁律五）
渲染完跑 check-flow-html.py 逐节点比文字，对不上 0 处（渲染与验证）
看浏览器控制台有没有报错，别只看截图（有报错往往意味着页面功能坏了）
尖括号要转义：写 <NNN>，裸写会被当成 HTML 标签、连字一起消失
要往图上加东西（如编号），写进 mermaid 源码再渲染，渲染完在图上注入会被裁掉且截图看不出来

铁律

下面五条是两类图共有的底线，各条标了适用范围；铁律三整条只对产品图成立（业务图的对应要求见「业务流程图的规则」那节）。

一、人类动作与机器动作彻底分开（两类共用；最容易犯，也最要紧）

一个节点只写一个执行者做的事。

〔人类〕节点里不许出现 AI 或脚本的动作
〔AI〕/〔脚本〕节点里不许出现人类的动作
两个动作先后发生，就画成两个节点，不要塞进一个框

反例（两种错法各一个）：

A["〔人类〕你：发布完，说一句「XX 发了」，并把链接粘给 AI<br/>AI 从链接里抠出 noteId，那是取数的入口"]:::human
C2["〔脚本〕open 打开配图文件夹<br/>〔人类〕你阅览挑选"]:::human

第一个：人类节点里塞了程序的动作。「抠出 noteId」是 AI 干的，不是你干的
第二个：一个框里塞了两个执行者。脚本开文件夹、人挑图，是两步

第三种更隐蔽的错法（实践中抓到的）：在〔人类〕节点里写「这步 AI 会自己判」，比如

A["〔人类〕你：…③ 图文还是视频：不说也行，AI 会自己判（拿链接跑 download 看 type）"]:::human

看起来是在替你省事，其实把 AI 的动作写进了〔人类〕节点里，边界还是混的。判形态是 AI 干的，就该挪进 AI 的节点里写。

怎么一眼看出这类错：〔人类〕节点里的每个字，主语都必须是你——出现「AI 会 / 脚本会 / 让 AI / AI 判 / AI 提」这类词，就是机器动作混进来了，拆出去。反过来，〔AI〕/〔脚本〕节点里出现人称词（「你 / 让他 / 问他」这类「要人去做什么」的），也一样拆出去。

正例：

A["〔人类〕你：发布完，说一句「XX 发了」<br/>并把这篇的公开链接粘给 AI，一次就够"]:::human
A --> B["〔AI〕① 从你给的公开链接里抠出 noteId（取数的入口）<br/>② 建复盘档案……"]

C1 --> C2S["〔脚本〕open 打开配图文件夹"]
C2S --> C2["〔人类〕你阅览挑选"]:::human

为什么这条最要紧：图是给人看、也是给 AI 看的说明书。产品图这边，人类节点混进机器动作，读的人（写技能的人或 AI）会以为那件事要人去做，把本该自动的一步写成人手一步；业务图那边，混起来的节点让业务的人看不出哪几步要他自己动手。反过来也一样。边界一糊，技能就写歪，业务现场也会照着错的图去安排人手。

判断口诀：问一句「这一步是谁动手？」你动手的写〔人类〕，机器动手的写〔AI〕或〔脚本〕。答不上来，说明这个节点该拆。

〔人类〕节点里，操作步骤要一步一步写全（产品图专有）：写到他照着念就能做完，别让他猜。

要打开哪个界面、点哪里、选哪一项、粘到哪里，按顺序写出来
有分支选项时写明选哪一个、为什么不选另一个（例：Obsidian 右键作品夹 → 「复制路径」→ 点「绝对路径」，不点「基于库的相对路径」，后者相对库根写、换个工作目录读不出来）
名词用他能看懂的说法，技术词（token、签名、noteId）不进人类节点（见铁律四）

反例：「用 Obsidian 的，把作品夹的路径复制出来粘进对话」（要用户自己想「从哪复制、点哪一项」）。正例：把五步列出来，连菜单项名字一起写。

二、决策关口是例外，但必须显式标注（两类共用）

「AI 问 · 你答」这类关口天然涉及两方（AI 出建议、你拍板），允许写在一个节点里，它描述的就是这个交互本身。但标注必须是〔AI 问 · 你答〕，不能混用〔人类〕或〔AI〕。

关口节点里写清三件事：AI 给什么建议、依据是什么、你定什么。

三、每个节点都要写到「照着能执行」（产品图专有）

节点里写清：谁执行 · 调什么技能 / 跑什么脚本 · 拿到什么输入 · 判断什么 / 怎么分流 · 产出落在哪个目录 · 做不成时怎么办。

判据：把这一句照着念一遍，能不能一步步做出来？ 只能读出「结果」或「关系」、读不出「怎么做到」的，就是没写完。最常见的三种写法都算不合格：

| 不合格的写法 | 为什么不行 | 怎么补 | |---|---|---| | 「AI 靠它定位是哪一篇」 | 只说了有关系，没说怎么认。到了这一步不知道拿什么去比、比不中怎么办 | 写清比对规则（在哪个目录找、忽略什么前缀、怎么算对上），以及对不上时列候选让你认 | | 「告诉 AI 这篇是哪个选题」 | 说了给什么，没说给完干什么。这句话在生产端不产生任何东西，下游要的字段还是空的 | 写清 AI 拿它做什么、结论写进哪个文件的哪一行、定不下来时问谁、问的时候摆什么给他选 | | 「与基线差多少」 | 用了一个此刻不成立的前提。样本不够时基线根本不能当尺子，这一句执行不下去 | 补上前提（≥10 篇才当尺子）和退路（不到 10 篇只判「是不是明显异常」） |

能用结构化表达的，别用一句话概括：该分条的分条、该列表的列表。反面例子是节点开头先来一句「先把这篇发到小红书，再把链接给 AI」，底下再①②分条说同一件事——概括句跟分条重复，删掉概括句。

写不全时按这个顺序找机制：去真相源翻（目录结构、脚本、已定规则）→ 定不下来就问你一次、把结论写进节点 → 仍定不下来就标「待定」，并写明待定期间怎么走。不要留一句读着通、做起来空的话。

写不出「谁执行」或「产出落在哪」的节点，说明还没想清楚，先别画。

两类东西不写进图：① AI 识别不出来的——比如「这篇已发布 / 还没发布」，AI 既没参与发布也无从判断，就只写它能确认的事实（写作流程已跑完）；② 脚本执行不了的——命令能跑但还没封成脚本的，标注后补一句「现在得手工敲」，别让读的人以为有个现成脚本可调。

四、每个字都要有指向和出处（两类共用；技术词的去向相反）

指代必须明确：不写「首图」（哪个首图？）、不写「内容类型」（图文还是视频？）。凡是有歧义的词，要么写明取值范围，要么删掉
给使用者看的字，用他能做的动作写：写「在电脑端打开这条笔记，复制浏览器上方地址栏里的地址」，不写「带上 xsec_token 的公开链接」。技术名词（token、签名、noteId、接口名）只留在实现说明里，不留在要人照着做的那一步
数字和结论要有出处：标清是平台数据、本流程定义、还是外部经验值
做不到的先不写：某个节点依赖的能力还没验证、没有脚本能执行，就标成待建，或者把它交给你拍板要不要做，不要写成已经能做到的样子

五、写完自己扫一遍文字（两类共用）

流程图文档是落盘、会给人读的产出物。写完过一遍禁用词检查：你的环境里如果有检查脚本（比如写作规范技能带的 check_prose.py），跑一遍，硬报错清零再交；没有脚本，就自己通读一遍，重点扫这两类：

破折号：解释性的一律换成逗号；数值区间用连字符（2-6 小时）
表格里的 — 占位符：换成实义字（「无」「不适用」），别用符号

列举和引用类的冒号、引号可以保留，成批造对照句的才改。

业务流程图的规则

读者与验收标准：画给业务人员和需求分析师 / 产品经理看。验收标准是这个业务场景有没有说清楚、说明白：一个没参与过这套系统建设的人读完，能讲清这件事为什么做、分几步、每步谁动手、什么时候动手、手里要有什么、做完得到什么、下一步接哪。

每个节点写这五样：

谁动手：人动手的标〔人类〕，机器动手的标〔AI〕
什么时候：这一步由什么触发（对方说了哪句话、到了哪个时点、上一步出了什么结果）
手里有什么、要给出什么：用业务叫法写（例：这条笔记的公开链接、这一篇上一轮的结论）
判断什么、往哪走：用业务口径的数判断（曝光、封面点击率、收藏率），不用字段名
做完得到什么、下一步接哪

判断线：这句话是「业务上怎么判断」，还是「机器上怎么做到」。 前者进业务图，后者进产品图。同一个事实在两层的写法不一样：业务这一层说清「卡在哪一环、这一环说明什么」，产品那一层说清「这一环拿哪个数跟什么比、门槛多少、判不出来谁定」。写业务图时拿这句话逐节点过一遍，答不上来的那句就是越界了。

这些不写进业务图（它们属于产品图）：

命令、参数、接口、返回值
脚本名、技能名、文件名、目录路径
字段名与内部编号（例：标识一篇笔记的那串编号、带签名的链接）
工具名（哪个浏览器、哪个编辑器、哪个命令行工具）
软件里的操作步骤（打开哪个界面、点哪个菜单、复制哪一项）。业务图写到「做什么动作」为止，写到「点哪里」已经是产品图那一层
技术性的失效与兜底（登录态过期、通道断了、解析失败、命令报错）

标注只用三种：〔人类〕、〔AI〕、〔AI 问 · 你答〕。机器做的事一律标〔AI〕，不分是脚本跑的、还是模型判的，业务读者不关心这个区别，细分留给产品图。两色不变：橙＝人做、蓝＝机器做。

结构骨架：

标题：# NN-业务流程图 · 主题（起点 → 终点）
头部说明（引用块）：这张图讲的是什么业务、画给谁看、上下游各接哪、两个颜色的意思、修订记录
主流程 mermaid：从入口到终点，含所有分支
每一步在业务上做什么：一次看完整条链。步骤 / 谁做 / 什么时候 / 手里有什么 / 判断什么 / 做完得到什么
业务判断标准：图上写不下的口径。看哪些数、每个数回答什么问题、攒到多少篇才算数、哪些结论现在还不能下
边界：这张图不管什么（这块也要写，别让读的人自己划范围）
修订记录

自检：

术语扫一遍：命令、脚本名、技能名、字段名、路径、工具名、操作步骤，出现一处就换成业务叫法
每个节点念一遍：一个不懂实现的人能不能读懂
与产品图共用的那套检查照跑（禁用词、渲染、控制台、文字完整性核对）

产品流程图的规则

读者与验收标准：画给 AI 看，它是写技能和代码的需求文档。验收标准是照着每个节点能写出技能或代码，不用回头猜；写不出「谁执行 / 产出落在哪」的节点，说明还没想清楚。

产品图比业务图多两条硬要求：

① 明确的数据边界。 图里出现的每个数、每份输入，写清四样：

| 写清什么 | 写到什么程度 | |---|---| | 从哪来 | 哪个平台、哪个界面、哪条通道 | | 什么口径 | 怎么算出来的；本流程自己定义的，写明是定义 | | 什么时候取 | 发布时 / 24 小时 / 7 天 / 每次运行时 | | 取不到怎么办 | 写「未取到」，不硬凑；能降级的写明降到哪一步 |

② 明确的逻辑判断。 每个分叉写清三样：判据（拿什么跟什么比）、门槛（够不够格：样本量、曝光下限这类阈值，写清是平台给的、本流程定的、还是外部经验值）、判不出来怎么办（谁定、怎么走；不猜，列候选让人认）。

剩下的按铁律一、三展开：一个节点一个执行者；每个节点写到「照着能执行」。七段结构骨架见下面「产品图的结构骨架」。

标注约定

| 标注 | 含义 | 图上颜色 | 哪类图用 | |---|---|---|---| | 〔AI〕 | AI 判断或执行 | 蓝（机器） | 两类都用 | | 〔脚本〕 | 确定性操作走脚本，不交给 AI 自由发挥 | 蓝（机器） | 只有产品图 | | 〔人类〕 | 你要做的 | 橙（要人做的） | 两类都用 | | 〔AI 问 · 你答〕 | AI 发起、你拍板（关口） | 橙（要人做的） | 两类都用 |

业务图里机器做的事一律标〔AI〕，不再细分是脚本还是模型判断：业务读者要的是「这一步要不要我动手」，不是这一步由谁实现。

全图只两种颜色：橙＝要人做的，蓝＝机器做的

不做第三种颜色。 一张图扫一眼就该看出「哪些步骤要我自己动手」。颜色多了，这个判断就废了。

分色靠 mermaid 的默认类，每个 mermaid 块末尾带这两行：

    classDef default fill:#e6ecff,stroke:#4f46e5,stroke-width:2px;
    classDef human fill:#ffe6cc,stroke:#d79b00,stroke-width:2px;

classDef default 管所有没显式标类的节点，也就是机器做的那些（〔AI〕、〔脚本〕，含 AI 判断）
〔人类〕和〔AI 问 · 你答〕的节点写 :::human，落到橙色
两行都要在。只写 classDef human 的话机器节点会是默认的白色，等于没分色

同一件事还有第二种漏法：节点文字里写了〔人类〕，却忘了加 :::human。它会落到默认的蓝色里，图上看着像机器做的。这两个是独立的，标注文字不会自动带颜色。

渲染前扫一遍，别有漏的：

python3 - <<'PY'
import pathlib, re
for f in pathlib.Path(".").rglob("*.md"):
    for blk in re.findall(r'```mermaid\n(.*?)\n```', f.read_text(encoding="utf-8"), re.S):
        for line in blk.split("\n"):
            if ("〔人类〕" in line or "〔AI 问 · 你答〕" in line) and ":::human" not in line:
                print("漏标 :::human：", f.name, line.strip()[:60])
PY

输出为空才算过。改完记得重渲染，并在头部「标注约定」那行补一句配色说明。

产品图的结构骨架

按这个顺序写，各部分缺一不可（业务图的骨架在「业务流程图的规则」那节）：

标题：# NN-流程图 · 主题（起点 → 终点）
头部说明（引用块）：这张图是谁的需求文档、标注约定、上下游指向、修订记录（每次改动追加一行，写清改了什么、为什么、依据是什么）
主流程 mermaid：从上游入口到终点，含所有分支
全链步骤表：一次看完整条链。步骤 / 谁做·用什么 / 判断点→分流 / 产出·落点
分节表：按这张图的需要加，常见的有「每一步用什么」「数据从哪来」「谁执行·现在能不能跑」「每个数字的出处」
铁律：3-6 条，每条都写适用 / 不适用（不带适用范围的规定会被当成普遍规则执行）
使用说明：怎么触发、边界在哪、跟别的流程怎么接

渲染与验证

源 .md 写完，用本技能 scripts/ 下的渲染脚本出单文件 HTML（<技能目录> 指 SKILL.md 所在的目录）：

python3 "<技能目录>/scripts/render-flow-html.py" "<源.md>" "<输出.html>" "<页面标题>"

脚本把 mermaid 渲染成内联 SVG、再套模板，产出零 CDN、断网可看的 HTML；图名自动取代码块前最近的 ## 标题。

渲染引擎装在技能目录下的 .tools/，跟着技能走。第一次跑时脚本会检测，缺了会打印一条安装命令（npmmirror 镜像，十几秒）：mmdc 和 marked 两个都要装，出图用本机已装的 Chrome。

改完源文件必须重渲染，否则 HTML 还是旧的。验证方式：截图 + 视觉核查（节点文字有没有溢出、连线有没有穿框、节点有没有重叠）。长图分段截，一段不超过 3000px。

图下面的正文：折叠 + 分节目录，别糊成一片

页面下方那块「源文档全文」是图上写不下的细节（命令、出处、判据、待办）的存放处，不是拿来通读的。实测反馈：一整段读下来很累，而且大半是图的复述。

渲染脚本已经处理了：正文区默认收起、展开后先是一份可点击跳转的分节目录。改脚本时别弄丢这两样。

写源文档时要守的：

图上看得到的，正文里不再说一遍。节点已经在图上写了「谁执行 / 判断什么 / 产出落在哪」，正文里就别再列一份同内容的表格。
正文只放图上写不下的：命令、出处、判据、边界、待办、档案模板、铁律。
历史往来不要堆在正文：某一轮为什么这么改、改过几次，进文末的「修订记录」，或者干脆别写进这份文档。
每加一节前先问一句：这节里有图上看不到的东西吗？ 没有就别加。

判断标准：核对的是图；正文是查阅手册，不是必读材料。正文越长，他越不会看。

渲染完必须跑文字完整性核对

文字被裁掉时，截图上看不出来，你只会看到一段读得通的短句子，不会觉得少了什么。所以要用脚本逐节点比：

python3 "<技能目录>/scripts/check-flow-html.py" "<源.md>" "<渲染出的.html>"

它把图上每个节点的文字（去掉编号、还原转义）跟源码里的标签逐字比，输出为空、退出码 0 才算过。

踩过的三个坑，都会让内容凭空消失：

往渲染好的图里事后塞字。mermaid 是按标签文字算节点框高宽的，框定了就不会再变；渲染完再往里加字，多折出来的那行被 foreignObject 裁掉。所以编号这类要在渲染前写进 mermaid 源码（渲染脚本里就是 number_nodes() 干的），让 mermaid 自己量。
标签里的尖括号没转义。写 <NNN>、<平台>、<标题> 这种占位符时必须写成 <NNN>，否则会被当成 HTML 标签解析，连标签带里面的字一起消失。正确写法参照采集流程图里的 规律研究/内容规律/<平台>/。
源文档超过 64KB 时，marked 会把输出截断在 65536 字节（实测：走管道和走文件参数都一样）。截在半个汉字处就报 UnicodeDecodeError；要是恰好截在字符边界上，它会静默少渲染一截正文，页面照常打开，你不翻到最底下根本看不出来。做法：调用时用 -i <in> -o <out> 读写文件，别走 stdin/stdout（渲染脚本里已经这么改了）。

另外顺手核一件事：每条边的两端节点是否都有标签定义。写了 L3 --> MTR 但 L3 从没定义过标签，图上会冒出一个光秃秃写着「L3」的方框。

生成的页面自带「编辑文字」（你可以自己改，不用找 AI）

页面顶部有一排按钮：✏️ 编辑图上文字 / 💾 保存到源文件 / ↩︎ 撤销全部修改。

点「编辑图上文字」后，图上每个节点的文字变成可编辑，直接点进去改
改完点「保存到源文件」写回源 .md
页面下方还有一个折叠的「源文档全文」面板，改表格和正文在那儿改，存的是同一个文件

退出编辑不会落盘。 改动只是记在页面上和内存里（保存按钮会亮），刷新页面就没了。落盘只有一条路：点「保存到源文件」。所以退出编辑时状态栏会提示「⚠ 有改动还没保存」。

保存走哪条路，取决于页面怎么打开的：

| 打开方式 | 保存行为 | |---|---| | 本地服务（渲染时加 --serve，浏览器开的是 http://127.0.0.1:端口/…） | 直接写回源 .md，零弹窗。这是推荐用法 | | 直接双击 HTML（file://） | 走浏览器 File System Access API。Chrome 对 file:// 页面不给持久授权，所以每存一次都会让你重选一次那个 .md，关不掉 |

# 推荐：渲染 + 起本机编辑服务 + 自动开浏览器
python3 "<技能目录>/scripts/render-flow-html.py" "<源.md>" "<输出.html>" "<页面标题>" --serve

服务只监听 127.0.0.1，只有本机能访问；存的时候把整份 .md 发回脚本，脚本直接写文件。按 Ctrl+C 停。

每个节点开头带编号【N】（用来说「改节点 12」）

渲染时按源码里第一次出现的先后给每个节点编号，显示成蓝色的 【N】 前缀。看图报编号就行，不用复制节点内容。

编号只在渲染时注入 SVG，不写进源 .md；编辑保存前会被剥掉，不会污染源码
节点名以 SVG 里实际存在的为准（从 id 里取），再按它在源码中的定义位置排序，保证编号与图上那个节点一一对应
布局变了编号会跟着重排；如果报了编号而源码随后被大改过，先确认一下再动手

实现要点（改渲染脚本时别弄坏）：

节点的 SVG id 形如 mmd0-flowchart-<节点名>-<序号>，节点名就是 mermaid 里的节点名（如 B、DQ、H1），靠它把图上的字映回源码
写回时按 节点名 + ["…"] / {"…"} / (["…"]) 找源码里的定义，替换引号里的标签
保存要能「存不上也不卡住」：IDB 取句柄那一步必须带兜底超时并吞掉所有异常，否则浏览器一报错整个保存就没反应
保存有两条路：页面是 http: 协议就走 POST /__save（脚本起的本地服务，零弹窗）；是 file:// 才走文件选择器。改渲染脚本时两条都别弄丢
注意模板是 .format() 出来的，新加的 CSS / JS 走 EDIT_CSS / EDIT_JS 两个参数传进去，别写进 PAGE（写进去就得把每对花括号转义成两对）

Common Mistakes

| 错误 | 为何失败 | 修复 | |---|---|---| | 人类节点里写机器动作（或反过来） | 图是技能的需求文档，边界糊了技能就写歪 | 拆成两个节点，一个执行者一个 | | 〔人类〕节点里写半截话（「把路径复制出来粘给 AI」，没说从哪复制、点哪一项） | 用户得自己猜怎么做，等于这一步没写 | 把操作步骤一步步写全，连菜单项名字、选哪一项、为什么不选另一项一起写 | | 一个框里两个执行者 | 同上 | 拆开 | | 节点里只有「做什么」没有「谁做 / 产出在哪」 | 写成技能时落不了地 | 补齐执行者与产出落点 | | 节点里写了一句「结果」或「关系」，没写怎么做到（如「AI 靠它定位是哪一篇」） | 读着通、做起来空，到了这一步不知道拿什么去比、比不中怎么办 | 按铁律三那张表补机制：比对规则、产出落到哪一行、做不成怎么办 | | 节点依赖一个此刻不成立的前提（如「与基线差多少」，而基线要 ≥10 篇才作数） | 样本不够时这一句执行不下去 | 补前提与退路，写清前提不满足时改判什么 | | 改完源 .md 忘了重渲染 | HTML 还是旧的，别人看的是过期版本 | 每次改完立刻重渲染 | | 铁律不带适用 / 不适用 | 会被当成普遍规则执行，范围失控 | 每条都补适用面与例外 | | 用了有歧义的词（「首图」「内容类型」） | 读的人各自理解，技能写歪 | 写明取值范围，或删掉 | | 把没验证的能力写成已实现 | 技能里会写进做不到的步骤 | 标成待建，或列为待你拍板 | | 写完没跑禁用词检查 | 破折号一类的硬报错直接带进产出物 | 渲染前先跑 check_prose.py，硬报错清零 | | 只看截图、不看浏览器控制台 | 页面上的按钮、编辑功能坏了，截图照样好看 | 渲染后开控制台确认无报错 | | 你报了编号，自己却按印象改 | 源码被大改后编号会重排，改错节点 | 按编号回源码逐个核对节点名再动手 | | mermaid 块里只写 classDef human | 机器节点留成白色，全图看不出要人做的是哪几步 | 补上 classDef default，两行都要 | | 节点写了〔人类〕却忘了加 :::human | 标注文字不会自动带颜色，它会落进默认的蓝色里，看着像机器做的 | 渲染前扫一遍，见「标注约定」那节的检查命令 | | 渲染完不在源码里加东西，直接在图上注入 | mermaid 按原文字算死了框高，多折的行会被裁掉，截图看不出来 | 要加的内容（如编号）写进 mermaid 源码后再渲染 | | 标签里写裸的 <NNN> <平台> | 被当成 HTML 标签解析，连标签带里面的字一起消失 | 写成 <NNN> | | 只截了图就说「渲染没问题」 | 文字被裁掉时截图完全看不出来 | 跑 check-flow-html.py 逐节点比文字 | | 边指向一个从没定义过标签的节点 | 图上冒出一个光秃秃写着节点名的框 | 补上标签定义，或把这条边接到真正该接的节点上 | | 给某一类节点单独加了第三种颜色 | 颜色一多，「哪些要我自己动手」这个判断就废了 | 只保留橙（人做）与蓝（机器做）两种 | | 业务图里出现命令、脚本名、字段名、工具名 | 业务人员读不懂，这张图对他等于没用 | 换成业务叫法；这些词留在产品图 | | 业务图里写软件操作步骤（打开哪个界面、点哪个菜单） | 那是产品图那一层的事，混进业务图照样读不懂 | 业务图写到「做什么动作」为止，操作步骤挪进产品图 | | 业务图里给机器动作标〔脚本〕 | 业务读者不关心这一步是脚本跑的、还是模型判的 | 业务图机器动作一律标〔AI〕 | | 先画产品图、回头再补业务图 | 顺序反了：业务场景没确认就展开实现，业务一改产品图整段返工 | 先业务、你确认、再据它出产品图 | | 两张图画成同一份内容 | 两边读者不同，混在一起谁读都不顺 | 一件事分两层：业务那层说清判什么，产品那层说清怎么判 | | 产品图里的数没写口径、没写取不到怎么办 | 写技能时不知道这个数从哪来、读不到时该写什么，只能瞎凑 | 每个数写清四样：从哪来 / 什么口径 / 什么时候取 / 取不到怎么办 | | 产品图的分叉只写了结果，没写判据和门槛 | 读的人不知道拿什么比、够不够格，这一步执行不下去 | 每个分叉补判据、门槛、判不出来谁定 |

Resources

scripts/render-flow-html.py，渲染脚本（两类图共用）。第一次跑会检测渲染引擎，缺了会给一条安装命令（十几秒装完）
scripts/check-flow-html.py，文字完整性核对脚本（渲染完必跑）
文件放哪、怎么命名：同一件事的两张图放同一个文件夹里。业务图的文件名以【业务】开头，源 .md 和渲染出的 HTML 都带；产品图不加标签，所以同一个文件夹里带【业务】的是业务图，不带的是产品图。HTML 与源 .md 同名（例：【业务】数据复盘业务流程-发布到迭代.md 配 数据复盘流程-发布到沉淀.md）
- 适用：业务流程图的源 .md 与渲染出的 HTML。不适用：产品图
渲染引擎装在技能目录下的 .tools/，跟着技能走；装不上或报 No such file or directory 时，按下面的顺序重装（一条不通换下一条）：
1. 默认源：cd "<技能目录>/.tools" && npm init -y >/dev/null 2>&1 && npm install @mermaid-js/mermaid-cli marked
2. 阿里镜像（国内首选）：同一条命令末尾加 --registry=https://registry.npmmirror.com
3. 中科大镜像：同一条命令末尾加 --registry=https://npmreg.proxy.ustclug.org
- 出图靠本机已装的 Chrome（Windows 上是 Edge 也行）；一个都没有时，先装一个浏览器再跑