/video-review
一次審閱循環:收集整批意見,按影片彙整,同時修復所有有問題的影片,自行檢查每個結果,交付下一個版本,並產出報告。
為何採用批次與平行處理:在這些技能所屬的生產環境中,曾經有三條意見間隔五分鐘到達,代理程式便在其自身上下文中開始修復第一條。上下文填滿後,審閱者不得不中止它,並表示逐一處理意見的方式沒有效率。合併成一個表格後交由三個平行子代理處理,同樣的三項修復在 70 分鐘後完成審閱與交付。修復從來不只是重新渲染:編輯、旁白、渲染、品質檢查和報告每部影片需要 50 到 90 分鐘,因此序列化修復會導致時間倍增。
0. 設定
PVS_HOME="$(cd "$(cd "${CLAUDE_SKILL_DIR}" && pwd -P)/../.." && pwd)"
PY="$PVS_HOME/bin/pvs-py"
找到產品(目前目錄上層最近的 product.yaml),並列出所有影片及其當前版本與交付狀態(對每部影片執行 skills/video-build/scripts/stages.py)。
1. 取得整批意見
如果引數是檔案,則讀取檔案;如果是文字,則使用該文字。然後確認一次:「這是此輪所有影片的全部意見回饋嗎?沒有意見的影片保持原樣。」在修復任何內容之前等待回答。如果在彙整時意見持續到達,請將其加入同一輪;不要為每條訊息啟動一次修復。
2. 將意見合併成每部影片一份表格
"$PY" "$PVS_HOME/skills/video-review/scripts/feedback_table.py" <product_dir> <notes file or -> \
--out <product_dir>/reviews/round-<date>.md
它會將每條意見逐字分類,放到它所命名的影片(依 id、標題或 heading)下方,將關於「所有影片」的意見放在共享區段,並列出無法歸類的意見。然後你需要在每一行填入:意義(你的解讀,包括不得變更的內容)、驗收條件(你將如何檢查:時間範圍、片段、某個畫面)以及是否為所有影片的規則?
在填寫之前請先閱讀 references/review-protocol.md:其中涵蓋聽寫錯誤、實際上是規則的意見,以及與產品衝突的意見。
對每條意見需要問的三個問題:
- 這真的是規則嗎?如果是,它適用於此輪的所有影片,而不僅是審閱者所指出的那一部。曾有審閱者在一部影片上給出覆蓋規則,數小時後又要求將其套用到所有影片。
- 產品真的有做到嗎?在承諾修復之前先檢查程式碼。如果沒有,提出一個封閉式問題並附上建議選項(「僅顯示已存在的內容」)。
- 這是 COVERAGE.md 中缺少的功能嗎?如果是,則修復時需加入該行。
向使用者展示合併後的表格,最多包含三個封閉式決策(附上預設值)。沉默表示接受預設值。沒有意見的影片被列為未更動。
3. 為每部有問題的影片開啟下一個版本
"$PY" "$PVS_HOME/skills/video-review/scripts/bump_version.py" <video_dir> --note "<quote>" ...
它會備份 lines.tsv、timings.json 和 video/src 為 v,將 BRIEF 版本提升至 N+1 並使用引號開啟一個變更日誌區段。如果 v 從未被渲染過(這會跳過一個版本),則會拒絕執行。v 的渲染結果保持不變:它是一致性比對的參考,且審閱者可能已分享的檔案絕不會被覆寫。
4. 每部影片一個修復子代理,全部同時啟動
為每部影片填寫 references/fix-prompt.md(審閱者的原話、你的意義與驗收條件、你已在程式碼中找到的內容及 file:line、共享規則),並在同一輪中使用 Agent 工具在背景啟動所有修復器。在啟動之前,請自行簡短執行「我已找到的內容」所需的程式碼查詢;這能為每個修復器省去相同的搜尋時間,並捕捉產品無法滿足的意見。
在修復器執行時,不要自行修復任何內容,也不要發送訊息輪詢它們。觀察檔案(stages.py、修改時間、渲染日誌)。如果修復器需要核准,向使用者提出一個封閉式問題並轉達答案。如果修復器停止,使用相同的提示詞加上其中止的位置啟動一個新的修復器:狀態都在檔案中。
5. 自行檢查每個結果
針對每部影片,無論修復器回報了什麼:
- 與先前版本的一致性比對,排除有意識變更的區段:
"$PY" "$PVS_HOME/skills/render-qa/scripts/parity.py" <old mp4> <new mp4> --skip a:b ...。 已核准的區段發生變更即為回歸:退回修復。 - 品質檢查:
"$PY" "$PVS_HOME/skills/render-qa/scripts/qa.py" <video_dir> <new mp4> --strip ...並在每個變更的節拍處設定 strip。請載入render-qa以了解如何解讀;自行查看 sheets 與 strips。 - 從你的表格中檢查每條意見的驗收條件。渲染結果未滿足的意見會退回同一個修復器(SendMessage:問題、時間範圍,「不要更改其他任何內容」)。
- BRIEF.md 中的變更日誌區段需填寫完整。
6. 交付並關閉此輪
"$PY" "$PVS_HOME/skills/render-qa/scripts/deliver.py" <video_dir> <new mp4> --archive-previous
然後一起關閉此輪:成為規則的意見需寫入 kit/RULES.md(附上日期與審閱者的原話),以便下一個建置繼承它們;每個 BRIEF 變更日誌需完整。不再更新的規則檔案會變得錯誤,然後規則就必須在每個提示詞中手動重複。如果審閱者已將先前版本上傳到某處,請指出哪些檔案需要重新上傳。
7. 報告
| 影片 | 從 | 到 | 已套用的意見 | 查看位置 | 一致性 | 品質檢查 | 交付版本 |
|---|
接著:未更動的影片、已加入 kit/RULES.md 的規則、任何未驗證的項目,最多三個封閉式決策。使用使用者的語言,以表格為先,保持簡短。
參考資料
references/review-protocol.md:在填寫合併表格之前閱讀。references/fix-prompt.md:在啟動修復器之前閱讀。