用途
design-doc-mermaid（Mermaid Architect）是一个分层式的 Mermaid 图表与文档系统，用于在用户请求时从文字描述或源代码生成 Mermaid 图表，并辅助生成设计文档。其描述为：Create Mermaid diagrams (activity, deployment, sequence, architecture) from text descriptions or source code.
主要能力
- 图表类型覆盖：活动图（activity）、部署图（deployment）、时序图（sequence）、架构图（architecture）。
- 代码转图（code-to-diagram）：可从代码库中分析并提取图表，覆盖 Spring Boot、FastAPI、React、Python ETL、Node/Express、Java Web App 等示例。
- 设计文档模板：提供架构设计、API 设计、功能设计、数据库设计、系统设计模板（存放于 assets/）。
- Unicode 语义符号指南：用于在图表中加入图标符号（如基础设施、计算、数据、消息、安全、监控类）。
- Python 脚本工具：extract_mermaid.py（提取、校验、替换为图片）、mermaid_to_image.py（.mmd 转 PNG/SVG、批量转换、自定义主题）、resilient_diagram.py（保存 .mmd、生成图片、校验、错误恢复的完整流程）。
使用方式
技能按“意图分析 → 判断图表/文档类型 → 加载对应指南 → 依据模板生成 → 交付并附带验证与导出选项”的决策树运行。用户提出请求后，技能会判断意图并加载以下相应资源：
- 工作流、流程、业务逻辑：references/guides/diagrams/activity-diagrams.md
- 基础设施、部署、云：references/guides/diagrams/deployment-diagrams.md
- 系统架构、组件：references/guides/diagrams/architecture-diagrams.md
- API 流程、交互：references/guides/diagrams/sequence-diagrams.md
- 代码转图：references/guides/code-to-diagram/ 与 examples/
- 设计文档：assets/*-design-template.md
- Unicode 符号：references/guides/unicode-symbols/guide.md
- 提取、校验、转换：scripts/extract_mermaid.py、scripts/mermaid_to_image.py
生成后可选择是否校验（运行 mmdc validation），脚本类请求则进入执行流程。
推荐做法是“稳健工作流”（Resilient Workflow）：识别类型 → 保存 .mmd 与图片 → 校验 → 通过后加入 Markdown；若不通过则进入错误恢复。关键原则是：在图表通过校验前，绝不将其加入 Markdown。
使用脚本示例（保留原文命令）：
Generate with full error recovery
python scripts/resilient_diagram.py
--code "flowchart TD; A-->B"
--markdown-file design_doc
--diagram-num 1
--title "process_flow"
--format png
--json
文件命名约定：
./diagrams/<markdown_file><num><type><title>.mmd ./diagrams/<markdown_file><num><type><title>.png
示例：./diagrams/api_design_01_sequence_auth_flow.png
提取与转换脚本用法（保留原文命令）：
List all diagrams
python scripts/extract_mermaid.py document.md --list-only
Extract to separate files
python scripts/extract_mermaid.py document.md --output-dir diagrams/
Validate all diagrams
python scripts/extract_mermaid.py document.md --validate
Replace with image references (for Confluence upload)
python scripts/extract_mermaid.py document.md --replace-with-images
--image-format png --output-markdown output.md
Single conversion
python scripts/mermaid_to_image.py diagram.mmd output.png
With custom settings
python scripts/mermaid_to_image.py diagram.mmd output.svg
--theme dark --background white --width 1200
Batch convert directory
python scripts/mermaid_to_image.py diagrams/ output/ --format png --recursive
From stdin
echo "graph TD; A-->B" | python scripts/mermaid_to_image.py - output.png
适用场景
- 根据文字描述生成流程图/工作流/业务逻辑图（如“展示结账流程”“记录 ETL 流水线”“创建审批工作流”）。
- 文档化云架构与部署（如“展示 AWS 架构”“记录 GCP 部署”“创建 K8s 图”）。
- 记录系统组件与微服务架构。
- 记录 API 交互、服务通信、请求/响应流程（如“展示 API 调用时序”“记录认证流程”）。
- 从既有代码库提取图表并按框架组织。
- 生成各类设计文档。
- 从 Markdown 提取、校验 Mermaid 图表，或将其批量转换为图片。
限制
- 校验失败时的错误恢复优先级为：先查 references/guides/troubleshooting.md（记录 28 个错误）；再用 perplexity_ask MCP、brave_web_search MCP、gemini skill；最后用 WebSearch 工具兜底。
- 当脚本不可用时，需手动：识别图表类型、加载对应参考指南、保存为约定命名、使用
mmdc -i file.mmd -o file.png -b transparent校验，出错时查 troubleshooting 指南，仍找不到则按上述检索优先级处理，最后以形式加入引用。 - 高对比度样式要求：所有图表必须使用高对比度配色，浅色背景用深色文字、深色背景用浅色文字，每个 classDef 都必须指定 color: 属性。
- 关于该技能的收费、价格、平台支持、效果数据等，资料中暂未提供。