@lingjingai/scriptctl 0.50.0 → 0.51.1

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"
 ```

package/dist/help-text.d.ts

@@ -1,2 +0,0 @@
-export declare function getHelp(command: readonly string[]): string | undefined;
-export declare const HELP: Map<string, string>;