@tbox-dev-js/sdk 0.1.4 → 0.1.6

package/README.md

@@ -1,19 +1,25 @@
 # @tbox-dev-js/sdk
 
-百宝箱（Tbox）平台 JavaScript SDK，提供知识库管理、插件工具执行、LLM 对话、会话管理、高德地图等一站式客户端能力。
+百宝箱（Tbox）平台 JavaScript SDK，提供知识库管理、插件工具执行、LLM 对话、首页开场白、会话管理、高德地图等一站式客户端能力。
 
 **核心特性：**
 
 - 🚀 **配置驱动** — 通过 `knowledge.json` 业务配置文件驱动多知识库操作，AI Coding 友好
-- 🔐 **认证统一** — 全 SDK 共享一套 Token 配置，支持静态字符串或动态函数
+- 🔐 **双鉴权模式** — 支持 B端（API Key）和 C端（Session）两种鉴权，自动桥接
 - 📦 **双格式支持** — 同时提供 ESM（`import`）和 CommonJS（`require`）构建产物
 - 🛡️ **类型安全** — 完整的 TypeScript 类型定义
-- 🧩 **模块化** — 知识库、插件、LLM、会话、地图等模块独立可用
+- 🧩 **模块化** — 知识库、插件、LLM、首页、会话、地图等模块独立可用
 
 调用域名：`https://o.tbox.cn`
 
 ---
 
+## 获取 API Key
+
+API Key 需要从 **百宝箱平台开发网关后台** 申请获取，用于 B端接口鉴权。
+
+---
+
 ## 安装
 
 ```bash
@@ -26,14 +32,53 @@ pnpm add @tbox-dev-js/sdk
 
 ---
 
+## 鉴权模式
+
+SDK 支持两种鉴权模式，适用于不同的接口场景：
+
+| 模式 | 请求头 | 适用客户端 | 说明 |
+|------|--------|-----------|------|
+| **B端** | `Authorization: <apiKey>` | `TboxPluginClient`、`TboxAppClient`、`TboxConversationClient`、`LlmClient`、`AmapClient`、`KnowledgeClient` | 服务端直接调用，使用 API Key |
+| **C端** | `TBOXSESSIONID` + `X-Tbox-Channel` + `X-Tbox-AppId` | `TboxHomepageClient` | 面向终端用户，需先通过 `generateSession` 获取 Session |
+
+**C端鉴权流程：**
+
+```
+B端 apiKey → TboxAppClient.generateSession() → sessionId + channel → C端请求头
+```
+
+---
+
 ## 快速开始
 
+### 首页开场白（C端鉴权）
+
+```ts
+import { TboxHomepageClient } from '@tbox-dev-js/sdk';
+
+// 一步到位：自动获取 session 并创建客户端
+const client = await TboxHomepageClient.create({
+  apiKey: 'your-api-key',   // B端 API Key，从百宝箱平台开发网关后台获取
+  appId: 'your-app-id',
+  userId: 'user-123',
+});
+
+const result = await client.get({
+  agentId: 'your-agent-id',
+  extInfo: '{}',
+});
+
+if (result.success) {
+  console.log('开场白:', result.data?.prologue);
+  console.log('推荐问题:', result.data?.suggestQuestions);
+}
+```
+
 ### 知识库管理（新架构 · 推荐）
 
 ```ts
 import { KnowledgeClient } from '@tbox-dev-js/sdk';
 
-// 从配置文件加载（支持多知识库）
 const client = new KnowledgeClient({
   token: process.env.TBOX_API_KEY,
   config: './config/knowledge.json',
@@ -48,7 +93,7 @@ console.log(results.data);
 const faqResults = await client.retrieve('FAQ', '如何重置密码？');
 ```
 
-### 插件工具执行
+### 插件工具执行（B端鉴权）
 
 ```ts
 import { TboxPluginClient } from '@tbox-dev-js/sdk';
@@ -64,7 +109,7 @@ if (result.success) {
 }
 ```
 
-### LLM 对话
+### LLM 对话（B端鉴权）
 
 ```ts
 import { LlmClient } from '@tbox-dev-js/sdk';
@@ -82,6 +127,68 @@ console.log(answer);
 
 ## 模块详解
 
+### TboxHomepageClient — 首页开场白（C端鉴权）
+
+封装 `/agent/v1/homepage` 下的接口，走 C端 Session 鉴权。
+
+#### 构造方式
+
+```ts
+import { TboxHomepageClient } from '@tbox-dev-js/sdk';
+
+// 方式一：自动获取 session（推荐）
+// 内部自动调用 generateSession 获取 sessionId + channel
+const client = await TboxHomepageClient.create({
+  apiKey: 'your-api-key',   // B端 API Key
+  appId: 'your-app-id',     // 百宝箱应用 ID
+  userId: 'user-123',       // 用户 ID
+});
+
+// 方式二：手动传入已有的 session
+const client = new TboxHomepageClient({
+  session: {
+    sessionId: '00a42411d8anzMXjKa3UcibPq',
+    channel: 'alipay_mini_app',
+    appId: 'your-app-id',
+  },
+});
+```
+
+#### API 方法
+
+| 方法 | 说明 | 示例 |
+|------|------|------|
+| `create(options)` | 静态工厂：自动获取 session 并创建客户端 | `TboxHomepageClient.create({ apiKey, appId, userId })` |
+| `get(request)` | 获取首页开场白 | `client.get({ agentId: 'xxx', extInfo: '{}' })` |
+
+---
+
+### TboxAppClient — 应用服务 & C端鉴权桥接（B端鉴权）
+
+封装 `/openapi/v1/app` 下的接口。核心功能是 `generateSession`，用于将 B端 API Key 转换为 C端 Session 鉴权信息。
+
+```ts
+import { TboxAppClient } from '@tbox-dev-js/sdk';
+
+const client = new TboxAppClient({ apiKey: 'your-api-key' });
+
+// 生成 sessionId + channel（C端鉴权的基础）
+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);
+  // 可用于构造 C端鉴权的 TboxHomepageClient 等
+}
+```
+
+---
+
 ### KnowledgeClient — 知识库管理
 
 配置驱动的多知识库客户端，支持语义检索、文档创建与更新。
@@ -124,7 +231,7 @@ const client = new KnowledgeClient({
 | 方法 | KnowledgeClient 签名 | KnowledgeScopedClient 签名 | 说明 |
 |------|----------------------|---------------------------|------|
 | `use` | `use(name)` | — | 获取绑定到指定知识库的 Scoped Client |
-| `list` | `list(name?, pageNo?, pageSize?)` | — | 查询知识库列表（共享，不绑定具体知识库） |
+| `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?)` | 更新知识库文档 |
@@ -172,7 +279,7 @@ const client = new KnowledgeClient({
 
 ---
 
-### TboxPluginClient — 插件工具执行
+### TboxPluginClient — 插件工具执行（B端鉴权）
 
 封装 `/openapi/v1/plugin` 下的全部接口。
 
@@ -180,7 +287,7 @@ const client = new KnowledgeClient({
 import { TboxPluginClient } from '@tbox-dev-js/sdk';
 
 const client = new TboxPluginClient({
-  apiKey: 'your-api-key',
+  apiKey: 'your-api-key',   // 从百宝箱平台开发网关后台获取
   baseUrl: 'https://o.tbox.cn',  // 可选，默认值
   timeout: 10000,                 // 可选，毫秒
 });
@@ -196,7 +303,7 @@ const client = new TboxPluginClient({
 
 ---
 
-### LlmClient — LLM 大模型对话
+### LlmClient — LLM 大模型对话（B端鉴权）
 
 提供 OpenAI 兼容的 Chat Completions 接口，支持流式和非流式输出。
 
@@ -251,7 +358,7 @@ console.log(response.choices?.[0]?.message?.content);
 
 ---
 
-### TboxConversationClient — 会话管理
+### TboxConversationClient — 会话管理（B端鉴权）
 
 封装 `/openapi/v1/conversation` 下的全部接口。
 
@@ -270,31 +377,7 @@ const client = new TboxConversationClient({ apiKey: 'your-api-key' });
 
 ---
 
-### TboxAppClient — 应用服务
-
-封装 `/openapi/v1/app` 下的接口。
-
-```ts
-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 (result.success) {
-  console.log('sessionId:', result.data?.sessionId);
-}
-```
-
----
-
-### AmapClient — 高德地图服务
+### AmapClient — 高德地图服务（B端鉴权）
 
 通过百宝箱插件服务调用高德地图 API，支持天气查询、地理编码、路线规划等。
 
@@ -351,17 +434,19 @@ console.log(schema?.operations);
 
 ## 统一响应格式
 
-旧架构客户端（`TboxPluginClient`、`TboxConversationClient`、`TboxAppClient`、`AmapClient`）的所有方法均返回 `SdkResponse<T>`：
+旧架构客户端（`TboxPluginClient`、`TboxConversationClient`、`TboxAppClient`、`TboxHomepageClient`、`AmapClient`）的所有方法均返回 `SdkResponse<T>`：
 
 ```ts
 interface SdkResponse<T> {
   success: boolean;
   data?: T;
-  errorCode?: string;
-  errorMsg?: string;
+  errorCode?: string;   // 业务错误码或 HTTP 状态码
+  errorMsg?: string;     // 错误描述（含服务端返回的中文信息）
 }
 ```
 
+> HTTP 非 200 响应也会尝试解析服务端返回的 JSON 错误体，提取真实的 `errorCode` 和 `errorMsg`，而非仅返回 `HTTP_403` 等笼统信息。
+
 新架构客户端（`TboxAPI`、`KnowledgeClient`）直接返回业务数据，错误通过异常抛出：
 
 ```ts
@@ -404,23 +489,27 @@ tbox-js/
 │   │   ├── types.ts                     #   类型定义
 │   │   └── schema.ts                    #   JSON Schema 定义
 │   ├── schema.ts                        # ResourceSchema 类型体系 + SchemaRegistry
-│   ├── plugin.ts                        # 插件工具执行客户端
-│   ├── conversation.ts                  # 会话管理客户端
-│   ├── app.ts                           # 应用服务客户端
-│   ├── amap.ts                          # 高德地图客户端
-│   ├── llm.ts                           # LLM 大模型对话客户端
-│   ├── http.ts                          # 旧架构 HTTP 封装
+│   ├── homepage.ts                      # 首页开场白客户端（C端鉴权）
+│   ├── plugin.ts                        # 插件工具执行客户端（B端鉴权）
+│   ├── conversation.ts                  # 会话管理客户端（B端鉴权）
+│   ├── app.ts                           # 应用服务客户端（B端鉴权 + C端桥接）
+│   ├── amap.ts                          # 高德地图客户端（B端鉴权）
+│   ├── llm.ts                           # LLM 大模型对话客户端（B端鉴权）
+│   ├── http.ts                          # 底层 HTTP 封装（支持 B端/C端双鉴权）
 │   ├── error.ts                         # 错误类层级
 │   ├── resource.ts                      # APIResource 基类
 │   ├── constant.ts                      # 常量定义
-│   ├── types.ts                         # 旧架构类型定义
+│   ├── types.ts                         # 类型定义（含鉴权类型）
 │   └── index.ts                         # 统一导出入口
 ├── config/
 │   └── knowledge.json                   # 知识库业务配置文件
+├── test/
+│   ├── homepage.test.mjs                # 首页开场白测试（含 C端鉴权流程）
+│   └── knowledge.test.mjs              # 知识库模块测试
 ├── docs/
 │   └── knowledge-client.md              # KnowledgeClient 设计文档
 ├── scripts/
-│   └── publish.sh                       # npm 发布脚本
+│   └── publish.sh                       # npm 发布脚本（自动切换 registry）
 ├── dist/                                # 构建产物
 │   ├── index.cjs                        #   CJS 格式
 │   ├── index.esm.js                     #   ESM 格式
@@ -448,6 +537,31 @@ npm run build
 npm run clean
 ```
 
+## 测试
+
+```bash
+# 首页开场白测试（含 C端鉴权完整流程）
+node test/homepage.test.mjs <apiKey> <appId>
+
+# 知识库模块测试
+node test/knowledge.test.mjs <apiKey> [datasetId]
+```
+
+## 发布
+
+```bash
+# 预览发布内容（Dry-run）
+./scripts/publish.sh
+
+# 正式发布（自动切换到官方 npm 源，发布后恢复）
+./scripts/publish.sh --release
+
+# 自动 bump 版本号并发布
+./scripts/publish.sh --patch   # 0.1.0 → 0.1.1
+./scripts/publish.sh --minor   # 0.1.0 → 0.2.0
+./scripts/publish.sh --major   # 0.1.0 → 1.0.0
+```
+
 ## 许可证
 
 MIT

package/dist/homepage.d.ts

@@ -0,0 +1,79 @@
+/**
+ * 百宝箱首页开场白 SDK - HomepageClient 核心类
+ *
+ * 封装 /agent/v1/homepage 下的接口。
+ * 该接口走 C端鉴权（TBOXSESSIONID + X-Tbox-Channel + X-Tbox-AppId）。
+ */
+import type { TboxSessionClientConfig, CreateSessionClientOptions, SdkResponse, HomepageGetRequest, HomepageGetResponse } from './types';
+/**
+ * 百宝箱首页开场白客户端（C端鉴权）
+ *
+ * @example
+ * ```ts
+ * import { TboxHomepageClient } from '@tbox-dev-js/sdk';
+ *
+ * // 方式一：自动获取 session（推荐）
+ * const client = await TboxHomepageClient.create({
+ *   apiKey: 'your-api-key',
+ *   appId: '202508APhciU03604644',
+ *   userId: 'user-123',
+ * });
+ *
+ * // 方式二：手动传入 session
+ * const client = new TboxHomepageClient({
+ *   session: { sessionId: 'xxx', channel: 'alipay_mini_app', appId: '202508APhciU03604644' },
+ * });
+ *
+ * const result = await client.get({ agentId: '202508APhciU03604644' });
+ * if (result.success) {
+ *   console.log('开场白:', result.data?.prologue);
+ * }
+ * ```
+ */
+export declare class TboxHomepageClient {
+    private readonly http;
+    /**
+     * 使用 C端 Session 鉴权构造
+     */
+    constructor(config: TboxSessionClientConfig);
+    /**
+     * 便捷工厂方法：通过 B端 apiKey 自动获取 session 并创建 C端客户端
+     *
+     * 内部流程：
+     * 1. 使用 apiKey 调用 TboxAppClient.generateSession() 获取 sessionId + channel
+     * 2. 用获取到的 session 信息创建 C端鉴权的 HomepageClient
+     *
+     * @param options - 创建参数（apiKey、appId、userId）
+     * @returns 已鉴权的 TboxHomepageClient 实例
+     *
+     * @example
+     * ```ts
+     * const client = await TboxHomepageClient.create({
+     *   apiKey: 'your-api-key',
+     *   appId: '202508APhciU03604644',
+     *   userId: 'user-123',
+     * });
+     * ```
+     */
+    static create(options: CreateSessionClientOptions): Promise<TboxHomepageClient>;
+    /**
+     * 获取首页开场白
+     *
+     * POST /agent/v1/homepage/get
+     *
+     * @param request - 请求参数，agentId 为必填
+     * @returns 开场白信息，包含开场白文本、推荐问题等
+     *
+     * @example
+     * ```ts
+     * const res = await client.get({
+     *   agentId: '202508APhciU03604644',
+     *   extInfo: '{}',
+     * });
+     * if (res.success) {
+     *   console.log(res.data?.prologue);
+     * }
+     * ```
+     */
+    get(request: HomepageGetRequest): Promise<SdkResponse<HomepageGetResponse>>;
+}

package/dist/http.d.ts

@@ -1,23 +1,55 @@
 /**
  * 百宝箱插件服务 SDK - 底层 HTTP 请求封装
+ *
+ * 支持两种鉴权模式：
+ * - B端：Authorization header（API Key）
+ * - C端：TBOXSESSIONID + X-Tbox-Channel + X-Tbox-AppId headers
  */
-import type { SdkResponse } from './types';
+import type { SdkResponse, SessionAuth } from './types';
 /** 默认调用域名 */
 export declare const DEFAULT_BASE_URL = "https://o.tbox.cn";
+/**
+ * 鉴权模式
+ */
+export type AuthMode = {
+    type: 'apiKey';
+    apiKey: string;
+} | {
+    type: 'session';
+    session: SessionAuth;
+};
 /** 内部 HTTP 客户端配置 */
 export interface HttpClientConfig {
+    baseUrl: string;
+    auth: AuthMode;
+    timeout?: number;
+}
+/**
+ * 旧版配置（向后兼容）
+ */
+export interface LegacyHttpClientConfig {
     baseUrl: string;
     apiKey: string;
     timeout?: number;
 }
 /**
  * 底层 HTTP 客户端
+ *
+ * 支持两种构造方式：
+ * - 新版：传入 HttpClientConfig（含 AuthMode）
+ * - 旧版：传入 LegacyHttpClientConfig（含 apiKey，向后兼容）
  */
 export declare class HttpClient {
-    private readonly baseUrl;
-    private readonly apiKey;
+    private readonly _baseUrl;
+    private readonly auth;
     private readonly timeout?;
-    constructor(config: HttpClientConfig);
+    constructor(config: HttpClientConfig | LegacyHttpClientConfig);
+    /** 获取 base URL */
+    get baseUrl(): string;
+    /** 获取鉴权请求头（供外部流式请求等场景使用） */
+    getAuthHeaders(): Record<string, string>;
+    /** 构建鉴权相关的请求头 */
+    private buildAuthHeaders;
     /** 构建通用请求头 */
     private buildHeaders;
     /** 构建 FormData 请求头（不设置 Content-Type，让浏览器自动处理 boundary） */