qing-client 1.0.5 → 1.0.7

package/README.md

@@ -83,39 +83,40 @@ await client.setToken('xxx');
 
 ---
 
-## 可用服务（15 个）
+## 可用服务（16 个）
 
 ### 核心服务
 
-| 服务 | 说明 | 注册名 | API 路径 |
+| 服务 | 说明 | 注册名 | API 文档 |
 |------|------|--------|----------|
-| AuthService | 认证与登录 | `auth` | `/api/auth` |
-| MsgService | 消息中心 | `msg` | `/api/msg` |
-| UserService | 用户管理 | `user` | `/api/users` |
-| TokenService | Token 管理（微信等） | `token` | `/api/token` |
-| FileService | 文件服务 | `file` | `/api/files` |
+| AuthService | 认证与登录 | `auth` | [auth.md](./docs/api/auth.md) |
+| MsgService | 消息中心 / 邮件 / 飞书 | `msg` | [msg.md](./docs/api/msg.md) |
+| UserService | 用户管理 | `user` | [user.md](./docs/api/user.md) |
+| TokenService | 微信 Token 管理 | `token` | [token.md](./docs/api/token.md) |
+| FileService | 文件与文件夹管理 | `file` | [file.md](./docs/api/file.md) |
 
 ### AI 相关
 
-| 服务 | 说明 | 注册名 | API 路径 |
+| 服务 | 说明 | 注册名 | API 文档 |
 |------|------|--------|----------|
-| AiService | AI 对话/会话/助手 | `ai` | `/api/ai` |
-| AigcService | AIGC 能力 | `aigc` | `/api/aigc` |
-| ProviderService | 大模型供应商管理 | `provider` | `/api/providers` |
-| UsageService | 用量统计 | `usage` | `/api/providers` |
+| AiService | AI 对话 / 助手 / 会话 | `ai` | [ai.md](./docs/api/ai.md) |
+| AigcService | AIGC 生成与图像处理 | `aigc` | [aigc.md](./docs/api/aigc.md) |
+| ProviderService | 大模型供应商管理 | `provider` | [provider.md](./docs/api/provider.md) |
+| UsageService | Token 用量统计 | `usage` | [usage.md](./docs/api/usage.md) |
 
 ### 业务服务
 
-| 服务 | 说明 | 注册名 | API 路径 |
+| 服务 | 说明 | 注册名 | API 文档 |
 |------|------|--------|----------|
-| AuditLogService | 审计日志 | `audit` | `/api/logs` |
-| FrontHostService | 静态 HTML 托管 | `fronthost` | `/api/gateway-h5` |
-| OrgService | 组织与多租户 | `org` | `/api/org` |
-| DeliveryStreamService | 投递流 | `deliveryStream` | `/api/delivery-stream` |
-| EzAbilityService | Ez AI 能力 | `ezAbility` | `/api/ez-ability` |
-| ImService | IM 群组 | `im` | `/api/im` |
+| AuditLogService | 审计日志 | `audit` | [audit.md](./docs/api/audit.md) |
+| FrontHostService | 前端 HTML 托管 | `fronthost` | [fronthost.md](./docs/api/fronthost.md) |
+| OrgService | 组织 / 项目 / 应用管理 | `org` | [org.md](./docs/api/org.md) |
+| DeliveryStreamService | 投递流 / 版本 / 需求 | `deliveryStream` | [delivery-stream.md](./docs/api/delivery-stream.md) |
+| EzAbilityService | AI 需求枚举与 PRD 生成 | `ezAbility` | [ez-ability.md](./docs/api/ez-ability.md) |
+| ImService | IM 群组与消息 | `im` | [im.md](./docs/api/im.md) |
+| HubService | 能力枢纽（大盘统计 / Worker / Task） | `hub` | [hub.md](./docs/api/hub.md) |
 
-> **注册名** 即 `client.services.<注册名>` 中的 key，也是 `ServicePlugin.serviceName` 的值。
+> **注册名** 即 `client.services.<注册名>` 中的 key。完整 API 参考见 [docs/api/](./docs/api/README.md)。
 
 ---
 
@@ -257,7 +258,7 @@ src/
 │   ├── config.ts            # 配置类型（ClientConfig）
 │   ├── service-contract.ts  # 服务契约（ServicePlugin / TokenAware 等）
 │   └── index.ts
-├── services/                # 服务目录（15 个服务）
+├── services/                # 服务目录（16 个服务）
 │   ├── auth/                # 认证服务
 │   ├── msg/                 # 消息服务
 │   ├── user/                # 用户服务
@@ -273,6 +274,7 @@ src/
 │   ├── delivery-stream/     # 投递流服务
 │   ├── ez-ability/          # Ez 能力服务
 │   ├── im/                  # IM 服务
+│   ├── hub/                 # 能力枢纽服务
 │   └── index.ts
 ├── docs/
 │   └── SDK-GENERATION.md    # 服务生成指南

package/docs/SDK-GENERATION.md

@@ -0,0 +1,327 @@
+# SDK 服务生成指南
+
+本文档描述如何为新的后端服务生成对应的 SDK 代码。
+
+---
+
+## 目录结构约定
+
+```
+src/
+├── core/                    # 核心框架（不要修改）
+│   ├── Client.ts            # 主客户端
+│   ├── BaseClient.ts        # 服务基类
+│   └── index.ts
+├── types/                   # 公共类型（不要修改）
+│   ├── common.ts
+│   ├── config.ts
+│   ├── service-contract.ts
+│   └── index.ts
+├── services/                # 服务目录
+│   ├── auth/                # 示例服务
+│   │   ├── AuthService.ts   # 服务实现
+│   │   ├── types.ts         # 类型定义
+│   │   └── index.ts         # 导出
+│   ├── msg/
+│   │   └── ...
+│   └── {新服务名}/          # 新服务放这里
+│       └── ...
+├── docs/
+│   └── SDK-GENERATION.md    # 本文档
+└── index.ts                 # 包入口
+```
+
+---
+
+## 生成步骤
+
+### 第一步：创建服务目录
+
+在 `src/services/` 下创建以服务名命名的目录（如 `im/`）。
+
+```
+src/services/im/
+├── ImService.ts
+├── types.ts
+└── index.ts
+```
+
+---
+
+### 第二步：生成类型定义 (`types.ts`)
+
+根据后端 API 接口定义，生成对应的 TypeScript 类型。
+
+```typescript
+// src/services/im/types.ts
+
+export interface Group {
+  id: string;
+  name: string;
+  ownerId: string;
+  memberCount: number;
+  createdAt: string;
+}
+
+export interface CreateGroupRequest {
+  name: string;
+  memberIds: string[];
+  requireAdmin?: boolean;
+}
+
+export interface GroupQueryParams {
+  page?: number;
+  limit?: number;
+}
+
+// ... 其他类型
+```
+
+---
+
+### 第三步：生成服务实现 (`ImService.ts`)
+
+**必须遵循以下模板**：
+
+```typescript
+// src/services/im/ImService.ts
+
+import { BaseClient } from '../../core/BaseClient';
+import { ClientConfig, TokenStorage, RequestOptions } from '../../types';
+import { Group, CreateGroupRequest, GroupQueryParams } from './types';
+
+/**
+ * IM 群组服务
+ *
+ * @example
+ * ```typescript
+ * const groups = await client.services.im.getGroups();
+ * ```
+ */
+export class ImService extends BaseClient {
+  // ========== 必须的静态属性 ==========
+  /** 服务名称（用于注册到 client.services 的 key） */
+  static readonly serviceName = 'im';
+
+  /** API 路径（对应 /api/im） */
+  static readonly servicePath = 'im';
+
+  // ========== 必须的实例属性 ==========
+  get serviceName(): string {
+    return 'im';
+  }
+
+  // ========== 构造函数 ==========
+  constructor(config: ClientConfig, tokenStorage: TokenStorage) {
+    super(config, 'im', tokenStorage);
+  }
+
+  // ========== 业务方法 ==========
+
+  async getGroups(params?: GroupQueryParams, options?: RequestOptions): Promise<Group[]> {
+    return this.request<Group[]>('/groups', {
+      ...options,
+      method: 'GET',
+      params,
+    });
+  }
+
+  async createGroup(request: CreateGroupRequest, options?: RequestOptions): Promise<Group> {
+    return this.request<Group>('/groups', {
+      ...options,
+      method: 'POST',
+      body: request,
+    });
+  }
+
+  // ... 其他方法
+}
+
+// ========== 必须的类型扩展 ==========
+/**
+ * 扩展 Client.Services 接口
+ * 使 client.services.im 具有完整类型推导
+ */
+declare module '../../core/Client' {
+  interface Services {
+    im: ImService;
+  }
+}
+```
+
+---
+
+### 第四步：创建导出文件 (`index.ts`)
+
+```typescript
+// src/services/im/index.ts
+
+export { ImService } from './ImService';
+export * from './types';
+```
+
+---
+
+### 第五步：在包入口添加导出
+
+在 `src/index.ts` 中添加服务类和类型的导出：
+
+```typescript
+// src/index.ts
+
+// ... 已有代码 ...
+
+// ========== 服务 ==========
+export { ImService } from './services/im/ImService';  // 新增
+
+// ========== 服务类型 ==========
+export type {
+  Group,
+  CreateGroupRequest,
+  GroupQueryParams,
+} from './services/im/types';  // 新增
+```
+
+---
+
+### 第六步（如需后端直连）：在 ClientConfig 中添加服务 URL
+
+如果需要后端模式直连该服务，需在 `src/types/config.ts` 的 `ClientConfig` 接口中添加对应的 URL 字段：
+
+```typescript
+export interface ClientConfig {
+  // ...
+  /** IM 服务地址 */
+  imServiceUrl?: string;
+  // ...
+}
+```
+
+---
+
+## 服务类必须实现的接口
+
+```typescript
+class YourService extends BaseClient {
+  static readonly serviceName = 'yourService';     // 必填：注册到 client.services 的 key
+  static readonly servicePath = 'your-service';    // 必填：API 路径前缀
+
+  get serviceName(): string { return 'yourService'; } // 必填：实例属性
+
+  constructor(config: ClientConfig, tokenStorage: TokenStorage) {
+    super(config, 'your-service', tokenStorage);   // servicePath 传给 BaseClient
+  }
+
+  // 业务方法...
+}
+
+// 类型扩展（必填）
+declare module '../../core/Client' {
+  interface Services {
+    yourService: YourService;
+  }
+}
+```
+
+> **注意**：`serviceName`（camelCase）用于注册和访问 `client.services.xxx`；`servicePath`（kebab-case）用于拼接 API URL `/api/xxx`。两者可能不同。
+
+---
+
+## 请求方法说明
+
+BaseClient 提供了两个请求方法：
+
+### `request<T>(path, options)`
+
+用于普通请求。
+
+```typescript
+// GET 请求
+return this.request<User>('/user/123', {
+  method: 'GET',
+});
+
+// POST 请求
+return this.request<User>('/user', {
+  method: 'POST',
+  body: userData,
+});
+
+// 带查询参数
+return this.request<User[]>('/users', {
+  method: 'GET',
+  params: { page: 1, limit: 10 },
+});
+```
+
+### `paginatedRequest<T>(path, options)`
+
+用于分页请求，返回带 pagination 的响应。
+
+```typescript
+return this.paginatedRequest<User>('/users', {
+  method: 'GET',
+  params: { page: 1, limit: 10 },
+});
+// 返回: { success, data: User[], pagination: { page, perPage, total, totalPages } }
+```
+
+---
+
+## 使用方注册示例
+
+```typescript
+import { Client, AuthService, MsgService, ImService } from 'qing-client';
+
+const client = new Client({
+  gatewayUrl: 'https://api.example.com',
+  projectId: 'xxx',
+})
+  .use(AuthService)
+  .use(MsgService)
+  .use(ImService);
+
+await client.setToken('xxx');
+
+// 完整类型推导
+client.services.im.getGroups();
+```
+
+---
+
+## 检查清单
+
+生成新服务后，请检查：
+
+- [ ] 服务目录已创建在 `src/services/{name}/`
+- [ ] `types.ts` 包含所有请求/响应类型
+- [ ] 服务类继承 `BaseClient`
+- [ ] 静态属性 `serviceName` 和 `servicePath` 已定义
+- [ ] 实例属性 `get serviceName()` 已实现（返回值与静态 `serviceName` 一致）
+- [ ] 构造函数签名为 `(config: ClientConfig, tokenStorage: TokenStorage)`
+- [ ] `declare module` 类型扩展已添加（key 与 `serviceName` 一致）
+- [ ] `index.ts` 导出文件已创建
+- [ ] `src/index.ts` 已添加服务类和类型的导出
+- [ ] （可选）`src/types/config.ts` 已添加后端模式服务 URL 字段
+
+---
+
+## AI 提示词模板
+
+如果使用 AI 生成 SDK，可以使用以下提示词：
+
+```
+请根据以下后端 API 接口定义，生成 qing-client SDK 的服务代码。
+
+接口定义：
+[粘贴 API 文档或接口描述]
+
+要求：
+1. 遵循 SDK-GENERATION.md 中的目录结构和代码模板
+2. 服务名为 {service-name}
+3. 生成 types.ts（类型定义）和 {ServiceName}.ts（服务实现）
+4. 必须包含静态属性 serviceName 和 servicePath
+5. 必须在文件末尾添加 declare module 类型扩展
+6. 所有方法使用 this.request<T>() 进行请求
+7. 添加完整的 JSDoc 注释
+```

package/docs/api/README.md

@@ -0,0 +1,82 @@
+# API 参考文档
+
+qing-client SDK 所有服务的 API 文档索引。
+
+每个文档包含：方法列表、参数类型、返回值类型、使用示例。
+
+---
+
+## 核心服务
+
+| 服务 | 说明 | 方法数 | 文档 |
+|------|------|--------|------|
+| AuthService | 认证与登录 | 9 | [auth.md](./auth.md) |
+| MsgService | 消息中心 / 邮件 / 飞书 | 12 | [msg.md](./msg.md) |
+| UserService | 用户管理 | 10 | [user.md](./user.md) |
+| TokenService | 微信 Token 管理 | 5 | [token.md](./token.md) |
+| FileService | 文件与文件夹管理 | 22 | [file.md](./file.md) |
+
+## AI 相关
+
+| 服务 | 说明 | 方法数 | 文档 |
+|------|------|--------|------|
+| AiService | AI 对话 / 助手 / 会话 | 30 | [ai.md](./ai.md) |
+| AigcService | AIGC 生成与图像处理 | 14 | [aigc.md](./aigc.md) |
+| ProviderService | 大模型供应商管理 | 16 | [provider.md](./provider.md) |
+| UsageService | Token 用量统计 | 6 | [usage.md](./usage.md) |
+
+## 业务服务
+
+| 服务 | 说明 | 方法数 | 文档 |
+|------|------|--------|------|
+| AuditLogService | 审计日志 | 2 | [audit.md](./audit.md) |
+| FrontHostService | 前端 HTML 托管 | 9 | [fronthost.md](./fronthost.md) |
+| OrgService | 组织 / 项目 / 应用管理 | 27 | [org.md](./org.md) |
+| DeliveryStreamService | 投递流 / 版本 / 需求 | 17 | [delivery-stream.md](./delivery-stream.md) |
+| EzAbilityService | AI 需求枚举与 PRD 生成 | 14 | [ez-ability.md](./ez-ability.md) |
+| ImService | IM 群组与消息 | 3 | [im.md](./im.md) |
+| HubService | 能力枢纽（大盘统计 / Worker / Task） | 6 | [hub.md](./hub.md) |
+
+---
+
+## 通用约定
+
+### RequestOptions
+
+所有方法的最后一个参数都支持 `RequestOptions`，用于覆盖本次请求的上下文：
+
+```typescript
+interface RequestOptions {
+  method?: 'GET' | 'POST' | 'PUT' | 'DELETE' | 'PATCH';
+  headers?: Record<string, string>;
+  params?: Record<string, any>;
+  body?: any;
+  projectId?: string;   // 覆盖本次请求的项目 ID
+  orgId?: string;       // 覆盖本次请求的组织 ID
+  appId?: string;       // 覆盖本次请求的应用 ID
+  userContext?: UserContext; // 覆盖本次请求的用户上下文（后端模式）
+}
+```
+
+### 响应格式
+
+SDK 会自动解包 `{ success, data, message }` 格式的响应，方法返回值直接是 `data` 部分。
+
+分页请求返回 `PaginatedResponse<T>`：
+
+```typescript
+interface PaginatedResponse<T> {
+  success: boolean;
+  data: T[];
+  pagination: {
+    page: number;
+    perPage: number;
+    total: number;
+    totalPages: number;
+  };
+}
+```
+
+### 错误处理
+
+请求失败时抛出 `Error`，错误消息格式为 `[服务名服务] 错误信息 (路径: /xxx)`。可通过 `ClientConfig.onHttpError` 回调统一处理。

package/docs/api/ai.md

@@ -0,0 +1,163 @@
+# AiService API
+
+AI 对话服务，提供会话管理、助手管理、对话补全、供应商和模型查询等能力。
+
+- **注册名**: `ai`
+- **API 路径**: `/api/ai`
+- **访问方式**: `client.services.ai`
+
+---
+
+## 方法列表
+
+### Chat 对话
+
+| 方法 | 说明 | HTTP |
+|------|------|------|
+| `chatCompletion()` | 对话补全 | `POST /chat` |
+| `chatCompletionStream()` | 对话补全（流式） | `POST /chat/stream` |
+
+### Session 会话管理
+
+| 方法 | 说明 | HTTP |
+|------|------|------|
+| `createSession()` | 创建会话 | `POST /session` |
+| `getSessions()` | 获取会话列表 | `GET /session` |
+| `getSession()` | 获取会话详情 | `GET /session/:id` |
+| `updateSession()` | 更新会话 | `PUT /session/:id` |
+| `endSession()` | 结束会话 | `POST /session/:id/end` |
+| `deleteSession()` | 删除会话 | `DELETE /session/:id` |
+| `getActiveSessions()` | 获取活跃会话 | `GET /session/active` |
+| `getSessionModelInfo()` | 获取会话模型信息 | `GET /session/:id/model` |
+| `switchSessionModel()` | 切换会话模型 | `POST /session/:id/switch-model` |
+| `getSessionStatistics()` | 获取会话统计 | `GET /session/statistics` |
+| `getSessionMessages()` | 获取会话消息（分页） | `GET /session/:id/messages` |
+| `addMessageToSession()` | 添加消息到会话 | `POST /session/:id/message` |
+| `deleteSessionsBatch()` | 批量删除会话 | `DELETE /session/batch` |
+
+### Assistant 助手管理
+
+| 方法 | 说明 | HTTP |
+|------|------|------|
+| `createAssistant()` | 创建助手 | `POST /assistant` |
+| `getAssistants()` | 获取助手列表 | `GET /assistant` |
+| `getAssistant()` | 获取助手详情 | `GET /assistant/:id` |
+| `updateAssistant()` | 更新助手 | `PUT /assistant/:id` |
+| `deleteAssistant()` | 删除助手 | `DELETE /assistant/:id` |
+| `getAccessibleAssistants()` | 获取可用助手 | `GET /assistant/accessible` |
+| `getPopularAssistants()` | 获取热门助手 | `GET /assistant/popular` |
+| `incrementAssistantUsage()` | 增加助手使用次数 | `POST /assistant/:id/usage` |
+| `duplicateAssistant()` | 复制助手 | `POST /assistant/:id/duplicate` |
+| `getAssistantModels()` | 获取助手可用模型 | `GET /assistant/:id/models` |
+
+### Provider / Model 查询
+
+| 方法 | 说明 | HTTP |
+|------|------|------|
+| `getProviders()` | 获取供应商列表 | `GET /provider` |
+| `getProvider()` | 获取供应商详情 | `GET /provider/:key` |
+| `getAccessibleProviders()` | 获取当前用户可用供应商 | `GET /provider/accessible/me` |
+| `getModels()` | 获取模型列表 | `GET /model` |
+| `getModel()` | 获取模型详情 | `GET /model/:id` |
+| `getModelsByProvider()` | 按供应商获取模型 | `GET /model/by-provider/:key` |
+| `getAccessibleModels()` | 获取当前用户可用模型 | `GET /model/accessible/me` |
+
+---
+
+## 核心方法详情
+
+### createSession(request, options?)
+
+创建一个新的对话会话。
+
+```typescript
+const { session, assistant, availableModels } = await client.services.ai.createSession({
+  assistantId: 'assistant-123',
+  currentModel: 'gpt-4',
+});
+```
+
+**参数** `CreateSessionRequest`
+
+| 字段 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| assistantId | `string` | 是 | 助手 ID |
+| currentModel | `string` | 否 | 使用的模型 |
+| initialMessages | `SessionMessage[]` | 否 | 初始消息 |
+
+**返回** `Promise<SessionDetailResponse>`
+
+```typescript
+interface SessionDetailResponse {
+  session: SessionResponse;
+  assistant: AssistantResponse;
+  availableModels: string[];
+}
+```
+
+---
+
+### chatCompletion(request, options?)
+
+发送对话补全请求。
+
+```typescript
+const res = await client.services.ai.chatCompletion({
+  sessionId: 'session-123',
+  message: '你好，请帮我分析数据',
+  model: 'gpt-4',
+});
+```
+
+**参数** `ChatCompletionRequest`: `{ sessionId: string; message: string; model?: string }`
+
+**返回** `Promise<ChatCompletionResponse>`
+
+---
+
+### createAssistant(request, options?)
+
+创建 AI 助手。
+
+```typescript
+const assistant = await client.services.ai.createAssistant({
+  name: '代码助手',
+  providerName: 'openai',
+  defaultModel: 'gpt-4',
+  roleDefinition: '你是一个专业的代码审查助手',
+  config: { temperature: 0.7, maxTokens: 2000 },
+});
+```
+
+**参数** `CreateAssistantRequest`
+
+| 字段 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| name | `string` | 是 | 助手名称 |
+| providerName | `string` | 是 | 供应商名称 |
+| defaultModel | `string` | 是 | 默认模型 |
+| roleDefinition | `string` | 是 | 角色定义（System Prompt） |
+| description | `string` | 否 | 描述 |
+| avatarUrl | `string` | 否 | 头像 URL |
+| availableModels | `string[]` | 否 | 可用模型列表 |
+| initMessages | `Array<{ role, content }>` | 否 | 初始消息 |
+| strictRules | `string[]` | 否 | 严格规则 |
+| config | `ModelConfig` | 否 | 模型配置 |
+| isGlobal | `boolean` | 否 | 是否全局可见 |
+
+**返回** `Promise<AssistantResponse>`
+
+---
+
+### getSessionStatistics(timeRange?, options?)
+
+获取会话统计数据。
+
+```typescript
+const stats = await client.services.ai.getSessionStatistics('week');
+// stats: { totalSessions, activeSessions, messagesCount, averageSessionLength }
+```
+
+**参数** `timeRange`: `'today' | 'week' | 'month' | 'year'`
+
+**返回** `Promise<SessionStatistics>`