@lingjingai/scriptctl 0.60.13 → 0.61.1

package/skills/scriptctl/SKILL.md

@@ -1,287 +1,230 @@
 ---
 name: scriptctl
-description: "剧本 script.json 的本地查询、无 ID 可读创作稿编译、文件化批量写作、原子精修、素材 ingest 与 revision publish CLI。处理 Script v3/v4、两个 script.json、剧本资产/state、Action、场景引用或 authoring 时使用。"
+description: "剧本 script.json 的本地阅读、定位、原子修改、整场整集回写、素材 ingest 与 revision publish CLI。处理 Script v3/v4、剧本资产与 state、Action、场景引用或视频证据核对时使用。"
 metadata:
-  version: "0.29.4"
-  scriptctl_version: "0.60.13"
+  version: "0.31.0"
+  scriptctl_version: "0.61.1"
   author: "official"
 ---
 
 # scriptctl
 
-`scriptctl` 始终对 `-p` 指向的本地 `script.json` 工作。远端剧本先
-`checkout`，完成本地查询、修改和 `validate` 后再 `publish`。
+`scriptctl` 始终对 `-p` 指向的本地 `script.json` 工作。远端剧本先 `checkout`，
+完成本地阅读、修改和 `validate` 后再 `publish`。
 
-实际调用和示例优先使用短参数：`-p/-w/-s/-o/-i/-g/-t/-a/-k/-n/-h/-v`。
-没有短名的参数保持完整长写。
+Agent 直接运行命令并阅读结果就是正常用法，默认文本输出即为给人和给 agent 看的形态。
 
-## 输出模式
+## 地址
 
-Agent 直接运行命令并阅读结果属于正常使用，使用默认文本输出；查询表格默认为 TSV。
-定位、查看正文、核对时间范围、读回修改和运行校验都使用默认输出。只有命令 stdout
-将由脚本、程序、测试或前端按字段消费时，才使用 `-j` JSON 输出。
+**一个字符串，读写通用**：
 
-## 先识别版本
+| 形式 | 例 | 指向 |
+|---|---|---|
+| 序号（1-based） | `3` / `3-2` / `3-2-5` | 第 3 集 / 第 3 集第 2 场 / 该场第 5 条 action |
+| 正式 ID | `acB4xR8p` `scnQ7mN2v` `actA3kP9x` | 对应节点 |
+| 资产名或别名 | `向北` `林教练` | 那个 actor / location / prop |
+| 状态 | `向北/23号球衣` `actQYEeTr/default` | 该资产的一个造型状态 |
+| 空 | （不传） | 剧本根 |
 
-读取 `script.json.version`：
+歧义会报错并列出候选，不做猜测。**查询返回的锚点可以原样用于修改**，没有单独的
+"可写地址"概念。v3 与 v4 用同一套语法——v3 没有 action ID，锚点退化成序号。
 
-- Script v4：新建和 ingest 的默认方言。episode、scene、Action、asset 使用带类型前缀的短随机 ID；修改只用正式 ID。
-- Script v3：线上既有项目的冻结方言。查询、修改、authoring 和 publish 继续使用 v3 地址与字段。
-
-不要根据字段形状猜版本。命令会按显式 `version` 自动分流。
-
-## 标准剧本通用流程
-
-1. **忠实理解输入**：创作时落实题材、集纲和人物关系；提取与解析时保留源素材可验证的对白、动作、顺序、场界和状态变化。把不确定信息标为待复核，不补写源素材未表达的事实。
-2. **注册资产**：先读现有人物、地点、道具；正文将出现的资产必须先注册。普通 Agent/LLM 创作用 `compose` 可读草稿的 `assets` 声明，CLI 自动生成 ID 和引用；高级批量 authoring 才使用 `<create>`。人物保留一个稳定的 `actor_name` 作为真名，称呼、绰号、职位放 `aliases[]`，同一人物共用一个 actor。
-3. **建好资产状态**：每个新资产必须有唯一的 `default` state ID；它是底层基础状态键，不是用户可见造型名。`state_name` 与普通创作的 variant 名写实际可辨认外观，如“深灰通勤装”“夜班白大褂”。新资产声明的第一项 variant 是基础状态。持久、可复用、需要独立生成视觉资产的服装/造型差异才建立独立 state。人物 `description` 只写稳定身份形态，每个 variant 的 `description` 独立写成从头到脚可复现的完整造型。引用尚未登记的 variant 时，即使人物已经存在，也在本场草稿 `assets.actors` 中声明该人物与新 variant。
-4. **建立真实场并绑定资产**：完整 scene 显式声明本场 `environment.time`，取 `day`、`night`、`dawn`、`dusk` 之一，并声明地点、全部人物、全部道具及其实际 state。V4 同一资产只出现一条场景引用，通常只绑定本场实际造型；只有本场正文明确发生持久外观变化时才同时绑定多个状态，并在 Action 中写清变化。V3 按其既有单状态引用结构处理。
-5. **写入或标准化正文**：Agent/LLM 从零创作和续写优先输出无 ID 的可读 JSON，再执行 `compose` plan/apply；CLI 负责 ID、资产、引用、时间戳和相邻同场合并。`.scriptctl` authoring 保留给确定性程序、高级人工批量事务、旧流程兼容和迁移；已有目标的大块结构化替换仍可先 `export` 再 `write`。
-6. **逐场复核**：每批正文落盘后读回 `scenes / actions`；一集完成后运行 `validate`。`validate` 通过只代表结构与引用合法，仍需完成内容标准和源素材一致性复核。
-
-## 四条工作流
-
-1. 素材转剧本：`ingest` → 内容复核 → `view` / `validate` → `publish`。见
-   [references/ingest-workflow.md](references/ingest-workflow.md)。
-2. 普通创作或续写：可读场景 JSON → `compose` plan → `compose --apply --plan` → 读回。模型不接触 ID、精确时间戳或 `.scriptctl`。
-3. 高级完整块创作或替换：`ids` → `export` 或新写 `.scriptctl` → `write` plan →
-   `write --apply --plan <digest>`。见
-   [references/bulk-authoring.md](references/bulk-authoring.md)。
-4. 少量精修：查询定位 → 单 ID 原子 verb；同构多点用 selector；异构多点用
-   `do`。见 [references/atomic-edit-workflow.md](references/atomic-edit-workflow.md)。
-
-## 无 ID 可读创作稿
-
-模型只写一场的可读内容，本地 CLI 将它编译进明确的 Script v4：
+## 读
 
 ```bash
-scriptctl compose /tmp/scene-draft.json -p "$SCRIPT" -j
-scriptctl compose /tmp/scene-draft.json -p "$SCRIPT" --apply --plan '<plan_digest>' -j
-scriptctl actions -i '@ep:1' -p "$SCRIPT"
+scriptctl scan 3 -p "$S"            # 一次拿全：本集场结构 + 全部正文 + 校验问题
+scriptctl read -p "$S"              # 剧本卡：题材 + 全部资产 + 每集一行
+scriptctl read 3 -p "$S"            # 整集正文
+scriptctl read 3 --outline -p "$S"  # 只要场头
+scriptctl read 3-1 -p "$S"          # 单场正文
+scriptctl read acCNFfN1 --context 3 -p "$S"    # 单条 + 上下文
+scriptctl read 向北 -p "$S"          # 人物卡：描述 + 全部状态 + 出场统计 + 未使用状态
+scriptctl read 向北/default -p "$S"  # 状态卡：绑在哪些场、被多少 speaker 引用
 ```
 
-草稿顶层为 `version: 1`，并含 `episode`、`scene` 与可选 `assets`。`scene` 使用可读地点、人物、道具和造型名；Action 只写 `type`、`content`、可选 `speaker` / `speakerVariant` / `parenthetical`，以及 `durationMs` 或 1–5 的 `weight`。人物对白未写 `speakerVariant` 时沿用该人物的本场造型；只有对白发生在本场另一项已声明造型时才写 `speakerVariant`。`assets` 既可登记新资产，也可为已有资产声明本场首次使用的新 variant。相邻地点、内外景和日夜相同时默认并入上一场；地点 state 变化不单独切场。只有确需新场时设置 `scene.boundary: "new"`。
-
-人物声音归属于人物：角色自述或画外叙述写人物名为 `speaker`，在 `parenthetical` 写 `V.O.`、声音状态或来源；角色内心语言用 `inner_thought` 并写人物名。`speaker: "旁白"` 只表示没有角色身份的客观叙述者；已知人物在电话、门外、回忆或画外说话仍使用该人物名。
-
-`compose` 只支持 Script v4，使用确定性 ID 和 plan digest，正式写入前必须审核当前计划。模型不得把 `compose` 的内部输出字段抄回创作稿。
-
-## 本地文件边界
+**一个 `read` 覆盖全部阅读，粒度由地址决定。** 开始审一集时先 `scan`，它把上下文
+建立从多次调用压成一次。
 
-- 普通命令默认读取 `<cwd>/workspace/script.json`；操作其他文件时始终显式传
-  `-p <file>`。
-- `-w` 只属于 `ingest` 命令族和 `view`。
-- 视频 ingest 还会在 workspace 的 `evidence/` 下写原片证据 sidecar 与抽帧；这些是
-  可重建的来源证据，不属于 `script.json`，不要作为剧本语义字段写回。
-- 已有带时间戳的 Script v4 也可在关联原视频后运行
-  `scriptctl evidence -p <script.json> -s <视频目录> -w <workspace>`。它只根据最终
-  Action 时间戳和人物/状态引用选择锚点并用本地 ffmpeg 抽帧，不调用模型、不重跑 ingest；
-  `--force` 会重抽已有的确定性图片路径。
-- 同时处理原剧与目标剧时，每条命令都显式带对应 `-p`，只从原剧读，
-  只向目标剧写。
-- `checkout` 不覆盖未管理文件或本地修改；`publish` 按工作副本 revision 严格写入。
+正文格式（`read` 输出、`write` 接受的**同一种**）：
 
-## 查询与定位
-
-默认文本查询输出 TSV。脚本消费查询结果时使用 `-j`：顶层固定包含
-`ok`、`exit_code`，表格数据位于 `rows`，列顺序位于 `row_columns`。地址流使用
-`--format addr`。写命令的 JSON 使用 `op`、`changed`、`plan_digest`、
-`validation`、`script_path` 等命令自身字段，不包含展示用的标题或结果区块。
-JSON 错误包含 `error_code`、`message` 和可选 `hint`。
+```text
+## 3-1  scnMMEb8A  EXTERIOR/DAY  学校球场  34 actions
+#  cast: 李壮, 王志, 向北  props: 篮球
+acMjTL1a  00:00 中景，仰拍。李壮满脸不可置信地张大嘴巴。
+acKoaixN  00:00 李壮(目瞪口呆地惊呼)：我去！
+acR8cV4n  → 三天后。
+```
 
-查询用于定位和读回，不以整份文档的语义校验结果作为前置条件。文档存在引用、
-状态或身份校验问题时，继续查询仍可寻址的数据；用 `issues` / `validate` 单独查看
-全局校验结果。
+- 左槽是锚点（v4 是稳定 `action_id`，v3 是序号）。
+- `名字(提示)：` 是对白；提示首段为 `心声` 表示 inner_thought；`→` 开头是转场。
+- **存在的字段一定显示**：speaker 状态写成 `名字·状态`，时间戳紧跟锚点。
+- 人物显示名取全局唯一的最短别名（`雷文娜指挥官` → `雷文娜`），别名回写时可解析。
+- `--plain` 去掉锚点与时间戳，**只读**：它的输出回写会被拒绝。
 
-常用查询：
+## 定位
 
 ```bash
-scriptctl summary -p "$SCRIPT"
-scriptctl episodes -p "$SCRIPT"
-scriptctl scenes -i '@ep:3' -p "$SCRIPT"
-scriptctl actions -g "台下掌声" -p "$SCRIPT"
-scriptctl actions -i '@ep:1' --time '00:30..00:45' -p "$SCRIPT"
-scriptctl actions -i 'acR8cV4n..acT2fG6z' --span -p "$SCRIPT"
-scriptctl actors --counts -p "$SCRIPT"
-scriptctl states actA3kP9x -p "$SCRIPT"
-scriptctl refs actA3kP9x/stB4xR8p -p "$SCRIPT"
-scriptctl validate -p "$SCRIPT"
+scriptctl find '真能蒙' -p "$S"                       # 按正文正则
+scriptctl find '' -a 向北 -t inner_thought -p "$S"     # 按说话人 + 类型
+scriptctl find '球' -i 3 -t dialogue -p "$S"           # 限定范围
+scriptctl span 3-1 -p "$S"                            # 换算成集内视频时间窗口
+scriptctl issues --severity error -p "$S"
+scriptctl validate -p "$S"
 ```
 
-序号锚点是 1-based 查询语法：
-
-- `@ep:3`
-- `@ep:3/scn:2`
-- `@ep:3/scn:2/ac:5`
-- `@scn:12`
-- `@ac:48`
+`find` 返回锚点 + 位置 + 命中窗口而不是整条，命中多时不炸上下文。
+`span` 给出半开区间（`start_timestamp` / `end_timestamp` / `end_open`）供视频核对使用。
 
-区间包含两端，端点正反等价，按当前文档顺序解释。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 -i '@ep:7'` |
-| 看某场的资产 + action 数 | `scriptctl scenes -i '@ep:7/scn:5'` |
-| **按正文搜某句话定位 action**（最常用） | `scriptctl actions -g "<片段>"` |
-| 列某集所有 action（含 timestamp / speaker / 正文 /表演提示） | `scriptctl actions -i '@ep:1'` |
-| 看单条 action 正文 | `scriptctl actions -i '@ep:1/scn:1/ac:3'` |
-| 按集内时间点或闭区间看正文 | `scriptctl actions -i '@ep:1' --time '00:30..00:45'` |
-| 把 Action / scene 范围换成可供视频处理的时间戳包络 | `scriptctl actions -i '<action-or-scene-range>' --span` |
-| action 多维过滤 | `scriptctl actions -i '@ep:1' -t dialogue -a <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` |
-| 某资产 / 状态反查 | `scriptctl refs <asset-id>` / `scriptctl refs <asset-id>/<state-id>` |
-| 当前校验问题 / 跑校验 | `scriptctl issues --severity error` / `scriptctl validate` |
-
-### Action 范围的时间戳包络
-
-需要按 Action、scene 或其他 action selector 获取对应视频时段时，使用 `actions --span`：
+单条命令直接生效。**没有 plan、没有确认码、没有两阶段提交**。
 
 ```bash
-scriptctl actions -i 'acR8cV4n..acT2fG6z' --span -p "$SCRIPT"
-scriptctl actions -i '@ep:3/scn:2' --span -p "$SCRIPT"
+scriptctl edit acCNFfN1 --content "新台词" --paren "低声" -p "$S"
+scriptctl edit acCNFfN1 --speaker 李壮 -p "$S"        # 按人物名，不用先查 ID
+scriptctl edit acCNFfN1 --no-paren -p "$S"            # 删字段（--paren "" 是设空串）
+scriptctl edit acCNFfN1 --ts 00:41 -p "$S"
+scriptctl edit 3-1 --space interior --time night -p "$S"    # 场的内外景 / 日夜
+scriptctl edit 3 --title "第三集" --synopsis "…" -p "$S"     # 集元数据
+scriptctl edit "" --logline "…" --theme "…" -p "$S"          # 剧本元数据（地址留空）
+scriptctl edit 向北 --role 主角 --alias 小北,7号 -p "$S"      # 资产
+scriptctl edit 向北/default --name 主场球衣 -p "$S"           # 状态
 ```
 
-结果只含一行，并给出 `episode_id`、`ep_no`、`start_timestamp`、
-`last_selected_timestamp`、`end_timestamp`、`end_open`、起止 Action 地址和
-`end_boundary_action`。区间按文档顺序解释：
-
-- `start_timestamp` 是第一个命中 Action 的时间戳。
-- `last_selected_timestamp` 是最后一个命中 Action 自身的时间戳；该 Action
-  没有时间戳时为空。
-- `end_timestamp` 是最后一个命中 Action 之后第一个更晚的时间戳，作为半开区间
-  的排他终点；`end_exclusive` 固定为 `true`。
-- 选区到达本集末尾且没有后续时间锚点时，`end_timestamp` 为空且
-  `end_open=true`，由消费方使用源视频总时长收口。
-
-一个 span 必须位于同一集，且第一个命中 Action 必须有合法时间戳。跨集、无命中、
-起点时间戳缺失或时间戳倒退会返回明确错误；按集拆分或修正时间戳后重试。
+`edit` 按地址分派，**地址决定哪些字段合法**：
 
-## Script v4 写入（v3 同样使用写后校验）
+| 地址 | 可改字段 |
+|---|---|
+| action | `--content` `--paren` `--speaker` `--ts` `--type` `--transition` |
+| 场 | `--space` `--time` |
+| 集 | `--title` `--synopsis` |
+| 剧本（空地址） | `--title` `--worldview` `--style` `--synopsis` `--logline` `--theme` `--main` |
+| 资产 | `--name` `--desc` `--importance` `--alias` `--role` |
+| 状态 | `--name` `--desc` |
 
-V4 新 ID 是类型前缀加 6 位 Bitcoin Base58：
+字段用错会报清这类节点收哪些字段。闭集值（`type` / `importance` / `role` /
+`space` / `time`）在写入前就校验，不等 `validate`。
 
-```text
-ep……  scn……  ac……  act……  loc……  prp……  st……
-```
-
-`ids` 只生成候选，不预留：
+**⚠️ `--content` 是整条覆写**：传入的字符串成为这条 action 的全部内容，原文丢弃。
+只改其中一个词或一段，用 `replace`。
 
 ```bash
-scriptctl ids -k action --count 4
-scriptctl ids -k scene --count 2 -p "$SCRIPT"
+scriptctl replace '林京南队教练' '林教练' -i 5 -p "$S"        # 默认只预览逐行 diff
+scriptctl replace '林京南队教练' '林教练' --apply -p "$S"      # 才真的写
+scriptctl replace '真能蒙' '真敢投' -a 王志 -t dialogue --apply -p "$S"
 ```
 
-单点修改使用正式 ID：
+过滤参数与 `find` 相同（`-i` / `-a` / `-t`），不用学第二套 selector。
+
+结构与资产：
 
 ```bash
-scriptctl replace acR8cV4n --from "旧句" --to "新句" -p "$SCRIPT"
-scriptctl parenthetical acT2fG6z --set "低声" -p "$SCRIPT"
-scriptctl parenthetical acT2fG6z --set "" -p "$SCRIPT"
-scriptctl parenthetical acT2fG6z --remove -p "$SCRIPT"
-scriptctl timestamp acT2fG6z --set 00:42.533 -p "$SCRIPT"
-scriptctl timestamp acT2fG6z --remove -p "$SCRIPT"
-scriptctl dialogue acT2fG6z -a actA3kP9x --state stB4xR8p -p "$SCRIPT"
-```
+scriptctl insert acCNFfN1 "他关上门。" -t action -p "$S"
+scriptctl insert acCNFfN1 "都回位置！" -t dialogue -a 白教练 --paren 皱眉 --before -p "$S"
+scriptctl move acD4eF6g acR8cV4n --before -p "$S"     # 跨场也保持 action_id
 
-原子 verb 只在目标、参数或操作本身无法安全执行时失败。操作成功写入后退出 `0`；
-`validation.passed=false` 表示文档仍需收口，不表示本次写入失败。`warnings` 只列本次
-新引入的校验问题；存在 `repair_hint` 时直接执行其中的修复命令，再读回目标。
+scriptctl ref 3-1 向北 --state 23号球衣 -p "$S"        # 完整状态集合，不是追加
+scriptctl ref 3-1 毛巾 --remove -p "$S"
 
-`parenthetical` 只属于 dialogue / inner_thought。字段省略表示没有表演提示；显式
-空字符串与省略不同。影响走位、道具或连续性的动作写成独立 Action。
+scriptctl asset actor 苏晓 --desc "…" --alias 晓姐,经理 -p "$S"
+scriptctl state 向北 受伤 --desc "…" -p "$S"
 
-V4 placement 使用父节点与相邻节点 ID：
+scriptctl del acCNFfN1 -p "$S"
+scriptctl del 向北/旧造型 --replacement 23号球衣 -p "$S"   # 删状态并改写引用
+scriptctl del 3-1 --force -p "$S"                        # 有内容的容器要 --force
+scriptctl merge 李壮 王志 -p "$S"                         # 合并重复资产
 
-```bash
-scriptctl insert scnK6wT3c --action-id acD4eF6g \
-  -t action --content "陈默关上门。" --before acT2fG6z
-scriptctl move acD4eF6g scnH7jK9m --after acR8cV4n
-scriptctl split scnK6wT3c --at acT2fG6z --new-scene-id scnD4eF6g
+scriptctl ext acCNFfN1 note "分镜待定" -p "$S"            # 任意节点的 extend
 ```
 
-## 场景资产与状态
+**每次修改都会报出它新引入的校验问题**（文档本来就有的不重复刷）。看到
+`introduced N issue(s)` 就按提示收口；带 `fix:` 的直接照做。
 
-V4 一个场景内同一资产只引用一次；引用携带完整、非空的 `state_ids` 集合。重复
-`--state` 传入整个集合，写入时按 state ID 排序：
+引用相关的两条硬规则：
 
-```bash
-scriptctl scene-ref scnK6wT3c actA3kP9x \
-  --state default --state stB4xR8p -p "$SCRIPT"
-scriptctl scene-ref scnK6wT3c actA3kP9x --remove -p "$SCRIPT"
-```
+- `ref --state` 是**完整集合**而非追加，`default` 也要显式写。
+- 删不存在的引用、删地点时 ID 对不上、空状态集合都报错，不当幂等成功。
 
-通过最终校验时，actor speaker 必须被当前 scene 引用；可选的 speaker state 必须属于
-该 actor 在当前 scene 的 `state_ids`。可以先修改 speaker，再根据写入结果中的
-`repair_hint` 补齐 scene 引用。状态集合不表示对白级落点，也没有先后顺序。
+## 整场 / 整集回写
 
-state 修改前后都反查并校验：
+`read` 的输出就是 `write` 的输入：
 
 ```bash
-scriptctl refs actA3kP9x/stB4xR8p -p "$SCRIPT"
-scriptctl state-delete actA3kP9x/stB4xR8p \
-  --strategy replace --replacement default -p "$SCRIPT"
-scriptctl validate -p "$SCRIPT"
+scriptctl read 3 -p "$S" > /tmp/ep3.txt      # 改这个文件
+scriptctl write 3 -f /tmp/ep3.txt -p "$S"
+scriptctl write + -f /tmp/ep51.txt -p "$S"   # `+` 追加新集
 ```
 
-详见 [references/state-reference-repair.md](references/state-reference-repair.md)。
-
-## V3 项目
+**按锚点做差**：带锚点的行保留身份并编辑，无锚点的行新建，**文本里消失的锚点 = 删除**。
+这是唯一一条看输出看不出来、猜错了会误删的规则。
 
-V3 继续使用现有复合地址，例如：
+- 整集回写时 `##` 场头带 scene id 表示保留该场，不带表示新建整场。
+- action 可以在本集内跨场移动——这就是拆场与并场，不需要额外动词。
+- 删整场、删光一场的 action、或整集少写几行，都需要 `--allow-delete`。
+- 场头本身就是完整的场声明（环境 / 地点 / cast / 道具及其状态），所以整集回写不
+  需要第二种语法。
 
-```bash
-scriptctl replace ep_001/scn_003#5 --from "旧句" --to "新句"
-scriptctl emotion ep_001/scn_003#5 "低声"
-scriptctl timestamp ep_001/scn_003#5 --set 00:42
-scriptctl scene-ref ep_001/scn_003 actor:act_001 --state st_002
-```
-
-对 V3 文件运行 `export`、`write`、原子命令、`validate` 和 `publish` 时，CLI
-会选择 V3 实现并保持原文件结构与既有 ID。
+批量改词用 `replace`，大块结构改用 `write`，**不要逐条 `edit` 硬凑**。
 
-## 版本变更边界
+## 本地文件边界
 
-Agent 不得自行调用 `migrate` 命令，也不得执行任何 Script schema 升级或生成升级产物。
-版本变更会重写全局身份与外部引用，可能影响项目上下文、视频锚点和下游工作流；只有用户
-明确要求时才由应用层处理。面对 V3 文件，按其现有版本读取、查询、修改和校验。
+- 普通命令默认读取 `<cwd>/workspace/script.json`；操作其他文件时始终显式传 `-p <file>`。
+- `-w` 只属于 `ingest` 命令族和 `view`。
+- 视频 ingest 会在 workspace 的 `evidence/` 下写原片证据 sidecar 与抽帧；这些是可
+  重建的来源证据，不属于 `script.json`，不要作为剧本语义字段写回。
+- 已有带时间戳的 Script v4 可在关联原视频后运行
+  `scriptctl evidence -p <script.json> -s <视频目录> -w <workspace>`。它只根据 Action
+  时间戳和人物/状态引用选锚点并用本地 ffmpeg 抽帧，不调模型、不重跑 ingest。
+- 同时处理原剧与目标剧时，每条命令都显式带对应 `-p`，只从原剧读、只向目标剧写。
+- `checkout` 不覆盖未管理文件或本地修改；`publish` 按工作副本 revision 严格写入。
 
-## 多点写与 plan
+## 流水线命令
 
-V4 单个明确 ID 的原子修改直接执行。任何单事务多点修改先生成完整计划：
+这些不是逐条修改的工具，是整段流程：
 
 ```bash
-scriptctl replace -i 'acR8cV4n..acT2fG6z' --from "。" --to "！"
-scriptctl replace -i 'acR8cV4n..acT2fG6z' --from "。" --to "！" \
-  --apply --plan sha256:...
+scriptctl ingest -s <素材> -w <workspace>     # 素材转 Script v4
+scriptctl synopsis generate -p "$S" --apply   # LLM 补全剧与分集梗概
+scriptctl audit-assets -p "$S"                # LLM 全剧资产一致性审计
+scriptctl review -p "$S" -s <视频目录>         # 派发 agent 逐集审核并修正
+scriptctl create --title "…" -p "$S"          # 从零建空剧本
+scriptctl view -w <workspace>                 # 渲染或起审阅页
+scriptctl checkout / status / publish         # 远端工作副本
+```
 
-scriptctl do edits.txt
-scriptctl do edits.txt --apply --plan sha256:...
+`ingest` 见 [references/ingest-workflow.md](references/ingest-workflow.md)。
 
-scriptctl patch changes.json
-scriptctl patch changes.json --apply --plan sha256:...
-```
+`review` 一个进程审完整本剧：剧本只解析一次进内存，按集扇出，最后单线程做全剧收敛。
+给 `-s` 就按原视频拉片核对（agent 自己切片段送模型看画面和听原声），不给就纯剧本审核，
+媒体工具不注册。每集完成一行 NDJSON 到 stdout（`{"type":"episode",…}`，末行
+`{"type":"done",…}`），所以调用方可以边跑边落盘，中途挂掉不丢已完成的集。
+`--episodes 3,7` 续跑指定集，`--concurrency` 控同时在飞的集数，`--check` 只验模型与
+agent 是否就绪。**Agent 不要自己调 `review` 去审自己正在改的剧本**——它会派发另一个
+agent 并直接改文件。
 
-V4 `do` / `patch` 内的创建操作必须显式携带候选 ID，确保 dry-run 与 apply
-审阅的是同一批新节点；先用 `ids` 生成候选。
+## 版本边界
 
-计划会完整列出每步/目标、前后计数、精确目标、全量新增/删除/保留身份、未触及
-身份或 sibling、声明、保留的孤立资产和 validation；确认码绑定这份完整计划及
-本地基线。CLI 不保存 plan 文件。当前工作流假设 Agent 从读取到最终写入期间
-没有外部修改。
+读取 `script.json.version`：`4` 是新建与 ingest 的默认方言，`3` 是线上既有项目的
+冻结方言。**不要根据字段形状猜版本**，命令按显式 `version` 自动分流：v3 写
+`emotion`、v4 写 `parenthetical`，同一条 `edit --paren` 在两边都对。
+
+**Agent 不得自行调用 `migrate`**，也不得执行任何 schema 升级。版本变更会重写全局
+身份与外部引用，只有用户明确要求时才由应用层处理。
 
 ## 完成标准
 
 每批修改后：
 
-1. 用 `actions` / `scenes` / `refs` 读回目标。
-2. 运行 `validate`。
-3. 做内容层复核；结构校验通过不代表剧情、对白和画面已达标。
-4. 远端项目最后运行 `publish`。
+1. 用 `read` 读回目标。
+2. 跑 `scriptctl validate`。
+3. 做内容层复核——结构校验通过不代表剧情、对白和画面已达标。
+4. 远端项目最后 `publish`。
+
+**零修改是合格结果。** 没发现问题就如实报告，不要为了交差制造修改。
 
-完整生产写作约束见
-[references/production-writing-standard.md](references/production-writing-standard.md)。
+内容标准见
+[references/production-writing-standard.md](references/production-writing-standard.md)；
+视频转录剧本的复核见
+[references/video-transcript-repair.md](references/video-transcript-repair.md)；
+state 引用修复见
+[references/state-reference-repair.md](references/state-reference-repair.md)。

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

@@ -134,7 +134,7 @@ scriptctl ingest status          # 人读：kind / state / 各 pass 进度（tra
 scriptctl ingest status -j       # 机器输出含 failure_summary / errors[]；视频另含 completed / parsed / skipped / skipped_episodes / complete / next_episode
 scriptctl view                   # 生成 workspace/review.html（视频版可点击定位到画面）
 scriptctl view --watch [--port N]# 实时监听面板：分阶段进度条 + 逐集 context/决策 + 产物树，自动刷新（跑中也能开）。🔴 仅本地用，**沙箱内不要用**（起阻塞服务+开浏览器，会挂住；沙箱看进度用 `ingest status`）
-scriptctl summary -p workspace/script.json   # 抽完当普通剧本读
+scriptctl read -p workspace/script.json   # 抽完当普通剧本读
 ```
 
 `state`：`empty`（没开始）/ `incomplete`（在跑、中断或只完成连续前缀）/ `failed`（有失败单元或校验没过）/ `ready`（全部 source units 完成，且 `script.json` 的 v4 结构校验通过）。文本与视频 ingest 的 `validation.json` 包含结构校验和 production warning。进度从工作区真实文件推导；它报的是管线事实，资产合并结论和源素材一致性仍由复核完成门确认。

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

@@ -1,38 +1,42 @@
 # State 引用修复
 
-先反查旧 state：
+删一个仍被引用的 state，必须先决定那些引用去哪里。
+
+## 先看它被谁引用
 
 ```bash
-scriptctl refs actA3kP9x/stB4xR8p -p "$SCRIPT"
+scriptctl read 向北/23号球衣 -p "$S"
 ```
 
-## Script v4
+状态卡直接给出：绑在哪些场、被多少 speaker 引用。资产卡（`read 向北`）还会列出
+**从没用过的 state**——那些可以直接删。
 
-场景引用保存完整、非空的 `state_ids` 集合。替换 state 会在场景集合与 actor
-speaker 上同步替换：
+## 删并改写
 
 ```bash
-scriptctl state-delete actA3kP9x/stB4xR8p \
-  --strategy replace --replacement default -p "$SCRIPT"
+scriptctl del 向北/旧造型 --replacement 23号球衣 -p "$S"
 ```
 
-`--strategy remove` 会从每个集合移除该 state；若任何集合将变为空，命令拒绝，
-应先为该场写入另一个完整状态集合。speaker 上的可选 state 被移除后可省略，由
-下游依据场景集合判断具体对白落点。
+场景集合与 actor speaker 上的引用会同步改写到 `--replacement`。不给
+`--replacement` 时，命令会拒绝并告诉你有多少处引用；要强行剥掉引用才用 `--force`。
 
-## Script v3
+`default` 是资产的基础状态键，不允许单独删除——要删整个资产用 `del 向北`（同样
+需要 `--replacement` 或 `--force`）。
 
-使用 V3 state 地址和既有单值引用语义：
+## v4 与 v3 的差别
 
-```bash
-scriptctl state-delete actor:act_001/st_002 \
-  --strategy replace --replacement st_001 -p "$SCRIPT"
-```
+v4 的场景引用是**完整非空的 `state_ids` 集合**：改写后集合仍需非空，所以
+`--replacement` 指向的 state 必须存在。v3 是单值 `state_id`，改写即替换。
+
+同一条命令在两个方言上都对——`del` 按 `script.json.version` 自动分流，不要为 v3
+另写地址形式。
 
 ## 核验
 
 ```bash
-scriptctl refs <旧-state-address> -p "$SCRIPT"
-scriptctl refs <新-state-address> -p "$SCRIPT"
-scriptctl validate -p "$SCRIPT"
+scriptctl read 向北 -p "$S"          # 状态列表与使用分布
+scriptctl read 3-1 -p "$S"           # 场头里的 cast 与状态
+scriptctl validate -p "$S"
 ```
+
+`del` 本身会报出它新引入的校验问题；`introduced 0 issue(s)`（无此行）才算收口。

package/skills/scriptctl/references/video-transcript-repair.md

@@ -11,14 +11,14 @@
 scriptctl validate -p "$V3"
 ```
 
-V3 保持其现有地址与字段；V4 使用其正式 ID 与计划写入语义。Agent 只在用户指定的
-现有版本内进行复核和精修，不改变 Script schema。任一版本有多个 blocking issue 时，
-把完整修复组织成一个 `do` 或 `patch` 事务；计划的最终状态通过校验后再 apply。
+V3 保持其现有地址与字段；V4 使用其正式 ID。Agent 只在用户指定的现有版本内进行复核和
+精修，不改变 Script schema。每条修改命令都会报出它新引入的校验问题，看到
+`introduced N issue(s)` 就当场收口，不要攒到最后。
 
 人物重名按剧情身份判断：
 
 - 同一人物被重复建档：先核对 `refs`、states、aliases、importance 和实际对白，再把信息
-  补到保留人物，最后 `merge <source> --into <survivor>`。
+  补到保留人物，最后 `merge <被并> <保留>`。
 - 不同人物共用外观标签：把各自 `actor_name` 改为真实稳定身份，外观或称呼放 aliases。
 - 人物名改成已有 alias 后，同步移除与正式名相同的 alias。
 
@@ -32,38 +32,37 @@ V3 保持其现有地址与字段；V4 使用其正式 ID 与计划写入语义
 同一场中多个同时发生的 Action 可以使用相同时间戳；后面的 Action 不能早于前一个有时间戳的 Action。
 
 ```bash
-scriptctl actions -i '@ep:4' -p "$SCRIPT"
-scriptctl actions -g "台词片段" -p "$SCRIPT"
-scriptctl timestamp <action-id> --set 00:42.533 -p "$SCRIPT"
+scriptctl read 4 -p "$SCRIPT"                    # 整集正文，时间戳就在锚点后面
+scriptctl find '台词片段' -p "$SCRIPT"            # 按正文定位到锚点
+scriptctl edit <action> --ts 00:42.533 -p "$SCRIPT"
+scriptctl span 4-1 -p "$SCRIPT"                  # 该场对应的视频时间窗口
 ```
 
 校时使用视频中该动作或对白真正开始的画面。保留亚秒级精度。没有视频证据时保留待复核，
-不根据相邻行平均分配。
+不根据相邻行平均分配。改完时间戳若造成倒序，`edit` 会当场报出
+`timestamp_out_of_order`，不用等 `validate`。
 
 ## 3. 补漏 Action 或对白
 
-先取得相邻 Action、场景和说话人的正式 ID，再生成一个 Action ID：
+`insert` 一步完成，Action ID 由 CLI 生成，不需要先取候选 ID：
 
 ```bash
-scriptctl ids -k action --count 1 -p "$SCRIPT"
+scriptctl insert <相邻action> "她推门进屋。" -t action -p "$SCRIPT"
+scriptctl insert <相邻action> "我回来了。" -t dialogue -a 向北 -p "$SCRIPT"
 ```
 
-把插入和时间戳写在同一个 `do` 事务中。动作示例：
+默认插在目标之后，`--before` 插在之前；说话人用**人物名**即可，不必查 actor ID，
+需要指定造型时写 `名字·状态`。补完时间戳：
 
-```text
-insert <scene-id> --action-id <new-action-id> -t action --content "她推门进屋。" --after <previous-action-id>
-timestamp <new-action-id> --set 00:42.533
+```bash
+scriptctl edit <新action> --ts 00:42.533 -p "$SCRIPT"
 ```
 
-对白示例：
-
-```text
-insert <scene-id> --action-id <new-action-id> -t dialogue --content "我回来了。" -a <actor-id> --after <previous-action-id>
-timestamp <new-action-id> --set 00:42.533
-```
+人物必须已被本场引用；若尚未引用，`insert` 会报出
+`actor_not_in_scene` 并给出修复命令，照做即可（`scriptctl ref <场> <人物> --state …`）。
 
-人物必须已经出现在本场 scene ref 中；需要指定造型时同时传 `--speaker-state <state-id>`。
-先运行 `scriptctl do edits.txt -p "$SCRIPT"` 查看计划，再用返回的 digest 精确 apply。
+要一次补多条、或顺带调整顺序时，改用整场回写：`read 4-1 > f.txt`，在文件里增删行，
+再 `write 4-1 -f f.txt`。**无锚点的行会被新建，消失的锚点会被删除。**
 
 ## 4. 合并被误拆的连续对白
 
@@ -76,15 +75,15 @@ timestamp <new-action-id> --set 00:42.533
 5. 视频确认它们属于同一次连续表达。
 
 保留第一条 Action ID，正文按原视频顺序拼接，时间戳取第一句真正开始的时间，删除后续
-Action。使用一个 `do` 事务：
+Action：
 
-```text
-replace <first-action-id> --from "第一段" --to "第一段第二段"
-timestamp <first-action-id> --set 00:42.533
-delete <second-action-id>
+```bash
+scriptctl edit <first> --content "第一段第二段" --ts 00:42.533 -p "$SCRIPT"
+scriptctl del <second> -p "$SCRIPT"
 ```
 
-多个连续碎片依次并入第一条。不同人物重复表达同一态度仍是多条对白；剧情功能相同不代表
+碎片多、或顺带要调顺序时改用整场回写（`read 4-1` → 改文件 → `write 4-1`）：把几行
+并成一行、只保留第一条的锚点，消失的锚点即删除，一次落盘。不同人物重复表达同一态度仍是多条对白；剧情功能相同不代表
 物理 Action 可以合并。
 
 ## 5. 人与 Agent 的分工
@@ -101,7 +100,6 @@ Agent 执行：
 
 - 查询 Action、资产、refs 和缺失时间戳；
 - 生成 V4 ID；
-- 组织 `do` 计划；
 - 应用经确认的插入、校时、合并和人物修复；
 - 读回目标并运行 `validate`；
 - 输出仍需人工复核的清单。