ai-agent-book 精选快照（<2MB 代码与文档，来自 github.com/bojieli/ai-agent-book）

chapter5/video-edit/README.md

@@ -0,0 +1,457 @@
+# Experiment 5-6: API-Driven Smart Video Editing / 实验 5-6：基于 API 的智能视频剪辑
+
+> Companion lab for *AI Agents in Depth*, Chapter 5 — NL request + multi-scene video → two-step Vision locate → Blender bpy script / ffmpeg cut → Proposer–Reviewer.  
+> 《深入理解 AI Agent》配套：自然语言需求 + 多场景视频 → 两步 Vision 定位 → 生成 Blender bpy / ffmpeg 剪辑 → 提议者-审核者。
+
+← [Chapter 5 index / 返回第 5 章目录](../README.md)
+
+---
+
+## English
+
+### Purpose
+
+Given a multi-scene video and one NL request (e.g. “cut out the surfing part”), the Agent locates the target scene, **generates a Blender Python API script**, cuts the clip, and self-reviews.
+
+Three mechanisms in multimedia processing:
+
+1. **Two-step Vision locate**: Proposer cannot “watch” video directly; a **video-analysis sub-agent** uses ffmpeg frame extraction + Vision LLM to find time bounds.
+2. **Code generation (Blender Python API)**: Proposer turns the edit plan into a **bpy** script—import / trim / subtitle / speed / render as API calls, run with `blender --background --python edit.py`. Without Blender, scripts still generate; render falls back to ffmpeg (see “edit backends”).
+3. **Proposer / Reviewer**: after cut, Reviewer samples key frames with Vision; fail → feedback → iterate.
+
+### Two-step locate
+
+Scanning every frame is slow/expensive → coarse then fine:
+
+- **Coarse**: one frame every **10s**; Vision gets a rough interval (e.g. surfing 20–30s).
+- **Fine**: expand the coarse window by one coarse step; one frame every **1s**; Vision returns precise bounds (e.g. 15–29s).
+
+Encapsulated as a **sub-agent**: tens of screenshots live only in the sub-agent’s one-shot context and do not pollute Proposer/Reviewer history. Demo prints token comparison at the end.
+
+### Proposer–Reviewer flow
+
+```
+NL request ──► Proposer parses intent (scene + effects)
+              │
+              ▼
+         Video-analysis sub-agent two-step locate ──► [start, end]
+              │
+              ▼
+         Proposer emits Blender bpy script (edit.py) ──► render cut (+ subtitle/slow-mo)
+              │                                        Blender if installed else ffmpeg
+              ▼
+         Reviewer samples start/mid/end frames ──► Vision pass/fail + feedback
+              │pass?  no → Proposer adjusts bounds, re-cut (max 3 rounds)
+              ▼yes
+           final.mp4
+```
+
+### Run
+
+```bash
+# From the repository root: use the shared Chapter 5 environment
+uv sync --locked --python 3.12 --extra ch5
+
+# Activate it before changing directories:
+# macOS/Linux:
+source .venv/bin/activate
+# Windows PowerShell: .\.venv\Scripts\Activate.ps1
+# Windows cmd: .venv\Scripts\activate.bat
+
+# pip fallback when uv is not installed:
+# python -m pip install -e ".[ch5]"
+
+cd chapter5/video-edit
+
+# Single-project compatibility path, still supported during migration:
+# python -m pip install -r requirements.txt
+
+cp env.example .env        # OPENAI_API_KEY (or OPENROUTER_API_KEY fallback)
+python demo.py             # default: "把冲浪的部分剪出来" (full pipeline)
+python demo.py "把滑雪部分剪出来，并加上字幕 Winter"   # custom request
+python demo.py -i my.mp4 -o out.mp4 "把演讲开场剪出来"  # own video + output
+python demo.py --backend blender   # force Blender headless (Blender required)
+python demo.py --vision-model gpt-5.6-luna  # also --text-model
+python demo.py --quick     # coarse sampling + single review round (cheapest Vision)
+python demo.py --smoke     # smoke: edit path + bpy script only; no API
+python demo.py --help
+```
+
+Common flags (see `--help`): `--input/-i`, `--output/-o`, `--backend {auto,blender,ffmpeg}`, `--text-model` / `--vision-model`.
+
+One command runs: generate/read video → two-step locate → bpy cut → review → final. Each run clears `output/` (idempotent). Full path calls Vision many times; use `--smoke` (zero API) or `--quick` first.
+
+### Sample outputs
+
+#### `--smoke` (zero API, reproducible)
+
+Real output of `python demo.py --smoke` (no OpenAI key; needs ffmpeg):
+
+```text
+==========================================================================
+  冒烟自检 | 剪辑链路 + bpy 脚本生成，不调用任何 API
+==========================================================================
+[1/3] 生成测试视频 OK：output/source.mp4（场景真值={'hiking': (0, 15), 'surfing': (15, 30), 'skiing': (30, 42), 'cycling': (42, 54)}）
+[2/3] 抽帧 OK：output/frames/smoke.png
+[3/3] 剪辑+字幕 OK（后端=ffmpeg（未装 Blender，回退））：
+  文件: smoke_cut.mp4
+  时长: 5.03s
+  容器: mov,mp4,m4a,3gp,3g2,mj2
+  大小: 121.4 KB
+  视频流: h264 1280x720 @ 30/1 fps
+  音频流: aac 44100Hz 1ch
+
+已生成 Proposer 的 Blender 脚本：output/edit.py
+（这正是书中'生成 Blender Python API 代码'的产物；装好 Blender 后可直接
+ `blender --background --python output/edit.py` 无头渲染。）
+
+✓ 冒烟自检通过：剪辑链路正常 + bpy 脚本已生成（未调用 OpenAI）。
+```
+
+`output/edit.py` is an executable Blender bpy script (`new_movie`, `frame_offset_start` / `frame_final_duration`, `new_effect(type='TEXT')`, `bpy.ops.render.render`); syntax-checked with `py_compile`.
+
+#### `--quick` (full path, needs API)
+
+Excerpt from `python demo.py --quick` (default surfing request); locate/error/token parts independent of bpy/ffmpeg:
+
+```text
+步骤 1 | Proposer 解析自然语言需求
+解析结果：目标场景='surfing scene'  特效=[]
+
+步骤 2 | 视频分析子 Agent：两步 Vision 定位（--quick 快速采样）
+  [粗粒度] 每 15s 采样 5 帧 → Vision 得区间 [15, 30]s（依据：The word 'SURFING' appears at t=15s and changes at t=30s.）
+  [细粒度] 窗口 [0.0, 45.0] 内每 2s 采样 23 帧 → 精确边界 [16.0, 28.0]s
+  >>> 最终定位：起 16.0s  止 28.0s
+  真值 [15, 30]s → 起点误差 1.0s，终点误差 2.0s（验收要求 ≤ 3s）
+
+步骤 3-4 | Proposer 剪辑 + Reviewer 审查（迭代）
+  Proposer 剪出片段 [16.0, 28.0]s，成片时长 12.0s
+  Reviewer：pass=... score=... 检查帧=['0.5', '6.0', '11.5']
+
+Token 统计（子 Agent 隔离截图，主上下文不被污染）
+  主 Agent（Proposer+Reviewer）：573 tokens
+  子 Agent（两步定位截图）    ：2934 tokens
+```
+
+Artifacts under `output/`:
+
+| File | Duration | Note |
+| --- | --- | --- |
+| `source.mp4` | 54.0s | Procedural 4-scene test source |
+| `edit_round1.py` | — | Proposer bpy script (portable) |
+| `cut_round1.mp4` | 12.0s | Round-1 candidate |
+| `final.mp4` | 12.0s | Chosen final (H.264 + AAC, 1280x720@30fps) |
+
+Token stats: tens of screenshots (2934 tok) only in **sub-agent**; main history (~573 tok) almost unpolluted. (Synthetic test shows “SURFING” text, not real surfing—Reviewer may fail on content; real video avoids that.)
+
+### Dependencies
+
+- **ffmpeg / ffprobe** for cuts and frames. `brew install ffmpeg` (macOS) / `apt install ffmpeg` (Ubuntu). Validated on ffmpeg 8.0.
+- **OPENAI_API_KEY**: `gpt-5.6-luna` for vision locate/review and text planning (vision model must accept images); or `OPENROUTER_API_KEY` fallback via OpenRouter.
+
+### Adapt / extend
+
+#### Model / provider
+
+All via env (`env.example`); no code change:
+
+- `TEXT_MODEL` (default `gpt-5.6-luna`).
+- `VISION_MODEL` must support images (default `gpt-5.6-luna`).
+- `OPENAI_BASE_URL` + matching `OPENAI_API_KEY` for compatible endpoints.
+
+```bash
+export OPENAI_BASE_URL=https://your-gateway.example.com/v1
+export VISION_MODEL=gpt-5.6-luna
+export TEXT_MODEL=gpt-5.6-luna
+```
+
+`agents.py` `OpenAI()` client reads these lazily via `client()`.
+
+#### Own input video
+
+`make_test_video.py` builds a 54s video with 4 distinct scenes (HIKING green / SURFING blue / SKIING white / CYCLING orange) plus large scene-name and timecode watermarks for Vision reproducibility.
+
+Own video: `python demo.py -i your.mp4 -o out.mp4 "edit request"` (skips test generation; no ground-truth error print).
+
+#### Blender vs ffmpeg (edit backends)
+
+Book uses **Blender Python API (bpy)** on the VSE. First-class here: `blender_editor.generate_bpy_script()` emits real bpy (`new_movie`, frame offsets, `TEXT`/`SPEED` effects, render); `render_with_blender()` runs `blender --background --python edit.py`.
+
+- `--backend blender`: force Blender (`blender --version` required);
+- `--backend ffmpeg`: force ffmpeg;
+- `--backend auto` (default): bpy if Blender installed, else ffmpeg.
+
+**Always**: Proposer’s bpy script is written to `output/edit_round*.py` (`output/edit.py` under `--smoke`)—core “generate Blender Python API code” artifact. This environment may not have Blender, so render is validated with ffmpeg; bpy is `py_compile`-checked but **not rendered in real Blender** unless you install it and use `--backend blender`.
+
+| | ffmpeg | Blender (bpy) |
+| --- | --- | --- |
+| Fit | 2D cut/join/subtitle/speed pipelines | 3D scenes, compositing, keyframe anim, particles/camera |
+| Ops | single binary, no GUI, CI-friendly | full Blender install; larger/slower |
+| When | most “cut a clip + simple effects” | only when 3D/compositing/complex transitions needed |
+
+Two-step Vision + Proposer–Reviewer is decoupled from the execution layer; same edit plan for both backends.
+
+### Files
+
+| File | Role |
+| --- | --- |
+| `demo.py` | CLI orchestration, self-check, iteration, token stats |
+| `agents.py` | `VideoAnalyzerAgent` / `ProposerAgent` / `ReviewerAgent` |
+| `blender_editor.py` | **bpy script gen + headless render** (book path) |
+| `video_editor.py` | `apply_edit()`; Blender/ffmpeg backends |
+| `make_test_video.py` | Procedural 4-scene test video |
+| `ffmpeg_utils.py` | Thin ffmpeg/ffprobe wrappers |
+
+`output/` is gitignored.
+
+### Limitations
+
+- Locate accuracy depends on visual distinctness; gradual scene transitions increase boundary error vs solid-color test film.
+- Fine step fixed at 1s → boundary precision about ±1s (book acceptance ±3s).
+- Slow-mo audio uses `atempo`; extreme ratios hurt quality; complex transitions/multi-track not covered.
+- Reviewer samples only start/mid/end; mid-clip glitches can be missed (raise sample density if needed).
+
+---
+
+## 中文
+
+### 目的
+
+用户给一段含多个场景的视频 + 一句自然语言需求（如"把冲浪部分剪出来"），Agent 自动定位目标场景、**生成 Blender Python API 脚本**剪出片段并自我审查。
+
+验证三个核心机制在多媒体处理中的作用：
+
+1. **两步 Vision 定位**：Proposer 无法直接"看懂"视频，于是委托一个**视频分析子 Agent**，
+   用 ffmpeg 抽帧 + Vision LLM 读图来定位目标场景的时间边界。
+2. **代码生成（Blender Python API）**：Proposer 把剪辑计划翻译成一段调用 **Blender
+   Python API（bpy）** 的脚本——导入 / 裁剪 / 字幕 / 变速 / 渲染各对应一个 API 调用，
+   用 `blender --background --python edit.py` 无头执行。这正是书中"把视频编辑重构为
+   API 调用和代码生成问题"的落地。未装 Blender 时脚本照常生成（代码生成产物），
+   实际渲染回退到 ffmpeg（见下文"剪辑后端"）。
+3. **提议者-审核者（Proposer / Reviewer）**：Proposer 剪辑后无法自证效果，
+   由 Reviewer 抽取成片关键帧、用 Vision LLM 检查是否剪对，不合格则反馈、迭代。
+
+### 两步定位原理
+
+Vision LLM 逐帧扫全片既慢又贵，因此采用"先粗后细"：
+
+- **第一步（粗粒度）**：每 **10 秒**抽一帧，把全片的稀疏截图连同"要找哪个场景"一起
+  交给 Vision，得到大致区间（如"冲浪在 20–30s"）。
+- **第二步（细粒度）**：在粗区间上下各外扩一个粗间隔，每 **1 秒**抽一帧，
+  再问 Vision 精确边界（如"15–29s"）。
+
+把这套抽帧-读图封装成**独立子 Agent**：几十张截图只进入子 Agent 的一次性上下文，
+不会污染主 Agent（Proposer/Reviewer）的对话历史。demo 末尾会打印两者的 token 对比。
+
+### 提议者-审核者
+
+```
+NL 需求 ──► Proposer 解析意图（目标场景 + 特效）
+              │
+              ▼
+         视频分析子 Agent 两步定位 ──► [start, end]
+              │
+              ▼
+         Proposer 生成 Blender bpy 脚本（edit.py）──► 渲染剪辑（可加字幕/慢动作）
+              │                                        装了 Blender 用 bpy，否则回退 ffmpeg
+              ▼
+         Reviewer 抽首/中/尾关键帧 ──► Vision 检查 pass/fail + 反馈
+              │pass?  否 → Proposer 据反馈修正边界，重剪（最多 3 轮）
+              ▼是
+           输出成片 final.mp4
+```
+
+### 运行
+
+```bash
+# 在仓库根目录使用统一的第 5 章环境
+uv sync --locked --python 3.12 --extra ch5
+
+# 切换目录前先激活环境：
+# macOS/Linux：
+source .venv/bin/activate
+# Windows PowerShell：.\.venv\Scripts\Activate.ps1
+# Windows cmd：.venv\Scripts\activate.bat
+
+# 未安装 uv 时可用 pip 兜底：
+# python -m pip install -e ".[ch5]"
+
+cd chapter5/video-edit
+
+# 迁移期间仍支持单项目兼容路径：
+# python -m pip install -r requirements.txt
+
+cp env.example .env        # 填入 OPENAI_API_KEY（未配置时设 OPENROUTER_API_KEY 自动改走 OpenRouter）
+python demo.py             # 默认需求"把冲浪的部分剪出来"（完整流程）
+python demo.py "把滑雪部分剪出来，并加上字幕 Winter"   # 自定义需求
+python demo.py -i my.mp4 -o out.mp4 "把演讲开场剪出来"  # 用自己的视频 + 自定义输出
+python demo.py --backend blender   # 强制用 Blender Python API 无头渲染（需装 Blender）
+python demo.py --vision-model gpt-5.6-luna  # 覆盖模型（也可用 --text-model）
+python demo.py --quick     # 快速模式：粗采样 + 单轮审查，Vision 调用最少（省时省钱）
+python demo.py --smoke     # 冒烟自检：仅剪辑链路 + 生成 bpy 脚本，不调用任何 API
+python demo.py --help      # 查看全部参数
+```
+
+常用参数（完整见 `--help`）：`--input/-i` 输入视频、`--output/-o` 成片路径、
+`--backend {auto,blender,ffmpeg}` 剪辑后端、`--text-model`/`--vision-model` 覆盖模型。
+
+一条命令即可跑通：生成/读取视频 → 两步定位 → 生成 bpy 脚本剪辑 → 审查 → 输出成片。
+每次运行都会清空 `output/`，从干净状态开始（幂等可重复）。完整流程会多次调用
+Vision 模型（较慢/耗费额度）；只想验证链路时先跑 `--smoke`（零 API），或用 `--quick`。
+
+### 预期输出示例
+
+#### `--smoke`（零 API，可复现）
+
+以下为 `python demo.py --smoke` 的**真实输出**（无需 OpenAI Key，仅需 ffmpeg）：
+
+```text
+==========================================================================
+  冒烟自检 | 剪辑链路 + bpy 脚本生成，不调用任何 API
+==========================================================================
+[1/3] 生成测试视频 OK：output/source.mp4（场景真值={'hiking': (0, 15), 'surfing': (15, 30), 'skiing': (30, 42), 'cycling': (42, 54)}）
+[2/3] 抽帧 OK：output/frames/smoke.png
+[3/3] 剪辑+字幕 OK（后端=ffmpeg（未装 Blender，回退））：
+  文件: smoke_cut.mp4
+  时长: 5.03s
+  容器: mov,mp4,m4a,3gp,3g2,mj2
+  大小: 121.4 KB
+  视频流: h264 1280x720 @ 30/1 fps
+  音频流: aac 44100Hz 1ch
+
+已生成 Proposer 的 Blender 脚本：output/edit.py
+（这正是书中'生成 Blender Python API 代码'的产物；装好 Blender 后可直接
+ `blender --background --python output/edit.py` 无头渲染。）
+
+✓ 冒烟自检通过：剪辑链路正常 + bpy 脚本已生成（未调用 OpenAI）。
+```
+
+生成的 `output/edit.py` 是一段**可执行的 Blender bpy 脚本**（`new_movie` 导入、
+`frame_offset_start`/`frame_final_duration` 裁剪、`new_effect(type='TEXT')` 字幕、
+`bpy.ops.render.render` 渲染），本机对其做过 `py_compile` 语法校验。
+
+#### `--quick`（完整链路，需 API）
+
+以下为 `python demo.py --quick`（默认需求"把冲浪的部分剪出来"）的真实节选（定位/误差/
+token 部分与剪辑后端无关，故不受 bpy/ffmpeg 后端切换影响）：
+
+```text
+步骤 1 | Proposer 解析自然语言需求
+解析结果：目标场景='surfing scene'  特效=[]
+
+步骤 2 | 视频分析子 Agent：两步 Vision 定位（--quick 快速采样）
+  [粗粒度] 每 15s 采样 5 帧 → Vision 得区间 [15, 30]s（依据：The word 'SURFING' appears at t=15s and changes at t=30s.）
+  [细粒度] 窗口 [0.0, 45.0] 内每 2s 采样 23 帧 → 精确边界 [16.0, 28.0]s
+  >>> 最终定位：起 16.0s  止 28.0s
+  真值 [15, 30]s → 起点误差 1.0s，终点误差 2.0s（验收要求 ≤ 3s）
+
+步骤 3-4 | Proposer 剪辑 + Reviewer 审查（迭代）
+  Proposer 剪出片段 [16.0, 28.0]s，成片时长 12.0s
+  Reviewer：pass=... score=... 检查帧=['0.5', '6.0', '11.5']
+
+Token 统计（子 Agent 隔离截图，主上下文不被污染）
+  主 Agent（Proposer+Reviewer）：573 tokens
+  子 Agent（两步定位截图）    ：2934 tokens
+```
+
+产物（`output/` 目录，真实文件）：
+
+| 文件 | 时长 | 说明 |
+| --- | --- | --- |
+| `source.mp4` | 54.0s | 程序化生成的 4 场景测试原片 |
+| `edit_round1.py` | — | Proposer 生成的 Blender bpy 脚本（代码生成产物，可换机执行） |
+| `cut_round1.mp4` | 12.0s | 第 1 轮剪出的候选片段 |
+| `final.mp4` | 12.0s | 采用的成片（H.264 + AAC，1280x720@30fps） |
+
+Token 统计印证了核心结论：几十张截图（2934 tokens）只进入**子 Agent**的一次性
+上下文，主 Agent 的对话历史（573 tokens）几乎不受截图污染。
+（注：合成测试片仅显示"SURFING"字样而非真实冲浪画面，Reviewer 有时会据此判为
+不通过——这正是审核者按画面内容如实反馈的体现；换真实视频即无此现象。）
+
+### 依赖
+
+- **ffmpeg / ffprobe**：本机实际剪辑与抽帧。`brew install ffmpeg`（macOS）/
+  `apt install ffmpeg`（Ubuntu）。本项目在 ffmpeg 8.0 上验证通过。
+- **OPENAI_API_KEY**：用 `gpt-5.6-luna` 做视觉定位/审查与文本规划（视觉模型须支持图像输入）；未配置时用 `OPENROUTER_API_KEY` 兜底，自动改走 OpenRouter。
+
+### 如何适配 / 扩展
+
+#### 换模型 / 供应商
+
+模型与端点全部通过**环境变量**注入（见 `env.example`），无需改代码：
+
+- `TEXT_MODEL`：规划/边界修正的文本模型（默认 `gpt-5.6-luna`）。
+- `VISION_MODEL`：定位/审查的视觉模型，**必须支持图像输入**（默认 `gpt-5.6-luna`）。
+- `OPENAI_BASE_URL`：换成任何兼容 OpenAI 协议的端点（自建代理、Azure OpenAI、
+  或其他厂商网关），配合对应的 `OPENAI_API_KEY` 即可。
+
+```bash
+export OPENAI_BASE_URL=https://your-gateway.example.com/v1
+export VISION_MODEL=gpt-5.6-luna       # 例：用当前廉价旗舰视觉模型
+export TEXT_MODEL=gpt-5.6-luna
+```
+
+`agents.py` 里的 `OpenAI()` 客户端会自动读取上述变量（`client()` 惰性初始化）。
+
+#### 换输入视频
+
+`make_test_video.py` 用 ffmpeg **程序化生成**一段 54s 的视频，含 4 个明显不同的场景
+（HIKING 绿 / SURFING 蓝 / SKIING 白 / CYCLING 橙），每段都叠加大号场景名与时间码水印，
+让 Vision 仅凭画面就能准确定位——便于复现验收。
+
+换成**你自己的真实视频**：直接 `python demo.py -i 你的.mp4 -o 输出.mp4 "剪辑需求"`
+即可（无需改代码）。此时跳过测试片生成，也不再打印定位误差（外部视频无真值）。
+
+#### Blender vs. ffmpeg（剪辑后端）
+
+书中原方案用 **Blender Python API（bpy）** 驱动视频序列编辑器（VSE）完成剪辑。
+本项目把它实现为**一等后端**：`blender_editor.generate_bpy_script()` 把剪辑计划翻译成
+一段真实可执行的 bpy 脚本（`new_movie` 导入、`frame_offset_start`/`frame_final_duration`
+裁剪、`new_effect(type='TEXT'/'SPEED')` 字幕/变速、`bpy.ops.render.render` 渲染），
+`render_with_blender()` 再用 `blender --background --python edit.py` 无头执行。
+
+- `--backend blender`：强制走 Blender（需 `blender --version` 可用）；
+- `--backend ffmpeg`：强制走 ffmpeg；
+- `--backend auto`（默认）：装了 Blender 用 bpy，否则回退 ffmpeg。
+
+**关键点：无论哪个后端，Proposer 生成的 bpy 脚本都会落盘到 `output/edit_round*.py`**
+（`--smoke` 下为 `output/edit.py`）——即"生成 Blender Python API 代码"这一核心产物，
+可人工核对、也可拷到装了 Blender 的机器上执行。本机未安装 Blender，故本仓库的实际
+渲染由 ffmpeg 完成并验证；bpy 脚本已通过 `py_compile` 语法校验，但**未在真实 Blender
+上跑过渲染**（装好 Blender 后即可用 `--backend blender` 端到端执行）。两种后端的取舍：
+
+| | ffmpeg | Blender（bpy） |
+| --- | --- | --- |
+| 定位 | 裁剪/拼接/字幕/变速等 2D 流水线 | 3D 场景、合成、关键帧动画、粒子/摄像机 |
+| 上手 | 单二进制、无 GUI、CI 友好 | 需装完整 Blender，体积大、渲染慢 |
+| 适用 | 绝大多数"剪一段 + 简单特效"需求 | 需要 3D 合成/复杂转场/图层混合时才值得 |
+
+核心的"两步 Vision 定位 + 提议者-审核者"与执行层解耦，两个后端共用同一份剪辑计划，
+`agents.py`/`demo.py` 无需为切换后端改动逻辑。
+
+### 文件
+
+| 文件 | 作用 |
+| --- | --- |
+| `demo.py` | 一条命令跑通的编排入口（CLI、启动自检、迭代循环、token 统计） |
+| `agents.py` | `VideoAnalyzerAgent`（两步定位）/ `ProposerAgent` / `ReviewerAgent` |
+| `blender_editor.py` | **Blender bpy 脚本生成 + 无头渲染**（书中原方案，核心实验点） |
+| `video_editor.py` | 剪辑执行层：`apply_edit()` 统一入口，调度 Blender/ffmpeg 双后端 |
+| `make_test_video.py` | 程序化生成含 4 个场景的测试视频 |
+| `ffmpeg_utils.py` | ffmpeg/ffprobe 薄封装（统一错误检查、抽帧、探测时长/流） |
+
+`output/`（生成的视频、截图、成片）已被 `.gitignore` 忽略，避免仓库膨胀。
+
+### 局限
+
+- 定位精度取决于场景在画面上的可辨识度；真实视频若场景过渡渐变，边界误差会大于纯色测试片。
+- 细粒度步长固定 1s，边界精度上限即 ±1s 量级（满足书中 ±3s 验收）。
+- 慢动作音频用 `atempo` 变速，倍率过大时音质下降；转场/多轨混音等复杂特效未覆盖。
+- Reviewer 仅抽首/中/尾三帧，长片段中段的偶发错误可能漏检（可调高抽帧密度）。
+
+---
+
+## Notes / 说明
+
+- Prefer `--smoke` then `--quick` before a full Vision run. / 完整 Vision 前先 `--smoke`，再 `--quick`。
+- Commands/code/paths/env vars are identical in both language sections. / 命令、代码、路径与环境变量在中英文两侧保持一致。