视觉资源使用指南
这个目录是项目的"图形化学习包"。除了 10 章文字说明书，这里把项目用 11 张图 + 3 份辅助材料重新组织一遍，适合快速过、适合做对外讲解的素材。
目录结构
视觉资源/
├── README.md 本文件
├── 快速讲解卡.md 15 段速记：每段 30 秒讲清一块
├── 进阶学习路径.md 5 阶段循序渐进学习计划
├── 常见问答30题.md 30 个高频问题及答案
├── diagrams/ 11 张图 + 对应解读
│ ├── 01-项目架构总览.md ← 解读文档（含 [图 1]）
│ ├── 02-启动时序图.md ← 解读文档（含 [图 2]）
│ ├── 03-音频数据流图.md
│ ├── 04-状态机转换图.md
│ ├── 05-唤醒到回复完整时序.md
│ ├── 06-协议对比.md
│ ├── 07-MCP工具调用时序.md
│ ├── 08-OTA升级流程.md
│ ├── 09-配网三方式对比.md
│ ├── 10-板级架构关系.md
│ ├── 11-核心文件依赖关系.md
│ └── src/ Mermaid 源文件 (.mmd) + puppeteer 配置
└── images/ 渲染好的 PNG 图（直接看）
├── 01-architecture.png
├── 02-startup-sequence.png
├── ...
└── 11-file-dependency.png
三类资源的不同用法
1. 11 张图 (images/*.png 或 diagrams/*.md)
直接看：每张图配一个 .md 解读文档，告诉你这张图怎么读、看完该懂什么、对应说明书哪一章。
推荐顺序：
| 阶段 | 看哪几张 | 用时 |
|---|---|---|
| 第一次接触项目 | 1 (架构总览) → 11 (文件依赖) → 4 (状态机) | 30 分钟 |
| 想搞清数据流 | 3 (音频流) → 5 (唤醒到回复) | 20 分钟 |
| 想理解通信 | 6 (协议对比) → 7 (MCP) | 20 分钟 |
| 想搞产品化 | 8 (OTA) → 9 (配网) → 2 (启动) → 10 (板级) | 30 分钟 |
2. 快速讲解卡 (快速讲解卡.md)
把整个项目浓缩成 15 段速记，每段 30 秒能讲清一块，按顺序念下来就是一个完整的 30 分钟项目介绍。每段标注配合看哪张图。
适合：
- 自己快速回顾整个项目脉络
- 拿来对外讲一遍这个项目
- 写技术分享 PPT 时的素材
3. 进阶学习路径 (进阶学习路径.md)
系统学习计划：从"跑通设备"到"产品化扩展"分 5 个阶段，每阶段给具体的阅读顺序和动手练习。
适合：
- 自己定阶段性学习计划
- 给团队新人下任务
- 估算"搞懂这个项目要多久"
4. 常见问答 30 题 (常见问答30题.md)
30 个高频问题及简短回答。涵盖项目定位、硬件、软件架构、安全运维、性能优化、商业合规 6 个方向。
适合：
- 阅读时遇到具体问题快速找答案
- 准备技术答辩或评审
- 自己复盘"哪些细节还不熟"
怎么打开这些图？
方式 A：直接看 PNG（最简单）
打开 images/ 目录任何 .png 文件，用 macOS Preview / Windows 照片查看器 / 浏览器都能看。
方式 B：在 Markdown 阅读器里看（推荐）
diagrams/*.md 文件里直接嵌入了图，用以下任一软件打开能看到图 + 解读文字一起：
| 软件 | 是否免费 | 平台 |
|---|---|---|
| Typora | 付费 | macOS / Windows / Linux |
| Obsidian | 免费 | macOS / Windows / Linux |
| VSCode + Markdown Preview | 免费 | 全平台 |
| MarkText | 免费 | macOS / Windows / Linux |
| GitHub 在线浏览 | 免费 | 浏览器 |
方式 C：自己改图
所有图的源文件在 diagrams/src/*.mmd，用 Mermaid 语法。
修改流程：
- 打开
diagrams/src/01-architecture.mmd改文字 - 复制内容粘贴到 https://mermaid.live 即时预览
- 在 Mermaid Live Editor 里导出为 PNG / SVG 覆盖
images/目录
如果改完想批量重新生成 PNG：
cd 视觉资源
for f in diagrams/src/*.mmd; do
name=$(basename "$f" .mmd)
npx -y -p @mermaid-js/mermaid-cli mmdc \
-i "$f" -o "images/$name.png" \
-p diagrams/src/puppeteer-config.json \
-w 2000 -t default --backgroundColor white
done
11 张图速览
| # | 图名 | 类型 | 看完后能讲明白 |
|---|---|---|---|
| 1 | 项目架构总览 | 大方框图 | 项目分哪几大块、各块怎么通信 |
| 2 | 启动时序图 | 时序图 | 从上电到能用之间发生了什么 |
| 3 | 音频数据流图 | 数据流图 | PCM 怎么进 Opus 怎么出 |
| 4 | 状态机转换图 | 状态图 | 11 个状态怎么跳 |
| 5 | 唤醒到回复完整时序 | 时序图 | 用户喊一句话到设备回应 |
| 6 | 协议对比 | 对比图 | WebSocket vs MQTT+UDP |
| 7 | MCP 工具调用时序 | 时序图 | LLM 怎么真的控制设备 |
| 8 | OTA 升级流程 | 流程图 | A/B 双分区怎么防砖 |
| 9 | 配网三方式对比 | 流程图 | 设备怎么知道 Wi-Fi 密码 |
| 10 | 板级架构关系 | UML 类图 | 110 块板子的继承结构 |
| 11 | 核心文件依赖关系 | 依赖图 | 哪个 .cc 依赖哪个 .cc |
对外讲解的推荐路径
如果只有 5 分钟讲：
- 打开 图 1 讲架构 + 三条主数据流
如果有 15 分钟讲：
- 图 1（架构）→ 图 5（唤醒到回复）→ 图 6（协议）
如果有 30 分钟讲：
- 按"快速讲解卡"的 15 段速记走一遍
如果想深入半天/一天：
- 按"进阶学习路径"的阶段 1-3 安排
反馈
如果发现：
- 某张图想要换种风格（比如时序图换成状态图、或者要彩色版本）
- 某张图描述的信息和实际代码对不上
- 想加新的图（比如服务器侧的实现示意、或某个具体子系统的细节图）
可以指出来，会按需求重做或新增。源文件都在 diagrams/src/，改起来很快。