# 美人鱼架构师：图表与文档技能

> 通过智能编排、代码转图表和Python实用程序，生成全面的美人鱼图表和设计文档。在几秒钟内开始创建详细的技术文档。

- Canonical: https://nanoskill.ai/zh/skills/mermaid-agent-skill
- Markdown: https://nanoskill.ai/zh/skills/mermaid-agent-skill.md
- Author: SpillwaveSolutions
- Published: 2026-05-26T01:25:42.765Z
- Updated: 2026-07-19T03:48:37.206Z
- Language: zh-CN
- Source type: github
- Popularity signal: 66

## Sources

- https://github.com/spillwavesolutions/design-doc-mermaid

## Install

```shell
npx skills add https://github.com/spillwavesolutions/design-doc-mermaid
```

## About

美人鱼架构师技能使开发人员、架构师和技术写作人员能够高效地创建和管理全面的美人鱼图表和设计文档。通过利用智能编排和按需指南加载，该技能简化了复杂系统、工作流程和代码结构的可视化。它帮助用户生成准确且视觉上吸引人的图表，确保清晰的沟通和最新的文档。

这个强大的克劳德代码技能提供了诸如代码转图表生成等高级功能，允许您直接从春靴或快速API应用程序中提取架构见解。它还包括一组丰富的Python实用程序，用于提取、验证美人鱼图表并将其转换为图像格式，从而轻松与现有文档工作流程和工具（如汇合）集成。分层系统确保了高效的令牌使用和快速响应时间，提供了无缝的体验。

无论您需要记录API、可视化系统架构还是说明业务流程，美人鱼架构师都提供了完成任务所需的工具和模板。支持各种图表类型、Unicode语义符号和高对比度样式，您的图表将既信息丰富又易于访问。该技能还提供了结构化的学习路径和示例，帮助用户快速熟练掌握创建详细技术文档。

## Key features

- **智能图表生成**: 创建各种Mermaid图表，包括活动图、部署图、架构图和序列图，用于工作流程、基础设施、系统组件和API流程。
- **代码到图表转换**: 从现有代码库（例如Spring Boot、FastAPI）或配置文件自动生成图表，以可视化架构、部署和序列流程。
- **全面的设计文档创建**: 使用预定义的架构、API、功能、数据库和系统设计模板，生成带有嵌入Mermaid图表的完整设计文档。
- **Unicode语义符号和高对比度样式**: 通过超过100个有意义的Unicode符号和高对比度配色方案增强图表的清晰度和可访问性，提高可读性。
- **用于图表管理的Python实用工具**: 使用Python脚本提取、验证Mermaid图表并将其转换为PNG/SVG图像，支持批处理以及与Confluence等工具的集成。

## Use cases

- **可视化软件架构**: 开发人员和架构师可以从代码或配置文件生成架构图和部署图，以了解系统组件和基础设施。
- **记录API流程和工作流程**: 技术写作人员和工程师可以创建详细的序列图和活动图，以说明API交互、业务流程和用户旅程。
- **自动化设计文档创建**: 团队可以快速生成针对各种用途（API、系统、功能）的结构化设计文档，并自动嵌入Mermaid图表，节省时间并确保一致性。
- **维护最新的技术文档**: 通过直接从代码或配置生成图表，确保文档保持最新，并轻松将其转换为图像格式以便共享和协作。

## Result preview

查看由此代理技能生成的外卖平台系统的美人鱼图表。

![mermaid-architect-demo1](https://file.nanoskill.ai/mermaid-architect-demo1.jpg)

![mermaid-architect-demo-2](https://file.nanoskill.ai/mermaid-architect-demo-2.jpg)

![mermaid-architect-demo-3](https://file.nanoskill.ai/mermaid-architect-demo-3.jpg)

## Result walkthrough

### 步骤1：安装

将技能添加到您的代理。

![mermaid-architect-step-1](https://file.nanoskill.ai/mermaid-architect-step-1.jpg)

### 步骤2：描述一个流程

输入您想要可视化的工作流、系统或序列。

![mermaid-architect-step-2](https://file.nanoskill.ai/mermaid-architect-step-2.jpg)

### 步骤3：查看结果

根据您的流程描述获取生成的美人鱼图表。

![mermaid-architect-step-3](https://file.nanoskill.ai/mermaid-architect-step-3.jpg)

## Skill definition

# 美人鱼架构师 - 全面图表与文档技能

**版本 2.0** - 具有智能编排的层次化架构

一项强大的克劳德代码技能，使用按需加载指南、代码到图表生成和 Python 实用程序来创建美人鱼图表和设计文档。

## 安装

### 通过 Skilz 市场一键安装

从 [Skilz 市场](https://skillzwave.ai/skill/SpillwaveSolutions__design-doc-mermaid__design-doc-mermaid__SKILL/) 立即安装此技能：

```bash
skilz install SpillwaveSolutions_design-doc-mermaid/design-doc-mermaid
```

### 手动安装

直接克隆到您的克劳德代码技能目录中：

```bash
# 导航到您的技能目录
cd ~/.claude/skills

# 克隆仓库
git clone https://github.com/SpillwaveSolutions/design-doc-mermaid.git
```

### 验证安装

安装后，验证技能是否可用：

```bash
# 列出已安装的技能
ls ~/.claude/skills/design-doc-mermaid

# 或询问克劳德代码
# "列出我安装的技能"
```

## 此技能的功能

**智能图表生成：**
- 活动图（工作流、流程、业务逻辑）
- 部署图（云基础设施、K8s、无服务器）
- 架构图（系统组件、微服务）
- 序列图（API 流、服务交互）
- 带有嵌入式图表的完整设计文档

**代码到图表转换：**
- 从 Spring Boot 应用中提取架构
- 从配置文件中生成部署图
- 从方法调用创建序列图
- 记录 ETL 管道和数据流

**图表管理：**
- 从 Markdown 文件中提取美人鱼图表
- 使用 mermaid-cli 验证图表语法
- 将图表转换为 PNG/SVG 图像
- 批量处理整个目录

## 快速开始

### 创建活动图

```
用户："创建一个包含电子邮件验证的用户注册活动图"
```

此技能将：
1. 加载 `references/guides/diagrams/activity-diagrams.md`
2. 使用注册模式模板
3. 添加 Unicode 符号（🔐 表示安全，📧 表示电子邮件，✅ 表示成功）
4. 应用高对比度样式
5. 输出完整的美人鱼图表

### 从代码生成

```
用户："这是我的 Spring Boot application.yml - 生成一个部署图"
```

此技能将：
1. 分析配置（数据源、缓存、安全）
2. 加载 `references/guides/diagrams/deployment-diagrams.md`
3. 加载 `examples/spring-boot/README.md`
4. 将配置映射到云资源
5. 生成带有资源规格的部署图

### 创建设计文档

```
用户："为联系人 API 创建一个 API 设计文档"
```

此技能将：
1. 加载 `assets/api-design-template.md`
2. 加载相关的图表指南（序列图、ER图、架构图）
3. 生成带有嵌入式图表的完整文档
4. 保存到 `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 符号：

```mermaid
graph TB
    User[👤 客户端] --> Gateway[🌐 API 网关]
    Gateway --> Auth[🔐 认证服务]
    Gateway --> API[⚙️ API 服务]
    API --> DB[(💾 数据库)]
    API --> Cache[(⚡ Redis)]
    API --> Queue[📬 消息队列]
    Queue --> Worker[⚙️ 后台工作器]
```

**符号分类：**
- 基础设施：☁️ 🌐 🔌 📡 🗄️
- 计算：⚙️ ⚡ 🔄 🚀 💨
- 数据：💾 📦 📊 📈 🗃️
- 消息传递：📨 📬 📤 📥 🐰
- 安全：🔐 🔑 🛡️ 🚪 👤
- 监控：📝 📊 🚨 ⚠️ ✅ ❌

### 2. 高对比度样式

所有图表都使用无障碍的高对比度颜色 - 详情见 SKILL.md。

### 3. Python 实用程序

#### 提取图表

```bash
# 列出文件中的所有图表
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
```

#### 转换为图像

```bash
# 单个文件
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
```

## 要求

### 图表生成
- 克劳德代码技能系统（自动）
- 指南和模板（包含在此技能中）

### 验证与图像转换
```bash
# 全局安装 mermaid-cli
npm install -g @mermaid-js/mermaid-cli

# 验证安装
mmdc --version
```

### Python 脚本
- Python 3.7+
- 无需额外包（仅使用标准库）

## 学习路径

### 初次接触美人鱼图表？

1. **从活动图开始** - 阅读 `references/guides/diagrams/activity-diagrams.md`
2. **学习 Unicode 符号** - 阅读 `references/guides/unicode-symbols/guide.md`
3. **尝试示例** - 使用 `examples/spring-boot/` 中的模式
4. **验证您的工作** - 运行 `python scripts/extract_mermaid.py --validate`

### 需要记录现有代码？

1. **确定框架** - Spring Boot、FastAPI、React 等
2. **加载示例指南** - 阅读 `examples/{your-framework}/README.md`
3. **匹配模式** - 在示例中查找相似的代码模式
4. **生成图表** - 使用指南中的模板
5. **验证** - 使用验证脚本

### 创建设计文档？

1. **选择模板类型** - 架构、API、功能、数据库或系统
2. **加载模板** - 从 `assets/{type}-design-template.md` 读取
3. **填写各部分** - 用实际内容替换占位符
4. **添加图表** - 根据需要为每个部分加载图表指南
5. **使用符号** - 在整个文档中增强使用 Unicode 符号
6. **保存** - 放入 `docs/design/` 并添加时间戳

## 层次化系统的工作原理

### 传统方法（低效）
- 加载整个技能文档（约 50KB）
- AI 处理所有模板和示例
- 高 token 使用量
- 响应时间慢

### 层次化方法（高效）
1. **用户发出请求** → AI 分析意图
2. **决策树激活** → 确定所需的指南
3. **仅加载所需内容** → 读取特定指南（约 2-5KB）
4. **生成输出** → 使用目标模板
5. **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 应用示例

## 贡献

要添加新的图表类型指南：

1. 在 `references/guides/diagrams/{type}-diagrams.md` 中创建指南
2. 包含：
   - 何时使用
   - 基本语法
   - 常见模式（3-5 个模板）
   - Unicode 符号示例
   - 最佳实践
3. 更新 `SKILL.md` 决策树
4. 添加带有代码映射的示例

要添加新的语言示例：

1. 在 `examples/{framework}/` 中创建目录
2. 添加 `README.md` 包含：
   - 框架概述
   - 从结构生成的架构图
   - 从配置生成的部署图
   - 从代码生成的序列图
   - 从逻辑生成的活动图
3. 更新 `SKILL.md` 代码到图表表格

## 许可证

克劳德代码技能的一部分 - MIT 许可证

## 相关技能

- **confluence** - 将图表上传到 Confluence
- **plantuml** - 替代图表格式

## 链接

- [GitHub 仓库](https://github.com/SpillwaveSolutions/design-doc-mermaid)
- [Skilz 市场列表](https://skillzwave.ai/skill/SpillwaveSolutions__design-doc-mermaid__design-doc-mermaid__SKILL/)
- [美人鱼官方文档](https://mermaid.js.org/)

---

**版本：** 2.0.0
**更新日期：** 2025-01-13
**维护者：** SpillwaveSolutions

## FAQ

### 这个技能可以生成哪些类型的Mermaid图表？

这个技能可以生成活动图、部署图、架构图和序列图。它支持可视化工作流、云基础设施、系统组件和API交互。

### 代码到图表的转换是如何工作的？

该技能分析您的代码或配置文件（例如Spring Boot的application.yml），并使用预定义的模式和指南自动生成相应的Mermaid图表，如部署图或序列图。

### 我可以用这个技能创建完整的设计文档吗？

是的，该技能包含各种设计文档（架构、API、功能、数据库、系统）的模板。它可以根据您的输入和所选模板生成带有嵌入Mermaid图表的完整文档。

### 生成Mermaid图表的分层系统有哪些好处？

分层系统高效地分析您的意图，只加载必要的指南和模板（通常只有2-5KB），而不是整个技能文档。这显著减少了令牌使用量并加快了响应时间。

### 这个技能包含任何Python实用工具吗？

是的，该技能提供了Python脚本，用于从Markdown文件中提取Mermaid图表、验证其语法并将其转换为PNG或SVG图像格式。这些实用工具还支持批处理。

### 使用验证和图像转换功能有哪些要求？

要进行图表验证和图像转换，您需要通过npm全局安装\`mermaid-cli\`（\`npm install -g @mermaid-js/mermaid-cli\`）。Python脚本需要Python 3.7+。