今日投资实时 Draw.io 架构图技能

概览

本技能用于通过 next-ai-draw-io MCP 在浏览器中实时渲染 draw.io 图，并完成从需求分析、信息抽象、模板选择、图标/图形增强、图形生成、人工反馈、视觉核验到导出交付的闭环。

它借鉴传统 drawio-skill 的“规划 -> XML -> 自检 -> 迭代 -> 导出”逻辑，但执行面改为 MCP 实时会话：打开预览前先判断当前目标图是否已在有效 session 中打开，命中时优先复用当前预览，只有未打开、会话失效或用户明确要求重开时才调用 start_session；随后用 create_new_diagram 创建新图，修改现有图前必须先 get_diagram，再用 edit_diagram 做 ID 级增删改，最后用 export_diagram 输出文件。除非用户明确要求细图、全量链路图或实现级展开，本技能默认先交付简洁总览图，而不是把需求原文逐条照搬成节点和连线。

前置依赖

• python: >=3.11
• node: >=20
• package: @next-ai-drawio/mcp-server (npm)
• package: PyYAML (pip)

输入要求

可接受输入

• 需求：图类型、业务背景、系统边界、模块列表、交互链路、部署范围、目标读者、用途、期望抽象层级。
• 参考风格：截图、已有 draw.io 文件、示例图、配色要求、布局偏好、品牌限制。
• 交付要求：实时预览确认、是否允许改当前图、是否需要导出 .drawio/PNG/SVG、导出路径、是否需要联网查最佳实践、是否先做总览再细化。

最小输入

• 图类型或目标：例如架构图、系统交互图、部署架构图、流程图。
• 核心内容：至少说明主要参与方、模块或流程。
• 输出目标：实时预览确认，以及是否需要可编辑 draw.io 源文件、图片导出或只做图结构建议。
• 抽象偏好：至少能判断这是总览图、汇报图、售前图，还是细节实现图；未说明时按总览图处理。

推荐输入

• 参考图或参考 .drawio 文件。
• 分区规则，例如今日投资侧、客户侧、外网区、内网区、安全边界。
• 不要出现的细节，例如不要具体组件、不要写数据库名、不要堆技术栈。
• 必须保留和允许折叠的内容，例如“保留能力边界，折叠内部微服务”。
• 验收标准，例如“适合售前方案”“能体现本地部署”“线条不要交叉”“保持简洁总览”。

可选输入

• 画布方向、颜色风格、按需导出的格式、文件名、是否保留版本历史。
• 是否要求联网搜索官方文档或最佳实践。
• 是否需要多代理复核。

默认假设

• 未指定语言时，图中文字和交付说明默认使用中文。
• 未指定图形风格时，默认使用商务架构图风格：浅色分区、圆角模块、正交连线。
• 未指定模板时，根据图类型从 references/template-catalog.md 选择默认模板。
• 未指定图标来源时，优先使用 draw.io 原生 shape library、本 skill 内置模板图形和 assets/icons/icon-manifest.json 中的本地白名单 SVG；只有在用户允许或确有必要时才引入外部 SVG 图标。
• 未指定抽象层级时，默认先交付简洁总览图：2-4 个分区、5-8 个核心节点、8-12 条以内主链路；同侧或同类内部组件优先合并成业务块或能力块。
• 实时预览必须使用 next-ai-drawio MCP；不以静态截图、手工脑补或其他绘图工具替代。
• 每次进入新建、修改、复核导出前，都必须先做 next-ai-drawio MCP 服务有效性检查；检查通过后才继续绘图或导出。
• 打开预览前先判断当前目标图是否已在有效 session 中打开；已打开则直接复用，不重复开启多个预览或重复打开同一张图。
• 实时预览是新建图表的默认交付要求，绘制前必须让用户确认；.drawio 源文件、PNG、SVG 等导出物按用户需求生成，不默认强制导出。
• 未明确允许外发时，不把本地图源、截图或业务资料上传到无关外部平台。

输入校验

• 如果用户给出参考文件路径，先确认文件存在。
• 如果用户给出的是长列表、会议纪要、PRD 段落或逐项组件清单，先做需求抽象，输出“最终绘制框架”；不得把原文逐条抄成节点和连线。
• 如果总览图的候选节点超过 8 个、主链路超过 12 条，必须先合并同类模块，或拆成“总览图 + 细节图”，不能默认塞进一张图。
• 每次进入实时预览、编辑或导出前，先检查 next-ai-drawio MCP 服务是否有效：先判断当前目标图是否已在有效 session 中打开，命中则复用；只有未打开、session 失效或用户明确要求新会话时才建立新 session，并取得可用预览 URL；失败时停止，不继续后续步骤。
• 新建图表前，先确认实时预览交付要求；如果用户需要导出，再确认导出格式和路径。
• 如果用户要求修改已有图，先读取当前 diagram XML，确认 cell id 和结构。
• 如果用户要求导出，确认目标路径、格式和是否会覆盖已有文件。
• 如果用户要求联网研究，优先使用官方文档、项目 README 或一手来源。

缺失输入处理

• 缺少图类型或核心内容时，先追问。
• 缺少抽象层级、读者或用途时，默认先输出简洁总览框架，并明确哪些细节会被折叠；如果图的用途决定边界取舍且无法安全推断，先追问 1-3 个阻塞问题。
• 缺少参考风格时，可使用默认商务架构图风格继续。
• 缺少导出需求时，不默认导出源文件或图片；用户明确需要导出但缺少路径时，默认使用当前工作目录。
• 涉及覆盖已有文件、外部发送、生产发布或敏感数据外传时，必须先确认。

示例输入

用 investoday-drawio-skill 画一张实时 draw.io 系统交互图。输入是需求、参考风格和要求：
需求：平台侧向客户侧输出数据能力和智能分析能力。
参考风格：类似网络拓扑图，左右分区，中间是安全边界。
要求：先给简洁总览图，不展开具体组件，实时预览，最后导出 .drawio 和 PNG。

反例输入

画一下。

原因：缺少图类型、核心内容和输出目标，应先追问要画什么图、包含哪些对象、是否需要实时预览或导出。

意图路由

意图路由只在本技能已经触发后使用；初始触发仍由 frontmatter description 决定。

Agent 自动触发策略

本技能命中 new_diagram、edit_diagram、review_diagram、export_diagram、learn_style 后，必须先按 metadata.clawdbot.quality_pipeline.route_agent_pipelines 真实 Spawn 对应 agent。只有 clarify 和 handoff 可不启用 agent。用户明确说“不要使用 agent / 只要当前模型处理”时，不得继续宣称已完成 agent-required route，只能输出受限草稿、待确认框架或路由建议。web_researcher 只在用户要求联网、需要核对最新 MCP/draw.io 行为、或涉及最新官方最佳实践时插入流水线。

自动 Spawn 时使用：

Spawn {codex_name} to {task}

如果当前运行时不支持 subagent、对应 agent 不存在或 Spawn 失败，必须把该 route 视为阻塞，明确报告未启用原因，并停止 agent-required route 的完成路径。不得用当前主会话模拟缺失 Agent 后宣称完成。

需求抽象与简图规则

• 先把用户输入拆成：图类型、目标读者、用途、边界、核心节点、主链路、必须保留的细节、允许折叠的细节。
• 不得把 PRD 段落、会议纪要、系统清单或用户原话逐条照搬成节点、泳道和连线；必须先合并同类项，再决定哪些内容进入图中。
• 未明确要求细图、实现图或全量链路图时，默认交付简洁总览图：2-4 个分区、5-8 个核心节点、8-12 条以内主链路。
• 当候选节点、边或标签明显过多时，先合并成业务块、能力块或阶段块；仍然超载时，拆成“总览图 + 细节图”，不要把所有信息塞到一张汇总图。
• 汇总图优先表达边界、角色、能力和主路径；实现细节、内部微服务、低优先级支线和重复链路默认折叠，除非用户明确要求展开。
• 新建图前必须先给出“最终绘制框架”，其中要写明保留细节、折叠细节、排除细节和复杂度控制方式。
• 需求抽象必须先读取 references/diagram-simplification-planning.md，按用途、读者、主故事线、责任边界、布局骨架和复杂度预算规划；不得直接从某张参考图或某次反馈中复制固定结构。

MCP 服务有效性检查

• 强制预览时，只能使用 next-ai-drawio MCP；不得改用其他浏览器白板、静态截图生成器或离线 XML 脑补来冒充实时预览。
• 每次进入 new_diagram、edit_diagram、review_diagram、export_diagram 前，都必须先检查 next-ai-drawio MCP 服务是否有效。
• 服务检查的首要动作不是盲目 start_session，而是先判断当前目标图是否已经在有效 session 中打开；命中则直接复用当前预览，不重复打开同一张图或并行开多份预览。
• 有效性的最小判断标准：能够成功连接到 next-ai-drawio MCP，并成功建立或复用与当前目标图匹配的 session，拿到可用预览 URL；涉及已有图时，还要能成功 get_diagram 读取当前状态。
• 只有在当前目标图未打开、现有 session 已失效、当前打开的不是目标图，或用户明确要求重开预览/新会话时，才允许调用 start_session。
• 服务检查失败时，必须停止后续绘图、编辑、导出或交付说明，明确报告失败环节、失败症状和下一步排查建议。
• 不得把“命令能启动”视为服务有效；必须以 MCP 可实际返回 session/图状态为准。

核心工作流

1. 识别 route，补齐需求、参考风格和交付要求；命中 agent-required route 后先按“Agent 自动触发策略”真实 Spawn 对应 agent。
2. 先执行“MCP 服务有效性检查”；先判断当前目标图是否已在有效 session 中打开，命中则直接复用，未命中时才建立新 session；确认 next-ai-drawio MCP 可稳定返回可用预览后，才进入实际绘图、编辑、复核或导出。
3. 读取 references/diagram-simplification-planning.md 和“需求抽象与简图规则”，把原始输入整理成最终绘制框架：图类型、读者/用途、主故事线、责任边界、布局骨架、分区、核心节点、主链路、保留细节、折叠细节、排除细节、复杂度预算、视觉风险和交付要求。
4. 新建图表前先输出最终绘制框架并取得用户确认；实时预览是必确认的默认交付项，.drawio 源文件、PNG、SVG 等导出物按用户需求确认后生成。用户明确要求“直接画”或需求已经非常明确时可先生成草图，但仍必须说明采用的框架和被折叠的细节。
5. 读取 references/template-catalog.md，根据图类型选择模板族和样式骨架；按 references/diagram-simplification-planning.md 控制分区数量、节点数量、连线数量和折叠边界；若总览图超出模板容量，优先合并节点，其次拆图，而不是强塞细节。
6. 读取 references/icon-sources.md 和 assets/icons/icon-manifest.json，按图类型选择图标、异形节点、箭头、容器和标识元素；不得只堆线和矩形框，也不得为追求装饰而额外引入无关节点。
7. 需要最新工具行为或官方最佳实践时，Spawn web_researcher，并只采用官方文档、项目 README 或一手来源。
8. 读取 references/mcp-workflow.md，按 MCP 实时闭环执行。
9. 生成新图时，先确认当前目标图是否已在有效 session 中打开；只有未打开、session 失效或用户明确要求重开时才重建 session，再用 create_new_diagram 写入完整 mxGraphModel。
10. 修改已有图时，必须先 get_diagram 获取最新 XML，再用 edit_diagram 做 ID 级操作；如果新增需求会把总览图推向复杂失控，先回到最终绘制框架决定是合并还是拆图。
11. 读取 references/xml-authoring-rules.md，检查 root、cell id、geometry、edge、label、容器和连线规则。
12. 读取 references/quality-checklist.md，做内容、抽象层级、复杂度、布局、边界、文案和可交付性核对。
13. 读取 references/visual-qa.md，导出 PNG 或截图做视觉核验；发现超界、重叠、遮挡、裁切、黑底、文字截断或线条堆叠时必须修正并复检。
14. 用户要求导出并确认格式/路径后，读取 references/export-troubleshooting.md，再次确认服务有效，再用 export_diagram 导出 .drawio、PNG 或 SVG。
15. 最终回复说明实时预览地址、MCP 服务检查结果、图是总览还是细图、折叠了哪些细节、改动内容、按需导出的文件、验证结果和未验证风险。

参考路由

• MCP 实时生成、编辑、导出流程：读取 references/mcp-workflow.md。
• 需求抽象、精简程度、规划方式和总览图复杂度控制：读取 references/diagram-simplification-planning.md。
• 模板族、风格选择和默认布局：读取 references/template-catalog.md。
• 图标、异形节点、内置图形和外部 SVG 来源：读取 references/icon-sources.md；本地 SVG 白名单读取 assets/icons/icon-manifest.json。
• mxGraphModel XML 编写与编辑规则：读取 references/xml-authoring-rules.md。
• 图表质量、风格、内容核对：读取 references/quality-checklist.md。
• 视觉核验、截图/PNG 检查和美观修复：读取 references/visual-qa.md。
• 导出、故障处理、隐私与本地部署：读取 references/export-troubleshooting.md。
• 官方来源和最佳实践摘要：读取 references/research-sources.md。

输出格式

• 新建或修改任务：说明实时预览地址、MCP 服务检查结果、图是总览还是细图、主要结构、被折叠的细节、已执行的 MCP 操作、验证结果和导出路径。
• 只读评审任务：按 P1/P2/P3 输出问题，包含图中位置、原因和建议。
• 导出任务：列出导出格式、文件路径、是否已核对文件存在。
• 失败任务：说明失败在哪一步、可恢复方案和需要用户补充的信息。

失败处理

• MCP 工具不可用：提示用户检查 MCP server 配置，确认 npx @next-ai-drawio/mcp-server@latest 可启动。
• next-ai-drawio MCP 服务检查失败：停止流程，报告失败步骤、报错或无响应症状，并建议检查 MCP 配置、session 建立、端口占用和浏览器预览页状态。
• 没有可复用的目标图 session：先确认当前图是否已打开；仅在未打开、session 失效或用户明确要求新会话时调用 start_session。
• 修改前未读取当前图：停止编辑，先 get_diagram。
• 需求明显过载但用户未要求细图：先给出简洁总览框架，并说明折叠或拆图建议；不要直接把所有条目塞进一张图。
• 用户要求把所有细节挤进单张汇总图：明确提示会降低可读性，优先建议拆成总览图和细节图。
• XML 无法渲染：检查 root、cell id、geometry、edge source/target 和 XML 转义。
• 导出失败：重试一次；仍失败时保留当前图状态，说明失败原因并建议导出替代格式。
• 参考风格无法读取：使用默认商务架构图风格，并在最终回复说明未能复用参考风格。

交付要求

最终交付必须说明：

• 是否使用实时 MCP 会话，以及预览地址。
• 是否先完成 next-ai-drawio MCP 服务有效性检查，检查结果如何。
• 是否先判断并复用了当前已打开图，避免重复开启多个预览。
• 是否基于需求、参考风格和要求完成规划。
• 是否先完成需求抽象，而不是把原始需求逐条照搬成节点和连线。
• 当前交付是简洁总览图还是细节图；如果折叠了细节，折叠了哪些内容。
• 是否合理使用图标、异形节点、阶段箭头或业务标识，而不是只用线和矩形框堆叠。
• 是否控制了汇总图复杂度；若超出简图阈值，是否已合并模块或拆图。
• 是否执行 get_diagram readback，避免覆盖用户手工修改。
• 是否完成图结构、布局、边界、文案和连线核对。
• 是否完成视觉核验，确认没有超出边界、模块重叠、线条遮挡、文字截断或导出背景异常。
• 导出了哪些文件，文件是否存在。
• 未验证风险，例如未做人工视觉确认、浏览器未打开、导出格式未测试。