@dreamerbird/camera-studio 0.0.0-stage → 0.1.0

package/dist/agent/bridgeClient.test.js

@@ -0,0 +1,413 @@
+/*
+ * @jest-environment jsdom
+ */
+/**
+ * 浏览器桥接客户端(2026-10-19,Task 6,spec §10.2/§10.4):
+ *
+ * - 握手:WebSocket subprotocol 为 `camera-studio-v1` +
+ *   `token.<encodeURIComponent(token)`;onopen 生成新 sessionId 并发送
+ *   hello(sessionId + registry.describe() schema);
+ * - 命令:command 报文 → registry.execute(name, args, {requestId 原样,
+ *   signal});成功回 result 报文(项目 mutation 带当前 revision,query 不带);
+ *   AgentApiError/未知异常回结构化 error 报文,绝不因错误关闭 socket;
+ * - 任务:runtime.jobs 事件 → job 报文,sessionId 与 hello 一致;
+ * - 断线:指数退避重连(上限 5 秒),每次连接生成新 sessionId;
+ *   close() 后停止重连、摘除消息处理、拒绝新执行;
+ * - 二进制:args 里的 fileRef 先经 bridgeFiles 水合,失败结构化上抛,
+ *   不调用领域命令(token 绝不进报文/日志)。
+ *
+ * WebSocket 用模块级 fake(赋值 globalThis.WebSocket),fetch 在
+ * bridgeClient 层只经 bridgeFiles 间接调用,这里用全局 jest.fn 替身。
+ */
+import { AgentApiError } from './errors';
+import { createAgentBridgeClient } from './bridgeClient';
+class FakeWebSocket {
+    constructor(url, protocols) {
+        this.sent = [];
+        this.readyState = 0;
+        this.closeCalled = false;
+        this.onopen = null;
+        this.onmessage = null;
+        this.onclose = null;
+        this.onerror = null;
+        this.url = url;
+        this.protocols = Array.isArray(protocols)
+            ? protocols
+            : protocols
+                ? [protocols]
+                : [];
+        FakeWebSocket.instances.push(this);
+    }
+    send(data) {
+        this.sent.push(data);
+    }
+    close() {
+        this.closeCalled = true;
+        this.readyState = 3;
+    }
+    /** 以下模拟对端(桥接)行为 */
+    serverOpen() {
+        this.readyState = 1;
+        this.onopen?.();
+    }
+    serverSend(message) {
+        this.onmessage?.({ data: JSON.stringify(message) });
+    }
+    serverClose() {
+        this.readyState = 3;
+        this.onclose?.();
+    }
+    lastSent() {
+        return JSON.parse(this.sent[this.sent.length - 1]);
+    }
+}
+FakeWebSocket.instances = [];
+/** 纯微任务链冲刷(hydrate → execute → send 全微任务;不依赖计时器) */
+async function flushAsync() {
+    for (let i = 0; i < 30; i++)
+        await Promise.resolve();
+}
+function makeRegistry() {
+    const execute = jest.fn();
+    const describe = jest.fn(() => ({
+        apiVersion: 1,
+        commands: [
+            {
+                name: 'objects.update',
+                kind: 'mutation',
+                stateDomain: 'project',
+                undoable: 'single-step',
+                inputSchema: {},
+                outputSchema: {},
+                errorCodes: [],
+                acceptsExpectedRevision: true,
+            },
+            {
+                name: 'scene.getSnapshot',
+                kind: 'query',
+                stateDomain: 'project',
+                undoable: 'none',
+                inputSchema: {},
+                outputSchema: {},
+                errorCodes: [],
+                acceptsExpectedRevision: false,
+            },
+            {
+                name: 'assets.importModel',
+                kind: 'job',
+                stateDomain: 'asset',
+                undoable: 'none',
+                inputSchema: {},
+                outputSchema: {},
+                errorCodes: [],
+                acceptsExpectedRevision: false,
+            },
+        ],
+    }));
+    return { execute, describe };
+}
+function makeRuntime() {
+    let listener;
+    const unsubscribe = jest.fn(() => {
+        listener = undefined;
+    });
+    return {
+        revision: 42,
+        jobs: {
+            subscribe: (l) => {
+                listener = l;
+                return unsubscribe;
+            },
+            cancel: jest.fn(),
+        },
+        unsubscribe,
+        emitJob(snapshot) {
+            listener?.(snapshot);
+        },
+    };
+}
+const config = {
+    url: 'ws://127.0.0.1:43110',
+    token: 'tok/en 1',
+    httpUrl: 'http://127.0.0.1:43110',
+};
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+function startClient(registry, runtime) {
+    return createAgentBridgeClient({
+        registry,
+        runtime,
+        config,
+    });
+}
+beforeEach(() => {
+    FakeWebSocket.instances = [];
+    globalThis.WebSocket = FakeWebSocket;
+});
+afterEach(() => {
+    delete globalThis.WebSocket;
+    delete globalThis.fetch;
+    jest.useRealTimers();
+    jest.restoreAllMocks();
+});
+describe('bridgeClient 握手与命令执行', () => {
+    test('连接使用 camera-studio-v1 + token.<encoded> subprotocol,open 后发送 hello', () => {
+        const registry = makeRegistry();
+        const runtime = makeRuntime();
+        const client = startClient(registry, runtime);
+        const ws = FakeWebSocket.instances[0];
+        expect(ws.url).toBe('ws://127.0.0.1:43110');
+        expect(ws.protocols).toEqual([
+            'camera-studio-v1',
+            `token.${encodeURIComponent('tok/en 1')}`,
+        ]);
+        ws.serverOpen();
+        const hello = JSON.parse(ws.sent[0]);
+        expect(hello.type).toBe('hello');
+        expect(typeof hello.sessionId).toBe('string');
+        expect(hello.sessionId.length).toBeGreaterThan(0);
+        expect(hello.schema).toEqual(registry.describe());
+        client.close();
+    });
+    test('command 报文 → registry.execute,name/args 一致,requestId 原样透传;项目 mutation 成功带 revision', async () => {
+        const registry = makeRegistry();
+        const runtime = makeRuntime();
+        registry.execute.mockResolvedValue({ updated: true });
+        const client = startClient(registry, runtime);
+        const ws = FakeWebSocket.instances[0];
+        ws.serverOpen();
+        ws.serverSend({
+            type: 'command',
+            commandId: 'c1',
+            request: {
+                requestId: 'req-1',
+                name: 'objects.update',
+                args: { objectId: 'model:M' },
+            },
+        });
+        await flushAsync();
+        expect(registry.execute).toHaveBeenCalledTimes(1);
+        const [name, args, context] = registry.execute.mock.calls[0];
+        expect(name).toBe('objects.update');
+        expect(args).toEqual({ objectId: 'model:M' });
+        expect(context).toMatchObject({ requestId: 'req-1' });
+        expect(context.signal).toBeInstanceOf(AbortSignal);
+        expect(ws.lastSent()).toEqual({
+            type: 'result',
+            commandId: 'c1',
+            response: { ok: true, result: { updated: true }, revision: 42 },
+        });
+        client.close();
+    });
+    test('query 命令成功不携带 revision', async () => {
+        const registry = makeRegistry();
+        const runtime = makeRuntime();
+        registry.execute.mockResolvedValue({ revision: 42, objects: [] });
+        const client = startClient(registry, runtime);
+        const ws = FakeWebSocket.instances[0];
+        ws.serverOpen();
+        ws.serverSend({
+            type: 'command',
+            commandId: 'c2',
+            request: { requestId: 'req-2', name: 'scene.getSnapshot', args: undefined },
+        });
+        await flushAsync();
+        const message = ws.lastSent();
+        expect(message.type).toBe('result');
+        expect(message.response.ok).toBe(true);
+        expect(message.response.result).toEqual({ revision: 42, objects: [] });
+        expect('revision' in message.response).toBe(false);
+        client.close();
+    });
+    test('AgentApiError → 结构化 error 报文,socket 保持打开', async () => {
+        const registry = makeRegistry();
+        const runtime = makeRuntime();
+        registry.execute.mockRejectedValue(new AgentApiError('REVISION_CONFLICT', 'revision 冲突', {
+            retryable: false,
+            details: { expectedRevision: 1, actualRevision: 42 },
+        }));
+        const client = startClient(registry, runtime);
+        const ws = FakeWebSocket.instances[0];
+        ws.serverOpen();
+        ws.serverSend({
+            type: 'command',
+            commandId: 'c3',
+            request: {
+                requestId: 'req-3',
+                name: 'objects.update',
+                args: { objectId: 'model:M' },
+            },
+        });
+        await flushAsync();
+        expect(ws.lastSent()).toEqual({
+            type: 'error',
+            commandId: 'c3',
+            response: {
+                ok: false,
+                error: {
+                    code: 'REVISION_CONFLICT',
+                    message: 'revision 冲突',
+                    retryable: false,
+                    details: { expectedRevision: 1, actualRevision: 42 },
+                },
+            },
+        });
+        expect(ws.closeCalled).toBe(false);
+        expect(ws.readyState).toBe(1);
+        client.close();
+    });
+    test('未知异常归一为 INTERNAL_ERROR,socket 保持打开', async () => {
+        const registry = makeRegistry();
+        const runtime = makeRuntime();
+        registry.execute.mockRejectedValue(new Error('boom'));
+        const client = startClient(registry, runtime);
+        const ws = FakeWebSocket.instances[0];
+        ws.serverOpen();
+        ws.serverSend({
+            type: 'command',
+            commandId: 'c4',
+            request: {
+                requestId: 'req-4',
+                name: 'objects.update',
+                args: {},
+            },
+        });
+        await flushAsync();
+        const message = ws.lastSent();
+        expect(message.type).toBe('error');
+        expect(message.commandId).toBe('c4');
+        expect(message.response.ok).toBe(false);
+        expect(message.response.error.code).toBe('INTERNAL_ERROR');
+        expect(message.response.error.retryable).toBe(false);
+        expect(ws.closeCalled).toBe(false);
+        client.close();
+    });
+    test('fileRef 水合失败 → 结构化错误,registry.execute 不被调用,token 不出现在报文里', async () => {
+        const registry = makeRegistry();
+        const runtime = makeRuntime();
+        const errorSpy = jest.spyOn(console, 'error').mockImplementation(() => { });
+        globalThis.fetch = jest
+            .fn()
+            .mockRejectedValue(new TypeError('Failed to fetch'));
+        const client = startClient(registry, runtime);
+        const ws = FakeWebSocket.instances[0];
+        ws.serverOpen();
+        ws.serverSend({
+            type: 'command',
+            commandId: 'c9',
+            request: {
+                requestId: 'req-9',
+                name: 'assets.importModel',
+                args: {
+                    file: {
+                        fileId: 'f1',
+                        fileName: 'Y Bot.glb',
+                        mimeType: 'model/gltf-binary',
+                    },
+                },
+            },
+        });
+        await flushAsync();
+        expect(registry.execute).not.toHaveBeenCalled();
+        const message = ws.lastSent();
+        expect(message.type).toBe('error');
+        expect(message.commandId).toBe('c9');
+        expect(message.response.ok).toBe(false);
+        expect(message.response.error.code).toBe('NETWORK_ERROR');
+        // token 绝不出现在报文与日志里
+        expect(JSON.stringify(ws.sent)).not.toContain('tok/en 1');
+        expect(JSON.stringify(errorSpy.mock.calls)).not.toContain('tok/en 1');
+        // CORS 日志保留 httpUrl 与页面 origin
+        expect(JSON.stringify(errorSpy.mock.calls)).toContain('http://127.0.0.1:43110');
+        expect(ws.closeCalled).toBe(false);
+        client.close();
+    });
+});
+describe('bridgeClient 任务事件', () => {
+    test('job 事件携带与 hello 相同的 sessionId', async () => {
+        const registry = makeRegistry();
+        const runtime = makeRuntime();
+        const client = startClient(registry, runtime);
+        const ws = FakeWebSocket.instances[0];
+        ws.serverOpen();
+        const helloSessionId = JSON.parse(ws.sent[0]).sessionId;
+        runtime.emitJob({
+            jobId: 'j1',
+            kind: 'exports.startVideo',
+            state: 'running',
+            progress: 0.5,
+            phase: 'committed',
+            cancelable: true,
+        });
+        await flushAsync();
+        const message = ws.lastSent();
+        expect(message.type).toBe('job');
+        expect(message.sessionId).toBe(helloSessionId);
+        expect(message.snapshot).toMatchObject({
+            jobId: 'j1',
+            state: 'running',
+            progress: 0.5,
+        });
+        client.close();
+    });
+    test('cancel 报文转发 runtime.jobs.cancel', () => {
+        const registry = makeRegistry();
+        const runtime = makeRuntime();
+        const client = startClient(registry, runtime);
+        const ws = FakeWebSocket.instances[0];
+        ws.serverOpen();
+        ws.serverSend({ type: 'cancel', jobId: 'j7' });
+        expect(runtime.jobs.cancel).toHaveBeenCalledWith('j7');
+        client.close();
+    });
+});
+describe('bridgeClient 重连与关闭', () => {
+    test('断线后指数退避重连,新连接生成新 sessionId', () => {
+        jest.useFakeTimers();
+        const registry = makeRegistry();
+        const runtime = makeRuntime();
+        const client = startClient(registry, runtime);
+        const ws1 = FakeWebSocket.instances[0];
+        ws1.serverOpen();
+        const sessionId1 = JSON.parse(ws1.sent[0]).sessionId;
+        ws1.serverClose();
+        expect(FakeWebSocket.instances).toHaveLength(1);
+        jest.advanceTimersByTime(250);
+        expect(FakeWebSocket.instances).toHaveLength(2);
+        const ws2 = FakeWebSocket.instances[1];
+        ws2.serverOpen();
+        const sessionId2 = JSON.parse(ws2.sent[0]).sessionId;
+        expect(sessionId2).not.toBe(sessionId1);
+        // 新连接重新 hello,schema 照带
+        expect(JSON.parse(ws2.sent[0]).schema).toEqual(registry.describe());
+        // 再次断线:退避增长(第二次 ≥ 500ms 才重连)
+        ws2.serverClose();
+        jest.advanceTimersByTime(249);
+        expect(FakeWebSocket.instances).toHaveLength(2);
+        jest.advanceTimersByTime(251);
+        expect(FakeWebSocket.instances).toHaveLength(3);
+        client.close();
+    });
+    test('close() 后停止重连并拒绝新执行', async () => {
+        jest.useFakeTimers();
+        const registry = makeRegistry();
+        const runtime = makeRuntime();
+        const client = startClient(registry, runtime);
+        const ws = FakeWebSocket.instances[0];
+        ws.serverOpen();
+        client.close();
+        expect(ws.closeCalled).toBe(true);
+        expect(runtime.unsubscribe).toHaveBeenCalled();
+        // 后续断线事件不再触发重连
+        ws.serverClose();
+        jest.advanceTimersByTime(30000);
+        expect(FakeWebSocket.instances).toHaveLength(1);
+        // 消息处理已摘除:迟到的 command 不执行
+        ws.serverSend({
+            type: 'command',
+            commandId: 'c-late',
+            request: { requestId: 'req-late', name: 'objects.update', args: {} },
+        });
+        await flushAsync();
+        expect(registry.execute).not.toHaveBeenCalled();
+    });
+});

package/dist/agent/bridgeFiles.d.ts

@@ -0,0 +1,33 @@
+import type { JobSnapshot } from './types';
+/** 桥接 HTTP 传输凭据(httpUrl + Bearer token;token 绝不进日志) */
+export type BridgeFileTransport = {
+    httpUrl: string;
+    token: string;
+};
+/** HTTP 传输形状:POST /v1/files 上传后 Agent 拿到的文件引用 */
+export type BridgeFileRef = {
+    fileId: string;
+    fileName?: string;
+    mimeType?: string;
+};
+/** 桥接返回的临时文件描述(POST /v1/files 201 的 result) */
+export type BridgeFileDescriptor = {
+    fileId: string;
+    fileName: string;
+    mimeType: string;
+    size: number;
+};
+/**
+ * 命令 args 水合:`{file:{fileId,...}}` → 下载字节构造 File 后替换;
+ * 无 fileRef 的 args 原样返回(同引用,不发起请求)。失败以 AgentApiError
+ * 结构化上抛——调用方(bridgeClient)据此回 error 报文,不调用领域命令。
+ */
+export declare function hydrateCommandArgs(args: unknown, transport: BridgeFileTransport, fetchImpl?: typeof fetch): Promise<unknown>;
+/**
+ * 任务结果脱水:succeeded 且 result 带 Blob → 上传到桥接,返回 result
+ * 换成 {fileId,fileName,mimeType,size} 的新快照(原始快照不改写);
+ * 其余快照同引用原样返回。上传失败返回 failed NETWORK_ERROR 投影
+ * (result 抹除)——绝不报告成功但缺文件。本函数不抛错。
+ */
+export declare function dehydrateJobResult(snapshot: JobSnapshot<unknown>, transport: BridgeFileTransport, fetchImpl?: typeof fetch): Promise<JobSnapshot<unknown>>;
+//# sourceMappingURL=bridgeFiles.d.ts.map

package/dist/agent/bridgeFiles.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"bridgeFiles.d.ts","sourceRoot":"","sources":["../../src/agent/bridgeFiles.ts"],"names":[],"mappings":"AAoBA,OAAO,KAAK,EAAC,WAAW,EAAC,MAAM,SAAS,CAAA;AAExC,uDAAuD;AACvD,MAAM,MAAM,mBAAmB,GAAG;IAChC,OAAO,EAAE,MAAM,CAAA;IACf,KAAK,EAAE,MAAM,CAAA;CACd,CAAA;AAED,iDAAiD;AACjD,MAAM,MAAM,aAAa,GAAG;IAC1B,MAAM,EAAE,MAAM,CAAA;IACd,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB,QAAQ,CAAC,EAAE,MAAM,CAAA;CAClB,CAAA;AAED,+CAA+C;AAC/C,MAAM,MAAM,oBAAoB,GAAG;IACjC,MAAM,EAAE,MAAM,CAAA;IACd,QAAQ,EAAE,MAAM,CAAA;IAChB,QAAQ,EAAE,MAAM,CAAA;IAChB,IAAI,EAAE,MAAM,CAAA;CACb,CAAA;AAoFD;;;;GAIG;AACH,wBAAsB,kBAAkB,CACtC,IAAI,EAAE,OAAO,EACb,SAAS,EAAE,mBAAmB,EAC9B,SAAS,CAAC,EAAE,OAAO,KAAK,GACvB,OAAO,CAAC,OAAO,CAAC,CAMlB;AA6DD;;;;;GAKG;AACH,wBAAsB,kBAAkB,CACtC,QAAQ,EAAE,WAAW,CAAC,OAAO,CAAC,EAC9B,SAAS,EAAE,mBAAmB,EAC9B,SAAS,CAAC,EAAE,OAAO,KAAK,GACvB,OAAO,CAAC,WAAW,CAAC,OAAO,CAAC,CAAC,CA0C/B"}

package/dist/agent/bridgeFiles.js

@@ -0,0 +1,193 @@
+/**
+ * 桥接二进制适配(2026-10-19,Task 6,spec §10.2):File/Blob ↔ fileId。
+ *
+ * 二进制内容不进 JSON、不经 WebSocket(spec §10.2 硬约束):
+ * - hydrate(下载):HTTP 命令 args 里的 `{file:{fileId,...}}` 引用,经
+ *   `GET ${httpUrl}/v1/files/<fileId>`(Bearer token)取回字节构造 File
+ *   后再进 registry validator——原始 fileRef 不许绕过传输适配直接进入
+ *   领域层(assets.importModel validator 只收 File);
+ * - dehydrate(上传):succeeded 任务结果里的 Blob(VideoExportResult)
+ *   经 `POST ${httpUrl}/v1/files`(X-File-Name encodeURIComponent、
+ *   Content-Type、Bearer)写入桥接临时文件,发给桥接的任务快照 result
+ *   换成 {fileId,fileName,mimeType,size};上传失败时任务投影为
+ *   failed NETWORK_ERROR——绝不报告成功但缺文件。
+ *
+ * 错误语义:401 → UNAUTHORIZED,404 → FILE_NOT_FOUND,其余非 ok 与
+ * fetch 拒绝(CORS/网络)→ NETWORK_ERROR(可重试)。CORS 日志保留
+ * httpUrl 与 location.origin,提示宿主把精确 origin 加入桥接
+ * corsOrigins(不建议 `*`);token 绝不出现在日志/错误信息中。
+ */
+import { AgentApiError } from './errors';
+/** fetch 拒绝(CORS 或网络不可达)时的宿主指引:精确 origin,不建议 * */
+function logCorsHint(transport, action) {
+    const origin = typeof location !== 'undefined' ? location.origin : '(无 location 信息)';
+    // token 绝不出现在日志里:只保留 httpUrl 与页面 origin
+    console.error(`[camera-studio] 桥接${action}请求失败(可能是 CORS 或网络错误):` +
+        `bridge httpUrl=${transport.httpUrl},页面 origin=${origin}。` +
+        `请把该精确 origin 加入桥接 corsOrigins 配置(不建议使用 *)。`);
+}
+/**
+ * fileRef 判定:plain object 且带字符串 fileId;已是 File/Blob 的不算
+ * (JS 侧直呼 API 传 hydrated File 时不得二次下载)。
+ */
+function isFileRef(value) {
+    if (typeof value !== 'object' || value === null)
+        return false;
+    if (typeof File !== 'undefined' && value instanceof File)
+        return false;
+    if (typeof Blob !== 'undefined' && value instanceof Blob)
+        return false;
+    return (typeof value.fileId === 'string' &&
+        value.fileId !== '');
+}
+async function downloadFile(ref, transport, fetchImpl) {
+    const url = `${transport.httpUrl}/v1/files/${ref.fileId}`;
+    let response;
+    try {
+        response = await fetchImpl(url, {
+            headers: { Authorization: `Bearer ${transport.token}` },
+        });
+    }
+    catch {
+        logCorsHint(transport, '文件下载');
+        throw new AgentApiError('NETWORK_ERROR', '桥接文件下载失败(网络/CORS)', {
+            retryable: true,
+            details: { fileId: ref.fileId },
+        });
+    }
+    if (!response.ok) {
+        if (response.status === 401) {
+            throw new AgentApiError('UNAUTHORIZED', '桥接文件下载鉴权失败', {
+                details: { fileId: ref.fileId },
+            });
+        }
+        if (response.status === 404) {
+            throw new AgentApiError('FILE_NOT_FOUND', `桥接文件不存在: ${ref.fileId}`, { details: { fileId: ref.fileId } });
+        }
+        throw new AgentApiError('NETWORK_ERROR', `桥接文件下载失败(HTTP ${response.status})`, { retryable: true, details: { fileId: ref.fileId } });
+    }
+    const buffer = await response.arrayBuffer();
+    // fileName/mimeType 优先取引用自带;缺省回退响应 Content-Type 与通用名
+    const contentType = response.headers?.get?.('content-type');
+    return new File([buffer], ref.fileName ?? 'file', {
+        type: ref.mimeType ?? contentType ?? 'application/octet-stream',
+    });
+}
+/** 解析 fetch 实现:缺省取全局;环境无 fetch 时结构化报错(不裸抛 TypeError) */
+function resolveFetch(fetchImpl) {
+    const impl = fetchImpl ?? globalThis.fetch?.bind(globalThis);
+    if (impl === undefined) {
+        throw new AgentApiError('NETWORK_ERROR', '当前环境无 fetch,无法访问桥接', {
+            retryable: false,
+        });
+    }
+    return impl;
+}
+/**
+ * 命令 args 水合:`{file:{fileId,...}}` → 下载字节构造 File 后替换;
+ * 无 fileRef 的 args 原样返回(同引用,不发起请求)。失败以 AgentApiError
+ * 结构化上抛——调用方(bridgeClient)据此回 error 报文,不调用领域命令。
+ */
+export async function hydrateCommandArgs(args, transport, fetchImpl) {
+    if (typeof args !== 'object' || args === null)
+        return args;
+    const candidate = args.file;
+    if (!isFileRef(candidate))
+        return args;
+    const file = await downloadFile(candidate, transport, resolveFetch(fetchImpl));
+    return { ...args, file };
+}
+/** VideoExportResult 形状判定(带 Blob 的任务结果;不 import 具体命令模块) */
+function isBlobResult(value) {
+    if (typeof value !== 'object' || value === null)
+        return false;
+    const blob = value.blob;
+    return typeof Blob !== 'undefined' && blob instanceof Blob;
+}
+function isFileDescriptor(value) {
+    if (typeof value !== 'object' || value === null)
+        return false;
+    const candidate = value;
+    return (typeof candidate.fileId === 'string' &&
+        typeof candidate.fileName === 'string' &&
+        typeof candidate.mimeType === 'string' &&
+        typeof candidate.size === 'number');
+}
+async function uploadBlob(result, transport, fetchImpl) {
+    const url = `${transport.httpUrl}/v1/files`;
+    let response;
+    try {
+        response = await fetchImpl(url, {
+            method: 'POST',
+            headers: {
+                Authorization: `Bearer ${transport.token}`,
+                'X-File-Name': encodeURIComponent(result.fileName),
+                'Content-Type': result.mimeType || 'application/octet-stream',
+            },
+            body: result.blob,
+        });
+    }
+    catch {
+        logCorsHint(transport, '文件上传');
+        throw new AgentApiError('NETWORK_ERROR', '桥接文件上传失败(网络/CORS)', {
+            retryable: true,
+        });
+    }
+    if (!response.ok) {
+        throw new AgentApiError('NETWORK_ERROR', `桥接文件上传失败(HTTP ${response.status})`, { retryable: true });
+    }
+    const body = (await response.json());
+    if (!isFileDescriptor(body?.result)) {
+        throw new AgentApiError('NETWORK_ERROR', '桥接文件上传响应形状不符', {
+            retryable: true,
+        });
+    }
+    return body.result;
+}
+/**
+ * 任务结果脱水:succeeded 且 result 带 Blob → 上传到桥接,返回 result
+ * 换成 {fileId,fileName,mimeType,size} 的新快照(原始快照不改写);
+ * 其余快照同引用原样返回。上传失败返回 failed NETWORK_ERROR 投影
+ * (result 抹除)——绝不报告成功但缺文件。本函数不抛错。
+ */
+export async function dehydrateJobResult(snapshot, transport, fetchImpl) {
+    if (snapshot.state !== 'succeeded')
+        return snapshot;
+    if (!isBlobResult(snapshot.result))
+        return snapshot;
+    const source = snapshot.result;
+    try {
+        const descriptor = await uploadBlob(source, transport, resolveFetch(fetchImpl));
+        return {
+            ...snapshot,
+            result: {
+                fileId: descriptor.fileId,
+                fileName: descriptor.fileName,
+                mimeType: descriptor.mimeType,
+                size: descriptor.size,
+            },
+        };
+    }
+    catch (error) {
+        const normalized = error instanceof AgentApiError
+            ? error
+            : new AgentApiError('NETWORK_ERROR', '桥接文件上传失败', {
+                retryable: true,
+            });
+        const failed = {
+            ...snapshot,
+            state: 'failed',
+            error: {
+                code: normalized.code,
+                message: normalized.message,
+                retryable: normalized.retryable,
+                ...(normalized.details !== undefined
+                    ? { details: normalized.details }
+                    : {}),
+            },
+        };
+        // result 里的 Blob 绝不能上线:显式抹除
+        delete failed.result;
+        return failed;
+    }
+}

package/dist/agent/bridgeFiles.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=bridgeFiles.test.d.ts.map

package/dist/agent/bridgeFiles.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"bridgeFiles.test.d.ts","sourceRoot":"","sources":["../../src/agent/bridgeFiles.test.ts"],"names":[],"mappings":""}