@lingjingai/scriptctl 0.34.0 → 0.36.0

package/skills/scriptctl/SKILL.md

@@ -0,0 +1,293 @@
+---
+name: scriptctl
+description: "剧本 script.json 的读写 + 入库 CLI。转剧本：ingest（txt/md/docx 或视频，自动分流，产出 workspace/script.json）→ view 自查 → publish 入库。读：集/场/action/资产/状态/校验/时间戳/出场统计。写：台词/类型/归属/scene-ref 场景造型/内联发声源/importance/资产。选择器批量精修（读写共享 --in/谓词）、动词脚本 do（异构批量一事务）、结构调整（插/删/移/分/合）。ingest status 从工作区真实文件报进度。沙箱里默认读写项目 DB；本地电脑默认 --script-path 直接读写本地 script.json。剧本阶段做任何剧本相关读写、以及洗稿/对标/转绘里操作两个 script.json 之前都应加载。正文由你用原子能力写入。"
+version: "0.19.0"
+scriptctl_version: "0.36.0"
+author: "official"
+---
+
+# scriptctl
+
+`scriptctl` 读写结构化剧本 `script.json`（Schema v3：资产 人物/场景/道具 + 分集→场景→action + 场景级 cast/造型 + 内联发声源 + 引用完整性 + 校验），并把外部素材**转成剧本、入库**。**每次调用只作用于一份剧本**（由目标 flag 选定），所以「换剧本 = 换目标」。
+
+两条主线：
+- **转剧本入库**：`ingest`（抽取，产出 `workspace/script.json`）→ `view`（自查）→ `publish`（入库）。见 [references/ingest-workflow.md](references/ingest-workflow.md)。
+- **读写既有剧本**：查询 + 原子写 + 选择器批量 + `do`。
+
+## 先定目标：作用在哪份剧本上
+
+除 `ingest`/`view`/`publish` 外，每条读写命令都要知道读写哪份剧本，从下面选一个（互斥）：
+
+| 目标 | flag | 用在 |
+|---|---|---|
+| **项目 DB（最终剧本）** | `--remote [--project-group-no <no>]` | ☁️ **沙箱首选**。每次写进 DB 新 revision，边写边入库 |
+| **本地文件** | `--script-path <file>` | 🖥️ **本地电脑首选**。直接读写这一个 JSON，无 store、无 revision。洗稿/对标/转绘、试验、离线全走它 |
+| 本地约定 store | `--local` | `SCRIPTCTL_OUTPUT_DIR` 下的约定 store |
+
+- ☁️ **沙箱里**：后端注入 `SANDBOX_PROJECT_GROUP_NO`,**裸命令自动指向该项目 DB**（自动 remote），无需任何 flag。
+- 🖥️ **本地电脑上**：几乎每条命令都带 `--script-path <file>`。下文示例为简洁常省略它，实际本地使用请补上。
+- **不给任何目标、又不在沙箱**：CLI 拒绝猜测并报 `SCRIPT_NO_TARGET`。选一个目标。
+- `--script-path`（本地文件）与 `--remote`/`--local`/`--project-group-no`（store）**互斥**，混用报 `TARGET_FLAG_CONFLICT`。
+- `--workspace-path <dir>` 只给 `ingest`/`view`/`publish`/`ingest status` 用，指 ingest 工作区（默认 `workspace`），不是剧本目标。
+
+### 两个 script.json：洗稿 / 对标 / 转绘
+
+洗稿、对标仿写、转绘（换地区/换壳）里常常**同时开着原剧和新剧两份 script.json**：从原剧读结构与节奏，往新剧写。因为每条命令只作用于 `--script-path` 指的那一份，**换文件就是换这个 flag 的值**：
+
+```bash
+ORIG=原剧/script.json
+NEW=新剧/script.json
+
+# 读原剧（了解要对标什么）
+scriptctl summary                         --script-path "$ORIG"
+scriptctl actions --in ep_001             --script-path "$ORIG"   # 带 timestamp 列，看节奏
+scriptctl states act_001                  --script-path "$ORIG"   # 看人物状态弧线
+
+# 建/写新剧（把改写后的正文灌进去）
+scriptctl create --title "新剧名"          --script-path "$NEW"
+scriptctl do ep01.txt --apply             --script-path "$NEW"
+
+# 逐场对照：同一集在两份里并排看
+scriptctl scenes --in ep_003              --script-path "$ORIG"
+scriptctl scenes --in ep_003              --script-path "$NEW"
+```
+
+- 一次只碰一份。要「从 A 抄到 B」就是：`--script-path A` 读出来 → 你决定改法 → `--script-path B` 写进去。
+- 事件级对齐：原剧 `actions` 的 `timestamp` 列 + `scenes` 的 `t=t_start..t_end` 给出每段的时间跨度；对标时按这个跨度切新剧的段落。
+- 人物状态弧线：`states <actor>` 每个状态末尾的 `episodes=<区间>` 告诉你某个造型/形态在原剧哪些集出现，转绘时据此规划新剧的状态。
+
+## 能干什么
+
+### 读（永远只读、永远安全）
+
+| 想做什么 | 命令 |
+|---|---|
+| **了解剧情 / 全貌**：synopsis/worldview/style/logline/theme/main_characters + 标题/集数/场数/资产数（"这剧本是关于什么"先跑这个） | `scriptctl summary` |
+| 每集字数 / 场数 / action 数 **+ 每集剧情梗概** | `scriptctl episodes`（`--min-chars 1000` 找长集） |
+| 看某集的所有场（含 `t=t_start..t_end` 时段） | `scriptctl scenes --in ep_007` |
+| 看某场的资产 + action 数 | `scriptctl scenes --in ep_007/scn_005` |
+| **按正文搜某句话定位 action**（最常用） | `scriptctl actions --grep "<片段>"` |
+| 列某集所有 action（TSV 含 **timestamp** / speaker / 正文 / 情绪） | `scriptctl actions --in ep_001` |
+| 看单条 action 正文 | `scriptctl actions --in ep_001/scn_001#3` |
+| action 多维过滤 | `scriptctl actions --in ep_001 --type dialogue --actor act_001 --has speaker` |
+| 某角色出现的所有场 | `scriptctl scenes --has-actor act_001`（另有 `--has-location`/`--has-prop`） |
+| **列某资产的所有 state + 状态弧线**（改造型前必查） | `scriptctl states act_001`（裸 id 即可，也认 `actor:act_001`） |
+| 资产**出场统计**（几场/几集，压成集区间） | `scriptctl actors --counts` / `locations --counts` / `props --counts` |
+| 某资产 / 状态 / speaker 反查 | `scriptctl refs actor:act_001`（`refs spk_001` 反查发声源） |
+| 当前校验问题 / 跑校验 | `scriptctl issues --severity error` / `scriptctl validate` |
+
+**读侧要点：**
+- `actions` TSV 列：`addr timestamp type speaker actor emotion content`。`timestamp` 是该 action 的 `extend.timestamp`（集内 `M:SS`，无则空）。事件跨度 = 首末 action 时间戳之差。`speaker` 列是 v3 内联发声源（actor 或 system/broadcast/offscreen/group）。
+- `scenes` 行尾 `t=<t_start>..<t_end>`：该场首/末带时间戳 action 的时间。
+- `states <asset>`：接受裸 id（`act_001`/`loc_001`/`prp_001`）；每个状态末尾 `episodes=<区间> (N eps, M scenes)` 是该状态的**集弧线**（按 scene 造型引用统计）；从不被引用的状态显示 `episodes=none`。
+- `--counts`：追加 `scenes=N episodes_count=M episodes=<区间>`。默认不带，保持精简。
+
+### 写（单点：第一个位置参数是 address。多点：见「选择器批量」）
+
+| 想做什么 | 命令 |
+|---|---|
+| 改 action 正文（替换/删一段） | `scriptctl replace <ep/scn#idx> --from X --to Y`（加 `--regex`；`--to` 省略即删） |
+| 改 action type | `scriptctl type <ep/scn#idx> <dialogue\|action\|inner_thought\|transition>` |
+| 改 action 归属角色（内联发声源） | `scriptctl actor <ep/scn#idx> <act_id\|none>` |
+| 改/清 action 情绪 | `scriptctl emotion <ep/scn#idx> "紧张"` / `--clear` |
+| **把某行设成对白 + 定内联发声源** | `scriptctl dialogue <ep/scn#idx> --actor act_001`（角色）／ `--kind <system\|broadcast\|offscreen\|group> [--label 广播]`（非角色声源）。同时把 type 翻成 dialogue |
+| **设/改场景里某资产的造型（state）** | `scriptctl scene-ref <ep/scn> <actor\|location\|prop>:<id> --state <state_id>`（`--state none` 上场但无造型；`--clear` 保留引用清造型；`--remove` 整个移出场景）。location 单值（set 即替换） |
+| 改资产名/描述/别名/role | `scriptctl rename actor:<id> "X"` / `describe` / `alias --add X` / `role <主角\|配角>` |
+| **设资产重要度**（决定下游是否生成视觉资产+状态跟踪） | `scriptctl importance <actor\|location\|prop>:<id> <featured\|background>`（featured=主角/配角；background=龙套/背景，下游跳过） |
+| 给资产加 state | `scriptctl state-add actor:<id> "震惊"` |
+| **改/删某个 state** | `scriptctl state-rename actor:<id>/<st_id> "新名"` / `scriptctl state-delete actor:<id>/<st_id> --strategy remove`（引用修复核验见 [references/state-reference-repair.md](references/state-reference-repair.md)） |
+| 挂自由维度键值 | `scriptctl extend <addr> --key <名> --value <JSON>`（如给 action 挂 `timestamp`） |
+| 合并资产/场景 | `scriptctl merge actor:<src> --into actor:<dst>` |
+| 删 action/scene/资产 | `scriptctl delete <addr>`（资产要 `--strategy replace\|remove`） |
+| 插 action/scene | `scriptctl insert <ep/scn> --type X --content X [--emotion X] [--actor <id>]` / `insert <ep> --location <id>` |
+| 移动/分场 | `scriptctl move <addr> <to>` / `split <ep/scn> --at <idx>` |
+| 设整本/分集剧情梗概 | `scriptctl synopsis "整本梗概"` / `scriptctl synopsis ep_001 "本集梗概"`（`synopsis generate` 用 LLM 批量生成） |
+| 设世界观 | `scriptctl worldview <现代\|古代历史\|...>` |
+
+> **v3 变化（相对旧版）**：① 发声源不再是独立实体——`add-speaker`/`speakers` 没了，改成**对白行内联**（`dialogue --actor/--kind`、`actor <at> <id>`）。② 造型不再挂在 action 上——`state-change` 没了，改成**挂在场景级 cast 引用**上（`scene-ref <ep/scn> <kind:id> --state`）。③ `context` 命令改名 `scene-ref`。④ 新增 `importance`。
+
+### 选择器批量（一条命令扫一片 —— 读写共享同一套选择语法）
+
+把单点写动词的「address」换成一个**选择**，它就对**所有命中的 action** 一次性改。支持选择器的写动词：`replace / type / actor / emotion / transition`。
+
+- **选范围 `--in`**：`ep_003..ep_007`（集区间）/ `ep/scn` 区间 / 逗号多区间 / `'*'`（全本）。
+- **加谓词**（和 `actions` 查询**完全一样**的 flag，AND 组合）：`--type` `--actor` `--grep /re/` `--has speaker|transition`。
+- 🔴 **护栏：多点写默认 dry-run**（回显命中数 + blast-radius，不落盘），加 **`--apply`** 才真写。单点（给 address）仍直写。
+
+```bash
+# 清全本所有 action 开头的 [xxx] 标记：一条正则扫全本
+scriptctl replace --in '*' --regex --from '^\s*\[[^\]]*\]\s*' --to ''          # 先看命中
+scriptctl replace --in '*' --regex --from '^\s*\[[^\]]*\]\s*' --to '' --apply  # 落地
+# 第3-7集里某角色的对白统一改归属（谓词直达，无需先查地址）
+scriptctl actor --in ep_003..ep_007 --actor act_001 act_009 --apply
+# 第3-7集里某角色的对白统一标情绪
+scriptctl emotion --in ep_003..ep_007 --actor act_001 "紧张" --apply
+```
+
+> 先 discover 后 mutate 用**同一套 flag**：`scriptctl actions --in … --actor …` 查出来是哪些，换个动词就改哪些。`actions --json` 带结构化 `rows[]`，`actions … --format addr` 直接吐裸地址流喂 `xargs`。scene-ref/importance/dialogue 是**单点**动词，不进选择器批量。
+
+### 异构批量 `do`（一组各不相同的改动 = 一段动词脚本 = 一个事务）
+
+每行就是一条**去掉 `scriptctl` 的命令**，`#` 注释、空行随意；整段全成或全不成。比手写 patch JSON 省心（动词原样，不猜字段名）。
+
+```bash
+scriptctl do edits.txt           # 默认 dry-run（预演 + 校验，不写）
+scriptctl do edits.txt --apply   # 一次性原子落盘
+cat edits.txt <<'EOF'
+replace   ep_001/scn_001#3 --from "台下掌声雷动" --to ""
+dialogue  ep_001/scn_002#1 --actor act_001
+scene-ref ep_001/scn_001 actor:act_001 --state st_calm
+merge     actor:act_005 --into actor:act_001
+insert    ep_001/scn_006 --type action --content "暗夜，街道空无一人。"
+EOF
+```
+
+`do` 也读 stdin（`scriptctl do -`）。结构性动词（insert/delete/move/split/merge）**只能**走单点或 `do`，不进选择器批量（索引会漂移）。目标 flag（如 `--script-path`）加在 `do` 命令本身上，整段脚本共用同一目标。
+
+### 建（从零起一本剧本，不要 address，第一个位置参数是名字）
+
+| 想做什么 | 命令 |
+|---|---|
+| 建空白剧本（v3 骨架） | `scriptctl create [--title X]` |
+| 加人物 | `scriptctl add-actor "林夏" [--role 主角\|配角] [--description X] [--alias X]` |
+| 加场景地点 | `scriptctl add-location "便利店" [--description X]` |
+| 加道具 | `scriptctl add-prop "怀表" [--description X]` |
+| 加分集 | `scriptctl add-episode [--title X]` |
+
+id 自动按序分配（`act_001` / `loc_001` / `prp_001` / `ep_001` / `scn_001`…）。建完资产与集，用 `insert` 建场景、灌正文（正文 = 你想好文字用原子能力写入）。整本怎么搭见 [references/atomic-write-workflow.md](references/atomic-write-workflow.md)。
+
+### Address 格式（决定 verb 作用对象，自动分发）
+
+| 形态 | 类型 | 例 |
+|---|---|---|
+| `ep_001/scn_001#3` | action | `replace` / `type` / `actor` / `emotion` / `dialogue` |
+| `ep_001/scn_001` | scene | `scene-ref`（配 `<kind:id>`）/ `split` |
+| `actor:act_001` / `location:loc_001` / `prop:prp_001` | asset | `rename` / `importance` / `merge` / `delete` |
+| `actor:act_001/st_001` | asset state | `state-rename` / `state-delete` |
+| `ep_001` | episode | `insert`（scene）|
+| `spk_001` | speaker 实体 | `refs` / `delete` |
+
+> `states` 查询额外接受裸资产 id（`act_001`/`loc_001`/`prp_001`），按前缀推断种类。其它 verb 仍要完整 address。
+
+## 经典最短路径
+
+**改某句台词**：grep 找地址 → replace 落字。
+```bash
+scriptctl actions --grep "台下掌声雷动"
+# → ep_001/scn_001#3	0:14	action	...	台下掌声雷动。
+scriptctl replace ep_001/scn_001#3 --from "，台下掌声雷动" --to ""
+```
+`--to` 省略即删除。一个 action 内多次命中默认拒绝，把 `--from` 写更长更唯一，或显式 `--all`。
+
+**改某行归属 / 定发声源**：
+```bash
+scriptctl dialogue ep_001/scn_003#5 --actor act_002        # 这行是 act_002 说的
+scriptctl dialogue ep_001/scn_003#7 --kind broadcast --label 广播   # 非角色声源
+```
+
+**设场景里某人的造型**：
+```bash
+scriptctl states act_001                                    # 先看有哪些 state
+scriptctl scene-ref ep_001/scn_003 actor:act_001 --state st_injured
+```
+
+**整理重复角色**：
+```bash
+scriptctl refs actor:act_005                 # 先看 act_005 出现在哪
+scriptctl merge actor:act_005 --into actor:act_001
+```
+
+**标龙套（下游省算力）**：
+```bash
+scriptctl actors --counts                                   # 看谁出场少
+scriptctl importance actor:act_042 background
+```
+
+**修校验问题**：
+```bash
+scriptctl issues --severity error
+# → STATE_NOT_MATERIALIZED at ep_001/scn_003 actor:act_001
+scriptctl states act_001                                    # 确认合法 state_id
+scriptctl scene-ref ep_001/scn_003 actor:act_001 --state st_calm
+```
+
+**批量精修（同构一片 → 选择器；异构多点 → `do`）**：
+```bash
+scriptctl replace --in ep_003..ep_007 --from 陈总 --to 陈墨 --all          # 同构：默认 dry-run
+scriptctl replace --in ep_003..ep_007 --from 陈总 --to 陈墨 --all --apply  # --apply 落地
+scriptctl do fixes.txt --apply                                            # 异构：一段动词脚本一事务
+```
+
+## 转剧本入库：ingest → view → publish
+
+有外部素材（剧本文本 / 分镜 / 小说 / 视频）要变成入库剧本时，走这条线。**统一入口是 `ingest`，自动分流文本/视频**。完整细节 + 复杂场景见 [references/ingest-workflow.md](references/ingest-workflow.md)。
+
+| 项目状态 | 走 |
+|---|---|
+| 没剧本文本，从零写（题材/灵感/集纲在手） | `create` + `add-*` + `insert` + `do`（正文你自己写），然后 `publish` |
+| 已有剧本/分镜/小说文本（txt/md/docx） | `scriptctl ingest --source-path <file>` → `view` 自查 → `publish` |
+| 有视频（正片文件或分集目录） | `scriptctl ingest --source-path <file\|dir>` → `view` 点击定位复核 → `publish` |
+
+三步：
+
+```bash
+# 1) 抽取：产出 workspace/script.json（不入库）。文本/视频看后缀自动分流。
+scriptctl ingest --source-path uploads/剧本.docx           # 文本
+scriptctl ingest --source-path uploads/正片/                # 视频分集目录（需 GEMINI_API_KEY）
+
+# 2) 看进度 / 自查
+scriptctl ingest status                                     # 从工作区真实文件报进度（见下）
+scriptctl view                                              # 生成 review.html（视频版可点击定位）
+scriptctl summary --script-path workspace/script.json      # 抽完后当普通剧本读/改（注意目标是本地文件）
+
+# 3) 入库：校验 v3 通过后写进目标 store
+scriptctl publish                                          # 沙箱：自动写项目 DB 新 revision
+scriptctl publish --local                                  # 本地：写 SCRIPTCTL_OUTPUT_DIR
+```
+
+- 🔴 **ingest 不入库**——它只产出 `workspace/script.json`。**入库是 `publish` 这独立一步**（沙箱里转完必须 publish，否则后端/前端看不到剧本）。
+- 抽取产物在 `workspace/` 下（默认目录，可 `--workspace-path` 改）。抽完后可用所有读写动词加 `--script-path workspace/script.json` 精修，再 `publish`；或 publish 入库后再对 DB（remote）精修。
+- publish 冲突（`SCRIPT_REVISION_CONFLICT`）= DB 被别的 revision 改过，重新拉取再 publish。
+
+### `ingest status`：进度按真实文件判定
+
+```bash
+scriptctl ingest status            # 人读：kind/state/各 pass 进度
+scriptctl ingest status --json     # 机器：.status = {kind,state,phase,passes[],units,validation,errors[]}
+```
+- `state`：`empty`（没开始）/ `incomplete`（在跑或中断、无硬错，重跑续）/ `failed`（有失败单元或校验没过）/ `ready`（script.json 已生成且 v3 校验通过）。
+- 进度**纯从工作区文件推导**（没有独立状态机文件，不会和真实状态不同步）。它报的是"管线事实"，不代表"已人工复核"——复核是你的完成门，另算。
+
+### 🔴 遇到错误怎么办（抖动是常态，重跑即续）
+
+大规模转剧本时，模型抖动 / 限流 / 单集超时 / 偶发解析失败是**正常现象**，不是 bug。护栏与恢复：
+
+- **`*_INCOMPLETE`（NORMALIZE / TRANSCRIBE / CORRECT / SPEAKER）= 可续的抖动**：部分单元失败，工作区留下 `passN/*.error.json` sidecar。**直接重跑 `scriptctl ingest`（同 source、同 workspace）即可**——它从 checkpoint 续，只补失败单元，成功的不重跑。跑完 `ingest status` 看还剩几个失败，多跑几次直到收敛。
+- 🔴 **不要**清工作区、不要删 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`。
+- 支持的输入：txt/md/docx + 视频（文件或分集目录）；其它（pdf/json/xlsx）会被拒。
+
+## 资产 state 判定（`state-add` / `scene-ref --state` 通用规则）
+
+只有**持久、可复用、需独立生成视觉资产的外观变体**才进 `states[]`。身份/年龄/职业/情绪/动作/姿态/临时伤病/混合状态**不**算状态，放 description 或 action 文本。
+
+**默认状态（default）**：每个有 `states[]` 的资产必须有且仅有一个 `state_id: "default"`（最常见常态外观，保留可读 state_name）。`ingest` 会自动把「默认/最常见」那档 canonical 成 `default`；手动 `state-add` 给原先无状态的资产加第一个 state 后，若校验报 `DEFAULT_STATE_MISSING`，把最常见那档的 state_id 设成 `default`。
+
+合并/删除 state 时，必须确认引用它的场景 `scene-ref --state` 已被正确修复；操作见 [references/state-reference-repair.md](references/state-reference-repair.md)。
+
+## 通用边界
+
+- 🔴 **不要加 `--json`**。默认列表/查询输出是给 agent 读的 TSV/行式文本（地址单独成列），比 JSON 更省 token、更好决策。除非真要 parse 字段喂给下一步程序（`actions --json` 有结构化 `rows[]`，`ingest status --json` 有 `.status`，或 `--format addr` 取裸地址流）。
+- 🔴 **多点写默认 dry-run**：`replace/type/actor/emotion/transition` 一旦带 `--in`/谓词就是预演（回显命中数，不落盘），确认后加 `--apply` 才真写。单点（给 address）直写。
+- 🔴 **手写批量走 `do`，不要手撸 patch JSON**。`scriptctl patch <file|->` 是**机器/jq 管道**接口（`… --json | jq '[…]' | scriptctl patch -`）；人/agent 手写一律用 `do`。需要 op schema 用 `scriptctl patch --schema [<op>]`。
+- 🔴 **本地用记得带 `--script-path <file>`**；洗稿/对标/转绘里两份剧本就是两个不同的 `--script-path`，一次只碰一份。
+- 🔴 **沙箱里转完剧本要 `publish`**：`ingest` 只产 `workspace/script.json`，不 publish 后端/前端看不到。
+- 只有 `ingest` 会请求大模型；`ingest status`、`view`、`publish`、`summary/actions` 等查询、`synopsis/replace/patch/do` 等读写命令**不打模型**。
+- 多态 verb（`delete`/`merge`/`move`/`describe`/`rename`/`insert`/`scene-ref`）按 address 格式分发；flag 用错 kind 会直接报错（不静默忽略）。
+- 互斥 flag（`scene-ref` 的 --state/--clear/--remove；`dialogue` 的 --actor/--kind；`transition` 的 --process+--contrast/--clear）只能传一个，多传报 `*_FLAG_CONFLICT`。
+- `mock` provider 仅测试，禁止作为交付；provider 失败不降级 mock。
+- 工具失败排查根因，不手工拼装 JSON 绕过校验。
+
+参数/默认值/退出码以 `scriptctl <cmd> --help` 为准。功能变更用 `scriptctl changelog` 查。

package/skills/scriptctl/references/atomic-write-workflow.md

@@ -0,0 +1,117 @@
+# 从零原子写 — 你自己写正文，scriptctl 只搭骨架
+
+适用：**没有现成剧本文本**，从零写（手里只有题材 / 灵感 / 集纲）。
+
+核心理念：**写手是你**。你自己想好每一句正文，用原子能力把它灌进结构化剧本里。scriptctl 负责「合法的骨架 + 引用完整性 + 校验」，不负责「写得好不好」。
+
+---
+
+## 端到端流程
+
+```
+create（空白剧本）
+  → worldview                 设世界观
+  → add-actor / add-location / add-prop   注册资产（+ state-add 给外观档位）
+  → add-episode               建分集
+  → synopsis                  写整本 / 分集梗概
+  → insert <ep> --location    建场景
+  → insert <ep/scn> --type ... --content "正文" [--emotion "情绪"] [--actor <id>]  逐 action 灌正文
+  → dialogue / scene-ref / transition / importance       发声源、场景造型、重要度
+  → validate                  收尾自查
+  → publish                   入库（沙箱必做）
+```
+
+> v3 里发声源是**对白行内联**（`dialogue <at> --actor/--kind`，或 `insert --actor`），没有独立的 speaker 实体命令；造型挂在**场景 cast 引用**上（`scene-ref <ep/scn> <kind:id> --state`），没有 action 级 state-change。
+
+资产/分集/场景的 id **自动按序分配**：第一个 actor 是 `act_001`、location 是 `loc_001`、prop 是 `prp_001`、episode 是 `ep_001`、它下面第一场是 `scn_001`……所以你能在后续命令里直接引用这些可预测的 id（也可以 `--id` 显式指定）。
+
+---
+
+## 两种写法
+
+### A. 增量（少量、边想边写）：逐条原子 verb
+
+```bash
+scriptctl create --title "夏夜便利店"
+scriptctl worldview 现代
+scriptctl add-actor 林夏 --role 主角 --description "高三女生，沉默寡言"
+scriptctl add-actor 陈默 --role 配角 --description "便利店夜班店员"
+scriptctl add-location 便利店 --description "24h 便利店，冷白光"
+scriptctl add-episode --title "第一集：相遇"
+scriptctl synopsis "雨夜便利店里，林夏与夜班店员陈默因一场意外相遇。"
+scriptctl synopsis ep_001 "林夏雨夜进入便利店，发现陈默似乎认识她。"
+scriptctl insert ep_001 --location loc_001 --time night --space interior   # → scn_001
+scriptctl insert ep_001/scn_001 --type action   --content "雨夜，林夏推门进店，浑身湿透。" --emotion "狼狈"
+scriptctl insert ep_001/scn_001 --type dialogue --content "欢迎光临。" --actor act_002
+scriptctl insert ep_001/scn_001 --type inner_thought --content "又是他。" --actor act_001
+scriptctl validate
+```
+
+### B. 整集 / 整本（推荐）：一段 `do` 动词脚本，一个事务
+
+一集几十个 action 不要敲几十条命令，也**不要手撸 patch JSON**。写一段 `do` 脚本——**每行就是一条你会敲的命令**（去掉开头的 `scriptctl`），按依赖顺序排好（先建资产、再 `add-episode`、再 `insert` 场景、最后 `insert` action），一次落地。同一段 `do` 内按顺序执行，因此 `add-episode` 产出的 `ep_001` 能被靠后的 `insert` 直接引用。
+
+```bash
+scriptctl create --title "夏夜便利店"   # 先有空白剧本
+scriptctl do ep01.txt                  # 默认 dry-run：内存里跑 + 校验，不落库
+scriptctl do ep01.txt --apply          # 确认后真写
+```
+
+`ep01.txt` 形如（每行一条动词，`#` 注释、空行随意）：
+
+```
+worldview 现代
+add-actor 林夏 --role 主角 --description "高三女生，沉默寡言"
+add-actor 陈默 --role 配角 --description "便利店夜班店员"
+add-location 便利店 --description "24h 便利店，冷白光"
+add-episode --title "第一集：相遇"
+synopsis "雨夜便利店里，林夏与夜班店员陈默因一场意外相遇。"
+synopsis ep_001 "林夏雨夜进入便利店，发现陈默似乎认识她。"
+insert ep_001 --location loc_001 --time night --space interior
+insert ep_001/scn_001 --type action   --content "雨夜，林夏推门进店。" --emotion "狼狈"
+insert ep_001/scn_001 --type dialogue --content "欢迎光临。" --actor act_002
+```
+
+动词与单条命令完全一致（参数见 `scriptctl <verb> --help`）。`do` 也读 stdin：`… | scriptctl do -`。
+
+> 机器/程序化生成的批量（如 jq 变换查询结果）才用 JSON：`scriptctl actions … --json | jq '[…ops…]' | scriptctl patch -`。手写一律 `do`。
+
+---
+
+## 写到哪里去（落库）
+
+`create` 和所有编辑 verb 共用同一套目标解析，三选一：
+
+| 目标 | 怎么走 | 说明 |
+|---|---|---|
+| **本地文件** | `--script-path <file>` | 🖥️ **本地电脑首选**。直接读写这一个 JSON，无 store、无 revision。洗稿/对标/转绘、试验都走它 |
+| **DB（项目组）** | `--remote`（沙箱裸命令自动 remote），或 `--project-group-no <no>` | ☁️ **沙箱首选**。每个编辑 op 直接写进 DB 的新 revision，边写边入库 |
+| **本地约定 store** | `--local` | 写 `SCRIPTCTL_OUTPUT_DIR` 下的约定 store |
+
+- 🖥️ **本地**：`scriptctl create --script-path new.json` 起本，之后每条编辑都带同一个 `--script-path new.json`；想入库时用 `scriptctl publish`（读某个 `workspace/script.json` 写 store）或直接对 DB 写。
+- ☁️ **沙箱**：直接对 DB 写（`create` → 编辑，不加 flag = 自动 remote），写完就在库里。想先本地攒好再入库，就 `create --script-path draft.json` → 全程 `--script-path draft.json` 编辑，最后把它放进 `workspace/` 用 `scriptctl publish` 入库。
+
+### 两份 script.json（洗稿 / 对标 / 转绘）
+
+同时开着原剧与新剧时，一次只作用于 `--script-path` 指的那份：从原剧读（`summary`/`actions`（带 timestamp）/`states`（带弧线）/`scenes`（带时段）），往新剧写（`create` → `do --apply`）。换文件 = 换 `--script-path` 的值。详见 SKILL.md「两个 script.json」。
+
+---
+
+## 校验语义（重要）
+
+「没填满」不拦路，「结构坏了」才拦：
+
+- **只提醒（warning，不影响 `validate` 通过）**：空剧本、空集、空场、场景没地点、资产缺描述。所以你可以先把骨架搭出来、逐步填，中途 `validate` 也能过。
+- **硬错误（拦截）**：悬挂引用、重复 id、非法枚举、缺 id/name、scene_id 不递增、非人类注册成 actor —— 这些会破坏 DB 图结构，必须修。
+
+随时 `scriptctl validate` 看整体，`scriptctl issues --severity warning` 专看「还没填」的清单。
+
+---
+
+## 提醒
+
+- 资产 state 判定（哪些进 `states[]`）见 SKILL.md「资产 state 判定」。
+- 非角色发声源（系统/广播/画外/群体）用 `dialogue <at> --kind system|broadcast|offscreen|group [--label ...]`（对白行内联），**不要**注册成 actor。
+- 角色名保持规范：别在名字里塞状态注解（`林夏（受伤）`会被拒），外观档位用 `state-add`。
+- action 情绪放 `emotion` 字段：插入时用 `insert ... --emotion "紧张"`，修改时用 `emotion <ep/scn#idx> "紧张"` / `emotion <ep/scn#idx> --clear`，不要把 `[紧张]` 这类标记塞进 content。
+- 参数 / 退出码以 `scriptctl <cmd> --help` 为准。

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

@@ -0,0 +1,85 @@
+# ingest workflow — 素材直转入库（文本 / 视频）
+
+适用：有外部素材要**转成 v3 剧本并入库**。统一入口 `scriptctl ingest`，看 source 后缀**自动分流**文本 / 视频；两条管线在同一个 govern 收尾汇合，产出**完全相同的 v3 `script.json`**。
+
+```
+ingest --source-path <file|dir>   →   view / ingest status   →   publish
+   (抽取，产 workspace/script.json)      (自查/看进度)            (校验+入库)
+```
+
+- 支持输入：**文本** txt / md / docx；**视频** 单个正片文件或**分集目录**（需 `GEMINI_API_KEY`）。pdf/json/xlsx 会被拒。
+- `ingest` **不入库**：只产 `workspace/script.json`（默认工作区 `workspace`，可 `--workspace-path` 改）。入库是独立的 `publish`。
+- 产物随后就是普通剧本：任何读写动词加 `--script-path workspace/script.json` 即可精修。
+
+## 一、抽取 `ingest`
+
+```bash
+# 文本
+scriptctl ingest --source-path uploads/剧本.docx
+# 视频（分集目录，文件名带集号；单文件也行）
+scriptctl ingest --source-path uploads/正片/
+```
+
+常用 flag：
+- `--workspace-path <dir>`：工作区根（manifest + 各 pass 目录 + 产物）。默认 `workspace`。
+- `--concurrency <n>`：文本/归并 fanout 并发（文本默认 80，视频默认 30）。
+- `--video-concurrency <n>`：视频上传+转录并发。默认 10。
+- `--fps <n>`：视频采样帧率（>1 解锁亚秒级时间码）。默认 3。
+- `--force`：**同源**重跑，清掉产物重来（**不能换源**）。
+
+管线（了解即可，产物都在 `workspace/`）：
+- **文本**：pass1 切块 → pass2 归一化（廉价模型出 markdown，确定性解析，**逐块 checkpoint**）→ pass3 合并 → 组装 `script.initial.json` → pass5 govern（资产 recall/refine → 合并/canonical/裁剪）→ `script.json`（v3 校验）。
+- **视频**：pass1 Gemini 转录 → pass2 解析 → pass3 跨集花名册归并 + 状态归并（**贵，`roster.json`/`context.merged.md` 会复用**）→ pass4 二次画面校正 → pass5 纯剧情发声源审计 → pass6 apply + 汇入同一 govern 收尾。时间戳挂在 `extend.timestamp`。
+
+## 二、看进度 / 自查
+
+```bash
+scriptctl ingest status          # 人读：kind / state / 各 pass 进度（transcribe 40/57 (2 failed) ...）
+scriptctl ingest status --json   # 机器：.status = {kind,state,phase,passes[],units,validation,errors[]}
+scriptctl view                   # 生成 workspace/review.html（视频版可点击定位到画面）
+scriptctl summary --script-path workspace/script.json   # 抽完当普通剧本读
+```
+
+`state`：`empty`（没开始）/ `incomplete`（在跑或中断、无硬错，重跑续）/ `failed`（有失败单元或校验没过）/ `ready`（`script.json` 生成且 v3 校验通过）。进度**纯从工作区真实文件推导**，不看任何独立状态机文件——不会出现"状态文件说完了但其实没完"。它报的是**管线事实**，不代表"已人工复核"（复核是你的完成门，另算）。
+
+## 三、🔴 抖动与重跑（大规模转剧本的常态）
+
+模型抖动 / 限流 / 单集超时 / 偶发解析失败在几十集体量下**是正常现象，不是 bug**。护栏与恢复：
+
+| 报错 | 含义 | 怎么办 |
+|---|---|---|
+| `INGEST_NORMALIZE_INCOMPLETE`（文本）<br>`INGEST_TRANSCRIBE_/CORRECT_/SPEAKER_INCOMPLETE`（视频） | 部分单元失败，留下 `passN/*.error.json` sidecar | **直接重跑 `scriptctl ingest`（同 source、同 workspace）**——从 checkpoint 续，只补失败单元。跑完 `ingest status` 看还剩几个，多跑几次到收敛 |
+| `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`
+
+```bash
+scriptctl publish                 # 沙箱：自动写项目 DB 新 revision（SANDBOX_PROJECT_GROUP_NO 已注入）
+scriptctl publish --local         # 本地：写 SCRIPTCTL_OUTPUT_DIR
+scriptctl publish --remote --project-group-no 123   # 显式指定项目组
+```
+
+- `publish` 读 `workspace/script.json`，**再跑一遍 v3 校验**，通过才写 store。
+- 沙箱里转完**必须 publish**，否则后端/前端看不到剧本。
+- `SCRIPT_REVISION_CONFLICT` = DB 被别的 revision 改过：重新拉取当前剧本、合并你的改动，再 publish。
+- publish 幂等：同一份 script 重复 publish 不会产生新 revision（按内容 sha 去重）。
+
+## 五、复杂场景怎么接
+
+- **转完先精修再入库**：`ingest` → 用 `--script-path workspace/script.json` 跑读写动词修（改归属、并角色、标龙套、补造型……）→ `publish`。
+- **入库后再改**：`publish` 之后直接对 DB（沙箱裸命令 = remote）继续精修，每次改都是新 revision。
+- **视频复核**：`view` 出的 `review.html` 视频版支持点击台词跳到对应画面时间码，逐场核对发声源/造型。
+- **超大剧集（几十集）**：并发默认已调好；失败就重跑到 `ingest status` 显示 `ready`。花名册归并只跑一次并复用，重跑很快。
+- **归并质量**：跨集角色归并靠文字锚点，相似角色可能误合/合过头。用 `roster.review.md`（视频）核对归并决策；发现误合，入库后用 `merge` 拆分/改名修正。
+
+## 六、抽完后的读写
+
+抽取产物就是标准 v3 剧本，用 SKILL.md 里所有读写能力精修（目标记得指 `--script-path workspace/script.json`，或 publish 后指 DB）：
+- `summary` / `episodes` 看整本 + 分集梗概；`actions --in <ep>` 带 timestamp 看节奏。
+- `states <actor>` 看造型弧线；`actors --counts` 看出场频次决定 `importance`。
+- 归属/造型修正：`dialogue <at> --actor/--kind`、`scene-ref <ep/scn> <kind:id> --state`。
+- 梗概/世界观：`synopsis` / `synopsis generate`（LLM 批量）/ `worldview`。

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

@@ -0,0 +1,59 @@
+# State 引用修复核验（v3）
+
+适用：合并 state、删除 state，或修 `STATE_NOT_MATERIALIZED` / 状态引用错连。重点不是只改 `states[]`，而是确认**引用该状态的场景 cast 引用**都被修好。
+
+> v3 里造型（state）只挂在**场景级 cast 引用**上（`scene.actors[]` / `props[]` / `location` 的 `state_id`），**没有** action 级 `state_changes`。所以引用只有一层，比 v2 简单。
+
+## 操作语义
+
+scriptctl 没有单独的 `state-merge` 命令；合并 state = "删旧 state 并替换引用"：
+
+```bash
+# 合并：把 st_old 的引用全指向 st_keep，再删 st_old（replacement 必须是同一资产已存在的 state_id）
+scriptctl state-delete actor:act_001/st_old --strategy replace --replacement st_keep
+
+# 真删除：删 st_old，引用它的场景 ref 的 state_id 被清掉
+scriptctl state-delete actor:act_001/st_old --strategy remove
+```
+
+（`delete actor:act_001/st_old --strategy ...` 是等价写法。）
+
+## 必查流程
+
+1. **操作前反查旧 state**，看谁在引用它：
+
+```bash
+scriptctl refs actor:act_001/st_old
+```
+
+输出里是各场景 cast 引用（形如 `ep_001/scn_003.actors[0].state_id`）。
+
+2. **合并用 `replace`**，不要先裸删：
+
+```bash
+scriptctl state-delete actor:act_001/st_old --strategy replace --replacement st_keep
+```
+
+期望：`refs actor:act_001/st_old` 为空；`refs actor:act_001/st_keep` 含原来该保留的场景引用；`scriptctl validate` 通过。
+
+3. **真删除用 `remove`**：
+
+```bash
+scriptctl state-delete actor:act_001/st_old --strategy remove
+```
+
+期望：引用该 state 的场景 ref 被保留、但 `state_id` 被清（角色仍在场，只是没造型）；`refs actor:act_001/st_old` 为空；`validate` 通过。
+
+4. **只想清某场的造型**（不删 state）：
+
+```bash
+scriptctl scene-ref ep_001/scn_003 actor:act_001 --clear     # 保留在场，清造型
+scriptctl scene-ref ep_001/scn_003 actor:act_001 --remove    # 整个移出该场
+```
+
+## 核验要点
+
+- 引用只有一层：`scene.{actors|props}[].state_id` 和 `scene.location.state_id`。`replace`/`remove` 会自动处理这一层。
+- replacement 只能是**同一资产**上已存在的 state_id。
+- 改完固定两步复查：`scriptctl refs actor:<id>/<st>` 为空 + `scriptctl validate` 通过。
+- `STATE_NOT_MATERIALIZED`：某场引用了一个该资产上不存在的 state_id。用 `scriptctl states <asset>` 看合法 state_id，再 `scene-ref <ep/scn> <kind:id> --state <合法 id>` 修正。

package/dist/domain/direct/runner.d.ts

@@ -1,25 +0,0 @@
-import { type Stage, type StageContext } from "./stage.js";
-export interface RunStagesOptions {
-    force?: boolean;
-    bypassInternalCaches?: boolean;
-    only?: Set<string>;
-    persistScriptAfterStages?: boolean;
-}
-/**
- * Run the pipeline in order. A stage whose output artifact already exists and
- * validates is skipped (resume), unless `force` is set or it isn't in `only`.
- * Stages with `output: null` always run (they decide their own per-unit reuse).
- *
- * The StageIncomplete sentinel (raised by episode-synopsis when some episode
- * still has unextracted batches) is NOT swallowed — it propagates so the
- * orchestrator can emit the INIT INCOMPLETE report + EXIT_RUNTIME, exactly as
- * the former god-command did with its early return.
- */
-export declare function runStages(ctx: StageContext, stages?: readonly Stage[], opts?: RunStagesOptions): Promise<void>;
-/**
- * Run exactly one stage by name against an existing workspace. Each stage
- * rehydrates the prior artifacts it needs from disk (ensure* helpers), so a
- * single step can run standalone — `direct run metadata` re-extracts metadata
- * for a workspace whose script.initial.json already exists, etc.
- */
-export declare function runOne(ctx: StageContext, stageName: string): Promise<Stage>;