@lingjingai/scriptctl 0.51.0 → 0.51.2

package/dist/usecases/script/migrate-v4.js

@@ -0,0 +1,194 @@
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { CliError, EXIT_NEEDS_AGENT, EXIT_OK, EXIT_USAGE, sha256Text, } from "../../common.js";
+import { requireScriptV3 } from "../../domain/script/v3/parse.js";
+import { validateScriptV3 } from "../../domain/script/v3/validation.js";
+import { newScriptV4FromV3WithIdentity, } from "../../domain/script/v4/from-v3.js";
+import { validateScriptV4 } from "../../domain/script/v4/validation.js";
+import { atomicWriteJson, withScriptFileLock, } from "../../infra/script-working-copy.js";
+function stringOption(opts, name) {
+    const value = opts[name];
+    return typeof value === "string" ? value.trim() : "";
+}
+function defaultIdentityMapPath(outputPath) {
+    const extension = path.extname(outputPath);
+    const stem = extension.length > 0
+        ? outputPath.slice(0, -extension.length)
+        : outputPath;
+    return `${stem}.identity-map.json`;
+}
+function requireDistinctPaths(sourcePath, outputPath, identityMapPath) {
+    const resolved = [sourcePath, outputPath, identityMapPath].map((item) => path.resolve(item));
+    if (resolved[0] === resolved[1]) {
+        throw new CliError("The V4 destination must differ from the V3 source.", {
+            exitCode: EXIT_USAGE,
+            errorCode: "MIGRATE_SAME_PATH",
+            hint: "Choose a separate --output path. The source V3 file stays unchanged.",
+            data: { actual: [sourcePath] },
+        });
+    }
+    if (resolved[0] === resolved[2] || resolved[1] === resolved[2]) {
+        throw new CliError("The identity map needs its own file path.", {
+            exitCode: EXIT_USAGE,
+            errorCode: "MIGRATE_IDENTITY_MAP_PATH",
+            hint: "Choose an --identity-map path separate from the source and output files.",
+            data: { actual: [identityMapPath] },
+        });
+    }
+}
+function assertWritableDestination(filePath, force) {
+    if (!force && fs.existsSync(filePath)) {
+        throw new CliError("Migration destination already exists.", {
+            exitCode: EXIT_USAGE,
+            errorCode: "MIGRATE_OUTPUT_EXISTS",
+            hint: "Choose a new path, or pass --force to replace the migration artifact.",
+            data: { actual: [filePath] },
+        });
+    }
+}
+function readSource(sourcePath) {
+    let raw;
+    try {
+        raw = fs.readFileSync(sourcePath, "utf8");
+    }
+    catch (error) {
+        throw new CliError("Cannot read the Script v3 source.", {
+            exitCode: EXIT_USAGE,
+            errorCode: "MIGRATE_SOURCE_READ_FAILED",
+            hint: "Pass an existing JSON file with --script-path.",
+            data: { actual: [sourcePath, error instanceof Error ? error.message : String(error)] },
+        });
+    }
+    try {
+        return { raw, value: JSON.parse(raw) };
+    }
+    catch (error) {
+        throw new CliError("The Script v3 source is not valid JSON.", {
+            exitCode: EXIT_USAGE,
+            errorCode: "MIGRATE_SOURCE_JSON_INVALID",
+            hint: "Repair the JSON syntax, then rerun migrate-v4.",
+            data: { actual: [error instanceof Error ? error.message : String(error)] },
+        });
+    }
+}
+function v3IdentityKeys(source) {
+    const action = {};
+    for (const episode of source.episodes) {
+        for (const scene of episode.scenes) {
+            const sceneAddress = `${episode.episode_id}/${scene.scene_id}`;
+            scene.actions.forEach((_item, index) => {
+                const address = `${sceneAddress}#${index}`;
+                action[address] = address;
+            });
+        }
+    }
+    return { action };
+}
+function readPriorIdentityMap(identityMapPath, force) {
+    if (!force || !fs.existsSync(identityMapPath))
+        return undefined;
+    let value;
+    try {
+        value = JSON.parse(fs.readFileSync(identityMapPath, "utf8"));
+    }
+    catch (error) {
+        throw new CliError("Cannot reuse the existing V3-to-V4 identity map.", {
+            exitCode: EXIT_USAGE,
+            errorCode: "MIGRATE_IDENTITY_MAP_INVALID",
+            hint: "Restore the identity map, or choose a new --identity-map path.",
+            data: { actual: [identityMapPath, error instanceof Error ? error.message : String(error)] },
+        });
+    }
+    if (value === null || typeof value !== "object" || Array.isArray(value)) {
+        throw new CliError("Cannot reuse the existing V3-to-V4 identity map.", {
+            exitCode: EXIT_USAGE,
+            errorCode: "MIGRATE_IDENTITY_MAP_INVALID",
+            hint: "Restore the identity map, or choose a new --identity-map path.",
+            data: { actual: [identityMapPath] },
+        });
+    }
+    const record = value;
+    const identityMap = record["identity_map"] ?? value;
+    if (identityMap === null
+        || typeof identityMap !== "object"
+        || Array.isArray(identityMap)
+        || identityMap["version"] !== 3) {
+        throw new CliError("Cannot reuse the existing V3-to-V4 identity map.", {
+            exitCode: EXIT_USAGE,
+            errorCode: "MIGRATE_IDENTITY_MAP_INVALID",
+            hint: "Restore the identity map, or choose a new --identity-map path.",
+            data: { actual: [identityMapPath] },
+        });
+    }
+    return identityMap;
+}
+export async function commandMigrateV4(opts) {
+    const sourceRawPath = stringOption(opts, "script_path");
+    const outputRawPath = stringOption(opts, "output");
+    if (!sourceRawPath || !outputRawPath) {
+        throw new CliError("Migration paths are required.", {
+            exitCode: EXIT_USAGE,
+            errorCode: "MIGRATE_PATH_MISSING",
+            hint: "Pass --script-path <v3.json> and --output <v4.json>.",
+            data: { expected: ["--script-path <v3.json>", "--output <v4.json>"] },
+        });
+    }
+    const sourcePath = path.resolve(sourceRawPath);
+    const outputPath = path.resolve(outputRawPath);
+    const identityMapPath = path.resolve(stringOption(opts, "identity_map") || defaultIdentityMapPath(outputPath));
+    const force = Boolean(opts["force"]);
+    requireDistinctPaths(sourcePath, outputPath, identityMapPath);
+    return withScriptFileLock(outputPath, async () => {
+        assertWritableDestination(outputPath, force);
+        assertWritableDestination(identityMapPath, force);
+        const sourceDocument = readSource(sourcePath);
+        const source = requireScriptV3(sourceDocument.value);
+        const sourceValidation = validateScriptV3(source);
+        const priorIdentityMap = readPriorIdentityMap(identityMapPath, force);
+        const converted = newScriptV4FromV3WithIdentity(source, priorIdentityMap, v3IdentityKeys(source));
+        const validation = validateScriptV4(converted.script);
+        const migrationRecord = {
+            version: 1,
+            source_version: 3,
+            target_version: 4,
+            source_path: sourcePath,
+            source_sha256: sha256Text(sourceDocument.raw),
+            identity_map: converted.identityMap,
+        };
+        atomicWriteJson(identityMapPath, migrationRecord);
+        atomicWriteJson(outputPath, converted.script);
+        const data = {
+            op: "script.migrate-v4",
+            changed: true,
+            source_script_path: sourcePath,
+            script_path: outputPath,
+            identity_map_path: identityMapPath,
+            source_version: 3,
+            target_version: 4,
+            source_validation: {
+                ok: sourceValidation.ok,
+                errors: sourceValidation.errors.length,
+                warnings: sourceValidation.warnings.length,
+            },
+            validation: {
+                ok: validation.ok,
+                errors: validation.errors.length,
+                warnings: validation.warnings.length,
+                issues: validation.errors.slice(0, 100),
+            },
+        };
+        const text = validation.ok
+            ? [
+                `V4 script: ${outputPath}`,
+                `Identity map: ${identityMapPath}`,
+                "validation: ok",
+            ].join("\n")
+            : [
+                `V4 script: ${outputPath}`,
+                `Identity map: ${identityMapPath}`,
+                `validation: ${validation.errors.length} errors; repair before production use`,
+            ].join("\n");
+        return [{ text, data }, validation.ok ? EXIT_OK : EXIT_NEEDS_AGENT];
+    });
+}
+//# sourceMappingURL=migrate-v4.js.map

package/dist/usecases/script/migrate-v4.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"migrate-v4.js","sourceRoot":"","sources":["../../../src/usecases/script/migrate-v4.ts"],"names":[],"mappings":"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"}

package/dist/usecases/script/v4/mutations.js

@@ -1,6 +1,6 @@
 import { applyPatchOperationsV4 } from "../../../domain/script/v4/patch/apply.js";
-import { requireScriptV4 } from "../../../domain/script/v4/parse.js";
+import { requireStructurallyReadableScriptV4 } from "../../../domain/script/v4/parse.js";
 export function applyV4Mutations(script, operations) {
-    return applyPatchOperationsV4(requireScriptV4(script), operations);
+    return applyPatchOperationsV4(requireStructurallyReadableScriptV4(script), operations);
 }
 //# sourceMappingURL=mutations.js.map

package/dist/usecases/script/v4/mutations.js.map

@@ -1 +1 @@
-{"version":3,"file":"mutations.js","sourceRoot":"","sources":["../../../../src/usecases/script/v4/mutations.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,sBAAsB,EAAE,MAAM,0CAA0C,CAAC;AAClF,OAAO,EAAE,eAAe,EAAE,MAAM,oCAAoC,CAAC;AAGrE,MAAM,UAAU,gBAAgB,CAAC,MAAY,EAAE,UAAkB;IAC/D,OAAO,sBAAsB,CAAC,eAAe,CAAC,MAAM,CAAC,EAAE,UAAU,CAAC,CAAC;AACrE,CAAC"}
+{"version":3,"file":"mutations.js","sourceRoot":"","sources":["../../../../src/usecases/script/v4/mutations.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,sBAAsB,EAAE,MAAM,0CAA0C,CAAC;AAClF,OAAO,EAAE,mCAAmC,EAAE,MAAM,oCAAoC,CAAC;AAGzF,MAAM,UAAU,gBAAgB,CAAC,MAAY,EAAE,UAAkB;IAC/D,OAAO,sBAAsB,CAAC,mCAAmC,CAAC,MAAM,CAAC,EAAE,UAAU,CAAC,CAAC;AACzF,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lingjingai/scriptctl",
-  "version": "0.51.0",
+  "version": "0.51.2",
   "description": "剧本阶段统一 CLI：素材转 Script v4，并兼容 Script v3 的本地写作、精修、校验和发布。",
   "type": "module",
   "bin": {

package/skills/scriptctl/SKILL.md

@@ -2,16 +2,19 @@
 name: scriptctl
 description: "剧本 script.json 的本地查询、文件化批量写作、原子精修、素材 ingest 与 revision publish CLI。处理 Script v3/v4、两个 script.json、剧本资产/state、Action、场景引用或 authoring 时使用。"
 metadata:
-  version: "0.27.0"
-  scriptctl_version: "0.51.0"
+  version: "0.27.2"
+  scriptctl_version: "0.51.2"
   author: "official"
 ---
 
 # scriptctl
 
-`scriptctl` 始终对 `--script-path` 指向的本地 `script.json` 工作。远端剧本先
+`scriptctl` 始终对 `-p` 指向的本地 `script.json` 工作。远端剧本先
 `checkout`，完成本地查询、修改和 `validate` 后再 `publish`。
 
+实际调用和示例优先使用短参数：`-p/-w/-s/-o/-i/-g/-t/-a/-k/-n/-j/-h/-v`。
+没有短名的参数保持完整长写。
+
 ## 先识别版本
 
 读取 `script.json.version`：
@@ -29,7 +32,7 @@ metadata:
 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>`，检查人物身份重复、同义视觉状态、未使用/落单状态，以及重复地点和道具资产。审计只给建议，不自动合并；必须核对剧情、身份、外观和跨集连续性后再修复。
+7. **全剧资产审计**：全剧完成后运行 `audit-assets -p <file>`，检查人物身份重复、同义视觉状态、未使用/落单状态，以及重复地点和道具资产。审计只给建议，不自动合并；必须核对剧情、身份、外观和跨集连续性后再修复。
 
 ## 三条工作流
 
@@ -40,19 +43,22 @@ metadata:
    [references/bulk-authoring.md](references/bulk-authoring.md)。
 3. 少量精修：查询定位 → 单 ID 原子 verb；同构多点用 selector；异构多点用
    `do`。见 [references/atomic-edit-workflow.md](references/atomic-edit-workflow.md)。
+4. 旧视频转录复核：V3 资产修复 → `migrate-v4` → 关联视频 → 补行、校时、
+   合并误拆对白 → `validate`。见
+   [references/video-transcript-repair.md](references/video-transcript-repair.md)。
 
 ## 本地文件边界
 
 - 普通命令默认读取 `<cwd>/workspace/script.json`；操作其他文件时始终显式传
-  `--script-path <file>`。
-- `--workspace-path` 只属于 `ingest`、`ingest status` 和 `view`。
-- 同时处理原剧与目标剧时，每条命令都显式带对应 `--script-path`，只从原剧读，
+  `-p <file>`。
+- `-w` 只属于 `ingest`、`ingest status` 和 `view`。
+- 同时处理原剧与目标剧时，每条命令都显式带对应 `-p`，只从原剧读，
   只向目标剧写。
 - `checkout` 不覆盖未管理文件或本地修改；`publish` 按工作副本 revision 严格写入。
 
 ## 查询与定位
 
-默认文本查询输出 TSV。需要结构化数据时使用 `--json`：顶层固定包含
+默认文本查询输出 TSV。需要结构化数据时使用 `-j`：顶层固定包含
 `ok`、`exit_code`，表格数据位于 `rows`，列顺序位于 `row_columns`。地址流使用
 `--format addr`。写命令的 JSON 使用 `op`、`changed`、`plan_digest`、
 `validation`、`script_path` 等命令自身字段，不包含展示用的标题或结果区块。
@@ -61,14 +67,14 @@ JSON 错误包含 `error_code`、`message` 和可选 `hint`。
 常用查询：
 
 ```bash
-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"
+scriptctl summary -p "$SCRIPT"
+scriptctl episodes -p "$SCRIPT"
+scriptctl scenes -i '@ep:3' -p "$SCRIPT"
+scriptctl actions -g "台下掌声" -p "$SCRIPT"
+scriptctl actors --counts -p "$SCRIPT"
+scriptctl states actA3kP9x -p "$SCRIPT"
+scriptctl refs actA3kP9x/stB4xR8p -p "$SCRIPT"
+scriptctl validate -p "$SCRIPT"
 ```
 
 序号锚点是 1-based 查询语法：
@@ -86,18 +92,18 @@ scriptctl validate --script-path "$SCRIPT"
 |---|---|
 | **了解剧情 / 全貌**：synopsis/worldview/style/logline/theme/main_characters + 标题/集数/场数/资产数（"这剧本是关于什么"先跑这个） | `scriptctl summary` |
 | 每集字数 / 场数 / action 数 **+ 每集剧情梗概** | `scriptctl episodes`（`--min-chars 1000` 找长集） |
-| 看某集的所有场（含 `t=t_start..t_end` 时段） | `scriptctl scenes --in '@ep:7'` |
-| 看某场的资产 + action 数 | `scriptctl scenes --in '@ep:7/scn:5'` |
-| **按正文搜某句话定位 action**（最常用） | `scriptctl actions --grep "<片段>"` |
-| 列某集所有 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` |
+| 看某集的所有场（含 `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'` |
+| 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` |
-| 全剧人物/状态/地点/道具去重审计 | `scriptctl audit-assets --script-path workspace/script.json` |
+| 全剧人物/状态/地点/道具去重审计 | `scriptctl audit-assets -p workspace/script.json` |
 
 ## Script v4 写入
 
@@ -110,18 +116,18 @@ ep……  scn……  ac……  act……  loc……  prp……  st……
 `ids` 只生成候选，不预留：
 
 ```bash
-scriptctl ids --kind action --count 4
-scriptctl ids --kind scene --count 2 --script-path "$SCRIPT"
+scriptctl ids -k action --count 4
+scriptctl ids -k scene --count 2 -p "$SCRIPT"
 ```
 
 单点修改使用正式 ID：
 
 ```bash
-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"
+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 dialogue acT2fG6z -a actA3kP9x --state stB4xR8p -p "$SCRIPT"
 ```
 
 `parenthetical` 只属于 dialogue / inner_thought。字段省略表示没有表演提示；显式
@@ -131,7 +137,7 @@ V4 placement 使用父节点与相邻节点 ID：
 
 ```bash
 scriptctl insert scnK6wT3c --action-id acD4eF6g \
-  --type action --content "陈默关上门。" --before acT2fG6z
+  -t action --content "陈默关上门。" --before acT2fG6z
 scriptctl move acD4eF6g scnH7jK9m --after acR8cV4n
 scriptctl split scnK6wT3c --at acT2fG6z --new-scene-id scnD4eF6g
 ```
@@ -143,8 +149,8 @@ V4 一个场景内同一资产只引用一次；引用携带完整、非空的 `
 
 ```bash
 scriptctl scene-ref scnK6wT3c actA3kP9x \
-  --state default --state stB4xR8p --script-path "$SCRIPT"
-scriptctl scene-ref scnK6wT3c actA3kP9x --remove --script-path "$SCRIPT"
+  --state default --state stB4xR8p -p "$SCRIPT"
+scriptctl scene-ref scnK6wT3c actA3kP9x --remove -p "$SCRIPT"
 ```
 
 actor speaker 可选一个 state；若指定，必须属于该 actor 在当前 scene 的
@@ -153,10 +159,10 @@ actor speaker 可选一个 state；若指定，必须属于该 actor 在当前 s
 state 修改前后都反查并校验：
 
 ```bash
-scriptctl refs actA3kP9x/stB4xR8p --script-path "$SCRIPT"
+scriptctl refs actA3kP9x/stB4xR8p -p "$SCRIPT"
 scriptctl state-delete actA3kP9x/stB4xR8p \
-  --strategy replace --replacement default --script-path "$SCRIPT"
-scriptctl validate --script-path "$SCRIPT"
+  --strategy replace --replacement default -p "$SCRIPT"
+scriptctl validate -p "$SCRIPT"
 ```
 
 详见 [references/state-reference-repair.md](references/state-reference-repair.md)。
@@ -174,13 +180,28 @@ scriptctl scene-ref ep_001/scn_003 actor:act_001 --state st_002
 对 V3 文件运行 `export`、`write`、原子命令、`validate` 和 `publish` 时，CLI
 会选择 V3 实现并保持原文件结构与既有 ID。
 
+旧 V3 转录稿进入新项目时创建独立 V4 副本：
+
+```bash
+scriptctl migrate-v4 \
+  -p ./source-v3.json \
+  -o ./script-v4.json \
+  --identity-map ./script-v4.identity-map.json
+```
+
+命令保留源文件，输出 V4 剧本和 V3→V4 身份映射。输出仍有校验错误时，命令返回
+`78`，文件继续作为“待人工修复”的 V4 工作副本使用；`validation.issues` 是修复清单。
+使用 `do` 或 `patch` 在一个事务中消除全部 blocking issue，再落盘。
+修正 V3 源后使用同一映射路径和 `--force` 重跑，既有节点复用已分配的 V4 ID。
+结构性插入、删除或调序会改变 V3 的序号身份；完成首次迁移后直接精修 V4。
+
 ## 多点写与 plan
 
 V4 单个明确 ID 的原子修改直接执行。任何单事务多点修改先生成完整计划：
 
 ```bash
-scriptctl replace --in 'acR8cV4n..acT2fG6z' --from "。" --to "！"
-scriptctl replace --in 'acR8cV4n..acT2fG6z' --from "。" --to "！" \
+scriptctl replace -i 'acR8cV4n..acT2fG6z' --from "。" --to "！"
+scriptctl replace -i 'acR8cV4n..acT2fG6z' --from "。" --to "！" \
   --apply --plan sha256:...
 
 scriptctl do edits.txt

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

@@ -8,9 +8,9 @@
 先查询，再用查询结果中的地址修改：
 
 ```bash
-scriptctl actions --grep "台下掌声雷动" --script-path "$SCRIPT"
+scriptctl actions -g "台下掌声雷动" -p "$SCRIPT"
 scriptctl replace acR8cV4n --from "台下掌声雷动" --to "掌声骤停" \
-  --script-path "$SCRIPT"
+  -p "$SCRIPT"
 ```
 
 V4 查询可以使用 1-based `@` 序号，但修改必须使用正式 ID。V3 查询返回原有的
@@ -21,8 +21,8 @@ V4 查询可以使用 1-based `@` 序号，但修改必须使用正式 ID。V3
 V4 先运行 dry-run，读取完整目标和 `plan_digest`，再用相同命令 apply：
 
 ```bash
-scriptctl replace --in 'acR8cV4n..acT2fG6z' --from "。" --to "！"
-scriptctl replace --in 'acR8cV4n..acT2fG6z' --from "。" --to "！" \
+scriptctl replace -i 'acR8cV4n..acT2fG6z' --from "。" --to "！"
+scriptctl replace -i 'acR8cV4n..acT2fG6z' --from "。" --to "！" \
   --apply --plan sha256:...
 ```
 
@@ -37,8 +37,8 @@ scene-ref scnK6wT3c actA3kP9x --state default --state stB4xR8p
 ```
 
 ```bash
-scriptctl do edits.txt --script-path "$SCRIPT"
-scriptctl do edits.txt --apply --plan sha256:... --script-path "$SCRIPT"
+scriptctl do edits.txt -p "$SCRIPT"
+scriptctl do edits.txt --apply --plan sha256:... -p "$SCRIPT"
 ```
 
 `do` 整体解析、修改和校验；任一行失败时不落盘。

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

@@ -3,25 +3,25 @@
 适用：有外部素材要**转成 Script v4 并入库**。统一入口 `scriptctl ingest`，按 source 类型自动分流文本 / 视频；两条管线最终都产出 v4 `script.json`。视频、小说和非标准剧本统一执行 [production-writing-standard.md](production-writing-standard.md)。
 
 ```
-ingest --source-path <file|dir>   →   标准化复核   →   view / ingest status   →   publish
+ingest -s <file|dir>   →   标准化复核   →   view / ingest status   →   publish
    (抽取，产 workspace/script.json)       (内容完成门)       (自查/看进度)            (校验+入库)
 ```
 
 - 支持输入：**文本** txt / md / docx；**视频** 单个正片文件或**分集目录**（需 `GEMINI_API_KEY`）。pdf/json/xlsx 会被拒。
-- `ingest` **不入库**：只产 `workspace/script.json`（默认工作区 `workspace`，可 `--workspace-path` 改）。入库是独立的 `publish`。
-- 产物随后就是普通剧本：任何读写动词加 `--script-path workspace/script.json` 即可精修。
+- `ingest` **不入库**：只产 `workspace/script.json`（默认工作区 `workspace`，可 `-w` 改）。入库是独立的 `publish`。
+- 产物随后就是普通剧本：任何读写动词加 `-p workspace/script.json` 即可精修。
 
 ## 一、抽取 `ingest`
 
 ```bash
 # 文本
-scriptctl ingest --source-path uploads/剧本.docx
+scriptctl ingest -s uploads/剧本.docx
 # 视频（分集目录，文件名带集号；单文件也行）
-scriptctl ingest --source-path uploads/正片/
+scriptctl ingest -s uploads/正片/
 ```
 
 常用 flag：
-- `--workspace-path <dir>`：工作区根（manifest + 各 pass 目录 + 产物）。**不传默认 `<cwd>/workspace`**；显式传可放别处。`view` / `ingest status` 使用同一 workspace；publish 用 `--script-path <workspace>/script.json`。
+- `-w <dir>`：工作区根（manifest + 各 pass 目录 + 产物）。**不传默认 `<cwd>/workspace`**；显式传可放别处。`view` / `ingest status` 使用同一 workspace；publish 用 `-p <workspace>/script.json`。
 - `--concurrency <n>`：文本 fanout 并发，默认 30。视频逐集串行。
 - `--fps <n>`：视频采样帧率（>1 解锁亚秒级时间码）。默认 3。
 - `--force`：**同源**重跑，清掉产物重来（**不能换源**）。
@@ -43,21 +43,21 @@ scriptctl ingest --source-path uploads/正片/
 `ingest` 生成且 `validate` 通过只代表结构与引用合法。publish 前按 [production-writing-standard.md](production-writing-standard.md) 逐集复核：
 
 1. 用 `actors / locations / props / states` 检查资产、去重、importance 和持久视觉状态。
-2. 用 `scenes --in <ep>` 检查唯一地点、场界、蒙太奇顺序和状态变化边界。
-3. 用 `actions --in <ep>` 检查说话人、群体发声、人物真名、动作链和可拍摄性。
+2. 用 `scenes -i <ep>` 检查唯一地点、场界、蒙太奇顺序和状态变化边界。
+3. 用 `actions -i <ep>` 检查说话人、群体发声、人物真名、动作链和可拍摄性。
 4. 视频对照画面与声音；文本对照原文，确认对白逐字保真，事实、因果、顺序、动作结果和状态没有改变或补造。
-5. 运行 `audit-assets --script-path workspace/script.json`，查看 `asset-audit.json` 中的人物身份重复、同义状态、未使用/落单状态、重复地点和道具建议。不要仅凭名称相似或低频就合并、删除。
+5. 运行 `audit-assets -p workspace/script.json`，查看 `asset-audit.json` 中的人物身份重复、同义状态、未使用/落单状态、重复地点和道具建议。不要仅凭名称相似或低频就合并、删除。
 6. 用 scriptctl 读写动词修正 `workspace/script.json`，再次运行 `validate` 和 `audit-assets`，完成内容复核后再 publish。
 
 ## 三、看进度 / 自查
 
 ```bash
 scriptctl ingest status          # 人读：kind / state / 各 pass 进度（transcribe 40/57 (2 failed) ...）
-scriptctl ingest status --json   # 机器：.status = {kind,state,phase,passes[],units,validation,errors[]}
+scriptctl ingest status -j   # 机器：.status = {kind,state,phase,passes[],units,validation,errors[]}
 scriptctl view                   # 生成 workspace/review.html（视频版可点击定位到画面）
 scriptctl view --watch [--port N]# 实时监听面板：分阶段进度条 + 逐集 context/决策 + 产物树，自动刷新（跑中也能开）。🔴 仅本地用，**沙箱内不要用**（起阻塞服务+开浏览器，会挂住；沙箱看进度用 `ingest status`）
-scriptctl audit-assets --script-path workspace/script.json  # 全剧资产一致性复核；结果写 asset-audit.json
-scriptctl summary --script-path workspace/script.json   # 抽完当普通剧本读
+scriptctl audit-assets -p workspace/script.json  # 全剧资产一致性复核；结果写 asset-audit.json
+scriptctl summary -p workspace/script.json   # 抽完当普通剧本读
 ```
 
 `state`：`empty`（没开始）/ `incomplete`（在跑或中断、无硬错，重跑续）/ `failed`（有失败单元或校验没过）/ `ready`（`script.json` 生成且 v4 结构校验通过）。`validation.json` 的 production/asset-audit warning 标出仍需复核的问题，`asset-audit.json` 保存完整证据和建议。进度从工作区真实文件推导；它报的是管线事实，资产合并结论和源素材一致性仍由复核完成门确认。
@@ -71,7 +71,7 @@ scriptctl summary --script-path workspace/script.json   # 抽完当普通剧本
 | `INGEST_NORMALIZE_INCOMPLETE`（文本）<br>`INGEST_TRANSCRIBE_/CORRECT_/SPEAKER_INCOMPLETE`（视频） | 部分单元失败，留下 `passN/*.error.json` sidecar | **直接重跑 `scriptctl ingest`（同 source、同 workspace）**——从 checkpoint 续，只补失败单元。跑完 `ingest status` 看还剩几个，多跑几次到收敛 |
 | `INGEST_SERIAL_FAILED`（文本串行 govern） | 某集串行解析连试几次仍失败（模型抖动） | **直接重跑**，从该集续——前面各集已缓存不重跑 |
 | `INGEST_PIPELINE_MISMATCH` | 工作区的管线版本与当前版本不同 | 确认 source 未变化后，使用同一 source、同一 workspace 加 `--force` 完整重建 checkpoint |
-| `INGEST_SOURCE_MISMATCH` | 工作区是别的 source 建的 | 换一个新的 `--workspace-path`，**别 `--force` 硬覆盖** |
+| `INGEST_SOURCE_MISMATCH` | 工作区是别的 source 建的 | 换一个新的 `-w`，**别 `--force` 硬覆盖** |
 | `INGEST_VALIDATION_FAILED` | 最终校验没过 | 看 `workspace/validation.json` 的具体报错，修复后再 `publish` |
 | 持续 401/403/404 / 模型路由错 | 网关/密钥/模型环境问题（不是抖动，重跑也不好） | 如实告诉用户，别反复空跑、别编造成功。视频需 `GEMINI_API_KEY` |
 
@@ -80,18 +80,18 @@ scriptctl summary --script-path workspace/script.json   # 抽完当普通剧本
 ## 五、入库 `publish`
 
 ```bash
-scriptctl publish --script-path workspace/script.json
-scriptctl publish --script-path workspace/script.json --project-group-no 123
+scriptctl publish -p workspace/script.json
+scriptctl publish -p workspace/script.json --project-group-no 123
 ```
 
-- `publish` 读本地 `--script-path`（默认 `workspace/script.json`），按显式版本再次校验，通过才发布。
+- `publish` 读本地 `-p`（默认 `workspace/script.json`），按显式版本再次校验，通过才发布。
 - 沙箱里转完**必须 publish**，否则后端/前端看不到剧本。
 - 已管理工作副本 publish 采用 local-wins：CAS/网络失败后重拉 snapshot、重算 diff 并重试，最终远端内容以本地稿为准。
 - 已管理且内容未变时 publish 本地直接 no-op，不发网络请求。服务端不保存 requestId，也不提供 publish 幂等重试。
 
 ## 六、复杂场景怎么接
 
-- **转完先精修再入库**：`ingest` → 用 `--script-path workspace/script.json` 跑读写动词修（改归属、并角色、标龙套、补造型……）→ `publish`。
+- **转完先精修再入库**：`ingest` → 用 `-p workspace/script.json` 跑读写动词修（改归属、并角色、标龙套、补造型……）→ `publish`。
 - **入库后再改**：继续编辑同一个受管本地文件再 publish；若工作副本不在，先 checkout，不能直接对 DB 跑原子命令。
 - **视频复核**：`view` 出的 `review.html` 视频版支持点击台词跳到对应画面时间码，逐场核对发声源/造型。
 - **超大剧集（几十集）**：并发默认已调好；失败就重跑到 `ingest status` 显示 `ready`。花名册归并只跑一次并复用，重跑很快。
@@ -99,8 +99,8 @@ scriptctl publish --script-path workspace/script.json --project-group-no 123
 
 ## 七、抽完后的读写
 
-抽取产物就是标准 v4 剧本，用 SKILL.md 里所有读写能力精修（目标指 `--script-path workspace/script.json`；远端稿先 checkout）：
-- `summary` / `episodes` 看整本 + 分集梗概；`actions --in <ep>` 带 timestamp 看节奏。
+抽取产物就是标准 v4 剧本，用 SKILL.md 里所有读写能力精修（目标指 `-p workspace/script.json`；远端稿先 checkout）：
+- `summary` / `episodes` 看整本 + 分集梗概；`actions -i <ep>` 带 timestamp 看节奏。
 - `states <actor>` 看造型弧线；`actors --counts` 看出场频次决定 `importance`。
-- 归属/造型修正：`dialogue <at> --actor/--kind`、`scene-ref <ep/scn> <kind:id> --state`。
+- 归属/造型修正：`dialogue <at> -a/-k`、`scene-ref <ep/scn> <kind:id> --state`。
 - 梗概/世界观：`synopsis` / `synopsis generate`（LLM 批量）/ `worldview`。

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

@@ -3,7 +3,7 @@
 先反查旧 state：
 
 ```bash
-scriptctl refs actA3kP9x/stB4xR8p --script-path "$SCRIPT"
+scriptctl refs actA3kP9x/stB4xR8p -p "$SCRIPT"
 ```
 
 ## Script v4
@@ -13,7 +13,7 @@ speaker 上同步替换：
 
 ```bash
 scriptctl state-delete actA3kP9x/stB4xR8p \
-  --strategy replace --replacement default --script-path "$SCRIPT"
+  --strategy replace --replacement default -p "$SCRIPT"
 ```
 
 `--strategy remove` 会从每个集合移除该 state；若任何集合将变为空，命令拒绝，
@@ -26,13 +26,13 @@ scriptctl state-delete actA3kP9x/stB4xR8p \
 
 ```bash
 scriptctl state-delete actor:act_001/st_002 \
-  --strategy replace --replacement st_001 --script-path "$SCRIPT"
+  --strategy replace --replacement st_001 -p "$SCRIPT"
 ```
 
 ## 核验
 
 ```bash
-scriptctl refs <旧-state-address> --script-path "$SCRIPT"
-scriptctl refs <新-state-address> --script-path "$SCRIPT"
-scriptctl validate --script-path "$SCRIPT"
+scriptctl refs <旧-state-address> -p "$SCRIPT"
+scriptctl refs <新-state-address> -p "$SCRIPT"
+scriptctl validate -p "$SCRIPT"
 ```