qing-client 0.0.50 → 0.0.52

package/README.MD

@@ -2,10 +2,15 @@
 
 `qing-client` 是一个统一的 JavaScript / TypeScript SDK，用于访问 Qing 平台提供的各类服务能力，包括：
 
-* 用户与认证
-* 消息中心
-* AI / AIGC 能力
-* 静态 HTML 托管（gateway-h5）
+* **用户与认证**（auth、user、token）
+* **消息中心**（msg）
+* **AI / AIGC 能力**（ai、aigc）
+* **文件服务**（file，可独立使用 `FileService`）
+* **审计日志**（audit）
+* **提供商与用量**（provider、usage）
+* **组织与多租户**（org）
+* **投递流与 Ez 能力**（deliveryStream、ezAbility）
+* **静态 HTML 托管**（gateway-h5，frontHost）
 
 该 SDK 为 **公开 npm 包**，任何 **拥有合法账号的第三方开发者** 均可使用。
 
@@ -15,13 +20,37 @@
 
 * 前后端统一 SDK
 * 支持 浏览器 / H5 / 移动端 / Node.js
-* 自动处理认证与请求头
-* 支持多服务调用
+* 自动处理认证与请求头（含项目 / 组织 / 应用多租户头）
+* 支持多服务调用（统一 `Client` 或按需使用独立 Service）
 * 完整 TypeScript 类型定义
 * 支持静态前端托管管理（上传 zip）
 
 ---
 
+## 如何查看每个函数的入参与返回值
+
+本 SDK 是**黑盒**使用时，可通过以下方式获知“怎么调、要传什么、会返回什么”：
+
+1. **TypeScript / IDE 类型提示**  
+   安装后，在支持 TypeScript 或 JSDoc 的项目中，编辑器会对所有方法做**参数和返回值**的自动补全与说明。每个方法的入参、返回类型都有定义。
+
+2. **类型均从包内导出**  
+   所有请求体/响应体的类型都可从 `qing-client` 直接导入，便于在业务代码里写类型、查看字段：
+   ```ts
+   import type {
+     LoginCredentials, LoginResponse, RegisterRequest,
+     User, UserCreateRequest, Message, MessageQueryParams, CreateMessageRequest,
+     ChatCompletionRequest, ChatCompletionResponse, CreateSessionRequest, SessionDetailResponse,
+     FrontHostCreateProjectInput, FrontHostProject
+   } from "qing-client";
+   ```
+   在 IDE 中跳转到这些类型即可看到**完整字段说明**。
+
+3. **下文「API 参考」**  
+   对最常用方法做了简要说明：方法名、入参、返回值及主要字段，便于快速查阅。
+
+---
+
 ## 安装
 
 ```bash
@@ -74,6 +103,7 @@ const client = new Client({
   gatewayUrl: "https://api.example.com",
   projectId: "your-project-id",
   appId: "your-app-id",
+  orgId: "your-org-id", // 可选，组织维度
 });
 ```
 
@@ -88,6 +118,9 @@ SDK 会自动为所有请求附加：
 * `Authorization: Bearer <token>`
 * `x-project-id`
 * `x-app-id`
+* `x-org-id`（若配置了 `orgId`）
+
+前端模式下还可使用：`client.setProjectAndApp(projectId, appId)`、`client.setOrgId(orgId)`、`client.setProjectOrgApp(projectId, orgId, appId)`。
 
 ---
 
@@ -98,23 +131,149 @@ import { Client } from "qing-client";
 
 const client = new Client({
   authServiceUrl: "http://auth-service",
+  msgServiceUrl: "http://msg-service",
   userServiceUrl: "http://user-service",
+  fileServiceUrl: "http://file-service",
+  tokenServiceUrl: "http://token-service",
+  aigcServiceUrl: "http://aigc-service",
+  auditLogServiceUrl: "http://audit-log-service",
+  providerServiceUrl: "http://provider-service",
+  orgServiceUrl: "http://org-service",
   gatewayH5ServiceUrl: "http://gateway-h5-service",
+  deliveryStreamServiceUrl: "http://delivery-stream-service",
+  ezAbilityServiceUrl: "http://ez-ability-service",
 });
 ```
 
+按需配置实际用到的服务地址即可，未用到的可省略。
+
 ### 设置用户上下文（仅后端模式）
 
 ```ts
 client.setUserContext({
   userId: "123",
-  role: "ADMIN",
+  role: "ADMIN", // SUPER_ADMIN | ADMIN | STAFF | USER | SYSTEM
   projectId: "project-1",
+  orgId: "org-1",   // 可选
+  appId: "app-1",   // 可选
 });
 ```
 
 ---
 
+## Client 上的服务
+
+通过 `Client` 实例可访问以下服务（均为同一配置与 Token）：
+
+| 属性 | 说明 |
+|------|------|
+| `client.auth` | 认证与登录 |
+| `client.user` | 用户信息 |
+| `client.token` | Token 管理 |
+| `client.msg` | 消息中心 |
+| `client.ai` | AI 对话/会话（chatCompletion、会话与助手等） |
+| `client.aigc` | AIGC 能力 |
+| `client.audit` | 审计日志 |
+| `client.provider` | 提供商与模型 |
+| `client.usage` | 用量统计 |
+| `client.org` | 组织与多租户 |
+| `client.frontHost` | 静态 HTML 托管（gateway-h5） |
+| `client.deliveryStream` | 投递流 |
+| `client.ezAbility` | Ez 能力 |
+
+文件服务需单独使用：`import { FileService } from "qing-client"`，并传入与前端/后端一致的配置。
+
+---
+
+## API 参考（主要方法）
+
+以下列出各服务**常用方法**的入参与返回值，便于在不看源码的情况下正确调用。未列出的方法可在安装后通过 IDE 查看方法签名，或查看包内类型定义（如 `lib/types/*.d.ts`）。
+
+**说明**：所有方法最后一个参数均为可选的 `options?: RequestOptions`（可传 `projectId` / `orgId` / `appId` 等覆盖本次请求的上下文），下文省略不写。
+
+### client.auth（认证）
+
+| 方法 | 入参 | 返回值 | 说明 |
+|------|------|--------|------|
+| `login(identifier, password, projectId?, options?)` | `identifier`: string（用户名/邮箱）<br>`password`: string<br>`projectId?`: number，默认 0 | `Promise<LoginResponse>` | 表单登录（旧版）。`LoginResponse` 含 `access_token`、`token_type`、`expires_at`、`project_id`、`org_id?`、`app_id?`。 |
+| `loginJson(credentials, projectId?, options?)` | `credentials`: `LoginCredentials`（`username`, `password`, `org_id?`, `app_id?`）<br>`projectId?`: number | `Promise<LoginResponse>` | 推荐：JSON 登录，支持组织/应用。 |
+| `wechatMiniProgramLogin(credentials, projectId?, options?)` | `credentials`: `WechatLoginCredentials`（`code`, `phone_code?`, `org_id?`, `app_id?`） | `Promise<LoginResponse>` | 微信小程序登录。 |
+| `register(data, projectId?, options?)` | `data`: `RegisterRequest`（`username`, `email`, `password`, `name?`, `phone?`, `org_id?`, `app_id?`） | `Promise<RegisterResponse>` | 注册，返回同登录结构。 |
+| `createTemporaryToken(request?, options?)` | `request?`: `TemporaryTokenRequest`（`expires_in?`，秒，60–3600） | `Promise<TemporaryTokenResponse>`：`temporary_token`, `expires_at`, `expires_in` | 签发临时令牌。 |
+| `verifyTemporaryToken(request, options?)` | `request`: `VerifyTemporaryTokenRequest` | `Promise<VerifyTemporaryTokenResponse>` | 验证临时令牌。 |
+| `logout(token, options?)` | `token`: string | `Promise<void>` | 登出。 |
+
+### client.user（用户）
+
+| 方法 | 入参 | 返回值 | 说明 |
+|------|------|--------|------|
+| `getCurrentUser(options?)` | — | `Promise<User>` | 当前用户。`User` 含 `id`, `username`, `email`, `name`, `avatar`, `phone`, `role`, `project_id`, `is_active`, `organizations?` 等。 |
+| `getUserById(userId, options?)` | `userId`: number | `Promise<User>` | 按 ID 查用户（管理员）。 |
+| `createUser(userData, options?)` | `userData`: `UserCreateRequest`（`username`, `email`, `password`, `name?`, `role?`, `phone?`, `project_id?`） | `Promise<User>` | 创建用户（管理员）。 |
+| `updateUser(userId, updateData, options?)` | `userId`: number<br>`updateData`: `UserUpdateRequest`（`name?`, `avatar?`, `phone?`, `role?`, `project_id?`） | `Promise<User>` | 更新用户（管理员）。 |
+| `listUsers(includeInactive?, page?, perPage?, projectId?, options?)` | `includeInactive?`: boolean<br>`page?`: number<br>`perPage?`: number<br>`projectId?`: number | `Promise<PaginatedResponse<User>>`（`data`, `pagination`） | 用户列表，支持分页与项目过滤。 |
+| `updateCurrentUser(updateData, options?)` | `updateData`: `SelfUserUpdateRequest`（`name?`, `avatar?`, `phone?`） | `Promise<User>` | 更新当前用户资料。 |
+| `changeOwnPassword(passwordData, options?)` | `passwordData`: `SelfPasswordChangeRequest`（`old_password`, `new_password`） | `Promise<{ id: number }>` | 修改当前用户密码。 |
+
+### client.msg（消息）
+
+| 方法 | 入参 | 返回值 | 说明 |
+|------|------|--------|------|
+| `getMessages(params?, options?)` | `params?`: `MessageQueryParams`（`type?`, `category?`, `isRead?`, `page?`, `limit?`, `userId?`, `pid?`, `aid?`） | `Promise<Message[]>` | 当前用户消息列表。`Message` 含 `_id`, `userId`, `title`, `content`, `type`, `category`, `isRead`, `readAt?`, `createdAt`, `updatedAt` 等。 |
+| `getUnreadStats(userId?, options?)` | `userId?`: string（管理员可指定） | `Promise<MessageStats>`：`total`, `byCategory` | 未读统计。 |
+| `markAsRead(messageId, request?, options?)` | `messageId`: string<br>`request?`: `MarkAsReadRequest` | `Promise<Message>` | 单条标已读。 |
+| `markManyAsRead(request, options?)` | `request`: `BatchMarkAsReadRequest`（如 `messageIds`） | `Promise<{ modifiedCount: number }>` | 批量标已读。 |
+| `createMessage(request, options?)` | `request`: `CreateMessageRequest`（`userId?`, `title`, `content`, `type`, `category`, `metadata?`） | `Promise<Message>` | 创建消息（管理员）。 |
+| `sendMail(request, options?)` | `request`: `MailRequest`（`to`, `subject?`, `text?`, `html?`, `cc?`, `bcc?`, `attachments?` 等） | `Promise<void>` | 发送邮件。 |
+| `sendFeishuMessage(message, options?)` | `message`: `FeishuMessage`（`url`, `title?`, `elements`, `noticeUser?`, `actions?`） | `Promise<void>` | 发送飞书消息。 |
+
+### client.ai（AI 对话与会话）
+
+| 方法 | 入参 | 返回值 | 说明 |
+|------|------|--------|------|
+| `chatCompletion(request, options?)` | `request`: `ChatCompletionRequest`（`sessionId`, `message`, `model?`） | `Promise<ChatCompletionResponse>`：`success`, `message`, `data.message`, `data.sessionId` | 单次对话（非流式）。 |
+| `chatCompletionStream(request, options?)` | 同上 | `Promise<ChatCompletionResponse>` | 流式对话。 |
+| `createSession(request, options?)` | `request`: `CreateSessionRequest`（见类型定义） | `Promise<SessionDetailResponse>` | 创建会话。 |
+| `getSessions(params?, options?)` | `params?`: `{ page?, limit?, status? }`，`status` 为 `'active' \| 'ended'` | `Promise<SessionListResponse>` | 会话列表。 |
+| `getSession(sessionId, options?)` | `sessionId`: string | `Promise<SessionDetailResponse>` | 会话详情。 |
+| `getSessionMessages(sessionId, params?, options?)` | `sessionId`: string<br>`params?`: `{ page?, limit? }` | `Promise<PaginatedSessionMessageResponse>` | 会话消息列表。 |
+| `addMessageToSession(sessionId, request, options?)` | `sessionId`: string<br>`request`: `AddMessageRequest` | `Promise<SessionDetailResponse>` | 向会话追加消息。 |
+| `getAssistants(params?, options?)` | `params?`: `{ page?, limit? }` | `Promise<AssistantListResponse>` | 助手列表。 |
+| `getAssistant(assistantId, options?)` | `assistantId`: string | `Promise<AssistantResponse>` | 助手详情。 |
+| `createAssistant(request, options?)` | `request`: `CreateAssistantRequest` | `Promise<AssistantResponse>` | 创建助手。 |
+| `getModels(params?, options?)` | `params?`: `{ provider?, capability? }` | `Promise<{ models: ModelListItem[] }>` | 模型列表。 |
+| `getModel(modelId, options?)` | `modelId`: string | `Promise<ModelDetail>` | 模型详情。 |
+
+### client.frontHost（静态 HTML 托管）
+
+| 方法 | 入参 | 返回值 | 说明 |
+|------|------|--------|------|
+| `listProjects(options?)` | — | `Promise<PaginatedResponse<FrontHostProject>>` | 托管项目列表。 |
+| `getProject(id, options?)` | `id`: string | `Promise<FrontHostProject>`：`id`, `name`, `domain`, `url`, `deployType`, `routePath`, `status` 等。 | 项目详情。 |
+| `createProject(input, options?)` | `input`: `FrontHostCreateProjectInput`（**必填** `deployType`, `file`；可选 `name`, `subdomain`, `domain`, `routePath`, `proxyDomain`）<br>`deployType`: `'subdomain' \| 'route' \| 'proxy' \| 'file'` | `Promise<FrontHostProject>` | 创建托管项目并上传 zip/文件。 |
+| `deployNewVersion(projectId, file, options?)` | `projectId`: string<br>`file`: Blob \| File（zip） | `Promise<FrontHostDeployResponse>`：`version`, `project` | 部署新版本。 |
+| `getProjectVersions(projectId, options?)` | `projectId`: string | `Promise<FrontHostProjectVersion[]>` | 项目版本列表。 |
+| `rollbackVersion(projectId, versionId, options?)` | `projectId`: string<br>`versionId`: string | `Promise<FrontHostDeployResponse>` | 回滚到指定版本。 |
+| `deleteProject(id, options?)` | `id`: string | `Promise<void>` | 删除项目。 |
+
+### 其他服务（类型即文档）
+
+以下服务方法较多，**入参与返回值均以包内 TypeScript 类型为准**，在 IDE 中查看对应 Service 的方法列表即可看到完整签名：
+
+- **client.token**：Token 管理。
+- **client.aigc**：AIGC 能力。
+- **client.audit**：`listAuditLogs(query?)` 等，入参见 `AuditLogListQuery`。
+- **client.provider**：`listProviders`、`getProvider`、`listProviderModels`、`listGlobalModels`、`chatCompletions` 等，请求/响应见 `provider`、`ai` 类型。
+- **client.usage**：`summary`、`daily`、`byModel`、`byProvider`、`byUser`、`top`，入参见 `UsageBaseQuery`、`UsageDailyQuery` 等。
+- **client.org**：组织/项目/应用 CRUD、解析等，见 `OrgService` 与 `types/org`。
+- **client.deliveryStream**：投递流、版本、需求等，见 `DeliveryStreamService` 与 `types/delivery-stream`。
+- **client.ezAbility**：需求枚举、PRD/MVPRD 生成、任务查询等，见 `EzAbilityService` 与 `types/ez-ability`。
+- **FileService**（独立实例）：`createFile`、`getFileById`、`listFiles`、`generateOSSUploadSign`、`getFolderTree`、`getDownloadUrl` 等，见 `FileService` 与 `types/file`。
+
+安装后可在 `node_modules/qing-client/lib/` 下查看 `*.d.ts` 或直接在业务代码中通过 IDE 跳转到上述类型与方法。
+
+---
+
 ## 用户与认证
 
 ### 登录
@@ -141,6 +300,7 @@ const messages = await client.msg.getMessages();
 ## AI / AIGC 示例
 
 ```ts
+// AI 对话（client.ai）
 const response = await client.ai.chatCompletion({
   sessionId: "session-id",
   message: "你好",
@@ -151,7 +311,7 @@ const response = await client.ai.chatCompletion({
 
 ## HTML 静态托管（gateway-h5）
 
-SDK 提供了静态 HTML 托管管理能力，用于上传和管理前端站点。
+SDK 提供了静态 HTML 托管管理能力，用于上传和管理前端站点。若已创建 `Client`，可直接使用 `client.frontHost`；也可单独 `import { FrontHostService } from "qing-client"` 并传入相同配置。
 
 > ⚠️ **重要说明**
 >

package/lib/service/EzAbilityService.d.ts

@@ -1,6 +1,6 @@
 import { BaseClient } from "../client/BaseClient";
 import { ClientConfig } from "../types";
-import { EnumerateRequirementsRequest, EnumerateRequirementsResponse, GeneratePRDRequest, GeneratePRDResponse, GenerateMVPRDRequest, GenerateMVPRDResponse, TaskQueryResponse, GetTasksQuery, GetPRDTasksQuery, GetMVPRDTasksQuery, TaskListResponse } from "../types/ez-ability";
+import { EnumerateRequirementsRequest, EnumerateRequirementsResponse, GeneratePRDRequest, GeneratePRDResponse, GenerateMVPRDRequest, GenerateMVPRDResponse, TaskQueryResponse, GetTasksQuery, GetPRDTasksQuery, GetMVPRDTasksQuery, TaskListResponse, NameRequirementRequest, NameRequirementResponse } from "../types/ez-ability";
 /**
  * EzAbility 服务 - AI 能力服务客户端
  *
@@ -8,6 +8,7 @@ import { EnumerateRequirementsRequest, EnumerateRequirementsResponse, GeneratePR
  * - 需求枚举（异步任务）
  * - PRD生成（异步任务）
  * - MVP PRD生成（异步任务）
+ * - 需求起名（同步接口）
  * - 任务列表查询（支持分页和过滤）
  * - 任务状态查询
  * - 任务取消
@@ -111,6 +112,15 @@ export declare class EzAbilityService extends BaseClient {
     cancelMVPRDTask(taskId: string): Promise<{
         message: string;
     }>;
+    /**
+     * 根据需求内容生成需求名称
+     *
+     * 同步接口，立即返回结果
+     *
+     * @param request 需求内容
+     * @returns 生成的需求名称
+     */
+    nameRequirement(request: NameRequirementRequest): Promise<NameRequirementResponse>;
     /**
      * 获取任务列表
      *

package/lib/service/EzAbilityService.js

@@ -10,6 +10,7 @@ const BaseClient_1 = require("../client/BaseClient");
  * - 需求枚举（异步任务）
  * - PRD生成（异步任务）
  * - MVP PRD生成（异步任务）
+ * - 需求起名（同步接口）
  * - 任务列表查询（支持分页和过滤）
  * - 任务状态查询
  * - 任务取消
@@ -153,6 +154,21 @@ class EzAbilityService extends BaseClient_1.BaseClient {
     async cancelMVPRDTask(taskId) {
         return this.request(`/prd-mvp/tasks/${taskId}`, { method: "DELETE" });
     }
+    // ==================== 需求起名 ====================
+    /**
+     * 根据需求内容生成需求名称
+     *
+     * 同步接口，立即返回结果
+     *
+     * @param request 需求内容
+     * @returns 生成的需求名称
+     */
+    async nameRequirement(request) {
+        return this.request("/requirement-naming/name", {
+            method: "POST",
+            body: request,
+        });
+    }
     // ==================== 任务管理 ====================
     /**
      * 获取任务列表

package/lib/types/ez-ability.d.ts

@@ -185,6 +185,16 @@ export interface TaskListResponse {
         hasMore: boolean;
     };
 }
+export interface NameRequirementRequest {
+    /** 需求内容（至少10个字符） */
+    requirement: string;
+    /** 指定使用的模型（不传则使用服务默认模型） */
+    model?: string;
+}
+export interface NameRequirementResponse {
+    /** 生成的需求名称 */
+    name: string;
+}
 export interface AbilityCallRequest {
     abilityId: string;
     params: Record<string, any>;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "qing-client",
-  "version": "0.0.50",
+  "version": "0.0.52",
   "main": "lib/index.js",
   "types": "lib/index.d.ts",
   "scripts": {