feat: doco P1 收尾(字幕裁切写死/dry-run/crop_params完善)

doco/README.md

@@ -18,11 +18,25 @@ Doco 将一期《军事科技》节目视频拆分为两路输入,供下游三
 
 ## 系统依赖
 
-- **Python >= 3.12**
-- **ffmpeg >= 4.x** (必须安装并加入 PATH)
-  - Windows 下载: https://ffmpeg.org/download.html
-  - macOS: `brew install ffmpeg`
-  - Linux: `apt install ffmpeg`
+### ffmpeg (必须)
+
+**Windows 用户:**
+1. 从 https://www.gyan.dev/ffmpeg/builds/ 下载 ffmpeg (建议用 essentials 版本)
+2. 解压到本地目录(如 `C:\ffmpeg`)
+3. 把 `C:\ffmpeg\bin` 加入系统 PATH
+4. 打开 cmd,验证: `ffmpeg -version`
+
+**Mac 用户:**
+```bash
+brew install ffmpeg
+```
+
+**Linux 用户:**
+```bash
+apt install ffmpeg
+```
+
+### Python >= 3.12
 
 ## 安装
 
@@ -50,20 +64,65 @@ Doco 使用三组独立凭证,互不混用:
 
 > 注意: 讯飞要用"录音文件转写标准版",不要用"大模型版"
 
-## P1 使用方法
+## 使用步骤(按顺序,不要跳步)
 
-### 准备素材目录
+### Step A. 安装 ffmpeg
 
-```
-programs/
-└── ep001_20260612_fangkong_fandao/
-    └── source/
-        └── video.mp4   ← 放入节目视频
+见上方"系统依赖"一节。安装后打开 cmd 验证 `ffmpeg -version` 能看到版本号。
+
+### Step B. 生成迷你测试视频(验证 ffmpeg 装好了)
+
+```bash
+ffmpeg -f lavfi -i testsrc=duration=5:size=320x240:rate=1 \
+       -f lavfi -i anullsrc=channel_layout=mono:sample_rate=16000 \
+       -c:v libx264 -c:a aac -shortest \
+       doco/tests/fixtures/mini_test.mp4 -y
 ```
 
-> video.mp4 由制片人放入,不放进 git
+出现 `mini_test.mp4` 文件即成功。
 
-### 运行拆分
+### Step C. 把 demo 视频放到指定位置
+
+```bash
+# 把 demo 视频文件复制到:
+programs/ep001_20260612_fangkong_fandao/source/video.mp4
+```
+
+> video.mp4 由制片人放入,不放进 git(已加入 .gitignore)
+
+### Step D. 配置凭证
+
+```bash
+cp doco/.env.example doco/.env
+# 用记事本或 VS Code 编辑 doco/.env,填入三组真实 API key
+```
+
+### Step E. 安装 doco 包
+
+```bash
+cd doco && pip install -e .
+```
+
+### Step F. 跑 dry-run(只裁切,不调 OCR API)
+
+**重要:先跑 dry-run,确认裁切框包住字幕后再跑正式版。**
+
+```bash
+doco split \
+  --episode-id ep001_20260612_fangkong_fandao \
+  --input-video programs/ep001_20260612_fangkong_fandao/source/video.mp4 \
+  --output-dir programs/ep001_20260612_fangkong_fandao/work/ \
+  --dry-run
+```
+
+**验收 dry-run 结果:**
+1. 检查 `work/frames/` 目录下的前 3-5 张关键帧小图
+2. 确认字幕被完整框住、没有切掉字
+3. 如果裁切位置不对,停下来反馈
+
+### Step G. 跑正式版(去掉 --dry-run)
+
+dry-run 验收通过后,跑正式版:
 
 ```bash
 doco split \
@@ -76,10 +135,10 @@ doco split \
 
 ```
 programs/ep001_20260612_fangkong_fandao/work/
-├── frames/                # 抽出的所有帧(临时)
+├── frames/                # 抽出的帧(临时)
 ├── audio_16k.wav          # 音频(16kHz/单声道/16bit)
 ├── b_manuscript.txt       # B 稿([Nm Ns] 句子格式)
-└── keyframes.json         # 关键帧索引
+└── keyframes.json         # 关键帧索引(含裁切参数)
 ```
 
 ## P1 验收标准
@@ -101,7 +160,7 @@ doco/
 ├── tests/
 │   ├── test_video_split.py # 单元测试
 │   └── fixtures/
-│       └── mini_test.mp4   # 迷你测试视频
+│       └── mini_test.mp4   # 迷你测试视频(需 Step B 生成)
 ├── docs/
 ├── .env.example            # 凭证模板
 ├── README.md