Visio 流程图生成技能（vsdx-flowchart-gen）
为业务文档（需求分析、数字化解决方案、方案汇报等）生成符合 Visio 2013+ 标准的泳道流程图 vsdx。核心资产 scripts/vsdx_gen.py 纯 Python 零依赖（无需本机安装 Visio），同时输出 vsdx 交付格式 + PNG 产物图（SVG 作为 PNG 的渲染源一并落盘）。不做会话内在线预览，直接交付产物文件。
铁律：必须按三段式流程走，且有两道确认门禁——①选题方向确认、②每张图的设计定稿（泳道+起止+分支）确认。两道门禁全部通过之前，绝对不能开始制作流程图。
依赖
- Python 3.8+（脚本本体仅标准库：zipfile / xml / subprocess）
- 可选：
vsdxpip 包（三重校验中的回读校验，缺失自动跳过） - PNG 导出引擎（默认产物含 PNG，二选一自动探测）：cairosvg pip 包优先；未装则用本机 Chrome headless 兜底（Windows 标准路径探测）。两者都不可用时 PNG 失败，自动降级只交 vsdx + svg
第一段：深度理解用户文档（不可跳过）
动手前必须完整阅读用户提供的文档，并提炼出流程图所需的全部素材：
- 定位文档：找到用户的需求分析文档、数字化解决方案（或业务方案、汇报材料）。若用户没给路径，先问或在工作目录中搜索。
- 重点提取（优先找文档中的「流程图设计」「业务闭环」「关键环节流程」章节）：
- 角色/泳道：业务涉及哪些主体（系统、值守人员、企业、监管方、用户等），各自的职责边界
- 流程步骤：主流程环节顺序、每个环节的动作和产出
- 判断分支：哪些环节有是/否判断、条件分流
- 规则编号：文档中的规则/条款编号（如 V01~V07、R01~R05），节点文字必须挂接这些编号——这是评分时可核验的关键
- 特殊结构：并行分支、回流环（继续监测/退回重办）、升级链（超期升级）、跨流程引用（"转流程图二"） - 自检：读完能回答——这张图讲什么故事？几个泳道？起点终点是什么？哪些节点必须出现？答不上来就回去重读或向用户追问业务流程，不要凭空编造流程。
第二段：选题确认 + 设计定稿确认（两道硬门禁，缺一不可）
门禁一：选题方向确认
基于文档理解，向用户提出 2~4 个流程图选题方向，用 AskUserQuestion 让用户选择：
- 每个方向说明三件事：覆盖哪个评分点/业务闭环环节、预计泳道数与节点规模、图与图之间如何衔接（如流程图一末尾"转流程图二"）。
- 推荐组合策略：主流程 1 张 + 特殊机制 1~2 张（如"处置全流程"+"升级督办"+"复核销号"），比画三张同质流程图更能体现业务闭环深度。
- 用户未确认选题前，不产出任何 vsdx 或设计稿。
门禁二：每张图的设计定稿确认（选题通过后、制作前）
选题定下后，逐张向用户提交《设计定稿单》，内容必须完整覆盖：
- 泳道：角色名称、数量、左右顺序（按业务时序排列）
- 起止节点：起点事件、终点去向（含"转流程图X"的跨图衔接点）
- 节点清单：每个节点的文字（含挂接的规则编号）、类型（处理/判断/起止）、所在泳道与先后位置
- 分支结构：每个判断节点的"是/否"分支走向、回流环、并行、升级链、虚线路由
- 预计规模：泳道 × 行数、总节点数
呈现形式用 Markdown 表格或结构化清单，让用户逐项过目。用户可以在此阶段增删节点、改泳道、调分支——此时改设计的成本是几分钟，生成后再改就是返工。
两条硬规则：
- 两道门禁都确认（用户明确同意"可以制作"）之前，绝对不调用生成器产出 vsdx；
- 若设计定稿阶段改动较大（节点增删超过 1/3 或泳道变更），需再次确认修改后的定稿才动手。
第三段：制作与校验
3.1 用生成器定义流程图
复用本技能 scripts/vsdx_gen.py（把它 copy 到工作目录或直接 import），每张图 = 一个 Flow 定义：
import sys
sys.path.insert(0, r'<技能目录>\scripts')
from vsdx_gen import Flow, build_vsdx, render_svg, save_png, validate
f = Flow('XX流程', ['泳道A', '泳道B', '泳道C', '泳道D'], 总行数)
f.add('n1', 0, 0, '开始：XXX', 'term') # term=起止(蓝底白字圆角)
f.add('n2', 0, 1, '规则匹配（V01~V07）', 'proc') # proc=处理(浅蓝矩形)，文字可\n换行
f.add('n3', 0, 2, '命中？', 'dec') # dec=判断(黄菱形)
f.edge('n3', 'n4', '是') # 同列直连/跨泳道正交折线，自动路由
f.edge('n2', 'n1', '否·继续监测', 'loop_r') # 回流环：loop_r/loop_l
f.edge('n8', 'n13', '是·办结', 'corridor_r') # 绕右侧走廊连线
f.edge('n5', 'n1', '否·继续监测', 'loop_l', dashed=True) # dashed=虚线
build_vsdx(f, out + '/流程图X.vsdx')
svg = render_svg(f)
with open(out + '/流程图X.svg', 'w', encoding='utf-8') as fp: # SVG必落盘：是PNG的源和降级保底
fp.write(svg)
engine = save_png(f, svg, out + '/流程图X.png') # PNG必产（cairosvg优先/Chrome兜底，2x），失败返回None降级
print(validate(out + '/流程图X.vsdx'))
定义要点：
- lane 从 0 起（左→右），row 从 0 起（上→下）；节点文字每行 ≤10 汉字，长文字用 \n 拆行
- 判断节点（dec）的"是/否"标签必须写全，标签以"是"开头自动绿色、"否"开头自动红色
- 连线尽量 auto 路由；同列回流用 loop_r/loop_l，避免连线穿过菱形
- 节点文字挂接文档规则编号（V/R），保持"图—规则—文档"可互核
3.2 运行与三重校验
<managed venv python> 生成脚本.py
- 校验函数
validate()自动做：zipfile 完整性 + 全部 XML 合法性 + vsdx 包回读（形状数/页名） - vsdx 回读需要
vsdxpip 包，装在 managed venv（C:\Users\Administrator\.workbuddy\binaries\python\envs\default\Scripts\python.exe），缺失时pip install vsdx（阿里云镜像） - 任何校验失败都必须修复后重生成，不带病交付
3.3 交付（不做会话内在线预览，直接给产物）
- 不使用 show_widget / 在线预览——直接把产物文件交给用户
- present_files 交付：全部
.vsdx+ 全部.png（用户直接看/复制的就是 PNG；SVG 是渲染源和降级保底，一并落盘但不占交付首位） - 交付信息中注明 PNG 使用的引擎（cairosvg / chrome）；若 PNG 生成失败（engine=None），如实告知并交付 vsdx + svg
- 明确请用户在 Visio 或 WPS 中打开 vsdx 做最终打开验证——本机通常没有 Visio 主程序，解析校验通过≠Visio 打开显示正常，这一步必须交用户确认；PNG 已可代替 SVG 承担"无 Visio 环境快速核验图面"的作用，用户看 PNG 即可核验版式
- 用户反馈样式问题（字号/配色/间距/连线）时，改 Flow 定义重生成，单张几分钟内出新版
已知坑（务必遵守）
- vsdx pip 包的 API 是
VisioFile，不是Vsdx（from vsdx import VisioFile） - vsdx 最小 OPC 结构 9 个 parts：
[Content_Types].xml、_rels/.rels、docProps/core.xml、docProps/app.xml、visio/document.xml、visio/_rels/document.xml.rels、visio/pages/pages.xml、visio/pages/_rels/pages.xml.rels、visio/pages/page1.xml - Shape 用
Cell N=V+GeometrySection（RelMoveTo/RelLineTo）+Character/ParagraphSection 表达样式；连线用 2D polyline shape +EndArrow=4+NoFill=1 - SVG 预览坐标必须做页面 y 翻转（vsdx 原点在左下，SVG 在左上）：所有 y 都要换成
(f.h - y) * IN，文字还要按行数做纵向居中偏移——漏翻转会文字上下颠倒 - 先探测环境再选路线：本机若无 Visio 主程序（查
VISIO.EXE）且无 draw.io，就走本技能的纯 Python 路线；有 Visio COM 可考虑 COM 自动化作备选 - PNG 是默认产物：
save_png()自动选引擎——cairosvg 优先（未装则跳过），Chrome headless 兜底（Windows 标准路径探测，2x 分辨率）；SVG 临时文件须以file:///+ 正斜杠绝对路径传入 Chrome；生成后校验文件 >1000 字节判断成败，失败返回 None 自动降级交付 SVG（核心交付 vsdx 不受任何影响） - 节点行距 ROW_H=1.02in、泳道宽 LANE_W=2.35in 是实测可读的默认值；行数多时图会很高，属正常，SVG 预览可缩放
- 边标签防重叠：
route_edge已做 x 边界钳制；若两张标签撞位，微调节点 row 或改 loop 路由 - 标签压节点已内置防护（2026-09-14改版，用户指定）：不用白底衬垫块（vsdx标签 FillPattern=0 透明；SVG/PNG 标签最后绘制+白色文字描边
stroke="#FFF" stroke-width="3.2" paint-order="stroke"）——无色块、文字仍清晰；若两个标签完全撞位（同点），仍须改节点row或路由错开（如申诉支线用loop_r绕行） - 跨泳道长线避让：同列多节点时，跨行连线（auto bot→top）的水平段会穿中间行节点——改用 corridor_r 绕右侧走廊（垂直段x=lane_r+0.12in，注意与相邻泳道节点左缘留≥0.1in余量）；两条线汇入同一节点底部会重叠，改链式收口（A→B→终点）或删除直连改经中间节点
- 同行节点必须严格等高（2026-09-14实战修复）：pos()采用行槽居中对齐（cy=行槽中线，与节点高度无关）——若按高度顶对齐（cy再减h/2），菱形(0.82)与矩形(0.62)同行中心差0.10in，auto横向连线会插中间小台阶不直；同row跨泳道边拉成一条水平直线是默认效果，发现小台阶先查节点对齐方式
- 竖直边标签位置（2026-09-14实战修复）：渲染层对标签统一+0.12in上移（为横线"浮在线上方"设计），竖直边若沿用会被顶到源节点上（如压菱形底尖）——竖直边标签必须预扣0.12并放线右侧0.28in、两锚点中点高度（lbl=(ax+0.28, anchor_mid-0.12)），vsdx/SVG 同步生效；横线/折线标签保持线上方偏移不变
- dec 与下行节点净空（2026-09-14用户截图反馈修复）：dec 高度 0.95→0.82，保证与下一行节点净空 ≥0.28in——否则菱形到下行节点的连线拐点被压扁（末段仅4px），箭头贴脸、标签压箭头；dec 跨行出边自动改走侧顶点水平引出（dx≥0.5in 时：侧anchor→水平到目标x→下行进top），标签落水平段中点自然分开，不再压拐点
- 虚线末段悬空（同上反馈）：loop 走廊原基于泳道边界（末段仅7px），短段会被 dash 空隙相位吃掉，箭头与线断开。已修：走廊改为节点边缘外 0.16in（末段≥14px）+ SVG 侧 dasharray 6,4 并按线总长计算 stroke-dashoffset 使末端必落实段。⚠️ document.xml 全局 StyleSheet 的 FillForegnd #FFFFFF 是页面默认样式，勿误判为标签白底残留
交付物清单（每次任务）
<编号>_<流程名>.vsdx× N（比赛/交付格式，核心交付物）<编号>_<流程名>.png× N（默认必产——2x 分辨率产物图，用户直接查看/复制；引擎失败时降级为 svg 并告知）<编号>_<流程名>.svg× N（必落盘——PNG 的渲染源与降级保底，交付排序在 png 之后）- 生成脚本留档在工作目录（方便改样式重生成）
- 无内联预览——present_files 直接交产物文件 + 用户 Visio 打开验证提醒
