@lingjingai/scriptctl 0.49.15 → 0.49.16

package/changes/0.49.16.md

@@ -0,0 +1,15 @@
+# 0.49.16
+
+## Added
+- None.
+
+## Changed
+- The bundled `scriptctl` skill routes full-script, episode, scene,
+  continuation, and continuous-body authoring through `.scriptctl` files and
+  `write`; `do` is reserved for small heterogeneous edits.
+
+## Fixed
+- None.
+
+## Breaking
+- None.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lingjingai/scriptctl",
-  "version": "0.49.15",
+  "version": "0.49.16",
   "description": "剧本阶段统一 CLI：素材转 Script v3、本地完整块批量写作与替换、原子精修、校验和发布。",
   "type": "module",
   "bin": {

package/skills/scriptctl/SKILL.md

@@ -2,8 +2,8 @@
 name: scriptctl
 description: "剧本 script.json 的本地读写 + 入库 CLI。远端剧本先 checkout 成工作副本；完整剧集/场/正文区间用 export + 文件化 authoring + write plan/apply 批量创作或替换，细小精修用原子 verb/do；完成后 publish 严格按 revision 入库。也覆盖 ingest、查询、资产/state、校验。剧本阶段做任何剧本相关读写、以及操作两个 script.json 之前都应加载。"
 metadata:
-  version: "0.25.1"
-  scriptctl_version: "0.49.15"
+  version: "0.25.2"
+  scriptctl_version: "0.49.16"
   author: "official"
 ---
 
@@ -13,7 +13,7 @@ metadata:
 
 三条主线：
 - **转剧本入库**：`ingest`（抽取，产出 `workspace/script.json`）→ 标准化复核 → `view`（自查）→ `publish`（入库）。见 [references/ingest-workflow.md](references/ingest-workflow.md)。
-- **完整块创作/替换**：`ids` → 写 `.scriptctl` authoring 文件，或先 `export` 既有完整块 → `write` plan → `write --apply --plan <digest>`。
+- **完整块创作/替换**：从零时直接分配 canonical ID 并写完整 `.scriptctl`；修改本地既有剧本时用 `ids` 取新 ID、用 `export` 取既有完整块 → `write` plan → `write --apply --plan <digest>`。
 - **精修既有剧本**：查询 + 原子写 + 选择器批量 + `do`。
 
 ## 标准剧本通用流程：先把可引用世界建完整
@@ -21,10 +21,10 @@ metadata:
 从零创作、视频提取、小说或非标准剧本解析、洗稿/对标/转绘的目标稿统一执行以下流程；“正文”指 scene 下的 `action / dialogue / inner_thought / transition`。完整生产写作规范见 [references/production-writing-standard.md](references/production-writing-standard.md)。
 
 1. **忠实理解输入**：创作时落实题材、集纲和人物关系；提取与解析时保留源素材可验证的对白、动作、顺序、场界和状态变化。把不确定信息标为待复核，不补写源素材未表达的事实。
-2. **注册资产**：先读现有人物、地点、道具；正文将出现的资产先用 `add-actor / add-location / add-prop` 注册。人物保留一个稳定的 `actor_name` 作为真名，称呼、绰号、职位放 `aliases[]`，同一人物共用一个 actor。
-3. **建好资产状态**：每个新资产自带 `default` state；先用 `state-rename` + `describe <kind:id/default>` 定义常态，持久、可复用、需要独立生成视觉资产的变体再用 `state-add` 建立。
-4. **建立真实场并绑定资产**：`insert <ep> --location` 建 scene 后，用 `scene-ref <ep/scn> <kind:id> --state <state_id>` 绑定本场地点、全部人物、全部道具及其实际状态。同一人物需要多份场景引用时，用 `--append` 逐份追加；正文中出现的资产属于本场引用集合。
-5. **写入或标准化正文**：资产批次落盘并读回确认后再写正文。发现新资产或新 state 时，先完成资产和 scene-ref，再继续正文。
+2. **注册资产**：先读现有人物、地点、道具；正文将出现的资产必须先注册。批量创作在 authoring `<create>` 中声明，ingest 由抽取流程建立。人物保留一个稳定的 `actor_name` 作为真名，称呼、绰号、职位放 `aliases[]`，同一人物共用一个 actor。
+3. **建好资产状态**：每个新资产必须有唯一的 `default` state；批量创作在 `<create>` 中随资产声明，持久、可复用、需要独立生成视觉资产的变体再声明独立 state。
+4. **建立真实场并绑定资产**：完整 scene 显式声明本场地点、全部人物、全部道具及其实际 state。同一人物需要多份场景引用时，写多条 cast 并保留顺序；正文中出现的资产属于本场引用集合。
+5. **写入或标准化正文**：从零、续写和连续正文修改使用 `.scriptctl` authoring 文件；已有目标先 `export`，再执行 `write` plan/apply。ingest 先完成抽取，大块标准化修改同样走 export/write。发现新资产或新 state 时，先补入 `<create>` 和 scene 引用，再继续正文。
 6. **逐场复核**：每批正文落盘后读回 `scenes / actions`；一集完成后运行 `validate`。`validate` 通过只代表结构与引用合法，仍需完成内容标准和源素材一致性复核。
 
 ### 动作描述必须可唯一解析
@@ -44,7 +44,7 @@ location 表示可独立布置、可独立生成参考图、可重复引用的
 
 跨地点蒙太奇按剪辑顺序建立多个短 scene，每个 scene 绑定自己的地点、实际人物、道具和 state，并用 transition 明确蒙太奇开始、切换和结束。纯空镜 scene 绑定实际 location 与关键道具即可，不创建虚假人物。
 
-人物在同一连续场内需要多份视觉参考时，先绑定第一份引用，再用 `scene-ref ... actor:<id> --state <state_id> --append` 追加其余引用；用 `--occurrence <n>` 精确修改或删除第 n 份同人物引用。地点切换、跳时或叙事线切换仍建立新 scene。收尾时用 `scenes --in <ep>` 复核相邻场界。完整命令顺序见 [references/atomic-write-workflow.md](references/atomic-write-workflow.md)。
+人物在同一连续场内需要多份视觉参考时，在完整 scene 中按画面需要写多条 cast 引用并保留顺序。地点切换、跳时或叙事线切换仍建立新 scene。收尾时用 `scenes --in <ep>` 复核相邻场界。少量既有内容精修见 [references/atomic-edit-workflow.md](references/atomic-edit-workflow.md)。
 
 ## 先定本地文件
 
@@ -69,9 +69,11 @@ 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"
+# 建/写新剧：直接分配 canonical ID，用 authoring 文件一次表达资产、状态、集、场和正文
+scriptctl write new-story.scriptctl --create \
+  --script-path "$NEW"                    # plan
+scriptctl write new-story.scriptctl --create --apply --plan sha256:... \
+  --script-path "$NEW"                    # apply
 
 # 逐场对照：同一集在两份里并排看
 scriptctl scenes --in ep_003              --script-path "$ORIG"
@@ -154,10 +156,10 @@ scriptctl emotion --in ep_003..ep_007 --actor act_001 "紧张" --apply
 
 ### 完整块批量创作与替换（`export` → authoring 文件 → `write`）
 
-写一整本、整集、整场，或替换中间连续几集/几场/几条 action 时，使用 `.scriptctl` authoring 文件，不把结构化 JSON 直接交给模型写。完整语法与约束见 [references/bulk-authoring.md](references/bulk-authoring.md)。
+从零写、向后续写、大量正文变更，以及写一整本、整集、整场或替换中间连续几集/几场/几条 action 时，使用 `.scriptctl` authoring 文件。完整语法与约束见 [references/bulk-authoring.md](references/bulk-authoring.md)。
 
 ```bash
-# 先取候选 ID；只读、不预留
+# 修改既有剧本时先取候选 ID；只读、不预留
 scriptctl ids --kind actor --count 2 --script-path workspace/script.json
 scriptctl ids --kind scene --count 4 --script-path workspace/script.json
 
@@ -177,17 +179,18 @@ scriptctl write rewrite.scriptctl --replace --apply --plan sha256:... \
 
 | 需求 | 导出/authoring target | mode |
 |---|---|---|
-| 从零创建整本 | `export script` 作为模板，或直接写 `<script>` | `--create` |
+| 从零创建整本 | 直接分配 canonical ID，写完整 `<script>` | `--create` |
 | 追加完整集/场 | `<episode>` / `<scene parent=...>` | `--create` |
+| 向既有场末尾续写大量 action | `export scenes`，在完整 `<body>` 末尾续写 | `--replace` |
 | 一对一替换多集/多场 | `export episodes` / `export scenes` | `--replace` |
 | 用不同数量节点替换连续几集/几场 | `export episode-spans` / `export scene-spans` | `--replace` |
 | 替换某场中间连续 action | `export action-spans` | `--replace` |
 
 一个 authoring 文件只有一种 target kind。完整 episode/scene 可以是待填充空骨架，计划会报告 empty/cleared warning；单条空 content 也会提示。scene span 的每个区间只能在同一 episode；action span 只能在同一 scene。区间端点按当前数组顺序判断，不按 ID 数字判断；新 ID 可以放在 replacement 内容中，但不能当旧区间端点。所有 span 都必须有非空 replacement。`write` 每次都持有本地独占锁，应用时还校验计划绑定的语义基线并用临时文件原子替换。
 
-### 异构批量 `do`（一组各不相同的改动 = 一段动词脚本 = 一个事务）
+### 少量异构精修 `do`（一组各不相同的改动 = 一个事务）
 
-每行就是一条**去掉 `scriptctl` 的命令**，`#` 注释、空行随意；整段全成或全不成。比手写 patch JSON 省心（动词原样，不猜字段名）。
+`do` 用于对既有剧本执行少量、离散、彼此不同的精修。每行是一条去掉 `scriptctl` 的命令，整段全成或全不成。完整场、集、整本和连续正文的创作或替换使用 authoring `write`。
 
 ```bash
 scriptctl do edits.txt           # 默认 dry-run（预演 + 校验，不写）
@@ -201,9 +204,9 @@ insert    ep_001/scn_006 --type action --content "暗夜，街道空无一人。
 EOF
 ```
 
-`do` 也读 stdin（`scriptctl do -`）。结构性动词（insert/delete/move/split/merge）**只能**走单点或 `do`，不进选择器批量（索引会漂移）。目标 flag（如 `--script-path`）加在 `do` 命令本身上，整段脚本共用同一目标。
+`do` 也读 stdin（`scriptctl do -`）。少量结构性精修中的 insert/delete/move/split/merge 走单点或 `do`，不进选择器批量（索引会漂移）。目标 flag（如 `--script-path`）加在 `do` 命令本身上，整段脚本共用同一目标。
 
-### 建（从零起一本剧本，不要 address，第一个位置参数是名字）
+### 原子建模命令（少量补充资产或骨架）
 
 | 想做什么 | 命令 |
 |---|---|
@@ -213,7 +216,7 @@ EOF
 | 加道具 | `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)。
+这些命令适合给既有剧本少量补充资产、集或空场。完整新剧及完整场/集创作使用 `.scriptctl` authoring 文件；全新剧本直接分配 canonical ID，既有本地剧本用 `ids` 取得未占用候选 ID，再执行 `write --create` plan/apply。
 
 ### Address 格式（决定 verb 作用对象，自动分发）
 
@@ -287,7 +290,7 @@ scriptctl do fixes.txt --apply                                            # 异
 
 | 项目状态 | 走 |
 |---|---|
-| 没剧本文本，从零写（题材/灵感/集纲在手） | `create` + `add-*` + `insert` + `do`（正文你自己写），然后 `publish` |
+| 没剧本文本，从零写（题材/灵感/集纲在手） | 直接分配 canonical ID → 生成完整 `.scriptctl` → `write --create` plan/apply → `validate` → `publish` |
 | 已有剧本/分镜/小说文本（txt/md/docx） | `scriptctl ingest --source-path <file>` → `view` 自查 → `publish` |
 | 有视频（正片文件或分集目录） | `scriptctl ingest --source-path <file\|dir>` → `view` 点击定位复核 → `publish` |
 
@@ -340,7 +343,7 @@ scriptctl ingest status --json     # 机器：.status = {kind,state,phase,passes
 
 **默认状态（default）**：每个有 `states[]` 的资产必须有且仅有一个 `state_id: "default"`（最常见常态外观，保留可读 state_name）。`ingest` 会自动把「默认/最常见」那档 canonical 成 `default`；手动 `state-add` 给原先无状态的资产加第一个 state 后，若校验报 `DEFAULT_STATE_MISSING`，把最常见那档的 state_id 设成 `default`。
 
-`add-actor / add-location / add-prop` 会自动建立 `default`。从零写正文时要先用 `state-rename <kind:id/default> <名称>` 和 `describe <kind:id/default> <描述>` 把它定义成可用的常态，再将实际 state 绑定到 scene-ref；不能用 `--state none` 跳过。
+原子 `add-actor / add-location / add-prop` 会自动建立 `default`；少量增补资产时，用 `state-rename` 和 `describe` 定义常态，再将实际 state 绑定到 scene-ref。文件化创作在 `<create>` 中直接声明每个新资产唯一的 `default` state，并在完整 scene 中绑定实际 state。
 
 合并/删除 state 时，必须确认引用它的场景 `scene-ref --state` 已被正确修复；操作见 [references/state-reference-repair.md](references/state-reference-repair.md)。
 
@@ -348,7 +351,7 @@ scriptctl ingest status --json     # 机器：.status = {kind,state,phase,passes
 
 - 🔴 **不要加 `--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>]`。
+- 🔴 **少量异构精修走 `do`**；完整场、集、整本和连续正文写作走 `.scriptctl` authoring + `write`。`scriptctl patch <file|->` 只用于机器/jq 管道（`… --json | jq '[…]' | scriptctl patch -`）；需要 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` 等读写命令**不打模型**。

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

@@ -0,0 +1,60 @@
+# 原子精修
+
+适用：对既有剧本做少量、明确、离散的修改。完整场、集、整本和连续正文的创作或替换见 [bulk-authoring.md](bulk-authoring.md)。
+
+## 路由
+
+| 修改形态 | 使用方式 |
+|---|---|
+| 一个明确地址 | 单个原子 verb |
+| 同一种变换命中多个 action | 选择器批量 verb |
+| 少量、不同类型、需要同事务落盘的修改 | `do` |
+
+## 单点精修
+
+先查询得到稳定地址，再执行对应 verb：
+
+```bash
+scriptctl actions --grep "台下掌声雷动" --script-path workspace/script.json
+scriptctl replace ep_001/scn_001#3 \
+  --from "台下掌声雷动" --to "掌声骤然停下" \
+  --script-path workspace/script.json
+```
+
+资产、state 和场景引用也先查询再修改：
+
+```bash
+scriptctl states act_001 --script-path workspace/script.json
+scriptctl scene-ref ep_001/scn_003 actor:act_001 \
+  --state st_injured --script-path workspace/script.json
+```
+
+## 同构批量精修
+
+查询和写入共用选择条件。多点写默认只生成计划，加 `--apply` 才落盘：
+
+```bash
+scriptctl actions --in ep_003..ep_007 --actor act_001 \
+  --script-path workspace/script.json
+scriptctl emotion --in ep_003..ep_007 --actor act_001 "紧张" \
+  --script-path workspace/script.json
+scriptctl emotion --in ep_003..ep_007 --actor act_001 "紧张" --apply \
+  --script-path workspace/script.json
+```
+
+## 少量异构精修
+
+`do` 文件每行是一条去掉 `scriptctl` 的原子命令。先 dry-run，再原子应用：
+
+```text
+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
+```
+
+```bash
+scriptctl do fixes.txt --script-path workspace/script.json
+scriptctl do fixes.txt --apply --script-path workspace/script.json
+```
+
+精修后读回受影响的 scenes/actions，并运行 `validate`。

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

@@ -5,7 +5,7 @@
 ## 固定工作流
 
 1. 既有远端剧本先 `checkout` 到 `--script-path`。
-2. 新 ID 用 `ids --kind ... --count ...` 查询候选值。它不预留 ID。
+2. 修改本地既有剧本时，新 ID 用 `ids --kind ... --count ...` 查询候选值；它不预留 ID。全新剧本没有可供 `ids` 读取的本地文件，直接从各 kind 的 `_001` 开始分配 canonical ID。
 3. 修改既有内容先用 typed `export` 导出完整目标；从零写时直接生成完整 `.scriptctl` 文件。
 4. `write FILE --create|--replace` 只做计划。
 5. 从计划读取完整 `plan_digest`。

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

@@ -1,176 +0,0 @@
-# 从零原子写 — 资产先行，按真实场界写正文
-
-适用：**没有现成剧本文本**，从零写（手里只有题材 / 灵感 / 集纲）。
-
-核心理念：**写手是你**。你自己想好每一句正文，用原子能力把它灌进结构化剧本里。scriptctl 负责「合法的骨架 + 引用完整性 + 校验」，不负责「写得好不好」。
-
-人物、路人群体、地点粒度、门口跨空间、蒙太奇、对白、Action 和场内状态变化统一执行 [production-writing-standard.md](production-writing-standard.md)。
-
----
-
-## 端到端流程
-
-```
-create（空白剧本，既有剧本略过）
-  → worldview                              设世界观
-  → 资产批次
-      add-actor / add-location / add-prop 注册或完善资产
-      state-rename / state-add / describe 定义默认与持久视觉状态
-      do assets.txt --apply → 读回资产与 states
-  → 正文批次
-      add-episode / synopsis               建分集与梗概
-      insert <ep> --location               仅在真实场界处建 scene
-      scene-ref --state                    绑定本场全部资产与实际 state
-      insert <ep/scn> --type ...           按 action 批次连续写正文
-  → scenes / actions / validate               收尾自查
-  → publish                                   入库（沙箱必做）
-```
-
-> 发声源写在**对白行内联**（`dialogue <at> --actor/--kind`，或 `insert --actor/--kind`）；造型挂在**场景 cast 引用**上（`scene-ref <ep/scn> <kind:id> --state`）。同一人物需要多份引用时用 `--append` 追加，用 `--occurrence <n>` 定位第 n 份。正文插入前，本场必须已有地点，并且本场全部地点/人物/道具引用都绑定已建立的 state。空镜、环境动作或非角色发声场可以没有人物引用。
-
-资产/分集/场景的 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 state-rename actor:act_001/default "平日造型"
-scriptctl describe actor:act_001/default "整洁校服，黑色长发"
-scriptctl state-rename actor:act_002/default "夜班造型"
-scriptctl describe actor:act_002/default "便利店制服，胸前佩戴工牌"
-scriptctl state-rename location:loc_001/default "常态"
-scriptctl describe location:loc_001/default "冷白灯全部亮起"
-scriptctl add-episode --title "第一集：相遇"
-scriptctl synopsis "雨夜便利店里，林夏与夜班店员陈默因一场意外相遇。"
-scriptctl synopsis ep_001 "林夏雨夜进入便利店，发现陈默似乎认识她。"
-scriptctl insert ep_001 --location loc_001 --time night --space interior   # → scn_001
-scriptctl scene-ref ep_001/scn_001 location:loc_001 --state default
-scriptctl scene-ref ep_001/scn_001 actor:act_001 --state default
-scriptctl scene-ref ep_001/scn_001 actor:act_002 --state default
-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
-```
-
-同一人物在本场需要第二份参考时，继续追加而不是新建 actor：
-
-```bash
-scriptctl scene-ref ep_001/scn_001 actor:act_001 --state st_rain --append
-scriptctl scene-ref ep_001/scn_001 actor:act_001 --state default --occurrence 2
-scriptctl scene-ref ep_001/scn_001 actor:act_001 --remove --occurrence 2
-```
-
-### B. 整集 / 整本（推荐）：资产与正文分两段 `do`
-
-一集几十个 action 用 `do` 批量写入。先独立落盘资产批次，读回自动分配的 id；再用正文批次建集、按真实场界建 scene、绑定 state 并写 action。这两次落盘让宿主先展示人物、地点、道具及状态，再展示正文。
-
-```bash
-scriptctl create --title "夏夜便利店"   # 先有空白剧本
-scriptctl do assets.txt                  # 资产批次 dry-run
-scriptctl do assets.txt --apply          # 先落盘资产与 states
-scriptctl actors                         # 读回资产 id
-scriptctl locations
-scriptctl props
-scriptctl states act_001                 # 逐个确认 state id / 名称 / 描述
-scriptctl states loc_001
-scriptctl states prp_001
-scriptctl do ep01.txt                    # 正文批次 dry-run
-scriptctl do ep01.txt --apply            # 再落盘场景与正文
-```
-
-`assets.txt` 先注册资产与持久视觉状态：
-
-```
-worldview 现代
-add-actor 林夏 --role 主角 --description "高三女生，沉默寡言"
-add-actor 陈默 --role 配角 --description "便利店夜班店员"
-add-location 便利店 --description "24h 便利店，冷白光"
-add-prop 黑伞 --description "林夏随身携带的旧黑伞"
-state-rename actor:act_001/default "平日造型"
-describe actor:act_001/default "整洁校服，黑色长发"
-state-add actor:act_001 "雨天造型" --state-id st_rain --description "校服湿透，发梢滴水"
-state-rename actor:act_002/default "夜班造型"
-describe actor:act_002/default "便利店制服，胸前佩戴工牌"
-state-rename location:loc_001/default "常态"
-describe location:loc_001/default "冷白灯全部亮起"
-state-add location:loc_001 "停电" --state-id st_outage --description "冷白灯熄灭，应急灯发绿"
-state-rename prop:prp_001/default "常态"
-describe prop:prp_001/default "伞面完整，伞骨可正常开合"
-state-add prop:prp_001 "破损" --state-id st_torn --description "伞面裂开，一根伞骨外翻"
-```
-
-`ep01.txt` 再建分集和真实 scene，然后写正文：
-
-```
-add-episode --title "第一集：相遇"
-synopsis "雨夜便利店里，林夏与夜班店员陈默因一场意外相遇。"
-synopsis ep_001 "林夏雨夜进入便利店，发现陈默似乎认识她。"
-insert ep_001 --location loc_001 --time night --space interior
-scene-ref ep_001/scn_001 actor:act_001 --state st_rain
-scene-ref ep_001/scn_001 actor:act_002 --state default
-scene-ref ep_001/scn_001 location:loc_001 --state default
-scene-ref ep_001/scn_001 prop:prp_001 --state default
-insert ep_001/scn_001 --type action   --content "雨夜，林夏推门进店。" --emotion "狼狈"
-insert ep_001/scn_001 --type dialogue --content "欢迎光临。" --actor act_002
-```
-
-地点、时段和叙事线连续时，后续节拍继续向 `ep_001/scn_001` 追加 action。同场人物需要多个造型或多份画面引用时，对同一 actor 追加 scene-ref，并在 Action 中写清变化顺序。互动式写作可把长场拆成多个 action 批次依次 `do --apply`，每批都指向同一 scene。场界规则以 SKILL.md「标准剧本通用流程」为准。
-
-动词与单条命令完全一致（参数见 `scriptctl <verb> --help`）。`do` 也读 stdin：`… | scriptctl do -`。
-
-> 机器/程序化生成的批量（如 jq 变换查询结果）才用 JSON：`scriptctl actions … --json | jq '[…ops…]' | scriptctl patch -`。手写一律 `do`。
-
----
-
-## 写到哪里去（落库）
-
-`create` 和所有编辑 verb 只写本地 `--script-path <file>`；省略时是
-`<cwd>/workspace/script.json`。远端剧本必须遵循：
-
-```text
-checkout → 本地查询/原子编辑/do/patch → validate → publish
-```
-
-- 已有远端剧本先 `scriptctl checkout --script-path draft.json`。
-- 全程对同一个 `draft.json` 编辑。新增原子能力只需实现本地操作，不增加远端业务 API。
-- `scriptctl status --script-path draft.json` 查看是否 dirty。
-- `scriptctl publish --script-path draft.json` 拉最新 snapshot 后以本地稿为准生成 patch；CAS/网络失败会重拉重试，最终远端内容与本地稿一致。
-- 本地新剧可直接 create/ingest 后首次 publish；没有 working-copy metadata 时只尝试从 revision 0 创建。
-
-### 两份 script.json（洗稿 / 对标 / 转绘）
-
-同时开着原剧与新剧时，一次只作用于 `--script-path` 指的那份：从原剧读（`summary`/`actions`（带 timestamp）/`states`（带弧线）/`scenes`（带时段）），往新剧写（`create` → `do --apply`）。换文件 = 换 `--script-path` 的值。详见 SKILL.md「两个 script.json」。
-
----
-
-## 校验语义（重要）
-
-空骨架可以逐步搭建，但正文入口有更严格的前置门：
-
-- **骨架阶段**：可以先建空剧本、空集和空场，再逐项补资产引用。
-- **正文插入门**：`insert <ep/scn>` 要求本场已有地点，且本场全部地点/人物/道具引用都带已物化 state；对白/心声使用 actor 时，该 actor 必须已在本场 cast。空镜、环境动作或非角色发声场可以没有人物引用。
-- **全局硬错误**：悬挂引用、重复 id、人物真名重复、说话人物不在本场、非法枚举、缺 id/name、非人类注册成 actor。
-
-随时 `scriptctl validate` 看整体，`scriptctl issues --severity warning` 专看「还没填」的清单。
-
----
-
-## 提醒
-
-- 资产 state 判定（哪些进 `states[]`）见 SKILL.md「资产 state 判定」。
-- 非角色发声源（系统/广播/画外/群体）用 `dialogue <at> --kind system|broadcast|offscreen|group [--label ...]`（对白行内联），**不要**注册成 actor。
-- 人物真名全剧唯一且稳定：动作中只用 `actor_name`；称呼、绰号、职位放 aliases，只能出现在自然对白等不要求资产解析的文本里。别在名字里塞状态注解（`林夏（受伤）`会被拒），外观档位用 `state-add`。
-- action 禁止“他 / 她 / 对方 / 其中一人 / 另一个人”等指代；逐个写明行动者真名。对白内容允许自然使用人称代词。
-- action 写明具体动作、作用对象、空间方向和可见结果；对白的短促伴随动作放 `emotion`，影响走位、道具或连续性的动作单独写 action。
-- 一个 scene 只绑定一个地点和每项资产的一个 state；多地点或多状态参考需求按 [production-writing-standard.md](production-writing-standard.md) 处理并报告结构限制。
-- action 情绪放 `emotion` 字段：插入时用 `insert ... --emotion "紧张"`，修改时用 `emotion <ep/scn#idx> "紧张"` / `emotion <ep/scn#idx> --clear`，不要把 `[紧张]` 这类标记塞进 content。
-- 参数 / 退出码以 `scriptctl <cmd> --help` 为准。