@lingjingai/scriptctl 0.49.16 → 0.51.0

package/skills/scriptctl/references/bulk-authoring.md

@@ -1,169 +1,50 @@
 # 文件化批量写作
 
-这套接口给 LLM 直接生成和修改，不要求人编辑 JSON。authoring 文件使用 XML 风格块表达结构边界，块内使用 `[type|slot...] content` 行表达高密度字段。
+完整剧本、集、场和连续 Action 区间使用 `.scriptctl` authoring 文件。
 
-## 固定工作流
+## 固定流程
 
-1. 既有远端剧本先 `checkout` 到 `--script-path`。
-2. 修改本地既有剧本时，新 ID 用 `ids --kind ... --count ...` 查询候选值；它不预留 ID。全新剧本没有可供 `ids` 读取的本地文件，直接从各 kind 的 `_001` 开始分配 canonical ID。
-3. 修改既有内容先用 typed `export` 导出完整目标；从零写时直接生成完整 `.scriptctl` 文件。
-4. `write FILE --create|--replace` 只做计划。
-5. 从计划读取完整 `plan_digest`。
-6. `write FILE --create|--replace --apply --plan DIGEST` 原子落盘。
-7. `validate` 后按需 `publish`。
+1. 既有目标先 `export`；新节点 ID 用 `ids` 生成候选。
+2. 修改导出文件或生成完整 create 文件。
+3. `write FILE --create|--replace` 生成计划。
+4. 审阅所有目标、目标内变化、全局保留/新增/删除 ID、未触及 sibling、声明、
+   保留的孤立资产和 validation。
+5. 使用相同文件与 mode 执行
+   `write FILE --create|--replace --apply --plan <digest>`。
 
-`write` 只接受命名文件，不读 stdin。digest 绑定源文件的精确字节、mode、解析后的正式目标和当前本地 Script v3 语义哈希。每次 plan/apply 均持有按 script 文件划分的独占锁；apply 在锁内重新校验基线。
+确认码绑定精确源文件、mode、解析目标和当前本地基线，不保存为计划文件。
 
-canonical export 原样写回属于 no-op，即使目标中已有校验错误也可以生成计划；计划会继续报告这些既有错误。稿件实际改变目标时，目标内既有错误和新错误仍会阻断写入。
+## 方言
 
-## 根结构
+- 无基线 `--create` 使用 Script v4。
+- 已有文件按显式 `script.version` 选择 V3 或 V4 parser、serializer、validator 和 apply。
+- V4 target、replacement 节点和 Action 都携带正式 ID。
+- V4 scene 中同一资产只声明一次，状态写成完整集合。
+- V4 speaking Action 使用
+  `[dlg|action-id|speaker|parenthetical?]` 或
+  `[think|action-id|speaker|parenthetical?]`。
 
-```text
-<authoring version=1>
+## Target
 
-<create>
-...create-only asset/state declarations...
-</create>
+一个文件包含一个或多个同类 target：
 
-...one or more homogeneous targets...
+- `script`
+- `episode`
+- `episode-span`
+- `scene`
+- `scene-span`
+- `action-span`
 
-</authoring>
-```
+区间包含两端，端点正反等价，并按写入前的当前文档顺序解析。replace 批次必须按
+当前文档顺序排列且互不重叠。span replacement 至少包含一个对应节点；纯删除使用
+显式 delete 原子操作。
 
-`<create>` 可省略，但存在时只能有一个且必须在 targets 前。一个文件只能包含一种 target：
+## 声明
 
-```text
-<script>...</script>
-<episode id=ep_007>...</episode>
-<episode-span from=ep_002 through=ep_004>...</episode-span>
-<scene id=scn_021 parent=ep_007>...</scene>
-<scene-span parent=ep_007 from=scn_010 through=scn_012>...</scene-span>
-<action-span parent=ep_007/scn_021 from=12 through=18>...</action-span>
-```
+`<create>` 放在 targets 前，声明本批次新增的 actor、location、prop 与 state。
+资产先声明，state 紧随 owner 或在 owner 已存在时作为 standalone state 声明。
+所有引用必须在最终提案中可解析。
 
-属性不加引号。script 只能有一个且 create-only。episode/scene 支持 create 或 replace。三种 span 都是 replace-only，端点包含两端，replacement 必须非空。
+## 核验
 
-## create-only 声明
-
-声明按 actor、location、prop 分组；每个新资产后立刻写它的 states，第一条且唯一常态 state 必须是 `default`。引用既有资产的 standalone state 放在所有资产声明之后。state ID 在所属资产内唯一，完整身份是 typed owner 与 state ID，例如 `actor:act_001/st_001`。
-
-```text
-<create>
-[aliases]
-[alias] 门卫
-[actor|act_010|王建国|featured|配角] 五十岁男性。
-[state|actor:act_010|default|常态] 深蓝色保安制服。
-[state|actor:act_010|st_010|雨衣] 黄色雨衣。
-[location|loc_003|旧教室|featured] 墙皮脱落。
-[state|location:loc_003|default|常态] 夜间无人使用。
-[prop|prp_004|工作证|featured] 蓝色塑封证件。
-[state|prop:prp_004|default|常态] 挂在胸前。
-</create>
-```
-
-重复提交完全相同的既有声明是 no-op；同 ID 不同定义是冲突。importance 只有 `featured|background`，actor role 只有 `主角|配角`。
-`[aliases]` 表示正式 aliases 数组存在；后续零到多条 `[alias]` 保留顺序，因此空数组也能无损导出。
-
-## script 与 episode
-
-script metadata 固定顺序：
-
-```text
-<script>
-[title] 剧名
-[worldview] 现代
-[worldview-raw] 可选原始世界观
-[style] 悬疑
-[synopsis] 可选全剧梗概
-[logline] 可选一句话梗概
-[theme] 可选主题
-[main-characters]
-[main-character|林夏|主角]
-
-<episode id=ep_001>
-[title] 第一集
-[synopsis] 可选分集梗概
-...scenes...
-</episode>
-</script>
-```
-
-可选字段省略表示字段不存在；写成空 content 表示字段存在且值为空。
-`[main-characters]` 表示正式数组存在，后续零到多条 main-character，因此空数组也能无损往返。
-
-## scene
-
-scene 成员固定为 environment、location、零到多条 cast、零到多条 prop、body。scene 的 body 可以为空，episode 也可以不含 scene，用于表达待填充骨架；`write` 会在计划中报告 warning。replace 把原本非空的 scene 或 episode 清空时会报告更明确的 cleared warning。每个非空 scene 引用都绑定具体 state。actor 引用允许重复并保留顺序；同一个 prop 不重复。
-
-```text
-<scene id=scn_021 parent=ep_007>
-[environment|interior|night]
-[location|loc_003|default]
-[cast|act_001|st_before]
-[cast|act_001|st_after]
-[cast|act_010|default]
-[prop|prp_004|default]
-
-<body>
-[act|紧张] 林夏拉开衣柜。
-[dlg|act_001/st_after|压低声音] 谁在那里？
-[think|act_001/st_after|不安] 不能让他发现。
-[dlg|broadcast:] 不要回头。
-[trans] 画面切黑。
-</body>
-</scene>
-```
-
-嵌在 episode/scene-span 内的 scene 不写 parent；根 scene 必须写 parent。`location` 无槽位表示 `null`。非人物 speaker 是 `system|broadcast|offscreen|group`，可写 `kind:label`。普通写作不需要 `transition_prompt` 或 timestamp。
-
-单条正文记录的 content 可以为空，但计划会报告 `authoring_empty_action_content` warning。`action-span` 的 replacement 仍必须至少包含一条 action；空 replacement 会被拒绝，纯删除使用显式 mutation。
-
-## prefix modifiers 与 extensions
-
-modifier 必须紧贴其节点，顺序是零到多条 extend、零到多条 alias、最多一条 prompt：
-
-```text
-[extensions]
-[extend|camera] {"lens":35,"locked":true}
-[prompt|actor:act_001|换装|由校服变为礼服]
-[act] 林夏拉开衣柜。
-```
-
-`[extensions]` 表示正式 extend 对象存在，后续零到多条 extend，因此缺失与空对象可无损区分。`extend` 的 content 是单个 JSON value，key 唯一；仅 extensions 使用 JSON。canonical serializer 按 key 排序。`prompt` 的 target/process/contrast 都必填，仅在确实存在显式过渡提示时使用。
-
-## span
-
-```text
-<episode-span from=ep_002 through=ep_004>
-...one or more complete episodes...
-</episode-span>
-
-<scene-span parent=ep_003 from=scn_010 through=scn_012>
-...one or more complete scenes...
-</scene-span>
-
-<action-span parent=ep_003/scn_010 from=12 through=18>
-<body>
-...one or more actions...
-</body>
-</action-span>
-```
-
-episode/scene 端点按写入前本地脚本的真实数组位置解析，不比较 ID 数字。action index 零基且包含两端。一个文件中的多个 span 不得重叠，全部相对同一个写入前基线解析；replacement 数量可以与旧区间不同。action-span 只改 body，不改 scene refs。
-
-## export
-
-```bash
-scriptctl export script --output story.scriptctl
-scriptctl export episodes --in "ep_002..ep_004,ep_010" --output episodes.scriptctl
-scriptctl export episode-spans --in "ep_002..ep_004" --output episode-span.scriptctl
-scriptctl export scenes --in "ep_003/scn_010..ep_003/scn_012" --output scenes.scriptctl
-scriptctl export scene-spans --in "ep_003/scn_010..ep_003/scn_012" --output scene-span.scriptctl
-scriptctl export action-spans --in "ep_003/scn_010#12..ep_003/scn_010#18" --output actions.scriptctl
-```
-
-逗号分隔多个 point/range region。episodes/scenes 把区间展开成独立 targets；三种 span 命令的每个 region 产生一个 span target。跨 parent 的 scene/action span 直接拒绝。
-
-## 转义
-
-tag 属性只接受 canonical ID/address 字符，不需要转义。record header 中可用 `\|`、`\]`、`\\`、`\n`；content 中只用 `\\`、`\n`。不支持注释或自由散文行。
+apply 后用对应 `episodes`、`scenes`、`actions` 和 `refs` 读回，再运行 `validate`。

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

@@ -1,6 +1,6 @@
 # ingest workflow — 素材直转入库（文本 / 视频）
 
-适用：有外部素材要**转成 v3 剧本并入库**。统一入口 `scriptctl ingest`，看 source 后缀**自动分流**文本 / 视频；两条管线在同一个 govern 收尾汇合，产出相同结构的 v3 `script.json`。视频、小说和非标准剧本统一执行 [production-writing-standard.md](production-writing-standard.md)。
+适用：有外部素材要**转成 Script v4 并入库**。统一入口 `scriptctl ingest`，按 source 类型自动分流文本 / 视频；两条管线最终都产出 v4 `script.json`。视频、小说和非标准剧本统一执行 [production-writing-standard.md](production-writing-standard.md)。
 
 ```
 ingest --source-path <file|dir>   →   标准化复核   →   view / ingest status   →   publish
@@ -22,18 +22,17 @@ scriptctl ingest --source-path uploads/正片/
 
 常用 flag：
 - `--workspace-path <dir>`：工作区根（manifest + 各 pass 目录 + 产物）。**不传默认 `<cwd>/workspace`**；显式传可放别处。`view` / `ingest status` 使用同一 workspace；publish 用 `--script-path <workspace>/script.json`。
-- `--concurrency <n>`：文本/归并 fanout 并发（文本默认 80，视频默认 30）。
-- `--video-concurrency <n>`：视频上传+转录并发。默认 10。
+- `--concurrency <n>`：文本 fanout 并发，默认 30。视频逐集串行。
 - `--fps <n>`：视频采样帧率（>1 解锁亚秒级时间码）。默认 3。
 - `--force`：**同源**重跑，清掉产物重来（**不能换源**）。
 
 管线（了解即可，产物都在 `workspace/`）：
-- **文本**：正文起点定位 → 切块 → 生产化归一（对白逐字保留；叙述转成具象 Action；按地点、时段、叙事线和持久状态变化分场）→ 合并组装 `body.json` → 串行资产/身份/state 治理 → 确定性编号 → v3 结构校验 + 生产规范 warning → `script.json`。逐块与串行窗口都有 checkpoint。
-- **视频**：逐集串行观看原视频，同时维护跨集人物花名册、剧情进展和造型；每集直接输出逐镜头 scenes + 资产增量 → 确定性人物归一、群体发声归一、编号和 state 物化 → v3 结构校验 + 生产规范 warning → `script.json`。时间戳写入 `extend.timestamp`，逐集 `ep/*.json` 和 `context.json` 支持断点续跑。
+- **文本**：正文起点定位 → 切块 → 生产化归一 → 合并组装 `body.json` → 串行资产/身份/state 治理 → V3 中间校验 → 稳定 V4 身份分配 → V4 校验与生产规范 warning → `script.json`。
+- **视频**：逐集串行观看原视频并维护跨集人物、剧情和造型上下文 → 确定性治理 → V3 中间校验 → 稳定 V4 身份分配 → V4 校验与生产规范 warning → `script.json`。时间戳写入 `extend.timestamp`，逐集 `ep/*.json`、`context.json` 和身份映射支持断点续跑。
 
 ### 提取与解析原则
 
-- 先忠实提取源素材可验证的对白、动作、顺序、人物状态和场景切换，再整理成标准 v3 资产与正文。
+- 先忠实提取源素材可验证的对白、动作、顺序、人物状态和场景切换，再整理成标准资产与正文。
 - 视频以画面和声音为准；小说与非标准剧本把叙述转换成可拍摄 Action，同时保留原文事实、因果和人物关系。
 - 保留对白原文；允许为结构化和可拍摄性规范化叙述措辞，同时保持事实、因果、顺序、动作结果和状态不变。
 - 将无法确认的人物身份、动作主体、地点和状态保留为待复核项，不补写源素材没有表达的事实。
@@ -47,7 +46,8 @@ scriptctl ingest --source-path uploads/正片/
 2. 用 `scenes --in <ep>` 检查唯一地点、场界、蒙太奇顺序和状态变化边界。
 3. 用 `actions --in <ep>` 检查说话人、群体发声、人物真名、动作链和可拍摄性。
 4. 视频对照画面与声音；文本对照原文，确认对白逐字保真，事实、因果、顺序、动作结果和状态没有改变或补造。
-5. 用 scriptctl 读写动词修正 `workspace/script.json`，再次运行 `validate`，完成内容复核后再 publish。
+5. 运行 `audit-assets --script-path workspace/script.json`，查看 `asset-audit.json` 中的人物身份重复、同义状态、未使用/落单状态、重复地点和道具建议。不要仅凭名称相似或低频就合并、删除。
+6. 用 scriptctl 读写动词修正 `workspace/script.json`，再次运行 `validate` 和 `audit-assets`，完成内容复核后再 publish。
 
 ## 三、看进度 / 自查
 
@@ -56,10 +56,11 @@ scriptctl ingest status          # 人读：kind / state / 各 pass 进度（tra
 scriptctl ingest status --json   # 机器：.status = {kind,state,phase,passes[],units,validation,errors[]}
 scriptctl view                   # 生成 workspace/review.html（视频版可点击定位到画面）
 scriptctl view --watch [--port N]# 实时监听面板：分阶段进度条 + 逐集 context/决策 + 产物树，自动刷新（跑中也能开）。🔴 仅本地用，**沙箱内不要用**（起阻塞服务+开浏览器，会挂住；沙箱看进度用 `ingest status`）
+scriptctl audit-assets --script-path workspace/script.json  # 全剧资产一致性复核；结果写 asset-audit.json
 scriptctl summary --script-path workspace/script.json   # 抽完当普通剧本读
 ```
 
-`state`：`empty`（没开始）/ `incomplete`（在跑或中断、无硬错，重跑续）/ `failed`（有失败单元或校验没过）/ `ready`（`script.json` 生成且 v3 结构校验通过）。`validation.json` 的 production warning 标出仍需复核的内容规范问题。进度从工作区真实文件推导；它报的是管线事实，源素材一致性仍由复核完成门确认。
+`state`：`empty`（没开始）/ `incomplete`（在跑或中断、无硬错，重跑续）/ `failed`（有失败单元或校验没过）/ `ready`（`script.json` 生成且 v4 结构校验通过）。`validation.json` 的 production/asset-audit warning 标出仍需复核的问题，`asset-audit.json` 保存完整证据和建议。进度从工作区真实文件推导；它报的是管线事实，资产合并结论和源素材一致性仍由复核完成门确认。
 
 ## 四、🔴 抖动与重跑（大规模转剧本的常态）
 
@@ -71,7 +72,7 @@ scriptctl summary --script-path workspace/script.json   # 抽完当普通剧本
 | `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` |
+| `INGEST_VALIDATION_FAILED` | 最终校验没过 | 看 `workspace/validation.json` 的具体报错，修复后再 `publish` |
 | 持续 401/403/404 / 模型路由错 | 网关/密钥/模型环境问题（不是抖动，重跑也不好） | 如实告诉用户，别反复空跑、别编造成功。视频需 `GEMINI_API_KEY` |
 
 🔴 **绝不**：清工作区、删 checkpoint、手塞/手改中间文件来"绕过"失败。重跑 = 唯一正解；成功单元不会重跑，贵的花名册归并（`roster.json`）也会复用。
@@ -83,7 +84,7 @@ scriptctl publish --script-path workspace/script.json
 scriptctl publish --script-path workspace/script.json --project-group-no 123
 ```
 
-- `publish` 读本地 `--script-path`（默认 `workspace/script.json`），**再跑一遍 v3 校验**，通过才发布。
+- `publish` 读本地 `--script-path`（默认 `workspace/script.json`），按显式版本再次校验，通过才发布。
 - 沙箱里转完**必须 publish**，否则后端/前端看不到剧本。
 - 已管理工作副本 publish 采用 local-wins：CAS/网络失败后重拉 snapshot、重算 diff 并重试，最终远端内容以本地稿为准。
 - 已管理且内容未变时 publish 本地直接 no-op，不发网络请求。服务端不保存 requestId，也不提供 publish 幂等重试。
@@ -98,7 +99,7 @@ scriptctl publish --script-path workspace/script.json --project-group-no 123
 
 ## 七、抽完后的读写
 
-抽取产物就是标准 v3 剧本，用 SKILL.md 里所有读写能力精修（目标指 `--script-path workspace/script.json`；远端稿先 checkout）：
+抽取产物就是标准 v4 剧本，用 SKILL.md 里所有读写能力精修（目标指 `--script-path workspace/script.json`；远端稿先 checkout）：
 - `summary` / `episodes` 看整本 + 分集梗概；`actions --in <ep>` 带 timestamp 看节奏。
 - `states <actor>` 看造型弧线；`actors --counts` 看出场频次决定 `importance`。
 - 归属/造型修正：`dialogue <at> --actor/--kind`、`scene-ref <ep/scn> <kind:id> --state`。

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

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

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

@@ -1,61 +1,38 @@
-# State 引用修复核验（v3）
+# State 引用修复
 
-适用：合并 state、删除 state，或修 `STATE_NOT_MATERIALIZED` / 状态引用错连。重点不是只改 `states[]`，而是确认**引用该状态的场景 cast 引用**都被修好。
-
-> 造型（state）挂在**场景级 cast 引用**上（`scene.actors[]` / `props[]` / `location` 的 `state_id`），引用只有这一层。
-
-## 操作语义
-
-合并 state 使用 `state-delete --strategy replace`，删除源 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
+scriptctl refs actA3kP9x/stB4xR8p --script-path "$SCRIPT"
 ```
 
-（`delete actor:act_001/st_old --strategy ...` 是等价写法。）
+## Script v4
 
-## 必查流程
-
-1. **操作前反查旧 state**，看谁在引用它：
+场景引用保存完整、非空的 `state_ids` 集合。替换 state 会在场景集合与 actor
+speaker 上同步替换：
 
 ```bash
-scriptctl refs actor:act_001/st_old
+scriptctl state-delete actA3kP9x/stB4xR8p \
+  --strategy replace --replacement default --script-path "$SCRIPT"
 ```
 
-输出里是各场景 cast 引用（形如 `ep_001/scn_003.actors[0].state_id`）。
+`--strategy remove` 会从每个集合移除该 state；若任何集合将变为空，命令拒绝，
+应先为该场写入另一个完整状态集合。speaker 上的可选 state 被移除后可省略，由
+下游依据场景集合判断具体对白落点。
 
-2. **合并用 `replace`**，不要先裸删：
+## Script v3
 
-```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`**：
+使用 V3 state 地址和既有单值引用语义：
 
 ```bash
-scriptctl state-delete actor:act_001/st_old --strategy remove
+scriptctl state-delete actor:act_001/st_002 \
+  --strategy replace --replacement st_001 --script-path "$SCRIPT"
 ```
 
-期望：引用该 state 的场景 ref 被保留、但 `state_id` 被清（角色仍在场，只是没造型）；`refs actor:act_001/st_old` 为空。这个结果是修复中间态：为该 ref 重新设置合法 state 前，CLI 会拒绝向该场继续插入正文。
-
-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    # 整个移出该场
+scriptctl refs <旧-state-address> --script-path "$SCRIPT"
+scriptctl refs <新-state-address> --script-path "$SCRIPT"
+scriptctl validate --script-path "$SCRIPT"
 ```
-
-`--clear` / `--state none` 只用于修复中间态；从零创作不能用它们跳过状态绑定。
-
-## 核验要点
-
-- 引用只有一层：`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/help-text.d.ts

@@ -1,2 +0,0 @@
-export declare function getHelp(command: readonly string[]): string | undefined;
-export declare const HELP: Map<string, string>;