ai-kefu-38k 全程复盘报告
状态：报告所列全部项已当日落地并验证（见第六节）。
范围：本片从动效审计 → BGM 重做 → 渲染性能追查 → PiP 修复 → 发布的完整周期。
产出：SKILL 问题 7 条（2 条已修）· HF 官方文档对照 6 项 · Pipeline 优化 8 项分级。2026-07-04。
一、本轮踩坑地图（复盘素材）
| 事件 | 损失 | 根因 | 谁发现 |
|---|
| PiP 在所有 mock/UI 段全灭 + 02:06 黑屏 | 整轮重渲 seg0-5 | stacking context 陷阱 + 子挂载 id 重复 | 用户（审计/validate/自审全漏） |
| 渲染莫名慢 2.4-5 倍 | ~40min 排查 | 帧缓存在机械盘，页缓存被大文件传输冲掉 | 用户先质疑 |
| 补卡文案写错重来 | ~15min | 项目里 asr/（旧）与 asr_fast/（权威）双源并存，查错了源 | 自查 |
| kill 流水线连锁杀掉渲染中的 seg0（66%） | ~4min 白渲 | exit 144 连锁坑第二次踩 | 自查 |
| 35 条审计 JSON 差点随 compact 丢失 | 从 transcript 抢救 | 子代理产出只在对话里未落盘 | 自查 |
| 封面脚本 --frame-time 参数不存在 | ~2min | SKILL 示例与脚本漂移 | 自查 |
| Suno「Bonobo influence」被拒 | 1 次重交 | Suno 禁艺人名（新知识） | API 报错 |
二、SKILL 问题清单
✅ 已修 1 §4.1 封面示例含不存在的 --frame-time 参数
SKILL 示例与脚本实际参数漂移。已改为「脚本固定取第一帧，关键帧先 ffmpeg 切 1s 小片」。
深层问题：SKILL 里的命令示例没有「从 --help 验证」的机制，脚本演进后示例静默失效。建议规矩：改脚本参数时必须同步 grep SKILL 中该脚本名。
✅ 已修 2 §3.3「缓存放外挂盘」指引已被本轮推翻
旧结论只考虑容量没考虑 IO。已改为「必放 NVMe，归档冷缓存才放外挂盘」+ 命令模板路径更新。
⛔ 待拍板 3（最重要） §3.4 自审 Gate 缺「分层可见性抽查」
PiP 全灭这种「层级级」bug，现有三道防线全部漏掉：35 条动效审计只盯卡片时序、validate 只查 console error、我自审只抽了改动点位的帧。用户看第一遍就发现了。
建议 Gate 增项：每次渲染批次后，按 broll_data 的窗口类型各抽 1 帧（pip 窗 / mock 窗 / evcard 窗 / 无窗底片），逐帧核对「该在的层都在」：PiP 小窗、mock 内容、字幕、卡片。约 5 帧 2 分钟，能挡住这类整层缺失。
⚠️ 待拍板 4 ASR 双源并存无权威标注
asr/（旧剪辑版）与 asr_fast/（权威）同时存在且内容完全不同，本轮我查空窗用错源写错两张补卡文案。建议铁律：一个项目只留一个 ASR 目录；产生新版时旧目录立即改名 asr_deprecated_YYYYMMDD/ 或删除。
⚠️ 待拍板 5 子代理产出必须当场落盘
5 组审计代理的 35 条 JSON 只存在于对话上下文，compact 后差点全丢（靠 transcript 抢救回来）。建议 §0.6/§Q 加一条：子代理回报的结构化产出（审计/调研/清单）收到后第一动作写入项目文件，再开始消费。
⚠️ 待拍板 6 停流水线的标准姿势缺失（exit 144 二次踩）
kill 包装 shell 连锁杀掉渲染中的 hyperframes。建议 §3.2 写死：停流水线 = 先 kill 最外层 wrapper PID，让渲染中的段自然跑完收产物；绝不 kill 多个 PID 或 pkill 模式串；确需全停用 kill -- -PGID 一次性处理进程组。
✅ 顺带已修 7 §3.3 渲染时长预估过时：「14-30 min」→ 已补三档实测 + NVMe 下 856s 全片 ~10min。
三、HyperFrames 官方文档对照发现
| 项 | 官方事实 | 对我们的意义 |
|---|
| quality 档位 | draft=CRF28/ultrafast · standard=CRF18/medium · high=CRF15/slow | 我们 seg 渲 standard(18) 后 concat 又重编 CRF16 = 双代损失（见 P0-1） |
| workers 默认 | 半核 cap 4；每 worker ~256MB 独立 Chrome | -w 6 合理略高于官方保守值；auto 校准结果也是 6 |
| 并发建议 | 32 核官方建议 5-6 路并发（producer server 表） | 我们只试了 3 路；NVMe 下可再测 5 路（P1-3） |
| producer server | POST /render + FIFO 信号量 + SSE 队列事件，专为 agent 编排设计 | bash 并发已够用，server 模式收益小（P2） |
| benchmark 命令 | npx hyperframes benchmark 跑多组合报时 | 值得一次性跑完沉淀本机最优（P1-5） |
| video-frame-format | UI 录屏/色彩敏感源用 png 提取 | 我们源是相机拍摄，auto(jpg) 正确，无需动 |
四、Pipeline 优化清单（分级）
P0 · 必须改
1. 消灭 concat 双重编码 → 零重编 copy 拼接
现状链：seg(CRF18 一代) → concat trim+重编 CRF16（二代 · ~10min · 643M 中间文件）→ mux copy。
本轮实测：7 段中 5 段已帧精确，seg4/seg6 各多恰好 1 帧——根因是 DURS 浮点写法（110.6667×30=3320.001 被 ceil 成 3321 帧）。
改法：build_full/concat 的段长全部改用整数帧数表达（dur=帧数/30 全精度），渲染产物即帧精确 → concat 直接 -c copy。收益：省 ~10 分钟 + 消除一代质量损失 + 少写 643M。
2. 渲染 Gate 补「分层可见性抽查」（= SKILL 问题 3，同一件事，流程侧落地）
P1 · 建议做
3. 并发 3 → 5 实测：官方 32 核建议 5-6；本轮 NVMe 3 并发 53 帧/s 时 CPU/GPU 仍有富余。预期全片再快 30-50%（→ ~6-7min）。需验证 beginFrame 模式 5 路不降级。
4. 终版编码链改 seg=high(CRF15) + concat copy：P0-1 落地后，成片质量链变成单代 CRF15（当前是 18+16 两代），文件略大但发布平台二压后观感更稳。
5. 跑一次 npx hyperframes benchmark 沉淀本机最优 workers/quality 组合进 SKILL。
6. ASR 目录唯一化（= SKILL 问题 4）。
P2 · 可选
7. producer server 常驻模式：SSE 进度 + 队列适合多片并行生产期再上，单片流水线 bash 并发已够。
8. Docker 渲染：需要跨机一致性（如云渲染/多机协作）时再引入，本机 GPU 快路径当前正确。
五、本轮性能数据存档
| 配置 | 聚合捕获速度 | 856s 全片预估 |
|---|
| HDD 冷读 · 3 并发 | 11.6 帧/s | ~37 min（实测） |
| HDD 页缓存热 · 串行 | 17.6 帧/s | ~22 min（实测） |
| NVMe · 3 并发 | 53 帧/s | ~11 min（实测） |
| NVMe · 5 并发（P1 待测） | 预估 70-85 帧/s | 预估 ~7 min |
| + concat copy（P0 待做） | — | 再省 ~10 min 重编 → 全链路 ~8 min 可期 |
诊断口诀（已入 SKILL §3.3）：渲染慢但 GPU/CPU 都闲 → iostat -x 看缓存盘 %util → HDD 打满 = IO bound，迁 NVMe。
六、落地验证结果（2026-07-04 当日全部执行完）
| 项 | 状态 | 验证数据 |
|---|
| SKILL 7 条修复 | ✅ 全部落地 | §3.4 分层可见性 Gate · §1.4 ASR 唯一化 · §0.6 子代理落盘 · §3.3 停流水线姿势 + 缓存/时长更新 · §4.1 示例修正 |
| 项目 asr/ 双源 | ✅ 已改名 | asr_deprecated_20260704/ · 代码零引用确认 |
| P0-1 concat 零重编 | ✅ 验证通过 | data-duration 改 (帧数-0.5)/30 → 7 段全帧精确 → -c copy 秒级完成（1573x），总长精确 856.600（旧链路多 2 帧也修掉） |
| P1-3 并发 5 实测 | ❌ 劣化 · 回退 3 | 5 并发聚合 ~40 帧/s < 3 并发 53 帧/s（30 workers 资源竞争）——官方"32核5-6路"在重媒体场景不成立 |
| P1-4 high 档终版链 | ✅ 验证通过 | v9 全链 11 min 出 CRF15 单代成片（编码比 standard 多 2-3 min） |
| P1-5 官方 benchmark | ⚠️ 放弃 | 工具会拿当前项目全片跑 15 次完整渲染（数小时代价），且 --ignore-scripts 安装无捆绑 Chromium 导致其子任务起不来；真实生产数据（三档缓存+并发对比）已足够 |
| 定版配方 | ✅ 固化 | render_pipeline.sh [quality]：迭代 standard ~8.5min / 终版 high ~11min · 均 3 并发 + concat copy |
七、一句话总结
本轮最大的教训不是技术坑本身，而是三道质检防线对「整层缺失」类 bug 全盲（审计盯时序、validate 盯报错、自审盯改动点）——分层可见性抽查这个 Gate 必须补上。最大的收益是渲染管线从「玄学慢」变成「确定性快」：IO 瓶颈定位方法 + NVMe 缓存 + 并行配方都已沉淀，下一片直接受益。