第 02 章 | 案例项目 doc2video 全貌

更新于 2026/5/9
💡 进群学习加 wx: agentupdate
(申请发送: agentupdate)

第 2 章：案例项目 doc2video 全貌

学习目标

理解整个教程要做的项目。这样后续每个抽象概念你都能对应到具体场景。

一句话项目定义

把一份 markdown 教学文档，编译成一段带配音、字幕、真实终端操作的视频。

输入输出

输入：一份 markdown 文档（比如 "Claude Code 安装教程"）

## 第一步：安装 Node
我们用 nvm 安装 Node 22。打开终端运行：
```bash
curl -o- https://raw.../nvm/install.sh | bash
```

## 第二步：安装 Claude Code
有了 Node 之后…
```bash
npm install -g @anthropic-ai/claude-code
```

输出：

dist/install-claude/
├── video.mp4         5 分钟视频，含真实操作
├── video.srt         字幕
└── report.md         运行报告

视频里能看到：

  • 左半屏：渲染好的 markdown 文档，当前步骤被高亮
  • 右半屏：真实 iTerm 终端，命令一个字一个字打出来、真的在跑
  • 中文配音：把每一步的讲解念出来

系统组件

flowchart TB
    Input["tutorial.md"] --> Parser["Markdown 解析器"]
    Parser --> Steps["Step 列表
narration + commands"]

    Steps --> TTS["edge-tts
生成 mp3"]
    Steps --> Term["tmux 终端
真实执行命令"]
    Steps --> Doc["浏览器面板
WebSocket 高亮"]

    TTS --> Recorder
    Term --> Recorder
    Doc --> Recorder

    Recorder["ffmpeg
全屏录像"] --> Composer["视频合成"]

    Composer --> Output["video.mp4 + .srt + report.md"]

    style Input fill:#e8f5e9
    style Output fill:#fff3e0

关键技术决策（这些决策的来历后面章节会详细讲）

决策 我们选了 为什么
真实执行 vs 演 真跑 真错也是教学价值
沙盒 vs 真桌面 真桌面 macOS 录屏要 avfoundation
配音引擎 edge-tts 免费、中文质量好
文档高亮 本地 HTTP + WebSocket 不引入 React 重型框架
同步策略 先念后敲 把反应式调度变线性

这个项目为什么是好"教学样本"

✅ 不大不小：3 周左右能跑通 MVP
✅ 多语言/多技术栈：Python + Web + 系统命令
✅ 涵盖测试金字塔：单元 / 功能 / E2E
✅ 有真实复杂度：状态机、并发协调、外部依赖
❌ 不太适合：UI 重的项目（这个项目几乎没 UI）

你现在能做什么

  • 能复述 doc2video 是做什么的
  • 能识别它属于哪一类项目（开发者工具 / 自动化 pipeline）
  • 能想清楚自己的项目跟它有多像

下一章建立心智模型，把整个教程的所有概念组织进一张图。