@lingjingai/scriptctl 0.48.0 → 0.49.0

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

@@ -1,10 +1,10 @@
 # ingest workflow — 素材直转入库（文本 / 视频）
 
-适用：有外部素材要**转成 v3 剧本并入库**。统一入口 `scriptctl ingest`，看 source 后缀**自动分流**文本 / 视频；两条管线在同一个 govern 收尾汇合，产出**完全相同的 v3 `script.json`**。
+适用：有外部素材要**转成 v3 剧本并入库**。统一入口 `scriptctl ingest`，看 source 后缀**自动分流**文本 / 视频；两条管线在同一个 govern 收尾汇合，产出相同结构的 v3 `script.json`。视频、小说和非标准剧本统一执行 [production-writing-standard.md](production-writing-standard.md)。
 
 ```
-ingest --source-path <file|dir>   →   view / ingest status   →   publish
-   (抽取，产 workspace/script.json)      (自查/看进度)            (校验+入库)
+ingest --source-path <file|dir>   →   标准化复核   →   view / ingest status   →   publish
+   (抽取，产 workspace/script.json)       (内容完成门)       (自查/看进度)            (校验+入库)
 ```
 
 - 支持输入：**文本** txt / md / docx；**视频** 单个正片文件或**分集目录**（需 `GEMINI_API_KEY`）。pdf/json/xlsx 会被拒。
@@ -28,10 +28,28 @@ scriptctl ingest --source-path uploads/正片/
 - `--force`：**同源**重跑，清掉产物重来（**不能换源**）。
 
 管线（了解即可，产物都在 `workspace/`）：
-- **文本**：pass1 切块 → pass2 归一化（廉价模型出 markdown，确定性解析，**逐块 checkpoint**）→ pass3 合并 → 组装 `body.json`（正文骨架；台词/动作**逐字保真、不改写**）→ **串行 govern**（逐集：模型带累积上下文，从正文自己认人物 / 判 importance(featured=出图/background=龙套) / 提造型(每个=一张造型图，带描述) / 做身份合并；`serial/context_NNN.md`=喂模型的完整上下文、`serial/ep_NNN.md`=模型每集决策，**逐集 checkpoint、重跑续**）→ `script.json`（v3 校验）。
-- **视频**：pass1 Gemini 转录 → pass2 解析 → pass3 跨集花名册归并 + 状态归并（**贵，`roster.json`/`context.merged.md` 会复用**）→ pass4 二次画面校正 → pass5 纯剧情发声源审计 → pass6 apply + 汇入 govern 收尾。时间戳挂在 `extend.timestamp`。
+- **文本**：正文起点定位 → 切块 → 生产化归一（对白逐字保留；叙述转成具象 Action；按地点、时段、叙事线和持久状态变化分场）→ 合并组装 `body.json` → 串行资产/身份/state 治理 → 确定性编号 → v3 结构校验 + 生产规范 warning → `script.json`。逐块与串行窗口都有 checkpoint。
+- **视频**：逐集串行观看原视频，同时维护跨集人物花名册、剧情进展和造型；每集直接输出逐镜头 scenes + 资产增量 → 确定性人物归一、群体发声归一、编号和 state 物化 → v3 结构校验 + 生产规范 warning → `script.json`。时间戳写入 `extend.timestamp`，逐集 `ep/*.json` 和 `context.json` 支持断点续跑。
 
-## 二、看进度 / 自查
+### 提取与解析原则
+
+- 先忠实提取源素材可验证的对白、动作、顺序、人物状态和场景切换，再整理成标准 v3 资产与正文。
+- 视频以画面和声音为准；小说与非标准剧本把叙述转换成可拍摄 Action，同时保留原文事实、因果和人物关系。
+- 保留对白原文；允许为结构化和可拍摄性规范化叙述措辞，同时保持事实、因果、顺序、动作结果和状态不变。
+- 将无法确认的人物身份、动作主体、地点和状态保留为待复核项，不补写源素材没有表达的事实。
+- 使用同一套人物、路人群体、地点粒度、蒙太奇、对白、Action 和状态变化规则，保证不同输入最终落成一致的标准剧本。
+
+## 二、标准化复核
+
+`ingest` 生成且 `validate` 通过只代表结构与引用合法。publish 前按 [production-writing-standard.md](production-writing-standard.md) 逐集复核：
+
+1. 用 `actors / locations / props / states` 检查资产、去重、importance 和持久视觉状态。
+2. 用 `scenes --in <ep>` 检查唯一地点、场界、蒙太奇顺序和状态变化边界。
+3. 用 `actions --in <ep>` 检查说话人、群体发声、人物真名、动作链和可拍摄性。
+4. 视频对照画面与声音；文本对照原文，确认对白逐字保真，事实、因果、顺序、动作结果和状态没有改变或补造。
+5. 用 scriptctl 读写动词修正 `workspace/script.json`，再次运行 `validate`，完成内容复核后再 publish。
+
+## 三、看进度 / 自查
 
 ```bash
 scriptctl ingest status          # 人读：kind / state / 各 pass 进度（transcribe 40/57 (2 failed) ...）
@@ -41,9 +59,9 @@ scriptctl view --watch [--port N]# 实时监听面板：分阶段进度条 + 逐
 scriptctl summary --script-path workspace/script.json   # 抽完当普通剧本读
 ```
 
-`state`：`empty`（没开始）/ `incomplete`（在跑或中断、无硬错，重跑续）/ `failed`（有失败单元或校验没过）/ `ready`（`script.json` 生成且 v3 校验通过）。进度**纯从工作区真实文件推导**，不看任何独立状态机文件——不会出现"状态文件说完了但其实没完"。它报的是**管线事实**，不代表"已人工复核"（复核是你的完成门，另算）。
+`state`：`empty`（没开始）/ `incomplete`（在跑或中断、无硬错，重跑续）/ `failed`（有失败单元或校验没过）/ `ready`（`script.json` 生成且 v3 结构校验通过）。`validation.json` 的 production warning 标出仍需复核的内容规范问题。进度从工作区真实文件推导；它报的是管线事实，源素材一致性仍由复核完成门确认。
 
-## 三、🔴 抖动与重跑（大规模转剧本的常态）
+## 四、🔴 抖动与重跑（大规模转剧本的常态）
 
 模型抖动 / 限流 / 单集超时 / 偶发解析失败在几十集体量下**是正常现象，不是 bug**。护栏与恢复：
 
@@ -51,13 +69,14 @@ scriptctl summary --script-path 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 建的 | 换一个新的 `--workspace-path`，**别 `--force` 硬覆盖** |
 | `INGEST_VALIDATION_FAILED` | 最终 v3 校验没过 | 看 `workspace/validation.json` 的具体报错，用读写动词修 `--script-path workspace/script.json` 再 `publish` |
 | 持续 401/403/404 / 模型路由错 | 网关/密钥/模型环境问题（不是抖动，重跑也不好） | 如实告诉用户，别反复空跑、别编造成功。视频需 `GEMINI_API_KEY` |
 
 🔴 **绝不**：清工作区、删 checkpoint、手塞/手改中间文件来"绕过"失败。重跑 = 唯一正解；成功单元不会重跑，贵的花名册归并（`roster.json`）也会复用。
 
-## 四、入库 `publish`
+## 五、入库 `publish`
 
 ```bash
 scriptctl publish                 # 沙箱：自动写项目 DB 新 revision（SANDBOX_PROJECT_GROUP_NO 已注入）
@@ -70,7 +89,7 @@ scriptctl publish --remote --project-group-no 123   # 显式指定项目组
 - `SCRIPT_REVISION_CONFLICT` = DB 被别的 revision 改过：重新拉取当前剧本、合并你的改动，再 publish。
 - publish 幂等：同一份 script 重复 publish 不会产生新 revision（按内容 sha 去重）。
 
-## 五、复杂场景怎么接
+## 六、复杂场景怎么接
 
 - **转完先精修再入库**：`ingest` → 用 `--script-path workspace/script.json` 跑读写动词修（改归属、并角色、标龙套、补造型……）→ `publish`。
 - **入库后再改**：`publish` 之后直接对 DB（沙箱裸命令 = remote）继续精修，每次改都是新 revision。
@@ -78,7 +97,7 @@ scriptctl publish --remote --project-group-no 123   # 显式指定项目组
 - **超大剧集（几十集）**：并发默认已调好；失败就重跑到 `ingest status` 显示 `ready`。花名册归并只跑一次并复用，重跑很快。
 - **归并质量**：跨集角色归并靠文字锚点，相似角色可能误合/合过头。用 `roster.review.md`（视频）核对归并决策；发现误合，入库后用 `merge` 拆分/改名修正。
 
-## 六、抽完后的读写
+## 七、抽完后的读写
 
 抽取产物就是标准 v3 剧本，用 SKILL.md 里所有读写能力精修（目标记得指 `--script-path workspace/script.json`，或 publish 后指 DB）：
 - `summary` / `episodes` 看整本 + 分集梗概；`actions --in <ep>` 带 timestamp 看节奏。

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

@@ -0,0 +1,83 @@
+# 标准剧本生产写作规范
+
+适用：从零创作、视频提取、小说或非标准剧本解析、洗稿、对标仿写、转绘。目标是生成可供后期生产直接读取的 Schema v3 `script.json`。
+
+## 一、输入原则
+
+- 从零创作时，根据题材、集纲、人物关系和世界观补全可执行正文。
+- 视频提取时，以画面和声音为准，保留可验证的对白、动作、人物状态、场景切换和时间顺序。
+- 小说与非标准剧本解析时，把叙述转换成结构化人物、地点、道具、scene 和 action，保留原文事实与因果关系。
+- 提取与解析保留对白原文；允许为结构化和可拍摄性规范化叙述措辞，同时保持事实、因果、顺序、动作结果和状态不变。
+- 洗稿、对标和转绘时，从原剧读取结构与节奏，只把新内容写入目标剧本。
+- 提取与解析遇到不确定信息时保留待复核标记；不为满足格式补写源素材没有表达的动作、身份、状态或镜头。
+
+## 二、每集与每场的开写清单
+
+开始每一集和每一场前：
+
+1. 读取现有人物、地点、道具及其 states。
+2. 确定本场唯一地点、全部出场人物、全部使用道具和各自实际 state。
+3. 注册缺少的资产，定义需要独立视觉参考的持久状态。
+4. 建立 scene，绑定地点、人物、道具及实际 state。
+5. 读回 scene-ref，确认正文中的每项资产都能映射到本场引用。
+6. 写入正文；发现新增资产或状态时，先完成资产与引用再继续。
+
+## 三、人物、路人与群体
+
+- 为承担独立对白、动作、道具交接或剧情结果的个体建立 actor；一次性小角色使用 `importance background`。
+- 将固定人数、固定服装、固定站位或跨场连续出现的群体拆成可识别人物资产。
+- 将无法区分成员、无需连续造型的环境人群写成群体 Action。
+- 将群体共同发声写成 `--kind group --label <群体名>`。`group` 只属于该条 dialogue，不创建 actor、state 或视觉参考资产。
+- 当某个群体成员开始独立说话或行动时，先为该成员建立 actor 并绑定到 scene。
+- 仅有 group 发声、没有可识别 actor 的场面直接使用 group speaker；scene 绑定实际 location 与关键道具，不创建虚假人物。
+
+## 四、地点、门口与关联空间
+
+- 将可独立布置、可独立生成参考图、可重复引用的稳定物理空间建立为 location。客厅、卧室、卫生间、大厅、广场分别建地点。
+- 使用“豪宅·客厅”“豪宅·卧室”“剧院·舞台”“剧院·后台”这类统一命名表达空间归属，并在 description 中写明共享建筑风格和连接关系。
+- 摄影机留在当前空间时，scene 继续引用当前地点；门内可见空间写入 Action。
+- 摄影机或主要表演进入另一空间时建立新 scene，并引用新地点。
+- 舞台与后台交叉剪辑按每次切换建立相邻 scene；连续跟拍跨过空间边界时在边界处切换 scene。
+- 当前每个 scene 只支持一个 location。画面需要同时使用两个正式地点参考图时，报告结构限制；“客厅/卧室”只会形成一个复合地点资产，不能代替两个地点引用。
+- 当前没有地点组、父地点或共享美术继承。统一命名和 description 是现阶段的归属约定。
+
+## 五、地点时间与地点状态
+
+- 使用 scene 的 `environment.time` 表达白天、夜晚、黄昏等时间信息。
+- 当光线、布景、损毁或季节变化需要反复引用或独立生成视觉资产时，为 location 建立 state，例如“广场·夕阳”“大厅·停电”。
+- 将一次性的时间描述保留在 environment 或 Action 中；将持久、可复用的视觉变化建立为 state。
+
+## 六、Action 与 dialogue
+
+- 将 Action 写成可拍摄的行为链：行动者真名 + 具体动作 + 作用对象 + 空间方向 + 可见结果。
+- 使用人物真名指明每个行动者；对白内容可以自然使用人称代词。
+- 根据生产需要补充景别、机位、镜头运动和画面焦点。
+- 将抽象心理和评价转换成表情、肢体、道具变化、环境反应或明确对白。
+- 为每条 dialogue 绑定 `--actor` 或非角色发声源。将情绪、语气和短促伴随动作写入 `emotion`；将影响走位、道具或连续性的动作单独写成 Action。
+- 两人同时说话时写成相邻两条 dialogue，第二条的 `emotion` 以“同时”开头。当前结构不提供对白重叠时间轴。
+
+## 七、蒙太奇与并行剪辑
+
+- 同一地点、同一组视觉状态下的快速动作组合写成同一 scene 的连续 Action。
+- 跨地点蒙太奇为每个地点建立短 scene，按剪辑顺序排列，并用 transition 标明蒙太奇开始、切换和结束。
+- 为蒙太奇中需要参考图或连续性的地点、人物、道具建立资产，并在各自 scene 绑定实际 state。
+- 当前没有 montage group。使用相邻 scene、transition 和统一文本标记表达组合关系。
+- 纯空镜或完全无人镜头单独建 scene，绑定实际 location 与关键道具，不创建虚假人物。
+
+## 八、场内状态变化
+
+- 一个 scene 中，每个人物、地点和道具绑定一个有效 state。
+- 需要更换视觉参考资产的持久状态变化构成生产场界，即使地点和时间连续也建立新 scene。
+- 变化前 scene 绑定旧 state，在末尾写清变化动作；需要生成过程画面时给该 Action 添加 `transition_prompt`。
+- 变化后 scene 绑定新 state。同地点、同时段的状态边界保持独立，不参与场景合并。
+- 当前同一 scene 不能同时引用同一资产的多个 state。一个镜头需要变化前后两张状态图时报告结构限制。
+
+## 九、完成门
+
+1. 读回本集 `scenes` 与 `actions`。
+2. 检查每场唯一地点、全部出场人物、道具和 state 引用。
+3. 检查 Action 的真名、动作链、空间结果和可拍摄性。
+4. 检查 dialogue 的说话人、emotion 和群体发声类型。
+5. 检查场界、蒙太奇顺序和状态变化边界。
+6. 提取与解析任务对照源素材复核对白原文，以及事实、因果、顺序、动作结果和状态。
+7. 运行 `validate`。把结构通过与内容标准、源素材一致性分别报告。