@lingjingai/scriptctl 0.49.16 → 0.51.0

package/skills/scriptctl/SKILL.md

@@ -1,365 +1,211 @@
 ---
 name: scriptctl
-description: "剧本 script.json 的本地读写 + 入库 CLI。远端剧本先 checkout 成工作副本；完整剧集/场/正文区间用 export + 文件化 authoring + write plan/apply 批量创作或替换，细小精修用原子 verb/do；完成后 publish 严格按 revision 入库。也覆盖 ingest、查询、资产/state、校验。剧本阶段做任何剧本相关读写、以及操作两个 script.json 之前都应加载。"
+description: "剧本 script.json 的本地查询、文件化批量写作、原子精修、素材 ingest 与 revision publish CLI。处理 Script v3/v4、两个 script.json、剧本资产/state、Action、场景引用或 authoring 时使用。"
 metadata:
-  version: "0.25.2"
-  scriptctl_version: "0.49.16"
+  version: "0.27.0"
+  scriptctl_version: "0.51.0"
   author: "official"
 ---
 
 # scriptctl
 
-`scriptctl` 读写结构化剧本 `script.json`，并把外部素材转成剧本、入库。查询和原子编辑始终作用于本地文件；远端只在 `checkout` / `publish` 边界访问。
+`scriptctl` 始终对 `--script-path` 指向的本地 `script.json` 工作。远端剧本先
+`checkout`，完成本地查询、修改和 `validate` 后再 `publish`。
 
-三条主线：
-- **转剧本入库**：`ingest`（抽取，产出 `workspace/script.json`）→ 标准化复核 → `view`（自查）→ `publish`（入库）。见 [references/ingest-workflow.md](references/ingest-workflow.md)。
-- **完整块创作/替换**：从零时直接分配 canonical ID 并写完整 `.scriptctl`；修改本地既有剧本时用 `ids` 取新 ID、用 `export` 取既有完整块 → `write` plan → `write --apply --plan <digest>`。
-- **精修既有剧本**：查询 + 原子写 + 选择器批量 + `do`。
+## 先识别版本
 
-## 标准剧本通用流程：先把可引用世界建完整
+读取 `script.json.version`：
 
-从零创作、视频提取、小说或非标准剧本解析、洗稿/对标/转绘的目标稿统一执行以下流程；“正文”指 scene 下的 `action / dialogue / inner_thought / transition`。完整生产写作规范见 [references/production-writing-standard.md](references/production-writing-standard.md)。
+- Script v4：新建和 ingest 的默认方言。episode、scene、Action、asset 使用带类型前缀的短随机 ID；修改只用正式 ID。
+- Script v3：线上既有项目的冻结方言。查询、修改、authoring 和 publish 继续使用 v3 地址与字段。
+
+不要根据字段形状猜版本。命令会按显式 `version` 自动分流。
+
+## 标准剧本通用流程
 
 1. **忠实理解输入**：创作时落实题材、集纲和人物关系；提取与解析时保留源素材可验证的对白、动作、顺序、场界和状态变化。把不确定信息标为待复核，不补写源素材未表达的事实。
 2. **注册资产**：先读现有人物、地点、道具；正文将出现的资产必须先注册。批量创作在 authoring `<create>` 中声明，ingest 由抽取流程建立。人物保留一个稳定的 `actor_name` 作为真名，称呼、绰号、职位放 `aliases[]`，同一人物共用一个 actor。
 3. **建好资产状态**：每个新资产必须有唯一的 `default` state；批量创作在 `<create>` 中随资产声明，持久、可复用、需要独立生成视觉资产的变体再声明独立 state。
-4. **建立真实场并绑定资产**：完整 scene 显式声明本场地点、全部人物、全部道具及其实际 state。同一人物需要多份场景引用时，写多条 cast 并保留顺序；正文中出现的资产属于本场引用集合。
+4. **建立真实场并绑定资产**：完整 scene 显式声明本场地点、全部人物、全部道具及其实际 state。V4 同一资产只出现一条场景引用，完整状态写入无序 `state_ids` 集合；V3 按其既有单状态引用结构处理。
 5. **写入或标准化正文**：从零、续写和连续正文修改使用 `.scriptctl` authoring 文件；已有目标先 `export`，再执行 `write` plan/apply。ingest 先完成抽取，大块标准化修改同样走 export/write。发现新资产或新 state 时，先补入 `<create>` 和 scene 引用，再继续正文。
 6. **逐场复核**：每批正文落盘后读回 `scenes / actions`；一集完成后运行 `validate`。`validate` 通过只代表结构与引用合法，仍需完成内容标准和源素材一致性复核。
+7. **全剧资产审计**：全剧完成后运行 `audit-assets --script-path <file>`，检查人物身份重复、同义视觉状态、未使用/落单状态，以及重复地点和道具资产。审计只给建议，不自动合并；必须核对剧情、身份、外观和跨集连续性后再修复。
 
-### 动作描述必须可唯一解析
-
-- `action.content` 中禁止人称代词和依赖上下文猜测的指代，包括“他 / 她 / 它 / 他们 / 她们 / 对方 / 其中一人 / 另一个人 / 前者 / 后者 / 有人 / 两人”等。每一个独立行动者都使用其唯一 `actor_name`：写“林夏拿起铁棒，陈默关门”，不写“她拿起铁棒，另一个人关门”。
-- 动作描述只用 `actor_name`，不用 alias、职位或临时称呼代替真名。`dialogue.content` 可以自然使用“我 / 你 / 他是谁”等人称代词；对白的说话人仍必须通过 `--actor <actor_id>` 明确绑定。非角色声源用 `--kind system|broadcast|offscreen|group`，不能伪造 actor。
-- Action 写成可直接转化为画面的行为链，明确行动者、具体动作、作用对象、空间方向和可见结果；需要镜头控制时补充景别、机位、镜头运动和画面焦点。把抽象心理和评价转成表情、肢体、道具变化或环境反应。
-- 每条 dialogue 绑定说话人物或非角色发声源。情绪、语气和短促伴随动作写入 `emotion`；影响走位、道具或连续性的动作单独写成 Action。两人同时说话时写成相邻两条 dialogue，第二条的 `emotion` 以“同时”开头；这是一种写作约定，不表示结构化重叠时间轴。
-- 凡是能独立说话、拿取或交接道具、推动动作的人，即使只出现一次，也注册为 actor（可设 `importance background`）。无法区分成员、无需连续造型的环境人群写成群体 Action；群体共同发声使用 `--kind group --label <群体名>`。`group` 只是一条对白的发声源，不创建人物资产、state 或参考图。仅有 group 发声、没有可识别 actor 的场面可直接写入，scene 绑定实际 location 与关键道具。
-- CLI 只校验显式结构关系，不从自由文本猜资产。写作者必须逐句保证正文中的真名、地点和道具都能映射到本场 `scene-ref`。
-
-### 场界判定
-
-场是时间、空间和叙事连续的单元。同一地点、同一连续时段、同一叙事线且动作未中断时，继续向当前 scene 追加；笑点升级、攻防回合、角色进出、剧情节拍和同场人物造型变化不是分场理由。地点切换、明显跳时、切到另一条同时叙事线或明确转场时建立新 scene。一集可以只有一场。
-
-location 表示可独立布置、可独立生成参考图、可重复引用的稳定物理空间；客厅、卧室、卫生间、大厅、广场分别注册。相关空间使用“豪宅·客厅”“豪宅·卧室”这类统一命名表达归属。每个 scene 绑定一个 location；人物引用可以重复，同一 actor 可按实际画面追加同 state 或不同 state 的多份引用。
+## 三条工作流
 
-跨地点蒙太奇按剪辑顺序建立多个短 scene，每个 scene 绑定自己的地点、实际人物、道具和 state，并用 transition 明确蒙太奇开始、切换和结束。纯空镜 scene 绑定实际 location 与关键道具即可，不创建虚假人物。
+1. 素材转剧本：`ingest` → 内容复核 → `view` / `validate` → `publish`。见
+   [references/ingest-workflow.md](references/ingest-workflow.md)。
+2. 完整块创作或替换：`ids` → `export` 或新写 `.scriptctl` → `write` plan →
+   `write --apply --plan <digest>`。见
+   [references/bulk-authoring.md](references/bulk-authoring.md)。
+3. 少量精修：查询定位 → 单 ID 原子 verb；同构多点用 selector；异构多点用
+   `do`。见 [references/atomic-edit-workflow.md](references/atomic-edit-workflow.md)。
 
-人物在同一连续场内需要多份视觉参考时，在完整 scene 中按画面需要写多条 cast 引用并保留顺序。地点切换、跳时或叙事线切换仍建立新 scene。收尾时用 `scenes --in <ep>` 复核相邻场界。少量既有内容精修见 [references/atomic-edit-workflow.md](references/atomic-edit-workflow.md)。
+## 本地文件边界
 
-## 先定本地文件
+- 普通命令默认读取 `<cwd>/workspace/script.json`；操作其他文件时始终显式传
+  `--script-path <file>`。
+- `--workspace-path` 只属于 `ingest`、`ingest status` 和 `view`。
+- 同时处理原剧与目标剧时，每条命令都显式带对应 `--script-path`，只从原剧读，
+  只向目标剧写。
+- `checkout` 不覆盖未管理文件或本地修改；`publish` 按工作副本 revision 严格写入。
 
-- 查询、`write`、`export`、`ids`、`create`、全部原子编辑、`do`、`patch` 只接受 `--script-path <file>`；省略时统一使用 `<cwd>/workspace/script.json`。
-- 编辑远端已有剧本：先 `scriptctl checkout [--script-path FILE]`，再对该文件运行任意原子命令，最后 `scriptctl publish [--script-path FILE]`。
-- `checkout` 会建立 `.scriptctl/<filename>.working-copy.json`，记录远端项目、API 地址、base revision 和语义内容 hash。已有未管理文件或有本地修改时拒绝覆盖；只有明确 `--discard-local` 才丢弃。
-- `status` 完全本地判断 managed / clean / dirty，不访问网络。
-- `publish` 对已管理文件拉取最新 snapshot，以本地稿为准计算 diff 后严格 CAS PATCH；CAS 或网络失败会重拉、重算、重试。干净工作副本不访问网络。无 metadata 的文件只允许以 base revision 0 首次发布。
-- 所有写命令按文件加锁；外部编辑器在命令期间改文件也会在落盘前被检测并拒绝覆盖。
-- `--workspace-path` 仍只属于 `ingest` / `view` / `ingest status`；普通读写和 publish 用 `--script-path`。
+## 查询与定位
 
-### 两个 script.json：洗稿 / 对标 / 转绘
+默认文本查询输出 TSV。需要结构化数据时使用 `--json`：顶层固定包含
+`ok`、`exit_code`，表格数据位于 `rows`，列顺序位于 `row_columns`。地址流使用
+`--format addr`。写命令的 JSON 使用 `op`、`changed`、`plan_digest`、
+`validation`、`script_path` 等命令自身字段，不包含展示用的标题或结果区块。
+JSON 错误包含 `error_code`、`message` 和可选 `hint`。
 
-洗稿、对标仿写、转绘（换地区/换壳）里常常**同时开着原剧和新剧两份 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"   # 看人物状态弧线
-
-# 建/写新剧：直接分配 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"
-scriptctl scenes --in ep_003              --script-path "$NEW"
+scriptctl summary --script-path "$SCRIPT"
+scriptctl episodes --script-path "$SCRIPT"
+scriptctl scenes --in '@ep:3' --script-path "$SCRIPT"
+scriptctl actions --grep "台下掌声" --script-path "$SCRIPT"
+scriptctl actors --counts --script-path "$SCRIPT"
+scriptctl states actA3kP9x --script-path "$SCRIPT"
+scriptctl refs actA3kP9x/stB4xR8p --script-path "$SCRIPT"
+scriptctl validate --script-path "$SCRIPT"
 ```
 
-- 一次只碰一份。要「从 A 抄到 B」就是：`--script-path A` 读出来 → 你决定改法 → `--script-path B` 写进去。
-- 事件级对齐：原剧 `actions` 的 `timestamp` 列 + `scenes` 的 `t=t_start..t_end` 给出每段的时间跨度；对标时按这个跨度切新剧的段落。
-- 人物状态弧线：`states <actor>` 每个状态末尾的 `episodes=<区间>` 告诉你某个造型/形态在原剧哪些集出现，转绘时据此规划新剧的状态。
+序号锚点是 1-based 查询语法：
 
-## 能干什么
+- `@ep:3`
+- `@ep:3/scn:2`
+- `@ep:3/scn:2/ac:5`
+- `@scn:12`
+- `@ac:48`
 
-### 读（永远只读、永远安全）
+区间包含两端，端点正反等价，按当前文档顺序解释。V4 查询返回正式 ID；V3
+查询返回可写的 v3 地址。先按序号或正文查询，再把结果中的正式地址用于修改。
 
 | 想做什么 | 命令 |
 |---|---|
 | **了解剧情 / 全貌**：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` |
+| 看某集的所有场（含 `t=t_start..t_end` 时段） | `scriptctl scenes --in '@ep:7'` |
+| 看某场的资产 + action 数 | `scriptctl scenes --in '@ep:7/scn:5'` |
 | **按正文搜某句话定位 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`） |
+| 列某集所有 action（含 timestamp / speaker / 正文 /表演提示） | `scriptctl actions --in '@ep:1'` |
+| 看单条 action 正文 | `scriptctl actions --in '@ep:1/scn:1/ac:3'` |
+| action 多维过滤 | `scriptctl actions --in '@ep:1' --type dialogue --actor <actor-id> --has speaker` |
+| 某角色出现的所有场 | `scriptctl scenes --has-actor <actor-id>`（另有 `--has-location`/`--has-prop`） |
+| **列某资产的所有 state + 状态弧线**（改造型前必查） | `scriptctl states <asset-id>` |
 | 资产**出场统计**（几场/几集，压成集区间） | `scriptctl actors --counts` / `locations --counts` / `props --counts` |
-| 某资产 / 状态 / speaker 反查 | `scriptctl refs actor:act_001`（`refs spk_001` 反查发声源） |
+| 某资产 / 状态反查 | `scriptctl refs <asset-id>` / `scriptctl refs <asset-id>/<state-id>` |
 | 当前校验问题 / 跑校验 | `scriptctl issues --severity error` / `scriptctl validate` |
+| 全剧人物/状态/地点/道具去重审计 | `scriptctl audit-assets --script-path workspace/script.json` |
 
-**读侧要点：**
-- `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=<区间>`。默认不带，保持精简。
+## Script v4 写入
 
-### 写（单点：第一个位置参数是 address。多点：见「选择器批量」）
+V4 新 ID 是类型前缀加 6 位 Bitcoin Base58：
 
-| 想做什么 | 命令 |
-|---|---|
-| 改 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>`；同一 actor 再加一份用 `--append`，重复后用 `--occurrence <n>` 精确修改/清除/删除第 n 份。新写正文时必须给实际 state；`--clear` / `--state none` 仅用于修复中间态。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`（对白/心声再传 `--actor <id>` 或 `--kind ... [--label ...]`；本场资产及 state 未绑定会拒绝）/ `insert <ep> --location <id>` |
-| 移动/分场 | `scriptctl move <addr> <to>` / `split <ep/scn> --at <idx>` |
-| 设整本/分集剧情梗概 | `scriptctl synopsis "整本梗概"` / `scriptctl synopsis ep_001 "本集梗概"`（`synopsis generate` 用 LLM 批量生成） |
-| 设世界观 | `scriptctl worldview <现代\|古代历史\|...>` |
-
-> 发声源写在**对白行内联**：角色用 `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 / 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
+```text
+ep……  scn……  ac……  act……  loc……  prp……  st……
 ```
 
-> 先 discover 后 mutate 用**同一套 flag**：`scriptctl actions --in … --actor …` 查出来是哪些，换个动词就改哪些。`actions --json` 带结构化 `rows[]`，`actions … --format addr` 直接吐裸地址流喂 `xargs`。scene-ref/importance/dialogue 是**单点**动词，不进选择器批量。
-
-### 完整块批量创作与替换（`export` → authoring 文件 → `write`）
-
-从零写、向后续写、大量正文变更，以及写一整本、整集、整场或替换中间连续几集/几场/几条 action 时，使用 `.scriptctl` authoring 文件。完整语法与约束见 [references/bulk-authoring.md](references/bulk-authoring.md)。
+`ids` 只生成候选，不预留：
 
 ```bash
-# 修改既有剧本时先取候选 ID；只读、不预留
-scriptctl ids --kind actor --count 2 --script-path workspace/script.json
-scriptctl ids --kind scene --count 4 --script-path workspace/script.json
-
-# 改既有第 2-4 集：先导出完整块，再让模型只改导出文件
-scriptctl export episodes --in "ep_002..ep_004" \
-  --output rewrite.scriptctl --script-path workspace/script.json
-
-# 默认只生成完整计划，不写
-scriptctl write rewrite.scriptctl --replace --script-path workspace/script.json
-
-# 读取计划里的 plan_digest，原样带回；任何源文件、mode、目标或本地剧本变化都会使它失效
-scriptctl write rewrite.scriptctl --replace --apply --plan sha256:... \
-  --script-path workspace/script.json
+scriptctl ids --kind action --count 4
+scriptctl ids --kind scene --count 2 --script-path "$SCRIPT"
 ```
 
-目标选择：
-
-| 需求 | 导出/authoring target | mode |
-|---|---|---|
-| 从零创建整本 | 直接分配 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` 的命令，整段全成或全不成。完整场、集、整本和连续正文的创作或替换使用 authoring `write`。
+单点修改使用正式 ID：
 
 ```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
+scriptctl replace acR8cV4n --from "旧句" --to "新句" --script-path "$SCRIPT"
+scriptctl parenthetical acT2fG6z --set "低声" --script-path "$SCRIPT"
+scriptctl parenthetical acT2fG6z --set "" --script-path "$SCRIPT"
+scriptctl parenthetical acT2fG6z --remove --script-path "$SCRIPT"
+scriptctl dialogue acT2fG6z --actor actA3kP9x --state stB4xR8p --script-path "$SCRIPT"
 ```
 
-`do` 也读 stdin（`scriptctl do -`）。少量结构性精修中的 insert/delete/move/split/merge 走单点或 `do`，不进选择器批量（索引会漂移）。目标 flag（如 `--script-path`）加在 `do` 命令本身上，整段脚本共用同一目标。
-
-### 原子建模命令（少量补充资产或骨架）
-
-| 想做什么 | 命令 |
-|---|---|
-| 建空白剧本（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]` |
-
-这些命令适合给既有剧本少量补充资产、集或空场。完整新剧及完整场/集创作使用 `.scriptctl` authoring 文件；全新剧本直接分配 canonical ID，既有本地剧本用 `ids` 取得未占用候选 ID，再执行 `write --create` plan/apply。
-
-### Address 格式（决定 verb 作用对象，自动分发）
+`parenthetical` 只属于 dialogue / inner_thought。字段省略表示没有表演提示；显式
+空字符串与省略不同。影响走位、道具或连续性的动作写成独立 Action。
 
-| 形态 | 类型 | 例 |
-|---|---|---|
-| `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` |
+V4 placement 使用父节点与相邻节点 ID：
 
-> `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 ""
+scriptctl insert scnK6wT3c --action-id acD4eF6g \
+  --type action --content "陈默关上门。" --before acT2fG6z
+scriptctl move acD4eF6g scnH7jK9m --after acR8cV4n
+scriptctl split scnK6wT3c --at acT2fG6z --new-scene-id scnD4eF6g
 ```
-`--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
-scriptctl scene-ref ep_001/scn_003 actor:act_001 --state st_calm --append
-scriptctl scene-ref ep_001/scn_003 actor:act_001 --state st_injured --occurrence 2
-```
+V4 一个场景内同一资产只引用一次；引用携带完整、非空的 `state_ids` 集合。重复
+`--state` 传入整个集合，写入时按 state ID 排序：
 
-同一人物可在同一 scene 中出现多份引用。`--occurrence` 从 1 开始；命中多份却不指定 occurrence 时，修改、清除和删除都会拒绝执行。
-
-**整理重复角色**：
 ```bash
-scriptctl refs actor:act_005                 # 先看 act_005 出现在哪
-scriptctl merge actor:act_005 --into actor:act_001
+scriptctl scene-ref scnK6wT3c actA3kP9x \
+  --state default --state stB4xR8p --script-path "$SCRIPT"
+scriptctl scene-ref scnK6wT3c actA3kP9x --remove --script-path "$SCRIPT"
 ```
 
-**标龙套（下游省算力）**：
-```bash
-scriptctl actors --counts                                   # 看谁出场少
-scriptctl importance actor:act_042 background
-```
+actor speaker 可选一个 state；若指定，必须属于该 actor 在当前 scene 的
+`state_ids`。状态集合不表示对白级落点，也没有先后顺序。
 
-**修校验问题**：
-```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
-```
+state 修改前后都反查并校验：
 
-**批量精修（同构一片 → 选择器；异构多点 → `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                                            # 异构：一段动词脚本一事务
+scriptctl refs actA3kP9x/stB4xR8p --script-path "$SCRIPT"
+scriptctl state-delete actA3kP9x/stB4xR8p \
+  --strategy replace --replacement default --script-path "$SCRIPT"
+scriptctl validate --script-path "$SCRIPT"
 ```
 
-## 转剧本入库：ingest → view → publish
+详见 [references/state-reference-repair.md](references/state-reference-repair.md)。
 
-有外部素材（剧本文本 / 分镜 / 小说 / 视频）要变成入库剧本时，走这条线。**统一入口是 `ingest`，自动分流文本/视频**。完整细节 + 复杂场景见 [references/ingest-workflow.md](references/ingest-workflow.md)。
+## V3 项目
 
-| 项目状态 | 走 |
-|---|---|
-| 没剧本文本，从零写（题材/灵感/集纲在手） | 直接分配 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` |
-
-三步：
+V3 继续使用现有复合地址，例如：
 
 ```bash
-# 1) 抽取：产出 <workspace>/script.json（不入库）。文本/视频看后缀自动分流。
-#    不传 --workspace-path 就落在 <cwd>/workspace；要放别处就显式传，结果会回显绝对路径。
-scriptctl ingest --source-path uploads/剧本.docx                                  # 文本，默认 <cwd>/workspace
-scriptctl ingest --source-path uploads/正片/ --workspace-path 1_script/workspace  # 视频，显式工作区（需 GEMINI_API_KEY）
-
-# 2) 看进度 / 自查
-scriptctl ingest status                                     # 从工作区真实文件报进度（见下）
-scriptctl view                                              # 生成 review.html（视频版可点击定位）
-scriptctl summary --script-path workspace/script.json      # 抽完后当普通剧本读/改（注意目标是本地文件）
-
-# 3) 入库：校验 v3 通过后写进目标 store
-scriptctl publish --script-path workspace/script.json      # 首次发布或更新受管工作副本
+scriptctl replace ep_001/scn_003#5 --from "旧句" --to "新句"
+scriptctl emotion ep_001/scn_003#5 "低声"
+scriptctl scene-ref ep_001/scn_003 actor:act_001 --state st_002
 ```
 
-- 🔴 **ingest 不入库**——它只产出 `<workspace>/script.json`。**入库是 `publish` 这独立一步**（沙箱里转完必须 publish，否则后端/前端看不到剧本）。
-- 🔴 **workspace 路径**：不传 `--workspace-path` 默认 `<cwd>/workspace`；`ingest` 结果回显绝对路径。后续读写/publish 指向该目录下的 `script.json`。
-- 抽取后用所有本地动词精修，再 publish。若后续继续编辑远端版本，checkout 到本地再改，不直接对 DB 跑原子 op。
-- publish 使用 local-wins：远端 revision 变化时自动以最新 snapshot 为 base 重算 diff，最终远端内容与本地稿一致；不会做三方合并。
+对 V3 文件运行 `export`、`write`、原子命令、`validate` 和 `publish` 时，CLI
+会选择 V3 实现并保持原文件结构与既有 ID。
 
-### `ingest status`：进度按真实文件判定
+## 多点写与 plan
 
-```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。护栏与恢复：
+V4 单个明确 ID 的原子修改直接执行。任何单事务多点修改先生成完整计划：
 
-- **`*_INCOMPLETE`（NORMALIZE / TRANSCRIBE / CORRECT / SPEAKER）= 可续的抖动**：部分单元失败，工作区留下 `passN/*.error.json` sidecar。**直接重跑 `scriptctl ingest`（同 source、同 workspace）即可**——它从 checkpoint 续，只补失败单元，成功的不重跑。跑完 `ingest status` 看还剩几个失败，多跑几次直到收敛。
-- **`INGEST_PIPELINE_MISMATCH` = 工作区的管线版本与当前版本不同**：确认 source 未变化后，使用同一 source、同一 workspace 加 `--force` 完整重建 checkpoint。
-- 🔴 **不要**清工作区、不要删 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）会被拒。
+```bash
+scriptctl replace --in 'acR8cV4n..acT2fG6z' --from "。" --to "！"
+scriptctl replace --in 'acR8cV4n..acT2fG6z' --from "。" --to "！" \
+  --apply --plan sha256:...
 
-## 资产 state 判定（`state-add` / `scene-ref --state` 通用规则）
+scriptctl do edits.txt
+scriptctl do edits.txt --apply --plan sha256:...
 
-只有**持久、可复用、需独立生成视觉资产的外观变体**才进 `states[]`。身份/年龄/职业/情绪/动作/姿态/临时伤病/混合状态**不**算状态，放 description 或 action 文本。
+scriptctl patch changes.json
+scriptctl patch changes.json --apply --plan sha256:...
+```
 
-**默认状态（default）**：每个有 `states[]` 的资产必须有且仅有一个 `state_id: "default"`（最常见常态外观，保留可读 state_name）。`ingest` 会自动把「默认/最常见」那档 canonical 成 `default`；手动 `state-add` 给原先无状态的资产加第一个 state 后，若校验报 `DEFAULT_STATE_MISSING`，把最常见那档的 state_id 设成 `default`。
+V4 `do` / `patch` 内的创建操作必须显式携带候选 ID，确保 dry-run 与 apply
+审阅的是同一批新节点；先用 `ids` 生成候选。
 
-原子 `add-actor / add-location / add-prop` 会自动建立 `default`；少量增补资产时，用 `state-rename` 和 `describe` 定义常态，再将实际 state 绑定到 scene-ref。文件化创作在 `<create>` 中直接声明每个新资产唯一的 `default` state，并在完整 scene 中绑定实际 state。
+计划会完整列出每步/目标、前后计数、精确目标、全量新增/删除/保留身份、未触及
+身份或 sibling、声明、保留的孤立资产和 validation；确认码绑定这份完整计划及
+本地基线。CLI 不保存 plan 文件。当前工作流假设 Agent 从读取到最终写入期间
+没有外部修改。
 
-合并/删除 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`**；完整场、集、整本和连续正文写作走 `.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` 等读写命令**不打模型**。
-- 多态 verb（`delete`/`merge`/`move`/`describe`/`rename`/`insert`/`scene-ref`）按 address 格式分发；flag 用错 kind 会直接报错（不静默忽略）。
-- 新增正文前，`insert <ep/scn>` 要求本场已有地点，并且本场所有地点/人物/道具引用都绑定已物化 state；角色对白/心声的 actor 必须已在本场 cast 中。空镜、环境动作或非角色发声场可以没有人物引用。
-- `actor_name` 在全剧内唯一（Unicode 规范化和大小写折叠后仍不能重复）；别名只放 `aliases[]`。`validate` 会报告历史数据里的重名人物和“说话人不在本场”。
-- 互斥 flag（`scene-ref` 的 --state/--clear/--remove；`dialogue` 的 --actor/--kind；`transition` 的 --process+--contrast/--clear）只能传一个，多传报 `*_FLAG_CONFLICT`。`scene-ref --append` 只与 `--state` 同用；重复 actor 引用用 1-based `--occurrence` 定位。
-- `mock` provider 仅测试，禁止作为交付；provider 失败不降级 mock。
-- 工具失败排查根因，不手工拼装 JSON 绕过校验。
+1. 用 `actions` / `scenes` / `refs` 读回目标。
+2. 运行 `validate`。
+3. 做内容层复核；结构校验通过不代表剧情、对白和画面已达标。
+4. 远端项目最后运行 `publish`。
 
-参数/默认值/退出码以 `scriptctl <cmd> --help` 为准。功能变更用 `scriptctl changelog` 查。
+完整生产写作约束见
+[references/production-writing-standard.md](references/production-writing-standard.md)。

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

@@ -1,60 +1,45 @@
 # 原子精修
 
-适用：对既有剧本做少量、明确、离散的修改。完整场、集、整本和连续正文的创作或替换见 [bulk-authoring.md](bulk-authoring.md)。
+适用于少量、明确、离散的修改。先读取 `script.json.version`，再使用该方言返回的
+正式地址。
 
-## 路由
+## 单点
 
-| 修改形态 | 使用方式 |
-|---|---|
-| 一个明确地址 | 单个原子 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
+scriptctl actions --grep "台下掌声雷动" --script-path "$SCRIPT"
+scriptctl replace acR8cV4n --from "台下掌声雷动" --to "掌声骤停" \
+  --script-path "$SCRIPT"
 ```
 
-资产、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
-```
+V4 查询可以使用 1-based `@` 序号，但修改必须使用正式 ID。V3 查询返回原有的
+`ep_NNN/scn_NNN#idx` 可写地址。
 
-## 同构批量精修
+## 同构多点
 
-查询和写入共用选择条件。多点写默认只生成计划，加 `--apply` 才落盘：
+V4 先运行 dry-run，读取完整目标和 `plan_digest`，再用相同命令 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
+scriptctl replace --in 'acR8cV4n..acT2fG6z' --from "。" --to "！"
+scriptctl replace --in 'acR8cV4n..acT2fG6z' --from "。" --to "！" \
+  --apply --plan sha256:...
 ```
 
-## 少量异构精修
+## 异构多点
 
-`do` 文件每行是一条去掉 `scriptctl` 的原子命令。先 dry-run，再原子应用：
+把不同原子命令写入文件，每行省略 `scriptctl`：
 
 ```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
+replace acR8cV4n --from "旧句" --to "新句"
+parenthetical acT2fG6z --set "低声"
+scene-ref scnK6wT3c actA3kP9x --state default --state stB4xR8p
 ```
 
 ```bash
-scriptctl do fixes.txt --script-path workspace/script.json
-scriptctl do fixes.txt --apply --script-path workspace/script.json
+scriptctl do edits.txt --script-path "$SCRIPT"
+scriptctl do edits.txt --apply --plan sha256:... --script-path "$SCRIPT"
 ```
 
-精修后读回受影响的 scenes/actions，并运行 `validate`。
+`do` 整体解析、修改和校验；任一行失败时不落盘。
+V4 `do` 中新增 asset、state、episode、scene 或 Action 时显式填写候选 ID。