@lingjingai/scriptctl 0.55.0 → 0.57.0

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

@@ -53,7 +53,23 @@ scriptctl ingest -s uploads/正片/ -w workspaces/正片 --step
 ```
 
 JSON 输出包含 `completed`、`remaining`、`complete` 和 `next_episode`。完成后再次调用是
-`processed=0` 的幂等 no-op。集与集之间依赖累计 context，因此不支持跳过前集指定任意集。
+`processed=0` 的幂等 no-op。集与集之间依赖累计 context，因此只能解析或人工跳过当前
+`next_episode`，不能越过它处理后面的集。
+
+### 手动跳过失败视频集
+
+某集已经产生 typed `ep/ep_NNN.error.json`，确认继续重试也无法解析时，可以把当前
+`next_episode` 人工接受为空集：
+
+```bash
+scriptctl ingest skip -w workspaces/正片 --episode 7 --reason "多模型均被合规拦截"
+scriptctl ingest -s uploads/正片/ -w workspaces/正片
+```
+
+跳过记录写入 `skipped.json`，其中保留原因、源视频哈希和原始 typed failure；`script.json`
+对应集的 `scenes` 为空，并在 `extend.scriptctl.ingest` 标记 `outcome=skipped`。后续集 context
+会明确提示该集剧情未知。命令只接受当前失败集，重复执行为幂等 no-op；`--force` 重建会清空
+跳过记录。
 
 ### 视频上传与 provider
 
@@ -77,7 +93,7 @@ scriptctl ingest -s uploads/正片/ -w workspaces/正片 \
 - `--fps <n>`：视频采样帧率（>1 解锁亚秒级时间码）。默认 3。
 - `--step`：视频每次只处理下一个未完成集。
 - `--upload-mode <file-api|base64>`：视频媒体传输方式，默认 `file-api`。
-- `--force`：当前视频 pipeline 的**同源**工作区可清掉产物重跑（**不能换源，也不能升级旧 pipeline workspace**）。
+- `--force`：当前视频 pipeline 的**同源**工作区可清掉产物和人工跳过记录重跑（**不能换源，也不能升级旧 pipeline workspace**）。
 
 管线（了解即可，产物都在 `workspace/`）：
 - **文本**：正文起点定位 → 切块 → 生产化归一 → 合并组装 `body.json` → 串行资产/身份/state 治理 → V3 中间校验 → 稳定 V4 身份分配 → V4 校验与生产规范 warning → `script.json`。
@@ -112,7 +128,7 @@ scriptctl ingest -s uploads/正片/ -w workspaces/正片 \
 
 ```bash
 scriptctl ingest status          # 人读：kind / state / 各 pass 进度（transcribe 40/57 (2 failed) ...）
-scriptctl ingest status -j   # 视频机器输出另含 completed / remaining / complete / next_episode
+scriptctl ingest status -j       # 机器输出含 failure_summary / errors[]；视频另含 completed / parsed / skipped / skipped_episodes / complete / next_episode
 scriptctl view                   # 生成 workspace/review.html（视频版可点击定位到画面）
 scriptctl view --watch [--port N]# 实时监听面板：分阶段进度条 + 逐集 context/决策 + 产物树，自动刷新（跑中也能开）。🔴 仅本地用，**沙箱内不要用**（起阻塞服务+开浏览器，会挂住；沙箱看进度用 `ingest status`）
 scriptctl summary -p workspace/script.json   # 抽完当普通剧本读
@@ -120,9 +136,22 @@ scriptctl summary -p workspace/script.json   # 抽完当普通剧本读
 
 `state`：`empty`（没开始）/ `incomplete`（在跑、中断或只完成连续前缀）/ `failed`（有失败单元或校验没过）/ `ready`（全部 source units 完成，且 `script.json` 的 v4 结构校验通过）。文本与视频 ingest 的 `validation.json` 包含结构校验和 production warning。进度从工作区真实文件推导；它报的是管线事实，资产合并结论和源素材一致性仍由复核完成门确认。
 
+失败时 `status -j` 的 `errors[]` 按 `failure_type` / `failure_code` 给出稳定分类，并显式给出
+`retryable`。网络错误可含 `system_code`，HTTP 错误可含 `http_status`；Gemini 合规拦截可含
+`provider_source`、`provider_reason` 和 `safety_ratings`；模型 fallback 全部失败时，`attempts[]`
+保留每个实际调用的 provider、model 和失败原因。`failure_summary` 汇总 retryable / terminal
+数量和 `by_type`。`state` 仍只表示管线生命周期，合规拦截表现为
+`state=failed` + `failure_type=policy`。
+
+人工跳过后，该集从活动 `errors[]` 移入 `skips[]`；全部集都已解析或跳过时仍可为
+`state=ready` / `complete=true`，同时 `has_skips=true`。消费方据此区分“管线已完成”和
+“内容是否完整”。
+
 ## 四、🔴 抖动与重跑（大规模转剧本的常态）
 
-模型抖动 / 限流 / 单集超时 / 偶发解析失败在几十集体量下**是正常现象，不是 bug**。护栏与恢复：
+模型抖动 / 限流 / 单集超时 / 偶发解析失败在几十集体量下**是正常现象，不是 bug**。先看
+`errors[].retryable`：retryable 失败直接续跑；terminal 失败按错误类型处理，合规拦截不应对同一
+素材反复空跑。护栏与恢复：
 
 | 报错 | 含义 | 怎么办 |
 |---|---|---|
@@ -132,10 +161,12 @@ scriptctl summary -p workspace/script.json   # 抽完当普通剧本读
 | `INGEST_SOURCE_MISMATCH` | 工作区是别的 source，或已接受的视频分集前缀发生变化 | 恢复原分集前缀；确实要换源时使用新的 `-w`，**别 `--force` 硬覆盖** |
 | `INGEST_VIDEO_SEQUENCE` | 视频集号没有组成从 1 开始的连续序列 | 补齐缺集或修正文件名后重跑 |
 | `INGEST_VIDEO_INLINE_TOO_LARGE` | 自动转码后的文件达到 Gemini inline base64 上限 | 改用 `--upload-mode file-api` |
+| `INGEST_SKIP_*` | 手动跳过目标不是当前失败集，或 workspace / sidecar / ledger 不满足要求 | 读取 `ingest status -j`，只对 `next_episode` 且已有 typed error sidecar 的视频集执行 `ingest skip` |
 | `INGEST_VALIDATION_FAILED` | 最终校验没过 | 看 `workspace/validation.json` 的具体报错，修复后再 `publish` |
 | 持续 401/403/404 / 模型路由错 | 网关/密钥/模型环境问题（不是抖动，重跑也不好） | 如实告诉用户，别反复空跑、别编造成功。视频需 `GEMINI_API_KEY` |
 
-🔴 **绝不**：清工作区、删 checkpoint、手塞/手改中间文件来"绕过"失败。重跑 = 唯一正解；成功单元不会重跑，贵的花名册归并（`roster.json`）也会复用。
+🔴 **绝不**：清工作区、删 checkpoint、手塞/手改中间文件来绕过失败。retryable 失败使用同源
+重跑；确认无法解析的当前视频集使用 `ingest skip`，由命令原子维护 ledger、context 和空集产物。
 
 ## 五、入库 `publish`