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

SKILL.md

---
name: investoday-drawio-skill
title: "今日投资实时 Draw.io 架构图技能"
version: 1.0.6
description: "基于 next-ai-draw-io MCP 实时生成、编辑、核对和导出 draw.io 图。Use when: 用户要画架构图、系统交互图、部署图、流程图、网络拓扑图，要求强制使用 next-ai-drawio MCP 实时预览，并在每次绘图前先检查该服务有效、优先复用当前已打开图的有效预览，再基于需求/参考风格/约束生成简洁总览图，随后按反馈迭代或导出 .drawio/PNG/SVG。典型话术：实时渲染 draw.io、用 MCP 画图、边画边改、按参考图生成 draw.io、先出总览图、导出可编辑图。Do not use when: 只需要 Mermaid 文本、只要静态图片、只读分析图中文字、不允许启动 next-ai-drawio MCP/浏览器预览，或要求发布/外发文件到外部平台。"
tags:
  - investoday
  - drawio
  - mcp
  - architecture
  - realtime-preview
metadata:
  clawdbot:
    category: productivity
    quality_pipeline:
      type: role_pipeline
      fallback: fail_if_agent_unavailable
      subagent_invocation_format: "Spawn {codex_name} to {task}"
      agent_template_dir: agents
      slash_namespace_reserved_for_skills: true
      pipelines:
        new_diagram:
          - drawio-commander
          - drawio-mcp-engineer
          - drawio-reviewer
          - drawio-acceptance
        edit_diagram:
          - drawio-mcp-engineer
          - drawio-reviewer
          - drawio-acceptance
        export_diagram:
          - drawio-acceptance
        review_diagram:
          - drawio-reviewer
          - drawio-acceptance
        learn_style:
          - drawio-commander
          - drawio-reviewer
        no_agent_handoff: []
        no_agent_clarify: []
      route_agent_pipelines:
        new_diagram:
          pipeline: new_diagram
          required: true
        edit_diagram:
          pipeline: edit_diagram
          required: true
        review_diagram:
          pipeline: review_diagram
          required: true
          readonly: true
        export_diagram:
          pipeline: export_diagram
          required: true
        learn_style:
          pipeline: learn_style
          required: true
        handoff:
          pipeline: no_agent_handoff
          required: false
          handoff: true
        clarify:
          pipeline: no_agent_clarify
          required: false
          clarify: true
      roles:
        - id: drawio-commander
          role: "Draw.io 方案指挥官"
          agent: "@agent-drawio-commander"
          codex_name: drawio_commander
          agent_template: agents/drawio_commander.toml
          required: false
        - id: web-researcher
          role: "联网研究员"
          agent: "@agent-web-researcher"
          codex_name: web_researcher
          agent_template: agents/web_researcher.toml
          required: false
        - id: drawio-mcp-engineer
          role: "Draw.io MCP 工程师"
          agent: "@agent-drawio-mcp-engineer"
          codex_name: drawio_mcp_engineer
          agent_template: agents/drawio_mcp_engineer.toml
          required: false
        - id: drawio-reviewer
          role: "Draw.io 图表审核师"
          agent: "@agent-drawio-reviewer"
          codex_name: drawio_reviewer
          agent_template: agents/drawio_reviewer.toml
          required: false
        - id: drawio-acceptance
          role: "Draw.io 交付验收官"
          agent: "@agent-drawio-acceptance"
          codex_name: drawio_acceptance
          agent_template: agents/drawio_acceptance.toml
          required: false
requirements:
  python: ">=3.11"
  node: ">=20"
  packages:
    - name: "@next-ai-drawio/mcp-server"
      manager: npm
    - name: PyYAML
      manager: pip
  network_access: true
---

# 今日投资实时 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 个阻塞问题。
- 缺少参考风格时，可使用默认商务架构图风格继续。
- 缺少导出需求时，不默认导出源文件或图片；用户明确需要导出但缺少路径时，默认使用当前工作目录。
- 涉及覆盖已有文件、外部发送、生产发布或敏感数据外传时，必须先确认。

### 示例输入

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

### 反例输入

```text
画一下。
```

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

## 意图路由

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

| route id | 用户意图 | 用户信号 | 必要输入 | 进入工作流 | 输出 |
|---|---|---|---|---|---|
| `new_diagram` | 新建实时 draw.io 图 | 生成、画一张、从需求出图、按参考风格生成 | 图类型、核心内容、输出目标、抽象层级或用途 | 实时生成闭环 | 最终绘制框架、浏览器预览、图源和导出文件 |
| `edit_diagram` | 修改当前实时图 | 调整、移动、删掉、换颜色、改文案、基于当前图继续 | 当前 MCP 会话或已有图、修改要求 | 编辑闭环 | 更新后的实时图和变更说明 |
| `review_diagram` | 只读核对图 | 检查、核对、有没有问题、线条/边界/文案是否合理 | 当前图 XML、截图或参考图 | 质量核对流程 | P1/P2/P3 问题清单 |
| `export_diagram` | 导出交付 | 导出、保存、生成 PNG/SVG/.drawio | 当前图、导出格式、目标路径 | 导出验收流程 | 文件路径和验证结果 |
| `learn_style` | 从参考风格抽取图形约束 | 按这张图风格、参考这个架构图、像示例图 | 参考图或 `.drawio` 文件 | 风格抽取流程 | 风格约束摘要和可复用的简图原则 |
| `clarify` | 输入不足 | 缺图类型、缺对象、缺导出要求 | 缺失项 | 追问 1-3 个阻塞问题 | 待补充清单 |
| `handoff` | 超出当前 skill | 只要 Mermaid、只做图片生成、发布到外部系统 | 目标任务 | 转交对应 skill 或工具 | 路由建议 |

## 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 行为、或涉及最新官方最佳实践时插入流水线。

| route id | 自动触发条件 | 自动 Agent 流水线 | 不触发或失败处理 |
|---|---|---|---|
| `new_diagram` | 从需求生成完整实时图，或包含参考风格、导出要求 | 必须 `Spawn drawio_commander to define the simplified drawing frame and abstraction boundary`，再 `Spawn drawio_mcp_engineer to build the realtime diagram from the approved frame`，再 `Spawn drawio_reviewer to review structure, complexity, and boundary clarity`，最后 `Spawn drawio_acceptance to verify delivery readiness`；需要联网时在 commander 后插入 `Spawn web_researcher to verify current MCP or draw.io facts from primary sources` | agent 不可用、缺失或 Spawn 失败时，停止完成路径，报告阻塞；不得由当前模型补做后宣称多代理已完成 |
| `edit_diagram` | 需要修改当前图或用户可能手动改过图 | 必须 `Spawn drawio_mcp_engineer to verify next-ai-drawio MCP health, read back the current diagram, and apply scoped edits`，再 `Spawn drawio_reviewer to review the updated diagram`，最后 `Spawn drawio_acceptance to verify export or delivery readiness when needed` | 仅补文案也不能跳过真实 Spawn；缺当前图时先走 `clarify` |
| `review_diagram` | 用户要求检查、核对、发布前图审或质量判断 | 必须 `Spawn drawio_reviewer to perform a read-only review of the current diagram`，再 `Spawn drawio_acceptance to verify delivery and residual risk statements` | 缺当前图或截图时先走 `clarify`；agent 不可用时停止完成路径 |
| `export_diagram` | 用户要求导出或保存交付件 | 必须 `Spawn drawio_acceptance to verify next-ai-drawio MCP health, approved diagram state, and export readiness` | 若 MCP 不可用，输出失败原因和替代导出建议；不得跳过验收直接报交付完成 |
| `learn_style` | 用户给出参考图或 `.drawio` 要求复用风格 | 必须 `Spawn drawio_commander to extract reusable style constraints and simplification rules`，再 `Spawn drawio_reviewer to check whether the derived style remains clear and concise` | 若缺少可读参考文件，先 `clarify`；agent 不可用时停止完成路径 |

自动 Spawn 时使用：

```text
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，避免覆盖用户手工修改。
- 是否完成图结构、布局、边界、文案和连线核对。
- 是否完成视觉核验，确认没有超出边界、模块重叠、线条遮挡、文字截断或导出背景异常。
- 导出了哪些文件，文件是否存在。
- 未验证风险，例如未做人工视觉确认、浏览器未打开、导出格式未测试。