@lingjingai/scriptctl 0.71.0 → 0.72.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lingjingai/scriptctl",
-  "version": "0.71.0",
+  "version": "0.72.1",
   "description": "剧本阶段统一 CLI：素材转 Script v4，并兼容 Script v3 的本地写作、精修、校验和发布。",
   "type": "module",
   "bin": {
@@ -22,6 +22,20 @@
   "engines": {
     "node": ">=22.22.0"
   },
+  "scripts": {
+    "build": "pnpm run clean && pnpm --filter @lingjingai/screenplay build && pnpm --filter @lingjingai/review-agent build && tsc && node scripts/bundle.mjs",
+    "clean": "rm -rf dist packages/screenplay/dist packages/review-agent/dist",
+    "postinstall": "node scripts/install-skill.mjs",
+    "install-skill": "node scripts/install-skill.mjs",
+    "prepublishOnly": "pnpm run build",
+    "pretest": "pnpm run build",
+    "test": "vitest run",
+    "pretest:coverage": "pnpm run build",
+    "test:coverage": "c8 --reporter=text --reporter=html --reporter=lcov --report-dir=coverage vitest run",
+    "test:watch": "vitest",
+    "typecheck": "tsc --noEmit",
+    "surface:snapshot": "node scripts/scriptctl-surface-snapshot.mjs"
+  },
   "dependencies": {
     "@anthropic-ai/sdk": "^0.111.0",
     "@google/genai": "^2.11.0",
@@ -39,8 +53,8 @@
     "zod": "^4.5.4"
   },
   "devDependencies": {
-    "@lingjingai/review-agent": "0.1.0",
-    "@lingjingai/screenplay": "0.1.0",
+    "@lingjingai/review-agent": "workspace:*",
+    "@lingjingai/screenplay": "workspace:*",
     "@types/jsdom": "^30.0.0",
     "@types/node": "^20.14.0",
     "@types/proper-lockfile": "^4.1.4",
@@ -68,18 +82,5 @@
     "@ai-sdk/openai-compatible": "^3.0.48",
     "@ai-sdk/provider": "^4.0.4",
     "@mastra/core": "^1.64.0"
-  },
-  "scripts": {
-    "build": "pnpm run clean && pnpm --filter @lingjingai/screenplay build && pnpm --filter @lingjingai/review-agent build && tsc && node scripts/bundle.mjs",
-    "clean": "rm -rf dist packages/screenplay/dist packages/review-agent/dist",
-    "postinstall": "node scripts/install-skill.mjs",
-    "install-skill": "node scripts/install-skill.mjs",
-    "pretest": "pnpm run build",
-    "test": "vitest run",
-    "pretest:coverage": "pnpm run build",
-    "test:coverage": "c8 --reporter=text --reporter=html --reporter=lcov --report-dir=coverage vitest run",
-    "test:watch": "vitest",
-    "typecheck": "tsc --noEmit",
-    "surface:snapshot": "node scripts/scriptctl-surface-snapshot.mjs"
   }
-}
+}

package/skills/scriptctl/SKILL.md

@@ -227,7 +227,7 @@ scriptctl checkout / status / publish         # 远端工作副本
 GrsAI 使用 `GRSAI_API_KEY` 和 base64 视频，每个型号最多尝试 3 次；未配置密钥或主渠道已为该 GrsAI 地址时跳过此段。
 主渠道视频上传失败时，也从 GrsAI 开始使用本地视频继续请求。
 主渠道 Gemini 按 provider 的 `maxAttempts` 重试暂时性错误，豆包最多尝试 3 次；明确拒绝时换模型，用户取消时停止。
-豆包 Seed 2.1 Turbo 使用 BytePlus Ark，读取 `DOUBAO_TURBO_API_KEY`；`DOUBAO_TURBO_MODEL` 可指定端点，默认 `ep-20261028172514-tlxzc`。
+豆包后备路由先使用火山 Seed 2.1 Lite（`https://ark.cn-beijing.volces.com/api/v3`），读取 `ARK_API_KEY`；`DOUBAO_LITE_MODEL` 可指定端点，默认 `ep-20261029164743-gt8dh`。Lite 失败后使用 BytePlus Seed 2.1 Turbo，读取 `DOUBAO_TURBO_API_KEY`；`DOUBAO_TURBO_MODEL` 可指定端点，默认 `ep-20261028172514-tlxzc`。缺少对应密钥时跳过该路。
 已完成集和跨集 context 保留，同 source、同 workspace 重跑会从失败集续接。
 
 有原视频的 `review --review-strategy batch` 启用可选联合审核：豆包 Flash ASR → Gemini 对比 → Mastra 联合核对校时与内容 → 落盘。`--concurrency` 控制整集流程并发，默认 5；需要 `SD_AUDIO_APIKEY`、ffmpeg 和按集对应的视频。Agent 一次收到本集完整正文、相关人物状态卡、相邻集梗概与尚未写入的 ASR 建议，用 `read_many` 集中补读，`apply_changes` 一起修正关联字段并返回最终回读和校验，`record_findings` 记录实质结论。已核实的词级时间保留原精度；出现原音与整集 ASR 的具体冲突时，`asr_window` 对至多 15 秒的声音重识别并返回本集绝对句/词时间，共用媒体核验预算。画面约数用于判断内容和先后，证据矛盾保留原文并记录 unresolved。单集失败保留已执行修改，其他集继续。默认 `legacy` 使用先写入 ASR 时间、再逐项审核的流程。批量方式的成本随上下文、缓存与取证次数变化；证据冲突和重要分段边界需人工复核后验收。
@@ -240,9 +240,9 @@ ASR 返回有效语句后，程序将整集对白与心声按顺序拼接，与
 
 `.review/asr/episode-N/` 保存成功 ASR 缓存及每次对比的正文、原始响应、前后时间与缺漏报告。源视频经 ffprobe 确认无音轨时，发出 `asr-skipped`（`reason=source_no_audio`），保留台词与时间并继续画面审核；分集结果保留“ASR 校时未执行”的未解决项，说明无法核验实际发声时间、漏词或无字幕画外音。探测、解码及服务错误仍作为失败集处理。`asr-compared` 仅表示对比完成，带 `episode_number` 的 `asr-applied` 表示本集校时已落盘，不等于 Agent 审核完成。`--episodes` 只重跑指定集的 ASR 和审核，`--converge-only` 只做全剧收敛。纯剧本和原文对照审核不执行 ASR；`--check` 不发模型请求。
 
-视频和纯剧本审核使用 `review-agent`，文本和漫画使用 `review-text`、`review-comic`；主 Agent 每次请求按 MSUICODE Vertex → GCP → T3 → 兔子 → 豆包 Seed 2.1 Turbo 的顺序调用，Gemini 渠道均为 `gemini-3.8-flash`。MSUICODE 地址为 `http://15.204.107.123:3000`，分别读取 `MSUICODE_VERTEX_API_KEY`、`MSUICODE_GCP_API_KEY`、`MSUICODE_T3_API_KEY`；兔子读取 `TUZI_API_KEY`，豆包读取 `DOUBAO_TURBO_API_KEY`。主渠道密钥必需，额外渠道仅在配置对应密钥时参与。普通服务错误按顺序切换；Gemini 明确内容拦截时，当前这一步跳过剩余 Gemini 渠道交给豆包，下一步重新从首选渠道开始。各模型沿用 provider 的 `maxAttempts`，内置最多三次。切换保留成功的工具操作，用量记录实际渠道和模型，Gemini 思考签名只在生成它的渠道内复用。逐集与全剧审核都要求成功调用 `validate` 后才结束。自定义 profile 使用声明的 `fallbacks` 顺序。`--no-fallback` 或 `SCRIPTCTL_REVIEW_SINGLE_MODEL=1` 仅使用选定模型。
+视频和纯剧本审核使用 `review-agent`，文本和漫画使用 `review-text`、`review-comic`；主 Agent 每次请求按 MSUICODE Vertex → GCP → T3 → 兔子 → 豆包 Seed 2.1 Lite → Turbo 的顺序调用，Gemini 渠道均为 `gemini-3.8-flash`。MSUICODE 地址为 `http://15.204.107.123:3000`，分别读取 `MSUICODE_VERTEX_API_KEY`、`MSUICODE_GCP_API_KEY`、`MSUICODE_T3_API_KEY`；兔子读取 `TUZI_API_KEY`，Lite 读取 `ARK_API_KEY`，Turbo 读取 `DOUBAO_TURBO_API_KEY`。主渠道密钥必需，额外渠道仅在配置对应密钥时参与。普通服务错误按顺序切换；Gemini 明确内容拦截时，当前这一步跳过剩余 Gemini 渠道交给豆包，下一步重新从首选渠道开始。各模型沿用 provider 的 `maxAttempts`，内置最多三次。切换保留成功的工具操作，用量记录实际渠道和模型，Gemini 思考签名只在生成它的渠道内复用。逐集与全剧审核都要求成功调用 `validate` 后才结束。自定义 profile 使用声明的 `fallbacks` 顺序。`--no-fallback` 或 `SCRIPTCTL_REVIEW_SINGLE_MODEL=1` 仅使用选定模型。
 
-独立的 ASR JSON 比对和原片视频核验使用 `review-media`：NNYYAI Gemini 3.8 → 3.7 → 3.6 Flash → 豆包，凭据为 `NNYYAI_API_KEY`、`DOUBAO_TURBO_API_KEY`，`DOUBAO_TURBO_MODEL` 可指定豆包端点。显式 `--model` 或自定义配置仍决定媒体主渠道。豆包 Flash ASR 继续读取 `SD_AUDIO_APIKEY`。
+独立的 ASR JSON 比对和原片视频核验使用 `review-media`：NNYYAI Gemini 3.8 → 3.7 → 3.6 Flash → 豆包 Seed 2.1 Lite → Turbo，凭据分别为 `NNYYAI_API_KEY`、`ARK_API_KEY`、`DOUBAO_TURBO_API_KEY`；`DOUBAO_LITE_MODEL`、`DOUBAO_TURBO_MODEL` 可覆盖对应豆包端点。显式 `--model` 或自定义配置仍决定媒体主渠道。豆包 Flash ASR 继续读取 `SD_AUDIO_APIKEY`。
 
 全剧收敛审核必须成功执行 `validate` 才能正常结束；未完成时在同一会话内继续，保留已有工具操作，并共用原步数和总时间预算。整集默认 15 分钟总时限，耗尽后结束本轮审核。
 
@@ -260,7 +260,15 @@ agent 并直接改文件。
 
 漫画 Agent 使用原页及局部图片逐页检查遗漏，再对照 action 核对正文、说话人、心声类别、顺序和来源。需要 `pdftoppm`；图片在 `review-pages/`，结果在 `.review/comic/episode-N.json` 和 `global.json`。新增 action 同时写来源，跨页引用保留全部页与区域。`viewed_pages` 只记录图片已加载；未看完整页集会留下 unresolved，不能据此宣称整话通过。漫画不生成时间戳，不执行 ASR；运行由 `--max-steps` 和 `--episode-timeout-ms` 限制。视频保留原有 ASR、校时和媒体预算流程。
 
-换壳仿写使用 `reskin`，命令通过 NDJSON 报告进度并保留已完成单元。流程为 `reskin analyze` 拆解、`reskin direction` 选择新壳、`reskin plan` 逐层设计、`reskin write --review-model <profile>` 逐集写作与审核、`reskin review --converge-only` 全剧收尾。写作在每个阶段内按集序执行，阶段之间并行；每集审核完成后，将累积事实账本交给下一集。全剧收尾检查阶段接缝，并由独立上下文通读实际成稿；发现方案层问题时回改方案、复查受影响正文，再读取修复结果。各命令通过 `--model` 选择 profile，写作通过 `--review-model` 指定审核 profile。原剧、拆解、方案和新剧路径分别显式传入 `-p`、`--source`、`--analysis`、`--plan` 等对应参数；用各子命令的 `--help` 查看完整调用。`reskin batch` 按清单逐部运行并保存进度和成本报告。
+换壳仿写使用 `reskin`，命令通过 NDJSON 报告进度并保留已完成单元。流程为 `reskin analyze` 拆解、`reskin direction` 选择新壳、`reskin plan` 逐层设计（最后两层是全剧故事时间线和按时间线设计的人物造型）、`reskin write --review-model <profile>` 逐集写作与审核（场景时段和造型按时间线绑定）、`reskin review --converge-only` 全剧收尾。写作在每个阶段内按集序执行，阶段之间并行；每集审核完成后，将累积事实账本交给下一集。全剧收尾检查阶段接缝，并由独立上下文通读实际成稿；发现方案层问题时回改方案、复查受影响正文，再读取修复结果。各命令通过 `--model` 选择 profile，写作通过 `--review-model` 指定审核 profile。原剧、拆解、方案和新剧路径分别显式传入 `-p`、`--source`、`--analysis`、`--plan` 等对应参数；用各子命令的 `--help` 查看完整调用。`reskin batch` 按清单逐部运行并保存进度和成本报告。
+
+换壳各步的模型请求按 profile 及其 `fallbacks` 的顺序走渠道，最后是豆包：配置里已有 openai-compatible 的豆包渠道（provider `doubao`、`ark` 或 `ark-lite`）时只用它，否则依次加内置的豆包 Lite（设置 `ARK_API_KEY` 时）和 Turbo。一个渠道用完自己的重试后因传输错误失败（超时、HTTP 408/429/5xx、连接错误），本进程的所有 Agent 在 `SCRIPTCTL_ROUTE_COOLDOWN_MS`（默认 600000，即 10 分钟）内跳过它，从下一个渠道开始，到期后再试；内容拦截、其他拒绝和取消不触发冷却，剩下的最后一个可用渠道照常请求。请求每离开一个渠道，NDJSON 流里发一条 `route-failover`（`reskin batch` 写进各步日志）：
+
+```json
+{"type":"route-failover","agent":"write-ep3","from":"nnyyai/gemini-3.8-flash","to":"msuicode-vertex/gemini-3.8-flash","reason":"timeout","blocked":false,"message":"..."}
+```
+
+`from` / `to` 是 `<provider>/<model>`，`agent` 是发请求的单元。`blocked: true` 表示 Gemini 内容拦截：`reason` 是拦截原因（如 `PROHIBITED_CONTENT`、`SAFETY`），`to` 是跳过其余 Gemini 渠道后的第一个非 Gemini 渠道（豆包）。`reason: "cooldown"` 表示 `from` 正在冷却、本次没有请求它。其余 `reason` 是 `from` 这次失败的原因：`timeout`、`http-<状态码>`、`network`、`error`（模型答复被拒，如格式错误或空答复），`message` 是错误原文（截到 300 字）。
 
 纯剧本使用独立的审核指令与剧本工具：检查内部结构、引用和设定冲突，不要求时间戳；需要外部事实才能判定的内容保持 unresolved。`review --check` 的 `review_kind` 明确本次选择 script / text / comic / video。
 

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

@@ -29,7 +29,7 @@ scriptctl ingest -s 漫画目录/ -w workspace
 
 支持单话 PDF、多话合集及 PDF 目录。先分段阅读原稿并识别实际章节，再按话连续转录；内部 episode 按阅读顺序编号，来源文件和原稿页范围保留在 manifest。章节识别结果保存在 workspace/sources，续跑复用。
 逐话维护人物身份、持续造型和剧情上下文。`--step` 只接受下一话，同源同工作区重跑从失败话续接，支持尾部追加。
-模型通过 `ingest.comic-serial` 路由配置，内置为 NNYYAI `gemini-3.8-flash`（`NNYYAI_API_KEY`），通过 base64 直接提交 PDF 并使用 `responseSchema`。失败后在同一 NNYYAI 渠道按 3.8 / 3.7 / 3.6 Flash 补齐未尝试模型，最后使用豆包 PDF 理解（`DOUBAO_TURBO_API_KEY`、可选 `DOUBAO_TURBO_MODEL`）。自定义 PDF provider 可设置 `documentUploadMode`（`file-api` / `base64`）和 `documentResponseSchemaField`（`responseJsonSchema` / `responseSchema`）。模型切换保留同一 PDF 与 Schema，用户取消立即停止，实际模型与用量进入账本。合集识别按页数和体积分段提交。模型输入副本 `ep/*.input.pdf` 带坐标网格，帮助定位长条页内区域；原 PDF 和审阅图保持原样。
+模型通过 `ingest.comic-serial` 路由配置，内置为 NNYYAI `gemini-3.8-flash`（`NNYYAI_API_KEY`），通过 base64 直接提交 PDF 并使用 `responseSchema`。失败后在同一 NNYYAI 渠道按 3.8 / 3.7 / 3.6 Flash 补齐未尝试模型，随后依次使用豆包 Lite、Turbo PDF 理解（密钥分别为 `ARK_API_KEY`、`DOUBAO_TURBO_API_KEY`，可选端点覆盖分别为 `DOUBAO_LITE_MODEL`、`DOUBAO_TURBO_MODEL`）；缺少对应密钥时跳过该路。自定义 PDF provider 可设置 `documentUploadMode`（`file-api` / `base64`）和 `documentResponseSchemaField`（`responseJsonSchema` / `responseSchema`）。模型切换保留同一 PDF 与 Schema，用户取消立即停止，实际模型与用量进入账本。合集识别按页数和体积分段提交。模型输入副本 `ep/*.input.pdf` 带坐标网格，帮助定位长条页内区域；原 PDF 和审阅图保持原样。
 资产引用缺失时，结合原稿和已生成正文补齐登记，保留转录正文；同源续跑可继续处理已保存的响应。
 每条 action 用 `extend.scriptctl.source` 保存 `document_id`、`pages` 和 `regions`。多话合集的页码以对应章节 PDF 为准，manifest 的 start_page/end_page 对应原文件页范围。每个 region 包含物理页码 `page`、区域类型 `kind`（`panel` / `bubble` / `text`）及 `box`（`top/left/bottom/right`，相对完整物理页归一化为 0–1000）。分离的画格和跨页气泡可关联多个区域。
 对白、心声和画面文字保留原文；动作叙述使用简体中文。页码覆盖和 Script 校验通过后才接受本话，仍需对照原页抽查漏格、说话人及小字。
@@ -105,7 +105,7 @@ scriptctl ingest -s uploads/正片/ -w workspaces/正片 \
 - 自定义 Gemini 主渠道先使用配置的主模型，再按 `gemini-3.8-flash → gemini-3.7-flash → gemini-3.6-flash` 在同渠道尝试尚未调用的模型，保留主渠道的服务地址、凭据和模型名前缀。每个模型按 provider 的 `maxAttempts` 重试暂时性错误；明确拒绝时直接换模型，用户取消时立即停止。
 - 视频的主渠道模型耗尽后，依次尝试 GrsAI（`https://grsai.dakka.com.cn`）的 `gemini-3.8-flash → gemini-3.7-flash → gemini-3.6-flash`，再进入豆包。GrsAI 使用独立的 `GRSAI_API_KEY`、base64 视频和 `responseSchema`，每个型号最多尝试 3 次；未配置密钥或主渠道已为该 GrsAI 地址时跳过此段。视频 CLI 的地址、凭据和模型覆盖只作用于主渠道。
 - 视频在主渠道的模型间复用媒体；切到普通 NNYYAI 或 GrsAI 时复用 base64 内容，或从本地转码文件读取内容。次卡 Files API 上传失败时，从普通 NNYYAI 开始继续请求；自定义主渠道上传失败时从 GrsAI 开始。豆包重新上传同一本地视频。默认路由与显式 Gemini provider/model 覆盖均使用该链；直接选择豆包时只调用豆包。
-- 豆包 Seed 2.1 Turbo 使用 BytePlus Ark `https://ark.ap-southeast.bytepluses.com/api/v3` 和 `DOUBAO_TURBO_API_KEY`，最多尝试 3 次；`DOUBAO_TURBO_MODEL` 可指定端点，默认 `ep-20261028172514-tlxzc`。文本、结构化工具和 PDF 请求在主渠道 Gemini 型号耗尽后进入豆包。
+- 豆包后备路由先使用火山 Seed 2.1 Lite（`https://ark.cn-beijing.volces.com/api/v3`、`ARK_API_KEY`），默认端点 `ep-20261029164743-gt8dh`，可用 `DOUBAO_LITE_MODEL` 覆盖；失败后使用 BytePlus Seed 2.1 Turbo。各路最多尝试 3 次，缺少对应密钥则跳过。Turbo 使用 `https://ark.ap-southeast.bytepluses.com/api/v3` 和 `DOUBAO_TURBO_API_KEY`；`DOUBAO_TURBO_MODEL` 可指定端点，默认 `ep-20261028172514-tlxzc`。文本、结构化工具和 PDF 请求在主渠道 Gemini 型号耗尽后进入豆包。
 - `--provider-base-url` 指向 Gemini Developer API 兼容的服务根地址；`file-api` 模式要求该服务同时兼容 Files API。
 
 常用 flag：