@lingjingai/scriptctl 0.51.0 → 0.51.2

package/skills/scriptctl/references/video-transcript-repair.md

@@ -0,0 +1,115 @@
+# 视频转录剧本人工复核
+
+本流程适用于视频转录产生的 Script v3/v4。目标是保留原视频可验证的内容与集内时间点，
+由人判断身份、场界、说话人和误拆合并，Agent 执行定位、批量写入、读回和校验。
+
+## 1. 建立可修复工作副本
+
+读取 `script.json.version`。V3 先运行：
+
+```bash
+scriptctl validate -p "$V3"
+scriptctl migrate-v4 -p "$V3" -o "$V4" --identity-map "$ID_MAP"
+```
+
+`migrate-v4` 的 `exit_code=78` 表示 V4 副本已经生成，且 `validation.issues` 仍需复核。
+源 V3 保持不变。V4 有多个 blocking issue 时，把完整修复组织成一个 `do` 或 `patch`
+事务；计划的最终状态通过校验后再 apply。首次 V4 副本建立后，后续内容精修直接写 V4。
+
+人物重名按剧情身份判断：
+
+- 同一人物被重复建档：先核对 `refs`、states、aliases、importance 和实际对白，再把信息
+  补到保留人物，最后 `merge <source> --into <survivor>`。
+- 不同人物共用外观标签：把各自 `actor_name` 改为真实稳定身份，外观或称呼放 aliases。
+- 人物名改成已有 alias 后，同步移除与正式名相同的 alias。
+
+每轮修复后运行 `validate`。校验通过表示结构与引用合法，人物身份仍以视频复核结论为准。
+
+## 2. 定位 Action 与时间点
+
+时间戳是集内固定起点，存储在 `action.extend.timestamp`，格式使用
+`M:SS` 或 `MM:SS.mmm`。它不是持续区间；一条 Action 的结束时间由下一条 Action 的
+起点或视频画面复核推断。
+
+```bash
+scriptctl actions -i '@ep:4' -p "$SCRIPT"
+scriptctl actions -g "台词片段" -p "$SCRIPT"
+scriptctl extend <action-id> timestamp 00:42.533 -p "$SCRIPT"
+```
+
+校时使用视频中该动作或对白真正开始的画面。保留亚秒级精度。没有视频证据时保留待复核，
+不根据相邻行平均分配。
+
+## 3. 补漏 Action 或对白
+
+先取得相邻 Action、场景和说话人的正式 ID，再生成一个 Action ID：
+
+```bash
+scriptctl ids -k action --count 1 -p "$SCRIPT"
+```
+
+把插入和时间戳写在同一个 `do` 事务中。动作示例：
+
+```text
+insert <scene-id> --action-id <new-action-id> -t action --content "她推门进屋。" --after <previous-action-id>
+extend <new-action-id> timestamp 00:42.533
+```
+
+对白示例：
+
+```text
+insert <scene-id> --action-id <new-action-id> -t dialogue --content "我回来了。" -a <actor-id> --after <previous-action-id>
+extend <new-action-id> timestamp 00:42.533
+```
+
+人物必须已经出现在本场 scene ref 中；需要指定造型时同时传 `--speaker-state <state-id>`。
+先运行 `scriptctl do edits.txt -p "$SCRIPT"` 查看计划，再用返回的 digest 精确 apply。
+
+## 4. 合并被误拆的连续对白
+
+满足以下条件时合并：
+
+1. 行在同一场内连续；
+2. 类型相同；
+3. 对白或心声的 speaker 相同；
+4. 中间没有独立动作、反应、转折或另一个说话人；
+5. 视频确认它们属于同一次连续表达。
+
+保留第一条 Action ID，正文按原视频顺序拼接，时间戳取第一句真正开始的时间，删除后续
+Action。使用一个 `do` 事务：
+
+```text
+replace <first-action-id> --from "第一段" --to "第一段第二段"
+extend <first-action-id> timestamp 00:42.533
+delete <second-action-id>
+```
+
+多个连续碎片依次并入第一条。不同人物重复表达同一态度仍是多条对白；剧情功能相同不代表
+物理 Action 可以合并。
+
+## 5. 人与 Agent 的分工
+
+人工确认：
+
+- 真实人物身份、同名人物是否同一人；
+- 场界和说话人；
+- 时间点与视频画面；
+- 拆行是否属于一次连续表达；
+- 修正后的对白和动作是否忠于原视频。
+
+Agent 执行：
+
+- 查询 Action、资产、refs 和缺失时间戳；
+- 生成 V4 ID；
+- 组织 `do` 计划；
+- 应用经确认的插入、校时、合并和人物修复；
+- 读回目标并运行 `validate`；
+- 输出仍需人工复核的清单。
+
+完成标准：
+
+1. 每条需要跳转视频的 Action 都有有效集内时间戳；
+2. 新增、删除和合并后的 Action 顺序正确；
+3. V4 Action ID 唯一且稳定；
+4. `validate` 通过；
+5. 人工完成逐集视频复核。