1实现原理 · 为什么它能做到
五条外科规则先立边界：改源不改成片、只重渲受影响场景、从当前批准时间线重建装配、不重设计/不重定时/不重同步无关段、宣布完成前搜索重复与 carryover 帧。
skills/render-qa-and-surgical-changes/SKILL.md
- Patch source artifacts, not the final MP4, when source scenes and assembly scripts exist.
注：这里在做什么：定义「外科」的含义——最小作用域加不触碰已批准部分；这是全族收尾阶段的第一原则，也在 workflows/surgical-final-edit.md 与 end-to-end-video-playbook 里重复出现。
QA 序列固定五段：探针成片（时长/分辨率/帧率/音轨/采样率/声道）→ 抽证明帧（场景边界、改动时刻、字幕样式帧、结尾 CTA）→ 做接触表（含改动前后对比）→ 查音频（旁白在、音乐该响处可听、结尾静音或淡出正确、裁剪后无吞词）→ 查主题与文本（过期颜色、carryover 重复标签、logo 与产品录屏未被误改色）。
skills/render-qa-and-surgical-changes/SKILL.md
5. Check theme and text.
注：这里在做什么：把验收拆成机器可查（探针与抽帧）与眼看耳听（接触表与音频）两半，且两半都必须做。
用户点名时间戳要三帧取证（该时刻 + 略前 + 略后），且必须在成片上验、不能只验源场景；若同一视觉出现在下一场景，还要抽边界帧。
skills/render-qa-and-surgical-changes/SKILL.md
- Extract a frame at that exact time.
注：这里在做什么：把「用户说的那一秒」变成可举证的三帧证据，同时防止「源场景改对了、成片没重建」这类假通过。
三类安全替换各有程序：音频（探旧新时长→同长则换路径重建、略差则决定 tempo 适配或重定时视觉、确认下游场景起点不动除非要求、措辞变了要重生成字幕）、文本（改源→搜下一场景 carryover 文案→重渲→重建→在可见时刻抽帧）、主题（用主题扫描器、只改可编辑源、不染 logo 与录屏、查 SVG、查下一场景 carryover）。
skills/render-qa-and-surgical-changes/SKILL.md
- Search next scene for carryover copy.
注：这里在做什么：把三种最常见的收尾改动写成「先搜索、再改、再重建、再取证」的同构流程，其中搜索是防回归的关键步。
先搜索再动手：搜索所有源场景文件里的文本或颜色、装配脚本里的音频路径与时长、字幕脚本里的旧措辞；只在需要更新公开文档时才搜 templates/examples；生成物一律不搜（除非做视觉 QA）。
skills/render-qa-and-surgical-changes/SKILL.md
- Ignore generated renders unless doing visual QA.
注：这里在做什么：明确搜索边界，既避免漏改（源文件全搜），也避免在渲染产物里白搜（生成物不是源）。
QA 输出包固定：probe 文本或控制台摘要、proof-*.png、contact-sheet.jpg、moving sync 用的 preview-*.mp4、最终渲染路径；并注明生成物不必入库（除非是公开示例）。
skills/render-qa-and-surgical-changes/SKILL.md
preview-*.mp4` for moving sync checks.
注：这里在做什么：把验收留痕标准化，同时把「产物不入库」写成纪律，与仓库 .gitignore（renders/、snapshots/、captions/*.ass 全忽略）一致。
定义停止条件：改动与已锁场景批准冲突、可见末帧的源资产找不到、文本或音频改动隐含未批准的脚本变更、logo 改色但品牌归属不明——遇到就停下来问，否则做最小安全改动并验证。
skills/render-qa-and-surgical-changes/SKILL.md
- A text/audio change implies a script change the user has not approved.
注：这里在做什么：给无条件执行加刹车；与仓库 AGENTS.md 的 Never mutate approved scenes unless the user explicitly asks 一致。
2核心能力
01六个仓库脚本的调用面：probe_media.py（探针）、extract_proof_frames.py（抽帧）、make_contact_sheet.py（接触表）、build_ass_captions.py（字幕）、scan_theme_colors.py（过期主题色扫描）、timeline_manifest_to_ffmpeg.py（清单转装配计划）
02精确时间戳取证程序（该时刻 + 略前 + 略后；在成片上验；下一场景同视觉要抽边界帧）
03音频安全替换（单条旁白）：探旧新时长 → 同长换路径重建 → 略差决定 tempo 适配或重定时视觉 → 确认下游场景起点不动 → 措辞变了重生成字幕
04文本安全替换：改源场景 → 搜下一场景 carryover 文案 → 措辞变了还要搜旧字幕 → 重渲受影响场景 → 重建 → 在可见时刻抽帧
05主题安全替换：用主题扫描器、只改可编辑源、不染 logo 与产品录屏、查 SVG 值、查下一场景 carryover
06QA 输出包与「生成物不入库」纪律；以及 Stop Conditions（四项）与「否则做最小安全改动并验证」的默认动作
07失败模式参考（视觉 6 条、音频 6 条、字幕 4 条、回归检查 5 条），可直接当验收勾选表
3外部依赖
| 类型 | 依赖 |
|---|---|
| cli | ffprobe / ffmpeg（经仓库脚本间接依赖：探针与抽帧、接触表合成；缺失即 SystemExit） |
| package | 仓库根脚本 scripts/probe_media.py（ffprobe JSON 封装：时长/体积/码率/视频编码与分辨率/帧率/像素格式/音频编码/采样率/声道） |
| package | 仓库根脚本 scripts/extract_proof_frames.py（按 -ss 精确抽帧并可拼接触表）与 scripts/make_contact_sheet.py |
| package | 仓库根脚本 scripts/scan_theme_colors.py（按允许色白名单扫文本源文件，跳过 node_modules/.git/renders/snapshots/assembly/dist/build，发现 review 项时退出码 1） |
| package | 仓库根脚本 scripts/build_ass_captions.py（字幕）与 scripts/timeline_manifest_to_ffmpeg.py（清单转装配计划） |
| package | 模板 templates/change-request.md（收尾小改动前必须先填：改动内容、保留项、实现规则、证明表、验收标准） |
4风险提醒 风险提醒：蓝色 · 知晓即可
风险提醒：蓝色 · 知晓即可
- skill 目录不带脚本，脚本位于仓库根 —— 单独复制 skill 目录会失去执行面 — README 建议过 copy selected folders from skills/ into your Codex skills directory；若只复制 skills/render-qa-and-surgical-changes/，SKILL.md 点名的 scripts/*.py 与 templates/change-request.md 都不在，验收流程会退化成手工操作。
- 依赖 PATH 上的 ffmpeg/ffprobe，缺失即硬失败 — probe_media.py 与 extract_proof_frames.py 在 shutil.which 找不到对应二进制时直接 SystemExit；文档未把这一前提写在 SKILL.md 的依赖段（只在仓库 README 的示例里隐含）。
- 主题扫描是文本正则，非语义检查 — scan_theme_colors.py 只按 #hex、rgb()、hsl() 正则与允许白名单比对，不认识「这段 hex 属于 logo」或缺省继承色；因此不染 logo 仍需人工保证（SKILL.md 也把它写成规则而非机制）。
- 改动请求的字面替换可能放大作用域 — 文本替换流程是「搜索所有源场景文件里的文本或颜色」再替换；若被替换字串过短（如单个词），可能命中无关位置。SKILL.md 要求搜下一场景 carryover，但没有要求先枚举命中清单并确认。
- preview 片段没有随包生成工具 — QA 输出包要求 preview-*.mp4（moving sync checks），但六个脚本里没有生成预览片的工具，需宿主自行拼 ffmpeg 命令；这一步最容易被跳过，导致移动同步问题（抽帧看不出的问题）漏检。
风险提醒：蓝色，知晓即可。本 skill 目录只有 SKILL.md + references/failure-modes.md（纯指令）；实际执行面是仓库根 scripts/ 六个确定性脚本，它们只做 ffprobe/ffmpeg 子进程调用与本地文件读写（已逐个核对：无 urllib/requests/socket，无网络分支），以及模板 templates/change-request.md。**没有把素材送外部服务**：全量扫描脚本与 skill 目录内无 http(s):// 端点、无 fetch/requests、无 token/env 读取。scan_theme_colors.py 在发现非白名单颜色时以退出码 1 结束——这是报告不符而非破坏性行为。九件同族 skill 判级口径一致：目录内只有 SKILL.md（+ references），行为面是本地读写与本地 CLI，无端点、无凭证、无素材外发。
5第二遍独立确认
- [ok] 本 skill 的执行面「无网络」是否成立（逐个脚本核对） — 六个脚本的 import 只有 argparse/csv/json/re/shutil/subprocess/pathlib（scan_theme_colors 另用 re/pathlib），无 urllib/requests/socket/http；子进程调用仅 ffprobe/ffmpeg，参数为本地路径。故无素材外发、无端点查询，不构成黄档或橙档。
- [ok] SKILL.md 点名的六个脚本是否都真实存在 — pin 内 scripts/ 下有 build_ass_captions.py、extract_proof_frames.py、make_contact_sheet.py、probe_media.py、scan_theme_colors.py、timeline_manifest_to_ffmpeg.py——与 SKILL.md 的 Use repo scripts when available 清单逐项对应。
- [ok] 「抽该时刻 + 略前 + 略后」是否可用脚本实现 — extract_proof_frames.py 接受可重复的 --time（label=timestamp 形式），每个时刻用 ffmpeg -ss 精确抽一帧并按序号与标签命名，可直接表达 0.05s 级的前后帧；--contact-sheet 可一次拼出对比表。
- [discrepancy] 本 skill 是否点名了 ffmpeg/ffprobe 本身 — SKILL.md 全文只点名仓库脚本（含名字里带 ffmpeg 的 timeline_manifest_to_ffmpeg.py），未直接写 ffprobe/ffmpeg 命令；CLI 依赖由脚本内部承担（probe_media.py 的 shutil.which("ffprobe")、extract_proof_frames.py 的 shutil.which("ffmpeg") 缺失即报错退出）。使用者需知道脚本依赖 PATH 上的 ffmpeg/ffprobe。
- [ok] 「生成物不入库」与仓库实际忽略规则是否一致 — SKILL.md 的 Generated QA files do not need to be committed unless they are public examples. 与仓库 .gitignore（忽略 renders/、snapshots/、assembly/、captions/*.ass、captions/*.json 与各类视频扩展名）一致。
- [ok] QA 输出包的五个产物是否都有生成路径 — probe 摘要来自 probe_media.py；proof-*.png 来自 extract_proof_frames.py；contact-sheet.jpg 来自 extract_proof_frames.py 的 --contact-sheet 或 make_contact_sheet.py；preview-*.mp4 由宿主用 ffmpeg 生成（文档未点名脚本，属流程项）；最终渲染路径由项目输出。除 preview 外均有随包工具。
6结论
适合：适合：片子已接近完成或已获批准时的收尾工作——最终 QA、HD 与渲染核验、小的文本或音频或颜色改动、已批准时序后的回归检查、场景边界与点名时间戳取证、主题过期色清理、carryover 帧刷新，以及只重渲受影响场景再重建装配的受控流程。
不适合：不适合：① 还在设计阶段的大改（应回 motion-design-systems 或 scene-builder，本件的五条规则明确禁止重设计）；② 需要重新配音或重排时间线的项目（走 audio-sync-assembly）；③ 需要字幕样式重做或音乐重混（走 captions-and-music-bed）；④ 只能复制单个 skill 目录、拿不到仓库根 scripts/ 与 templates/ 的使用方式（执行面会残缺）；⑤ 环境无 ffmpeg/ffprobe 时。
安装 agent 直装可复制
① 本站镜像 更新 2026-09-28
方式 A · 人下载镜像包下载 render-qa-and-surgical-changes.tar.gz
sha256:
方式 B · JSON 格式安装指南，复制给 agent47a9915a5d91b665…agent 读 JSON 指南后会自动从本站下载安装，无需更多说明。
② 上游 GitHub · 原始来源
来源信息 GitHub 原始
作者 / 仓库saranambiar / saranambiar/hyperframes-video-agent-skills
Stars48
最近推送2026-06-14
本 skill commit
f6b043d9fd许可Apache-2.0（仓库根 LICENSE 为 Apache License Version 2.0；GitHub API license.spdx_id = Apache-2.0）
本站信息
收录日期2026-09-06
分类内容创作
侦查报告AI 侦查 · 2 遍 · 2026-09-06
本站镜像与 GitHub 原始是不同来源：本站锁定 commit 快照经 /r2 分发；GitHub 为实时上游，内容可能已更新。