应用场景与用例

核心应用场景

场景 1: AI Agent 架构讨论

用户画像: 技术主管、架构师、高级开发者

痛点:

• 向团队解释新架构时，文字描述冗长且易误解
• 远程会议中无法快速绘制共享视觉参考
• 架构文档更新滞后于实际演进

使用工作流:

1. 用户在 Claude Code 中提问:
   "创建 Excalidraw 图表展示我们的微服务架构，包括 API Gateway、
    用户服务、订单服务、支付服务和数据库"

2. AI 执行 SKILL.md 流程:
   - 深度评估：综合技术图表 → 需要证据工件
   - 研究：查找真实服务名、API 端点、数据格式
   - 视觉映射：API Gateway 使用扇出模式，数据库使用收敛模式
   - 分区块构建：Section 1 入口、Section 2 服务层、Section 3 数据层

3. 输出:
   - architecture.excalidraw（可编辑）
   - architecture.png（预览）

4. 用户迭代:
   "添加缓存层在 API Gateway 和UserService 之间"
   → AI 修改 JSON → 重新渲染 → 新预览

价值实现:

• 时间节省: 从 30 分钟手绘 → 2 分钟生成 + 迭代
• 准确性提升: AI 研究真实规范，避免记忆错误
• 版本控制: .excalidraw 文件可 git 跟踪变更

场景 2: 技术教程/博客创作

用户画像: 技术博主、教育者、布道师

痛点:

• 教程中需要大量图表解释概念
• 手绘图表风格不一致，显得不专业
• 更新教程时图表难以维护

典型案例: YouTube 技术视频脚本配图

用户指令:
"创建一系列 Excalidraw 图表，解释 AG-UI 协议如何工作。
 需要包含：
 1. 整体架构图
 2. 事件流时间线
 3. 前端渲染流程
 4. 代码示例（使用 CopilotKit）"

AI 输出:
- 图 1: 架构图（扇出模式展示事件从 Agent 到多个 UI 组件）
- 图 2: 时间线（垂直主线 + 真实事件名 RUN_STARTED、STATE_DELTA 等）
- 图 3: 前端流程（收敛模式展示多个事件聚合到 renderer）
- 证据工件：嵌入 createA2UIMessageRenderer() 代码片段

迭代优化:
"图 2 的事件名间距太小，文字重叠了"
→ AI 调整 y 坐标 → 重新渲染 → 问题解决

价值实现:

• 教学价值: 图表包含真实代码和数据，viewer 可学习实际实现
• 一致性: 所有图表使用相同颜色系统，专业统一
• 可维护: 更新教程时，修改 JSON 即可重新渲染

场景 3: PRD/技术文档撰写

用户画像: 产品经理、技术文档工程师

痛点:

• PRD 中流程图用文字描述，开发理解成本高
• 需求变更时图表更新困难
• 缺乏与代码仓库的集成

使用工作流:

PRD 章节：系统架构

传统方式:
"用户请求首先到达 API Gateway，然后 Gateway 根据路由规则
 转发到相应的微服务。微服务处理后将响应返回给 Gateway，
 Gateway 聚合多个服务的响应后返回给客户端。"
  （开发需要自行脑补架构）

使用 Skill:
[插入 Excalidraw 图表]
- API Gateway（中心椭圆，扇出箭头到各服务）
- 微服务（矩形，标注真实服务名）
- 数据库（圆柱形或椭圆，收敛箭头）
- 证据工件：示例请求/响应 JSON

开发阅读图表后，5 秒内理解架构，无需反复询问。

价值实现:

• 沟通效率: 一图胜千言，减少澄清会议
• 需求追溯: .excalidraw 文件与 PRD 同版本管理
• 开发友好: 包含真实 API 格式，开发可直接参考实现

场景 4: 代码库理解与分析

用户画像: 新入职开发者、代码审查者

痛点:

• 接手老项目时难以快速理解架构
• 代码审查中难以描述模块间关系
• 文档缺失或过时

增强用例（需结合代码库分析技能）:

用户指令:
"分析这个代码库，创建 Excalidraw 图表展示模块依赖关系"

AI 工作流（未来扩展）:
1. 读取 package.json / requirements.txt 识别模块
2. 扫描 import/require 语句构建依赖图
3. 生成 Excalidraw 图表：
   - 模块作为节点
   - import 关系作为箭头
   - 证据工件：关键模块的代码片段

输出:
- dependencies.excalidraw（可点击查看模块详情）
- 新开发者 10 分钟内理解项目结构

当前限制: excalidraw-diagram-skill 本身不具备代码库分析能力，需用户手动描述或结合其他技能。

场景 5: Obsidian/PKM 知识管理

用户画像: 知识工作者、研究者、学生

痛点:

• 笔记中概念关系用文字描述，难以回顾
• 双向链接只能显示连接，无法可视化关系类型
• 知识图谱过于简化，缺乏细节

Obsidian 集成工作流:

1. 在 Obsidian 笔记中:
   ```excalidraw
   ![[concept-map.excalidraw]]

2. AI 生成概念图:

   • 核心概念（椭圆，中心位置）
   • 子概念（矩形，扇出排列）
   • 关系类型（箭头标签：extends、uses、depends-on）
   • 证据工件：引用原文片段

3. Obsidian 渲染:

   • 安装 Excalidraw 插件后直接显示图表
   • 点击图表可编辑
   • 图表与笔记同版本管理

**价值实现**:
- **知识可视化**: 复杂概念关系一目了然
- **可交互**: 读者可点击编辑、添加注释
- **版本历史**: git 跟踪知识演进

## 典型用户画像

### 画像 1: Alex - 技术主管

**背景**: 35 岁，10 年经验，管理 15 人工程团队

**日常工作**:
- 设计系统架构
- 向团队解释技术方案
- 评审 PRD 和技术文档
- 跨部门沟通

**使用 Skill 场景**:
- 架构评审会议前生成讨论图表
- PRD 中嵌入架构图减少澄清
- 新员工 onboarding 材料

**价值点**:
- 节省手绘时间（30 分钟→2 分钟）
- 提升沟通准确性（视觉论证 vs 文字描述）
- 可复用图表模板（类似架构只需修改服务名）

### 画像 2: Jamie - 技术博主

**背景**: 28 岁，全职技术内容创作者，YouTube 50K 订阅

**日常工作**:
- 撰写技术教程
- 制作视频脚本
- 设计示例代码
- 维护博客

**使用 Skill 场景**:
- 教程配图生成
- 视频脚本可视化
- 系列文章风格统一

**价值点**:
- 专业外观（语义化颜色系统）
- 教学价值（证据工件包含真实代码）
- 更新便捷（修改 JSON 重新渲染）

### 画像 3: Sam - 新入职开发者

**背景**: 24 岁，初级工程师，接手遗留项目

**日常工作**:
- 理解代码库结构
- 修复 bug
- 实现新功能
- 向导师请教

**使用 Skill 场景**:
- 请导师用 Skill 生成架构图
- 自己生成模块依赖图辅助理解
- 在代码审查中用图表解释改动

**价值点**:
- 学习曲线降低（视觉化加速理解）
- 减少提问次数（图表自助理解）
- 建立系统思维（看到整体而非局部）

## 用例深度分析

### 用例 A: AG-UI 协议事件流图（真实案例）

**用户需求**:
> "创建 Excalidraw 图表展示 AG-UI 协议如何从 AI Agent 流式传输事件到前端 UI"

**AI 研究过程**（SKILL.md 强制要求）:
1. 搜索 AG-UI 协议文档
2. 查找真实事件名：RUN_STARTED、STATE_DELTA、A2UI_UPDATE
3. 查找前端渲染方法：createA2UIMessageRenderer()
4. 理解事件流方向：Agent → Protocol → Frontend

**图表设计**:

Section 1: AI Agent（左侧）

• 椭圆表示 Agent
• 证据工件：Agent 初始化代码片段

Section 2: AG-UI Protocol（中间）

• 时间线模式（垂直主线）
• 事件标记点 + 真实事件名
• 证据工件：示例事件 JSON

Section 3: Frontend UI（右侧）

• 收敛模式（多个事件→renderer）
• 证据工件：createA2UIMessageRenderer() 调用代码

**迭代过程**:
1. 第一遍渲染：事件名间距太小，文字重叠 → 增加 y 轴间隔
2. 第二遍渲染：箭头穿过时间线主线 → 添加路径点绕过
3. 第三遍渲染：证据工件代码太长被裁剪 → 放大背景矩形
4. 第四遍渲染：通过 ✓

**最终输出**:
- agui-protocol.excalidraw（可编辑）
- agui-protocol.png（预览，嵌入教程）

**教学价值**:
- viewer 不仅理解事件流，还知道真实事件名
- 开发者可直接复制代码片段到自己的项目
- 比纯文字描述学习效率高 3-5 倍

### 用例 B: 微服务架构图

**用户需求**:
> "创建微服务架构图，包括 API Gateway、UserService、OrderService、PaymentService 和 PostgreSQL"

**图表设计**:

Section 1: Client → API Gateway

• 扇出模式（Gateway→Services）
• Gateway 使用 Start/Trigger 颜色

Section 2: Microservices

• 矩形表示各服务
• 水平排列，均匀间距
• 证据工件：各服务的核心 API 端点

Section 3: Database

• 收敛模式（Services→DB）
• DB 使用 End/Success 颜色
• 证据工件：示例表结构

**关键设计决策**:
- **为什么 API Gateway 用椭圆？** 椭圆表示"入口点/触发器"，符合语义
- **为什么服务用矩形？** 矩形表示"处理单元"，符合"过程/动作"语义
- **为什么 DB 用绿色？** End/Success 颜色表示"数据持久化=完成"

**证据工件选择**:
- API Gateway: 路由配置示例
- UserService: GET /users/:id 响应 JSON
- OrderService: POST /orders 请求体示例
- PaymentService: 支付回调 Webhook 格式
- Database: users 表 schema

**价值**:
- 新开发者 5 分钟内理解系统架构
- API 文档与架构图一体化
- 架构演进时可追溯变更

## 边界与限制

### 当前能力边界

| 支持 | 不支持 | 需扩展 |
|------|--------|--------|
| 自然语言→静态图表 | 实时画布编辑 | MCP 协议集成 |
| 手动描述→图表 | 自动代码库分析 | 代码理解技能 |
| 单图表生成 | 多图表联动/动画 | - |
| PNG 静态预览 | 交互式 SVG 导出 | 导出功能扩展 |
| 品牌颜色定制 | 自动布局优化 | 布局算法 |

### 不适用场景

**场景 1: 快速草图**
- 需求：5 分钟内画出粗略想法
- 问题：Skill 需要详细研究验证，耗时较长
- 替代：手绘或使用 simpler 工具

**场景 2: 超大规模系统**
- 需求：展示 100+ 微服务的企业架构
- 问题：JSON 过于庞大，渲染性能差
- 替代：分层图表（按领域拆分）

**场景 3: 实时数据可视化**
- 需求：展示当前系统状态的实时监控图
- 问题：静态 JSON 无法动态更新
- 替代：Grafana、Datadog 等监控工具

### 最佳实践建议

**何时使用**:
- ✓ 需要教学价值的技术图表
- ✓ 架构讨论/评审场景
- ✓ 教程/文档配图
- ✓ 知识管理可视化

**何时不使用**:
- ✗ 只需粗略草图
- ✗ 需要实时数据更新
- ✗ 超大规模系统（考虑分层）
- ✗ 需要复杂交互（考虑专业工具）

---

## 本章小结

**核心价值场景**:
1. AI Agent 架构讨论（节省 90% 绘图时间）
2. 技术教程创作（提升教学价值）
3. PRD/文档撰写（减少沟通成本）
4. 代码库理解（加速 onboarding）
5. Obsidian 知识管理（视觉化概念关系）

**典型用户**:
- 技术主管（架构沟通）
- 技术博主（教程配图）
- 新开发者（理解代码库）

**成功关键**:
- 证据工件提供真实代码/数据
- 语义化颜色系统确保一致性
- 渲染验证循环保证视觉质量
- 分区块构建规避 token 限制

下一章将进行竞品对比分析。