@lingjingai/scriptctl 0.63.19 → 0.64.0

package/README.md

@@ -1,6 +1,6 @@
 # @lingjingai/scriptctl
 
-剧本阶段统一 CLI：把 txt/md/docx 或视频素材转为结构化 Script v4，同时继续原样读写和发布线上 Script v3；在本地工作副本上查询、校验、完整块批量写作或原子精修，并通过 revision CAS 发布。
+剧本阶段统一 CLI：把 txt/md/docx、视频或 PDF 漫画素材转为结构化 Script v4，同时继续原样读写和发布线上 Script v3；在本地工作副本上查询、校验、完整块批量写作或原子精修，并通过 revision CAS 发布。
 
 ## 安装
 
@@ -45,6 +45,31 @@ Script v4 的新节点使用类型前缀加 6 位 Bitcoin Base58 的 NanoID。
 1-based `@` 序号定位，修改使用查询返回的正式 ID。已有 Script v3 按显式
 `version: 3` 继续走原有查询、写入、authoring 和 publish 实现，不改写旧 ID。
 
+## 剧本审核的证据类型
+
+`scriptctl review` 按本次提供的原稿选择审核方式。没有 `-s` 时仅做剧本内部一致性检查，不因剧本来自 ingest 就声称核对过原稿。审核包含证据支持的修复，修改在逐集结果事件发出前保存。
+
+| 输入 | 审核方式 | 默认 profile |
+|---|---|---|
+| 仅 `-p script.json` | 内部结构、引用、人物与状态的一致性 | `review-agent` |
+| `-s` 文本 ingest 工作区或对应 txt/md/docx | 原文行窗口、遗漏、说话人、心声类型和语义忠实度 | `review-text` |
+| `-s` 漫画 ingest 工作区或对应 PDF | 原页、画格、气泡与正文对照 | `review-comic` |
+| `-s` 视频/分集目录或完整 `--video` 列表 | 原声、画面、ASR 与时间轴 | `review-agent` |
+
+纯剧本使用独立 prompt 和工具，不要求时间戳，不生成缺失剧情；遇到无法判定哪一版正确的设定矛盾时保留原文并报告未解决项。需要事实依据的警告不靠猜测补齐。
+
+## 原文审核
+
+`scriptctl review -p <workspace/script.json> -s <文本 ingest 工作区>` 读取 `pass1/source.txt`，使用 manifest 的 SHA-256 核实原文快照。也可以传对应的 `.txt`、`.md` 或 `.docx`，此时剧本旁需要完整 ingest 工作区；输入按 ingest 相同规则规范化并核对摘要。默认 `review-text` 使用现有官方 Gemini 渠道，`--model` 可选择已有 profile。
+
+文本 Agent 使用 `source` 定位 action 的候选原文窗口、`text_range` 读取带行号的原文、`search_source` 查找完整原稿。先读本集全部原文检查遗漏，再逐条反查 action。台词保留原文语言，动作允许忠实的简体中文转述；合法翻译、拆分和合并不作为错误。
+
+文本来源存于 `extend.scriptctl.source`，包含 `kind: "text"`、`document_id` 和 `ranges`。`start_line` / `end_line` 是**完整规范化原文的 1-based 闭区间**，包含前言偏移。ingest 保存的是 chunk 窗口，可能对应多条 action；它是定位线索，不是逐句精确标注。审核可依据实际原文缩小或修正窗口，新增 action 同时写入来源。
+
+既有 v4 产物通过 `v4_identity_map.json` 和 `pass1/body_start.json` 恢复来源，按稳定 ID 对应，不按当前行序或正文相似度猜测。保留这些文件以及 `manifest.json`、`pass1/source.txt`。缺失来源或摘要不符时停止，不转为纯剧本审核。
+
+`.review/text/episode-N.json` 与 `global.json` 保存 findings、用量和已读/未读行窗口；读取记录不代表内容正确。未读完本集原文会留下 unresolved。文本审核使用 `--episodes`、`--converge-only`、`--max-steps` 和 `--episode-timeout-ms`，不执行 ASR 或视频校时。
+
 ## 原视频审核的全剧 ASR 校时与补漏
 
 `scriptctl review -p <script.json> -s <视频目录>`（或按集排序的完整 `--video` 列表）逐集执行「豆包 Flash ASR → Gemini 对比 → 校时落盘 → Mastra 审核 → 落盘」。`--concurrency` 控制同时进行的整集流程，默认 **5 集并发**。需要 `ffmpeg` 和 `SD_AUDIO_APIKEY`；ASR 协议与 Redraw `subtitle_realign/asr.py` 一致，使用每集完整音轨，以本集 00:00 为原点。
@@ -61,7 +86,17 @@ Gemini 接收左侧带时间戳、行锚点的亚洲格式剧本正文，以及
 
 `asr-started` / `asr-transcribed` / `asr-compared` NDJSON 按集报告进度与证据；`asr-compared` 不代表修改已落盘，带 `episode_number` 的 `asr-applied` 表示本集校时已经保存。之后的 `episode` 报告本集完成或失败，已有修改已保存；`done.statistics.fixed` 包含自动校时条数，`usage_total` 汇总对比与审核 Gemini 用量。
 
-`--episodes` 只对所选集执行 ASR、校时和审核，适合失败集重试；`--converge-only` 只做全剧收敛。无视频的纯文本审核不执行 ASR；`--check` 只检查配置与 bundle，不发 ASR/Gemini 请求。服务失败不自动换模型或重提请求。
+`--episodes` 只对所选集执行 ASR、校时和审核，适合失败集重试；`--converge-only` 只做全剧收敛。纯剧本和原文对照审核不执行 ASR；`--check` 返回所选 `review_kind`，只检查配置与 bundle，不发 ASR/Gemini 请求。
+
+## 原漫画审核
+
+`scriptctl review -p <workspace/script.json> -s <漫画 ingest 工作区>` 对照原 PDF 逐话审核并修正。也可以把 `-s` 指向原 PDF 或 PDF 目录，此时 `manifest.json` 必须位于剧本旁。来源通过 `document_id` 和 manifest 中的 PDF SHA-256 匹配，不按文件名重新配话；文件移动或改名后可以显式传入内容相同的 PDF。`--episodes 1,3` 只要求所选话的来源可用。缺少 manifest、来源映射或原文件内容变化时停止并报错。
+
+漫画使用独立的 `review-comic` profile（默认 NNYYAI `gemini-3.8-flash`，`NNYYAI_API_KEY`），支持现有 Gemini 型号切换及已配置的豆包恢复路由，不进入官方 Google 渠道。自定义 LLM 配置需要定义该 profile，或用 `--model` 选择有显式服务地址的 profile。视频和纯剧本仍使用 `review-agent`。
+
+漫画 Agent 逐页看原稿并反向核对 action，使用 `source` 定位、`pages` 看完整原页、`region` 看清晰局部，核对遗漏、重复、文字、人物、心声类型及阅读顺序。需要 Poppler（`pdftoppm`）；局部图按显示页的 CropBox/旋转归一化坐标渲染。正文修改保留来源；插入遗漏内容必须同时提供 `extend.scriptctl.source` 页码及区域。跨页内容使用同一条 action 的多个来源区域，不添加时间戳。
+
+`.review/comic/episode-N.json` 保存逐话 findings、用量和原页加载记录，`global.json` 保存最后的全剧收敛结果。`viewed_pages` 仅表示整页图片已加载，不代表内容正确或小字已看清；未加载完全部页时报告未解决项。图片证据保存在剧本旁的 `review-pages/`。漫画不执行 ASR、校时或视频媒体预算；`--max-steps` 和 `--episode-timeout-ms` 限制审核运行。逐话结果在剧本与报告落盘后才发出，未提供 `-s` 仍是纯剧本审核。
 
 ## 退出码
 
@@ -80,6 +115,7 @@ Gemini 接收左侧带时间戳、行锚点的亚洲格式剧本正文，以及
 | `PROJECT_LITELLM_GATEWAY_API_KEY` | 内置 LLM 配置引用的 gateway key |
 | `PROJECT_LITELLM_GATEWAY_BASE_URL` | 内置配置的 gateway endpoint；OpenAI-compatible synopsis 必须配置 |
 | `SCRIPTCTL_LLM_CONFIG` | LLM 路由 YAML；优先级低于 `--llm-config` |
+| `NNYYAI_API_KEY` | 内置视频与漫画拉片 provider 的 API key |
 | `AWB_BASE_URL` | script-output gateway URL |
 | `LINGJING_AWB_ACCESS_KEY` | gateway 访问凭证 |
 | `SANDBOX_PROJECT_GROUP_NO` | 项目组号（也可用 `--project-group-no`） |
@@ -102,6 +138,30 @@ tasks:
   direct.episode-titles: default
 ```
 
+Gemini provider 可设置 `videoResponseSchemaField: responseSchema`，用于 GRSAI 等仅接受该字段的视频接口；默认仍为 `responseJsonSchema`。
+`responseSchema` 由 Google SDK 转换字段定义，保留类型、必填字段和描述，但不发送 `additionalProperties` 约束。
+
+内置 `ingest.video-serial` 与 `ingest.comic-serial` 使用 NNYYAI 的 `gemini-3.8-flash`（`https://api.nnyyai.com`），
+从 `NNYYAI_API_KEY` 读取密钥，使用 `responseSchema` 与 base64 视频或 PDF 输入。设置密钥后直接运行
+`scriptctl ingest -s <视频或PDF文件或目录> -w <workspace>`。Gemini 型号切换始终使用同一 NNYYAI 渠道；配置了 `ARK_API_KEY` 时保留豆包最终兜底。文本任务与 `review-agent` 保持原有路由。
+显式 LLM 配置仍完全按所选文件执行；GrsAI、Google Vertex 等 provider 可继续使用。
+
+Gemini provider 的 `videoUploadMode: base64` 可指定视频默认传输方式；未设置时为 `file-api`，
+显式 `--upload-mode` 优先于 provider 默认值。PDF 对应的配置为 `documentUploadMode` 和 `documentResponseSchemaField`，默认分别为 `file-api` 和 `responseJsonSchema`。自定义配置中的 NNYYAI provider 可写为：
+
+```yaml
+nnyyai:
+  protocol: google-gemini
+  baseUrl: https://api.nnyyai.com
+  apiKey: { env: NNYYAI_API_KEY }
+  timeoutMs: 600000
+  maxAttempts: 3
+  videoResponseSchemaField: responseSchema
+  videoUploadMode: base64
+  documentResponseSchemaField: responseSchema
+  documentUploadMode: base64
+```
+
 ## 开发
 
 ```bash

package/changes/0.63.20.md

@@ -0,0 +1,20 @@
+# 0.63.20
+
+## Added
+- Gemini PDF provider 支持 `documentUploadMode` 和 `documentResponseSchemaField`，分别配置 PDF 传输与输出 Schema 格式。
+- Gemini 视频 provider 支持 `videoUploadMode` 指定默认传输方式，命令行 `--upload-mode` 可覆盖。
+- Gemini 视频 provider 支持通过 `videoResponseSchemaField` 选择 `responseSchema`，适配 GRSAI 等渠道；默认渠道与 `responseJsonSchema` 行为不变。
+- `scriptctl ingest` automatically recognizes PDF comics and chapter directories, preserving reading order, page and region references and chapter titles in Script v4, with serial identity tracking, resumable checkpoints and `--step`.
+- `scriptctl view` renders comic PDF pages as local images alongside the screenplay, with clickable action cards that scroll to and highlight panels, bubbles or text regions, cross-page links and navigation back to the corresponding text. Page rendering requires Poppler (`pdftoppm`) and is cached by source content.
+
+## Changed
+- 内置漫画拉片使用 NNYYAI `gemini-3.8-flash`，通过 `NNYYAI_API_KEY` 认证，以 base64 传 PDF 并使用 `responseSchema`；Gemini 型号切换始终使用同一 NNYYAI 渠道。
+- 内置视频拉片使用 NNYYAI `gemini-3.8-flash`，通过 `NNYYAI_API_KEY` 认证并默认以 base64 传视频；文本和审核路由保持不变。
+
+## Fixed
+- Comic review images use the PDF CropBox to match panel and text coordinates, regenerating previously cached page images.
+- Comic ingest publishes chapters only after checkpoint acceptance and restores the accepted script and identity map before resuming after an interrupted write.
+- Comic PDF requests recover through the configured Gemini model, remaining Flash models and Doubao, preserving the original document, cancellation and per-model usage. Upload failures can continue with the same PDF bytes.
+
+## Breaking
+- None.

package/changes/0.64.0.md

@@ -0,0 +1,16 @@
+# 0.64.0
+
+## Added
+- `scriptctl review` supports source-grounded comic review from PDF ingest workspaces or original PDFs, with page/region evidence, source-preserving repairs, per-episode reports, and a dedicated NNYYAI `review-comic` profile.
+- `scriptctl review` supports original-text comparison from text ingest workspaces or matching txt/md/docx sources, with line-window evidence, omission checks, and per-episode coverage reports.
+
+## Changed
+- Source-less `scriptctl review` uses dedicated script-consistency instructions and tools, without requiring timestamps or original-media evidence.
+- Text ingest preserves full-source line windows on actions. Existing v4 ingest workspaces can recover those windows through stable identity mappings during text review.
+- `scriptctl review --check` reports the selected `review_kind` (`script`, `text`, `comic`, or `video`).
+
+## Fixed
+- None.
+
+## Breaking
+- None.

package/dist/bin.js

@@ -1,2 +1,2 @@
 #!/usr/bin/env node
-import{b as s}from"./chunk-YOCQDDQC.js";import{Console as r}from"node:console";var o=new r({stdout:process.stderr,stderr:process.stderr});console.debug=o.debug.bind(o);console.info=o.info.bind(o);console.log=o.log.bind(o);s(process.argv.slice(2)).then(e=>{process.exitCode=e}).catch(e=>{console.error(e),process.exitCode=70});
+import{b as s}from"./chunk-5T4VIFJR.js";import{Console as r}from"node:console";var o=new r({stdout:process.stderr,stderr:process.stderr});console.debug=o.debug.bind(o);console.info=o.info.bind(o);console.log=o.log.bind(o);s(process.argv.slice(2)).then(e=>{process.exitCode=e}).catch(e=>{console.error(e),process.exitCode=70});