@tbox-dev-js/sdk 0.1.0

package/dist/knowledge.d.ts

@@ -0,0 +1,185 @@
+/**
+ * 知识库 SDK - KnowledgeClient 核心类
+ *
+ * 封装知识库管理功能，通过百宝箱服务接口实现知识库的创建和管理。
+ */
+import type { KnowledgeClientConfig, KnowledgeCreateRequest, KnowledgeCreateResponse, KnowledgeUpdateRequest, KnowledgeUpdateResponse, KnowledgeQueryListRequest, KnowledgeQueryListResponse, KnowledgeRetrieveRequest, KnowledgeRetrieveResponse, SdkResponse } from './types';
+/**
+ * 知识库客户端
+ *
+ * @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}`);
+ * }
+ * ```
+ */
+export declare class KnowledgeClient {
+    private readonly http;
+    constructor(config: KnowledgeClientConfig);
+    /**
+     * 创建知识库
+     *
+     * 通过上传文件创建知识库，支持结构化和非结构化数据。
+     *
+     * @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}`);
+     * }
+     * ```
+     */
+    createKnowledgeBase(request: KnowledgeCreateRequest): Promise<SdkResponse<KnowledgeCreateResponse>>;
+    /**
+     * 更新知识库
+     *
+     * 通过上传文件更新已有的知识库文档，支持覆盖更新和增量更新。
+     *
+     * @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}`);
+     * }
+     * ```
+     */
+    updateKnowledgeBase(request: KnowledgeUpdateRequest): Promise<SdkResponse<KnowledgeUpdateResponse>>;
+    /**
+     * 查询知识库列表
+     *
+     * 通过名称模糊查询知识库，返回知识库 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}`);
+     * }
+     * ```
+     */
+    queryDatasetsList(request?: KnowledgeQueryListRequest): Promise<SdkResponse<KnowledgeQueryListResponse>>;
+    /**
+     * 检索知识库
+     *
+     * 通过自然语言查询知识库内容，返回相关度最高的内容片段。
+     * 支持两种方式获取知识库:
+     * 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}`);
+     * }
+     * ```
+     */
+    retrieve(request: KnowledgeRetrieveRequest): Promise<SdkResponse<KnowledgeRetrieveResponse>>;
+}

package/dist/llm.d.ts

@@ -0,0 +1,121 @@
+/**
+ * LLM SDK - LlmClient 核心类
+ *
+ * 封装大语言模型调用功能，提供 OpenAI 兼容的 Chat Completions 接口。
+ */
+import type { LlmClientConfig, ChatCompletionRequest, ChatCompletionResponse, ChatCompletionChunk, ChatMessage } from './types';
+/**
+ * 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 ?? '');
+ * }
+ * ```
+ */
+export declare class LlmClient {
+    private readonly http;
+    constructor(config: LlmClientConfig);
+    /**
+     * 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);
+     * ```
+     */
+    chatCompletions(request: ChatCompletionRequest): Promise<ChatCompletionResponse | AsyncIterable<ChatCompletionChunk>>;
+    /**
+     * 流式调用 Chat Completions
+     */
+    private streamChatCompletions;
+    /**
+     * 简化的对话方法
+     *
+     * 快速发起一次对话，自动处理流式输出。
+     *
+     * @param model - 模型名称
+     * @param messages - 对话消息列表
+     * @param options - 可选参数
+     * @returns 完整的对话内容（对于推理模型，返回推理内容 + 正式内容）
+     *
+     * @example
+     * ```ts
+     * const answer = await client.chat('kimi-k2.5', [
+     *   { role: 'user', content: '你好' }
+     * ]);
+     * console.log(answer);
+     * ```
+     */
+    chat(model: string, messages: ChatMessage[], options?: {
+        temperature?: number;
+        top_p?: number;
+        max_tokens?: number;
+    }): Promise<string>;
+}

package/dist/plugin.d.ts

@@ -0,0 +1,118 @@
+/**
+ * 百宝箱插件服务 SDK - PluginClient 核心类
+ *
+ * 封装 /openapi/v1/plugin 下的全部接口
+ */
+import type { TboxPluginClientConfig, TtsRequest, TtsResponse, AsrRequest, AsrResponse, PluginToolExecRequest, PluginExecResult, PluginInfo, WebSearchRequest, WebSearchResponse, SdkResponse } from './types';
+/**
+ * 百宝箱插件服务客户端
+ *
+ * @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' } });
+ * ```
+ */
+export declare class TboxPluginClient {
+    private readonly http;
+    constructor(config: TboxPluginClientConfig);
+    /**
+     * 文字转语音
+     *
+     * 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);
+     * }
+     * ```
+     */
+    doTts(request: TtsRequest): Promise<SdkResponse<TtsResponse>>;
+    /**
+     * 语音转文字（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);
+     * }
+     * ```
+     */
+    asrBase64(request: AsrRequest): Promise<SdkResponse<AsrResponse>>;
+    /**
+     * 按工具 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);
+     * }
+     * ```
+     */
+    run(pluginToolId: string, request: PluginToolExecRequest): Promise<SdkResponse<PluginExecResult>>;
+    /**
+     * 查询插件配置信息（含工具集）
+     *
+     * 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);
+     * }
+     * ```
+     */
+    getPluginInfo(pluginId: string): Promise<SdkResponse<PluginInfo>>;
+    /** 网络搜索工具的固定工具 ID */
+    private static readonly WEB_SEARCH_TOOL_ID;
+    /**
+     * 网络搜索
+     *
+     * 内部调用 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);
+     *   }
+     * }
+     * ```
+     */
+    webSearch(request: WebSearchRequest): Promise<SdkResponse<WebSearchResponse>>;
+}

package/dist/resource.d.ts

@@ -0,0 +1,11 @@
+/**
+ * @tbox/sdk — APIResource 基类
+ *
+ * 所有 Resource 子类（Knowledge、Plugins 等）继承此类，
+ * 通过 this._client 引用 APIClient 发起请求。
+ */
+import type { APIClient } from './core';
+export declare class APIResource {
+    protected _client: APIClient;
+    constructor(client: APIClient);
+}

package/dist/resources/knowledge/documents.d.ts

@@ -0,0 +1,24 @@
+/**
+ * @tbox/sdk — Knowledge Documents sub-resource
+ *
+ * Handles knowledge base creation and update (multipart/form-data uploads).
+ */
+import { APIResource } from '../../resource';
+import type { RequestOptions } from '../../core';
+import type { DocumentCreateParams, DocumentCreateResult, DocumentUpdateParams, DocumentUpdateResult } from './types';
+export declare class Documents extends APIResource {
+    /**
+     * Create a knowledge base by uploading a file.
+     *
+     * POST /openapi/v1/knowledge/createKnowledgeBaseByDataSet
+     * Content-Type: multipart/form-data
+     */
+    create(params: DocumentCreateParams, options?: RequestOptions): Promise<DocumentCreateResult>;
+    /**
+     * Update an existing knowledge base document.
+     *
+     * POST /openapi/v1/knowledge/updateDocument
+     * Content-Type: multipart/form-data
+     */
+    update(params: DocumentUpdateParams, options?: RequestOptions): Promise<DocumentUpdateResult>;
+}

package/dist/resources/knowledge/index.d.ts

@@ -0,0 +1,28 @@
+/**
+ * @tbox/sdk — Knowledge Resource
+ *
+ * Provides knowledge base list, semantic retrieval, and document management.
+ */
+import { APIResource } from '../../resource';
+import type { APIClient, RequestOptions } from '../../core';
+import { Documents } from './documents';
+import type { DatasetListParams, DatasetListResult, RetrieveParams, RetrieveResult } from './types';
+export declare class Knowledge extends APIResource {
+    /** Document management sub-resource (create / update). */
+    readonly documents: Documents;
+    constructor(client: APIClient);
+    /**
+     * Query knowledge base list.
+     *
+     * GET /api/datasets/queryDatasetsList
+     */
+    list(params?: DatasetListParams, options?: RequestOptions): Promise<DatasetListResult>;
+    /**
+     * Semantic retrieval against a knowledge base.
+     *
+     * POST /api/datasets/retrieve
+     */
+    retrieve(params: RetrieveParams, options?: RequestOptions): Promise<RetrieveResult>;
+}
+export { Documents } from './documents';
+export type { DatasetListParams, DatasetListResult, DatasetInfo, RetrieveParams, RetrieveResult, RetrieveRecord, DocumentCreateParams, DocumentCreateResult, DocumentUpdateParams, DocumentUpdateResult, TableSchema, ColumnSchema, } from './types';

package/dist/resources/knowledge/schema.d.ts

@@ -0,0 +1,9 @@
+/**
+ * @tbox/sdk — Knowledge 模块 ResourceSchema 定义
+ *
+ * 用 JSON Schema 风格描述知识库的 4 个核心 API 操作，
+ * 端侧可据此动态渲染表单、校验参数、生成配置。
+ */
+import type { ResourceDefinition } from '../../schema';
+/** Knowledge resource schema — the complete definition */
+export declare const knowledgeSchema: ResourceDefinition;

package/dist/resources/knowledge/types.d.ts

@@ -0,0 +1,117 @@
+/**
+ * @tbox/sdk — Knowledge 模块类型定义
+ */
+export interface DatasetListParams {
+    /** 知识库名称（模糊搜索） */
+    name?: string;
+    /** 页码，从 1 开始 */
+    pageNo?: number;
+    /** 每页条数 */
+    pageSize?: number;
+}
+export interface DatasetListResult {
+    /** 知识库列表 */
+    data: DatasetInfo[];
+    /** 总条数 */
+    totalCount: number;
+}
+export interface DatasetInfo {
+    /** 知识库 ID */
+    datasetId: string;
+    /** 知识库名称 */
+    name: string;
+    /** 知识库描述 */
+    description?: string;
+    /** 知识库类型 */
+    type: 'STRUCTURED' | 'UNSTRUCTURED';
+    /** 文档数量 */
+    documentCount?: number;
+    /** 存储大小 */
+    storageSize?: number;
+    /** 创建时间 */
+    createdAt?: string;
+    /** 更新时间 */
+    updatedAt?: string;
+}
+export interface RetrieveParams {
+    /** 知识库 ID（必填） */
+    datasetId: string;
+    /** 检索查询文本（必填） */
+    query: string;
+    /** 返回结果数量上限 */
+    topK?: number;
+    /** 最低相关度分数阈值 */
+    scoreThreshold?: number;
+}
+export interface RetrieveResult {
+    /** 检索结果列表 */
+    data: RetrieveRecord[];
+}
+export interface RetrieveRecord {
+    /** 文档片段内容 */
+    content: string;
+    /** 相关度分数 (0~1) */
+    score: number;
+    /** 来源文件名 */
+    originFileName?: string;
+    /** 来源文档 ID */
+    documentId?: string;
+    /** 元数据 */
+    metadata?: Record<string, unknown>;
+}
+export interface DocumentCreateParams {
+    /** 上传的文件（必填） */
+    file: Blob;
+    /** 知识库类型（必填） */
+    type: 'STRUCTURED' | 'UNSTRUCTURED';
+    /** 表结构定义（STRUCTURED 类型必填） */
+    tableSchema?: TableSchema;
+    /** 索引列名列表 */
+    indexColumns?: string[];
+}
+export interface TableSchema {
+    /** 表名 */
+    name: string;
+    /** 表描述 */
+    description?: string;
+    /** 列定义列表 */
+    columns: ColumnSchema[];
+}
+export interface ColumnSchema {
+    /** Column name */
+    name: string;
+    /** Data type (e.g. "STRING", "INTEGER") */
+    dataType?: string;
+    /** Whether this column is a primary key */
+    primaryKey?: boolean;
+    /** Whether this column is required */
+    required?: boolean;
+    /** Column description */
+    description?: string;
+    /** Default value */
+    defaultValue?: string;
+    /** Sort order */
+    order?: number;
+}
+export interface DocumentCreateResult {
+    /** 创建的文档 ID */
+    documentId: string;
+}
+export interface DocumentUpdateParams {
+    /** 要更新的文档 ID（必填） */
+    documentId: string;
+    /** 上传的新文件（必填） */
+    file: Blob;
+    /** 知识库类型（必填） */
+    type: 'STRUCTURED' | 'UNSTRUCTURED';
+    /** 更新模式：OVERWRITE（覆盖） / UPSERT（增量，默认） */
+    updateMode?: 'OVERWRITE' | 'UPSERT';
+    /** 表结构定义 */
+    tableSchema?: TableSchema;
+    /** 索引列名列表 */
+    indexColumns?: string[];
+}
+export interface DocumentUpdateResult {
+    /** 更新的文档 ID */
+    documentId: string;
+}