HiWork Visio 出图技能
把用户口述的流程变成一张可编辑的 Visio .vsdx。你负责把流程整理成 JSON spec，
调用 MCP 工具渲染，检查预览图，再把下载链接交给用户。渲染在远端服务完成（服务端
装有 Visio），本机不需要任何 Office 组件。
工具
| 工具 | 用途 |
|---|---|
visio_capabilities |
返回 spec 说明（节点类型、页面、主题、路由）和完整示例。第一次出图或对字段拿不准时先调用。 |
visio_create_diagram |
渲染一张图。入参是 spec 对象；返回 JSON 摘要（diagram_id、vsdx_download_url、preview_url）+ base64 PNG 预览。 |
visio_get_preview |
按 diagram_id 重新取回 PNG 预览。 |
visio_list_diagrams |
列出最近的图。新会话先看这里，可能已有现成的图可复用。 |
visio_health |
服务与 Visio 可用性检查；probe: true 会真的启动一次 Visio 验证全链路。 |
客户端里工具名可能带服务前缀（如 mcp__visio__visio_create_diagram），以实际列出的为准。
工作流程
- 理解流程：把用户描述整理成节点（步骤）和连线（流转）。跨角色流程用泳道：
每个角色一条lane，按时间先后从左到右排泳道；单角色简单流程省略swimlanes。 - 写 spec：按下文"spec 骨架"组 JSON。字段拿不准就先调
visio_capabilities，
不要猜字段名——schema 禁止未知字段，拼错会被直接拒绝。 - 渲染：调
visio_create_diagram。渲染是串行排队的（单张约 4-7 秒），
不要并发渲染多张。 - 看预览：返回结果里带 PNG，必须看图确认：泳道归属、节点顺序、连线路由、
驳回回路是否符合预期。发现问题就改 spec 重渲，不要把没检查过的下载链接直接给用户。 - 交付：把
vsdx_download_url（可编辑文件）和preview_url一起给用户，
并用一两句话说明图中画了什么。
spec 骨架
{
"name": "出差申请流程", // 输出文件名，≤80 字符
"title": "出差申请流程", // 画在图顶部的标题，可省略
"page": { "size": "A3", "orientation": "portrait", "margin": 0.5 },
"theme": "standard", // standard | blue | mono
"swimlanes": { // 不需要泳道就整个省略
"lanes": ["申请人", "部门主管", "财务"], // 泳道表头，左→右，1-10 条
"phases": ["申请", "审批"] // 左侧阶段列，可省略
},
"legend": true, // 图下方追加图例，默认 false
"nodes": [
{ "id": "start", "kind": "start", "text": "开始", "lane": 0 },
{ "id": "fill", "kind": "node", "text": "填写出差申请单", "lane": 0 },
{ "id": "ok", "kind": "decision", "text": "是否通过?", "lane": 1 }
],
"edges": [
{ "from": "start", "to": "fill" },
{ "from": "ok", "to": "fill", "label": "驳回", "style": "dashed", "route": "return" }
]
}
节点类型（kind）
| kind | 形状 | 用在 |
|---|---|---|
start / end |
圆角胶囊 | 开始 / 结束 |
key |
圆角矩形（强调填充） | 关键流程节点 |
node |
圆角矩形（默认） | 一般流程节点 |
manual |
直角矩形 | 具体业务或人工工作 |
decision |
菱形 | 决策判断，每个出口一条边并用 label 区分（"通过"/"驳回"） |
form |
文档形（波浪底边） | 流程中的表格/单据 |
related |
双边线矩形 | 关联流程（另一个流程） |
布局与连线要点
- 节点按流程顺序声明，默认自上而下排列；
lane选泳道列，row/phase可微调纵向位置。 - 连线用
from/to引用节点 id。route可选： auto（默认）：避障正交路由，自动绕开无关节点，一般不用改；return：驳回/反馈回路，自动走左侧独立通道，多条互不重叠；straight：单段直连，可能穿过其他节点，只在用户明确要求时用；vertical/side：偏好上下端口 / 侧面端口。- 页面放不下会自动向下扩；节点框按文字自动换行、自动定大小，一般不用手调宽高。
限制与常见报错
- 节点 ≤ 200，连线 ≤ 400；不支持自环（
from==to）；节点 id 必须唯一。 - 用了
lane就必须定义swimlanes，且 lane 序号小于泳道数；phase同理。 - 字段名拼错、多写未知字段、边引用不存在的 id，都会返回带具体字段的校验错误——按提示改。
- 渲染超时通常是 Visio 弹了模态对话框卡住：稍后重试或用
visio_health检查。
详细参考
字段级完整说明（每个字段的类型、取值范围、默认值）、主题配色、页面尺寸、排版、
路由行为、工具返回格式和服务接入方式见
references/spec-schema.md。对任何字段没把握时先读它再写 spec。
