@lingjingai/scriptctl 0.49.7 → 0.49.9

package/skills/scriptctl/SKILL.md

@@ -1,15 +1,15 @@
 ---
 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 之前都应加载。正文由你用原子能力写入。"
+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 之前都应加载。"
 metadata:
   version: "0.24.0"
-  scriptctl_version: "0.49.7"
+  scriptctl_version: "0.49.8"
   author: "official"
 ---
 
 # scriptctl
 
-`scriptctl` 读写结构化剧本 `script.json`（Schema v3：资产 人物/场景/道具 + 分集→场景→action + 场景级 cast/造型 + 内联发声源 + 引用完整性 + 校验），并把外部素材**转成剧本、入库**。**每次调用只作用于一份剧本**（由目标 flag 选定），所以「换剧本 = 换目标」。
+`scriptctl` 读写结构化剧本 `script.json`，并把外部素材转成剧本、入库。查询和原子编辑始终作用于本地文件；远端只在 `checkout` / `publish` 边界访问。
 
 两条主线：
 - **转剧本入库**：`ingest`（抽取，产出 `workspace/script.json`）→ 标准化复核 → `view`（自查）→ `publish`（入库）。见 [references/ingest-workflow.md](references/ingest-workflow.md)。
@@ -45,21 +45,15 @@ location 表示可独立布置、可独立生成参考图、可重复引用的
 
 人物在同一连续场内需要多份视觉参考时，先绑定第一份引用，再用 `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)。
 
-## 先定目标：作用在哪份剧本上
+## 先定本地文件
 
-除 `ingest`/`view`/`publish` 外，每条读写命令都要知道读写哪份剧本，从下面选一个（互斥）：
-
-| 目标 | flag | 用在 |
-|---|---|---|
-| **项目 DB（最终剧本）** | `--remote [--project-group-no <no>]` | ☁️ **沙箱首选**。每次写进 DB 新 revision，边写边入库 |
-| **本地文件** | `--script-path <file>` | 🖥️ **本地电脑首选**。直接读写这一个 JSON，无 store、无 revision。洗稿/对标/转绘、试验、离线全走它 |
-| 本地约定 store | `--local` | `SCRIPTCTL_OUTPUT_DIR` 下的约定 store |
-
-- ☁️ **沙箱里**：后端注入 `SANDBOX_PROJECT_GROUP_NO`,**裸命令自动指向该项目 DB**（自动 remote），无需任何 flag。
-- 🖥️ **本地电脑上**：几乎每条命令都带 `--script-path <file>`。下文示例为简洁常省略它，实际本地使用请补上。
-- **不给任何目标、又不在沙箱**：CLI 拒绝猜测并报 `SCRIPT_NO_TARGET`。选一个目标。
-- `--script-path`（本地文件）与 `--remote`/`--local`/`--project-group-no`（store）**互斥**，混用报 `TARGET_FLAG_CONFLICT`。
-- `--workspace-path <dir>` 只给 `ingest`/`view`/`publish`/`ingest status` 用，指 ingest 工作区，不是剧本目标。**不传就是 `<cwd>/workspace`**（默认值 `workspace` 相对当前目录解析）；要放别处就显式传 `--workspace-path <dir>`，`ingest` 会在结果里回显解析后的绝对路径。`view`/`publish`/`ingest status` 要传**同一个** workspace 路径。
+- 查询、`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，不访问网络。
+- `publish` 对已管理文件拉取最新 snapshot，以本地稿为准计算 diff 后严格 CAS PATCH；CAS 或网络失败会重拉、重算、重试。干净工作副本不访问网络。无 metadata 的文件只允许以 base revision 0 首次发布。
+- 所有写命令按文件加锁；外部编辑器在命令期间改文件也会在落盘前被检测并拒绝覆盖。
+- `--workspace-path` 仍只属于 `ingest` / `view` / `ingest status`；普通读写和 publish 用 `--script-path`。
 
 ### 两个 script.json：洗稿 / 对标 / 转绘
 
@@ -277,14 +271,13 @@ scriptctl view                                              # 生成 review.html
 scriptctl summary --script-path workspace/script.json      # 抽完后当普通剧本读/改（注意目标是本地文件）
 
 # 3) 入库：校验 v3 通过后写进目标 store
-scriptctl publish                                          # 沙箱：自动写项目 DB 新 revision
-scriptctl publish --local                                  # 本地：写 SCRIPTCTL_OUTPUT_DIR
+scriptctl publish --script-path workspace/script.json      # 首次发布或更新受管工作副本
 ```
 
 - 🔴 **ingest 不入库**——它只产出 `<workspace>/script.json`。**入库是 `publish` 这独立一步**（沙箱里转完必须 publish，否则后端/前端看不到剧本）。
-- 🔴 **workspace 路径**：不传 `--workspace-path` 默认 `<cwd>/workspace`；`ingest` 结果第一行回显解析后的绝对路径。**`view`/`publish`/`ingest status` 必须传同一个 `--workspace-path`**（或在同一 cwd 下裸跑），否则会指到别的目录、看不到刚抽的产物。
-- 抽取产物在该 workspace 下。抽完后可用所有读写动词加 `--script-path <workspace>/script.json` 精修，再 `publish`；或 publish 入库后再对 DB（remote）精修。
-- publish 冲突（`SCRIPT_REVISION_CONFLICT`）= DB 被别的 revision 改过，重新拉取再 publish。
+- 🔴 **workspace 路径**：不传 `--workspace-path` 默认 `<cwd>/workspace`；`ingest` 结果回显绝对路径。后续读写/publish 指向该目录下的 `script.json`。
+- 抽取后用所有本地动词精修，再 publish。若后续继续编辑远端版本，checkout 到本地再改，不直接对 DB 跑原子 op。
+- publish 使用 local-wins：远端 revision 变化时自动以最新 snapshot 为 base 重算 diff，最终远端内容与本地稿一致；不会做三方合并。
 
 ### `ingest status`：进度按真实文件判定
 

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

@@ -133,16 +133,18 @@ insert ep_001/scn_001 --type dialogue --content "欢迎光临。" --actor act_00
 
 ## 写到哪里去（落库）
 
-`create` 和所有编辑 verb 共用同一套目标解析，三选一：
+`create` 和所有编辑 verb 只写本地 `--script-path <file>`；省略时是
+`<cwd>/workspace/script.json`。远端剧本必须遵循：
 
-| 目标 | 怎么走 | 说明 |
-|---|---|---|
-| **本地文件** | `--script-path <file>` | 🖥️ **本地电脑首选**。直接读写这一个 JSON，无 store、无 revision。洗稿/对标/转绘、试验都走它 |
-| **DB（项目组）** | `--remote`（沙箱裸命令自动 remote），或 `--project-group-no <no>` | ☁️ **沙箱首选**。每个编辑 op 直接写进 DB 的新 revision，边写边入库 |
-| **本地约定 store** | `--local` | 写 `SCRIPTCTL_OUTPUT_DIR` 下的约定 store |
+```text
+checkout → 本地查询/原子编辑/do/patch → validate → publish
+```
 
-- 🖥️ **本地**：`scriptctl create --script-path new.json` 起本，之后每条编辑都带同一个 `--script-path new.json`；想入库时用 `scriptctl publish`（读某个 `workspace/script.json` 写 store）或直接对 DB 写。
-- ☁️ **沙箱**：直接对 DB 写（`create` → 编辑，不加 flag = 自动 remote），写完就在库里。想先本地攒好再入库，就 `create --script-path draft.json` → 全程 `--script-path draft.json` 编辑，最后把它放进 `workspace/` 用 `scriptctl publish` 入库。
+- 已有远端剧本先 `scriptctl checkout --script-path draft.json`。
+- 全程对同一个 `draft.json` 编辑。新增原子能力只需实现本地操作，不增加远端业务 API。
+- `scriptctl status --script-path draft.json` 查看是否 dirty。
+- `scriptctl publish --script-path draft.json` 拉最新 snapshot 后以本地稿为准生成 patch；CAS/网络失败会重拉重试，最终远端内容与本地稿一致。
+- 本地新剧可直接 create/ingest 后首次 publish；没有 working-copy metadata 时只尝试从 revision 0 创建。
 
 ### 两份 script.json（洗稿 / 对标 / 转绘）
 

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

@@ -21,7 +21,7 @@ scriptctl ingest --source-path uploads/正片/
 ```
 
 常用 flag：
-- `--workspace-path <dir>`：工作区根（manifest + 各 pass 目录 + 产物）。**不传默认 `<cwd>/workspace`**；显式传可放别处，`ingest` 结果第一行回显解析后的绝对路径。🔴 `view`/`publish`/`ingest status` 要传**同一个**路径（或同 cwd 裸跑）。
+- `--workspace-path <dir>`：工作区根（manifest + 各 pass 目录 + 产物）。**不传默认 `<cwd>/workspace`**；显式传可放别处。`view` / `ingest status` 使用同一 workspace；publish 用 `--script-path <workspace>/script.json`。
 - `--concurrency <n>`：文本/归并 fanout 并发（文本默认 80，视频默认 30）。
 - `--video-concurrency <n>`：视频上传+转录并发。默认 10。
 - `--fps <n>`：视频采样帧率（>1 解锁亚秒级时间码）。默认 3。
@@ -79,27 +79,26 @@ scriptctl summary --script-path workspace/script.json   # 抽完当普通剧本
 ## 五、入库 `publish`
 
 ```bash
-scriptctl publish                 # 沙箱：自动写项目 DB 新 revision（SANDBOX_PROJECT_GROUP_NO 已注入）
-scriptctl publish --local         # 本地：写 SCRIPTCTL_OUTPUT_DIR
-scriptctl publish --remote --project-group-no 123   # 显式指定项目组
+scriptctl publish --script-path workspace/script.json
+scriptctl publish --script-path workspace/script.json --project-group-no 123
 ```
 
-- `publish` 读 `workspace/script.json`，**再跑一遍 v3 校验**，通过才写 store。
+- `publish` 读本地 `--script-path`（默认 `workspace/script.json`），**再跑一遍 v3 校验**，通过才发布。
 - 沙箱里转完**必须 publish**，否则后端/前端看不到剧本。
-- `SCRIPT_REVISION_CONFLICT` = DB 被别的 revision 改过：重新拉取当前剧本、合并你的改动，再 publish。
-- publish 幂等：同一份 script 重复 publish 不会产生新 revision（按内容 sha 去重）。
+- 已管理工作副本 publish 采用 local-wins：CAS/网络失败后重拉 snapshot、重算 diff 并重试，最终远端内容以本地稿为准。
+- 已管理且内容未变时 publish 本地直接 no-op，不发网络请求。服务端不保存 requestId，也不提供 publish 幂等重试。
 
 ## 六、复杂场景怎么接
 
 - **转完先精修再入库**：`ingest` → 用 `--script-path workspace/script.json` 跑读写动词修（改归属、并角色、标龙套、补造型……）→ `publish`。
-- **入库后再改**：`publish` 之后直接对 DB（沙箱裸命令 = remote）继续精修，每次改都是新 revision。
+- **入库后再改**：继续编辑同一个受管本地文件再 publish；若工作副本不在，先 checkout，不能直接对 DB 跑原子命令。
 - **视频复核**：`view` 出的 `review.html` 视频版支持点击台词跳到对应画面时间码，逐场核对发声源/造型。
 - **超大剧集（几十集）**：并发默认已调好；失败就重跑到 `ingest status` 显示 `ready`。花名册归并只跑一次并复用，重跑很快。
 - **归并质量**：跨集角色归并靠文字锚点，相似角色可能误合/合过头。用 `roster.review.md`（视频）核对归并决策；发现误合，入库后用 `merge` 拆分/改名修正。
 
 ## 七、抽完后的读写
 
-抽取产物就是标准 v3 剧本，用 SKILL.md 里所有读写能力精修（目标记得指 `--script-path workspace/script.json`，或 publish 后指 DB）：
+抽取产物就是标准 v3 剧本，用 SKILL.md 里所有读写能力精修（目标指 `--script-path workspace/script.json`；远端稿先 checkout）：
 - `summary` / `episodes` 看整本 + 分集梗概；`actions --in <ep>` 带 timestamp 看节奏。
 - `states <actor>` 看造型弧线；`actors --counts` 看出场频次决定 `importance`。
 - 归属/造型修正：`dialogue <at> --actor/--kind`、`scene-ref <ep/scn> <kind:id> --state`。