@tbox-dev-js/sdk 0.1.0 → 0.1.4

package/README.md

@@ -1,222 +1,453 @@
-# @tbox/plugin-sdk
+# @tbox-dev-js/sdk
 
-百宝箱平台插件服务 JavaScript SDK，封装了插件工具执行、TTS/ASR、插件信息查询等核心能力。
+百宝箱（Tbox）平台 JavaScript SDK，提供知识库管理、插件工具执行、LLM 对话、会话管理、高德地图等一站式客户端能力。
+
+**核心特性：**
+
+- 🚀 **配置驱动** — 通过 `knowledge.json` 业务配置文件驱动多知识库操作，AI Coding 友好
+- 🔐 **认证统一** — 全 SDK 共享一套 Token 配置，支持静态字符串或动态函数
+- 📦 **双格式支持** — 同时提供 ESM（`import`）和 CommonJS（`require`）构建产物
+- 🛡️ **类型安全** — 完整的 TypeScript 类型定义
+- 🧩 **模块化** — 知识库、插件、LLM、会话、地图等模块独立可用
 
 调用域名：`https://o.tbox.cn`
 
+---
+
 ## 安装
 
 ```bash
-npm install @tbox/plugin-sdk
+npm install @tbox-dev-js/sdk
 # 或
-yarn add @tbox/plugin-sdk
+yarn add @tbox-dev-js/sdk
 # 或
-pnpm add @tbox/plugin-sdk
+pnpm add @tbox-dev-js/sdk
 ```
 
+---
+
 ## 快速开始
 
+### 知识库管理（新架构 · 推荐）
+
 ```ts
-import { TboxPluginClient } from '@tbox/plugin-sdk';
+import { KnowledgeClient } from '@tbox-dev-js/sdk';
 
-const client = new TboxPluginClient({
-  apiKey: 'your-api-key', // 百宝箱应用 API Key
+// 从配置文件加载（支持多知识库）
+const client = new KnowledgeClient({
+  token: process.env.TBOX_API_KEY,
+  config: './config/knowledge.json',
 });
 
-// 按工具 ID 执行插件工具
-const result = await client.run('your-plugin-tool-id', {
+// Scoped 模式：绑定到具体知识库后调用
+const product = client.use('产品数据');
+const results = await product.retrieve('消防安全措施有哪些？');
+console.log(results.data);
+
+// Direct 模式：名称作为第一个参数
+const faqResults = await client.retrieve('FAQ', '如何重置密码？');
+```
+
+### 插件工具执行
+
+```ts
+import { TboxPluginClient } from '@tbox-dev-js/sdk';
+
+const client = new TboxPluginClient({ apiKey: 'your-api-key' });
+
+const result = await client.run('tool-id-xxx', {
   inputs: { city: '杭州' },
 });
 
 if (result.success) {
   console.log(result.data?.output);
-} else {
-  console.error(result.errorCode, result.errorMsg);
 }
 ```
 
-## 初始化配置
+### LLM 对话
 
 ```ts
-const client = new TboxPluginClient({
-  // 必填：API Key（百宝箱应用维度的 API Key）
-  apiKey: 'your-api-key',
+import { LlmClient } from '@tbox-dev-js/sdk';
 
-  // 可选：自定义 base URL，默认 https://o.tbox.cn
-  baseUrl: 'https://o.tbox.cn',
+const client = new LlmClient({ apiKey: 'your-api-key' });
 
-  // 可选：请求超时时间（毫秒）
-  timeout: 10000,
-});
+// 简化调用 — 自动处理流式输出，返回完整文本
+const answer = await client.chat('kimi-k2.5', [
+  { role: 'user', content: '你好，请介绍一下你自己' },
+]);
+console.log(answer);
 ```
 
-## API 文档
+---
+
+## 模块详解
 
-### `client.run(pluginToolId, request)` — 按工具 ID 执行插件
+### KnowledgeClient — 知识库管理
 
-**适用场景**：已知工具 ID，调用最直接、性能最好。
+配置驱动的多知识库客户端，支持语义检索、文档创建与更新。
+
+#### 构造方式
 
 ```ts
-const res = await client.run('tool-id-xxx', {
-  inputs: {
-    query: '今天杭州天气',
+import { KnowledgeClient, TboxAPI } from '@tbox-dev-js/sdk';
+
+// 方式一：直接创建（CJS 环境）
+const client = new KnowledgeClient({
+  token: process.env.TBOX_API_KEY,
+  config: './config/knowledge.json',
+});
+
+// 方式二：异步工厂（ESM 环境推荐）
+const client = await KnowledgeClient.fromFile(
+  { token: process.env.TBOX_API_KEY },
+  './config/knowledge.json',
+);
+
+// 方式三：从已有 TboxAPI 实例创建（共享连接）
+const tbox = new TboxAPI({ token: process.env.TBOX_API_KEY });
+const client = KnowledgeClient.fromTboxAPI(tbox, './config/knowledge.json');
+
+// 方式四：直接传配置对象（单知识库场景）
+const client = new KnowledgeClient({
+  token: process.env.TBOX_API_KEY,
+  config: {
+    datasetId: 'your-dataset-id',
+    type: 'STRUCTURED',
+    topK: 5,
+    tableSchema: { name: '产品表', columns: [] },
   },
 });
-// res.data: PluginExecResult
 ```
 
-| 参数 | 类型 | 说明 |
-|------|------|------|
-| `pluginToolId` | `string` | 插件工具 ID |
-| `request.inputs` | `Record<string, unknown>` | 工具输入参数 |
+#### API 方法
+
+| 方法 | KnowledgeClient 签名 | KnowledgeScopedClient 签名 | 说明 |
+|------|----------------------|---------------------------|------|
+| `use` | `use(name)` | — | 获取绑定到指定知识库的 Scoped Client |
+| `list` | `list(name?, pageNo?, pageSize?)` | — | 查询知识库列表（共享，不绑定具体知识库） |
+| `retrieve` | `retrieve(name, query, options?)` | `retrieve(query, options?)` | 语义检索 |
+| `create` | `create(name, file, options?)` | `create(file, options?)` | 上传文件创建知识库文档 |
+| `update` | `update(name, file, options?)` | `update(file, options?)` | 更新知识库文档 |
+
+#### knowledge.json 配置文件
+
+```json
+{
+  "config": {
+    "type": "STRUCTURED",
+    "topK": 5,
+    "scoreThreshold": 0.5,
+    "updateMode": "UPSERT",
+    "pageSize": 10
+  },
+  "tools": ["list", "retrieve", "create", "update"],
+  "knowledges": {
+    "产品数据": {
+      "datasetId": "your-dataset-id",
+      "documentId": "",
+      "config": { "topK": 10, "scoreThreshold": 0.7 },
+      "tableSchema": {
+        "name": "产品表",
+        "columns": [
+          { "name": "id", "dataType": "STRING", "primaryKey": true },
+          { "name": "title", "dataType": "STRING" },
+          { "name": "price", "dataType": "FLOAT" }
+        ]
+      },
+      "indexColumns": ["id"]
+    },
+    "FAQ": {
+      "datasetId": "your-faq-dataset-id",
+      "documentId": "",
+      "tableSchema": { "name": "FAQ表", "columns": [] },
+      "indexColumns": []
+    }
+  }
+}
+```
+
+**Config 继承机制**：方法参数 > 知识库自身 config > 全局 config > 代码默认值
+
+**Tools 运行时校验**：如果配置了 `tools` 字段，调用未声明的操作会抛出错误。
 
 ---
 
-### `client.runByToolName(pluginId, toolName, request)` — 按工具名称执行插件
+### TboxPluginClient — 插件工具执行
 
-**适用场景**：已知插件 ID 和工具名称，SDK 内部自动解析工具 ID。
+封装 `/openapi/v1/plugin` 下的全部接口。
 
 ```ts
-const res = await client.runByToolName('plugin-id', 'weather_search', {
-  inputs: { city: '上海' },
+import { TboxPluginClient } from '@tbox-dev-js/sdk';
+
+const client = new TboxPluginClient({
+  apiKey: 'your-api-key',
+  baseUrl: 'https://o.tbox.cn',  // 可选，默认值
+  timeout: 10000,                 // 可选，毫秒
 });
 ```
 
-| 参数 | 类型 | 说明 |
+| 方法 | 说明 | 示例 |
 |------|------|------|
-| `pluginId` | `string` | 插件 ID |
-| `toolName` | `string` | 工具名称 |
-| `request.inputs` | `Record<string, unknown>` | 工具输入参数 |
+| `run(toolId, request)` | 按工具 ID 执行插件 | `client.run('tool-id', { inputs: { city: '杭州' } })` |
+| `getPluginInfo(pluginId)` | 查询插件信息及工具列表 | `client.getPluginInfo('plugin-id')` |
+| `webSearch(request)` | 网络搜索（内置工具 ID） | `client.webSearch({ q: '上海天气' })` |
+| `doTts(request)` | 文字转语音 | `client.doTts({ text: '你好' })` |
+| `asrBase64(request)` | 语音转文字（Base64 输入） | `client.asrBase64({ audioBase64: '...' })` |
 
 ---
 
-### `client.getPluginInfo(pluginId)` — 查询插件信息
+### LlmClient — LLM 大模型对话
 
-查询插件配置信息，包含插件下的工具列表及参数定义。
+提供 OpenAI 兼容的 Chat Completions 接口，支持流式和非流式输出。
 
 ```ts
-const res = await client.getPluginInfo('plugin-id');
-if (res.success) {
-  const tools = res.data?.pluginToolList;
-  tools?.forEach(tool => {
-    console.log(tool.name, tool.description);
-  });
+import { LlmClient } from '@tbox-dev-js/sdk';
+
+const client = new LlmClient({ apiKey: 'your-api-key' });
+```
+
+#### 简化调用
+
+```ts
+const answer = await client.chat('kimi-k2.5', [
+  { role: 'system', content: '你是一个有帮助的助手' },
+  { role: 'user', content: '你好' },
+], { temperature: 0.7, max_tokens: 2000 });
+
+console.log(answer);
+```
+
+#### 流式调用
+
+```ts
+const stream = await client.chatCompletions({
+  model: 'kimi-k2.5',
+  messages: [{ 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.usage) {
+    console.log(`\nToken 用量: ${chunk.usage.total_tokens}`);
+  }
 }
 ```
 
+#### 非流式调用
+
+```ts
+const response = await client.chatCompletions({
+  model: 'kimi-k2.5',
+  messages: [{ role: 'user', content: '你好' }],
+  stream: false,
+});
+
+console.log(response.choices?.[0]?.message?.content);
+```
+
 ---
 
-### `client.submitToolOutput(request)` — 提交工具输出
+### TboxConversationClient — 会话管理
 
-在 Agent 调用工具后，将工具执行结果回传给平台。
+封装 `/openapi/v1/conversation` 下的全部接口。
 
 ```ts
-const res = await client.submitToolOutput({
-  agent_id: 'app-id-xxx',       // 百宝箱应用 ID
-  tool_call_id: 'call-id-yyy',  // 工具调用 ID
-  output: { result: '晴天，25°C' },
-});
+import { TboxConversationClient } from '@tbox-dev-js/sdk';
+
+const client = new TboxConversationClient({ apiKey: 'your-api-key' });
 ```
 
+| 方法 | 说明 | 示例 |
+|------|------|------|
+| `createConversation(request)` | 创建新会话 | `client.createConversation({ agentId: 'app-id', userId: 'user-id' })` |
+| `listConversations(request)` | 查询会话列表（分页） | `client.listConversations({ agentId: 'app-id', pageNum: 1 })` |
+| `listMessages(request)` | 查询消息列表（分页） | `client.listMessages({ conversationId: 'conv-id' })` |
+| `saveMessage(request)` | 保存对话消息 | `client.saveMessage({ conversationId: 'conv-id', query: '...', answer: '...' })` |
+
 ---
 
-### `client.doTts(request)` — 文字转语音
+### TboxAppClient — 应用服务
+
+封装 `/openapi/v1/app` 下的接口。
 
 ```ts
-const res = await client.doTts({
-  text: '你好，欢迎使用百宝箱',
-  voice: 'xiaoyun',   // 可选，发音人
-  speechRate: 0,      // 可选，语速 -500~500
+import { TboxAppClient } from '@tbox-dev-js/sdk';
+
+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 (res.success) {
-  const audioBase64 = res.data?.audioBase64;
+
+if (result.success) {
+  console.log('sessionId:', result.data?.sessionId);
 }
 ```
 
 ---
 
-### `client.asrBase64(request)` — 语音转文字
+### AmapClient — 高德地图服务
 
-输入 Base64 编码的音频数据，返回识别文本。
+通过百宝箱插件服务调用高德地图 API，支持天气查询、地理编码、路线规划等。
 
 ```ts
-const res = await client.asrBase64({
-  audioBase64: '<base64-encoded-audio>',
-  format: 'mp3',       // 可选，音频格式
-  sampleRate: 16000,   // 可选，采样率
+import { AmapClient } from '@tbox-dev-js/sdk';
+
+const client = new AmapClient({ apiKey: 'your-api-key' });
+```
+
+| 方法 | 说明 |
+|------|------|
+| `weather(request)` | 天气查询 |
+| `geocode(request)` | 地址转经纬度 |
+| `regeocode(request)` | 经纬度转地址 |
+| `ipLocation(request)` | IP 定位 |
+| `peripheralSearch(request)` | 周边搜索 |
+| `poiSearch(request)` | POI 关键字搜索 |
+| `walkingRoute(request)` | 步行路线规划 |
+| `cyclingRoute(request)` | 骑行路线规划 |
+| `drivingRoute(request)` | 驾车路线规划 |
+| `ebikeRoute(request)` | 电动车路线规划 |
+| `transitRoute(request)` | 公交路线规划 |
+| `district(request)` | 行政区域查询 |
+| `convert(request)` | 坐标转换 |
+
+---
+
+### TboxAPI — 底层资源访问（高级用户）
+
+直接访问底层 API 资源，适合需要精细控制的场景。
+
+```ts
+import { TboxAPI } from '@tbox-dev-js/sdk';
+
+const tbox = new TboxAPI({
+  token: process.env.TBOX_API_KEY,
+  baseURL: 'https://o.tbox.cn',
+  timeout: 10000,
+  debug: true,
 });
-if (res.success) {
-  console.log(res.data?.text);
-}
+
+// 知识库 API
+await tbox.knowledge.list({ name: '搜索关键词' });
+await tbox.knowledge.retrieve({ datasetId: '...', query: '查询文本', topK: 5 });
+await tbox.knowledge.documents.create({ file, type: 'STRUCTURED', tableSchema });
+await tbox.knowledge.documents.update({ documentId: '...', file, type: 'STRUCTURED' });
+
+// Schema Registry — 获取 API 的 JSON Schema 描述
+const schema = tbox.schemas.get('knowledge');
+console.log(schema?.operations);
 ```
 
 ---
 
 ## 统一响应格式
 
-所有方法均返回 `Promise<SdkResponse<T>>`：
+旧架构客户端（`TboxPluginClient`、`TboxConversationClient`、`TboxAppClient`、`AmapClient`）的所有方法均返回 `SdkResponse<T>`：
 
 ```ts
 interface SdkResponse<T> {
-  success: boolean;      // 是否成功
-  data?: T;              // 响应数据（成功时）
-  errorCode?: string;    // 错误码（失败时）
-  errorMsg?: string;     // 错误信息（失败时）
+  success: boolean;
+  data?: T;
+  errorCode?: string;
+  errorMsg?: string;
 }
 ```
 
-## 错误处理
+新架构客户端（`TboxAPI`、`KnowledgeClient`）直接返回业务数据，错误通过异常抛出：
 
 ```ts
-const res = await client.run('tool-id', { inputs: {} });
-
-if (!res.success) {
-  switch (res.errorCode) {
-    case 'NETWORK_ERROR':
-      console.error('网络请求失败:', res.errorMsg);
-      break;
-    case 'HTTP_401':
-      console.error('API Key 无效或已过期');
-      break;
-    default:
-      console.error(`调用失败 [${res.errorCode}]:`, res.errorMsg);
+import { APIError, AuthenticationError, NetworkError } from '@tbox-dev-js/sdk';
+
+try {
+  const results = await client.retrieve('产品数据', '查询文本');
+} catch (error) {
+  if (error instanceof AuthenticationError) {
+    console.error('Token 无效或已过期');
+  } else if (error instanceof NetworkError) {
+    console.error('网络请求失败');
+  } else if (error instanceof APIError) {
+    console.error(`API 错误 [${error.status}]:`, error.message);
   }
 }
 ```
 
-## 兼容环境
+---
+
+## 环境要求
 
-- **Node.js** >= 18（原生支持 `fetch`）
+- **Node.js** >= 16.0.0
 - **浏览器**：支持 `fetch` API 的现代浏览器
 - **模块格式**：ESM（`import`）+ CJS（`require`）双格式
 
+---
+
 ## 项目结构
 
 ```
 tbox-js/
 ├── src/
-│   ├── types.ts      # TypeScript 类型定义
-│   ├── http.ts       # 底层 HTTP 封装
-│   ├── plugin.ts     # TboxPluginClient 核心类
-│   └── index.ts      # 统一导出入口
-├── dist/             # 构建产物（npm 发布内容）
-│   ├── index.js      # CJS 格式
-│   ├── index.esm.js  # ESM 格式
-│   └── index.d.ts    # TypeScript 类型声明
+│   ├── core.ts                          # APIClient 核心基类（认证、请求、错误处理）
+│   ├── tbox-api.ts                      # SDK 入口类（挂载子模块 + SchemaRegistry）
+│   ├── knowledge-client.ts              # 配置驱动的多知识库客户端
+│   ├── resources/knowledge/             # Knowledge 资源模块
+│   │   ├── index.ts                     #   list、retrieve
+│   │   ├── documents.ts                 #   create、update（FormData 上传）
+│   │   ├── types.ts                     #   类型定义
+│   │   └── schema.ts                    #   JSON Schema 定义
+│   ├── schema.ts                        # ResourceSchema 类型体系 + SchemaRegistry
+│   ├── plugin.ts                        # 插件工具执行客户端
+│   ├── conversation.ts                  # 会话管理客户端
+│   ├── app.ts                           # 应用服务客户端
+│   ├── amap.ts                          # 高德地图客户端
+│   ├── llm.ts                           # LLM 大模型对话客户端
+│   ├── http.ts                          # 旧架构 HTTP 封装
+│   ├── error.ts                         # 错误类层级
+│   ├── resource.ts                      # APIResource 基类
+│   ├── constant.ts                      # 常量定义
+│   ├── types.ts                         # 旧架构类型定义
+│   └── index.ts                         # 统一导出入口
+├── config/
+│   └── knowledge.json                   # 知识库业务配置文件
+├── docs/
+│   └── knowledge-client.md              # KnowledgeClient 设计文档
+├── scripts/
+│   └── publish.sh                       # npm 发布脚本
+├── dist/                                # 构建产物
+│   ├── index.cjs                        #   CJS 格式
+│   ├── index.esm.js                     #   ESM 格式
+│   └── index.d.ts                       #   TypeScript 类型声明
 ├── package.json
 ├── tsconfig.json
 └── rollup.config.js
 ```
 
+---
+
 ## 开发构建
 
 ```bash
 # 安装依赖
 npm install
 
+# 类型检查
+npm run typecheck
+
 # 构建产物
 npm run build
 
-# 类型检查
-npm run typecheck
+# 清理构建产物
+npm run clean
 ```
+
+## 许可证
+
+MIT

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tbox-dev-js/sdk",
-  "version": "0.1.0",
+  "version": "0.1.4",
   "description": "百宝箱平台 JavaScript SDK — 知识库、插件、会话等服务的统一客户端",
   "type": "module",
   "main": "dist/index.cjs",