@lingjingai/scriptctl 0.35.0 → 0.36.1

package/skills/scriptctl/SKILL.md

@@ -1,29 +1,34 @@
 ---
 name: scriptctl
-description: "剧本 script.json 的读写 CLI：从零创建（create + add-actor/location/prop/episode）、查询（集/场/action/资产/状态/校验/时间戳/出场统计）、原子编辑（台词/类型/归属/state/资产）、选择器批量精修（一条命令扫一片，读写共享 --in/谓词）、动词脚本 do（异构批量一事务）、结构调整（插/删/移/分/合）、入库导出。本地电脑上默认直接读写本地 script.json（--script-path）；沙箱里默认读写项目 DB。剧本阶段做任何剧本相关读写、以及洗稿/对标/转绘里操作原剧与新剧两个 script.json 之前都应加载。正文由你用原子能力写入。"
-version: "0.18.0"
-scriptctl_version: "0.35.0"
+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`：资产（人物/场景/道具/发声源）、分集 → 场景 → action、状态与引用完整性、校验。**每次调用只作用于一份剧本**（由目标 flag 选定），所以「换剧本 = 换目标」。
+`scriptctl` 读写结构化剧本 `script.json`（Schema v3：资产 人物/场景/道具 + 分集→场景→action + 场景级 cast/造型 + 内联发声源 + 引用完整性 + 校验），并把外部素材**转成剧本、入库**。**每次调用只作用于一份剧本**（由目标 flag 选定），所以「换剧本 = 换目标」。
+
+两条主线：
+- **转剧本入库**：`ingest`（抽取，产出 `workspace/script.json`）→ `view`（自查）→ `publish`（入库）。见 [references/ingest-workflow.md](references/ingest-workflow.md)。
+- **读写既有剧本**：查询 + 原子写 + 选择器批量 + `do`。
 
 ## 先定目标：作用在哪份剧本上
 
-`scriptctl` 每条命令都要知道读写哪份剧本，四选一（互斥）：
+除 `ingest`/`view`/`publish` 外，每条读写命令都要知道读写哪份剧本，从下面选一个（互斥）：
 
 | 目标 | flag | 用在 |
 |---|---|---|
+| **项目 DB（最终剧本）** | `--remote [--project-group-no <no>]` | ☁️ **沙箱首选**。每次写进 DB 新 revision，边写边入库 |
 | **本地文件** | `--script-path <file>` | 🖥️ **本地电脑首选**。直接读写这一个 JSON，无 store、无 revision。洗稿/对标/转绘、试验、离线全走它 |
-| direct 中间稿 | `--draft` | 指向 `script.initial.json`（direct 抽取产物）；不用写路径 |
-| 项目 DB（最终剧本） | `--remote` / `--project-group-no <no>` | ☁️ **沙箱首选**。每次写进 DB 新 revision，边写边入库 |
-| 本地约定 store | `--local` | `output/` 目录下的约定 store |
+| 本地约定 store | `--local` | `SCRIPTCTL_OUTPUT_DIR` 下的约定 store |
 
+- ☁️ **沙箱里**：后端注入 `SANDBOX_PROJECT_GROUP_NO`,**裸命令自动指向该项目 DB**（自动 remote），无需任何 flag。
 - 🖥️ **本地电脑上**：几乎每条命令都带 `--script-path <file>`。下文示例为简洁常省略它，实际本地使用请补上。
-- ☁️ **沙箱里**：`SANDBOX_PROJECT_GROUP_NO` 已注入时，裸命令自动指向该项目 DB，无需 flag。
-- 不给任何目标、又不在沙箱：CLI 拒绝猜测并报错。选一个目标。
+- **不给任何目标、又不在沙箱**：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：洗稿 / 对标 / 转绘
 
@@ -57,73 +62,69 @@ scriptctl scenes --in ep_003              --script-path "$NEW"
 
 | 想做什么 | 命令 |
 |---|---|
-| **了解剧情 / 全貌**：讲什么（synopsis）、世界观（worldview）、风格（style）、一句话（logline）、主旨（theme）、主角（main_characters）+ 标题 / 集数 / 场数 / 资产数（"这剧本是关于什么的"先跑这个） | `scriptctl summary` |
-| 每集字数 / 场数 / action 数 **+ 每集剧情梗概** | `scriptctl episodes` |
-| 找字数超 1000 的集 | `scriptctl episodes --min-chars 1000` |
+| **了解剧情 / 全貌**：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** / 正文 / 情绪） | `scriptctl actions --in ep_001` |
+| 列某集所有 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` |
-| 某角色出现的所有场 | `scriptctl scenes --has-actor act_001` |
-| **列某资产的所有 state + 状态弧线**（拿 state_id↔名↔描述↔出现在哪些集，改 state 前必查） | `scriptctl states act_001`（裸 id 即可，也认 `actor:act_001`） |
-| 资产**出场统计**（几场 / 几集，压成集区间） | `scriptctl actors --counts` / `locations --counts` / `props --counts` |
-| 某资产 / 状态 / speaker 反查 | `scriptctl refs actor:act_001` |
-| 当前校验问题 | `scriptctl issues --severity error` |
-| 跑校验 | `scriptctl validate` |
-
-**读侧新特性（0.35.0 起）**——洗稿/对标/转绘的核心读法：
-
-- `actions` TSV 列：`addr timestamp type delivery speaker actor emotion content`。`timestamp` 是该 action 的 `extend.timestamp`（集内 `M:SS`，无则空）。事件跨度 = 首末 action 时间戳之差。
+| 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 context + action state_changes 里被绑定的位置）。从不绑定的状态显示 `episodes=none`。
-- `actors|locations|props|assets --counts`：追加 `scenes=N episodes_count=M episodes=<区间>`（按 scene context 出场统计）。默认不带 `--counts`，保持输出精简。
-- `summary`：多吐 `worldview`（有 `worldview_raw` 且不同则括号附带）与 `style`。
+- `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。多点：见下「选择器批量」）
+### 写（单点：第一个位置参数是 address。多点：见「选择器批量」）
 
 | 想做什么 | 命令 |
 |---|---|
-| 改 action 正文（替换 / 删一段） | `scriptctl replace <ep/scn#idx> --from X --to Y`（加 `--regex` 走正则） |
-| 改 action type | `scriptctl type <ep/scn#idx> <dialogue\|action\|inner_thought>` |
-| 改 action 归属角色 | `scriptctl actor <ep/scn#idx> <act_id\|none>` |
-| 改 / 清 action 情绪 | `scriptctl emotion <ep/scn#idx> "紧张"` / `scriptctl emotion <ep/scn#idx> --clear` |
-| 加 state 变化 | `scriptctl state-change <ep/scn#idx> actor:<id> --to <state>` |
-| 清 state 变化 | `scriptctl state-change <ep/scn#idx> actor:<id> --clear` |
-| action 转对白 | `scriptctl dialogue <ep/scn#idx> --speakers spk_001` |
-| 改资产名 / 描述 / 别名 / role | `scriptctl rename actor:<id> "X"` / `describe` / `alias --add X` / `role <主角\|配角>` |
+| 改 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 rename actor:<id>/<st_id> "新名"` / `scriptctl delete actor:<id>/<st_id> --strategy remove`（地址带 `/st_id` 即作用于 state；`state-rename` / `state-delete` 是等价别名；合并/删除 state 的引用修复核验见 [references/state-reference-repair.md](references/state-reference-repair.md)） |
-| 改 scene 资产 ref | `scriptctl context <ep/scn> actor:<id> --state st_X \| --clear \| --remove` |
+| **改/删某个 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]` / `insert <ep> --location <id>` |
-| 移动 / 分场 | `scriptctl move <addr> <to>` / `split <ep/scn> --at <idx>` |
-| 设整本 / 分集剧情梗概 | `scriptctl synopsis "整本梗概"` / `scriptctl synopsis ep_001 "本集梗概"` |
+| 合并资产/场景 | `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 <现代\|古代历史\|...>` |
-| 新建 speaker | `scriptctl add-speaker --kind X --name Y` |
+
+> 发声源写在**对白行内联**：角色用 `dialogue <at> --actor <id>`（或 `actor <at> <id>`），非角色声源用 `dialogue <at> --kind <system\|broadcast\|offscreen\|group>`。造型（state）挂在**场景级 cast 引用**上：`scene-ref <ep/scn> <kind:id> --state <state_id>`。
 
 ### 选择器批量（一条命令扫一片 —— 读写共享同一套选择语法）
 
-把单点写动词的「address」换成一个**选择**，它就对**所有命中的 action** 一次性改。`replace / type / actor / emotion / state-change / transition` 都支持。
+把单点写动词的「address」换成一个**选择**，它就对**所有命中的 action** 一次性改。支持选择器的写动词：`replace / type / actor / emotion / transition`。
 
 - **选范围 `--in`**：`ep_003..ep_007`（集区间）/ `ep/scn` 区间 / 逗号多区间 / `'*'`（全本）。
-- **加谓词**（和 `actions` 查询**完全一样**的 flag，AND 组合）：`--type` `--actor` `--speaker` `--grep /re/` `--has state-changes|transition|lines`。
+- **加谓词**（和 `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集里某 speaker 的对白统一改归属（谓词直达，无需先查地址）
-scriptctl actor --in ep_003..ep_007 --speaker spk_001 act_009 --apply
-# 第3-7集里某 speaker 的对白统一标情绪
-scriptctl emotion --in ep_003..ep_007 --speaker spk_001 "紧张" --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 … --speaker …` 查出来是哪些，换个动词就改哪些。`actions --json` 带结构化 `rows[]`（含独立 `addr` / `timestamp` / `emotion` 字段），`actions … --format addr` 直接吐裸地址流喂 `xargs`。
+> 先 discover 后 mutate 用**同一套 flag**：`scriptctl actions --in … --actor …` 查出来是哪些，换个动词就改哪些。`actions --json` 带结构化 `rows[]`，`actions … --format addr` 直接吐裸地址流喂 `xargs`。scene-ref/importance/dialogue 是**单点**动词，不进选择器批量。
 
 ### 异构批量 `do`（一组各不相同的改动 = 一段动词脚本 = 一个事务）
 
@@ -133,11 +134,11 @@ scriptctl emotion --in ep_003..ep_007 --speaker spk_001 "紧张" --apply
 scriptctl do edits.txt           # 默认 dry-run（预演 + 校验，不写）
 scriptctl do edits.txt --apply   # 一次性原子落盘
 cat edits.txt <<'EOF'
-replace ep_001/scn_001#3 --from "台下掌声雷动" --to ""
-type    ep_001/scn_002#1 dialogue
-merge   actor:act_005 --into actor:act_001
-insert  ep_001/scn_006 --type action --content "暗夜，街道空无一人。"
-emotion ep_001/scn_001#3 --clear
+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
 ```
 
@@ -147,26 +148,26 @@ EOF
 
 | 想做什么 | 命令 |
 |---|---|
-| 建空白剧本（schema v2 骨架） | `scriptctl create [--title X]` |
+| 建空白剧本（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)。
+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 |
-| `ep_001/scn_001` | scene |
-| `actor:act_001` / `location:loc_001` / `prop:prp_001` | asset |
-| `actor:act_001/st_001` | asset state |
-| `ep_001` | episode |
-| `spk_001` | speaker |
+| 形态 | 类型 | 例 |
+|---|---|---|
+| `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。
+> `states` 查询额外接受裸资产 id（`act_001`/`loc_001`/`prp_001`），按前缀推断种类。其它 verb 仍要完整 address。
 
 ## 经典最短路径
 
@@ -176,48 +177,38 @@ scriptctl actions --grep "台下掌声雷动"
 # → ep_001/scn_001#3	0:14	action	...	台下掌声雷动。
 scriptctl replace ep_001/scn_001#3 --from "，台下掌声雷动" --to ""
 ```
-`--to` 省略即删除。一个 action 内多次命中默认拒绝，要么把 `--from` 写更长更唯一，要么显式 `--all`。
+`--to` 省略即删除。一个 action 内多次命中默认拒绝，把 `--from` 写更长更唯一，或显式 `--all`。
 
-**改某角色名 + 补别名**：
+**改某行归属 / 定发声源**：
 ```bash
-scriptctl rename actor:act_001 "陈墨"
-scriptctl alias actor:act_001 --add "陈总" --add "老板"
-```
-
-**整理重复角色**：
-```bash
-scriptctl refs actor:act_005                 # 先看 act_005 出现在哪
-scriptctl merge actor:act_005 --into actor:act_001
+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
-# → actor:act_001/st_001  京北队球衣  desc="…"  episodes=ep_001..ep_017,ep_022..ep_044 (40 eps, 43 scenes)
-# → actor:act_001/st_002  石膏轮椅装  desc="…"  episodes=ep_018..ep_021 (4 eps, 4 scenes)
-scriptctl actors --counts                     # 每个人物出场几场/几集
+scriptctl states act_001                                    # 先看有哪些 state
+scriptctl scene-ref ep_001/scn_003 actor:act_001 --state st_injured
 ```
 
-**写 / 改梗概**：
+**整理重复角色**：
 ```bash
-scriptctl summary                         # 先看整本 worldview/style/synopsis/logline/theme
-scriptctl episodes                         # 每集列表含 synopsis
-scriptctl synopsis "一段整本剧情梗概。"
-scriptctl synopsis ep_001 "第一集剧情梗概。"
+scriptctl refs actor:act_005                 # 先看 act_005 出现在哪
+scriptctl merge actor:act_005 --into actor:act_001
 ```
 
-**插一场过渡 + 起头 action**：
+**标龙套（下游省算力）**：
 ```bash
-scriptctl insert ep_001 --after ep_001/scn_005 --location loc_002 --time night --space exterior
-scriptctl insert ep_001/scn_006 --type action --content "暗夜，街道空无一人。" --emotion "紧张"
+scriptctl actors --counts                                   # 看谁出场少
+scriptctl importance actor:act_042 background
 ```
 
 **修校验问题**：
 ```bash
 scriptctl issues --severity error
-# → STATE_NOT_FOUND at ep_001/scn_003#5 actor:act_001
-scriptctl actions --in ep_001/scn_003 --has state-changes
-scriptctl state-change ep_001/scn_003#5 actor:act_001 --to st_calm --from st_default
+# → 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`）**：
@@ -227,47 +218,76 @@ scriptctl replace --in ep_003..ep_007 --from 陈总 --to 陈墨 --all --apply  #
 scriptctl do fixes.txt --apply                                            # 异构：一段动词脚本一事务
 ```
 
-**从零写一集（你自己写正文，`do` 批量灌）**：
+## 转剧本入库：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
-scriptctl create --title "夏夜便利店"      # 空白剧本
-scriptctl do ep01.txt --apply             # 每行一条建词/insert：add-actor → add-location → add-episode → insert
+# 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
 ```
-完整骨架与写法见 [references/atomic-write-workflow.md](references/atomic-write-workflow.md)。
 
-## 三种入库起点（按项目状态选）
+- 🔴 **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。
 
-| 项目状态 | 走 | 细节 |
-|---|---|---|
-| 没剧本文本，从零写（题材 / 灵感 / 集纲在手） | `create` + `add-*` + `insert` + `do`，正文你自己写 | [references/atomic-write-workflow.md](references/atomic-write-workflow.md) |
-| 已有完整剧本 / 分镜素材（docx / pdf / xlsx / md / json） | `scriptctl direct ...`（LLM 抽取） | [references/direct-workflow.md](references/direct-workflow.md) |
-| 只有正文 md、还没资产 md | `scriptctl parse <dir> --extract-assets`（LLM 提资产） | 只写 `人物.md`/`场景.md`/`道具.md`/`发声源.md`/`元信息.md`，不生成 script.json、不发布；复核后再跑普通 parse |
-| 自己手写好一个 md 工作区 | `scriptctl parse <dir> [--publish]`（确定性组装，无 LLM） | `scriptctl parse --spec` 看 md 语法 |
+### `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 校验通过）。
+- 进度**纯从工作区文件推导**（没有独立状态机文件，不会和真实状态不同步）。它报的是"管线事实"，不代表"已人工复核"——复核是你的完成门，另算。
 
-写正文 = 你（agent）想好正文，用上面「建 / 写」的原子能力灌进剧本。
+### 🔴 遇到错误怎么办（抖动是常态，重跑即续）
 
-`direct export` 只卡 validation：passed 才放行。但**强烈建议**导出前用 `direct review` 自查（curation/issues 总览 + `--episode N` 源文↔抽取对照），细节看 direct-workflow.md。
+大规模转剧本时，模型抖动 / 限流 / 单集超时 / 偶发解析失败是**正常现象**，不是 bug。护栏与恢复：
 
-`direct init` 可续跑：成功批次跳过、失败批次粘性不自动重试。`scriptctl direct status` 看每集状态，`direct init --episodes <N> / --batches <key> / --retry-errors / --all` 选择性重跑（只动点名的，不碰其它集）。某集内容过滤就 `--episodes <N>` 重跑或软化源文本，不要清 run_state / 手塞文件。
+- **`*_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` 通用规则）
+## 资产 state 判定（`state-add` / `scene-ref --state` 通用规则）
 
-只有**持久、可复用、需独立生成视觉资产的外观变体**才进 `states[]`。身份 / 年龄 / 职业 / 情绪 / 动作 / 姿态 / 临时伤病 / 混合状态**不**算状态，放 description 或 action 文本。
+只有**持久、可复用、需独立生成视觉资产的外观变体**才进 `states[]`。身份/年龄/职业/情绪/动作/姿态/临时伤病/混合状态**不**算状态，放 description 或 action 文本。
 
-**默认状态（default）**：每个有 `states[]` 的资产必须有且仅有一个 asset-scoped 的 `state_id: "default"`（代表最常见的常态外观，保留可读的 state_name）。`direct`/`parse` 会自动把「默认/最常见」那一档 canonical 成 `default`；手动 `state-add` 给一个原先无状态的资产加第一个 state 后，若校验报 `DEFAULT_STATE_MISSING`，说明缺默认态——把最常见那档的 state_id 设成 `default`（改 raw JSON 或重跑 direct state-curation）。
+**默认状态（default）**：每个有 `states[]` 的资产必须有且仅有一个 `state_id: "default"`（最常见常态外观，保留可读 state_name）。`ingest` 会自动把「默认/最常见」那档 canonical 成 `default`；手动 `state-add` 给原先无状态的资产加第一个 state 后，若校验报 `DEFAULT_STATE_MISSING`，把最常见那档的 state_id 设成 `default`。
 
-合并或删除 state 时，必须确认引用该 state 的场景 context 和 action state_changes 已被正确修复；操作与实现路径见 [references/state-reference-repair.md](references/state-reference-repair.md)。
+合并/删除 state 时，必须确认引用它的场景 `scene-ref --state` 已被正确修复；操作见 [references/state-reference-repair.md](references/state-reference-repair.md)。
 
 ## 通用边界
 
-- 🔴 **不要加 `--json`**。默认列表 / 查询输出是给 agent 读的 TSV / 行式文本（地址单独成列），比 JSON 更省 token、更好决策。除非真的要 parse 字段喂给下一步程序（那时 `actions --json` 有结构化 `rows[]`，或用 `--format addr` 取裸地址流）。
-- 🔴 **多点写默认 dry-run**：`replace/type/actor/emotion/state-change/transition` 一旦带 `--in`/谓词就是预演（回显命中数，不落盘），确认后加 `--apply` 才真写。单点（给 address）直写、不用 `--apply`。
-- 🔴 **手写批量走 `do`，不要手撸 patch JSON**。`scriptctl patch <file|->` 降级为**机器/jq 管道**的接口（`… --json | jq '[…]' | scriptctl patch -`）；人/agent 手写一律用 `do`（动词原样，无翻译）。需要 op schema 用 `scriptctl patch --schema [<op>]`。
+- 🔴 **不要加 `--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`，一次只碰一份。
-- 只有 `direct init` 和 `parse --extract-assets` 会请求大模型；普通 `parse`、`summary/episodes/actions` 查询、`synopsis/replace/patch/do` 等 script.json 读写命令不打模型。
-- 修 direct 中间稿（`script.initial.json`）：所有读写 verb 加 `--draft` 即可，不用知道文件路径；不加 `--draft` 默认操作 DB 里的最终剧本。`--draft` 与 `--script-path`/`--project-group-no` 互斥。
-- 多态 verb（`delete` / `merge` / `move` / `describe` / `rename` / `insert`）按 address 格式分发；flag 用错 kind 会直接报错（不会静默忽略）。
-- 互斥 flag（`context` 的 --state/--clear/--remove；`state-change` 的 --to/--clear；`transition` 的 --process+--contrast/--clear）只能传一个，多传会报 `*_FLAG_CONFLICT`。
+- 🔴 **沙箱里转完剧本要 `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` 查。
+参数/默认值/退出码以 `scriptctl <cmd> --help` 为准。功能变更用 `scriptctl changelog` 查。

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

@@ -11,15 +11,18 @@
 ```
 create（空白剧本）
   → worldview                 设世界观
-  → add-actor / add-location / add-prop / add-speaker   注册资产（+ state-add 给外观档位）
+  → add-actor / add-location / add-prop   注册资产（+ state-add 给外观档位）
   → add-episode               建分集
   → synopsis                  写整本 / 分集梗概
   → insert <ep> --location    建场景
-  → insert <ep/scn> --type ... --content "正文" [--emotion "情绪"]  逐 action 灌正文
-  → state-change / transition / context / dialogue       关系与状态层
+  → insert <ep/scn> --type ... --content "正文" [--emotion "情绪"] [--actor <id>]  逐 action 灌正文
+  → dialogue / scene-ref / transition / importance       发声源、场景造型、重要度
   → validate                  收尾自查
+  → publish                   入库（沙箱必做）
 ```
 
+> 发声源写在**对白行内联**（`dialogue <at> --actor/--kind`，或 `insert --actor`）；造型挂在**场景 cast 引用**上（`scene-ref <ep/scn> <kind:id> --state`）。
+
 资产/分集/场景的 id **自动按序分配**：第一个 actor 是 `act_001`、location 是 `loc_001`、prop 是 `prp_001`、episode 是 `ep_001`、它下面第一场是 `scn_001`……所以你能在后续命令里直接引用这些可预测的 id（也可以 `--id` 显式指定）。
 
 ---
@@ -77,16 +80,16 @@ insert ep_001/scn_001 --type dialogue --content "欢迎光临。" --actor act_00
 
 ## 写到哪里去（落库）
 
-`create` 和所有编辑 verb 共用同一套目标解析，四选一：
+`create` 和所有编辑 verb 共用同一套目标解析，三选一：
 
 | 目标 | 怎么走 | 说明 |
 |---|---|---|
 | **本地文件** | `--script-path <file>` | 🖥️ **本地电脑首选**。直接读写这一个 JSON，无 store、无 revision。洗稿/对标/转绘、试验都走它 |
-| **DB（最终剧本）** | 不加目标 flag（沙箱默认），或 `--project-group-no <no>` | ☁️ **沙箱首选**。每个 op / patch 直接写进 DB 的新 revision，边写边入库，不需要单独的「发布」步骤 |
-| **direct 中间稿** | `--draft` | 写进 `script.initial.json`；想要「先攒后审再入库」就走这条，最后 `scriptctl direct export` 落库 |
+| **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`。
-- ☁️ **沙箱**：直接对 DB 写（`create` → 编辑，不加 flag），写完就在库里；想导出前人工自查就 `create --draft` → 全程 `--draft` 编辑 → `direct export`。
+- 🖥️ **本地**：`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（洗稿 / 对标 / 转绘）
 
@@ -108,7 +111,7 @@ insert ep_001/scn_001 --type dialogue --content "欢迎光临。" --actor act_00
 ## 提醒
 
 - 资产 state 判定（哪些进 `states[]`）见 SKILL.md「资产 state 判定」。
-- 非人类发声源（系统/广播/道具音）用 `add-speaker --kind system|broadcast|prop|...`，**不要**注册成 actor。
+- 非角色发声源（系统/广播/画外/群体）用 `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`。