# 流程问题清单（首次手工解析 B 站视频的复盘）

> 来源：2026-10-20 手工解析《原始积累的5条建议》（BV1HWJa61E9M）全过程。
> 每条都写成「当时的现象 → 根因 → 现在的做法」，能固化的已经写进插件。

| # | 当时的问题 | 根因 | 现在怎么做 |
|---|---|---|---|
| 1 | `web_fetch` 抓 B 站链接直接 404 | 本机 DSH 的 fetch 接口配置不可用，且 B 站页面本身是 JS 壳 | 只走 B 站公开 JSON API（`/x/web-interface/view` 等），带 UA + Referer |
| 2 | 想直接拿官方字幕 / AI 总结 | 匿名请求字幕接口返回 0 条；AI 总结接口返回 `-101 账号未登录` | 放弃字幕幻想，直接下音轨做本地 ASR |
| 3 | `pip install` 卡住很久没输出 | 默认源 `files.pythonhosted.org` 慢 | 用国内镜像（阿里云 `mirrors.aliyun.com/pypi/simple`）+ `--no-cache-dir` + `--target` 装到独立目录，不污染 DSH 运行时 |
| 4 | 先想装 yt-dlp，安装又卡住 | 其实不需要它：`playurl` 接口直接给 m4a 音轨 | 彻底去掉 yt-dlp 依赖，少一个变量 |
| 5 | 模型从 hf-mirror 下载，单线程只有约 300KB/s；开 16 线程跑到 70% 触发 429 限流 | hf-mirror 按 IP 限速，多连接会被拒 | 模型改从 ModelScope 下载（实测约 9MB/s，461MB 约 1 分钟）；多线程下载遇到 429 要退避并支持断点续传 |
| 6 | 转写时报 `TypeError: open() got an unexpected keyword argument 'metadata_errors'` | faster-whisper 1.2.1 按旧版 PyAV 写的调用，装的 av 19.0.1 不支持该参数 | 不用它自带的解码：自己用 `av.open` 解成 16kHz 单声道 float32 ndarray，再传给 `model.transcribe` |
| 7 | 控制台中文全是乱码，看不到进度 | Windows 控制台默认 GBK，Python 输出按 UTF-8 | 所有产物文件统一 UTF-8；脚本 stdout 只输出一行 JSON（UTF-8），进度写 stderr |
| 8 | 前台跑长命令，180 秒后被工具挂到后台，流程被切得很碎 | shell 工具有默认超时 | 插件里用 Node `spawn` 管子进程，超时 60 分钟；一次调用跑完下载+转写 |
| 9 | 音频 URL 有时效，隔一会儿再下会失败 | B 站 DASH 地址带签名和过期时间，且必须带 Referer/UA | 拿到地址立即下载，headers 带 UA + Referer；失败自动换 backupUrl |
| 10 | 转写专名错得离谱：T-Bill→"TBU"、古董字画→"股安自化"、自住房→"资助房" | small 模型对低频词和数字不敏感 | `initial_prompt` 注入视频标题和领域术语；交付时明确标注「ASR 可能有误差，引用前复核」 |
| 11 | 写 md 时把 UP 主粉丝数写成 35 万，实际 23 万 | 凭印象填数字，没有现查 | 元数据一律从 API 现取并写进结果 JSON，禁止凭记忆写数据 |
| 12 | 第一版图有文字溢出和标点断行难看 | Pillow 手动画图不做排版检查 | 断行函数处理标点后处理 + 支持显式换行；生成后必须 `read_image` 看一眼再交付 |
| 13 | 「解析流程」和「内容总结」容易混成一张图 | 两种图信息类型不同（流程 vs 观点） | 拆成两张：流程图讲"怎么做的"，总结图讲"视频讲了什么" |
| 14 | 同一视频重复转写浪费 12 分钟 | 没有按视频缓存 | 按 BV 号缓存音频 + 转录 + 结果；重复请求秒回 |
| 15 | 用户不知道要等多久 | 长任务没有事先说明 | 工具描述里写清耗时预期（约视频时长 ×0.4）；脚本 stderr 打进度 |
| 16 | 依赖装在临时目录 `output/tmp`，换个工作区就没了 | 没有固定数据目录 | 模型和 python 依赖固定到 `~/.dsh/bili-video-summary`，与工作区解耦 |

## 下次开工前的检查清单

1. 确认工具可用：会话里能看到 `bili_video_transcribe` / `bili_video_render`（没有就重启 DSH）。
2. 先看缓存：同一 BV 号第二次调用是秒回的，不要加 `force`。
3. 长视频先跟用户说预计时间（例如 30 分钟视频约 12 分钟转写）。
4. 交付三件套：一图读懂 PNG + 解析 md + 转录 txt/srt，图片先 `read_image` 自查。
5. 引用数字/专名前对照原视频，拿不准就标注「以原视频为准」。
6. 不要把任何 token、cookie 写进插件或输出文件。