@lingjingai/scriptctl 0.49.5 → 0.49.7

package/scripts/install-skill.mjs

@@ -49,13 +49,13 @@ function readVersion(root) {
   }
 }
 
-// 把源 SKILL.md 里的 `scriptctl_version:` frontmatter 值改成实际安装的版本，让装好的
+// 把源 SKILL.md metadata 里的 `scriptctl_version:` 值改成实际安装的版本，让装好的
 // skill 一眼看清对应的是哪个 scriptctl。没有该行时不硬插（保持 frontmatter 干净）。
 function stampVersion(skillMdPath, version) {
   try {
     const text = fs.readFileSync(skillMdPath, "utf-8");
-    if (!/^scriptctl_version:/m.test(text)) return;
-    const stamped = text.replace(/^scriptctl_version:.*$/m, `scriptctl_version: "${version}"`);
+    if (!/^\s+scriptctl_version:/m.test(text)) return;
+    const stamped = text.replace(/^(\s+)scriptctl_version:.*$/m, `$1scriptctl_version: "${version}"`);
     fs.writeFileSync(skillMdPath, stamped, "utf-8");
   } catch {
     /* 戳版本失败不影响 skill 可用 */

package/skills/scriptctl/SKILL.md

@@ -1,9 +1,10 @@
 ---
 name: scriptctl
 description: "剧本 script.json 的读写 + 入库 CLI。转剧本：ingest（txt/md/docx 或视频，自动分流，产出 workspace/script.json）→ 标准化复核 → view 自查 → publish 入库。读：集/场/action/资产/状态/校验/时间戳/出场统计。写：台词/类型/归属/scene-ref 场景造型/内联发声源/importance/资产。选择器批量精修（读写共享 --in/谓词）、动词脚本 do（异构批量一事务）、结构调整（插/删/移/分/合）。从零创作、视频提取、小说与非标准剧本解析、洗稿/对标/转绘统一执行资产与 state 先行、场景引用完整、生产可执行正文规范。ingest status 从工作区真实文件报进度。沙箱里默认读写项目 DB；本地电脑默认 --script-path 直接读写本地 script.json。剧本阶段做任何剧本相关读写、以及操作两个 script.json 之前都应加载。正文由你用原子能力写入。"
-version: "0.23.0"
-scriptctl_version: "0.49.2"
-author: "official"
+metadata:
+  version: "0.24.0"
+  scriptctl_version: "0.49.7"
+  author: "official"
 ---
 
 # scriptctl
@@ -21,7 +22,7 @@ author: "official"
 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>` 绑定本场地点、全部人物、全部道具及其实际状态。正文中出现的资产属于本场引用集合。
+4. **建立真实场并绑定资产**：`insert <ep> --location` 建 scene 后，用 `scene-ref <ep/scn> <kind:id> --state <state_id>` 绑定本场地点、全部人物、全部道具及其实际状态。同一人物需要多份场景引用时，用 `--append` 逐份追加；正文中出现的资产属于本场引用集合。
 5. **写入或标准化正文**：资产批次落盘并读回确认后再写正文。发现新资产或新 state 时，先完成资产和 scene-ref，再继续正文。
 6. **逐场复核**：每批正文落盘后读回 `scenes / actions`；一集完成后运行 `validate`。`validate` 通过只代表结构与引用合法，仍需完成内容标准和源素材一致性复核。
 
@@ -36,13 +37,13 @@ author: "official"
 
 ### 场界判定
 
-场是时间、空间和生产状态连续的单元。同一地点、同一连续时段、同一叙事线、同一组视觉状态且动作未中断时，继续向当前 scene 追加；笑点升级、攻防回合、角色进出和剧情节拍不是分场理由。地点切换、明显跳时、切到另一条同时叙事线、明确转场，或人物/地点/道具切换到另一项持久视觉 state 时建立新 scene。一集可以只有一场。
+场是时间、空间和叙事连续的单元。同一地点、同一连续时段、同一叙事线且动作未中断时，继续向当前 scene 追加；笑点升级、攻防回合、角色进出、剧情节拍和同场人物造型变化不是分场理由。地点切换、明显跳时、切到另一条同时叙事线或明确转场时建立新 scene。一集可以只有一场。
 
-location 表示可独立布置、可独立生成参考图、可重复引用的稳定物理空间；客厅、卧室、卫生间、大厅、广场分别注册。相关空间使用“豪宅·客厅”“豪宅·卧室”这类统一命名表达归属，当前 Schema 不提供地点组或父地点。每个 scene 只支持一个 location 和每项资产的一个 state；需要一个镜头同时引用多个地点图或同一资产的多个状态图时，报告当前结构限制。
+location 表示可独立布置、可独立生成参考图、可重复引用的稳定物理空间；客厅、卧室、卫生间、大厅、广场分别注册。相关空间使用“豪宅·客厅”“豪宅·卧室”这类统一命名表达归属，当前 Schema 不提供地点组或父地点。每个 scene 只支持一个 location；人物引用可以重复，同一 actor 可按实际画面追加同 state 或不同 state 的多份引用。
 
 跨地点蒙太奇按剪辑顺序建立多个短 scene，每个 scene 绑定自己的地点、实际人物、道具和 state，并用 transition 明确蒙太奇开始、切换和结束。纯空镜 scene 绑定实际 location 与关键道具即可，不创建虚假人物。
 
-人物、地点或关键道具发生持久视觉状态变化时，变化前 scene 绑定旧 state，变化动作写在该 scene 末尾，变化后 scene 绑定新 state；同地点、同时段的状态边界保持独立。收尾时用 `scenes --in <ep>` 复核相邻场界，只合并地点、时段、叙事线和全部资产 state 均连续的误拆场。完整命令顺序见 [references/atomic-write-workflow.md](references/atomic-write-workflow.md)。
+人物在同一连续场内需要多份视觉参考时，先绑定第一份引用，再用 `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)。
 
 ## 先定目标：作用在哪份剧本上
 
@@ -121,7 +122,7 @@ scriptctl scenes --in ep_003              --script-path "$NEW"
 | 改 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；`--clear` / `--state none` 仅用于修复中间态，恢复 state 前不能继续插正文；`--remove` 整个移出场景）。location 单值（set 即替换） |
+| **设/改场景里某资产的造型（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> "震惊"` |
@@ -219,8 +220,12 @@ 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
 ```
 
+同一人物可在同一 scene 中出现多份引用。`--occurrence` 从 1 开始；命中多份却不指定 occurrence 时，修改、清除和删除都会拒绝执行。
+
 **整理重复角色**：
 ```bash
 scriptctl refs actor:act_005                 # 先看 act_005 出现在哪
@@ -323,7 +328,7 @@ scriptctl ingest status --json     # 机器：.status = {kind,state,phase,passes
 - 多态 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`。
+- 互斥 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 绕过校验。
 

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

@@ -26,7 +26,7 @@ create（空白剧本，既有剧本略过）
   → publish                                   入库（沙箱必做）
 ```
 
-> 发声源写在**对白行内联**（`dialogue <at> --actor/--kind`，或 `insert --actor/--kind`）；造型挂在**场景 cast 引用**上（`scene-ref <ep/scn> <kind:id> --state`）。正文插入前，本场必须已有地点，并且本场全部地点/人物/道具引用都绑定已建立的 state。空镜、环境动作或非角色发声场可以没有人物引用。
+> 发声源写在**对白行内联**（`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` 显式指定）。
 
@@ -61,6 +61,14 @@ scriptctl insert ep_001/scn_001 --type inner_thought --content "陈默又出现
 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。这两次落盘让宿主先展示人物、地点、道具及状态，再展示正文。
@@ -115,7 +123,7 @@ insert ep_001/scn_001 --type action   --content "雨夜，林夏推门进店。"
 insert ep_001/scn_001 --type dialogue --content "欢迎光临。" --actor act_002
 ```
 
-地点、时段、叙事线和全部资产 state 连续时，后续节拍继续向 `ep_001/scn_001` 追加 action。持久视觉 state 变化时在变化动作后建立同地点的新 scene，并绑定新 state。互动式写作可把长场拆成多个 action 批次依次 `do --apply`，每批都指向同一 scene。场界规则以 SKILL.md「标准剧本通用流程」为准。
+地点、时段和叙事线连续时，后续节拍继续向 `ep_001/scn_001` 追加 action。同场人物需要多个造型或多份画面引用时，对同一 actor 追加 scene-ref，并在 Action 中写清变化顺序。互动式写作可把长场拆成多个 action 批次依次 `do --apply`，每批都指向同一 scene。场界规则以 SKILL.md「标准剧本通用流程」为准。
 
 动词与单条命令完全一致（参数见 `scriptctl <verb> --help`）。`do` 也读 stdin：`… | scriptctl do -`。
 

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

@@ -16,7 +16,7 @@
 开始每一集和每一场前：
 
 1. 读取现有人物、地点、道具及其 states。
-2. 确定本场唯一地点、全部出场人物、全部使用道具和各自实际 state。
+2. 确定本场唯一地点、全部出场人物、全部使用道具和各自实际 state；同一人物需要多份画面引用时列出每一份引用。
 3. 注册缺少的资产，定义需要独立视觉参考的持久状态。
 4. 建立 scene，绑定地点、人物、道具及实际 state。
 5. 读回 scene-ref，确认正文中的每项资产都能映射到本场引用。
@@ -64,13 +64,13 @@
 - 当前没有 montage group。使用相邻 scene、transition 和统一文本标记表达组合关系。
 - 纯空镜或完全无人镜头单独建 scene，绑定实际 location 与关键道具，不创建虚假人物。
 
-## 八、场内状态变化
+## 八、同场人物多引用与状态变化
 
-- 一个 scene 中，每个人物、地点和道具绑定一个有效 state。
-- 需要更换视觉参考资产的持久状态变化构成生产场界，即使地点和时间连续也建立新 scene。
-- 变化前 scene 绑定旧 state，在末尾写清变化动作；需要生成过程画面时给该 Action 添加 `transition_prompt`。
-- 变化后 scene 绑定新 state。同地点、同时段的状态边界保持独立，不参与场景合并。
-- 当前同一 scene 不能同时引用同一资产的多个 state。一个镜头需要变化前后两张状态图时报告结构限制。
+- 一个 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 仍是单值引用。
 
 ## 九、完成门
 
@@ -78,6 +78,6 @@
 2. 检查每场唯一地点、全部出场人物、道具和 state 引用。
 3. 检查 Action 的真名、动作链、空间结果和可拍摄性。
 4. 检查 dialogue 的说话人、emotion 和群体发声类型。
-5. 检查场界、蒙太奇顺序和状态变化边界。
+5. 检查场界、蒙太奇顺序、重复人物引用和状态变化顺序。
 6. 提取与解析任务对照源素材复核对白原文，以及事实、因果、顺序、动作结果和状态。
 7. 运行 `validate`。把结构通过与内容标准、源素材一致性分别报告。