@lingjingai/scriptctl 0.33.0 → 0.35.0

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

@@ -0,0 +1,72 @@
+# direct workflow — 已有素材直转
+
+适用：已有完整剧本 / 分镜（docx / pdf / xlsx / md / json）需要结构化入库。
+
+## 流程
+
+```
+direct init <file> → direct review → [<edit verb> --draft / patch --draft] → direct validate → direct export
+```
+
+| 步骤 | 命令 | 说明 |
+|---|---|---|
+| 1. 解析 | `scriptctl direct init --source-path <file>` | 把素材切批、抽取到 `script.initial.json` |
+| 2. 检查 | `scriptctl direct review`（总览）/ `scriptctl direct review --episode 1,15,30`（源文↔抽取对照） | 无参看 curation 决策 + issues（含 batch 抽取失败）；带 `--episode` 看按集对照视图 |
+| 3. 修中间稿 | `scriptctl <verb> ... --draft` 单点改，或 `scriptctl patch <file> --draft` 批量 | 加 `--draft` 即指向 `script.initial.json`，不用写路径。改 type / actor / 命名 / 状态等 |
+| 4. 校验 | `scriptctl direct validate` | 跑结构校验 |
+| 5. 入库 | `scriptctl direct export` | 落最终剧本到 DB（只卡 validation passed） |
+
+> 编辑 / 查询中间稿：所有顶层 verb（`replace` / `rename` / `actions` / `episodes` / `patch` / ...）都认 `--draft`。例如 `scriptctl actions --in ep_001 --draft`、`scriptctl rename actor:act_001 "陈墨" --draft`。
+
+## 梗概产物
+
+direct 流程完成后，最终剧本会带有整本和分集梗概。查看方式：
+
+- `scriptctl summary`：看整本 synopsis / theme / logline / style / main_characters
+- `scriptctl episodes`：看每集 synopsis
+
+## 状态 / 续跑 / 重跑（关键）
+
+init **可续跑**：已成功的批次跳过（看结果文件在不在），失败的批次留下错误标记、**默认不自动重试**（避免内容过滤这类硬失败无限重打）。状态全部从磁盘派生 —— 清掉 `run_state.json` 也不丢，重跑只会动你点名的集 / 批次，绝不碰其它集。
+
+| 想做什么 | 命令 |
+|---|---|
+| 看每集状态（done / ERROR / pending，错误集标出原因 + 批次 key） | `scriptctl direct status` |
+| 续跑（只补从没跑过的批次） | `scriptctl direct init --source-path <file>`（同参数再跑一次） |
+| 只重跑某集 | `scriptctl direct init ... --episodes 27` |
+| 只重跑某些批次 | `scriptctl direct init ... --batches bat_0063,bat_0065` |
+| 重跑所有错误批次 | `scriptctl direct init ... --retry-errors` |
+| 全部重来 | `scriptctl direct init ... --all` |
+
+某集持续 error（典型：内容过滤 `PROVIDER_CONTENT_FILTERED`）的标准处理：`direct status` 定位 → `--episodes <N>` 重跑；仍失败就软化源文本对应那一段再 `--episodes <N>`，或先入库其余集、在最终剧本里用 patch 工具补这一集。🔴 **不要清 `run_state.json` 或手工往 `batch_results/` 塞文件** —— 用 `direct status` + 选择性重跑即可，错误批次默认粘性不会被自动重试。
+
+## export 前的质量自查（强烈建议，非强制）
+
+`direct export` 只卡 validation —— passed 就能导出，没有 review 签字闸门。但抽取质量靠 validation 兜不住（它只看结构），导出前**强烈建议**自己走一遍：
+
+1. `direct review`：把 issues 清零（结构性问题 + batch 抽取失败），看 curation 决策是否合理
+2. 抽样 ≥3 集（开头 / 中段 / 结尾；双语 / 特殊场次必查）跑 `direct review --episode <N>` 做下面的语义 checklist
+
+## review checklist
+
+**对白 / 动作**
+- 双语 / gloss / 旁注没被错抽进 content
+- 角色注解前缀（`Sloane(画外音):` 这类）没被当 content
+- 字幕 / 音效 / 屏幕字归 `type=action`；系统 / 广播 / 道具发声归 dialogue + speaker
+- dialogue / inner_thought / action 三型分得对
+- 没漏抽 / 没拆碎 / 没合并对白
+- emotion 进 emotion 字段，不进 content
+
+**场景 / 角色**
+- 场景顺序、每场角色与原文一致
+- location_name / location_state 与原文场号标题对应
+
+**资产**
+- actors / locations / props 是跨场景可复用的生产资产；单场临时物留在 action 文本
+- 名字是规范实体名（不夹括号 / 状态 / 情绪 / 身份注解）
+- 群体词（众人 / 群众 / 围观者）不进 actors
+- description 不能 LLM 凭空编造
+
+## 阈值
+
+抽样集每集 ≤1 问题 → `--draft` 改掉后即可 export；≥2 个 → `scriptctl direct init --episodes <N>` 重跑该集（或 `--batches <key>` 重跑具体批次）。

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

@@ -0,0 +1,72 @@
+# State 引用修复核验
+
+适用：合并 state、删除 state，或修 `STATE_NOT_FOUND` / 状态引用错连。重点不是只改 `states[]`，而是确认引用该状态的场和动作都被修好。
+
+## 操作语义
+
+scriptctl 没有单独的 `state-merge` 命令；合并 state 用“删除旧 state 并替换引用”表达：
+
+```bash
+scriptctl delete actor:act_001/st_old --strategy replace --replacement st_keep
+```
+
+删除且不保留引用：
+
+```bash
+scriptctl delete actor:act_001/st_old --strategy remove
+```
+
+等价别名：`state-delete actor:act_001/st_old --strategy ...`。
+
+## 必查流程
+
+1. 操作前反查旧 state：
+
+```bash
+scriptctl refs actor:act_001/st_old
+```
+
+输出里 `scene_initial_state` 是场景 context 引用，形如 `ep_001/scn_003.context.actors[0]`；`state_change_from` / `state_change_to` 是 action 的 `state_changes` 引用。
+
+2. 合并时用 `replace`，不要先裸删 state：
+
+```bash
+scriptctl delete actor:act_001/st_old --strategy replace --replacement st_keep
+```
+
+期望结果：
+- `scriptctl refs actor:act_001/st_old` 为空。
+- `scriptctl refs actor:act_001/st_keep` 包含原来应该保留的场景初始状态和 action 状态变化引用。
+- `scriptctl validate` 通过。
+
+3. 真删除时用 `remove`：
+
+```bash
+scriptctl delete actor:act_001/st_old --strategy remove
+```
+
+期望结果：
+- 场景 context 中引用该 state 的 ref 被保留，但 `state_id` 变成 `null`。
+- 涉及该 state 的 action `state_changes` 被移除，避免留下半截 from/to。
+- `scriptctl refs actor:act_001/st_old` 为空，`scriptctl validate` 通过。
+
+4. 如果只想清某场的初始状态，不要删 state：
+
+```bash
+scriptctl context ep_001/scn_003 actor:act_001 --clear
+```
+
+如果要移除该角色在某场的引用：
+
+```bash
+scriptctl context ep_001/scn_003 actor:act_001 --remove
+```
+
+## 状态引用散在两层
+
+改状态引用时两层都要覆盖，`replace`/`remove` 会自动处理，核验时也按这两层看：
+
+- 场景初始状态：`scene.context.{actors|locations|props}[].state_id`。
+- 动作状态变化：`action.state_changes[].from_state_id` / `to_state_id`。
+
+`replace` 把两层里指向旧 state 的引用全改成 replacement 再删旧定义；`remove` 把 context ref 的 `state_id` 清成 `null` 并删掉碰到旧 state 的 action state_changes。replacement 只能是**同一资产**上已存在的 state_id。改完用 `scriptctl refs actor:<id>/<st>` 复查为空、`scriptctl validate` 通过。