tps-dashboard/doco/note/doco_handoff_to_next_chat.md

# Doco 子项目续接快照 · 交接给下一轮 Opus 顾问

> 起草:Opus 4.7 顾问(算力即将耗尽)
> 日期:2026-06-12
> 给:接手本对话的下一个 Opus 实例
> 用户:制片人刘通(《军事科技》栏目 TPS 中台主理人)

---

## 一、先看哪些文件(读完这几份再接话)

主 project 知识库里这几份**必读**:

1. `Claude协作原则.md` — 跟制片人说话的规矩(简体中文、说人话、不堆叠技术语言、Cline 指令要代码块、宪法第 3 条不架空 Cline 的 Plan 模式)
2. `Doco子项目_Brief.md` — Doco 子项目宪法,红线全在这
3. `doco_project_design.md` — Doco 算法层设计(P3 阶段才用,但先了解全貌)
4. `主project对Doco_PRDv2的回复.md` — 主项目顾问对 5 个问题的批复
5. `跨子项目协作规则.md` — PRD 版本管理

---

## 二、当前进度坐标

- **阶段**:Doco P1(视频双路拆分预处理)
- **节点**:dry-run 调试,**核心 bug 未解决,不能进入 OCR 阶段**
- **git 状态**:多个 commit 已推 origin/main,按宪法直接推 main 不开分支

P1 任务回顾:
- 输入:一期节目视频(黑底白字字幕,干净人声)+ A 稿
- 输出:B 稿 txt + audio_16k.wav + keyframes.json
- 流程:ffmpeg 抽帧(1fps,crop 到下方 20%全宽)→ 空白帧过滤 → dHash+IoU 去重 → 关键帧 → (OCR)→ B 稿

---

## 三、当前 bug 状态(最重要)

### 已确认未修复的核心 bug

**`is_blank_frame()` 读取的图像 ≠ `frames/` 目录里最终保存的图像**

证据链:
1. 制片人上传 `frame_0008.png`(从 frames/ 直接复制)
2. Opus 用 Python 实测:整张图 414720 像素**全部为 0**(`arr.max() == 0`)
3. CSV 报告 frame_8:`max_brightness=255, white_pixel_ratio=0.0124`
4. **两者无法同时为真** → 检测时读的不是这张图

最新 dry-run 自检也证实了这点:
```
[WARNING] 自检失败: frame_0938.png 像素数据与 CSV 不一致!
  CSV:    max_brightness=255, white_ratio=0.007603
  实际重读: max_brightness=255, white_ratio=0.022852
[error] 已中止
```

### Cline 已经修了但没修对的事

Cline 把这个 bug 解释成"CSV 列写入顺序错位",但**那只是表层**——
列对齐改完后,frame_8 的 CSV 数据 `max_brightness=255、white_ratio=0.0124` 仍然跟"全 0 像素"对不上。

Cline 已修复(列错位)是真问题,但**根本原因没找到**。

### 推测根因(交接给你)

很可能 video_split.py 的抽帧流程是分两步,而不是 ffmpeg 一步搞定:
- ffmpeg 把帧抽到某临时目录(可能是全尺寸 1920×1080,**没**裁切)
- Python 用 PIL 后裁切到 1920×216 再存到 frames/
- `is_blank_frame()` 读的是裁切前的临时全画面(里面有节目画面有亮像素 → max=255)
- `frames/` 里是裁切后的小图(字幕区域纯黑 → 像素全 0)

但这只是**推测**,你应该让 Cline 自查代码确认。

---

## 四、下一步建议指令(给你参考,可调整)

发给 Cline 的 ACT 模式指令,大致这样:

```
[ACT 模式]

P1 dry-run 自检揪出严重 bug:is_blank_frame() 读的图 ≠ frames/ 里保存的图。

证据:
1. 制片人确认 frame_0008.png 是全 0 纯黑(Python 实测 arr.max()=0)
2. CSV 仍报告 max_brightness=255, white_ratio=0.0124
3. dry-run 自检也确认 frame_0938.png 数据不一致

上次"列错位"修复是真 bug 但不是这次的根因,这是另一个独立的 bug。

请逐行排查 video_split.py 的抽帧流程,回答以下问题(在汇报里贴具体代码):

1. ffmpeg 命令是什么?是否真的有 vf "fps=1,crop=iw:ih*0.2:0:ih*0.8" 过滤器?
2. ffmpeg 输出到哪个目录?
3. is_blank_frame() 接收的 image_path 是哪个目录?
4. compute_hash() / compute_binary_matrix() 接收的 image_path 是哪个目录?
5. 最终保存到 frames/ 的图,是从哪里来的?

如果发现某个判断函数读了"非 frames/ 里的图",修复方法:
- 选项 A:让 ffmpeg 用 vf crop 直接输出裁切后的小图到 frames/,
  所有判断函数都从 frames/ 读(单一数据源)
- 选项 B:保持当前流程,但把所有判断函数的 image_path 改为 frames/ 里的路径

修复后重新跑 dry-run,自检通过 + 制片人验证 frames/ 里没纯黑帧才算成功。

不要再加新功能,这次只修这一个 bug。
```

---

## 五、协作风格备忘

- **制片人不懂代码**,你要"说人话",不堆叠 Python 术语
- **简明扼要**,他明确要求不要解释中间过程
- **给 Cline 的指令一律用 ``` 代码块封装**,方便他复制粘贴
- **明确标 ACT 或 Plan 模式**——前几轮制片人提醒过这点
- 不要架空 Cline 的 Plan 模式(宪法第 3 条),但小 bug 修复可以直接 ACT
- 制片人现在的疲劳度比较高(连续 dry-run 多轮),回复要紧凑,不要长篇大论
- 制片人的 git 工作流:直接推 main 不开分支(宪法规定)

---

## 六、关键决策(已锁,不能动)

| 项 | 值 |
|---|---|
| 字幕裁切区域 | `crop=iw:ih*0.2:0:ih*0.8`(全宽 × 下方 20%),写死,栏目全年 52 期一致 |
| 抽帧密度 | 1fps |
| 哈希算法 | dHash 默认,阈值 5 |
| IoU 保底阈值 | 0.95 |
| 空白帧双条件 | `max_brightness >= 240` AND `white_pixel_ratio >= 0.005` |
| 凭证管理 | doco 自管 `doco/.env`,主仓库根 `docs/api_credentials_inventory.md` 只记元信息 |
| OCR 提供方 | DeepSeek Vision API(P1 dry-run 阶段还没正式调用) |
| ASR 提供方 | 讯飞录音文件转写标准版(P2 才用) |
| AI 融合层 | Claude Sonnet 4.6(P3 才用) |
| 不引入 ffmpeg-python wrapper | subprocess 调系统 ffmpeg |
| Git workflow | 按宪法直接推 main |

---

## 七、环境信息

- Windows + Python 3.12.10 + `.venv`(主项目共享虚拟环境)
- VS Code + Cline 插件
- 仓库根目录:`E:\tps-dashboard\`
- 主仓库:`simonkoson/tps-dashboard`(自部署 git,localhost:3000)
- ffmpeg:已通过 winget 安装,系统 PATH
- demo 视频:`programs/ep001_20260612_fangkong_fandao/source/video.mp4`(《现代防空反导大对决》26 分钟)

doco 子模块目录结构(已建好):
```
doco/
├── src/
│   └── doco/                  ← src layout 的包目录
│       ├── __init__.py
│       ├── cli.py
│       ├── video_split.py     ← 当前 bug 在这
│       ├── asr_adapter.py     ← P2 用
│       └── ocr_adapter.py     ← P2 用
├── tests/
│   ├── test_video_split.py
│   └── fixtures/
│       └── mini_test.mp4
├── .env.example
├── .env(本地,不进 git)
├── pyproject.toml
└── README.md
```

---

## 八、踩过的坑(不要重蹈)

1. **Python 包配置 src layout**:Cline 第一次配置时忘了在 src/ 下建 doco/ 子目录,导致 `doco --help` 报 `ModuleNotFoundError`。后来 git mv 文件到 src/doco/ 下才好。
2. **系统 Python vs .venv**:制片人第一次 `pip install -e doco/` 装到了系统 Python 3.12,而不是 .venv 里。VS Code 重启后 .venv 自动激活,需要在 .venv 里重装。
3. **VS Code 工作目录**:必须打开 `E:\tps-dashboard\`(仓库根目录),不能打开 `docs\` 子目录,否则 Cline 看不到 .clinerules 和其他子模块。
4. **ffmpeg PATH 不生效**:winget 装完 ffmpeg 后,旧的 VS Code 终端 PATH 还是旧的,要完全关闭 VS Code 重开。
5. **Cline 的命令示例有错**:Cline 多次给的命令示例是错的(用 `python -m doco.src.doco.cli` + `split-video` 子命令),正确命令是 `doco split --episode-id XXX --input-video XXX --output-dir XXX [--dry-run]`。
6. **frames/ 目录的语义**:Cline 第一次实现把 1620 张原始抽帧全部保留在 frames/,让制片人误以为"筛选没生效"。后来改为只保留最终关键帧。
7. **pHash 阈值**:dHash 阈值 5,pHash 阈值 2,IoU 阈值 0.95——这些是实测调好的,不要再动。
8. **CSV 列对齐**:Cline 加列时只改 header 没改写入顺序导致全部错位。这次修复了,但**不是核心 bug**。

---

## 九、最新一次 dry-run 的统计(自检失败那次)

```
[stats] 原始抽帧: 1620 张
[stats] 空白帧过滤后: 1393 张 (筛掉 227 张纯黑)
[stats] pHash/dHash 去重后(IoU保底): 308 张 (筛掉 0 张IoU相同 + 0 张哈希相同)  ← 统计 bug 还在
[stats] 最终关键帧: 308 张
[debug] frames/ 目录实际文件数: 308 (预期: 308)
[WARNING] 自检失败: frame_0938.png 像素数据与 CSV 不一致!
[error] 已中止
```

注意:
- "筛掉 0 张IoU相同 + 0 张哈希相同" 这个统计还是 0,说明**之前那个 stats 计数 bug 也没真正修好**——或者是这次新加的双条件改变了流程,导致 IoU/hash 没被触发(走了空白帧分支?)。需要复查。

最近的 commit(按时间倒序):
1. Cline 双条件 + 自检 + 测试 + CSV 列对齐
2. Cline numpy 加速 + CLI 参数
3. Cline IoU 保底 + dHash + 诊断 CSV
4. Cline 第一次修空白帧检测(用 brightness=200,后来发现不够,改 240)
5. Cline 加 crop 写死 + dry-run flag
6. Cline 初始化 doco 子项目 P1

---

## 十、给下一个 Opus 的最后嘱托

- 这个 bug 排查过两轮了(Cline 都没真正定位到),所以这次**让 Cline 自查代码并贴出关键函数的实际代码**,不要轻信他的口头解释
- 制片人有耐心,但已经累了,你接手后**第一句话就给方案,不要重复诊断**
- 修完这个 bug 后,P1 dry-run 应该能通过自检,接下来就是填 DeepSeek API key 跑正式 OCR(去掉 --dry-run)
- 如果 dry-run 通过,P1 就算完工,可以进入 P2(讯飞 ASR 集成)

祝接力顺利。