@chatu-ai/builder-sdk 0.9.6 → 0.10.0

package/dist/client.d.ts

@@ -269,6 +269,22 @@ export type ExecStreamEvent = {
     type: 'result';
     result: ExecResult;
 };
+/** 一次生成（run，技术方案 22 Phase 2）：创建即返回，事件另行订阅 */
+export interface RunMeta {
+    ok: boolean;
+    runId: string;
+    /** pending（准备沙箱中）| running | finished | failed */
+    state: string;
+    xid?: string | null;
+    error?: string | null;
+    createdAt?: string;
+}
+/** run 事件帧：id 用于断线续传（Last-Event-ID 语义），data 为原始载荷（与 v1 完全一致） */
+export interface RunEventFrame {
+    id: string;
+    event: string | null;
+    data: unknown;
+}
 export interface DeployInput {
     provider: 'edgeone';
     projectName: string;
@@ -435,6 +451,46 @@ export interface BuilderClient {
             signal?: AbortSignal;
         }): AsyncIterable<FunctionDeployStreamEvent>;
     };
+    /**
+     * v2 生成接口（技术方案 22 Phase 2）：创建 run 立即返回，不等沙箱冷启动；
+     * 事件用 `runs.events()` 订阅，断线自动从上次 id 续传。v1 的 create/connect/send 仍可用。
+     */
+    runs: {
+        /** 受理一次生成，立即返回 runId（沙箱准备过程会作为 run.phase 事件下发） */
+        start(input: {
+            conversationId: string;
+            prompt?: string;
+            message?: string;
+        } & Record<string, unknown>): Promise<RunMeta>;
+        /** run 状态（轮询兜底/调试） */
+        status(runId: string): Promise<RunMeta>;
+        /** 订阅事件；断线自动带上最后一帧的 id 重连（默认重试 5 次，退避 1s→8s） */
+        events(runId: string, opts?: {
+            after?: string | null;
+            signal?: AbortSignal;
+            maxRetries?: number;
+            retryBaseMs?: number;
+        }): AsyncIterable<RunEventFrame>;
+        /** 向进行中的 run 追加消息 */
+        send(runId: string, input: Record<string, unknown>): Promise<{
+            ok: boolean;
+            statusCode?: number;
+        }>;
+        /** 取消 run */
+        cancel(runId: string): Promise<{
+            ok: boolean;
+            cancelled?: boolean;
+        }>;
+    };
+    /**
+     * 生成事件里的单条消息全文（技术方案 22 S2）：平台把超大的工具结果改为"预览 + 引用"下发，
+     * 前端展开时用 `chatuRef`（`{xid}/{seq}`）回取完整内容。
+     */
+    runMessage(conversationId: string, xid: string, seq: number): Promise<{
+        ok: boolean;
+        error?: string;
+        message?: Record<string, unknown>;
+    }>;
     /** 沙箱终端（001/09 P2-A）：执行一条命令并流式回输出；AI 生成中会被拒绝（409） */
     exec(conversationId: string, command: string, opts?: {
         timeoutMs?: number;

package/dist/client.js

@@ -105,6 +105,16 @@ export function createBuilderClient(options) {
             deployFunctionStream: (id, input, o) => readNamedSse(`${restBase}/${id}/export/deploy-function/stream`, auth.apply({ method: 'POST', headers: { 'content-type': 'application/json', accept: 'text/event-stream' }, body: JSON.stringify(input), signal: o?.signal }), doFetch),
             deployStream: (id, input, o) => readNamedSse(`${restBase}/${id}/export/deploy/stream`, auth.apply({ method: 'POST', headers: { 'content-type': 'application/json', accept: 'text/event-stream' }, body: JSON.stringify(input), signal: o?.signal }), doFetch),
         },
+        runs: {
+            start: input => req(`/runs`, { method: 'POST', headers: { 'content-type': 'application/json' }, body: JSON.stringify(input) }),
+            status: runId => req(`/runs/${encPath(runId)}`),
+            send: (runId, input) => req(`/runs/${encPath(runId)}/messages`, { method: 'POST', headers: { 'content-type': 'application/json' }, body: JSON.stringify(input) }),
+            cancel: runId => req(`/runs/${encPath(runId)}/cancel`, { method: 'POST' }),
+            events: (runId, opts) => ({
+                [Symbol.asyncIterator]: () => readRunEvents(`${restBase}/runs/${encPath(runId)}/events`, auth, doFetch, opts),
+            }),
+        },
+        runMessage: (id, xid, seq) => req(`/${id}/runs/${encPath(xid)}/messages/${seq}`),
         exec: (id, command, o) => readNamedSse(`${restBase}/${id}/exec/stream`, auth.apply({ method: 'POST', headers: { 'content-type': 'application/json', accept: 'text/event-stream' }, body: JSON.stringify({ command, timeoutMs: o?.timeoutMs }), signal: o?.signal }), doFetch),
         data: {
             access: id => req(`/${id}/data-access`),
@@ -180,6 +190,93 @@ export class BuilderApiError extends Error {
     }
 }
 /** 读取带 event: 名的 SSE（log / result） */
+/**
+ * 订阅 run 事件：逐帧产出 { id, event, data }，断线后带 `after={最后一帧 id}` 自动重连。
+ * 这是 v2 相对 v1 的关键差别——v1 断线要靠调用方自己记 checkpoint 再发一次 connect。
+ */
+async function* readRunEvents(url, auth, doFetch, opts) {
+    let cursor = opts?.after ?? null;
+    const maxRetries = opts?.maxRetries ?? 5;
+    const retryBaseMs = opts?.retryBaseMs ?? 1000;
+    // 连续"没拿到任何新帧"的重连次数：有进展就清零，这样长任务可以无限续订，
+    // 而"连上就断且没数据"的坏情况不会变成死循环
+    let attempt = 0;
+    for (;;) {
+        const target = cursor ? `${url}?after=${encodeURIComponent(cursor)}` : url;
+        let res;
+        try {
+            res = await doFetch(target, auth.apply({ headers: { accept: 'text/event-stream' }, signal: opts?.signal }));
+        }
+        catch (err) {
+            if (opts?.signal?.aborted || attempt >= maxRetries)
+                throw err;
+            await new Promise(r => setTimeout(r, Math.min(8000, retryBaseMs * 2 ** attempt++)));
+            continue;
+        }
+        if (!res.ok || !res.body)
+            throw new BuilderApiError(res.status, await res.text().catch(() => ''));
+        const reader = res.body.getReader();
+        const decoder = new TextDecoder();
+        let buffer = '';
+        let id = null;
+        let eventName = null;
+        let ended = false;
+        let delivered = 0;
+        try {
+            for (;;) {
+                const { value, done } = await reader.read();
+                if (done)
+                    break;
+                buffer += decoder.decode(value, { stream: true });
+                let nl;
+                while ((nl = buffer.indexOf('\n')) >= 0) {
+                    const line = buffer.slice(0, nl).replace(/\r$/, '');
+                    buffer = buffer.slice(nl + 1);
+                    if (line.startsWith(':'))
+                        continue; // 心跳
+                    if (line.startsWith('id:')) {
+                        id = line.slice(3).trim();
+                        continue;
+                    }
+                    if (line.startsWith('event:')) {
+                        eventName = line.slice(6).trim();
+                        continue;
+                    }
+                    if (!line.startsWith('data:'))
+                        continue;
+                    const raw = line.slice(5).trim();
+                    if (!raw)
+                        continue;
+                    let data = raw;
+                    try {
+                        data = JSON.parse(raw);
+                    }
+                    catch { /* 原样 */ }
+                    if (id)
+                        cursor = id;
+                    delivered++;
+                    yield { id: id ?? '', event: eventName, data };
+                    if (eventName === 'done')
+                        ended = true;
+                    id = null;
+                    eventName = null;
+                }
+                if (ended)
+                    break;
+            }
+        }
+        finally {
+            reader.releaseLock();
+        }
+        if (ended || opts?.signal?.aborted)
+            return;
+        // 服务端把连接断了但 run 还没结束（部署/重启/网关超时）：带着 cursor 续订
+        attempt = delivered > 0 ? 0 : attempt + 1;
+        if (attempt > maxRetries)
+            return;
+        await new Promise(r => setTimeout(r, Math.min(8000, retryBaseMs * 2 ** Math.max(0, attempt - 1))));
+    }
+}
 async function* readNamedSse(url, init, doFetch) {
     const res = await doFetch(url, init);
     if (!res.ok || !res.body)

package/dist/runs.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/runs.test.js

@@ -0,0 +1,86 @@
+import { describe, expect, it } from 'vitest';
+import { createBuilderClient, CookieAuth } from './index';
+/** 把若干行组成一个 SSE 响应体 */
+const sse = (body) => new Response(new ReadableStream({
+    start(controller) {
+        controller.enqueue(new TextEncoder().encode(body));
+        controller.close();
+    },
+}), { status: 200, headers: { 'content-type': 'text/event-stream' } });
+const frame = (id, data, event) => `${event ? `event:${event}\n` : ''}id:${id}\ndata:${JSON.stringify(data)}\n\n`;
+function clientWith(handler) {
+    const urls = [];
+    const client = createBuilderClient({
+        restBase: 'https://api.test/web/Builder',
+        auth: new CookieAuth(),
+        transport: { stream: async function* () { }, resubscribe: async function* () { }, cancel: async () => { } },
+        fetchImpl: (async (url) => {
+            urls.push(String(url));
+            return handler(String(url));
+        }),
+    });
+    return { client, urls };
+}
+describe('runs.events（v2 事件订阅，技术方案 22 Phase 2）', () => {
+    it('逐帧产出 id/event/data，遇到 done 结束', async () => {
+        const { client } = clientWith(() => sse(frame('1-0', { type: 'run.phase', phase: 'sandbox' }) +
+            frame('2-0', { type: 'created-response', xid: 'x1' }) +
+            frame('3-0', { type: 'run.finished' }, 'done')));
+        const got = [];
+        for await (const f of client.runs.events('run-1'))
+            got.push(f);
+        expect(got.map(f => f.id)).toEqual(['1-0', '2-0', '3-0']);
+        expect(got[2].event).toBe('done');
+        expect(got[1].data.xid).toBe('x1');
+    });
+    it('中途断流会带着最后一帧的 id 续订（不重复投递已收到的帧）', async () => {
+        let call = 0;
+        const { client, urls } = clientWith(() => {
+            call += 1;
+            // 第一次：只吐两帧就结束（模拟 Web 重启/网关超时），没有 done
+            if (call === 1)
+                return sse(frame('1-0', { i: 1 }) + frame('2-0', { i: 2 }));
+            return sse(frame('3-0', { i: 3 }) + frame('4-0', { type: 'run.finished' }, 'done'));
+        });
+        const got = [];
+        for await (const f of client.runs.events('run-1', { maxRetries: 2, retryBaseMs: 1 }))
+            got.push(f);
+        expect(got.map(f => f.data.i ?? 'done')).toEqual([1, 2, 3, 'done']);
+        expect(urls[0]).not.toContain('after=');
+        expect(urls[1]).toContain('after=2-0');
+    });
+    it('可以从指定 id 开始订阅（页面刷新后接着看）', async () => {
+        const { client, urls } = clientWith(() => sse(frame('9-0', { i: 9 }, 'done')));
+        for await (const _ of client.runs.events('run-1', { after: '8-0' })) { /* drain */ }
+        expect(urls[0]).toContain('after=8-0');
+    });
+    it('心跳注释行被忽略', async () => {
+        const { client } = clientWith(() => sse(': ping\n\n' + frame('1-0', { i: 1 }, 'done')));
+        const got = [];
+        for await (const f of client.runs.events('run-1'))
+            got.push(f);
+        expect(got).toHaveLength(1);
+    });
+    it('一直有新帧就一直续订（长任务不该被重试次数掐断）', async () => {
+        let call = 0;
+        const { client } = clientWith(() => {
+            call += 1;
+            // 每次连上都给一帧新数据然后断开；第 4 次给 done
+            return call >= 4
+                ? sse(frame(`${call}-0`, { type: 'run.finished' }, 'done'))
+                : sse(frame(`${call}-0`, { i: call }));
+        });
+        const got = [];
+        for await (const f of client.runs.events('run-1', { maxRetries: 1, retryBaseMs: 1 }))
+            got.push(f);
+        expect(got).toHaveLength(4);
+    });
+    it('连上就断且没有任何数据时，重试用尽即结束（不死循环）', async () => {
+        const { client, urls } = clientWith(() => sse(''));
+        const got = [];
+        for await (const f of client.runs.events('run-1', { maxRetries: 2, retryBaseMs: 1 }))
+            got.push(f);
+        expect(got).toHaveLength(0);
+        expect(urls.length).toBe(3); // 首次 + 2 次重试
+    });
+});

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@chatu-ai/builder-sdk",
-  "version": "0.9.6",
+  "version": "0.10.0",
   "description": "ChatU Builder client SDK core: REST + streaming client, zod event schemas, seq resume",
   "license": "MIT",
   "type": "module",