@lingjingai/scriptctl 0.67.1 → 0.67.3

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lingjingai/scriptctl",
-  "version": "0.67.1",
+  "version": "0.67.3",
   "description": "剧本阶段统一 CLI：素材转 Script v4，并兼容 Script v3 的本地写作、精修、校验和发布。",
   "type": "module",
   "bin": {
@@ -22,6 +22,20 @@
   "engines": {
     "node": ">=22.22.0"
   },
+  "scripts": {
+    "build": "pnpm run clean && pnpm --filter @lingjingai/screenplay build && pnpm --filter @lingjingai/review-agent build && tsc && node scripts/bundle.mjs",
+    "clean": "rm -rf dist packages/screenplay/dist packages/review-agent/dist",
+    "postinstall": "node scripts/install-skill.mjs",
+    "install-skill": "node scripts/install-skill.mjs",
+    "prepublishOnly": "pnpm run build",
+    "pretest": "pnpm run build",
+    "test": "vitest run",
+    "pretest:coverage": "pnpm run build",
+    "test:coverage": "c8 --reporter=text --reporter=html --reporter=lcov --report-dir=coverage vitest run",
+    "test:watch": "vitest",
+    "typecheck": "tsc --noEmit",
+    "surface:snapshot": "node scripts/scriptctl-surface-snapshot.mjs"
+  },
   "dependencies": {
     "@anthropic-ai/sdk": "^0.111.0",
     "@google/genai": "^2.11.0",
@@ -39,8 +53,8 @@
     "zod": "^4.5.4"
   },
   "devDependencies": {
-    "@lingjingai/review-agent": "0.1.0",
-    "@lingjingai/screenplay": "0.1.0",
+    "@lingjingai/review-agent": "workspace:*",
+    "@lingjingai/screenplay": "workspace:*",
     "@types/jsdom": "^30.0.0",
     "@types/node": "^20.14.0",
     "@types/proper-lockfile": "^4.1.4",
@@ -68,18 +82,5 @@
     "@ai-sdk/openai-compatible": "^3.0.48",
     "@ai-sdk/provider": "^4.0.4",
     "@mastra/core": "^1.64.0"
-  },
-  "scripts": {
-    "build": "pnpm run clean && pnpm --filter @lingjingai/screenplay build && pnpm --filter @lingjingai/review-agent build && tsc && node scripts/bundle.mjs",
-    "clean": "rm -rf dist packages/screenplay/dist packages/review-agent/dist",
-    "postinstall": "node scripts/install-skill.mjs",
-    "install-skill": "node scripts/install-skill.mjs",
-    "pretest": "pnpm run build",
-    "test": "vitest run",
-    "pretest:coverage": "pnpm run build",
-    "test:coverage": "c8 --reporter=text --reporter=html --reporter=lcov --report-dir=coverage vitest run",
-    "test:watch": "vitest",
-    "typecheck": "tsc --noEmit",
-    "surface:snapshot": "node scripts/scriptctl-surface-snapshot.mjs"
   }
-}
+}

package/skills/scriptctl/SKILL.md

@@ -246,7 +246,8 @@ ASR 返回有效语句后，程序将整集对白与心声按顺序拼接，与
 
 全剧收敛审核必须成功执行 `validate` 才能正常结束；未完成时在同一会话内继续，保留已有工具操作，并共用原步数和总时间预算。整集默认 15 分钟总时限，耗尽后结束本轮审核。
 
-`review` 一个进程审完整本剧：剧本只解析一次进内存，按集扇出，最后单线程做全剧收敛。
+`review` 一个进程审完整本剧：剧本只解析一次进内存，按集扇出，再单线程做全剧收敛。视频人物按相关集覆盖来源，逐帧独立观察后组合自身阶段与主体衣服造型，同步场景、说话引用、正文和梗概。同衣服下实际不同的脸形体态分别建人物 state；独立操作物件的完整外观归 prop，持有、穿戴、数量和位置关系归 Action。snapshot 支持帧与 unassignedFrames 共同保留盲帧事实和未知，供人物与物件修订使用。`--media-model` 可单独选择取证 profile；固定形象组合在 profile 未指定 thinking 时使用 high，其余调用沿用各自配置。
+全局结束后，本次选集范围内的交接事项及依据已变化的已完成集自动补审一次，复用同次 ASR。逐集审核可依据已核形象为本集引用资产创建缺失状态，再迁移对应引用；已有共享状态内容保留。`--converge-only` 保留逐集待办，供下次正常审核续接。视频专项 `--converge-only --assets <ID列表>` 可配合 `--episodes` 限定人物取证范围；其中明确的 category=asset 未决事项定向进入现有资产升级，按正文与有效来源登记物件并绑定相关场景，不扩展为全剧扫描。普通全局审核保留一次既有资产升级。
 给 `-s` 按来源选择文本、漫画或视频核对，不给就检查剧本内部一致性，
 媒体工具不注册。每集**先落盘再输出**一行 NDJSON 到 stdout（`{"type":"episode",…}`，末行
 `{"type":"done",…}`）——收到一行就代表那一集的修改已经在文件里，中途挂掉只丢没报告的集。

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

@@ -118,7 +118,7 @@ scriptctl ingest -s uploads/正片/ -w workspaces/正片 \
 
 管线（了解即可，产物都在 `workspace/`）：
 - **文本**：正文起点定位 → 切块 → 生产化归一（对白/内心独白保留源语言，非台词正文转换成简体中文）→ 合并组装 `body.json` → 串行资产/身份/state 治理 → V3 中间校验 → 稳定 V4 身份分配 → V4 校验与生产规范 warning → `script.json`。
-- **视频**：逐集串行观看原视频并维护跨集人物、地点、道具、持久状态及其可见描述、最近三集剧情和未闭合线索 → 确定性治理 → V3 中间校验 → 稳定 V4 身份分配 → V4 校验与生产规范 warning → `script.json`。人物资产维护结构化身份画像（脸部结构与五官、肤色面部、稳定头发特征、骨架体型、固定标记和可确认声线）以及 3–6 条组合识别锚点；后续剧集按字段补充新看清的特征。角色语境只辅助判断，服装、妆容、饰品与临时外观归入 state。地点和道具继续使用稳定 appearance。Action 时间戳写入 `extend.timestamp`；逐集内容身份、`ep/*.json`、`context.json` 和身份映射共同支持断点续跑与严格尾部追加。人物证据不再要求 Gemini 额外选择时间点，也不在逐集阶段反复抽帧；全部剧集完成后，才从最终稳定的 actor/state 引用和 Action 时间戳一次性生成。
+- **视频**：逐集串行观看原视频并维护跨集人物、地点、道具、持久状态及其可见描述、最近三集剧情和未闭合线索 → 确定性治理 → V3 中间校验 → 稳定 V4 身份分配 → V4 校验与生产规范 warning → `script.json`。人物资产保存规范名、别名及已确认的身份关系，人物 state 独立记录本阶段自身可见外貌、持续服装整体造型和可辨声线；独立操作物件的完整外观归 prop，取放与穿戴关系归 Action。同衣服下脸形体态实质变化时建立独立人物状态，后续剧集按来源补齐对应资产。旧身份画像与识别锚点中的外貌按来源归入适用状态，使用完整 identity_revision 清空画像与锚点。地点和道具继续使用稳定 appearance。Action 时间戳写入 `extend.timestamp`；逐集内容身份、`ep/*.json`、`context.json` 和身份映射共同支持断点续跑与严格尾部追加。全部剧集完成后，从最终 actor/state 引用和 Action 时间戳生成浏览用人物证据；视频 ingest 逐集阶段沿用原片直接观察。
 - **造型身份**：临时登记、跨集 context 和正式身份映射统一按 NFC、连续空白归一化及小写后的状态名识别同一造型；展示名保留首次登记拼写。后续 `POLO` / `Polo` / `polo` 写法变化复用已有状态 ID 和引用。
 - **人物与状态原片证据**：`evidence/state-evidence.json` 是 version 2 sidecar。后处理先用场次人物引用确认“谁在这一场、穿哪套状态”，再优先选择该人物在本场普通台词的时间点，因为这比首次外观描写更可能出现清晰人物镜头；画外音、旁白、未入镜台词和 inner thought 不作为人物识别锚点。没有合格台词时，从明确提到目标人物的可见 Action 中按人物主体、服装词、半身/全身、面部可见度和多人歧义排序；仍没有人物直提时，可用不指向其他人物的带时间戳视觉 Action 作为低优先级造型兜底。多人共用时间点、背影、远景、模糊、纯道具和局部特写只降低造型候选的排序，不再因低于阈值导致整套已引用造型消失；人物识别图板仍要求最低可信分。场内存在多个无序 state 时不猜造型先后。每个人物最多保留 6 张跨场次、至少相隔 3 秒的代表帧，供客户端组成 3×2 人物图板；每套可确认造型保留最佳锚点的前 1 秒、原时刻、后 1 秒三帧，覆盖常见切镜偏差并供人类快速切换。图片在 `evidence/frames/`，样本按质量排序。抽帧失败不会让剧本 ingest 失败，而是在样本上标为 `unavailable`。sidecar 不保存原视频绝对路径，也不进入 `script.json`；人类复核和后续处理引用同一个 `evidence_id`。
 - **已有项目补生原片证据**：对最终 Script v4 运行 `scriptctl evidence -p <script.json> -s <视频文件或分集目录> -w <workspace>`。命令校验连续集号和剧本集数，直接复用上述本地选点与 ffmpeg 落图；不读取 ingest 中间文档、不调用 Gemini，也不会重新生成剧本。为了避免 NAS 全文件扫描，独立补生只用视频路径、大小和修改时间建立可重建缓存指纹；源文件原地替换后使用 `--force` 重抽。
@@ -131,7 +131,7 @@ scriptctl ingest -s uploads/正片/ -w workspaces/正片 \
 - 视频 Action 按原片分镜组织：每次切镜和连续镜头内的摄影变化都在实际时间点保留，重复镜头也不去重。正文如实记录可确认的景别、角度、机位、运镜、构图、焦点、画面主体，以及人物的画面占位、实际空间位置、姿态、面向、视线、接触、动作和可见结果。对白、分镜与动作按原片时间交错排列，不把跨多个镜头的台词或先后事件压缩成一条剧情概述。
 - 视频解析先完整盘点原声，再扫描可见行为，完成前复核全部人声和最后十秒。手机、屏幕、照片与回忆只写画面直接呈现的事实，不推断未被画面、文字或台词证明的状态、原因或结果。
 - 视频人物规范名只依据书面姓名或台词本名逐步升级；描述名、简称和旧规范名保存在同一人物的 aliases 中。确定性整合按完整名称解析人物、说话人、地点和道具引用，跨集保持同一资产身份；Action、对白和独白正文保留逐集提取的原文，正文中的历史称呼可通过资产 aliases 对照。
-- 视频资产登记同时保留实体描述与持久 state 描述。人物实体描述由身份画像、识别锚点和角色语境确定性渲染；身份画像只承载跨造型稳定、客观可见的特征，不用审美、性格、经历、关系、姿态或情绪代替形态信息。人物 default 与每项持久 state 都是独立完整的视觉造型描述，综合多个清晰镜头，从头到脚记录该套造型可见的妆发、头颈饰物、内外服装层次、单品颜色/材质/版型/领袖/开合/长度/图案、鞋袜、手套、饰品和持续破损污渍，不用“同默认”“沿用前述”代替具体外观；后续看到更多角度时以同名 state 补全描述，不从局部画面猜全身。地点和道具描述写可确认的结构、材质、颜色、陈设、形制和用途，不补造看不清的细节。
+- 视频资产登记同时保留实体描述与持久 state 描述。人物总描述记录已确认的身份、称谓和关系，外貌与声线由各阶段 state 独立承载。既有身份画像或识别锚点包含外貌时，按来源补齐适用状态，并用完整 identity_revision 清空画像与锚点。人物 default 与每项持久 state 独立描述该阶段的脸形、体态、肤况、妆发、持续服装整体造型和声线，包括相同的特征；同衣服下实际不同的脸形体态分别建 state。独立取放、持有或穿戴操作对象登记为 prop，完整可见外观归道具，人物与物件的持有、佩戴、摘下、数量和位置关系归 Action。人物 state、道具与 Action 共同复现场景，物件操作关系不扩展成人物状态组合。后续同阶段的更多角度可补全对应状态；遮挡或未确认部分保留未知，不从局部画面猜全身。地点和道具描述写可确认的结构、材质、颜色、形制和用途。
 - 视频对白前先建立画面可确认的持续状态；状态不变时不为每句对白补造动作。`parenthetical` 可写发声方式、声音来源或与台词同时发生的短促可见动作，影响走位、姿势、接触、道具或连续性的动作独立写 Action。
 - 视频正文以具体表情、视线、肢体和环境反应表达人物状态。角色既有服装由场景 state 与资产承载；换装、脱衣、破损、泥污等现场变化或必要区分写入 Action。
 - 每场填写一个明确时段：日、夜、晨、昏分别写入 `day`、`night`、`dawn`、`dusk`。原素材未直写时依据照明、作息、天空和上下文判断，并在人工复核中确认。

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

@@ -6,19 +6,19 @@
 
 1. 正文出现的可识别人物、地点和关键道具先注册为资产。
 2. 每个资产有且仅有一个 `default` state ID；它只标记底层基础状态。`state_name` 使用实际可辨认的外观名称，不写“默认”或“default”。需要独立视觉参考的持久变体再建 state。人物基础状态同样是一项完整基础造型，不复用人物身份描述。
-3. 人物资产描述以结构化身份画像和多条组合识别锚点为基础，细分记录脸部结构与五官、肤色面部、稳定头发特征、骨架体型、固定标记和可确认声线；使用客观形态与比例，不用审美、性格、经历、关系、姿态或情绪代替形态。每个持久 state 独立成篇，综合多个清晰角度，从头到脚记录可见妆发、服装层次、单品结构、材质纹理、配色、鞋袜、饰品及持续破损污渍；描述仅凭本 state 即可复现造型，不写“同默认”“沿用前述”。看不清的项省略，不从局部补造全身。地点和道具写可确认的恒定外观、关系或用途。
+3. 人物总描述只写已确认的身份、称谓和人物关系。人物 state 独立写全该阶段自身外貌、可辨声线与持续服装整体造型，各阶段相同的特征也完整保留。同衣服下实际不同的脸形、体态和肤况分别建 state。作为独立取放、持有或穿戴操作对象的物件登记为 prop，其完整形制、颜色、材质和尺寸归道具；持有、佩戴、摘下、数量和位置关系写入 Action。人物 state、道具资产与 Action 共同复现场景，独立物件的操作关系不扩展成人物状态组合。用具体可见形态与比例描述，遮挡或未确认部分保留未知。地点和道具自身的持续外观变化写入各自 state。
 4. 每个 scene 绑定实际地点、全部在场人物、关键道具及本场适用状态。
 5. V4 同一资产在一场只引用一次，通常只引用实际造型；本场确有持久外观变化时，`state_ids` 包含变化前后的状态，正文 Action 写清变化过程。
 6. actor speaker 必须属于当前 scene；显式 speaker state 必须在该 actor 的场景状态集合中。
 
 ## 人物身份与剧情外貌阶段
 
-- 人物总描述与识别锚点只记录跨阶段不变的身份特征。祛痘、胖瘦、年龄、伤病恢复、伪装和变身等承担剧情因果的可见差异写入对应 state；同一套衣服可以对应多个阶段。
+- 人物总描述与身份识别信息用于确认是谁；外貌与声线完整写入适用 state。同一套衣服可以对应多个外貌阶段，同一体态也可以对应多套造型。
 - 写作时先根据创作要求明确初始状态、触发变化的事件、变化后的状态和各自可见差异，再写场与 Action。分别使用“校服·祛痘前”“校服·祛痘后”等可辨认名称和独立完整描述。资产建模不依赖另增阶段字段，沿用现有 state / variant 与场景引用。
 - 原创作品可按明确创作要求设计外貌特征；提取或导入只能保留原片/原文提供的事实。只给出“丑”而没有具体特征时，保留该设定和信息边界，不擅自补出痤疮、体重数值或残障。面孔好看与否不能替代剧情功能，不能用肤色或族裔替代丑美设定。
 - 同一连续场有变身时，场引用包含前后状态，Action 明确触发时点和实际变化；显式 speaker state 对应发声时的阶段。回忆、照片、幻想或系统预演使用被呈现的阶段，返回现实恢复现实状态。状态集合无序，不用集合顺序表达时间。
 - `authoring compose` 的人物 `variants` 按阶段声明，`scene.actors` 可按不同 variant 列出同一人物；编译后合为一个人物引用的多个 state。使用实际 variant 名区分阶段，同一阶段新增视角或细节才沿用同名，不能让终态覆盖初始状态。
-- 审核同时检查“误拆”和“误合”：服装与持续外貌均一致才合并；只出现一次、衣服相同或同为受伤不能证明阶段相同。先检查首次亮相、变化前后及回忆/预演，再评价画面或文字呈现质量。
+- 审核同时检查“误拆”和“误合”：人物持续服装整体造型与自身外貌均一致才合并；只出现一次、衣服相同或同为受伤不能证明阶段相同。先检查首次亮相、变化前后及回忆/预演，再评价画面或文字呈现质量。
 
 ## Action 与对白
 
@@ -31,7 +31,7 @@
 - 视频提取以原片分镜组织 Action：每次切镜、重复镜头和连续镜头内可确认的摄影变化都保留；分镜、新动作、反应、接触、道具结果、进出场和空间关系变化按实际时间分别写入。
 - 视频对白沿用前文已经建立且未变化的持续状态；`parenthetical` 可写发声方式、声音来源或与台词同时发生的短促可见动作。
 - 视频对白逐句回看发声区间：与台词同时、不独立改变连续性的短促表演写入 `parenthetical`；在台词开始时发生的走位、姿势、接触、道具或空间关系变化先写独立 Action，不得错放到对白之后。已由前文建立且持续不变的动作不重复。
-- 视频 Action 如实写可确认的景别、拍摄角度、机位、运镜、构图、焦点和画面主体，并写具体可见的人物占位、实际空间位置、表情、视线、肢体、接触和可见结果；不推测原片无法确认的镜头参数、拍摄意图、情绪或心理。角色既有服装由场景 state 与资产承载，正文只写现场发生的外观变化或必要区分。
+- 视频 Action 如实写可确认的景别、拍摄角度、机位、运镜、构图、焦点和画面主体，并写具体可见的人物占位、实际空间位置、表情、视线、肢体、接触和可见结果；不推测原片无法确认的镜头参数、拍摄意图、情绪或心理。人物持续服装整体造型由人物 state 承载，独立物件外观由道具资产承载；正文写明现场变化、必要区分及人物与道具的时点关系。
 - 手机、屏幕、照片、监控和回忆画面只描述直接可见的动作、物体及文字；没有画面、文字或台词证据时不推断状态、原因和结果。
 - `parenthetical` 仅在确有发声方式、声音来源或同时发生的短动作时使用；走位、接触和道具操作独立写 Action。
 

package/skills/scriptctl/references/state-reference-repair.md

@@ -45,6 +45,18 @@ scriptctl validate -p "$S"
 
 同一套衣服在祛痘、减重、衰老、伤病恢复或变身前后可以需要独立 state。先用原片核验变化前后与回忆/预演，记录集、场/action、时间和实际可见差异，再用 `state` 建立可复现状态、`ref --state` 回写完整集合。连续场内同时出现前后阶段时保留两个状态，在对应动作中明确变化时点和阶段；按真实时空决定场界。
 
-人物总描述与识别锚点只承载跨阶段不变的事实，肤况、面颊软组织和胖瘦写入适用状态；同名状态的补充限于同一阶段。回忆按被回忆的阶段绑定，系统预演保留预演外貌。判断重复状态需同时核对服装与外貌阶段。
+人物总描述只写身份、称谓和关系；人物 state 独立描述自身外貌、声线与持续服装整体造型，遮挡和未确认部分保留未知。独立取放、持有或穿戴操作对象的完整外观归 prop；持有、佩戴、摘下、数量和位置关系归 Action，不按这些关系新增人物状态组合。人物 state、道具与 Action 共同复现场景。回忆按被回忆的形象绑定，预演保留预演外貌。复用状态需核对整段描述与当前来源一致。
 
-自动 `review` 的逐集阶段以 finding 记录已看原片的时间、地址与观察；需要全局描述/状态修改的项目交给末尾收敛阶段处理。本次运行的 wardrobe、actor-identity、asset findings 会随证据传入收敛；收敛先读回当前地址，只按达到证据准入的事实修改。`--converge-only` 没有本次逐集证据时只做结构核验，不能据此声称核实外貌阶段。
+## 原片人物修订事务
+
+先按本集原片记录目标人物的时段、自身可见外貌、持续服装整体造型、独立物件及其操作关系、变化与未知，再对照本集相关场、Action、显式 speaker 和资产状态目录形成修订方案。逐场列出本人物完整状态集合，指定需要调整的说话引用，精确替换动作正文或表演提示中的冲突片段，并同步本集梗概。对白和心声正文保留原声。
+
+图片组合复核分别保存人物画像和独立物件的逐帧使用关系。更正原帧观察时保留原始记录，人物画像、物件、正文与资产审核共同使用修订后的事实。物件使用者按可见连接确认，使用时点按对应帧记录；场景绑定表示该场出现。身体形状依据可见皮肤或能反映身体的贴身轮廓，宽松厚衣的外轮廓描述衣物，衣下形状保留未知。
+
+既有 state 整段描述与本集一致时复用其 ID；人物自身外貌或持续服装整体造型不同则新增具区分名称的 state；独立物件的差异按道具资产与 Action 修订。仅迁移已核实的本集引用，保留共享旧状态供其他引用使用。同场多个形象分别引用，Action 表达其时间与变化关系。
+
+同一人物阶段与主体服装可以由多个取证组共同支持。以来源充分且适用的画像作为状态代表，其他组通过 `reuseKey` 共用本次选定状态，各场及说话引用仍保留自身 snapshot 与实际 state ID 的映射。取证分组用于组织观察，人物状态按已确认的固定形象划分。
+
+场景状态集合只绑定有依据的形象。说话修订显式填写 `state:null` 可清除无依据的具体造型，保留人物指派、对白及时间；省略该条修订表示保持原值。人物身份与具体造型分别核实，尚未确认的部分按 Action 记录未决，已有依据的其他引用照常迁移。
+
+状态、场景引用、说话引用、正文片段和梗概在同一未绑定文件的 draft 中应用，全部操作成功后由调用方一次采纳并提交。记录实际修改地址、原片时段与未决项；事务成功表示修改已一致落盘，来源事实仍需逐项核对。仅全局审核也按已提供原片取证，缺片或预算未覆盖的范围保留未决。