| name | flowchart |
| description | 「流程图 / 泳道图 / 审批流 / 状态机」触发。引擎自动选（mermaid / drawio），输出 .svg + .png 供 PRD / IMAP / PPT / 架构图 `<img>` 引用。
|
| argument-hint | ["主题 或 data 文件"] |
| type | standalone |
| output_format | .svg + .png |
| output_prefix | flow- |
| depends_on | [] |
| optional_inputs | ["baseline"] |
| consumed_by | [] |
| scripts | {"gen_flow_base.py":"双引擎统一生成器 — from gen_flow_base import render_flowchart"} |
Flowchart 流程图（双引擎：drawio + mermaid）
触发与定位
独立产出型 Skill。把业务流程 / 审批流 / 状态机 / 因果链路可视化，输出矢量 SVG + 位图 PNG。
双引擎自动 dispatch（按 chart type 字段）：
| 引擎 | 触发 type | 适用场景 | 输出文件 |
|---|
| drawio CLI | branch / swimlane | DAG 流程、泳道、决策分支、因果矩阵 | .drawio 多 page 源 + -N.drawio.svg + -N.drawio.png |
| mermaid (mmdc) | state | 状态机（含回路）、生命周期 | -N.mmd 源 + -N.mmd.svg + -N.mmd.png |
不在范围：时序图（用 IMAP 跨端时序）/ 系统架构（用 architecture-diagrams skill）/ UI 跳转图（用 interaction-map skill）。
改脚本前 30 秒
hook pre-skill-load-gate 守的是「Read 过本文件」不看读了多少行。
改本 skill scripts/gen_flow_base.py：Read 此文件 limit=80 即可。
改产出 .drawio / .mmd 源：脚本生成的，改项目侧 gen_flow_v{N}.py 重跑而非手改源。
Public API（不可改签名 · 改前看调用方）：
render_flowchart(output_path, title, subtitle, charts) — 唯一入口；调用方位置 projects/{产品线}/{项目}/scripts/gen_flow_v{N}.py- chart dict schema：
{type, title, nodes/states, edges/transitions, lanes?} —— 改字段必同步本文件 §核心输出规范
会拦你的 hook：
post-script-syntax-check — pyflakes（写 .py 自动跑）- CJK 标点 hook（写
.drawio / .mmd 自动跑，详见 §自检清单）
改完跑啥：
python3 projects/{产品线}/{项目}/scripts/gen_flow_v1.py
深入读什么：
- 引擎决策 / 节点视觉 / 数据结构：
grep -A 30 "^## 核心输出规范" SKILL.md
- drawio CLI 局限 + 手工 ELK 重排：
grep -A 15 "^### Step 5" SKILL.md
硬规则（FAIL 即拦）
- 引擎选型按数据特征：有「状态」语义就用
state → mermaid（不管有无回路）；多角色 / 因果矩阵就用 swimlane；单角色 DAG 流程才用 branch
- 回路图禁硬塞 branch / swimlane：mermaid stateDiagram-v2 原生支持回路，drawio BFS 在回路前要么炸要么靠手动 col/row 控
- decision 菱形每条出边必须有 label（"是" / "否" / "Yes" / "No"），缺 label = 视为未交付
- 失败分支用
fail，成功终态用 success——不可混用 process 蓝色掩盖语义
- swimlane 同 lane 同 col 不重复（base 会 auto-bump 但建议自己排清楚）
- label 内禁用半角
:（mermaid 语法分隔符），用全角 ：，引擎自动转
- CJK 全角标点（hook 自动拦截）：
.drawio 提 <mxCell value="..."> 内容、.mmd 提 state label + 边 label 扫
- 禁裸编号：图 label 不能出现
M-1 / A-2 / 决策 N 等内部锚点（hook check_plain_language 拦截）
- 产出统一前缀
flow-，存 projects/{项目}/deliverables/
- 多 chart 时全局 chart index 编号（无论引擎）：
flow-xxx-v1-1.mmd.png / flow-xxx-v1-2.drawio.png
核心输出规范
产物文件
每个 chart 产 2 个图像 + 1 个源文件：
flow-xxx-v1-N.{engine}.svg — 矢量，<img> 嵌 HTML / PRD md / Confluenceflow-xxx-v1-N.{engine}.png — 位图，docx 嵌入 + 预览flow-xxx-v1.drawio（drawio 合并多 page）/ flow-xxx-v1-N.mmd（mermaid 各自一文件）— 可编辑源
节点类型 + 视觉
| type | 形状 | fillColor | strokeColor | 用途 |
|---|
terminal | 圆角矩形 arcSize=40（胶囊） | #E8E5FF 紫 | #1F2329 黑 | 起点 / 终点 |
process | 圆角矩形 arcSize=18 | #E7EFFE 蓝 | #1F2329 黑 | 处理 / 操作 |
decision | 菱形 rhombus | #FDF3D5 黄 | #1F2329 黑 | 判定（Yes/No 分支） |
success | 圆角矩形 arcSize=18 | #D9F5E5 绿 | #0ECB81 绿描边 | 成功终态 |
fail | 圆角矩形 arcSize=18 | #FEE3E6 红 | #F6465D 红描边 | 失败 / 拦截 |
字体 PingFang SC / Noto Sans SC。决策菱形 180×80，其他节点 160×60（whiteSpace=wrap 自动撑高）。
引擎决策表
设计前问一遍：节点之间有没有回路？多角色还是单角色？需不需要状态语义？
| 数据特征 | 选 type | 引擎 |
|---|
| 节点 = 状态，边 = 触发事件，有回路 | state | mermaid |
| 节点 = 状态，纯单向无回路 | state | mermaid |
| 单角色 DAG 流程 ≤ 15 节点 | branch | drawio |
| 多角色泳道（≥ 2 lane） | swimlane | drawio |
| 因果矩阵（多列动作 × 多层响应） | swimlane | drawio |
数据结构
状态机（state，mermaid）
{
"type": "state",
"title": "活动生命周期状态机",
"states": [
{"id": "s1", "label": "待补全"},
{"id": "s3", "label": "已上线", "kind": "active"},
{"id": "s5", "label": "已结束", "kind": "terminal"},
{"id": "s6", "label": "已删除", "kind": "rejected"},
],
"transitions": [
{"from": "[*]", "to": "s1", "label": "业务系统同步入库"},
{"from": "s2", "to": "s1", "label": "退回字段不达标"},
],
}
字段：id 禁空格 / 特殊字符；kind ∈ {active 绿 / terminal 紫 / rejected 红}；[*] 表起点 / 终点。布局自动（dagre / ELK），回路 / 多源汇聚 / 扇出无需 col/row。
分支流程（branch，drawio）
{
"type": "branch",
"nodes": [
{"id": "Q1", "type": "decision", "label": "QI 已认证？"},
{"id": "AUTH", "type": "fail", "label": "拦截 + 引导"},
{"id": "DONE", "type": "success", "label": "进入认购"},
],
"edges": [
{"s": "Q1", "t": "AUTH", "label": "否"},
{"s": "Q1", "t": "DONE", "label": "是"},
],
}
布局：base topo BFS 自动算 col/row，decision 向左右展开。精确控制给 col row 字段覆盖。
泳道流程（swimlane，drawio）
{
"type": "swimlane",
"lanes": ["投资人", "运营", "风控", "基金经理"],
"nodes": [
{"id": "I1", "lane": "投资人", "col": 0, "type": "terminal", "label": "发起赎回"},
{"id": "R1", "lane": "风控", "col": 2, "type": "decision", "label": "合规？"},
],
"edges": [
{"s": "I1", "t": "O1"},
{"s": "R1", "t": "M1", "label": "是", "sp": "top", "tp": "bottom"},
],
}
字段：lane 必出现在 lanes 列表；col 0-indexed；跨 lane 长跳建议显式 sp/tp 引导路由。
执行步骤
Step 1：读必要文件
必读：本 SKILL.md + scripts/gen_flow_base.py（API）。
按需：用户原始流程描述（baseline / 会议纪要 / 截图）。
Step 2：梳理数据
把流程整理成 nodes + edges（branch）或 lanes + nodes + edges（swimlane）。检查清单：
- 节点 type 是否准确
- 决策菱形每条出边 label 是否齐
- 失败分支用
fail，成功终态用 success
- swimlane 同 lane 同 col 不重复
Step 3：写项目侧 gen 脚本
projects/{产品线}/{项目}/scripts/gen_flow_v{N}.py：
import sys
from pathlib import Path
BASE = Path(__file__).resolve().parents[4]
sys.path.insert(0, str(BASE / ".claude/skills/flowchart/scripts"))
from gen_flow_base import render_flowchart
CHARTS = [
{"type": "branch", "title": "...", "nodes": [...], "edges": [...]},
]
render_flowchart(
output_path=str(Path(__file__).parents[1] / "deliverables/flow-xxx-v1"),
title="流程图 · XXX",
subtitle="...",
charts=CHARTS,
)
Step 4：执行
python3 projects/{产品线}/{项目}/scripts/gen_flow_v1.py
输出按 chart type 引擎自动选。打开 PNG 自检。
Step 5：复杂图手动微调（按需）
drawio CLI 不跑 ELK auto-layout。如出现跨 lane 长跳 / 同源多边 label 重叠：
- 双击
flow-xxx-v1.drawio（drawio desktop 打开）
Ctrl+A → Arrange → Layout → Vertical / Horizontal Flow，desktop 内置 ELK 重排File → Export As → SVG / PNG，覆盖原文件
回路图直接选 state 走 mermaid，不要硬塞 branch / swimlane。
自检清单
下游消费
- PRD md 嵌图：
- IMAP / PPT / 架构图：
<img src="flow-xxx-v1-N.{mmd,drawio}.svg">（矢量缩放无损）
- drawio desktop 编辑：双击
.drawio 源文件可视化微调
失败恢复
| 现象 | 原因 | 处理 |
|---|
| 跨 lane 长边 label 重叠 | drawio CLI 不跑 ELK | desktop Ctrl+L 重排 |
| 同源 ≥ 3 带 label 边出口挤 | 同上 | 拆数据 / 手动调端口 sp/tp |
| 中文 lane title 竖排 | drawio horizontal=0 swimlane 对 CJK 默认 | 接受（标准 BPMN 中文风格） |
| 边箭头超出节点 | 节点宽度不够装 label | 拆 label 多行（用 \n） |
