@lingjingai/scriptctl 0.54.0 → 0.56.0

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`）。编号分集目录必须组成从第 1 集开始、无缺集的 `1..N` 连续序列。pdf/json/xlsx 会被拒。
+- 支持输入：**文本** txt / md / docx；**视频** 单个正片文件或**分集目录**（默认凭证为 `GEMINI_API_KEY`，也可用下文 provider 参数覆盖）。编号分集目录必须组成从第 1 集开始、无缺集的 `1..N` 连续序列。pdf/json/xlsx 会被拒。
 - `ingest` **不入库**：只产 `workspace/script.json`（默认工作区 `workspace`，可 `-w` 改）。入库是独立的 `publish`。
 - 产物随后就是普通剧本：任何读写动词加 `-p workspace/script.json` 即可精修。
 
@@ -41,21 +41,58 @@ workspace 把已经接受的分集视为不可变前缀。允许的 source 变
 每次追加会从全部逐集 checkpoint 重建 `script.json`。先用前几集试跑和复核抽取质量，
 等最后一批完成后再精修 `script.json`；批次之间直接修改成稿会在下一次重建时被覆盖。
 
+### 视频逐集推进
+
+外部调度器需要逐集控制时使用 `--step`。每次调用只接受下一个未完成集，成功后立即对当前
+连续前缀生成并校验 `script.json`，退出码为 0；全部 source episodes 完成前，
+`ingest status` 仍为 `incomplete`。
+
+```bash
+scriptctl ingest -s uploads/正片/ -w workspaces/正片 --step
+scriptctl ingest -s uploads/正片/ -w workspaces/正片 --step
+```
+
+JSON 输出包含 `completed`、`remaining`、`complete` 和 `next_episode`。完成后再次调用是
+`processed=0` 的幂等 no-op。集与集之间依赖累计 context，因此不支持跳过前集指定任意集。
+
+### 视频上传与 provider
+
+```bash
+scriptctl ingest -s uploads/正片/ -w workspaces/正片 \
+  --upload-mode base64 \
+  --provider-base-url https://gemini.example.com \
+  --provider-api-key-env CUSTOM_GEMINI_KEY \
+  --provider-model gemini-3.6-flash
+```
+
+- `--upload-mode file-api|base64`：默认 `file-api`；`base64` 把自动转码后的本地视频放入 Gemini `inlineData`，文件必须小于 100 MB。
+- `--provider-base-url`、`--provider-api-key` / `--provider-api-key-env`、`--provider-model`：只覆盖视频任务对应字段，其余字段继承 `--llm-config` 或内置配置。
+- provider 参数必须提供非空值；`--provider-api-key` 与 `--provider-api-key-env` 互斥。明文参数会暴露在进程参数和 shell history 中，常规调用使用环境变量方式；密钥不会写入 workspace、错误或命令输出。
+- 任一 provider 覆盖参数出现时严格使用指定后的 provider/model，不进入内置模型回退链。未覆盖 provider 时保留默认 Gemini 回退；base64 模式不会进入依赖 Files API 的跨 provider 回退。
+- `--provider-base-url` 指向 Gemini Developer API 兼容的服务根地址；`file-api` 模式要求该服务同时兼容 Files API。
+
 常用 flag：
 - `-w <dir>`：工作区根（manifest + 各 pass 目录 + 产物）。**不传默认 `<cwd>/workspace`**；显式传可放别处。`view` / `ingest status` 使用同一 workspace；publish 用 `-p <workspace>/script.json`。
 - `--concurrency <n>`：文本 fanout 并发，默认 30。视频逐集串行。
 - `--fps <n>`：视频采样帧率（>1 解锁亚秒级时间码）。默认 3。
+- `--step`：视频每次只处理下一个未完成集。
+- `--upload-mode <file-api|base64>`：视频媒体传输方式，默认 `file-api`。
 - `--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` 都从明细聚合，可用于按模型价格精确核算成本。
 
 ### 提取与解析原则
 
 - 先忠实提取源素材可验证的对白、动作、顺序、人物状态和场景切换，再整理成标准资产与正文。
 - 视频以画面和声音为准；逐条保留出镜对白、画外对白、角色内心独白/自述、客观旁白、电话/广播/设备声和跨画面连续讲述。人物未出镜或画面切换不构成省略声音的理由。小说与非标准剧本把叙述转换成可拍摄 Action，同时保留原文事实、因果和人物关系。
+- 视频 Action 按生产行为节拍组织：场景开头建立人物位置、姿态、面向、视线和当前行为；之后每个新动作、反应、接触、进出场、道具结果或空间关系变化分别保留。只去重不同镜头重复展示的同一个节拍，不把先后事件压缩成剧情概述，正文不写景别、机位、运镜等摄影调度。
+- 视频解析先完整盘点原声，再扫描可见行为，完成前复核全部人声和最后十秒。手机、屏幕、照片与回忆只写画面直接呈现的事实，不推断未被画面、文字或台词证明的状态、原因或结果。
+- 视频人物规范名只依据书面姓名或台词本名逐步升级；描述名、简称和旧规范名会作为同一人物的 aliases 回填历史剧集。
+- 视频对白前先建立画面可确认的持续状态；状态不变时不为每句对白补造动作。`parenthetical` 可写发声方式、声音来源或与台词同时发生的短促可见动作，影响走位、姿势、接触、道具或连续性的动作独立写 Action。
+- 视频正文以具体表情、视线、肢体和环境反应表达人物状态。角色既有服装由场景 state 与资产承载；换装、脱衣、破损、泥污等现场变化或必要区分写入 Action。
 - 每场填写一个明确时段：日、夜、晨、昏分别写入 `day`、`night`、`dawn`、`dusk`。原素材未直写时依据照明、作息、天空和上下文判断，并在人工复核中确认。
 - 视频对白和独白逐字保留音轨实际语言与夹杂语言。原始音轨优先于字幕；翻译字幕不得替换外语原声。文本素材保留对白原文。允许为结构化和可拍摄性规范化叙述措辞，同时保持事实、因果、顺序、动作结果和状态不变。
 - 将无法确认的人物身份、动作主体、地点和状态保留为待复核项，不补写源素材没有表达的事实。
@@ -75,17 +112,26 @@ workspace 把已经接受的分集视为不可变前缀。允许的 source 变
 
 ```bash
 scriptctl ingest status          # 人读：kind / state / 各 pass 进度（transcribe 40/57 (2 failed) ...）
-scriptctl ingest status -j   # 机器：.status = {kind,state,phase,passes[],units,validation,errors[]}
+scriptctl ingest status -j       # 机器输出含 failure_summary / errors[]；视频另含 completed / remaining / complete / next_episode
 scriptctl view                   # 生成 workspace/review.html（视频版可点击定位到画面）
 scriptctl view --watch [--port N]# 实时监听面板：分阶段进度条 + 逐集 context/决策 + 产物树，自动刷新（跑中也能开）。🔴 仅本地用，**沙箱内不要用**（起阻塞服务+开浏览器，会挂住；沙箱看进度用 `ingest status`）
 scriptctl summary -p workspace/script.json   # 抽完当普通剧本读
 ```
 
-`state`：`empty`（没开始）/ `incomplete`（在跑或中断、无硬错，重跑续）/ `failed`（有失败单元或校验没过）/ `ready`（`script.json` 生成且 v4 结构校验通过）。文本与视频 ingest 的 `validation.json` 包含结构校验和 production warning。进度从工作区真实文件推导；它报的是管线事实，资产合并结论和源素材一致性仍由复核完成门确认。
+`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`。
 
 ## 四、🔴 抖动与重跑（大规模转剧本的常态）
 
-模型抖动 / 限流 / 单集超时 / 偶发解析失败在几十集体量下**是正常现象，不是 bug**。护栏与恢复：
+模型抖动 / 限流 / 单集超时 / 偶发解析失败在几十集体量下**是正常现象，不是 bug**。先看
+`errors[].retryable`：retryable 失败直接续跑；terminal 失败按错误类型处理，合规拦截不应对同一
+素材反复空跑。护栏与恢复：
 
 | 报错 | 含义 | 怎么办 |
 |---|---|---|
@@ -94,6 +140,7 @@ scriptctl summary -p workspace/script.json   # 抽完当普通剧本读
 | `INGEST_PIPELINE_MISMATCH` | 工作区的管线版本与当前版本不同 | 视频使用新的 `-w` 重新 ingest；文本按错误提示处理 |
 | `INGEST_SOURCE_MISMATCH` | 工作区是别的 source，或已接受的视频分集前缀发生变化 | 恢复原分集前缀；确实要换源时使用新的 `-w`，**别 `--force` 硬覆盖** |
 | `INGEST_VIDEO_SEQUENCE` | 视频集号没有组成从 1 开始的连续序列 | 补齐缺集或修正文件名后重跑 |
+| `INGEST_VIDEO_INLINE_TOO_LARGE` | 自动转码后的文件达到 Gemini inline base64 上限 | 改用 `--upload-mode file-api` |
 | `INGEST_VALIDATION_FAILED` | 最终校验没过 | 看 `workspace/validation.json` 的具体报错，修复后再 `publish` |
 | 持续 401/403/404 / 模型路由错 | 网关/密钥/模型环境问题（不是抖动，重跑也不好） | 如实告诉用户，别反复空跑、别编造成功。视频需 `GEMINI_API_KEY` |
 

package/skills/scriptctl/references/production-writing-standard.md

@@ -18,6 +18,11 @@
 - V4 的短表演提示写 `parenthetical`；字段可省略，也可显式保存空字符串。
 - 影响走位、道具、状态或连续性的动作写成独立 Action。
 - 同时说话用相邻 dialogue 表达；结构不声明对白重叠时间轴。
+- 视频提取以生产行为节拍组织 Action：只去重不同镜头重复展示的同一个节拍；新动作、反应、接触、道具结果、进出场和空间关系变化分别保留。场景开头建立可确认的位置、姿态、面向、视线和当前行为，对白期间只在可见状态改变时更新。
+- 视频对白沿用前文已经建立且未变化的持续状态；`parenthetical` 可写发声方式、声音来源或与台词同时发生的短促可见动作。
+- 视频 Action 写具体可见表演，不用情绪或心理判断代替表情、视线、肢体和可见结果，也不写摄影调度；角色既有服装由场景 state 与资产承载，正文只写现场发生的外观变化或必要区分。
+- 手机、屏幕、照片、监控和回忆画面只描述直接可见的动作、物体及文字；没有画面、文字或台词证据时不推断状态、原因和结果。
+- `parenthetical` 仅在确有发声方式、声音来源或同时发生的短动作时使用；走位、接触和道具操作独立写 Action。
 
 ## 场界