美人鱼架构师 - 全面图表与文档技能
版本 2.0 - 具有智能编排的层次化架构
一项强大的克劳德代码技能，使用按需加载指南、代码到图表生成和 Python 实用程序来创建美人鱼图表和设计文档。
安装
通过 Skilz 市场一键安装
从 Skilz 市场 立即安装此技能：
skilz install SpillwaveSolutions_design-doc-mermaid/design-doc-mermaid
手动安装
直接克隆到您的克劳德代码技能目录中：
# 导航到您的技能目录
cd ~/.claude/skills
# 克隆仓库
git clone https://github.com/SpillwaveSolutions/design-doc-mermaid.git
验证安装
安装后，验证技能是否可用：
# 列出已安装的技能
ls ~/.claude/skills/design-doc-mermaid
# 或询问克劳德代码
# "列出我安装的技能"
此技能的功能
智能图表生成：
- 活动图（工作流、流程、业务逻辑）
- 部署图（云基础设施、K8s、无服务器）
- 架构图（系统组件、微服务）
- 序列图（API 流、服务交互）
- 带有嵌入式图表的完整设计文档
代码到图表转换：
- 从 Spring Boot 应用中提取架构
- 从配置文件中生成部署图
- 从方法调用创建序列图
- 记录 ETL 管道和数据流
图表管理：
- 从 Markdown 文件中提取美人鱼图表
- 使用 mermaid-cli 验证图表语法
- 将图表转换为 PNG/SVG 图像
- 批量处理整个目录
快速开始
创建活动图
用户："创建一个包含电子邮件验证的用户注册活动图"
此技能将：
- 加载
references/guides/diagrams/activity-diagrams.md - 使用注册模式模板
- 添加 Unicode 符号（🔐 表示安全，📧 表示电子邮件，✅ 表示成功）
- 应用高对比度样式
- 输出完整的美人鱼图表
从代码生成
用户："这是我的 Spring Boot application.yml - 生成一个部署图"
此技能将：
- 分析配置（数据源、缓存、安全）
- 加载
references/guides/diagrams/deployment-diagrams.md - 加载
examples/spring-boot/README.md - 将配置映射到云资源
- 生成带有资源规格的部署图
创建设计文档
用户："为联系人 API 创建一个 API 设计文档"
此技能将：
- 加载
assets/api-design-template.md - 加载相关的图表指南（序列图、ER图、架构图）
- 生成带有嵌入式图表的完整文档
- 保存到
docs/design/api-contacts-v1-2025-01-13.md
结构
层次化组织
mermaid-architect/
├── SKILL.md # 主编排器，包含决策树
├── README.md # 此文件
├── CLAUDE.md # 克劳德代码指令
│
├── references/ # 参考资料
│ ├── mermaid-diagram-guide.md # 旧的通用指南
│ └── guides/ # 专用指南（按需加载）
│ ├── diagrams/
│ │ ├── activity-diagrams.md # ✅ 完成
│ │ ├── deployment-diagrams.md # ✅ 完成
│ │ ├── architecture-diagrams.md # ✅ 完成
│ │ └── sequence-diagrams.md # ✅ 完成
│ ├── code-to-diagram/
│ │ └── README.md # ✅ 完成（主指南）
│ ├── unicode-symbols/
│ │ └── guide.md # ✅ 完成（100+ 符号）
│ └── troubleshooting.md # ✅ 完成（28个常见错误）
│
├── scripts/ # Python 实用程序
│ ├── extract_mermaid.py # ✅ 提取和验证图表
│ └── mermaid_to_image.py # ✅ 转换为 PNG/SVG
│
├── examples/ # 特定语言的模式
│ ├── spring-boot/ # ✅ 完成
│ ├── fastapi/ # ✅ 完成
│ ├── react/ # ✅ 完成
│ ├── python-etl/ # ✅ 完成
│ ├── node-webapp/ # ✅ 完成
│ └── java-webapp/ # ✅ 完成
│
└── assets/ # 设计文档模板
├── architecture-design-template.md
├── api-design-template.md
├── feature-design-template.md
├── database-design-template.md
└── system-design-template.md
主要特性
1. Unicode 语义符号
每个图表都使用有意义的 Unicode 符号：
graph TB
User[👤 客户端] --> Gateway[🌐 API 网关]
Gateway --> Auth[🔐 认证服务]
Gateway --> API[⚙️ API 服务]
API --> DB[(💾 数据库)]
API --> Cache[(⚡ Redis)]
API --> Queue[📬 消息队列]
Queue --> Worker[⚙️ 后台工作器]
符号分类：
- 基础设施：☁️ 🌐 🔌 📡 🗄️
- 计算：⚙️ ⚡ 🔄 🚀 💨
- 数据：💾 📦 📊 📈 🗃️
- 消息传递：📨 📬 📤 📥 🐰
- 安全：🔐 🔑 🛡️ 🚪 👤
- 监控：📝 📊 🚨 ⚠️ ✅ ❌
2. 高对比度样式
所有图表都使用无障碍的高对比度颜色 - 详情见 SKILL.md。
3. Python 实用程序
提取图表
# 列出文件中的所有图表
python scripts/extract_mermaid.py document.md --list-only
# 提取为单独的 .mmd 文件
python scripts/extract_mermaid.py document.md --output-dir diagrams/
# 验证所有图表
python scripts/extract_mermaid.py document.md --validate
# 用图像引用替换图表（适用于 Confluence）
python scripts/extract_mermaid.py document.md --replace-with-images \
--image-format png --output-markdown output.md
转换为图像
# 单个文件
python scripts/mermaid_to_image.py diagram.mmd output.png
# 自定义主题和尺寸
python scripts/mermaid_to_image.py diagram.mmd output.svg \
--theme dark --background white --width 1200
# 批量转换目录
python scripts/mermaid_to_image.py diagrams/ output/ \
--format png --recursive
# 从标准输入
echo "graph TD; A-->B" | python scripts/mermaid_to_image.py - output.png
要求
图表生成
- 克劳德代码技能系统（自动）
- 指南和模板（包含在此技能中）
验证与图像转换
# 全局安装 mermaid-cli
npm install -g @mermaid-js/mermaid-cli
# 验证安装
mmdc --version
Python 脚本
- Python 3.7+
- 无需额外包（仅使用标准库）
学习路径
初次接触美人鱼图表？
- 从活动图开始 - 阅读
references/guides/diagrams/activity-diagrams.md - 学习 Unicode 符号 - 阅读
references/guides/unicode-symbols/guide.md - 尝试示例 - 使用
examples/spring-boot/中的模式 - 验证您的工作 - 运行
python scripts/extract_mermaid.py --validate
需要记录现有代码？
- 确定框架 - Spring Boot、FastAPI、React 等
- 加载示例指南 - 阅读
examples/{your-framework}/README.md - 匹配模式 - 在示例中查找相似的代码模式
- 生成图表 - 使用指南中的模板
- 验证 - 使用验证脚本
创建设计文档？
- 选择模板类型 - 架构、API、功能、数据库或系统
- 加载模板 - 从
assets/{type}-design-template.md读取 - 填写各部分 - 用实际内容替换占位符
- 添加图表 - 根据需要为每个部分加载图表指南
- 使用符号 - 在整个文档中增强使用 Unicode 符号
- 保存 - 放入
docs/design/并添加时间戳
层次化系统的工作原理
传统方法（低效）
- 加载整个技能文档（约 50KB）
- AI 处理所有模板和示例
- 高 token 使用量
- 响应时间慢
层次化方法（高效）
- 用户发出请求 → AI 分析意图
- 决策树激活 → 确定所需的指南
- 仅加载所需内容 → 读取特定指南（约 2-5KB）
- 生成输出 → 使用目标模板
- Token 高效 → 所需上下文减少 10 倍
示例流程
用户： "为我的 Docker Compose 设置创建部署图"
决策树：
1. 分析："部署图" + "Docker Compose"
2. 确定：需要 deployment-diagrams.md
3. 加载：references/guides/diagrams/deployment-diagrams.md（2KB）
4. 查找模式：存在 Docker Compose 模板
5. 生成：使用模板 + Unicode 符号
6. 输出：在 30 秒内完成图表
使用的 Token： 约 2,000（对比传统方法的约 10,000）
完成状态
✅ 已完成：
- 层次化决策树编排器
- 包含模板的活动图指南
- 部署图指南（AWS、GCP、K8s、无服务器、Docker）
- Unicode 符号指南（100+ 符号）
- 包含验证的美人鱼图提取脚本
- 美人鱼图到图像转换脚本
- Spring Boot 代码到图表示例
- 设计文档模板（5 种类型）
- 高对比度样式系统
🚧 进行中：
- FastAPI 示例
- React 组件架构示例
- Python ETL 管道示例
📋 计划中：
- 架构图指南
- 序列图指南
- 代码到图表总指南
- Node.js/Express 示例
- Java Web 应用示例
贡献
要添加新的图表类型指南：
- 在
references/guides/diagrams/{type}-diagrams.md中创建指南 - 包含：
- 何时使用
- 基本语法
- 常见模式（3-5 个模板）
- Unicode 符号示例
- 最佳实践
- 更新
SKILL.md决策树 - 添加带有代码映射的示例
要添加新的语言示例：
- 在
examples/{framework}/中创建目录 - 添加
README.md包含：- 框架概述
- 从结构生成的架构图
- 从配置生成的部署图
- 从代码生成的序列图
- 从逻辑生成的活动图
- 更新
SKILL.md代码到图表表格
许可证
克劳德代码技能的一部分 - MIT 许可证
相关技能
- confluence - 将图表上传到 Confluence
- plantuml - 替代图表格式
链接
- GitHub 仓库
- Skilz 市场列表
- 美人鱼官方文档
版本： 2.0.0 更新日期： 2025-01-13 维护者： SpillwaveSolutions