@tbox-dev-js/sdk 0.1.0

package/dist/index.esm.js

@@ -0,0 +1,2951 @@
+/**
+ * @tbox/sdk — 常量定义
+ */
+/** 默认 API 基础 URL */
+const TBOX_BASE_URL = 'https://o.tbox.cn';
+/** SDK 版本号 */
+const SDK_VERSION = '1.0.0';
+/** SDK 版本标识 header key */
+const SDK_VERSION_HEADER = 'X-Tbox-SDK-Version';
+
+/**
+ * @tbox/sdk — 分层错误体系
+ *
+ * 对齐 coze-js 的 error.ts 设计：
+ * TboxError → APIError → 按 HTTP 状态码的子类
+ */
+/** 所有 SDK 错误的基类 */
+class TboxError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'TboxError';
+        Object.setPrototypeOf(this, new.target.prototype);
+    }
+}
+/** API 调用错误，包含 HTTP 状态码和业务错误信息 */
+class APIError extends TboxError {
+    constructor(status, errorCode, errorMsg, traceId, rawResponse) {
+        const message = errorMsg ?? `API error (status ${status})`;
+        super(message);
+        this.name = 'APIError';
+        this.status = status;
+        this.errorCode = errorCode;
+        this.errorMsg = errorMsg;
+        this.traceId = traceId;
+        this.rawResponse = rawResponse;
+    }
+    /**
+     * Factory: create the appropriate error subclass based on HTTP status code.
+     */
+    static generate(status, body) {
+        const errorCode = body?.errorCode ?? (body?.code != null ? String(body.code) : undefined) ?? body?.resultCode;
+        const errorMsg = body?.errorMsg ?? body?.msg ?? body?.resultDesc;
+        const traceId = body?.traceId;
+        switch (status) {
+            case 400:
+                return new BadRequestError(errorCode, errorMsg, traceId, body);
+            case 401:
+                return new AuthenticationError(errorCode, errorMsg, traceId, body);
+            case 403:
+                return new ForbiddenError(errorCode, errorMsg, traceId, body);
+            case 404:
+                return new NotFoundError(errorCode, errorMsg, traceId, body);
+            case 429:
+                return new RateLimitError(errorCode, errorMsg, traceId, body);
+            case 500:
+                return new InternalServerError(errorCode, errorMsg, traceId, body);
+            case 502:
+                return new GatewayError(errorCode, errorMsg, traceId, body);
+            default:
+                return new APIError(status, errorCode, errorMsg, traceId, body);
+        }
+    }
+}
+class BadRequestError extends APIError {
+    constructor(errorCode, errorMsg, traceId, rawResponse) {
+        super(400, errorCode, errorMsg, traceId, rawResponse);
+        this.name = 'BadRequestError';
+    }
+}
+class AuthenticationError extends APIError {
+    constructor(errorCode, errorMsg, traceId, rawResponse) {
+        super(401, errorCode, errorMsg, traceId, rawResponse);
+        this.name = 'AuthenticationError';
+    }
+}
+class ForbiddenError extends APIError {
+    constructor(errorCode, errorMsg, traceId, rawResponse) {
+        super(403, errorCode, errorMsg, traceId, rawResponse);
+        this.name = 'ForbiddenError';
+    }
+}
+class NotFoundError extends APIError {
+    constructor(errorCode, errorMsg, traceId, rawResponse) {
+        super(404, errorCode, errorMsg, traceId, rawResponse);
+        this.name = 'NotFoundError';
+    }
+}
+class RateLimitError extends APIError {
+    constructor(errorCode, errorMsg, traceId, rawResponse) {
+        super(429, errorCode, errorMsg, traceId, rawResponse);
+        this.name = 'RateLimitError';
+    }
+}
+class InternalServerError extends APIError {
+    constructor(errorCode, errorMsg, traceId, rawResponse) {
+        super(500, errorCode, errorMsg, traceId, rawResponse);
+        this.name = 'InternalServerError';
+    }
+}
+class GatewayError extends APIError {
+    constructor(errorCode, errorMsg, traceId, rawResponse) {
+        super(502, errorCode, errorMsg, traceId, rawResponse);
+        this.name = 'GatewayError';
+    }
+}
+/** Network unreachable error */
+class NetworkError extends TboxError {
+    constructor(message, cause) {
+        super(message);
+        this.name = 'NetworkError';
+        this.cause = cause;
+    }
+}
+/** Request timeout error */
+class TimeoutError extends TboxError {
+    constructor(timeout) {
+        super(`Request timed out after ${timeout}ms`);
+        this.name = 'TimeoutError';
+        this.timeout = timeout;
+    }
+}
+/** JSON parse error */
+class ParseError extends TboxError {
+    constructor(message, responseText) {
+        super(message);
+        this.name = 'ParseError';
+        this.responseText = responseText;
+    }
+}
+
+/**
+ * @tbox/sdk — APIClient 核心基类
+ *
+ * 对齐 coze-js 的 core.ts 设计：
+ * - Token 管理（静态字符串 / 动态函数）
+ * - 请求构建（JSON / FormData / SSE）
+ * - 响应解包（兼容多种服务端格式）
+ * - 错误映射（HTTP 状态码 → 错误子类）
+ */
+/**
+ * Check if a result field is a knowledge-style nested wrapper:
+ * { response: {...}, success: boolean, errorType?: string }
+ */
+function isKnowledgeWrapper(value) {
+    return (typeof value === 'object' &&
+        value !== null &&
+        'response' in value &&
+        'success' in value);
+}
+/**
+ * Core request engine. All Resource classes call methods on this via `this._client`.
+ */
+class APIClient {
+    constructor(options) {
+        this.baseURL = (options.baseURL ?? TBOX_BASE_URL).replace(/\/$/, '');
+        this.token = options.token;
+        this.timeout = options.timeout;
+        this.debug = options.debug ?? false;
+        this.defaultHeaders = options.headers;
+    }
+    /** Resolve the current token value (supports async token functions). */
+    async getToken() {
+        if (typeof this.token === 'function') {
+            return this.token();
+        }
+        return this.token;
+    }
+    /** JSON POST request — returns unwrapped business data. */
+    async post(path, body, options) {
+        const url = this.buildUrl(path, options);
+        const headers = await this.buildHeaders(options, 'application/json;charset=UTF-8');
+        this.debugLog(options, `POST ${url}`, body);
+        const response = await this.fetchWithTimeout(url, {
+            method: 'POST',
+            headers,
+            body: body != null ? JSON.stringify(body) : undefined,
+            signal: options?.signal,
+        }, options);
+        return this.parseAndUnwrap(response, options);
+    }
+    /** GET request — query params auto-appended to URL. */
+    async get(path, params, options) {
+        let url = this.buildUrl(path, options);
+        if (params) {
+            const searchParams = new URLSearchParams();
+            for (const [key, value] of Object.entries(params)) {
+                if (value !== undefined) {
+                    searchParams.append(key, String(value));
+                }
+            }
+            const queryString = searchParams.toString();
+            if (queryString) {
+                url += `?${queryString}`;
+            }
+        }
+        const headers = await this.buildHeaders(options);
+        this.debugLog(options, `GET ${url}`);
+        const response = await this.fetchWithTimeout(url, {
+            method: 'GET',
+            headers,
+            signal: options?.signal,
+        }, options);
+        return this.parseAndUnwrap(response, options);
+    }
+    /** FormData POST request (file uploads). Content-Type is set automatically by fetch. */
+    async postFormData(path, formData, options) {
+        const url = this.buildUrl(path, options);
+        const headers = await this.buildHeaders(options);
+        // Do NOT set Content-Type — fetch/browser will set multipart/form-data with boundary
+        delete headers['Content-Type'];
+        this.debugLog(options, `POST (FormData) ${url}`);
+        const response = await this.fetchWithTimeout(url, {
+            method: 'POST',
+            headers,
+            body: formData,
+            signal: options?.signal,
+        }, options);
+        return this.parseAndUnwrap(response, options);
+    }
+    /** SSE streaming POST request — yields SSEEvent objects. */
+    async *postStream(path, body, options) {
+        const url = this.buildUrl(path, options);
+        const headers = await this.buildHeaders(options, 'application/json;charset=UTF-8');
+        this.debugLog(options, `POST (stream) ${url}`, body);
+        const response = await this.fetchWithTimeout(url, {
+            method: 'POST',
+            headers,
+            body: body != null ? JSON.stringify(body) : undefined,
+            signal: options?.signal,
+        }, options);
+        if (!response.ok) {
+            const raw = await this.safeParseJson(response);
+            throw APIError.generate(response.status, raw ?? undefined);
+        }
+        if (!response.body) {
+            throw new ParseError('Response body is null — streaming not supported');
+        }
+        yield* this.parseSSEStream(response);
+    }
+    // ================================================================
+    // Internal helpers
+    // ================================================================
+    buildUrl(path, options) {
+        const base = options?.baseURL?.replace(/\/$/, '') ?? this.baseURL;
+        return `${base}${path}`;
+    }
+    async buildHeaders(options, contentType) {
+        const token = await this.getToken();
+        const headers = {
+            Authorization: token,
+            [SDK_VERSION_HEADER]: SDK_VERSION,
+            ...this.defaultHeaders,
+            ...options?.headers,
+        };
+        if (contentType) {
+            headers['Content-Type'] = contentType;
+        }
+        return headers;
+    }
+    async fetchWithTimeout(url, init, options) {
+        const timeoutMs = options?.timeout ?? this.timeout;
+        if (!timeoutMs) {
+            try {
+                return await fetch(url, init);
+            }
+            catch (error) {
+                throw new NetworkError('Network request failed', error instanceof Error ? error : undefined);
+            }
+        }
+        const controller = new AbortController();
+        const existingSignal = init.signal;
+        // Merge external signal with timeout signal
+        if (existingSignal) {
+            existingSignal.addEventListener('abort', () => controller.abort(existingSignal.reason));
+        }
+        const timer = setTimeout(() => controller.abort('timeout'), timeoutMs);
+        try {
+            return await fetch(url, { ...init, signal: controller.signal });
+        }
+        catch (error) {
+            if (controller.signal.aborted && controller.signal.reason === 'timeout') {
+                throw new TimeoutError(timeoutMs);
+            }
+            throw new NetworkError('Network request failed', error instanceof Error ? error : undefined);
+        }
+        finally {
+            clearTimeout(timer);
+        }
+    }
+    async parseAndUnwrap(response, options) {
+        if (!response.ok) {
+            const raw = await this.safeParseJson(response);
+            throw APIError.generate(response.status, raw ?? undefined);
+        }
+        const raw = await this.parseJsonResponse(response);
+        this.debugLog(options, 'Response:', raw);
+        return this.unwrapResponse(raw, response.status);
+    }
+    /**
+     * Unwrap server response — extract business data from various envelope formats.
+     *
+     * Priority: data > resultObj > result.response (knowledge) > result > raw
+     */
+    unwrapResponse(raw, httpStatus) {
+        // Check outer success flag
+        if (raw.success === false) {
+            throw APIError.generate(httpStatus, raw);
+        }
+        // Priority 1: data field
+        if (raw.data !== undefined) {
+            return raw.data;
+        }
+        // Priority 2: resultObj field
+        if (raw.resultObj !== undefined) {
+            return raw.resultObj;
+        }
+        // Priority 3: result field (may be knowledge wrapper)
+        if (raw.result !== undefined) {
+            if (isKnowledgeWrapper(raw.result)) {
+                if (raw.result.success === false) {
+                    throw APIError.generate(httpStatus, {
+                        ...raw,
+                        errorMsg: raw.result.errorType ?? raw.errorMsg,
+                    });
+                }
+                return raw.result.response;
+            }
+            return raw.result;
+        }
+        // Fallback: return the entire raw response if it has meaningful fields,
+        // otherwise throw a ParseError to avoid silently returning an unexpected shape.
+        if (raw.success !== undefined || raw.code !== undefined || raw.resultCode !== undefined) {
+            return raw;
+        }
+        throw new ParseError('Unexpected response format — unable to extract business data', JSON.stringify(raw));
+    }
+    /** Parse JSON response using ArrayBuffer + TextDecoder for correct UTF-8 handling. */
+    async parseJsonResponse(response) {
+        let text;
+        try {
+            const buffer = await response.arrayBuffer();
+            text = new TextDecoder('utf-8').decode(buffer);
+        }
+        catch {
+            throw new ParseError('Failed to read response body');
+        }
+        try {
+            return JSON.parse(text);
+        }
+        catch {
+            throw new ParseError('Failed to parse response JSON', text);
+        }
+    }
+    /** Safely parse JSON without throwing (for error responses). */
+    async safeParseJson(response) {
+        try {
+            const buffer = await response.arrayBuffer();
+            const text = new TextDecoder('utf-8').decode(buffer);
+            return JSON.parse(text);
+        }
+        catch {
+            return null;
+        }
+    }
+    /** Parse SSE stream from ReadableStream. */
+    async *parseSSEStream(response) {
+        const reader = response.body.getReader();
+        const decoder = new TextDecoder();
+        let buffer = '';
+        try {
+            while (true) {
+                const { done, value } = await reader.read();
+                if (done)
+                    break;
+                buffer += decoder.decode(value, { stream: true });
+                const lines = buffer.split('\n');
+                buffer = lines.pop() ?? '';
+                for (const line of lines) {
+                    const trimmed = line.trim();
+                    if (trimmed.startsWith('data: ')) {
+                        const data = trimmed.slice(6).trim();
+                        if (data === '[DONE]')
+                            return;
+                        yield { data };
+                    }
+                }
+            }
+        }
+        finally {
+            reader.releaseLock();
+        }
+    }
+    /** Output debug log when debug mode is enabled. */
+    debugLog(options, ...messages) {
+        const isDebug = options?.debug ?? this.debug;
+        if (isDebug) {
+            console.log('[TboxSDK]', ...messages);
+        }
+    }
+}
+
+/**
+ * @tbox/sdk — APIResource 基类
+ *
+ * 所有 Resource 子类（Knowledge、Plugins 等）继承此类，
+ * 通过 this._client 引用 APIClient 发起请求。
+ */
+class APIResource {
+    constructor(client) {
+        this._client = client;
+    }
+}
+
+/**
+ * @tbox/sdk — Knowledge Documents sub-resource
+ *
+ * Handles knowledge base creation and update (multipart/form-data uploads).
+ */
+/** Build FormData for knowledge base creation. */
+function buildCreateFormData(params) {
+    const formData = new FormData();
+    formData.append('file', params.file);
+    formData.append('type', params.type);
+    if (params.tableSchema) {
+        formData.append('tableSchema', JSON.stringify(params.tableSchema));
+    }
+    if (params.indexColumns) {
+        for (const col of params.indexColumns) {
+            formData.append('indexColumns', col);
+        }
+    }
+    return formData;
+}
+/** Build FormData for knowledge base update. */
+function buildUpdateFormData(params) {
+    const formData = new FormData();
+    formData.append('documentId', params.documentId);
+    formData.append('file', params.file);
+    formData.append('type', params.type);
+    if (params.updateMode) {
+        formData.append('updateMode', params.updateMode);
+    }
+    if (params.tableSchema) {
+        formData.append('tableSchema', JSON.stringify(params.tableSchema));
+    }
+    if (params.indexColumns) {
+        for (const col of params.indexColumns) {
+            formData.append('indexColumns', col);
+        }
+    }
+    return formData;
+}
+class Documents extends APIResource {
+    /**
+     * Create a knowledge base by uploading a file.
+     *
+     * POST /openapi/v1/knowledge/createKnowledgeBaseByDataSet
+     * Content-Type: multipart/form-data
+     */
+    async create(params, options) {
+        const formData = buildCreateFormData(params);
+        return this._client.postFormData('/openapi/v1/knowledge/createKnowledgeBaseByDataSet', formData, options);
+    }
+    /**
+     * Update an existing knowledge base document.
+     *
+     * POST /openapi/v1/knowledge/updateDocument
+     * Content-Type: multipart/form-data
+     */
+    async update(params, options) {
+        const formData = buildUpdateFormData(params);
+        return this._client.postFormData('/openapi/v1/knowledge/updateDocument', formData, options);
+    }
+}
+
+/**
+ * @tbox/sdk — Knowledge Resource
+ *
+ * Provides knowledge base list, semantic retrieval, and document management.
+ */
+class Knowledge extends APIResource {
+    constructor(client) {
+        super(client);
+        this.documents = new Documents(client);
+    }
+    /**
+     * Query knowledge base list.
+     *
+     * GET /api/datasets/queryDatasetsList
+     */
+    async list(params, options) {
+        return this._client.get('/api/datasets/queryDatasetsList', params, options);
+    }
+    /**
+     * Semantic retrieval against a knowledge base.
+     *
+     * POST /api/datasets/retrieve
+     */
+    async retrieve(params, options) {
+        return this._client.post('/api/datasets/retrieve', params, options);
+    }
+}
+
+/**
+ * @tbox/sdk — ResourceSchema 类型体系
+ *
+ * 用 JSON Schema 风格统一描述所有 API 资源的入参、出参和元信息，
+ * 端侧可据此动态渲染表单、校验参数、生成配置。
+ *
+ * 设计原则：
+ * - 对齐 JSON Schema Draft 7 的 property 描述格式
+ * - 每个 API 操作（Operation）独立描述入参 + 出参 schema
+ * - 所有资源通过 ResourceDefinition 统一注册
+ * - 支持嵌套子资源（如 knowledge.documents）
+ */
+// ================================================================
+// Schema Registry — 统一注册和查询
+// ================================================================
+/** Registry that holds all resource definitions */
+class SchemaRegistry {
+    constructor() {
+        this.resources = new Map();
+    }
+    /** Register a resource definition */
+    register(definition) {
+        this.resources.set(definition.name, definition);
+    }
+    /** Get a resource definition by name */
+    get(name) {
+        return this.resources.get(name);
+    }
+    /** Get all registered resource definitions */
+    list() {
+        return Array.from(this.resources.values());
+    }
+    /** Get a specific operation by resource name and operation ID */
+    getOperation(resourceName, operationId) {
+        const resource = this.resources.get(resourceName);
+        if (!resource)
+            return undefined;
+        const operation = resource.operations.find(op => op.operationId === operationId);
+        if (operation)
+            return operation;
+        // Search in sub-resources
+        for (const subResource of resource.subResources ?? []) {
+            const subOperation = subResource.operations.find(op => op.operationId === operationId);
+            if (subOperation)
+                return subOperation;
+        }
+        return undefined;
+    }
+    /** Export all schemas as a plain JSON-serializable object */
+    toJSON() {
+        const result = {};
+        for (const [name, definition] of this.resources) {
+            result[name] = definition;
+        }
+        return result;
+    }
+}
+
+/**
+ * @tbox/sdk — Knowledge 模块 ResourceSchema 定义
+ *
+ * 用 JSON Schema 风格描述知识库的 4 个核心 API 操作，
+ * 端侧可据此动态渲染表单、校验参数、生成配置。
+ */
+/** Knowledge documents sub-resource schema */
+const documentsResource = {
+    name: 'documents',
+    displayName: '知识库文档',
+    description: '知识库文档的创建和更新（文件上传）',
+    operations: [
+        {
+            operationId: 'create',
+            summary: '创建知识库',
+            description: '上传文件创建新的知识库，支持结构化（STRUCTURED）和非结构化（UNSTRUCTURED）两种类型',
+            method: 'POST',
+            path: '/openapi/v1/knowledge/createKnowledgeBaseByDataSet',
+            contentType: 'multipart/form-data',
+            params: {
+                type: 'object',
+                properties: {
+                    file: {
+                        type: 'file',
+                        description: '上传的文件（如 .xlsx、.csv、.pdf 等）',
+                        required: true,
+                        format: 'file-upload',
+                    },
+                    type: {
+                        type: 'string',
+                        description: '知识库类型',
+                        required: true,
+                        enum: ['STRUCTURED', 'UNSTRUCTURED'],
+                        default: 'STRUCTURED',
+                        format: 'select',
+                    },
+                    tableSchema: {
+                        type: 'object',
+                        description: '表结构定义（STRUCTURED 类型必填），JSON 格式',
+                        required: false,
+                        format: 'json-editor',
+                        properties: {
+                            name: {
+                                type: 'string',
+                                description: '表名',
+                                required: true,
+                            },
+                            description: {
+                                type: 'string',
+                                description: '表描述',
+                                required: false,
+                            },
+                            columns: {
+                                type: 'array',
+                                description: '列定义列表',
+                                required: true,
+                                items: {
+                                    type: 'object',
+                                    properties: {
+                                        name: {
+                                            type: 'string',
+                                            description: '列名',
+                                            required: true,
+                                        },
+                                        dataType: {
+                                            type: 'string',
+                                            description: '数据类型',
+                                            enum: ['STRING', 'INTEGER', 'FLOAT', 'BOOLEAN', 'DATE'],
+                                            default: 'STRING',
+                                        },
+                                        primaryKey: {
+                                            type: 'boolean',
+                                            description: '是否主键',
+                                            default: false,
+                                        },
+                                        required: {
+                                            type: 'boolean',
+                                            description: '是否必填',
+                                            default: false,
+                                        },
+                                        description: {
+                                            type: 'string',
+                                            description: '列描述',
+                                        },
+                                        defaultValue: {
+                                            type: 'string',
+                                            description: '默认值',
+                                        },
+                                        order: {
+                                            type: 'integer',
+                                            description: '排序序号',
+                                            minimum: 0,
+                                        },
+                                    },
+                                },
+                            },
+                        },
+                    },
+                    indexColumns: {
+                        type: 'array',
+                        description: '索引列名列表',
+                        required: false,
+                        items: {
+                            type: 'string',
+                            description: '列名',
+                        },
+                    },
+                },
+                required: ['file', 'type'],
+            },
+            response: {
+                type: 'object',
+                properties: {
+                    documentId: {
+                        type: 'string',
+                        description: '创建后的文档 ID，用于后续更新操作',
+                    },
+                },
+                required: ['documentId'],
+            },
+            tags: ['knowledge', 'write'],
+        },
+        {
+            operationId: 'update',
+            summary: '更新知识库文档',
+            description: '上传新文件更新已有的知识库文档，支持覆盖（OVERWRITE）和增量（UPSERT）两种模式',
+            method: 'POST',
+            path: '/openapi/v1/knowledge/updateDocument',
+            contentType: 'multipart/form-data',
+            params: {
+                type: 'object',
+                properties: {
+                    documentId: {
+                        type: 'string',
+                        description: '要更新的文档 ID（从创建响应中获取）',
+                        required: true,
+                    },
+                    file: {
+                        type: 'file',
+                        description: '上传的新文件',
+                        required: true,
+                        format: 'file-upload',
+                    },
+                    type: {
+                        type: 'string',
+                        description: '知识库类型',
+                        required: true,
+                        enum: ['STRUCTURED', 'UNSTRUCTURED'],
+                        format: 'select',
+                    },
+                    updateMode: {
+                        type: 'string',
+                        description: '更新模式',
+                        required: false,
+                        enum: ['OVERWRITE', 'UPSERT'],
+                        default: 'UPSERT',
+                        format: 'select',
+                    },
+                    tableSchema: {
+                        type: 'object',
+                        description: '表结构定义（同创建接口的 tableSchema）',
+                        required: false,
+                        format: 'json-editor',
+                        properties: {
+                            name: { type: 'string', description: '表名', required: true },
+                            description: { type: 'string', description: '表描述' },
+                            columns: {
+                                type: 'array',
+                                description: '列定义列表',
+                                required: true,
+                                items: {
+                                    type: 'object',
+                                    properties: {
+                                        name: { type: 'string', description: '列名', required: true },
+                                        dataType: { type: 'string', description: '数据类型', enum: ['STRING', 'INTEGER', 'FLOAT', 'BOOLEAN', 'DATE'] },
+                                        primaryKey: { type: 'boolean', description: '是否主键' },
+                                        required: { type: 'boolean', description: '是否必填' },
+                                        description: { type: 'string', description: '列描述' },
+                                        defaultValue: { type: 'string', description: '默认值' },
+                                        order: { type: 'integer', description: '排序序号', minimum: 0 },
+                                    },
+                                },
+                            },
+                        },
+                    },
+                    indexColumns: {
+                        type: 'array',
+                        description: '索引列名列表',
+                        required: false,
+                        items: { type: 'string', description: '列名' },
+                    },
+                },
+                required: ['documentId', 'file', 'type'],
+            },
+            response: {
+                type: 'object',
+                properties: {
+                    documentId: {
+                        type: 'string',
+                        description: '更新后的文档 ID',
+                    },
+                },
+                required: ['documentId'],
+            },
+            tags: ['knowledge', 'write'],
+        },
+    ],
+};
+/** Knowledge resource schema — the complete definition */
+const knowledgeSchema = {
+    name: 'knowledge',
+    displayName: '知识库',
+    description: '知识库管理，包括列表查询、语义检索、文档创建和更新',
+    operations: [
+        {
+            operationId: 'list',
+            summary: '查询知识库列表',
+            description: '分页查询当前账号下的知识库列表，支持按名称模糊搜索',
+            method: 'GET',
+            path: '/api/datasets/queryDatasetsList',
+            contentType: 'none',
+            params: {
+                type: 'object',
+                properties: {
+                    name: {
+                        type: 'string',
+                        description: '知识库名称（模糊搜索）',
+                        required: false,
+                    },
+                    pageNo: {
+                        type: 'integer',
+                        description: '页码，从 1 开始',
+                        required: false,
+                        default: 1,
+                        minimum: 1,
+                    },
+                    pageSize: {
+                        type: 'integer',
+                        description: '每页条数',
+                        required: false,
+                        default: 10,
+                        minimum: 1,
+                        maximum: 100,
+                    },
+                },
+            },
+            response: {
+                type: 'object',
+                properties: {
+                    data: {
+                        type: 'array',
+                        description: '知识库列表',
+                        items: {
+                            type: 'object',
+                            properties: {
+                                datasetId: { type: 'string', description: '知识库 ID' },
+                                name: { type: 'string', description: '知识库名称' },
+                                description: { type: 'string', description: '知识库描述' },
+                                type: { type: 'string', description: '知识库类型', enum: ['STRUCTURED', 'UNSTRUCTURED'] },
+                                documentCount: { type: 'integer', description: '文档数量' },
+                                storageSize: { type: 'number', description: '存储大小' },
+                                createdAt: { type: 'string', description: '创建时间' },
+                                updatedAt: { type: 'string', description: '更新时间' },
+                            },
+                        },
+                    },
+                    totalCount: {
+                        type: 'integer',
+                        description: '总条数',
+                    },
+                },
+                required: ['data', 'totalCount'],
+            },
+            tags: ['knowledge', 'read'],
+        },
+        {
+            operationId: 'retrieve',
+            summary: '语义检索',
+            description: '对指定知识库进行语义检索，返回与查询文本最相关的文档片段',
+            method: 'POST',
+            path: '/api/datasets/retrieve',
+            contentType: 'application/json',
+            params: {
+                type: 'object',
+                properties: {
+                    datasetId: {
+                        type: 'string',
+                        description: '知识库 ID',
+                        required: true,
+                    },
+                    query: {
+                        type: 'string',
+                        description: '检索查询文本',
+                        required: true,
+                        format: 'textarea',
+                    },
+                    topK: {
+                        type: 'integer',
+                        description: '返回结果数量上限',
+                        required: false,
+                        default: 5,
+                        minimum: 1,
+                        maximum: 50,
+                    },
+                    scoreThreshold: {
+                        type: 'number',
+                        description: '最低相关度分数阈值 (0~1)',
+                        required: false,
+                        minimum: 0,
+                        maximum: 1,
+                        example: 0.5,
+                    },
+                },
+                required: ['datasetId', 'query'],
+            },
+            response: {
+                type: 'object',
+                properties: {
+                    data: {
+                        type: 'array',
+                        description: '检索结果列表',
+                        items: {
+                            type: 'object',
+                            properties: {
+                                content: { type: 'string', description: '文档片段内容' },
+                                score: { type: 'number', description: '相关度分数 (0~1)' },
+                                originFileName: { type: 'string', description: '来源文件名' },
+                                documentId: { type: 'string', description: '来源文档 ID' },
+                                metadata: { type: 'object', description: '元数据', properties: {} },
+                            },
+                        },
+                    },
+                },
+                required: ['data'],
+            },
+            tags: ['knowledge', 'read'],
+        },
+    ],
+    subResources: [documentsResource],
+};
+
+/**
+ * @tbox/sdk — TboxAPI 入口类
+ *
+ * SDK 的唯一入口，继承 APIClient，通过属性访问子模块。
+ * 内置 SchemaRegistry，自动注册所有资源的 JSON Schema 定义。
+ */
+class TboxAPI extends APIClient {
+    constructor(options) {
+        super(options);
+        this.knowledge = new Knowledge(this);
+        // Initialize schema registry with all resource schemas
+        this.schemas = new SchemaRegistry();
+        this.schemas.register(knowledgeSchema);
+    }
+}
+
+/**
+ * @tbox/sdk — KnowledgeClient
+ *
+ * Configuration-driven, multi-knowledge-base client.
+ * Reuses the unified ClientOptions (token/baseURL/timeout) from core.ts.
+ *
+ * Supports multiple named knowledge bases via knowledges map in knowledge.json:
+ *   client.use("产品数据").retrieve("查询文本")
+ *   client.retrieve("产品数据", "查询文本")
+ */
+/** Scoped handle returned by client.use(name), bound to a specific knowledge base */
+class KnowledgeScopedClient {
+    constructor(tbox, globalConfig, instanceConfig, allowedTools) {
+        this.tbox = tbox;
+        this.instanceConfig = instanceConfig;
+        this.allowedTools = allowedTools;
+        const local = instanceConfig.config;
+        this.effectiveConfig = {
+            type: local?.type ?? globalConfig.type,
+            topK: local?.topK ?? globalConfig.topK,
+            scoreThreshold: local?.scoreThreshold ?? globalConfig.scoreThreshold,
+            updateMode: local?.updateMode ?? globalConfig.updateMode,
+            pageSize: local?.pageSize ?? globalConfig.pageSize,
+        };
+        this.currentDocumentId = instanceConfig.documentId;
+    }
+    /** Get the effective merged config for this knowledge base */
+    getConfig() {
+        return { ...this.effectiveConfig, ...this.instanceConfig, documentId: this.currentDocumentId };
+    }
+    /** Get the current documentId (may be auto-filled after create()) */
+    getDocumentId() {
+        return this.currentDocumentId;
+    }
+    /** Semantic retrieval against this knowledge base */
+    async retrieve(query, options) {
+        this.assertToolAllowed('retrieve');
+        const datasetId = this.instanceConfig.datasetId;
+        if (!datasetId) {
+            throw new Error('datasetId is not configured for this knowledge base.');
+        }
+        const params = {
+            datasetId,
+            query,
+            topK: options?.topK ?? this.effectiveConfig.topK,
+            scoreThreshold: options?.scoreThreshold ?? this.effectiveConfig.scoreThreshold,
+        };
+        return this.tbox.knowledge.retrieve(params);
+    }
+    /**
+     * Create this knowledge base by uploading a file.
+     *
+     * Side effect: on success, the returned documentId is cached in this scoped client
+     * so that subsequent update() calls can use it automatically.
+     * The original instanceConfig is NOT mutated.
+     */
+    async create(file, options) {
+        this.assertToolAllowed('create');
+        const params = {
+            file,
+            type: options?.type ?? this.effectiveConfig.type ?? 'STRUCTURED',
+            tableSchema: options?.tableSchema ?? this.instanceConfig.tableSchema,
+            indexColumns: options?.indexColumns ?? this.instanceConfig.indexColumns,
+        };
+        const result = await this.tbox.knowledge.documents.create(params);
+        if (result.documentId) {
+            this.currentDocumentId = result.documentId;
+        }
+        return result;
+    }
+    /** Update this knowledge base document */
+    async update(file, options) {
+        this.assertToolAllowed('update');
+        const documentId = this.currentDocumentId;
+        if (!documentId) {
+            throw new Error('documentId is not configured. Call create() first or set it in knowledge.json.');
+        }
+        const params = {
+            documentId,
+            file,
+            type: this.effectiveConfig.type ?? 'STRUCTURED',
+            updateMode: options?.updateMode ?? this.effectiveConfig.updateMode ?? 'UPSERT',
+            tableSchema: options?.tableSchema ?? this.instanceConfig.tableSchema,
+            indexColumns: options?.indexColumns ?? this.instanceConfig.indexColumns,
+        };
+        return this.tbox.knowledge.documents.update(params);
+    }
+    /** Throw if the tool is not in the allowed set (when tools are configured) */
+    assertToolAllowed(tool) {
+        if (this.allowedTools && !this.allowedTools.has(tool)) {
+            const allowed = Array.from(this.allowedTools).join(', ');
+            throw new Error(`Tool "${tool}" is not allowed. Configured tools: [${allowed}]`);
+        }
+    }
+}
+/**
+ * Configuration-driven, multi-knowledge-base client.
+ *
+ * Usage patterns:
+ *   // Scoped: bind to a named knowledge base, then call methods
+ *   const product = client.use("产品数据");
+ *   await product.retrieve("查询文本");
+ *
+ *   // Direct: pass name as first arg
+ *   await client.retrieve("产品数据", "查询文本");
+ *
+ *   // List: shared across all knowledge bases
+ *   await client.list("搜索关键词");
+ */
+let KnowledgeClient$1 = class KnowledgeClient {
+    constructor(options) {
+        const { config, ...clientOptions } = options;
+        this.tbox = new TboxAPI(clientOptions);
+        this.serviceConfig = {};
+        this.knowledges = new Map();
+        this.resolveConfig(config);
+    }
+    /** Create from an existing TboxAPI instance */
+    static fromTboxAPI(tbox, config) {
+        const instance = Object.create(KnowledgeClient.prototype);
+        instance.tbox = tbox;
+        instance.serviceConfig = {};
+        instance.knowledges = new Map();
+        instance.resolveConfig(config);
+        return instance;
+    }
+    /**
+     * Load config from a knowledge.json file asynchronously (ESM-compatible).
+     * Use this in ESM environments instead of passing a file path to the constructor.
+     */
+    static async fromFile(options, filePath) {
+        const client = new KnowledgeClient(options);
+        await client.loadConfigFromFileAsync(filePath);
+        return client;
+    }
+    /** Resolve config from object, file path, or default */
+    resolveConfig(config) {
+        if (!config) {
+            this.serviceConfig = { type: 'STRUCTURED' };
+            return;
+        }
+        if (typeof config === 'string') {
+            this.loadConfigFromFileSync(config);
+            return;
+        }
+        // Single knowledge config passed as object — store as "default"
+        this.serviceConfig = {
+            type: config.type,
+            topK: config.topK,
+            scoreThreshold: config.scoreThreshold,
+            updateMode: config.updateMode,
+            pageSize: config.pageSize,
+        };
+        this.knowledges.set('default', {
+            datasetId: config.datasetId,
+            documentId: config.documentId,
+            tableSchema: config.tableSchema,
+            indexColumns: config.indexColumns,
+        });
+    }
+    /** Apply parsed JSON schema to this client */
+    applyJsonSchema(parsed) {
+        this.serviceConfig = parsed.config ?? { type: 'STRUCTURED' };
+        if (parsed.tools && parsed.tools.length > 0) {
+            this.allowedTools = new Set(parsed.tools);
+        }
+        if (parsed.knowledges) {
+            for (const [name, instanceConfig] of Object.entries(parsed.knowledges)) {
+                this.knowledges.set(name, { ...instanceConfig });
+            }
+        }
+    }
+    /** Load config from knowledge.json file synchronously (CJS environments) */
+    loadConfigFromFileSync(filePath) {
+        try {
+            // eslint-disable-next-line @typescript-eslint/no-implied-eval -- dynamic require for CJS compat
+            const dynamicRequire = new Function('id', 'return require(id)');
+            const fs = dynamicRequire('fs');
+            const raw = fs.readFileSync(filePath, 'utf-8');
+            const parsed = JSON.parse(raw);
+            this.applyJsonSchema(parsed);
+        }
+        catch (error) {
+            throw new Error(`Failed to load knowledge config from "${filePath}": ${error instanceof Error ? error.message : String(error)}`);
+        }
+    }
+    /** Load config from knowledge.json file asynchronously (ESM-compatible) */
+    async loadConfigFromFileAsync(filePath) {
+        try {
+            // Dynamic import avoids bundler static analysis and works in both CJS and ESM
+            const fsModule = await Function('return import("node:fs/promises")')();
+            const raw = await fsModule.readFile(filePath, 'utf-8');
+            const parsed = JSON.parse(raw);
+            this.applyJsonSchema(parsed);
+        }
+        catch (error) {
+            throw new Error(`Failed to load knowledge config from "${filePath}": ${error instanceof Error ? error.message : String(error)}`);
+        }
+    }
+    /** Get all registered knowledge base names */
+    names() {
+        return Array.from(this.knowledges.keys());
+    }
+    /** Get the allowed tools set (undefined means all tools are allowed) */
+    getAllowedTools() {
+        return this.allowedTools;
+    }
+    /** Get the shared service config */
+    getServiceConfig() {
+        return { ...this.serviceConfig };
+    }
+    /** Get instance config for a named knowledge base */
+    getInstanceConfig(name) {
+        const config = this.knowledges.get(name);
+        return config ? { ...config } : undefined;
+    }
+    /**
+     * Get a scoped client bound to a named knowledge base.
+     * All subsequent calls on the returned handle use that knowledge base's config.
+     */
+    use(name) {
+        const instanceConfig = this.knowledges.get(name);
+        if (!instanceConfig) {
+            const available = this.names().join(', ');
+            throw new Error(`Knowledge base "${name}" not found. Available: [${available}]`);
+        }
+        return new KnowledgeScopedClient(this.tbox, this.serviceConfig, instanceConfig, this.allowedTools);
+    }
+    /** Query knowledge base list (shared, not scoped to a specific knowledge base) */
+    async list(name, pageNo, pageSize) {
+        this.assertToolAllowed('list');
+        const params = {};
+        if (name !== undefined)
+            params.name = name;
+        if (pageNo !== undefined)
+            params.pageNo = pageNo;
+        params.pageSize = pageSize ?? this.serviceConfig.pageSize;
+        return this.tbox.knowledge.list(params);
+    }
+    /** Semantic retrieval — pass knowledge base name as first arg to route */
+    async retrieve(knowledgeName, query, options) {
+        return this.use(knowledgeName).retrieve(query, options);
+    }
+    /** Create a knowledge base by name */
+    async create(knowledgeName, file, options) {
+        return this.use(knowledgeName).create(file, options);
+    }
+    /** Update a knowledge base by name */
+    async update(knowledgeName, file, options) {
+        return this.use(knowledgeName).update(file, options);
+    }
+    /** Throw if the tool is not in the allowed set (when tools are configured) */
+    assertToolAllowed(tool) {
+        if (this.allowedTools && !this.allowedTools.has(tool)) {
+            const allowed = Array.from(this.allowedTools).join(', ');
+            throw new Error(`Tool "${tool}" is not allowed. Configured tools: [${allowed}]`);
+        }
+    }
+};
+
+/**
+ * 百宝箱插件服务 SDK - 底层 HTTP 请求封装
+ */
+/** 默认调用域名 */
+const DEFAULT_BASE_URL = 'https://o.tbox.cn';
+/**
+ * 将服务端原始响应统一转换为 SdkResponse
+ */
+function normalizeResponse(raw) {
+    const success = raw.success !== false;
+    const data = raw.data ?? raw.resultObj ?? raw.result;
+    // 按优先级兼容多种错误码字段
+    const errorCode = raw.errorCode ?? raw.code ?? raw.resultCode;
+    const errorMsg = raw.errorMsg ?? raw.msg ?? raw.resultDesc;
+    if (success) {
+        return { success: true, data };
+    }
+    return { success: false, errorCode, errorMsg };
+}
+/**
+ * 底层 HTTP 客户端
+ */
+class HttpClient {
+    constructor(config) {
+        this.baseUrl = config.baseUrl.replace(/\/$/, '');
+        this.apiKey = config.apiKey;
+        this.timeout = config.timeout;
+    }
+    /** 构建通用请求头 */
+    buildHeaders(extra) {
+        return {
+            'Content-Type': 'application/json;charset=UTF-8',
+            Authorization: this.apiKey,
+            ...extra,
+        };
+    }
+    /** 构建 FormData 请求头（不设置 Content-Type，让浏览器自动处理 boundary） */
+    buildHeadersForFormData(extra) {
+        return {
+            Authorization: this.apiKey,
+            ...extra,
+        };
+    }
+    /** 发起 fetch，支持可选超时 */
+    async fetchWithTimeout(url, init) {
+        if (!this.timeout) {
+            return fetch(url, init);
+        }
+        const controller = new AbortController();
+        const timer = setTimeout(() => controller.abort(), this.timeout);
+        try {
+            return await fetch(url, { ...init, signal: controller.signal });
+        }
+        finally {
+            clearTimeout(timer);
+        }
+    }
+    /**
+     * POST 请求
+     */
+    async post(path, body, queryParams) {
+        const url = this.buildUrl(path, queryParams);
+        let response;
+        try {
+            response = await this.fetchWithTimeout(url, {
+                method: 'POST',
+                headers: this.buildHeaders(),
+                body: JSON.stringify(body),
+            });
+        }
+        catch (err) {
+            return {
+                success: false,
+                errorCode: 'NETWORK_ERROR',
+                errorMsg: err instanceof Error ? err.message : String(err),
+            };
+        }
+        return this.parseResponse(response);
+    }
+    /**
+     * POST FormData 请求（用于文件上传）
+     */
+    async postFormData(path, formData, queryParams) {
+        const url = this.buildUrl(path, queryParams);
+        let response;
+        try {
+            // FormData 请求不设置 Content-Type，让浏览器自动设置 multipart/form-data 边界
+            response = await this.fetchWithTimeout(url, {
+                method: 'POST',
+                headers: this.buildHeadersForFormData(),
+                body: formData,
+            });
+        }
+        catch (err) {
+            return {
+                success: false,
+                errorCode: 'NETWORK_ERROR',
+                errorMsg: err instanceof Error ? err.message : String(err),
+            };
+        }
+        return this.parseResponse(response);
+    }
+    /**
+     * GET 请求
+     */
+    async get(path, queryParams) {
+        const url = this.buildUrl(path, queryParams);
+        let response;
+        try {
+            response = await this.fetchWithTimeout(url, {
+                method: 'GET',
+                headers: this.buildHeaders(),
+            });
+        }
+        catch (err) {
+            return {
+                success: false,
+                errorCode: 'NETWORK_ERROR',
+                errorMsg: err instanceof Error ? err.message : String(err),
+            };
+        }
+        return this.parseResponse(response);
+    }
+    /** 构建完整 URL（含 query string） */
+    buildUrl(path, queryParams) {
+        // 如果 path 已经是完整 URL（以 http:// 或 https:// 开头），直接使用
+        let base;
+        if (path.startsWith('http://') || path.startsWith('https://')) {
+            base = path;
+        }
+        else {
+            base = `${this.baseUrl}${path}`;
+        }
+        if (!queryParams || Object.keys(queryParams).length === 0) {
+            return base;
+        }
+        const qs = new URLSearchParams(queryParams).toString();
+        return `${base}?${qs}`;
+    }
+    /** 解析响应体 */
+    async parseResponse(response) {
+        if (!response.ok) {
+            return {
+                success: false,
+                errorCode: `HTTP_${response.status}`,
+                errorMsg: `HTTP error: ${response.status} ${response.statusText}`,
+            };
+        }
+        let json;
+        try {
+            // 使用 arrayBuffer + TextDecoder 确保多字节 UTF-8 字符（如中文）正确解码
+            const buffer = await response.arrayBuffer();
+            const text = new TextDecoder('utf-8').decode(buffer);
+            json = JSON.parse(text);
+        }
+        catch {
+            return {
+                success: false,
+                errorCode: 'PARSE_ERROR',
+                errorMsg: 'Failed to parse response JSON',
+            };
+        }
+        return normalizeResponse(json);
+    }
+}
+
+/**
+ * 百宝箱插件服务 SDK - PluginClient 核心类
+ *
+ * 封装 /openapi/v1/plugin 下的全部接口
+ */
+/** API 路径前缀 */
+const API_PREFIX$4 = '/openapi/v1/plugin';
+/**
+ * 百宝箱插件服务客户端
+ *
+ * @example
+ * ```ts
+ * import { TboxPluginClient } from '@tbox/plugin-sdk';
+ *
+ * const client = new TboxPluginClient({ apiKey: 'your-api-key' });
+ *
+ * // 执行插件工具
+ * const result = await client.run('tool-id-xxx', { params: { key: 'value' } });
+ * ```
+ */
+class TboxPluginClient {
+    constructor(config) {
+        this.http = new HttpClient({
+            baseUrl: config.baseUrl ?? DEFAULT_BASE_URL,
+            apiKey: config.apiKey,
+            timeout: config.timeout,
+        });
+    }
+    // ============================================================
+    // TTS - 文字转语音
+    // ============================================================
+    /**
+     * 文字转语音
+     *
+     * POST /openapi/v1/plugin/doTts
+     *
+     * @param request - TTS 请求参数
+     * @returns 音频数据（Base64 或 URL）
+     *
+     * @example
+     * ```ts
+     * const res = await client.doTts({ text: '你好，世界' });
+     * if (res.success) {
+     *   console.log(res.data?.audioBase64);
+     * }
+     * ```
+     */
+    async doTts(request) {
+        return this.http.post(`${API_PREFIX$4}/doTts`, request);
+    }
+    // ============================================================
+    // ASR - 语音转文字
+    // ============================================================
+    /**
+     * 语音转文字（Base64 音频输入）
+     *
+     * POST /openapi/v1/plugin/asrBase64V2
+     *
+     * @param request - ASR 请求参数，音频以 Base64 格式传入
+     * @returns 识别出的文本
+     *
+     * @example
+     * ```ts
+     * const res = await client.asrBase64({ audioBase64: '<base64-string>', format: 'mp3' });
+     * if (res.success) {
+     *   console.log(res.data?.text);
+     * }
+     * ```
+     */
+    async asrBase64(request) {
+        return this.http.post(`${API_PREFIX$4}/asrBase64V2`, request);
+    }
+    // ============================================================
+    // 插件工具执行
+    // ============================================================
+    /**
+     * 按工具 ID 执行插件工具
+     *
+     * POST /openapi/v1/plugin/run/{pluginToolId}
+     *
+     * 适用于已知工具 ID 的场景，调用更直接、性能更好。
+     *
+     * @param pluginToolId - 插件工具 ID
+     * @param request      - 工具执行请求（含输入参数）
+     * @returns 工具执行结果
+     *
+     * @example
+     * ```ts
+     * const res = await client.run('tool-id-xxx', {
+     *   inputs: { city: '杭州' },
+     * });
+     * if (res.success) {
+     *   console.log(res.data?.output);
+     * }
+     * ```
+     */
+    async run(pluginToolId, request) {
+        return this.http.post(`${API_PREFIX$4}/run/${encodeURIComponent(pluginToolId)}`, request);
+    }
+    // ============================================================
+    // 插件信息查询
+    // ============================================================
+    /**
+     * 查询插件配置信息（含工具集）
+     *
+     * GET /openapi/v1/plugin/info/{pluginId}
+     *
+     * @param pluginId - 插件 ID
+     * @returns 插件信息，包含插件名称、描述及工具列表
+     *
+     * @example
+     * ```ts
+     * const res = await client.getPluginInfo('plugin-id');
+     * if (res.success) {
+     *   console.log(res.data?.pluginToolList);
+     * }
+     * ```
+     */
+    async getPluginInfo(pluginId) {
+        return this.http.get(`${API_PREFIX$4}/info/${encodeURIComponent(pluginId)}`);
+    }
+    /**
+     * 网络搜索
+     *
+     * 内部调用 run('20240611204600000001', ...) 实现，对外屏蔽工具 ID 细节。
+     * 服务端响应层级：result.result.result.data[]，SDK 自动解包为扁平的 items 列表。
+     *
+     * @param request - 搜索请求，包含关键词 q
+     * @returns 搜索结果列表
+     *
+     * @example
+     * ```ts
+     * const res = await client.webSearch({ q: '上海今天天气' });
+     * if (res.success) {
+     *   for (const item of res.data?.items ?? []) {
+     *     console.log(item.title, item.url);
+     *   }
+     * }
+     * ```
+     */
+    async webSearch(request) {
+        // 按服务端约定，搜索关键词放在 params.q
+        const raw = await this.run(TboxPluginClient.WEB_SEARCH_TOOL_ID, {
+            params: { q: request.q },
+        });
+        if (!raw.success) {
+            return {
+                success: false,
+                errorCode: raw.errorCode,
+                errorMsg: raw.errorMsg,
+            };
+        }
+        // 深层解包：raw.data → result.data[]
+        // 服务端实际结构：{ cost, result: { data: [...], success, message } }
+        const inner = raw.data;
+        const level1 = inner?.['result'];
+        const dataArr = level1?.['data'];
+        const items = Array.isArray(dataArr)
+            ? dataArr
+            : [];
+        return {
+            success: true,
+            data: { items },
+        };
+    }
+}
+// ============================================================
+// 网络搜索
+// ============================================================
+/** 网络搜索工具的固定工具 ID */
+TboxPluginClient.WEB_SEARCH_TOOL_ID = '20240611204600000001';
+
+/**
+ * 百宝箱会话管理 SDK - ConversationClient 核心类
+ *
+ * 封装 /openapi/v1/conversation 下的全部接口
+ */
+/** API 路径前缀 */
+const API_PREFIX$3 = '/openapi/v1/conversation';
+/**
+ * 百宝箱会话管理客户端
+ *
+ * @example
+ * ```ts
+ * import { TboxConversationClient } from '@tbox/plugin-sdk';
+ *
+ * const client = new TboxConversationClient({ apiKey: 'your-api-key' });
+ *
+ * // 创建新会话
+ * const res = await client.createConversation({ agentId: 'app-id', userId: 'user-id' });
+ * if (res.success) {
+ *   console.log('会话 ID:', res.data);
+ * }
+ * ```
+ */
+class TboxConversationClient {
+    constructor(config) {
+        this.http = new HttpClient({
+            baseUrl: config.baseUrl ?? DEFAULT_BASE_URL,
+            apiKey: config.apiKey,
+            timeout: config.timeout,
+        });
+    }
+    // ============================================================
+    // 会话管理
+    // ============================================================
+    /**
+     * 创建新会话
+     *
+     * POST /openapi/v1/conversation/create
+     *
+     * @param request - 创建会话请求，包含 agentId 和 userId
+     * @returns 新会话 ID（字符串）
+     *
+     * @example
+     * ```ts
+     * const res = await client.createConversation({
+     *   agentId: 'your-app-id',
+     *   userId: 'user-123',
+     * });
+     * if (res.success) {
+     *   const conversationId = res.data;
+     * }
+     * ```
+     */
+    async createConversation(request) {
+        return this.http.post(`${API_PREFIX$3}/create`, request);
+    }
+    /**
+     * 查询会话列表（分页）
+     *
+     * POST /openapi/v1/conversation/list
+     *
+     * @param request - 查询请求，支持按 agentId、userId 过滤，支持分页
+     * @returns 分页会话列表
+     *
+     * @example
+     * ```ts
+     * const res = await client.listConversations({
+     *   agentId: 'your-app-id',
+     *   userId: 'user-123',
+     *   pageNum: 1,
+     *   pageSize: 20,
+     * });
+     * if (res.success) {
+     *   console.log(res.data?.list);
+     * }
+     * ```
+     */
+    async listConversations(request) {
+        return this.http.post(`${API_PREFIX$3}/list`, request);
+    }
+    // ============================================================
+    // 消息管理
+    // ============================================================
+    /**
+     * 查询消息列表（分页）
+     *
+     * POST /openapi/v1/conversation/message/list
+     *
+     * @param request - 查询请求，支持按 conversationId、agentId、userId 过滤，支持分页
+     * @returns 分页消息列表
+     *
+     * @example
+     * ```ts
+     * const res = await client.listMessages({
+     *   conversationId: 'conv-id-xxx',
+     *   pageNum: 1,
+     *   pageSize: 20,
+     * });
+     * if (res.success) {
+     *   console.log(res.data?.list);
+     * }
+     * ```
+     */
+    async listMessages(request) {
+        return this.http.post(`${API_PREFIX$3}/message/list`, request);
+    }
+    /**
+     * 新增会话消息
+     *
+     * POST /openapi/v1/conversation/message/save
+     *
+     * 将一条对话消息（问题 + 回答）保存到指定会话中。
+     *
+     * @param request - 保存消息请求
+     * @returns 消息 ID（字符串）
+     *
+     * @example
+     * ```ts
+     * const res = await client.saveMessage({
+     *   conversationId: 'conv-id-xxx',
+     *   query: '今天天气怎么样？',
+     *   answer: '今天杭州晴天，25°C。',
+     * });
+     * if (res.success) {
+     *   const messageId = res.data;
+     * }
+     * ```
+     */
+    async saveMessage(request) {
+        return this.http.post(`${API_PREFIX$3}/message/save`, request);
+    }
+}
+
+/**
+ * 百宝箱插件服务 SDK - 应用服务客户端
+ *
+ * 封装 /openapi/v1/app 下的接口
+ */
+/**
+ * 百宝箱应用服务客户端
+ *
+ * @example
+ * ```ts
+ * const client = new TboxAppClient({ apiKey: 'your-api-key' });
+ *
+ * // 生成 sessionId，用于免登录访问百宝箱应用
+ * const result = await client.generateSession({
+ *   appId: 'your-app-id',
+ *   userId: 'user-123',
+ *   userInfo: [
+ *     { infoType: 'name', infoValue: '张三' },
+ *   ],
+ *   deviceInfo: {
+ *     platform: 'IOS',
+ *     appVersion: '1.0.0',
+ *   },
+ * });
+ *
+ * if (result.success) {
+ *   console.log('sessionId:', result.data?.sessionId);
+ *   console.log('channel:', result.data?.channel);
+ * }
+ * ```
+ */
+class TboxAppClient {
+    constructor(config) {
+        this.http = new HttpClient({
+            baseUrl: config.baseUrl ?? DEFAULT_BASE_URL,
+            apiKey: config.apiKey,
+            timeout: config.timeout,
+        });
+    }
+    /**
+     * 根据用户信息生成 sessionId 和 channel
+     *
+     * 接口：POST /openapi/v1/app/generate_session
+     *
+     * 生成的 sessionId 可用于拼接百宝箱 H5 访问链接，实现免登录跳转。
+     *
+     * @param request 请求参数，appId 和 userId 为必填
+     * @returns sessionId 和 channel
+     */
+    async generateSession(request) {
+        return this.http.post('/openapi/v1/app/generate_session', request);
+    }
+}
+
+/**
+ * 高德地图 SDK - AmapClient 核心类
+ *
+ * 封装高德地图天气查询工具（amap_weather），
+ * 通过百宝箱插件服务 /openapi/v1/plugin/run/{pluginToolId} 接口调用。
+ */
+/** API 路径前缀 */
+const API_PREFIX$2 = '/openapi/v1/plugin';
+/**
+ * 高德地图客户端
+ *
+ * @example
+ * ```ts
+ * import { AmapClient } from '@tbox/plugin-sdk';
+ *
+ * const client = new AmapClient({ apiKey: 'your-api-key' });
+ *
+ * // 查询实况天气
+ * const res = await client.weather({ city: '杭州市' });
+ * if (res.success) {
+ *   console.log(res.data?.lives?.[0]?.weather);
+ * }
+ *
+ * // 查询预报天气
+ * const forecast = await client.weather({ city: '上海市', extensions: 'all' });
+ * if (forecast.success) {
+ *   console.log(forecast.data?.forecasts?.[0]?.casts);
+ * }
+ * ```
+ */
+class AmapClient {
+    constructor(config) {
+        this.http = new HttpClient({
+            baseUrl: config.baseUrl ?? DEFAULT_BASE_URL,
+            apiKey: config.apiKey,
+            timeout: config.timeout,
+        });
+    }
+    // ============================================================
+    // 天气查询
+    // ============================================================
+    /**
+     * 查询天气（实况或预报）
+     *
+     * 内部调用 run('20240627231800002183', ...) 实现，对外屏蔽工具 ID 细节。
+     * 数据来源于中国气象局。
+     *
+     * @param request - 天气查询请求
+     *   - `city`（必填）：省份名、市名、区/县/镇、乡/村或具体地点
+     *   - `extensions`（可选）：`base`（实况，默认）或 `all`（预报）
+     * @returns 天气查询结果
+     *   - `extensions=base` 时，`data.lives` 包含实况天气数据
+     *   - `extensions=all` 时，`data.forecasts` 包含逐日预报数据
+     *
+     * @example
+     * ```ts
+     * // 查询实况天气
+     * const live = await client.weather({ city: '西湖区' });
+     * if (live.success) {
+     *   const w = live.data?.lives?.[0];
+     *   console.log(`${w?.city} ${w?.weather} ${w?.temperature}℃`);
+     * }
+     *
+     * // 查询未来几天预报
+     * const forecast = await client.weather({ city: '北京市', extensions: 'all' });
+     * if (forecast.success) {
+     *   for (const cast of forecast.data?.forecasts?.[0]?.casts ?? []) {
+     *     console.log(`${cast.date} 白天：${cast.dayweather} 夜间：${cast.nightweather}`);
+     *   }
+     * }
+     * ```
+     */
+    async weather(request) {
+        const params = { city: request.city };
+        if (request.extensions !== undefined) {
+            params['extensions'] = request.extensions;
+        }
+        const raw = await this.http.post(`${API_PREFIX$2}/run/${encodeURIComponent(AmapClient.AMAP_WEATHER_TOOL_ID)}`, { params });
+        if (!raw.success) {
+            return {
+                success: false,
+                errorCode: raw.errorCode,
+                errorMsg: raw.errorMsg,
+            };
+        }
+        // 从 raw.data.result 中解包天气数据
+        // 服务端实际结构：{ success, result: { status, info, infocode, count, lives?, forecasts? }, cost, traceId }
+        const execResult = raw.data;
+        const weatherData = execResult?.result;
+        return {
+            success: true,
+            data: weatherData ?? {},
+        };
+    }
+    // ============================================================
+    // 地址转经纬度
+    // ============================================================
+    /**
+     * 地址转经纬度（地理编码）
+     *
+     * 将详细的地名，转换为经纬度坐标。
+     * 内部调用 run('20240627233200002185', ...) 实现，对外屏蔽工具 ID 细节。
+     *
+     * @param request - 地址转经纬度请求
+     *   - `address`（必填）：详细地址信息（国家、省份、城市、区县、城镇、乡村、街道、门牌号）
+     *   - `city`（可选）：查询的城市，指定可提高查询精度
+     * @returns 地理编码结果
+     *   - `data.geocodes` 包含地理编码信息列表
+     *
+     * @example
+     * ```ts
+     * // 地址转经纬度
+     * const res = await client.geocode({ address: '北京市朝阳区阜通东大街6号', city: '北京' });
+     * if (res.success) {
+     *   const geo = res.data?.geocodes?.[0];
+     *   console.log(`地址: ${geo?.formatted_address}`);
+     *   console.log(`经纬度: ${geo?.location}`);
+     *   console.log(`区域编码: ${geo?.adcode}`);
+     * }
+     * ```
+     */
+    async geocode(request) {
+        const params = { address: request.address };
+        if (request.city !== undefined) {
+            params['city'] = request.city;
+        }
+        const raw = await this.http.post(`${API_PREFIX$2}/run/${encodeURIComponent(AmapClient.AMAP_GEOCODE_TOOL_ID)}`, { params });
+        if (!raw.success) {
+            return {
+                success: false,
+                errorCode: raw.errorCode,
+                errorMsg: raw.errorMsg,
+            };
+        }
+        // 从 raw.data.result 中解包地理编码数据
+        // 服务端实际结构：{ success, result: { code, status, infocode, count, geocodes? }, cost, traceId }
+        const execResult = raw.data;
+        const geocodeData = execResult?.result;
+        return {
+            success: true,
+            data: geocodeData ?? {},
+        };
+    }
+    // ============================================================
+    // 骑行路线规划
+    // ============================================================
+    /**
+     * 骑行路线规划
+     *
+     * 提供起点和终点的位置，返回骑行路线，支持多条路线。
+     *
+     * @param request - 骑行路线规划请求
+     *   - `origin`（必填）：起点位置名称
+     *   - `destination`（必填）：终点位置名称
+     * @returns 骑行路线规划结果
+     *
+     * @example
+     * ```ts
+     * const res = await client.cyclingRoute({
+     *   origin: '杭州市西湖区',
+     *   destination: '杭州市余杭区'
+     * });
+     * if (res.success) {
+     *   const path = res.data?.route?.paths?.[0];
+     *   console.log(`距离: ${path?.distance}米, 时间: ${path?.duration}秒`);
+     * }
+     * ```
+     */
+    async cyclingRoute(request) {
+        const params = {
+            origin: request.origin,
+            destination: request.destination,
+        };
+        const raw = await this.http.post(`${API_PREFIX$2}/run/${encodeURIComponent(AmapClient.AMAP_CYCLING_ROUTE_TOOL_ID)}`, { params });
+        if (!raw.success) {
+            return {
+                success: false,
+                errorCode: raw.errorCode,
+                errorMsg: raw.errorMsg,
+            };
+        }
+        const execResult = raw.data;
+        const routeData = execResult?.result;
+        return {
+            success: true,
+            data: routeData ?? {},
+        };
+    }
+    // ============================================================
+    // IP 定位
+    // ============================================================
+    /**
+     * IP 定位
+     *
+     * 定位输入的 IP 所在的地理位置（暂不支持 IPv6）。
+     *
+     * @param request - IP 定位请求
+     *   - `ip`（必填）：需要定位的 IP 地址
+     * @returns IP 定位结果
+     *
+     * @example
+     * ```ts
+     * const res = await client.ipLocation({ ip: '114.114.114.114' });
+     * if (res.success) {
+     *   console.log(`省份: ${res.data?.province}, 城市: ${res.data?.city}`);
+     * }
+     * ```
+     */
+    async ipLocation(request) {
+        const params = { ip: request.ip };
+        const raw = await this.http.post(`${API_PREFIX$2}/run/${encodeURIComponent(AmapClient.AMAP_IP_LOCATION_TOOL_ID)}`, { params });
+        if (!raw.success) {
+            return {
+                success: false,
+                errorCode: raw.errorCode,
+                errorMsg: raw.errorMsg,
+            };
+        }
+        const execResult = raw.data;
+        const locationData = execResult?.result;
+        return {
+            success: true,
+            data: locationData ?? {},
+        };
+    }
+    // ============================================================
+    // 周边搜索
+    // ============================================================
+    /**
+     * 周边搜索
+     *
+     * 根据指定地点和关键词，搜索周边景点、美食、酒店、运动场所等。
+     *
+     * @param request - 周边搜索请求
+     *   - `address`（必填）：中心点地址信息
+     *   - `keyword`（必填）：检索关键词（景点、美食、游玩区域等，不超过 80 字符）
+     *   - `count`（可选）：返回条数，默认 5
+     *   - `radius`（可选）：搜索半径（米），范围 0-50000
+     * @returns 周边搜索结果
+     *
+     * @example
+     * ```ts
+     * const res = await client.peripheralSearch({
+     *   address: '杭州市西湖区',
+     *   keyword: '美食',
+     *   count: 10,
+     *   radius: 1000
+     * });
+     * if (res.success) {
+     *   for (const poi of res.data?.pois ?? []) {
+     *     console.log(`${poi.name} - ${poi.address}`);
+     *   }
+     * }
+     * ```
+     */
+    async peripheralSearch(request) {
+        const params = {
+            address: request.address,
+            keyword: request.keyword,
+        };
+        if (request.count !== undefined) {
+            params['count'] = request.count;
+        }
+        if (request.radius !== undefined) {
+            params['radius'] = request.radius;
+        }
+        const raw = await this.http.post(`${API_PREFIX$2}/run/${encodeURIComponent(AmapClient.AMAP_PERIPHERAL_SEARCH_TOOL_ID)}`, { params });
+        if (!raw.success) {
+            return {
+                success: false,
+                errorCode: raw.errorCode,
+                errorMsg: raw.errorMsg,
+            };
+        }
+        const execResult = raw.data;
+        const searchData = execResult?.result;
+        return {
+            success: true,
+            data: searchData ?? {},
+        };
+    }
+    // ============================================================
+    // 步行路线规划
+    // ============================================================
+    /**
+     * 步行路线规划
+     *
+     * 提供起点和终点的位置，返回步行路线，支持多条路线。
+     *
+     * @param request - 步行路线规划请求
+     *   - `origin`（必填）：起点地址
+     *   - `destination`（必填）：终点地址
+     * @returns 步行路线规划结果
+     *
+     * @example
+     * ```ts
+     * const res = await client.walkingRoute({
+     *   origin: '杭州市西湖区古荡',
+     *   destination: '杭州市西湖区西溪湿地'
+     * });
+     * if (res.success) {
+     *   const path = res.data?.route?.paths?.[0];
+     *   console.log(`距离: ${path?.distance}米, 时间: ${path?.duration}秒`);
+     * }
+     * ```
+     */
+    async walkingRoute(request) {
+        const params = {
+            origin: request.origin,
+            destination: request.destination,
+        };
+        const raw = await this.http.post(`${API_PREFIX$2}/run/${encodeURIComponent(AmapClient.AMAP_WALKING_ROUTE_TOOL_ID)}`, { params });
+        if (!raw.success) {
+            return {
+                success: false,
+                errorCode: raw.errorCode,
+                errorMsg: raw.errorMsg,
+            };
+        }
+        const execResult = raw.data;
+        const routeData = execResult?.result;
+        return {
+            success: true,
+            data: routeData ?? {},
+        };
+    }
+    // ============================================================
+    // 驾车路线规划
+    // ============================================================
+    /**
+     * 驾车路线规划
+     *
+     * 提供起点和终点的位置，返回驾车路线，支持多条路线。
+     *
+     * @param request - 驾车路线规划请求
+     *   - `origin`（必填）：起点地址或经纬度
+     *   - `destination`（必填）：终点地址或经纬度
+     * @returns 驾车路线规划结果
+     *
+     * @example
+     * ```ts
+     * const res = await client.drivingRoute({
+     *   origin: '杭州西溪湿地',
+     *   destination: '绍兴市'
+     * });
+     * if (res.success) {
+     *   const path = res.data?.route?.paths?.[0];
+     *   console.log(`距离: ${path?.distance}米, 时间: ${path?.duration}秒`);
+     *   console.log(`出租车费用: ${res.data?.route?.taxi_cost}元`);
+     * }
+     * ```
+     */
+    async drivingRoute(request) {
+        const params = {
+            origin: request.origin,
+            destination: request.destination,
+        };
+        const raw = await this.http.post(`${API_PREFIX$2}/run/${encodeURIComponent(AmapClient.AMAP_DRIVING_ROUTE_TOOL_ID)}`, { params });
+        if (!raw.success) {
+            return {
+                success: false,
+                errorCode: raw.errorCode,
+                errorMsg: raw.errorMsg,
+            };
+        }
+        const execResult = raw.data;
+        const routeData = execResult?.result;
+        return {
+            success: true,
+            data: routeData ?? {},
+        };
+    }
+    // ============================================================
+    // 电动车路线规划
+    // ============================================================
+    /**
+     * 电动车路线规划
+     *
+     * 提供起点和终点的位置，返回电动车骑行路线，支持多条路线。
+     *
+     * @param request - 电动车路线规划请求
+     *   - `origin`（必填）：起点地址或经纬度
+     *   - `destination`（必填）：终点地址或经纬度
+     * @returns 电动车路线规划结果
+     *
+     * @example
+     * ```ts
+     * const res = await client.ebikeRoute({
+     *   origin: '杭州市西湖区',
+     *   destination: '杭州市余杭区'
+     * });
+     * if (res.success) {
+     *   const path = res.data?.route?.paths?.[0];
+     *   console.log(`距离: ${path?.distance}米, 时间: ${path?.duration}秒`);
+     * }
+     * ```
+     */
+    async ebikeRoute(request) {
+        const params = {
+            origin: request.origin,
+            destination: request.destination,
+        };
+        const raw = await this.http.post(`${API_PREFIX$2}/run/${encodeURIComponent(AmapClient.AMAP_EBIKE_ROUTE_TOOL_ID)}`, { params });
+        if (!raw.success) {
+            return {
+                success: false,
+                errorCode: raw.errorCode,
+                errorMsg: raw.errorMsg,
+            };
+        }
+        const execResult = raw.data;
+        const routeData = execResult?.result;
+        return {
+            success: true,
+            data: routeData ?? {},
+        };
+    }
+    // ============================================================
+    // 公交路线规划
+    // ============================================================
+    /**
+     * 公交路线规划
+     *
+     * 提供起点和终点的位置，返回公交换乘方案，支持多条路线。
+     *
+     * @param request - 公交路线规划请求
+     *   - `origin`（必填）：起点地址或经纬度
+     *   - `destination`（必填）：终点地址或经纬度
+     * @returns 公交路线规划结果
+     *
+     * @example
+     * ```ts
+     * const res = await client.transitRoute({
+     *   origin: '杭州火车站',
+     *   destination: '西湖'
+     * });
+     * if (res.success) {
+     *   for (const transit of res.data?.route?.transits ?? []) {
+     *     console.log(`费用: ${transit.cost}元, 时间: ${transit.duration}秒`);
+     *   }
+     * }
+     * ```
+     */
+    async transitRoute(request) {
+        const params = {
+            origin: request.origin,
+            destination: request.destination,
+        };
+        const raw = await this.http.post(`${API_PREFIX$2}/run/${encodeURIComponent(AmapClient.AMAP_TRANSIT_ROUTE_TOOL_ID)}`, { params });
+        if (!raw.success) {
+            return {
+                success: false,
+                errorCode: raw.errorCode,
+                errorMsg: raw.errorMsg,
+            };
+        }
+        const execResult = raw.data;
+        const routeData = execResult?.result;
+        return {
+            success: true,
+            data: routeData ?? {},
+        };
+    }
+    // ============================================================
+    // 行政区域查询
+    // ============================================================
+    /**
+     * 行政区域查询
+     *
+     * 根据用户输入，快速查找特定的行政区域信息。
+     *
+     * @param request - 行政区域查询请求
+     *   - `keywords`（必填）：查询关键字（行政区名称、citycode、adcode）
+     * @returns 行政区域查询结果
+     *
+     * @example
+     * ```ts
+     * const res = await client.district({ keywords: '成都市' });
+     * if (res.success) {
+     *   for (const district of res.data?.districts ?? []) {
+     *     console.log(`${district.name} (${district.adcode})`);
+     *   }
+     * }
+     * ```
+     */
+    async district(request) {
+        const params = { keywords: request.keywords };
+        const raw = await this.http.post(`${API_PREFIX$2}/run/${encodeURIComponent(AmapClient.AMAP_DISTRICT_TOOL_ID)}`, { params });
+        if (!raw.success) {
+            return {
+                success: false,
+                errorCode: raw.errorCode,
+                errorMsg: raw.errorMsg,
+            };
+        }
+        const execResult = raw.data;
+        const districtData = execResult?.result;
+        return {
+            success: true,
+            data: districtData ?? {},
+        };
+    }
+    // ============================================================
+    // 经纬度转地址（逆地理编码）
+    // ============================================================
+    /**
+     * 经纬度转地址（逆地理编码）
+     *
+     * 将经纬度转换为详细的地址，且返回附近周边的 POI、AOI 信息。
+     *
+     * @param request - 经纬度转地址请求
+     *   - `location`（必填）：经纬度坐标（经度在前，纬度在后，英文逗号分隔）
+     *   - `extensions`（可选）：base（基本地址）/ all（详细信息）
+     * @returns 逆地理编码结果
+     *
+     * @example
+     * ```ts
+     * const res = await client.regeocode({
+     *   location: '116.480881,39.989410',
+     *   extensions: 'base'
+     * });
+     * if (res.success) {
+     *   console.log(`地址: ${res.data?.regeocode?.formatted_address}`);
+     * }
+     * ```
+     */
+    async regeocode(request) {
+        const params = { location: request.location };
+        if (request.extensions !== undefined) {
+            params['extensions'] = request.extensions;
+        }
+        const raw = await this.http.post(`${API_PREFIX$2}/run/${encodeURIComponent(AmapClient.AMAP_REGEOCODE_TOOL_ID)}`, { params });
+        if (!raw.success) {
+            return {
+                success: false,
+                errorCode: raw.errorCode,
+                errorMsg: raw.errorMsg,
+            };
+        }
+        const execResult = raw.data;
+        const regeocodeData = execResult?.result;
+        return {
+            success: true,
+            data: regeocodeData ?? {},
+        };
+    }
+    // ============================================================
+    // 坐标转换
+    // ============================================================
+    /**
+     * 坐标转换
+     *
+     * 将非高德坐标（GPS、mapbar、baidu 坐标）转换成高德坐标。
+     *
+     * @param request - 坐标转换请求
+     *   - `locations`（必填）：坐标点（经纬度用逗号分隔，多个坐标用 "|" 分隔，最多 40 个）
+     *   - `coordsys`（必填）：原坐标系（gps / mapbar / baidu / autonavi）
+     * @returns 坐标转换结果
+     *
+     * @example
+     * ```ts
+     * const res = await client.convert({
+     *   locations: '116.481488,39.990464',
+     *   coordsys: 'baidu'
+     * });
+     * if (res.success) {
+     *   console.log(`转换后的坐标: ${res.data?.locations}`);
+     * }
+     * ```
+     */
+    async convert(request) {
+        const params = {
+            locations: request.locations,
+            coordsys: request.coordsys,
+        };
+        const raw = await this.http.post(`${API_PREFIX$2}/run/${encodeURIComponent(AmapClient.AMAP_CONVERT_TOOL_ID)}`, { params });
+        if (!raw.success) {
+            return {
+                success: false,
+                errorCode: raw.errorCode,
+                errorMsg: raw.errorMsg,
+            };
+        }
+        const execResult = raw.data;
+        const convertData = execResult?.result;
+        return {
+            success: true,
+            data: convertData ?? {},
+        };
+    }
+    // ============================================================
+    // POI 关键字搜索
+    // ============================================================
+    /**
+     * POI 关键字搜索
+     *
+     * 通过文本关键字搜索地点信息，支持结构化地址和 POI 名称搜索。
+     *
+     * @param request - POI 关键字搜索请求
+     *   - `keywords`（可选）：查询关键字
+     *   - `types`（可选）：指定地点类型
+     *   - `region`（可选）：搜索区划（默认全国）
+     *   - `city_limit`（可选）：是否限制在 region 内（true / false）
+     *   - `page_size`（可选）：每页数据条数（1-25）
+     *   - `page_num`（可选）：分页页码（1-100）
+     * @returns POI 搜索结果
+     *
+     * @example
+     * ```ts
+     * const res = await client.poiSearch({
+     *   keywords: '首开广场',
+     *   region: '北京',
+     *   page_size: '10',
+     *   page_num: '1'
+     * });
+     * if (res.success) {
+     *   for (const poi of res.data?.pois ?? []) {
+     *     console.log(`${poi.name} - ${poi.address}`);
+     *   }
+     * }
+     * ```
+     */
+    async poiSearch(request) {
+        const params = {};
+        if (request.keywords !== undefined) {
+            params['keywords'] = request.keywords;
+        }
+        if (request.types !== undefined) {
+            params['types'] = request.types;
+        }
+        if (request.region !== undefined) {
+            params['region'] = request.region;
+        }
+        if (request.city_limit !== undefined) {
+            params['city_limit'] = request.city_limit;
+        }
+        if (request.page_size !== undefined) {
+            params['page_size'] = request.page_size;
+        }
+        if (request.page_num !== undefined) {
+            params['page_num'] = request.page_num;
+        }
+        const raw = await this.http.post(`${API_PREFIX$2}/run/${encodeURIComponent(AmapClient.AMAP_POI_SEARCH_TOOL_ID)}`, { params });
+        if (!raw.success) {
+            return {
+                success: false,
+                errorCode: raw.errorCode,
+                errorMsg: raw.errorMsg,
+            };
+        }
+        const execResult = raw.data;
+        const poiData = execResult?.result;
+        return {
+            success: true,
+            data: poiData ?? {},
+        };
+    }
+}
+/** 高德天气查询工具的固定工具 ID */
+AmapClient.AMAP_WEATHER_TOOL_ID = '20240627231800002183';
+/** 高德地址转经纬度工具的固定工具 ID */
+AmapClient.AMAP_GEOCODE_TOOL_ID = '20240627233200002185';
+/** 高德骑行路线规划工具的固定工具 ID */
+AmapClient.AMAP_CYCLING_ROUTE_TOOL_ID = '20240627233900002186';
+/** 高德 IP 定位工具的固定工具 ID */
+AmapClient.AMAP_IP_LOCATION_TOOL_ID = '20240627235900002187';
+/** 高德周边搜索工具的固定工具 ID */
+AmapClient.AMAP_PERIPHERAL_SEARCH_TOOL_ID = '20240628000200002188';
+/** 高德步行路线规划工具的固定工具 ID */
+AmapClient.AMAP_WALKING_ROUTE_TOOL_ID = '20240628000400002189';
+/** 高德驾车路线规划工具的固定工具 ID */
+AmapClient.AMAP_DRIVING_ROUTE_TOOL_ID = '20240628000900002190';
+/** 高德电动车路线规划工具的固定工具 ID */
+AmapClient.AMAP_EBIKE_ROUTE_TOOL_ID = '20240628001000002191';
+/** 高德公交路线规划工具的固定工具 ID */
+AmapClient.AMAP_TRANSIT_ROUTE_TOOL_ID = '20240628001100002192';
+/** 高德行政区域查询工具的固定工具 ID */
+AmapClient.AMAP_DISTRICT_TOOL_ID = '20240628001200002193';
+/** 高德经纬度转地址工具的固定工具 ID */
+AmapClient.AMAP_REGEOCODE_TOOL_ID = '20240629202400006671';
+/** 高德坐标转换工具的固定工具 ID */
+AmapClient.AMAP_CONVERT_TOOL_ID = '20251110ArTR04496110';
+/** 高德 POI 关键字搜索工具的固定工具 ID */
+AmapClient.AMAP_POI_SEARCH_TOOL_ID = '20251110crvO04497983';
+
+/**
+ * 知识库 SDK - KnowledgeClient 核心类
+ *
+ * 封装知识库管理功能，通过百宝箱服务接口实现知识库的创建和管理。
+ */
+/** API 路径前缀 */
+const API_PREFIX$1 = '/openapi/v1';
+/**
+ * 知识库客户端
+ *
+ * @example
+ * ```ts
+ * import { KnowledgeClient } from '@tbox/plugin-sdk';
+ *
+ * const client = new KnowledgeClient({ apiKey: 'your-api-key' });
+ *
+ * // 创建结构化知识库
+ * const res = await client.createKnowledgeBase({
+ *   file: fileBlob,
+ *   type: 'STRUCTURED',
+ *   tableSchema: {
+ *     columns: [
+ *       { name: 'id', dataType: 'STRING', required: true, order: 1 },
+ *       { name: 'name', dataType: 'STRING', required: false, order: 2 }
+ *     ],
+ *     name: '示例表'
+ *   },
+ *   indexColumns: ['id']
+ * });
+ * if (res.success) {
+ *   console.log(`文档 ID: ${res.data?.documentId}`);
+ * }
+ * ```
+ */
+class KnowledgeClient {
+    constructor(config) {
+        this.http = new HttpClient({
+            baseUrl: config.baseUrl ?? DEFAULT_BASE_URL,
+            apiKey: config.apiKey,
+            timeout: config.timeout,
+        });
+    }
+    // ============================================================
+    // 创建知识库
+    // ============================================================
+    /**
+     * 创建知识库
+     *
+     * 通过上传文件创建知识库，支持结构化和非结构化数据。
+     *
+     * @param request - 创建知识库请求
+     *   - `file`（必填）：上传的文件（如 .xlsx、.pdf 等）
+     *   - `type`（必填）：数据类型，`STRUCTURED`（结构化）或其他类型
+     *   - `tableSchema`（条件必填）：表格 Schema 定义，当 type = STRUCTURED 时必填
+     *   - `indexColumns`（条件必填）：索引列名列表，当 type = STRUCTURED 时必填
+     * @returns 创建知识库结果
+     *
+     * @example
+     * ```ts
+     * // 从本地文件创建结构化知识库
+     * const fileInput = document.querySelector('input[type="file"]');
+     * const file = fileInput.files[0];
+     *
+     * const res = await client.createKnowledgeBase({
+     *   file: file,
+     *   type: 'STRUCTURED',
+     *   tableSchema: {
+     *     columns: [
+     *       { name: 'id', dataType: 'STRING', required: true, order: 1 },
+     *       { name: 'message_id', dataType: 'STRING', required: false, order: 2 },
+     *       { name: 'content', dataType: 'STRING', required: false, order: 3 }
+     *     ],
+     *     name: '消息记录',
+     *     description: '用于存储消息数据'
+     *   },
+     *   indexColumns: ['id', 'message_id']
+     * });
+     *
+     * if (res.success) {
+     *   console.log(`创建成功，文档 ID: ${res.data?.documentId}`);
+     * } else {
+     *   console.error(`创建失败: ${res.errorMsg}`);
+     * }
+     * ```
+     */
+    async createKnowledgeBase(request) {
+        // 构建 FormData
+        const formData = new FormData();
+        formData.append('file', request.file);
+        formData.append('type', request.type);
+        // 当 type 为 STRUCTURED 时，需要添加 tableSchema 和 indexColumns
+        if (request.type === 'STRUCTURED') {
+            if (request.tableSchema) {
+                formData.append('tableSchema', JSON.stringify(request.tableSchema));
+            }
+            if (request.indexColumns && request.indexColumns.length > 0) {
+                // indexColumns 作为数组传递，每个元素单独 append
+                for (const col of request.indexColumns) {
+                    formData.append('indexColumns', col);
+                }
+            }
+        }
+        const raw = await this.http.postFormData(`${API_PREFIX$1}/knowledge/createKnowledgeBaseByDataSet`, formData);
+        if (!raw.success) {
+            return {
+                success: false,
+                errorCode: raw.errorCode,
+                errorMsg: raw.errorMsg,
+            };
+        }
+        return {
+            success: true,
+            data: raw.data,
+        };
+    }
+    // ============================================================
+    // 更新知识库
+    // ============================================================
+    /**
+     * 更新知识库
+     *
+     * 通过上传文件更新已有的知识库文档，支持覆盖更新和增量更新。
+     *
+     * @param request - 更新知识库请求
+     *   - `file`（必填）：上传的文件（如 .xlsx、.pdf 等）
+     *   - `type`（必填）：数据类型，`STRUCTURED`（结构化）或其他类型
+     *   - `documentId`（必填）：要更新的文档 ID（从创建响应中获取）
+     *   - `tableSchema`（可选）：表格 Schema 定义，结构化数据需要
+     *   - `updateMode`（可选）：更新模式，`OVERWRITE`（覆盖更新）或 `UPSERT`（增量更新，默认）
+     * @returns 更新知识库结果
+     *
+     * @example
+     * ```ts
+     * // 覆盖更新知识库
+     * const res = await client.updateKnowledgeBase({
+     *   file: newFile,
+     *   type: 'STRUCTURED',
+     *   documentId: '20251128999def29600J6WS04301922',
+     *   tableSchema: {
+     *     columns: [
+     *       { name: 'id', dataType: 'STRING', required: true, order: 1 },
+     *       { name: 'message_id', dataType: 'STRING', required: false, order: 2 },
+     *       { name: 'content', dataType: 'STRING', required: false, order: 3 }
+     *     ],
+     *     name: '消息记录'
+     *   },
+     *   updateMode: 'OVERWRITE'
+     * });
+     *
+     * if (res.success) {
+     *   console.log(`更新成功，文档 ID: ${res.data?.documentId}`);
+     * } else {
+     *   console.error(`更新失败: ${res.errorMsg}`);
+     * }
+     * ```
+     */
+    async updateKnowledgeBase(request) {
+        // 构建 FormData
+        const formData = new FormData();
+        formData.append('file', request.file);
+        formData.append('type', request.type);
+        formData.append('documentId', request.documentId);
+        // 可选：更新模式
+        if (request.updateMode) {
+            formData.append('updateMode', request.updateMode);
+        }
+        // 可选：tableSchema（结构化数据需要）
+        if (request.tableSchema) {
+            formData.append('tableSchema', JSON.stringify(request.tableSchema));
+        }
+        const raw = await this.http.postFormData(`${API_PREFIX$1}/knowledge/updateDocument`, formData);
+        if (!raw.success) {
+            return {
+                success: false,
+                errorCode: raw.errorCode,
+                errorMsg: raw.errorMsg,
+            };
+        }
+        return {
+            success: true,
+            data: raw.data,
+        };
+    }
+    // ============================================================
+    // 查询知识库列表
+    // ============================================================
+    /**
+     * 查询知识库列表
+     *
+     * 通过名称模糊查询知识库，返回知识库 ID 和基本信息。
+     *
+     * @param request - 查询请求
+     *   - `name`（可选）：知识库名称（支持模糊查询）
+     *   - `pageNo`（可选）：页码，从 1 开始，默认 1
+     *   - `pageSize`（可选）：每页条数，默认 10
+     * @returns 知识库列表
+     *
+     * @example
+     * ```ts
+     * // 查询知识库列表
+     * const res = await client.queryDatasetsList({
+     *   name: '用户知识库'
+     * });
+     *
+     * if (res.success) {
+     *   for (const item of res.data?.datasets ?? []) {
+     *     console.log(`ID: ${item.datasetId}, 名称: ${item.name}`);
+     *   }
+     * } else {
+     *   console.error(`查询失败: ${res.errorMsg}`);
+     * }
+     * ```
+     */
+    async queryDatasetsList(request = {}) {
+        // 构建查询参数
+        const queryParams = {};
+        if (request.name) {
+            queryParams.name = request.name;
+        }
+        if (request.pageNo !== undefined) {
+            queryParams.pageNo = String(request.pageNo);
+        }
+        if (request.pageSize !== undefined) {
+            queryParams.pageSize = String(request.pageSize);
+        }
+        // 查询知识库列表接口使用不同的域名 api.tbox.cn
+        const raw = await this.http.get(`https://api.tbox.cn/api/datasets/queryDatasetsList`, queryParams);
+        if (!raw.success) {
+            return {
+                success: false,
+                errorCode: raw.errorCode,
+                errorMsg: raw.errorMsg,
+            };
+        }
+        return {
+            success: true,
+            data: raw.data,
+        };
+    }
+    // ============================================================
+    // 检索知识库
+    // ============================================================
+    /**
+     * 检索知识库
+     *
+     * 通过自然语言查询知识库内容，返回相关度最高的内容片段。
+     * 支持两种方式获取知识库:
+     * 1. 直接传入 datasetId
+     * 2. 传入 name，SDK 会自动查询获取 datasetId
+     *
+     * @param request - 检索知识库请求
+     *   - `name`（可选）：知识库名称，SDK 会自动查询获取 datasetId
+     *   - `datasetId`（可选）：知识库 ID（优先使用）
+     *   - `query`（必填）：查询内容（自然语言描述）
+     * @returns 检索结果
+     *
+     * @example
+     * ```ts
+     * // 方式 1: 通过名称自动查询
+     * const res = await client.retrieve({
+     *   name: '用户知识库',
+     *   query: '消防安全管理制度'
+     * });
+     *
+     * // 方式 2: 直接传入 datasetId
+     * const res = await client.retrieve({
+     *   datasetId: '20251024999def29600U6J302721040',
+     *   query: '消防安全管理制度'
+     * });
+     *
+     * if (res.success) {
+     *   for (const item of res.data?.data ?? []) {
+     *     console.log(`文件: ${item.originFileName}`);
+     *     console.log(`内容: ${item.content}`);
+     *     console.log(`相关度: ${item.score}`);
+     *   }
+     * } else {
+     *   console.error(`检索失败: ${res.errorMsg}`);
+     * }
+     * ```
+     */
+    async retrieve(request) {
+        let datasetId = request.datasetId;
+        // 如果没有直接传入 datasetId，通过 name 查询
+        if (!datasetId && request.name) {
+            const queryRes = await this.queryDatasetsList({ name: request.name });
+            if (!queryRes.success) {
+                return {
+                    success: false,
+                    errorCode: queryRes.errorCode,
+                    errorMsg: queryRes.errorMsg,
+                };
+            }
+            const datasets = queryRes.data?.datasets ?? [];
+            if (datasets.length === 0) {
+                return {
+                    success: false,
+                    errorCode: 'KNOWLEDGE_NOT_FOUND',
+                    errorMsg: `未找到名称为 "${request.name}" 的知识库`,
+                };
+            }
+            datasetId = datasets[0].datasetId;
+        }
+        if (!datasetId) {
+            return {
+                success: false,
+                errorCode: 'INVALID_REQUEST',
+                errorMsg: '必须提供datasetId 参数',
+            };
+        }
+        // 检索接口使用不同的域名 api.tbox.cn
+        const raw = await this.http.post(`https://api.tbox.cn/api/datasets/retrieve`, {
+            datasetId,
+            query: request.query,
+        });
+        if (!raw.success) {
+            return {
+                success: false,
+                errorCode: raw.errorCode,
+                errorMsg: raw.errorMsg,
+            };
+        }
+        return {
+            success: true,
+            data: raw.data,
+        };
+    }
+}
+
+/**
+ * LLM SDK - LlmClient 核心类
+ *
+ * 封装大语言模型调用功能，提供 OpenAI 兼容的 Chat Completions 接口。
+ */
+/** API 路径前缀 */
+const API_PREFIX = '/compat/openai/v1';
+/**
+ * LLM 客户端
+ *
+ * 提供大语言模型调用能力，支持流式和非流式输出。
+ *
+ * @example
+ * ```ts
+ * import { LlmClient } from '@tbox/plugin-sdk';
+ *
+ * const client = new LlmClient({ apiKey: 'your-api-key' });
+ *
+ * // 流式调用
+ * const stream = await client.chatCompletions({
+ *   model: 'kimi-k2.5',
+ *   messages: [{ role: 'user', content: '你好' }],
+ *   stream: true
+ * });
+ *
+ * for await (const chunk of stream) {
+ *   process.stdout.write(chunk.choices[0]?.delta?.content ?? '');
+ * }
+ * ```
+ */
+class LlmClient {
+    constructor(config) {
+        this.http = new HttpClient({
+            baseUrl: config.baseUrl ?? DEFAULT_BASE_URL,
+            apiKey: config.apiKey,
+            timeout: config.timeout,
+        });
+    }
+    // ============================================================
+    // Chat Completions
+    // ============================================================
+    /**
+     * Chat Completions 对话补全
+     *
+     * 支持流式和非流式两种模式：
+     * - 流式（stream=true）：返回 AsyncIterable<ChatCompletionChunk>
+     * - 非流式（stream=false）：返回 ChatCompletionResponse
+     *
+     * @param request - 对话补全请求
+     *   - `model`（必填）：模型名称
+     *   - `messages`（必填）：对话消息列表
+     *   - `stream`（可选）：是否流式输出，默认 false
+     *   - `temperature`（可选）：温度参数，范围 0~2
+     *   - `top_p`（可选）：核采样参数，范围 0~1，推荐 0.95
+     *   - `max_tokens`（可选）：最大输出 token 数，推荐 8000
+     *   - `stream_options`（可选）：流式选项，`{ include_usage: true }` 可在末尾返回 token 用量
+     * @returns 流式返回 AsyncIterable，非流式返回完整响应
+     *
+     * @example
+     * ```ts
+     * // 流式调用
+     * const stream = await client.chatCompletions({
+     *   model: 'kimi-k2.5',
+     *   messages: [
+     *     { role: 'system', content: '你是一个有帮助的助手' },
+     *     { role: 'user', content: '你好，请介绍一下你自己' }
+     *   ],
+     *   stream: true,
+     *   stream_options: { include_usage: true }
+     * });
+     *
+     * for await (const chunk of stream) {
+     *   const content = chunk.choices[0]?.delta?.content;
+     *   if (content) {
+     *     process.stdout.write(content);
+     *   }
+     *   // 检查是否结束
+     *   if (chunk.choices[0]?.finish_reason === 'stop') {
+     *     console.log('\n对话结束');
+     *   }
+     *   // 获取 token 用量（需要 stream_options.include_usage=true）
+     *   if (chunk.usage) {
+     *     console.log(`Token 用量: ${chunk.usage.total_tokens}`);
+     *   }
+     * }
+     * ```
+     *
+     * @example
+     * ```ts
+     * // 非流式调用
+     * const response = await client.chatCompletions({
+     *   model: 'kimi-k2.5',
+     *   messages: [
+     *     { role: 'user', content: '你好' }
+     *   ],
+     *   stream: false
+     * });
+     *
+     * console.log(response.choices[0]?.message?.content);
+     * ```
+     */
+    async chatCompletions(request) {
+        // 流式模式
+        if (request.stream) {
+            return this.streamChatCompletions(request);
+        }
+        // 非流式模式
+        const response = await this.http.post(`${API_PREFIX}/chat/completions`, request);
+        if (!response.success) {
+            throw new Error(response.errorMsg ?? 'Chat completion failed');
+        }
+        return response.data;
+    }
+    /**
+     * 流式调用 Chat Completions
+     */
+    async *streamChatCompletions(request) {
+        const url = `${this.http['baseUrl']}${API_PREFIX}/chat/completions`;
+        const response = await fetch(url, {
+            method: 'POST',
+            headers: {
+                'Content-Type': 'application/json;charset=UTF-8',
+                Authorization: this.http['apiKey'],
+            },
+            body: JSON.stringify(request),
+        });
+        if (!response.ok) {
+            throw new Error(`HTTP error: ${response.status} ${response.statusText}`);
+        }
+        const reader = response.body?.getReader();
+        if (!reader) {
+            throw new Error('No response body');
+        }
+        const decoder = new TextDecoder('utf-8');
+        let buffer = '';
+        try {
+            while (true) {
+                const { done, value } = await reader.read();
+                if (done)
+                    break;
+                buffer += decoder.decode(value, { stream: true });
+                const lines = buffer.split('\n');
+                buffer = lines.pop() ?? '';
+                for (const line of lines) {
+                    const trimmed = line.trim();
+                    if (!trimmed || !trimmed.startsWith('data:'))
+                        continue;
+                    // 支持 "data:" 和 "data: " 两种格式
+                    const data = trimmed.startsWith('data: ')
+                        ? trimmed.slice(6)
+                        : trimmed.slice(5);
+                    if (data === '[DONE]')
+                        return;
+                    try {
+                        const chunk = JSON.parse(data);
+                        yield chunk;
+                    }
+                    catch {
+                        // 忽略解析错误
+                    }
+                }
+            }
+            // 处理剩余 buffer
+            if (buffer.trim()) {
+                const trimmed = buffer.trim();
+                if (trimmed.startsWith('data:')) {
+                    const data = trimmed.startsWith('data: ')
+                        ? trimmed.slice(6)
+                        : trimmed.slice(5);
+                    if (data !== '[DONE]') {
+                        try {
+                            const chunk = JSON.parse(data);
+                            yield chunk;
+                        }
+                        catch {
+                            // 忽略解析错误
+                        }
+                    }
+                }
+            }
+        }
+        finally {
+            reader.releaseLock();
+        }
+    }
+    /**
+     * 简化的对话方法
+     *
+     * 快速发起一次对话，自动处理流式输出。
+     *
+     * @param model - 模型名称
+     * @param messages - 对话消息列表
+     * @param options - 可选参数
+     * @returns 完整的对话内容（对于推理模型，返回推理内容 + 正式内容）
+     *
+     * @example
+     * ```ts
+     * const answer = await client.chat('kimi-k2.5', [
+     *   { role: 'user', content: '你好' }
+     * ]);
+     * console.log(answer);
+     * ```
+     */
+    async chat(model, messages, options) {
+        const stream = await this.chatCompletions({
+            model,
+            messages,
+            stream: true,
+            stream_options: { include_usage: true },
+            ...options,
+        });
+        let fullContent = '';
+        let reasoningContent = '';
+        for await (const chunk of stream) {
+            const content = chunk.choices?.[0]?.delta?.content;
+            const reasoning = chunk.choices?.[0]?.delta?.reasoning_content;
+            if (content) {
+                fullContent += content;
+            }
+            if (reasoning) {
+                reasoningContent += reasoning;
+            }
+        }
+        // 如果有推理内容但没有正式内容，返回推理内容
+        // 这对于 glm-5v-turbo 等推理模型很重要
+        if (!fullContent && reasoningContent) {
+            return reasoningContent;
+        }
+        return fullContent;
+    }
+}
+
+export { APIClient, APIError, APIResource, AmapClient, AuthenticationError, BadRequestError, Documents, ForbiddenError, GatewayError, InternalServerError, Knowledge, KnowledgeClient$1 as KnowledgeClient, KnowledgeScopedClient, KnowledgeClient as LegacyKnowledgeClient, LlmClient, NetworkError, NotFoundError, ParseError, RateLimitError, SDK_VERSION, SchemaRegistry, TBOX_BASE_URL, TboxAPI, TboxAppClient, TboxConversationClient, TboxError, TboxPluginClient, TimeoutError, knowledgeSchema };
+//# sourceMappingURL=index.esm.js.map