@lingjingai/scriptctl 0.49.11 → 0.49.13

package/skills/scriptctl/SKILL.md

@@ -1,9 +1,9 @@
 ---
 name: scriptctl
-description: "剧本 script.json 的本地读写 + 入库 CLI。远端剧本先 checkout 成工作副本，所有原子读写只改本地 script.json，完成后 publish 严格按 revision 入库；新增 op 无需新增业务 API。转剧本：ingest（txt/md/docx 或视频，产出 workspace/script.json）→ 标准化复核 → view 自查 → publish。覆盖集/场/action/资产/state/scene-ref/结构调整/批量 do/patch/校验。剧本阶段做任何剧本相关读写、以及操作两个 script.json 之前都应加载。"
+description: "剧本 script.json 的本地读写 + 入库 CLI。远端剧本先 checkout 成工作副本；完整剧集/场/正文区间用 export + 文件化 authoring + write plan/apply 批量创作或替换，细小精修用原子 verb/do；完成后 publish 严格按 revision 入库。也覆盖 ingest、查询、资产/state、校验。剧本阶段做任何剧本相关读写、以及操作两个 script.json 之前都应加载。"
 metadata:
-  version: "0.24.1"
-  scriptctl_version: "0.49.11"
+  version: "0.25.0"
+  scriptctl_version: "0.49.12"
   author: "official"
 ---
 
@@ -11,9 +11,10 @@ metadata:
 
 `scriptctl` 读写结构化剧本 `script.json`，并把外部素材转成剧本、入库。查询和原子编辑始终作用于本地文件；远端只在 `checkout` / `publish` 边界访问。
 
-两条主线：
+三条主线：
 - **转剧本入库**：`ingest`（抽取，产出 `workspace/script.json`）→ 标准化复核 → `view`（自查）→ `publish`（入库）。见 [references/ingest-workflow.md](references/ingest-workflow.md)。
-- **读写既有剧本**：查询 + 原子写 + 选择器批量 + `do`。
+- **完整块创作/替换**：`ids` → 写 `.scriptctl` authoring 文件，或先 `export` 既有完整块 → `write` plan → `write --apply --plan <digest>`。
+- **精修既有剧本**：查询 + 原子写 + 选择器批量 + `do`。
 
 ## 标准剧本通用流程：先把可引用世界建完整
 
@@ -47,7 +48,7 @@ location 表示可独立布置、可独立生成参考图、可重复引用的
 
 ## 先定本地文件
 
-- 查询、`create`、全部原子编辑、`do`、`patch` 只接受 `--script-path <file>`；省略时统一使用 `<cwd>/workspace/script.json`。
+- 查询、`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，不访问网络。
@@ -151,6 +152,39 @@ scriptctl emotion --in ep_003..ep_007 --actor act_001 "紧张" --apply
 
 > 先 discover 后 mutate 用**同一套 flag**：`scriptctl actions --in … --actor …` 查出来是哪些，换个动词就改哪些。`actions --json` 带结构化 `rows[]`，`actions … --format addr` 直接吐裸地址流喂 `xargs`。scene-ref/importance/dialogue 是**单点**动词，不进选择器批量。
 
+### 完整块批量创作与替换（`export` → authoring 文件 → `write`）
+
+写一整本、整集、整场，或替换中间连续几集/几场/几条 action 时，使用 `.scriptctl` authoring 文件，不把结构化 JSON 直接交给模型写。完整语法与约束见 [references/bulk-authoring.md](references/bulk-authoring.md)。
+
+```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
+```
+
+目标选择：
+
+| 需求 | 导出/authoring target | mode |
+|---|---|---|
+| 从零创建整本 | `export script` 作为模板，或直接写 `<script>` | `--create` |
+| 追加完整集/场 | `<episode>` / `<scene parent=...>` | `--create` |
+| 一对一替换多集/多场 | `export episodes` / `export scenes` | `--replace` |
+| 用不同数量节点替换连续几集/几场 | `export episode-spans` / `export scene-spans` | `--replace` |
+| 替换某场中间连续 action | `export action-spans` | `--replace` |
+
+一个 authoring 文件只有一种 target kind。scene span 的每个区间只能在同一 episode；action span 只能在同一 scene。区间端点按当前数组顺序判断，不按 ID 数字判断；新 ID 可以放在 replacement 内容中，但不能当旧区间端点。所有 span 都必须有非空 replacement。`write` 每次都持有本地独占锁，应用时还校验计划绑定的语义基线并用临时文件原子替换。
+
 ### 异构批量 `do`（一组各不相同的改动 = 一段动词脚本 = 一个事务）
 
 每行就是一条**去掉 `scriptctl` 的命令**，`#` 注释、空行随意；整段全成或全不成。比手写 patch JSON 省心（动词原样，不猜字段名）。

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

@@ -0,0 +1,165 @@
+# 文件化批量写作
+
+这套接口给 LLM 直接生成和修改，不要求人编辑 JSON。authoring 文件使用 XML 风格块表达结构边界，块内使用 `[type|slot...] content` 行表达高密度字段。
+
+## 固定工作流
+
+1. 既有远端剧本先 `checkout` 到 `--script-path`。
+2. 新 ID 用 `ids --kind ... --count ...` 查询候选值。它不预留 ID。
+3. 修改既有内容先用 typed `export` 导出完整目标；从零写时直接生成完整 `.scriptctl` 文件。
+4. `write FILE --create|--replace` 只做计划。
+5. 从计划读取完整 `plan_digest`。
+6. `write FILE --create|--replace --apply --plan DIGEST` 原子落盘。
+7. `validate` 后按需 `publish`。
+
+`write` 只接受命名文件，不读 stdin。digest 绑定源文件的精确字节、mode、解析后的正式目标和当前本地 Script v3 语义哈希。每次 plan/apply 均持有按 script 文件划分的独占锁；apply 在锁内重新校验基线。
+
+## 根结构
+
+```text
+<authoring version=1>
+
+<create>
+...create-only asset/state declarations...
+</create>
+
+...one or more homogeneous targets...
+
+</authoring>
+```
+
+`<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>
+```
+
+属性不加引号。script 只能有一个且 create-only。episode/scene 支持 create 或 replace。三种 span 都是 replace-only，端点包含两端，replacement 必须非空。
+
+## create-only 声明
+
+声明按 actor、location、prop 分组；每个新资产后立刻写它的 states，第一条且唯一常态 state 必须是 `default`。引用既有资产的 standalone state 放在所有资产声明之后。非 default `state_id` 全剧唯一。
+
+```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 至少一条 action。每个非空 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。
+
+## 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`。不支持注释或自由散文行。

package/dist/domain/ingest/script-v3.d.ts

@@ -1,94 +0,0 @@
-export type SpeakerV3 = {
-    actor_id: string;
-    state_id?: string;
-} | {
-    kind: "system" | "broadcast" | "offscreen" | "group";
-    label?: string;
-};
-export type Importance = "featured" | "background";
-export declare const IMPORTANCE_TIERS: readonly ["featured", "background"];
-export type TransitionPromptV3 = {
-    target: string;
-    process: string;
-    contrast: string;
-};
-export interface ActionV3 {
-    type: "action" | "dialogue" | "inner_thought" | "transition";
-    content: string;
-    speaker?: SpeakerV3;
-    emotion?: string;
-    transition_prompt?: TransitionPromptV3;
-}
-export type EntityRefV3 = {
-    actor_id: string;
-    state_id?: string;
-} | {
-    prop_id: string;
-    state_id?: string;
-};
-export interface SceneV3 {
-    scene_id: string;
-    environment?: {
-        space?: string;
-        time?: string;
-    };
-    location: {
-        location_id: string;
-        state_id?: string;
-    } | null;
-    actors: {
-        actor_id: string;
-        state_id?: string;
-    }[];
-    props: {
-        prop_id: string;
-        state_id?: string;
-    }[];
-    actions: ActionV3[];
-}
-export interface EpisodeV3 {
-    episode_id: string;
-    title?: string;
-    scenes: SceneV3[];
-}
-export interface StateV3 {
-    state_id: string;
-    state_name: string;
-    description: string;
-}
-export interface ActorV3 {
-    actor_id: string;
-    actor_name: string;
-    importance: Importance;
-    role_type?: string;
-    aliases?: string[];
-    description: string;
-    states: StateV3[];
-}
-export interface LocationV3 {
-    location_id: string;
-    location_name: string;
-    importance: Importance;
-    aliases?: string[];
-    description: string;
-    states: StateV3[];
-}
-export interface PropV3 {
-    prop_id: string;
-    prop_name: string;
-    importance: Importance;
-    aliases?: string[];
-    description: string;
-    states: StateV3[];
-}
-export interface ScriptV3 {
-    version: 3;
-    title: string;
-    worldview: string;
-    style: string;
-    actors: ActorV3[];
-    locations: LocationV3[];
-    props: PropV3[];
-    episodes: EpisodeV3[];
-}
-export declare const NON_ACTOR_SPEAKER_KINDS: readonly ["system", "broadcast", "offscreen", "group", "minor"];

package/dist/domain/ingest/script-v3.js

@@ -1,7 +0,0 @@
-// Script schema v3 (§15.1, revised): content is plain text; scene-level cast and
-// props carry materialized state. Kept ingest-local. Scripts remain plain JSON
-// objects; these types document the shape the emitter writes and the validator
-// enforces.
-export const IMPORTANCE_TIERS = ["featured", "background"];
-export const NON_ACTOR_SPEAKER_KINDS = ["system", "broadcast", "offscreen", "group", "minor"];
-//# sourceMappingURL=script-v3.js.map

package/dist/domain/ingest/script-v3.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"script-v3.js","sourceRoot":"","sources":["../../../src/domain/ingest/script-v3.ts"],"names":[],"mappings":"AAAA,iFAAiF;AACjF,+EAA+E;AAC/E,+EAA+E;AAC/E,YAAY;AASZ,MAAM,CAAC,MAAM,gBAAgB,GAAG,CAAC,UAAU,EAAE,YAAY,CAAU,CAAC;AAyCpE,MAAM,CAAC,MAAM,uBAAuB,GAAG,CAAC,QAAQ,EAAE,WAAW,EAAE,WAAW,EAAE,OAAO,EAAE,OAAO,CAAU,CAAC"}