@chatu-ai/builder-sdk 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 chatu-ai
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,25 @@
+# @chatu-ai/builder-sdk
+
+Framework-agnostic client for the ChatU **App Builder** (AI-driven app generation with a live sandbox preview).
+
+```ts
+import { createBuilderClient, CookieAuth } from '@chatu-ai/builder-sdk'
+
+const client = createBuilderClient({
+  restBase: 'https://your-chatu-host/web/Builder',
+  auth: new CookieAuth(),          // or new ApiKeyAuth('...')
+  transport,                       // streaming transport injected by the host (see docs)
+})
+
+const status = await client.sandbox.status(conversationId)
+const { previewUrl } = await client.sandbox.previewToken(conversationId)
+const versions = await client.versions.list(conversationId)
+```
+
+- Zod event schemas (`events.ts`) are the single source of truth for the streaming protocol
+- `parseBuilderEvent` + seq-based resume for reconnect-safe consumption
+- No login-state assumptions: bring your own `AuthProvider`
+
+Vue bindings: [`@chatu-ai/builder-sdk-vue`](https://www.npmjs.com/package/@chatu-ai/builder-sdk-vue). Mock client for UI dev: [`@chatu-ai/builder-sdk-mock`](https://www.npmjs.com/package/@chatu-ai/builder-sdk-mock).
+
+MIT

package/dist/agent3.d.ts

@@ -0,0 +1,22 @@
+/**
+ * agent3 SSE（BuilderController create/connect 直通流）→ BuilderEvent 翻译。
+ * P0 步骤一形态：服务端不做翻译，前端按 chatuse Message 形态推导事件（03 §2 语义）。
+ * 步骤二切 A2A 时本模块保留为 REST/SSE 传输的实现之一（同一 BuilderEvent 出口）。
+ *
+ * agent3 Message: { type: step|chunk|complete|error|status|input|dialog, content, sequenceNumber, xid }
+ *   content = Claude Agent SDK 原始消息（assistant text/tool_use、user tool_result、result...）
+ */
+import { BuilderEvent } from './events';
+/**
+ * 有状态翻译器：一个 xid 一个实例（跟踪 tool_use_id → 任务卡 id，用于 done 状态回填）
+ */
+export declare class Agent3Translator {
+    private readonly toolCards;
+    /**
+     * 翻译一条 SSE data 行（JSON 文本或服务端自产的 builder-ack/created-response）
+     * 返回 0..n 个事件（一条 assistant 消息可能含 text + 多个 tool_use）
+     */
+    translate(raw: unknown): BuilderEvent[];
+    private fromSdkMessage;
+    private resultState;
+}

package/dist/agent3.js

@@ -0,0 +1,137 @@
+/**
+ * agent3 SSE（BuilderController create/connect 直通流）→ BuilderEvent 翻译。
+ * P0 步骤一形态：服务端不做翻译，前端按 chatuse Message 形态推导事件（03 §2 语义）。
+ * 步骤二切 A2A 时本模块保留为 REST/SSE 传输的实现之一（同一 BuilderEvent 出口）。
+ *
+ * agent3 Message: { type: step|chunk|complete|error|status|input|dialog, content, sequenceNumber, xid }
+ *   content = Claude Agent SDK 原始消息（assistant text/tool_use、user tool_result、result...）
+ */
+import { BuilderEvent } from './events';
+/** 工具名 → 任务卡标签（规则化，07 §4 taskCardMapper 的前端镜像） */
+const TOOL_LABELS = {
+    Bash: '执行命令',
+    Write: '写入文件',
+    Edit: '修改文件',
+    MultiEdit: '批量修改',
+    Read: '读取文件',
+    Glob: '查找文件',
+    Grep: '搜索代码',
+    WebSearch: '搜索资料',
+    WebFetch: '获取网页',
+    Task: '子任务',
+};
+/**
+ * 有状态翻译器：一个 xid 一个实例（跟踪 tool_use_id → 任务卡 id，用于 done 状态回填）
+ */
+export class Agent3Translator {
+    toolCards = new Map();
+    /**
+     * 翻译一条 SSE data 行（JSON 文本或服务端自产的 builder-ack/created-response）
+     * 返回 0..n 个事件（一条 assistant 消息可能含 text + 多个 tool_use）
+     */
+    translate(raw) {
+        if (typeof raw !== 'object' || raw === null)
+            return [];
+        const m = raw;
+        // 服务端流前事件（BuilderController）
+        if (m.type === 'builder-ack' && m.sandbox) {
+            const parsed = BuilderEvent.safeParse({ kind: 'ack', xid: 'pending', seq: 0, sandbox: m.sandbox });
+            return parsed.success ? [parsed.data] : [];
+        }
+        if (m.type === 'created-response')
+            return []; // xid 由调用方从此事件取出，不产出 BuilderEvent
+        const xid = m.xid;
+        const seq = m.sequenceNumber;
+        if (!xid || typeof seq !== 'number')
+            return [];
+        const out = [];
+        switch (m.type) {
+            case 'chunk':
+            case 'step':
+                out.push(...this.fromSdkMessage(xid, seq, m.content));
+                break;
+            case 'complete':
+                out.push({ kind: 'done', xid, seq, state: this.resultState(m.content) });
+                break;
+            case 'error':
+                out.push({ kind: 'done', xid, seq, state: 'failed', error: errorText(m.content) });
+                break;
+            case 'status':
+                break; // 系统状态：P0 不映射（后续可映射 task_updated → taskCard）
+            default:
+                break;
+        }
+        return out
+            .map(e => BuilderEvent.safeParse(e))
+            .filter((r) => r.success)
+            .map(r => r.data);
+    }
+    fromSdkMessage(xid, seq, content) {
+        const events = [];
+        const message = content?.message ?? content;
+        const blocks = Array.isArray(message?.content) ? message.content : [];
+        const role = message?.role ?? content?.type;
+        for (const block of blocks) {
+            if (block?.type === 'text' && role === 'assistant' && typeof block.text === 'string' && block.text.trim()) {
+                events.push({ kind: 'message', xid, seq, role: 'assistant', text: block.text });
+            }
+            else if (block?.type === 'tool_use') {
+                const cardId = `tc_${block.id ?? seq}`;
+                this.toolCards.set(block.id, cardId);
+                events.push({
+                    kind: 'taskCard', xid, seq, id: cardId,
+                    label: TOOL_LABELS[block.name] ?? block.name ?? '执行工具',
+                    state: 'running',
+                    detail: describeInput(block.name, block.input),
+                });
+                // 文件变更事件（Write/Edit）
+                const path = block.input?.file_path ?? block.input?.path;
+                if ((block.name === 'Write' || block.name === 'Edit' || block.name === 'MultiEdit') && typeof path === 'string') {
+                    events.push({
+                        kind: 'fileDiff', xid, seq, path: relPath(path),
+                        action: block.name === 'Write' ? 'create' : 'modify',
+                        bytes: typeof block.input?.content === 'string' ? block.input.content.length : 0,
+                        truncated: false,
+                    });
+                }
+            }
+            else if (block?.type === 'tool_result') {
+                const cardId = this.toolCards.get(block.tool_use_id);
+                if (cardId) {
+                    events.push({
+                        kind: 'taskCard', xid, seq, id: cardId,
+                        label: '', // upsert 时保留原 label（reducer 以 id 合并；空 label 由 reducer 忽略）
+                        state: block.is_error ? 'failed' : 'done',
+                    });
+                }
+            }
+        }
+        return events;
+    }
+    resultState(content) {
+        const subtype = content?.subtype ?? content?.result?.subtype;
+        if (subtype === 'success')
+            return 'completed';
+        if (typeof subtype === 'string' && subtype.includes('cancel'))
+            return 'canceled';
+        if (content?.is_error)
+            return 'failed';
+        return 'completed';
+    }
+}
+function describeInput(tool, input) {
+    if (!input)
+        return undefined;
+    if (tool === 'Bash' && typeof input.command === 'string')
+        return input.command.slice(0, 80);
+    const p = input.file_path ?? input.path ?? input.pattern;
+    return typeof p === 'string' ? relPath(p).slice(0, 80) : undefined;
+}
+function relPath(p) {
+    return p.replace(/^\/workspace\//, '');
+}
+function errorText(content) {
+    if (typeof content === 'string')
+        return content;
+    return content?.message ?? content?.error ?? 'unknown error';
+}

package/dist/agent3.test.d.ts

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

package/dist/agent3.test.js

@@ -0,0 +1,47 @@
+import { describe, expect, it } from 'vitest';
+import { Agent3Translator } from './agent3';
+const X = 'xid-1';
+const sdk = (seq, type, content) => ({ xid: X, sequenceNumber: seq, type, content });
+describe('Agent3Translator', () => {
+    it('translates builder-ack into ack event with seq 0', () => {
+        const t = new Agent3Translator();
+        const evs = t.translate({ type: 'builder-ack', seq: 0, sandbox: { sandboxId: 'chat-use-abc', state: 'ready', previewUrl: 'https://chat-use-abc.n.y.com' } });
+        expect(evs).toHaveLength(1);
+        expect(evs[0]).toMatchObject({ kind: 'ack', seq: 0, sandbox: { sandboxId: 'chat-use-abc' } });
+    });
+    it('assistant text + tool_use -> message + running taskCard (+ fileDiff for Write)', () => {
+        const t = new Agent3Translator();
+        const evs = t.translate(sdk(3, 'chunk', {
+            type: 'assistant',
+            message: {
+                role: 'assistant',
+                content: [
+                    { type: 'text', text: '开始创建首页' },
+                    { type: 'tool_use', id: 'tu_1', name: 'Write', input: { file_path: '/workspace/src/app/page.tsx', content: 'export default 1' } },
+                ],
+            },
+        }));
+        expect(evs.map(e => e.kind)).toEqual(['message', 'taskCard', 'fileDiff']);
+        expect(evs[1]).toMatchObject({ kind: 'taskCard', id: 'tc_tu_1', label: '写入文件', state: 'running' });
+        expect(evs[2]).toMatchObject({ kind: 'fileDiff', path: 'src/app/page.tsx', action: 'create' });
+    });
+    it('tool_result marks matching card done/failed with empty label (state-only upsert)', () => {
+        const t = new Agent3Translator();
+        t.translate(sdk(1, 'chunk', { message: { role: 'assistant', content: [{ type: 'tool_use', id: 'tu_9', name: 'Bash', input: { command: 'npm i' } }] } }));
+        const evs = t.translate(sdk(2, 'step', { message: { role: 'user', content: [{ type: 'tool_result', tool_use_id: 'tu_9', is_error: true }] } }));
+        expect(evs).toHaveLength(1);
+        expect(evs[0]).toMatchObject({ kind: 'taskCard', id: 'tc_tu_9', state: 'failed', label: '' });
+    });
+    it('complete/error -> done', () => {
+        const t = new Agent3Translator();
+        expect(t.translate(sdk(9, 'complete', { subtype: 'success' }))[0]).toMatchObject({ kind: 'done', state: 'completed' });
+        expect(t.translate(sdk(10, 'error', { message: 'boom' }))[0]).toMatchObject({ kind: 'done', state: 'failed', error: 'boom' });
+    });
+    it('ignores status/created-response/garbage', () => {
+        const t = new Agent3Translator();
+        expect(t.translate(sdk(1, 'status', { subtype: 'init' }))).toEqual([]);
+        expect(t.translate({ type: 'created-response', xid: 'x' })).toEqual([]);
+        expect(t.translate('not json')).toEqual([]);
+        expect(t.translate({ type: 'chunk' })).toEqual([]); // 无 xid/seq
+    });
+});

package/dist/agent3Transport.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Agent3 SSE 直通传输 —— A2ATransport 的 REST/SSE 实现（P0 步骤一，对接 BuilderController）。
+ * 产出的是**已翻译**的 BuilderEvent（而非 A2A 原始事件），因此配套 client 需用 identity 解析。
+ */
+import type { AuthProvider } from './auth';
+import type { BuilderEvent } from './events';
+import type { ResilienceOptions } from './resume';
+export interface Agent3TransportOptions {
+    /** BuilderController 前缀，如 https://api.example.com/web/Builder */
+    baseUrl: string;
+    auth: AuthProvider;
+    fetchImpl?: typeof fetch;
+}
+export interface Agent3Transport {
+    stream(conversationId: string, prompt: string, opts?: {
+        agentId?: string;
+        attachments?: unknown[];
+    }): AsyncIterable<BuilderEvent>;
+    resubscribe(conversationId: string, xid: string, lastSeq: number): AsyncIterable<BuilderEvent>;
+    cancel(conversationId: string, xid: string): Promise<void>;
+}
+export declare function createAgent3Transport(options: Agent3TransportOptions): Agent3Transport;
+/**
+ * 便捷工厂：agent3 SSE 直通形态的完整 BuilderClient（P0 步骤一，chat-web USE_MOCK=false 即用此）。
+ * conversationId 通过闭包绑定到 transport（A2ATransport.resubscribe 只带 xid）。
+ */
+export declare function createAgent3Client(conversationId: string, options: Agent3TransportOptions & {
+    restBase?: string;
+    agentId?: string;
+    resilience?: ResilienceOptions;
+}): import("./client").BuilderClient;

package/dist/agent3Transport.js

@@ -0,0 +1,53 @@
+import { Agent3Translator } from './agent3';
+import { createBuilderClient } from './client';
+import { readSse } from './sse';
+export function createAgent3Transport(options) {
+    const { baseUrl, auth } = options;
+    async function* translated(src, translator) {
+        for await (const raw of src) {
+            for (const ev of translator.translate(raw))
+                yield ev;
+        }
+    }
+    return {
+        stream(conversationId, prompt, opts) {
+            const translator = new Agent3Translator();
+            const init = auth.apply({
+                method: 'POST',
+                headers: { 'content-type': 'application/json', accept: 'text/event-stream' },
+                body: JSON.stringify({ conversationId, prompt, agentId: opts?.agentId }),
+            });
+            return translated(readSse(`${baseUrl}/create`, init, { fetchImpl: options.fetchImpl }), translator);
+        },
+        resubscribe(conversationId, xid, lastSeq) {
+            const translator = new Agent3Translator();
+            const init = auth.apply({ method: 'GET', headers: { accept: 'text/event-stream' } });
+            const url = `${baseUrl}/connect?conversationId=${conversationId}&xid=${xid}&checkpoint=${lastSeq}`;
+            return translated(readSse(url, init, { fetchImpl: options.fetchImpl }), translator);
+        },
+        async cancel(conversationId, xid) {
+            const init = auth.apply({ method: 'POST' });
+            await (options.fetchImpl ?? fetch)(`${baseUrl}/cancel?conversationId=${conversationId}&xid=${xid}`, init);
+        },
+    };
+}
+/**
+ * 便捷工厂：agent3 SSE 直通形态的完整 BuilderClient（P0 步骤一，chat-web USE_MOCK=false 即用此）。
+ * conversationId 通过闭包绑定到 transport（A2ATransport.resubscribe 只带 xid）。
+ */
+export function createAgent3Client(conversationId, options) {
+    const transport = createAgent3Transport(options);
+    const a2aLike = {
+        stream: (cid, prompt, opts) => transport.stream(cid, prompt, { ...opts, agentId: opts?.agentId ?? options.agentId }),
+        resubscribe: (xid, lastSeq) => transport.resubscribe(conversationId, xid, lastSeq),
+        cancel: xid => transport.cancel(conversationId, xid),
+    };
+    return createBuilderClient({
+        restBase: options.restBase ?? options.baseUrl,
+        transport: a2aLike,
+        auth: options.auth,
+        fetchImpl: options.fetchImpl,
+        resilience: options.resilience,
+        parse: e => e, // transport 已产出 BuilderEvent
+    });
+}

package/dist/auth.d.ts

@@ -0,0 +1,13 @@
+/** auth provider 接口：内部=Cookie 会话；开放 API=API Key（P2）。（04 §1 约束 1） */
+export interface AuthProvider {
+    /** 为请求附加认证信息（headers / credentials 模式） */
+    apply(init: RequestInit): RequestInit;
+}
+export declare class CookieAuth implements AuthProvider {
+    apply(init: RequestInit): RequestInit;
+}
+export declare class ApiKeyAuth implements AuthProvider {
+    private readonly apiKey;
+    constructor(apiKey: string);
+    apply(init: RequestInit): RequestInit;
+}

package/dist/auth.js

@@ -0,0 +1,17 @@
+export class CookieAuth {
+    apply(init) {
+        return { ...init, credentials: 'include' };
+    }
+}
+export class ApiKeyAuth {
+    apiKey;
+    constructor(apiKey) {
+        this.apiKey = apiKey;
+    }
+    apply(init) {
+        return {
+            ...init,
+            headers: { ...(init.headers ?? {}), Authorization: `Bearer ${this.apiKey}` },
+        };
+    }
+}

package/dist/client.d.ts

@@ -0,0 +1,97 @@
+/**
+ * BuilderClient —— 08 §2 冻结 API 面的实现。
+ * A2A 传输层由宿主注入（chat-web 传入 libs/a2a-client 的包装），core 不重写传输。
+ */
+import type { AuthProvider } from './auth';
+import type { BuilderEvent, SandboxState } from './events';
+import { type ResilienceOptions } from './resume';
+export interface A2ATransport {
+    /** message/stream：发起生成，产出原始 A2A 事件 */
+    stream(conversationId: string, prompt: string, opts?: {
+        agentId?: string;
+        attachments?: unknown[];
+    }): AsyncIterable<unknown>;
+    /** tasks/resubscribe：按 task 重连（服务端回放 seq > lastSeq） */
+    resubscribe(xid: string, lastSeq: number): AsyncIterable<unknown>;
+    /** tasks/cancel */
+    cancel(xid: string): Promise<void>;
+}
+export interface BuilderClientOptions {
+    /** REST 前缀，如 https://api.example.com/web/builder */
+    restBase: string;
+    transport: A2ATransport;
+    auth: AuthProvider;
+    fetchImpl?: typeof fetch;
+    resilience?: ResilienceOptions;
+    /**
+     * 原始传输事件 → BuilderEvent 解析器。默认 A2A 解析；
+     * 传输层已产出 BuilderEvent 时（如 agent3 SSE 直通）传 identity：`e => e as BuilderEvent`
+     */
+    parse?: (raw: unknown) => BuilderEvent | null;
+}
+export interface SandboxStatus {
+    state: SandboxState;
+    previewUrl?: string;
+    devServer?: {
+        running: boolean;
+        lastError?: string;
+    };
+}
+export interface VersionInfo {
+    sha: string;
+    message: string;
+    filesChanged: number;
+    createdAt?: string;
+}
+export interface FileNode {
+    path: string;
+    type: 'file' | 'dir';
+    children?: FileNode[];
+}
+export interface BuilderClient {
+    chat: {
+        stream(conversationId: string, prompt: string, opts?: {
+            agentId?: string;
+            attachments?: unknown[];
+        }): AsyncIterable<BuilderEvent>;
+        resubscribe(conversationId: string, xid: string, lastSeq: number): AsyncIterable<BuilderEvent>;
+        cancel(conversationId: string, xid: string): Promise<void>;
+    };
+    sandbox: {
+        status(conversationId: string): Promise<SandboxStatus>;
+        heartbeat(conversationId: string, opts: {
+            visible: boolean;
+        }): Promise<void | {
+            ok?: boolean;
+            state?: SandboxState | string;
+        }>;
+        /** 一次性预览 token（06 §6.1）：返回可直接作 iframe src 的带 ?t= 的 URL */
+        previewToken(conversationId: string): Promise<{
+            token: string;
+            previewUrl: string;
+        }>;
+        /** 唤醒/确保沙箱（休眠 → 恢复快照 → 起 dev server；不发起 agent 会话） */
+        wake(conversationId: string): Promise<SandboxStatus>;
+    };
+    versions: {
+        list(conversationId: string, opts?: {
+            limit?: number;
+        }): Promise<VersionInfo[]>;
+        restore(conversationId: string, sha: string): Promise<void>;
+    };
+    files: {
+        tree(conversationId: string, opts?: {
+            path?: string;
+            ref?: string;
+        }): Promise<FileNode[]>;
+        read(conversationId: string, path: string, opts?: {
+            ref?: string;
+        }): Promise<string>;
+        downloadUrl(conversationId: string): string;
+    };
+}
+export declare function createBuilderClient(options: BuilderClientOptions): BuilderClient;
+export declare class BuilderApiError extends Error {
+    readonly status: number;
+    constructor(status: number, body: string);
+}

package/dist/client.js

@@ -0,0 +1,107 @@
+import { parseBuilderEvent } from './parse';
+import { resilientStream } from './resume';
+export function createBuilderClient(options) {
+    const { restBase, transport, auth } = options;
+    const doFetch = options.fetchImpl ?? fetch;
+    const parse = options.parse ?? parseBuilderEvent;
+    async function req(path, init = {}) {
+        const res = await doFetch(`${restBase}${path}`, auth.apply(init));
+        if (!res.ok)
+            throw new BuilderApiError(res.status, await res.text().catch(() => ''));
+        const ct = res.headers.get('content-type') ?? '';
+        if (!ct.includes('json'))
+            return (await res.text());
+        const json = await res.json();
+        return unwrapEnvelope(json);
+    }
+    /** 把原始 A2A 迭代器包装成解析后的迭代器 */
+    async function* parsed(src) {
+        for await (const raw of src)
+            yield parse(raw);
+    }
+    return {
+        chat: {
+            stream(conversationId, prompt, opts) {
+                // xid 在 ack 事件中获知，用于断线 reopen
+                let xid;
+                const base = resilientStream({
+                    open: () => parsed(transport.stream(conversationId, prompt, opts)),
+                    reopen: lastSeq => {
+                        if (!xid)
+                            throw new Error('cannot resubscribe before ack (xid unknown)');
+                        return parsed(transport.resubscribe(xid, lastSeq));
+                    },
+                }, options.resilience);
+                // 旁路捕获 xid
+                return (async function* () {
+                    for await (const ev of base) {
+                        if (ev.kind === 'ack')
+                            xid = ev.xid;
+                        yield ev;
+                    }
+                })();
+            },
+            resubscribe(_conversationId, xid, lastSeq) {
+                return resilientStream({
+                    open: () => parsed(transport.resubscribe(xid, lastSeq)),
+                    reopen: seq => parsed(transport.resubscribe(xid, seq)),
+                }, options.resilience);
+            },
+            cancel: (_conversationId, xid) => transport.cancel(xid),
+        },
+        sandbox: {
+            status: id => req(`/sandbox/${id}/status`),
+            heartbeat: (id, opts) => req(`/sandbox/${id}/heartbeat`, {
+                method: 'POST',
+                headers: { 'content-type': 'application/json' },
+                body: JSON.stringify(opts),
+            }),
+            previewToken: id => req(`/${id}/preview-token`),
+            wake: id => req(`/sandbox/${id}/wake`, { method: 'POST' }),
+        },
+        versions: {
+            // 服务端形状：{ versions: VersionInfo[] }（runtime 透传）
+            list: async (id, opts) => {
+                const r = await req(`/${id}/versions${opts?.limit ? `?limit=${opts.limit}` : ''}`);
+                return Array.isArray(r) ? r : (r.versions ?? []);
+            },
+            restore: async (id, sha) => { await req(`/${id}/versions/${sha}/restore`, { method: 'POST' }); },
+        },
+        files: {
+            // 服务端形状：{ tree: FileNode[] }
+            tree: async (id, opts) => {
+                const r = await req(`/${id}/files?${qs(opts)}`);
+                return Array.isArray(r) ? r : (r.tree ?? []);
+            },
+            read: (id, path, opts) => req(`/${id}/files/read?${qs({ path, ...opts })}`),
+            downloadUrl: id => `${restBase}/${id}/files/download`,
+        },
+    };
+}
+/**
+ * Dapi.Web 结果过滤器会把 object 返回包成 { code, data, message }（ContentResult 直通不包）。
+ * 统一拆信封：code !== 0 视为业务错误抛出；非信封形状原样返回。
+ */
+function unwrapEnvelope(json) {
+    if (json && typeof json === 'object' && 'code' in json && 'data' in json) {
+        const env = json;
+        if (env.code !== 0)
+            throw new BuilderApiError(200, env.message ?? `api code ${env.code}`);
+        return env.data;
+    }
+    return json;
+}
+export class BuilderApiError extends Error {
+    status;
+    constructor(status, body) {
+        super(`builder api ${status}: ${body.slice(0, 200)}`);
+        this.status = status;
+    }
+}
+function qs(obj) {
+    const p = new URLSearchParams();
+    for (const [k, v] of Object.entries(obj ?? {}))
+        if (v !== undefined)
+            p.set(k, v);
+    return p.toString();
+}