@lingjingai/scriptctl 0.61.3 → 0.62.1

package/README.md

@@ -117,3 +117,23 @@ pnpm publish          # access=public，会自动跑 prepublishOnly
 ## License
 
 MIT
+
+### 指定视频理解服务
+
+默认视频 ingest 沿用 Gemini 主流程，失败后由豆包兜底。显式选择服务时只调用所选服务和模型：
+
+```bash
+# 豆包：默认读取 ARK_API_KEY；模型也可通过 ARK_MODEL 设置
+scriptctl ingest --source-path ./video.mp4 --video-provider doubao --provider-model ep-your-endpoint
+
+# 使用自定义凭据来源和服务地址
+scriptctl ingest --source-path ./video.mp4 --video-provider doubao \
+  --provider-model ep-your-endpoint --provider-api-key-env MY_ARK_API_KEY \
+  --provider-base-url https://ark.cn-beijing.volces.com/api/v3
+
+# Gemini：模型省略时使用配置中的视频模型
+scriptctl ingest --source-path ./video.mp4 --video-provider gemini
+```
+
+`--provider-api-key` 与 `--provider-api-key-env` 互斥。豆包仅支持默认的 `--upload-mode file-api`；
+直接选择豆包必须提供模型，且不需要 Gemini key。这些参数只影响视频理解阶段。

package/changes/0.61.4.md

@@ -0,0 +1,13 @@
+# 0.61.4
+
+## Added
+- None.
+
+## Changed
+- None.
+
+## Fixed
+- Preserve Google content-filter reason suffixes and report them as non-retryable filtering instead of empty responses.
+
+## Breaking
+- None.

package/changes/0.61.5.md

@@ -0,0 +1,5 @@
+# 0.61.5
+
+## Fixed
+- Review frame requests now describe even single timestamps as JSON arrays. Framework argument errors are returned to the agent as text so it can correct the request, instead of crashing while treating the error as image results.
+- Valid frame images keep their existing model output format.

package/changes/0.62.0.md

@@ -0,0 +1,13 @@
+# 0.62.0
+
+## Added
+- `scriptctl ingest --video-provider gemini|doubao` supports explicit video provider selection with existing model, API key, and base URL overrides. Direct Doubao requires `--provider-model` or `ARK_MODEL` and file-api upload mode. Explicit selection disables fallback; the default Gemini flow with Doubao fallback is unchanged.
+
+## Changed
+- None.
+
+## Fixed
+- None.
+
+## Breaking
+- None.

package/changes/0.62.1.md

@@ -0,0 +1,15 @@
+# 0.62.1
+
+## Added
+- `scriptctl refs` and `sc refs` locate asset and appearance references with scene/action addresses, surrounding text, and pagination. Explicit scene bindings, speakers, and textual mentions are reported separately; mentions do not imply presence or a particular appearance.
+- The screenplay SDK exports read-only `references` and `formatReferences`, shared by the CLI and review agents.
+- The Mastra screenplay review agent exposes `refs` during both episode review and whole-series convergence, querying the current in-memory document after edits.
+
+## Changed
+- Review instructions and the packaged scriptctl skill document reference lookup and distinguish read-only `refs` from the binding mutation `ref`.
+
+## Fixed
+- None.
+
+## Breaking
+- None.

package/dist/bin.js

@@ -1648,7 +1648,7 @@ var GeminiVideoModel = class {
     return file;
   }
   async generate(request2) {
-    if (request2.media.kind === "local-fallback") {
+    if (request2.media.kind === "local-fallback" || request2.media.kind === "local") {
       throw new LlmTransportError("invalid_response", "A local fallback video cannot be sent to Gemini.");
     }
     const config = {
@@ -1761,7 +1761,7 @@ var GeminiVideoModel = class {
     return { text: value.text, finishReason: value.finishReason, attempts, usage: addTokenUsage(failedUsage, value.usage), raw: value.raw };
   }
   async release(media, signal) {
-    if (media.kind === "base64" || media.kind === "local-fallback") return;
+    if (media.kind === "base64" || media.kind === "local-fallback" || media.kind === "local") return;
     try {
       await this.client.files.delete({ name: media.file.name });
     } catch (error) {
@@ -1930,7 +1930,7 @@ var OpenAiCompatibleModel = class {
       const choice = firstChoice(payload);
       const reason = finishReason(choice);
       if (reason === "length") throw new LlmTransportError("truncated", "Provider output was truncated.");
-      if (reason === "content_filter") throw new LlmTransportError("content_filtered", "Provider filtered the response.");
+      if (reason === "content_filter" || reason.startsWith("content_filter:")) throw new LlmTransportError("content_filtered", `Provider filtered the response (${reason}).`);
       const text2 = messageText(choice);
       if (!text2) throw new LlmTransportError("empty_response", "Provider returned an empty text response.");
       return { text: text2, finishReason: reason, attempts, usage, raw: payload };
@@ -1957,7 +1957,7 @@ var OpenAiCompatibleModel = class {
       const choice = firstChoice(payload);
       const reason = finishReason(choice);
       if (reason === "length") throw new LlmTransportError("truncated", "Provider tool output was truncated.");
-      if (reason === "content_filter") throw new LlmTransportError("content_filtered", "Provider filtered the response.");
+      if (reason === "content_filter" || reason.startsWith("content_filter:")) throw new LlmTransportError("content_filtered", `Provider filtered the response (${reason}).`);
       const calls = message(choice)?.["tool_calls"];
       if (!Array.isArray(calls)) throw new LlmTransportError("invalid_response", "Provider did not return a tool call.");
       for (const call of calls) {
@@ -2065,6 +2065,11 @@ var ModelRouter = class {
     const cached2 = this.resolvedRoutes.get(task);
     if (cached2) return cached2;
     const spec2 = LLM_TASK_REGISTRY[task];
+    if (spec2.mode === "video" && this.options.videoProvider?.provider === "doubao") {
+      const resolved2 = this.resolveDoubao(task, true);
+      this.resolvedRoutes.set(task, resolved2);
+      return resolved2;
+    }
     const profile = this.config.tasks[task] ?? spec2.defaultProfile;
     const modelConfig = this.config.models[profile];
     if (!modelConfig) throw configRuntimeError("The task route references a missing model profile.", [profile], [`task: ${task}`]);
@@ -2257,25 +2262,37 @@ var ModelRouter = class {
       };
     });
   }
-  doubaoRoute(task) {
-    const provider = {
+  resolveDoubao(task, explicit) {
+    const overrides = explicit ? this.options.videoProvider : void 0;
+    const modelName = explicit ? (overrides?.model ?? process.env["ARK_MODEL"] ?? "").trim() : this.doubaoModel();
+    if (!modelName) {
+      throw configRuntimeError("Doubao requires --provider-model or ARK_MODEL.", ["--provider-model <id> or ARK_MODEL"], ["model: empty"]);
+    }
+    const providerConfig = {
       protocol: "openai-compatible",
-      baseUrl: DOUBAO_FALLBACK.baseUrl,
+      baseUrl: overrides?.baseUrl ? normalizeProviderBaseUrl(overrides.baseUrl, "--provider-base-url") : DOUBAO_FALLBACK.baseUrl,
       apiKeyEnv: DOUBAO_FALLBACK.apiKeyEnv,
       timeoutMs: DOUBAO_FALLBACK.timeoutMs,
       maxAttempts: DOUBAO_FALLBACK.maxAttempts
     };
-    const model = { provider: "doubao", model: this.doubaoModel() };
+    const modelConfig = { provider: "doubao", model: modelName };
     return {
-      task,
-      profile: "doubao-fallback",
-      provider: "doubao",
-      protocol: provider.protocol,
-      baseUrl: provider.baseUrl,
-      model: model.model,
-      fingerprint: routeFingerprint(task, provider, model)
+      info: {
+        task,
+        profile: explicit ? "doubao" : "doubao-fallback",
+        provider: "doubao",
+        protocol: providerConfig.protocol,
+        baseUrl: providerConfig.baseUrl,
+        model: modelName,
+        fingerprint: routeFingerprint(task, providerConfig, modelConfig)
+      },
+      providerConfig,
+      modelConfig
     };
   }
+  doubaoRoute(task) {
+    return this.resolveDoubao(task, false).info;
+  }
   adapter(route) {
     const key = `${route.info.provider}\0${route.info.model}\0${route.modelConfig.thinkingBudgetTokens ?? ""}`;
     const cached2 = this.adapters.get(key);
@@ -2317,6 +2334,38 @@ var ModelRouter = class {
     const spec2 = LLM_TASK_REGISTRY[task];
     if (spec2.mode !== "video") throw configRuntimeError("The task does not support video generation.", ["video task"], [`task: ${task}`]);
     const route = this.resolve(task);
+    if (this.options.videoProvider?.provider === "doubao") {
+      const adapter = this.doubaoAdapter(route);
+      if (!adapter) throw credentialError("doubao");
+      return {
+        prepare: async (localPath, mimeType, mode, signal) => {
+          if (mode !== "file-api") {
+            throw configRuntimeError("Doubao requires file-api upload mode.", ["file-api"], [mode]);
+          }
+          signal?.throwIfAborted();
+          return { kind: "local", path: localPath, mimeType };
+        },
+        generate: (request2) => {
+          if (request2.media.kind !== "local") {
+            throw configRuntimeError("Doubao requires locally prepared video.", ["local media"], [request2.media.kind]);
+          }
+          request2.signal?.throwIfAborted();
+          const { path: localPath, mimeType: localMime } = request2.media;
+          return this.tracked(route.info, () => adapter.run({
+            localPath,
+            localMime,
+            user: request2.user,
+            fps: request2.fps,
+            maxOutputTokens: spec2.maxOutputTokens,
+            ...request2.system ? { system: request2.system } : {},
+            ...request2.responseJsonSchema ? { responseJsonSchema: request2.responseJsonSchema } : {},
+            ...request2.signal ? { signal: request2.signal } : {}
+          }));
+        },
+        release: async () => {
+        }
+      };
+    }
     if (route.providerConfig.protocol !== "google-gemini") {
       throw configRuntimeError(
         "Video tasks require a google-gemini provider.",
@@ -2405,16 +2454,17 @@ var ModelRouter = class {
       }
     };
   }
-  // The Doubao fallback adapter, or null when ARK_API_KEY is unset. Cached per key.
+  // Resolve an explicit Doubao route or the default fallback; absent fallback credentials skip it.
   // Overridable in tests to inject a fake Ark client.
-  doubaoAdapter() {
-    const apiKey = (process.env[DOUBAO_FALLBACK.apiKeyEnv] ?? "").trim();
+  doubaoAdapter(route) {
+    const apiKey = route ? this.videoCredential(route) : (process.env[DOUBAO_FALLBACK.apiKeyEnv] ?? "").trim();
     if (!apiKey) return null;
-    const model = this.doubaoModel();
-    const key = `doubao ${model}`;
+    const model = route?.info.model ?? this.doubaoModel();
+    const baseUrl = route?.providerConfig.baseUrl ?? DOUBAO_FALLBACK.baseUrl;
+    const key = `doubao ${baseUrl} ${model}`;
     const cached2 = this.doubaoAdapters.get(key);
     if (cached2) return cached2;
-    const adapter = new DoubaoVideoModel(model, DOUBAO_FALLBACK.timeoutMs, DOUBAO_FALLBACK.maxAttempts, apiKey, DOUBAO_FALLBACK.baseUrl);
+    const adapter = new DoubaoVideoModel(model, DOUBAO_FALLBACK.timeoutMs, DOUBAO_FALLBACK.maxAttempts, apiKey, baseUrl);
     this.doubaoAdapters.set(key, adapter);
     return adapter;
   }
@@ -4502,6 +4552,67 @@ function spanAddresses(doc2, actions) {
   });
 }
 
+// packages/screenplay/dist/references.js
+function references(doc2, address, opts = {}) {
+  const offset = opts.offset ?? 0, limit = opts.limit ?? 20, context = opts.context ?? 3;
+  for (const [name, value, minimum] of [["offset", offset, 0], ["limit", limit, 1], ["context", context, 0]]) {
+    if (!Number.isSafeInteger(value) || value < minimum)
+      throw new Error(`${name} must be an integer >= ${minimum}`);
+  }
+  const node = resolve6(doc2, address);
+  if (node.t !== "asset" && node.t !== "state")
+    throw new Error("references requires an asset or asset/state address; use read for episodes/scenes/actions");
+  const asset2 = node.asset;
+  const state2 = node.t === "state" ? node.state.id : null;
+  const names = [.../* @__PURE__ */ new Set([asset2.id, asset2.name, ...asset2.aliases])].filter(Boolean);
+  const hits = [];
+  for (const ep of doc2.episodes)
+    for (const scene of ep.scenes) {
+      const bindings = [...scene.location ? [scene.location] : [], ...scene.actors, ...scene.props].filter((ref2) => ref2.id === asset2.id && (state2 === null || ref2.states.includes(state2)));
+      if (bindings.length)
+        hits.push({ kind: "scene_binding", scene, matched: bindings.flatMap((ref2) => ref2.states) });
+      for (const action of scene.actions) {
+        if (action.speaker?.id === asset2.id && (state2 === null || action.speaker.state === state2)) {
+          hits.push({ kind: "speaker", scene, action, matched: [asset2.id] });
+        }
+        if (state2 === null) {
+          const matched = names.filter((name) => action.content.includes(name));
+          if (matched.length)
+            hits.push({ kind: "text_mention", scene, action, matched });
+        }
+      }
+    }
+  const end = offset + limit;
+  return {
+    asset_id: asset2.id,
+    state_id: state2,
+    total: hits.length,
+    next_offset: end < hits.length ? end : null,
+    items: hits.slice(offset, end).map(({ kind, scene, action, matched }) => {
+      const index = action ? scene.actions.indexOf(action) : -1;
+      const nearby = action ? scene.actions.slice(Math.max(0, index - context), index + context + 1) : [];
+      const gutter = Math.max(0, ...nearby.map((row) => row.anchor.length));
+      return {
+        kind,
+        address: action?.anchor ?? scene.anchor,
+        scene_address: scene.anchor,
+        episode: scene.ep.no,
+        matched,
+        text: [formatSceneHead(doc2, scene), ...nearby.map((row) => (row === action ? "> " : "  ") + formatAction(doc2, row, gutter))].join("\n")
+      };
+    })
+  };
+}
+function formatReferences(result) {
+  return [
+    `${result.asset_id}${result.state_id === null ? "" : "/" + result.state_id}  ${result.total} references \xB7 showing ${result.items.length}`,
+    "scene_binding=explicit scene presence; speaker=explicit speaker; text_mention=name/alias mention only (not proof of presence).",
+    ...result.items.map((hit) => `${hit.address}  ${hit.kind}  ep=${hit.episode}
+${hit.text}`),
+    result.next_offset === null ? "end" : `Continue: --offset ${result.next_offset}`
+  ].join("\n\n");
+}
+
 // packages/screenplay/dist/tools.js
 var NON_ACTOR_NAMES = ["\u65C1\u767D", "\u5E7F\u64AD", "\u753B\u5916", "\u7FA4\u58F0"];
 var NON_ACTOR_KIND = {
@@ -5629,6 +5740,15 @@ ${issues(d, {})}`
     ...opts["full"] ? { full: true } : {}
   }), "find"), state2));
   describeArguments(find2, ["\u6B63\u5219\uFF1B\u53EA\u6309 speaker/type \u8FC7\u6EE4\u65F6\u53EF\u7701\u7565"]);
+  const refs = withScriptOpts(program.command("refs <addr>"), "read").description("\u53EA\u8BFB\u5B9A\u4F4D\u8D44\u4EA7/\u9020\u578B\u7684\u573A\u666F\u7ED1\u5B9A\u3001\u8BF4\u8BDD\u5F15\u7528\u548C\u6B63\u6587\u63D0\u53CA\uFF0C\u8FD4\u56DE\u53EF read \u7684\u5730\u5740\u53CA\u4E0A\u4E0B\u6587").option("--offset <n>", "\u4ECE\u7B2C\u51E0\u6761\u5F15\u7528\u7EE7\u7EED\uFF08\u4ECE 0 \u5F00\u59CB\uFF09").option("--limit <n>", "\u672C\u6279\u5F15\u7528\u6570\uFF08\u9ED8\u8BA4 20\uFF09").option("--context <n>", "\u6B63\u6587\u547D\u4E2D\u524D\u540E\u5404\u51E0\u6761 action\uFF08\u9ED8\u8BA4 3\uFF09").action(dispatch((opts) => {
+    const result = references(doc(opts), arg(opts), {
+      offset: num(opts, "offset"),
+      limit: num(opts, "limit"),
+      context: num(opts, "context")
+    });
+    return [{ text: formatReferences(result), data: { op: "refs", changed: false, ...result } }, EXIT_OK];
+  }, state2));
+  describeArguments(refs, ["\u4EBA\u7269/\u573A\u666F/\u9053\u5177 ID \u6216\u540D\u79F0\uFF0C\u6216 <\u8D44\u4EA7>/<\u9020\u578B>\uFF1B\u6B63\u6587\u63D0\u53CA\u4E0D\u7B49\u4E8E\u5B9E\u9645\u51FA\u573A"]);
   const span2 = withScriptOpts(program.command("span <range>"), "read").description("\u628A\u4E00\u6BB5 action \u6362\u7B97\u6210\u96C6\u5185\u89C6\u9891\u65F6\u95F4\u7A97\u53E3\uFF08\u534A\u5F00\u533A\u95F4\uFF09").action(dispatch((opts) => text(() => span(doc(opts), arg(opts)), "span"), state2));
   describeArguments(span2, [`${ADDR}\uFF0C\u6216 \`\u8D77ID..\u6B62ID\``]);
   withScriptOpts(program.command("validate"), "read").description("\u8DD1\u6574\u672C\u6821\u9A8C").action(dispatch((opts) => text(() => validate(doc(opts)), "validate"), state2));
@@ -12097,6 +12217,7 @@ var intOf = (v, fallback) => {
   return Number.isInteger(n) && n > 0 ? n : fallback;
 };
 var VIDEO_OPTION_KEYS = [
+  "video_provider",
   "upload_mode",
   "provider_base_url",
   "provider_api_key",
@@ -12129,6 +12250,10 @@ function uploadModeOf(opts) {
   return mode;
 }
 function providerOverridesOf(opts) {
+  const provider = requiredOptionValue(opts, "video_provider", "--video-provider");
+  if (provider !== void 0 && provider !== "gemini" && provider !== "doubao") {
+    throw invalidVideoOption("Video provider must be gemini or doubao.", ["--video-provider gemini|doubao"]);
+  }
   const literalKeyProvided = optionProvided(opts, "provider_api_key");
   const keyEnvProvided = optionProvided(opts, "provider_api_key_env");
   if (literalKeyProvided && keyEnvProvided) {
@@ -12147,8 +12272,9 @@ function providerOverridesOf(opts) {
   let apiKey;
   if (literalKey !== void 0) apiKey = { kind: "literal", value: literalKey };
   else if (keyEnv !== void 0) apiKey = { kind: "env", name: keyEnv };
-  if (!baseUrl && !apiKey && !model) return void 0;
+  if (!provider && !baseUrl && !apiKey && !model) return void 0;
   return {
+    ...provider ? { provider } : {},
     ...baseUrl ? { baseUrl } : {},
     ...apiKey ? { apiKey } : {},
     ...model ? { model } : {}
@@ -12176,6 +12302,9 @@ async function commandIngest(opts, composition = PRODUCTION_LLM_COMPOSITION) {
   if (resolved.kind !== "text") {
     const uploadMode = uploadModeOf(opts);
     const videoProvider = providerOverridesOf(opts);
+    if (videoProvider?.provider === "doubao" && uploadMode !== "file-api") {
+      throw invalidVideoOption("Doubao requires --upload-mode file-api.", ["--upload-mode file-api"]);
+    }
     const executorOptions = videoProvider ? { videoProvider } : void 0;
     const executor2 = composition.createExecutor(strOf3(opts["llm_config"]).trim() || void 0, executorOptions);
     const configuredRoute = executor2.route("ingest.video-serial");
@@ -15962,7 +16091,7 @@ function registerWorkflowCommands(program, state2, llm2) {
     "after",
     "\nExample:\n  scriptctl migrate -p ./old-script.json -o ./script-v4.json --to 4\n"
   ).action(dispatch(commandMigrate, state2));
-  const ingest = program.command("ingest").description("Convert source files into a Script v4 workspace").option("-s, --source-path <path>", "Source file or directory").option("-w, --workspace-path <path>", "Workspace directory", "workspace").option("--llm-config <path>", "LLM configuration file").option("--concurrency <n>", "Maximum concurrent model calls").option("--fps <n>", "Video sampling rate").option("--upload-mode <mode>", "Video transport: file-api (default) or base64").option("--provider-base-url <url>", "Gemini-compatible provider service root").option("--provider-api-key <key>", "Provider API key (visible in process arguments; prefer --provider-api-key-env)").option("--provider-api-key-env <name>", "Environment variable containing the provider API key").option("--provider-model <model>", "Gemini-compatible provider model").option("--step", "Process only the next unfinished video episode").option("--force", "Rebuild completed stages").addHelpText("after", "\nExample:\n  scriptctl ingest --source-path ./draft.md --workspace-path ./workspace\n").action(dispatch((options) => commandIngest(options, llm2), state2));
+  const ingest = program.command("ingest").description("Convert source files into a Script v4 workspace").option("-s, --source-path <path>", "Source file or directory").option("-w, --workspace-path <path>", "Workspace directory", "workspace").option("--llm-config <path>", "LLM configuration file").option("--concurrency <n>", "Maximum concurrent model calls").option("--fps <n>", "Video sampling rate").option("--upload-mode <mode>", "Video transport: file-api (default) or base64").option("--video-provider <provider>", "Video provider: gemini or doubao (explicit selection disables fallback)").option("--provider-base-url <url>", "Selected video provider service root").option("--provider-api-key <key>", "Provider API key (visible in process arguments; prefer --provider-api-key-env)").option("--provider-api-key-env <name>", "Environment variable containing the provider API key").option("--provider-model <model>", "Selected video provider model (Doubao defaults to ARK_MODEL)").option("--step", "Process only the next unfinished video episode").option("--force", "Rebuild completed stages").addHelpText("after", "\nExample:\n  scriptctl ingest --source-path ./draft.md --workspace-path ./workspace\n").action(dispatch((options) => commandIngest(options, llm2), state2));
   ingest.command("status").description("Show ingest workspace progress").option("-w, --workspace-path <path>", "Workspace directory").action(dispatch(commandIngestStatus, state2));
   ingest.command("skip").description("Manually accept the next failed video episode as empty").option("-w, --workspace-path <path>", "Workspace directory").requiredOption("--episode <n>", "Failed episode number").requiredOption("--reason <text>", "Why this episode is being skipped").addHelpText("after", '\nExample:\n  scriptctl ingest skip -w ./workspace --episode 7 --reason "provider policy block"\n').action(dispatch(commandSkipVideoEpisode, state2));
   program.command("evidence").description("Generate local original-video reference frames from final Script v4 timestamps").option("-p, --script-path <path>", "Final Script v4 JSON file").requiredOption("-s, --source-path <path>", "Linked source-video file or episode directory").requiredOption("-w, --workspace-path <path>", "Project workspace directory").option("--force", "Re-extract frames even when deterministic output files already exist").addHelpText("after", "\nExample:\n  scriptctl evidence -p ./script.json -s /Volumes/NAS/videos -w ./workspace --force\n").action(dispatch(commandGenerateVideoStateEvidence, state2));