@lingjingai/scriptctl 0.53.7 → 0.53.9

package/skills/scriptctl/SKILL.md

@@ -3,7 +3,7 @@ name: scriptctl
 description: "剧本 script.json 的本地查询、文件化批量写作、原子精修、素材 ingest 与 revision publish CLI。处理 Script v3/v4、两个 script.json、剧本资产/state、Action、场景引用或 authoring 时使用。"
 metadata:
   version: "0.27.11"
-  scriptctl_version: "0.53.7"
+  scriptctl_version: "0.53.9"
   author: "official"
 ---
 

package/skills/scriptctl/references/ingest-workflow.md

@@ -7,7 +7,7 @@ ingest -s <file|dir>   →   标准化复核   →   view / ingest status   →
    (抽取，产 workspace/script.json)       (内容完成门)       (自查/看进度)            (校验+入库)
 ```
 
-- 支持输入：**文本** txt / md / docx；**视频** 单个正片文件或**分集目录**（需 `GEMINI_API_KEY`）。pdf/json/xlsx 会被拒。
+- 支持输入：**文本** txt / md / docx；**视频** 单个正片文件或**分集目录**（需 `GEMINI_API_KEY`）。编号分集目录必须组成从第 1 集开始、无缺集的 `1..N` 连续序列。pdf/json/xlsx 会被拒。
 - `ingest` **不入库**：只产 `workspace/script.json`（默认工作区 `workspace`，可 `-w` 改）。入库是独立的 `publish`。
 - 产物随后就是普通剧本：任何读写动词加 `-p workspace/script.json` 即可精修。
 
@@ -20,15 +20,36 @@ scriptctl ingest -s uploads/剧本.docx
 scriptctl ingest -s uploads/正片/
 ```
 
+### 视频分批追加
+
+分集目录可以只放前几集先跑；后续把连续的新集加到同一目录，再对同一 workspace
+重复原命令：
+
+```bash
+# 首批目录内为第 1～3 集
+scriptctl ingest -s uploads/正片/ -w workspaces/正片
+
+# 加入第 4～6 集后继续；复用前 3 集，只处理新增集
+scriptctl ingest -s uploads/正片/ -w workspaces/正片
+```
+
+workspace 把已经接受的分集视为不可变前缀。允许的 source 变化只有在尾部加入连续集号；
+旧集内容改变、删除、改名、移动，或新增集造成断档时，返回
+`INGEST_SOURCE_MISMATCH` / `INGEST_VIDEO_SEQUENCE`，不会复用不可信的跨集 context。
+一次追加中断后仍运行同一条命令，继续补未完成的新集。
+
+每次追加会从全部逐集 checkpoint 重建 `script.json`。先用前几集试跑和复核抽取质量，
+等最后一批完成后再精修 `script.json`；批次之间直接修改成稿会在下一次重建时被覆盖。
+
 常用 flag：
 - `-w <dir>`：工作区根（manifest + 各 pass 目录 + 产物）。**不传默认 `<cwd>/workspace`**；显式传可放别处。`view` / `ingest status` 使用同一 workspace；publish 用 `-p <workspace>/script.json`。
 - `--concurrency <n>`：文本 fanout 并发，默认 30。视频逐集串行。
 - `--fps <n>`：视频采样帧率（>1 解锁亚秒级时间码）。默认 3。
-- `--force`：**同源**重跑，清掉产物重来（**不能换源**）。
+- `--force`：当前视频 pipeline 的**同源**工作区可清掉产物重跑（**不能换源，也不能升级旧 pipeline workspace**）。
 
 管线（了解即可，产物都在 `workspace/`）：
 - **文本**：正文起点定位 → 切块 → 生产化归一 → 合并组装 `body.json` → 串行资产/身份/state 治理 → V3 中间校验 → 稳定 V4 身份分配 → V4 校验与生产规范 warning → `script.json`。
-- **视频**：逐集串行观看原视频并维护跨集人物、剧情和造型上下文 → 确定性治理 → V3 中间校验 → 稳定 V4 身份分配 → V4 校验与生产规范 warning → `script.json`。时间戳写入 `extend.timestamp`，逐集 `ep/*.json`、`context.json` 和身份映射支持断点续跑。
+- **视频**：逐集串行观看原视频并维护跨集人物、剧情和造型上下文 → 确定性治理 → V3 中间校验 → 稳定 V4 身份分配 → V4 校验与生产规范 warning → `script.json`。时间戳写入 `extend.timestamp`；逐集内容身份、`ep/*.json`、`context.json` 和身份映射共同支持断点续跑与严格尾部追加。
 - **用量账本**：`usage.json` 在每集/处理单元成功或失败后立即原子更新。`records` 保存实际 task/provider/model 的逐次调用、失败、重试、token 与耗时；`episodes`、`byTask[].byModel`、全局 `byModel`、`totals` 和 `timing` 都从明细聚合，可用于按模型价格精确核算成本。
 
 ### 提取与解析原则
@@ -70,8 +91,9 @@ scriptctl summary -p workspace/script.json   # 抽完当普通剧本读
 |---|---|---|
 | `INGEST_NORMALIZE_INCOMPLETE`（文本）<br>`INGEST_TRANSCRIBE_/CORRECT_/SPEAKER_INCOMPLETE`（视频） | 部分单元失败，留下 `passN/*.error.json` sidecar | **直接重跑 `scriptctl ingest`（同 source、同 workspace）**——从 checkpoint 续，只补失败单元。跑完 `ingest status` 看还剩几个，多跑几次到收敛 |
 | `INGEST_SERIAL_FAILED`（文本串行 govern） | 某集串行解析连试几次仍失败（模型抖动） | **直接重跑**，从该集续——前面各集已缓存不重跑 |
-| `INGEST_PIPELINE_MISMATCH` | 工作区的管线版本与当前版本不同 | 确认 source 未变化后，使用同一 source、同一 workspace 加 `--force` 完整重建 checkpoint |
-| `INGEST_SOURCE_MISMATCH` | 工作区是别的 source 建的 | 换一个新的 `-w`，**别 `--force` 硬覆盖** |
+| `INGEST_PIPELINE_MISMATCH` | 工作区的管线版本与当前版本不同 | 视频使用新的 `-w` 重新 ingest；文本按错误提示处理 |
+| `INGEST_SOURCE_MISMATCH` | 工作区是别的 source，或已接受的视频分集前缀发生变化 | 恢复原分集前缀；确实要换源时使用新的 `-w`，**别 `--force` 硬覆盖** |
+| `INGEST_VIDEO_SEQUENCE` | 视频集号没有组成从 1 开始的连续序列 | 补齐缺集或修正文件名后重跑 |
 | `INGEST_VALIDATION_FAILED` | 最终校验没过 | 看 `workspace/validation.json` 的具体报错，修复后再 `publish` |
 | 持续 401/403/404 / 模型路由错 | 网关/密钥/模型环境问题（不是抖动，重跑也不好） | 如实告诉用户，别反复空跑、别编造成功。视频需 `GEMINI_API_KEY` |
 
@@ -94,7 +116,7 @@ scriptctl publish -p workspace/script.json --project-group-no 123
 - **转完先精修再入库**：`ingest` → 用 `-p workspace/script.json` 跑读写动词修（改归属、并角色、标龙套、补造型……）→ `publish`。
 - **入库后再改**：继续编辑同一个受管本地文件再 publish；若工作副本不在，先 checkout，不能直接对 DB 跑原子命令。
 - **视频复核**：`view` 出的 `review.html` 视频版支持点击台词跳到对应画面时间码，逐场核对发声源/造型。
-- **超大剧集（几十集）**：并发默认已调好；失败就重跑到 `ingest status` 显示 `ready`。花名册归并只跑一次并复用，重跑很快。
+- **超大剧集（几十集）**：可以按连续尾部分批加入同一 source 目录并重复 ingest；失败就重跑到 `ingest status` 显示 `ready`。已完成集和跨集 context 会复用。
 - **归并质量**：跨集角色归并靠文字锚点，相似角色可能误合/合过头。用 `roster.review.md`（视频）核对归并决策；发现误合，入库后用 `merge` 拆分/改名修正。
 
 ## 七、抽完后的读写