@xiaohhhh1/canvas-agent 0.4.49 → 0.4.51

package/dist/agent/codex.d.ts

@@ -17,7 +17,18 @@ export type CodexRunResult = {
     ok: false;
     error: string;
 };
-export type CodexWorkflowRunResult = CodexRunResult & {
+export type CodexWorkflowRunResult = {
+    ok: true;
+    text: string;
+    timings: {
+        queueWaitMs: number;
+        threadStartMs: number;
+        modelMs: number;
+    };
+} | {
+    ok: false;
+    error: string;
+    retryable: boolean;
     timings: {
         queueWaitMs: number;
         threadStartMs: number;
@@ -45,6 +56,8 @@ export declare function runCodexWorkflowTurn(prompt: string, emit: AgentEmit, op
     onWorkerStart?: () => void;
     onWorkerFinish?: () => void;
 }): Promise<CodexWorkflowRunResult>;
+/** Contract/preflight 4xx errors are deterministic and must never burn every fallback chunk size. */
+export declare function isDeterministicWorkflowContractError(error: unknown): boolean;
 /** 强制回收失去响应的 app-server；只用于有界超时恢复。 */
 export declare function restartCodexApp(message?: string): Promise<void>;
 /** 回复当前 app-server 的待处理权限请求。 */

package/dist/agent/codex.js

@@ -37,7 +37,7 @@ export async function interruptCodexTurn(threadId) {
  */
 export async function runCodexWorkflowTurn(prompt, emit, options) {
     if (!prompt.trim())
-        return { ok: false, error: "Codex prompt is empty", timings: { queueWaitMs: 0, threadStartMs: 0, modelMs: 0 } };
+        return { ok: false, error: "Codex prompt is empty", retryable: false, timings: { queueWaitMs: 0, threadStartMs: 0, modelMs: 0 } };
     return await workflowCodexPool.run(async (workerIndex, queueWaitMs) => {
         options.onWorkerStart?.();
         const modelSettings = { model: FLOW_C_CODEX_MODEL, reasoningEffort: FLOW_C_CODEX_REASONING_EFFORT };
@@ -61,7 +61,7 @@ export async function runCodexWorkflowTurn(prompt, emit, options) {
                 workflowCodexApps.delete(workerIndex);
                 await app.terminate("Flow C 脚本回合超时，已仅回收当前 worker");
                 await turn.catch(() => undefined);
-                return { ok: false, error: "Flow C 脚本回合超过 8 分钟，已自动终止当前 worker", timings: { queueWaitMs, threadStartMs, modelMs: Date.now() - modelStartedAt } };
+                return { ok: false, error: "Flow C 脚本回合超过 8 分钟，已自动终止当前 worker", retryable: true, timings: { queueWaitMs, threadStartMs, modelMs: Date.now() - modelStartedAt } };
             }
             return { ok: true, text: result, timings: { queueWaitMs, threadStartMs, modelMs: Date.now() - modelStartedAt } };
         }
@@ -69,7 +69,7 @@ export async function runCodexWorkflowTurn(prompt, emit, options) {
             logger.error("Flow C Codex worker failed", { workerIndex, error });
             const message = errorMessage(error);
             emit("agent_error", { message });
-            return { ok: false, error: message, timings: { queueWaitMs, threadStartMs: threadStartMs || Date.now() - threadStartedAt, modelMs: modelStartedAt ? Date.now() - modelStartedAt : 0 } };
+            return { ok: false, error: message, retryable: !isDeterministicWorkflowContractError(message), timings: { queueWaitMs, threadStartMs: threadStartMs || Date.now() - threadStartedAt, modelMs: modelStartedAt ? Date.now() - modelStartedAt : 0 } };
         }
         finally {
             if (timer)
@@ -78,6 +78,11 @@ export async function runCodexWorkflowTurn(prompt, emit, options) {
         }
     });
 }
+/** Contract/preflight 4xx errors are deterministic and must never burn every fallback chunk size. */
+export function isDeterministicWorkflowContractError(error) {
+    const message = errorMessage(error);
+    return /invalid_json_schema|invalid schema for response_format|text\.format\.schema|response[_ ]format[^\n]*(?:invalid|schema)/i.test(message);
+}
 async function startWorkflowCodexApp(workerIndex, emit) {
     let started;
     started = await CodexAppClient.start(emit, () => {

package/dist/workflow/manager.d.ts

@@ -30,13 +30,14 @@ type ReferenceStyleCard = {
     voiceTone?: unknown;
     categoryFit?: unknown;
 };
+type StoryboardLayoutVersion = "director-table-scripted-v1" | "hybrid-three-anchor-v1" | "legacy-five-row-v1";
 type ScriptTask = {
     id: string;
     workflow: "flow-c";
     market: string;
     duration_seconds?: 10 | 20 | 30;
-    storyboard_layout_version?: "hybrid-three-anchor-v1" | "legacy-five-row-v1";
-    storyboardLayoutVersion?: "hybrid-three-anchor-v1" | "legacy-five-row-v1";
+    storyboard_layout_version?: StoryboardLayoutVersion;
+    storyboardLayoutVersion?: StoryboardLayoutVersion;
     reference_style_card?: ReferenceStyleCard;
     referenceStyleCard?: ReferenceStyleCard;
     requested_count: number;
@@ -229,6 +230,11 @@ export declare class WorkflowManager {
     private save;
 }
 export declare function compareScriptQueueRecords(left: Pick<ScriptRecord, "priorityAt" | "updatedAt">, right: Pick<ScriptRecord, "priorityAt" | "updatedAt">): number;
+/** A deterministic response-format failure stops fallback isolation immediately. */
+export declare function terminalScriptChunkError(results: Array<{
+    error?: string;
+    terminal?: boolean;
+}>): string;
 export declare function scriptChunkPrompt(id: string, task: ScriptTask, ordinals: number[]): string;
 export declare function missingOrdinals(total: number, received: number[]): number[];
 export {};

package/dist/workflow/manager.js

@@ -239,6 +239,10 @@ export class WorkflowManager {
             const workspace = ensureSiteWorkspace(this.config);
             const durationSeconds = Number(task.duration_seconds || 10);
             const chunkSizes = flowCScriptChunkSizes(durationSeconds);
+            // Fail locally before starting any worker if a future schema edit
+            // violates strict response-format invariants.
+            for (const chunkSize of new Set(chunkSizes))
+                flowCScriptOutputSchema(durationSeconds, chunkSize);
             record.activeChunks = 0;
             let chunkSizeIndex = 0;
             while (record.receivedOrdinals.length < task.requested_count) {
@@ -253,6 +257,10 @@ export class WorkflowManager {
                 this.save();
                 const results = await Promise.all(chunks.map((ordinals) => this.runScriptChunk(id, task, ordinals, workspace.workspacePath)));
                 await this.scriptTask(id);
+                const terminalError = terminalScriptChunkError(results);
+                if (terminalError) {
+                    throw new Error(`本机脚本结构化契约被 Codex 拒绝，已停止自动重试且未提交缺失脚本。请先升级或修复 Canvas Agent，再手动重试（${terminalError}）`);
+                }
                 const progressed = record.receivedOrdinals.length > before;
                 if (progressed) {
                     chunkSizeIndex = 0;
@@ -304,7 +312,7 @@ export class WorkflowManager {
         this.emitScriptStage(id, ordinals, "thread_start", result.timings.threadStartMs);
         this.emitScriptStage(id, ordinals, "model", result.timings.modelMs);
         if (!result.ok || !result.text)
-            return { error: result.ok ? "Codex 未返回可用的结构化脚本" : result.error };
+            return { error: result.ok ? "Codex 未返回可用的结构化脚本" : result.error, terminal: !result.ok && !result.retryable };
         try {
             const parseStartedAt = Date.now();
             const jobs = parseFlowCScriptOutput(result.text, ordinals);
@@ -312,10 +320,10 @@ export class WorkflowManager {
             const persistStartedAt = Date.now();
             await this.submitGeneratedScriptJobs(id, jobs);
             this.emitScriptStage(id, ordinals, "persist", Date.now() - persistStartedAt);
-            return {};
+            return { terminal: false };
         }
         catch (error) {
-            return { error: error instanceof Error ? `结构化脚本未通过本机校验：${error.message}` : "结构化脚本未通过本机校验" };
+            return { error: error instanceof Error ? `结构化脚本未通过本机校验：${error.message}` : "结构化脚本未通过本机校验", terminal: false };
         }
     }
     /** 只记录阶段、ordinal 和毫秒数；禁止记录 prompt、令牌或中心能力。 */
@@ -487,11 +495,15 @@ export function compareScriptQueueRecords(left, right) {
         return String(right.priorityAt || "").localeCompare(String(left.priorityAt || ""));
     return left.updatedAt.localeCompare(right.updatedAt);
 }
+/** A deterministic response-format failure stops fallback isolation immediately. */
+export function terminalScriptChunkError(results) {
+    return results.find((result) => result.terminal)?.error || "";
+}
 class ExpiredCapabilityError extends Error {
 }
 export function scriptChunkPrompt(id, task, ordinals) {
     const duration = Number(task.duration_seconds || 10);
-    const layoutVersion = task.storyboard_layout_version || task.storyboardLayoutVersion || "hybrid-three-anchor-v1";
+    const layoutVersion = task.storyboard_layout_version || task.storyboardLayoutVersion || "director-table-scripted-v1";
     const styleCard = compactReferenceStyleCard(task.reference_style_card || task.referenceStyleCard);
     const durationRules = duration === 10 ? `
 本任务每条成片为 10 秒，不生成 masterScript。每条只输出一份 openingState 和一个完整 0–10 秒 segment；Agent 会从 structured shots 确定性渲染兼容顶层 script，并按 shots 顺序派生 segmentVoiceovers，模型不要生成这两个派生字段。` : `
@@ -500,10 +512,11 @@ export function scriptChunkPrompt(id, task, ordinals) {
     return `你正在后台处理“抖音小辉跨境工具”Flow C 脚本交接 ${id}。
 完整中心任务已经附在本提示词末尾。只创作 ordinal ${ordinals[0]} 到 ${ordinals.at(-1)}（精确列表：${ordinals.join(", ")}）。
 本段 productIndex 必须严格按此映射填写：${scriptProductAssignments(task.product_quantities, ordinals)}。不得凭产品名称猜测或把相邻产品编号混用。
-脚本质量绝不能因批量而降低：每条都必须独立构思、完整、真实合规，严格遵守任务 instructions、产品图片顺序和 productIndex；使用目标市场 ${task.market} 的自然本地语言与偏快但清晰的短视频节奏。${durationRules}
+脚本质量绝不能因批量而降低：每条都必须独立构思、完整、真实合规，严格遵守任务 instructions、产品图片顺序和 productIndex；使用目标市场 ${task.market} 的自然本地口播与偏快但清晰的短视频节奏。${durationRules}
 每条先按“画面先行”写 creativePlan，再写本段/总脚本。creativePlan 必须给出 visualHook、conflict、productIntervention、visibleProof、callbackMotivation、truthBoundary、differentiationKey，并在 escalation 或 turn 中至少给出一项真实成立的升级/转折；format 必须依据当前产品、市场、事实证据和真实场景适配选择。中国短剧式冲突/喜剧只能是适合时的实验路线，绝不是默认；工厂、仓库、超市等条件场景也只有在商品动作自然且不伪造来源、库存或销量证据时才可选，不能固定轮换。
 styleCardSummary 只使用已缓存的压缩风格卡，没有就明确写“无”；不要分析、读取或转录原始参考视频。每条只生成一份 voiceProfile（性别、年龄感、音高、音质、语速、口音、停顿习惯、情绪基调），所有局部段共同引用它；每段仅用简短 voiceCue 表达情绪变化，不复写整套音色。
-每个 segment 必须有完整 0–10 秒 shots、voiceCue 和 endingState；不要让模型生成 continuityMode 或 continuity。每个 shot 都包含画面、准确本地口播、可控屏幕字、商品证据、soundBgm 与 emotionalNote。qualityGate 必须逐项用具体证据核对强钩子、冲突、升级/转折、商品介入、可见证明、开头回扣购买动机、事实边界与批内差异，禁止用“已满足”空话。
+每个 segment 必须有完整 0–10 秒 shots、voiceCue 和 endingState；不要让模型生成 continuityMode 或 continuity。镜头数由本条剧情实际需要决定（契约允许 1–8 个），不得为了故事板版式强行固定为三个或五个。每个 shot 都包含画面、准确本地口播、可控屏幕字、商品证据、soundBgm 与 emotionalNote。qualityGate 必须逐项用具体证据核对强钩子、冲突、升级/转折、商品介入、可见证明、开头回扣购买动机、事实边界与批内差异，禁止用“已满足”空话。
+【回传语言契约】为了让导演故事板稳定可读，creativePlan、masterScript 中的导演/剧情说明、voiceProfile、qualityGate、openingState、voiceCue、endingState，以及每个 shot 的 visual、evidence、soundBgm、emotionalNote 必须用清晰简洁的制作英文。每个 shot.voiceover 必须逐字使用目标市场 ${task.market} 的自然当地语言，不得翻译成英文；onScreenText 若画面确实需要展示文字，则写目标市场当地语言的准确短文案，否则写英文 NONE。不得在英文导演字段里混入另一份口播或全局时轴。
 每条 differentiationKey 必须在带货形式、第一眼画面、剧情骨架、痛点/反差、商品证明和口播气质上与本批其他条目显著不同，不能只换措辞。
 本脚本回合固定使用 GPT-5.6 Terra 高推理；不要建议换低档模型或降低推理。故事版布局由中心顶层 storyboardLayoutVersion=${layoutVersion} 管理，不要让模型选择，也不要把它重复进每条 job。
 【已缓存压缩的参考 style card】${styleCard || "无参考风格卡"}【style card 结束】

package/dist/workflow/script-output.d.ts

@@ -1,5 +1,11 @@
 type JsonSchema = Record<string, unknown>;
 /** Codex app-server 的结构化脚本返回契约；回传由 Agent 完成，不依赖模型调用 MCP。 */
 export declare function flowCScriptOutputSchema(durationSeconds: 10 | 20 | 30, count: number): JsonSchema;
+/**
+ * OpenAI strict structured output requires every declared object property to
+ * appear in `required`. Optional semantics must therefore be represented by a
+ * required nullable field, never by omitting that key from `required`.
+ */
+export declare function assertStrictResponseSchema(schemaValue: unknown, path?: string): asserts schemaValue is JsonSchema;
 export declare function parseFlowCScriptOutput(value: string, expectedOrdinals: number[]): unknown[];
 export {};

package/dist/workflow/script-output.js

@@ -1,4 +1,5 @@
 const text = { type: "string", minLength: 1 };
+const nullableText = { anyOf: [text, { type: "null" }] };
 const continuityFields = ["character", "wardrobe", "location", "lighting", "productState", "unfinishedAction", "nextGoal"];
 function object(properties, required = Object.keys(properties)) {
     return { type: "object", properties, required, additionalProperties: false };
@@ -26,16 +27,16 @@ function creativePlanSchema() {
         format: text,
         visualHook: text,
         conflict: text,
-        escalation: text,
-        turn: text,
+        escalation: nullableText,
+        turn: nullableText,
         productIntervention: text,
         visibleProof: text,
         callbackMotivation: text,
         truthBoundary: text,
         differentiationKey: text,
-        styleCardSummary: text,
+        styleCardSummary: nullableText,
     };
-    return object(properties, Object.keys(properties).filter((field) => !["escalation", "turn"].includes(field)));
+    return object(properties);
 }
 function qualityGateSchema() {
     return object({
@@ -87,7 +88,40 @@ export function flowCScriptOutputSchema(durationSeconds, count) {
         properties.masterScript = { type: "string", minLength: 40 };
         properties.segments = { type: "array", minItems: durationSeconds / 10, maxItems: durationSeconds / 10, items: segmentSchema() };
     }
-    return object({ jobs: { type: "array", minItems: count, maxItems: count, items: object(properties) } });
+    const schema = object({ jobs: { type: "array", minItems: count, maxItems: count, items: object(properties) } });
+    assertStrictResponseSchema(schema);
+    return schema;
+}
+/**
+ * OpenAI strict structured output requires every declared object property to
+ * appear in `required`. Optional semantics must therefore be represented by a
+ * required nullable field, never by omitting that key from `required`.
+ */
+export function assertStrictResponseSchema(schemaValue, path = "$") {
+    const schema = recordOf(schemaValue);
+    if (!schema)
+        throw new Error(`Strict response schema at ${path} must be an object`);
+    if (schema.type === "object") {
+        const properties = recordOf(schema.properties);
+        if (!properties)
+            throw new Error(`Strict response schema object at ${path} needs properties`);
+        const keys = Object.keys(properties).sort();
+        const required = Array.isArray(schema.required) ? schema.required.map(String).sort() : [];
+        if (keys.length !== required.length || keys.some((key, index) => key !== required[index])) {
+            throw new Error(`Strict response schema object at ${path} must require every property`);
+        }
+        if (schema.additionalProperties !== false)
+            throw new Error(`Strict response schema object at ${path} must disable additional properties`);
+        for (const [key, child] of Object.entries(properties))
+            assertStrictResponseSchema(child, `${path}.properties.${key}`);
+    }
+    if (schema.items)
+        assertStrictResponseSchema(schema.items, `${path}.items`);
+    for (const branchKey of ["anyOf", "oneOf", "allOf"]) {
+        const branches = schema[branchKey];
+        if (Array.isArray(branches))
+            branches.forEach((branch, index) => assertStrictResponseSchema(branch, `${path}.${branchKey}[${index}]`));
+    }
 }
 export function parseFlowCScriptOutput(value, expectedOrdinals) {
     const source = String(value || "").trim().replace(/^```(?:json)?\s*/i, "").replace(/\s*```$/, "");
@@ -147,8 +181,8 @@ function segmentVoiceoverLines(segmentValue) {
     return shots.map((shot) => String(shot.voiceover || "").trim()).filter((line) => line && !/^(none|无|sin voz|sin diálogo)$/i.test(line));
 }
 function continuityFromOpeningState(openingState) {
-    const continuity = Object.fromEntries(continuityFields.map((field) => [field, openingState?.[field] || "由本段首镜建立"]));
-    continuity.previousEndingFrame = openingState?.openingFrame || "本段首镜";
+    const continuity = Object.fromEntries(continuityFields.map((field) => [field, openingState?.[field] || "Established by the opening shot"]));
+    continuity.previousEndingFrame = openingState?.openingFrame || "Opening shot of this segment";
     return continuity;
 }
 /**
@@ -163,11 +197,11 @@ function withLegacySegmentScript(segmentValue, segmentIndex, segmentCount, voice
     const shots = Array.isArray(segment?.shots) ? segment.shots.map(recordOf).filter((shot) => Boolean(shot)) : [];
     if (!segment || !continuity || !endingState || !shots.length)
         return segmentValue;
-    const context = `人物：${continuity.character}；服装：${continuity.wardrobe}；地点：${continuity.location}；光线：${continuity.lighting}；商品状态：${continuity.productState}；承接动作：${continuity.unfinishedAction}；本段目标：${continuity.nextGoal}；上一段结尾画面：${continuity.previousEndingFrame}`;
-    const ending = `人物：${endingState.character}；服装：${endingState.wardrobe}；地点：${endingState.location}；光线：${endingState.lighting}；商品状态：${endingState.productState}；未完成动作：${endingState.unfinishedAction}；下一段目标：${endingState.nextGoal}；本段结尾画面：${endingState.endingFrame}`;
-    const voice = voiceProfile ? `性别：${voiceProfile.gender}；年龄感：${voiceProfile.ageImpression}；音高：${voiceProfile.pitch}；音质：${voiceProfile.timbre}；语速：${voiceProfile.speakingRate}；口音：${voiceProfile.accent}；停顿习惯：${voiceProfile.pauseHabit}；情绪基调：${voiceProfile.emotionalBaseline}` : "沿用本条共同音色档案";
-    const timeline = shots.map((shot, index) => `镜头 ${index + 1}｜${shot.startSeconds}–${shot.endSeconds} 秒｜画面：${shot.visual}｜口播：${shot.voiceover}｜屏幕字：${shot.onScreenText}｜证据：${shot.evidence}｜声音/BGM：${shot.soundBgm}｜情绪：${shot.emotionalNote}`).join("\n");
-    return { ...segment, script: `Flow C 独立分段 ${segmentIndex + 1}/${segmentCount}\n局部时轴：0–10 秒；不得引用或绘制总片时间轴。\n共同音色档案：${voice}\n本段音色提示：${segment.voiceCue}\n本段起始连续性：${context}\n${timeline}\n本段结束状态：${ending}` };
+    const context = `CHARACTER: ${continuity.character}; WARDROBE: ${continuity.wardrobe}; LOCATION: ${continuity.location}; LIGHTING: ${continuity.lighting}; PRODUCT STATE: ${continuity.productState}; INHERITED ACTION: ${continuity.unfinishedAction}; SEGMENT GOAL: ${continuity.nextGoal}; PREVIOUS ENDING FRAME: ${continuity.previousEndingFrame}`;
+    const ending = `CHARACTER: ${endingState.character}; WARDROBE: ${endingState.wardrobe}; LOCATION: ${endingState.location}; LIGHTING: ${endingState.lighting}; PRODUCT STATE: ${endingState.productState}; UNFINISHED ACTION: ${endingState.unfinishedAction}; NEXT GOAL: ${endingState.nextGoal}; ENDING FRAME: ${endingState.endingFrame}`;
+    const voice = voiceProfile ? `GENDER: ${voiceProfile.gender}; AGE IMPRESSION: ${voiceProfile.ageImpression}; PITCH: ${voiceProfile.pitch}; TIMBRE: ${voiceProfile.timbre}; SPEAKING RATE: ${voiceProfile.speakingRate}; ACCENT: ${voiceProfile.accent}; PAUSE HABIT: ${voiceProfile.pauseHabit}; EMOTIONAL BASELINE: ${voiceProfile.emotionalBaseline}` : "Use the shared voice profile for this video";
+    const timeline = shots.map((shot, index) => `SHOT ${index + 1} | ${shot.startSeconds}-${shot.endSeconds}s | VISUAL: ${shot.visual} | VO: ${shot.voiceover} | ON-SCREEN TEXT: ${shot.onScreenText} | EVIDENCE: ${shot.evidence} | SOUND/BGM: ${shot.soundBgm} | EMOTION: ${shot.emotionalNote}`).join("\n");
+    return { ...segment, script: `FLOW C INDEPENDENT SEGMENT ${segmentIndex + 1}/${segmentCount}\nLOCAL TIMELINE: 0-10 seconds only. Never reference or draw a full-video timeline.\nVOICE PROFILE: ${voice}\nSEGMENT VOICE CUE: ${segment.voiceCue}\nOPENING CONTINUITY: ${context}\n${timeline}\nENDING STATE: ${ending}` };
 }
 function recordOf(value) {
     return value && typeof value === "object" && !Array.isArray(value) ? value : null;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xiaohhhh1/canvas-agent",
-  "version": "0.4.49",
+  "version": "0.4.51",
   "type": "module",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",