qing-client 0.0.52 → 0.0.53

package/README.MD

@@ -171,6 +171,8 @@ client.setUserContext({
 | `client.user` | 用户信息 |
 | `client.token` | Token 管理 |
 | `client.msg` | 消息中心 |
+| `client.files` | 文件服务（V2 新路由 `/api/files`） |
+| `client.file` | 文件服务（V1 兼容老项目 `/api/file`） |
 | `client.ai` | AI 对话/会话（chatCompletion、会话与助手等） |
 | `client.aigc` | AIGC 能力 |
 | `client.audit` | 审计日志 |
@@ -181,7 +183,7 @@ client.setUserContext({
 | `client.deliveryStream` | 投递流 |
 | `client.ezAbility` | Ez 能力 |
 
-文件服务需单独使用：`import { FileService } from "qing-client"`，并传入与前端/后端一致的配置。
+`client.files` 与 `client.file` 指向同一后端（fileServiceUrl），仅路径前缀不同；也可单独 `import { FileService } from "qing-client"` 并传入配置（如 `new FileService(config, 'files')` 或 `'file'`）。
 
 ---
 
@@ -201,6 +203,8 @@ client.setUserContext({
 | `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>` | 验证临时令牌。 |
+| `getTokenInfo(options?)` | — | `Promise<TokenInfoResponse>`：`sub`, `exp`, `expires_at`, `project_id`, `role`, `token_type`, `org_id?`, `app_id?` | 获取当前令牌信息（脱敏），需已 setToken。 |
+| `revokeToken(token?, options?)` | `token?`: string（不传则撤销当前令牌） | `Promise<RevokeTokenResponse>` | 撤销当前或指定令牌；撤销指定令牌仅限本人或管理员。 |
 | `logout(token, options?)` | `token`: string | `Promise<void>` | 登出。 |
 
 ### client.user（用户）
@@ -220,10 +224,15 @@ client.setUserContext({
 | 方法 | 入参 | 返回值 | 说明 |
 |------|------|--------|------|
 | `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` 等。 |
+| `getAdminMessages(params?, options?)` | 同上（管理员可传 `userId`/`pid`/`aid` 筛选） | `Promise<Message[]>` | 管理员获取消息列表（需管理员权限）。 |
+| `getTypes(options?)` | — | `Promise<MessageTypeItem[]>`：`{ value: 'system' \| 'business' \| 'notice', label }` | 消息类型枚举，供前端筛选或展示。 |
+| `getCategories(options?)` | — | `Promise<CategoryInfo[]>`：`category`, `unreadCount`, `latestMessage?` | 用户消息分类及未读数。 |
 | `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 }>` | 批量标已读。 |
+| `deleteMessage(messageId, request?, options?)` | `messageId`: string<br>`request?`: `MarkAsReadRequest`（管理员可传 `userId`） | `Promise<Message>` | 删除消息（软删除）。 |
 | `createMessage(request, options?)` | `request`: `CreateMessageRequest`（`userId?`, `title`, `content`, `type`, `category`, `metadata?`） | `Promise<Message>` | 创建消息（管理员）。 |
+| `createManyMessages(request, options?)` | `request`: `BatchCreateMessageRequest`（`messages: Array<{ userId, title, content, type, category, metadata? }>`） | `Promise<{ createdCount: number, messages: 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>` | 发送飞书消息。 |
 
@@ -268,12 +277,266 @@ client.setUserContext({
 - **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`。
+- **client.files / client.file**：文件服务（files 为新路由，file 兼容老项目）；方法同下。
+- **FileService**（独立实例）：`createFile`、`getFileById`、`listFiles`、`getStorageStats`、`generateOSSUploadSign`、`getFolderTree`、`getDownloadUrl` 等，见 `FileService` 与 `types/file`。构造时可选 `new FileService(config, 'files')` 或 `'file'`。
 
 安装后可在 `node_modules/qing-client/lib/` 下查看 `*.d.ts` 或直接在业务代码中通过 IDE 跳转到上述类型与方法。
 
 ---
 
+## 各服务方法使用示例
+
+以下为各服务**每个方法**的调用示例（假设已初始化 `client` 并已 `await client.setToken("...")`）。
+
+### client.auth（认证）
+
+```ts
+// 表单登录（旧版）
+const loginRes = await client.auth.login("username", "password", 0);
+await client.setToken(loginRes.access_token);
+
+// JSON 登录（推荐）
+const res = await client.auth.loginJson(
+  { username: "user", password: "pwd", org_id: "org1", app_id: "app1" },
+  0
+);
+await client.setToken(res.access_token);
+
+// 微信小程序登录
+const wxRes = await client.auth.wechatMiniProgramLogin({
+  code: "wx_code",
+  phone_code: "optional_phone_code",
+});
+await client.setToken(wxRes.access_token);
+
+// 注册
+const regRes = await client.auth.register({
+  username: "newuser",
+  email: "a@b.com",
+  password: "pwd",
+  name: "显示名",
+});
+
+// 签发临时令牌
+const tmp = await client.auth.createTemporaryToken({ expires_in: 300 });
+
+// 验证临时令牌
+const verified = await client.auth.verifyTemporaryToken({
+  temporary_token: tmp.temporary_token,
+});
+
+// 获取当前令牌信息
+const info = await client.auth.getTokenInfo();
+// info: { sub, exp, expires_at, project_id, role, token_type, org_id?, app_id? }
+
+// 撤销令牌（不传则撤销当前）
+await client.auth.revokeToken();
+await client.auth.revokeToken("specific_token");
+
+// 登出
+await client.auth.logout("token_to_logout");
+```
+
+### client.user（用户）
+
+```ts
+// 当前用户
+const me = await client.user.getCurrentUser();
+
+// 按 ID 查用户（管理员）
+const user = await client.user.getUserById(123);
+
+// 创建用户（管理员）
+const created = await client.user.createUser({
+  username: "u1",
+  email: "u1@example.com",
+  password: "pwd",
+  name: "User One",
+  role: "USER",
+});
+
+// 更新用户（管理员）
+const updated = await client.user.updateUser(123, {
+  name: "New Name",
+  avatar: "https://...",
+  phone: "13800138000",
+});
+
+// 用户列表（分页、可选项目过滤）
+const list = await client.user.listUsers(false, 1, 10, 0);
+// list: { data: User[], pagination: { ... } }
+
+// 更新当前用户资料
+await client.user.updateCurrentUser({ name: "My Name", avatar: "..." });
+
+// 修改当前用户密码
+await client.user.changeOwnPassword({
+  old_password: "old",
+  new_password: "new",
+});
+
+// 停用用户（管理员）
+await client.user.deactivateUser(123);
+
+// 恢复用户（管理员）
+await client.user.restoreUser(123);
+```
+
+### client.msg（消息中心）
+
+```ts
+// 获取当前用户消息列表（可分页、按类型/分类/已读筛选）
+const messages = await client.msg.getMessages({
+  type: "business",
+  category: "order",
+  isRead: false,
+  page: 1,
+  limit: 20,
+});
+
+// 管理员获取消息列表（可传 userId/pid/aid 筛选）
+const adminList = await client.msg.getAdminMessages({
+  userId: "user-id",
+  page: 1,
+  limit: 100,
+});
+
+// 消息类型枚举（供前端筛选用）
+const types = await client.msg.getTypes();
+// types: [{ value: 'system'|'business'|'notice', label }]
+
+// 用户消息分类及未读数
+const categories = await client.msg.getCategories();
+// categories: [{ category, unreadCount, latestMessage? }]
+
+// 未读统计（管理员可传 userId）
+const stats = await client.msg.getUnreadStats();
+// stats: { total, byCategory: Record<string, number> }
+
+// 标记单条已读
+const msg = await client.msg.markAsRead("message_id_24");
+
+// 批量标记已读
+const { modifiedCount } = await client.msg.markManyAsRead({
+  messageIds: ["id1", "id2"],
+});
+
+// 删除消息（软删除）
+const deleted = await client.msg.deleteMessage("message_id");
+
+// 创建单条消息（管理员）
+const created = await client.msg.createMessage({
+  title: "通知标题",
+  content: "内容",
+  type: "business",
+  category: "task",
+  userId: "optional_target_user_id",
+  metadata: { taskId: "t1" },
+});
+
+// 批量创建消息（管理员）
+const batch = await client.msg.createManyMessages({
+  messages: [
+    { userId: "u1", title: "标题", content: "内容", type: "notice", category: "announce" },
+  ],
+});
+// batch: { createdCount, messages }
+
+// 发送邮件
+await client.msg.sendMail({
+  to: ["a@example.com"],
+  subject: "主题",
+  text: "纯文本内容",
+  // 或 html: "<p>HTML 内容</p>",
+});
+
+// 发送飞书消息
+await client.msg.sendFeishuMessage({
+  url: "https://open.feishu.cn/open-apis/bot/v2/hook/xxx",
+  title: "卡片标题",
+  elements: [{ title: "字段名", text: "字段值", color: "green" }],
+  noticeUser: [{ user_id: "user_open_id" }],
+  actions: [{ text: "查看", url: "https://...", type: "primary" }],
+});
+```
+
+### client.ai（AI 对话与会话）
+
+```ts
+// 单次对话（非流式）
+const chat = await client.ai.chatCompletion({
+  sessionId: "session-id",
+  message: "你好",
+  model: "model-id",
+});
+
+// 流式对话
+const stream = await client.ai.chatCompletionStream({
+  sessionId: "session-id",
+  message: "你好",
+});
+
+// 创建会话
+const session = await client.ai.createSession({
+  assistant_id: "asst-id",
+  model_id: "model-id",
+  title: "新会话",
+});
+
+// 会话列表
+const sessions = await client.ai.getSessions({ page: 1, limit: 20, status: "active" });
+
+// 会话详情
+const detail = await client.ai.getSession("session-id");
+
+// 会话消息列表
+const msgs = await client.ai.getSessionMessages("session-id", { page: 1, limit: 50 });
+
+// 向会话追加消息
+await client.ai.addMessageToSession("session-id", { role: "user", content: "..." });
+
+// 助手列表 / 详情
+const assistants = await client.ai.getAssistants({ page: 1, limit: 20 });
+const assistant = await client.ai.getAssistant("assistant-id");
+await client.ai.createAssistant({ name: "助手", model_id: "..." });
+
+// 模型列表 / 详情
+const { models } = await client.ai.getModels({ provider: "openai", capability: "chat" });
+const model = await client.ai.getModel("model-id");
+```
+
+### client.frontHost（静态 HTML 托管）
+
+```ts
+// 托管项目列表
+const projects = await client.frontHost.listProjects();
+
+// 项目详情
+const project = await client.frontHost.getProject("project-id");
+
+// 创建托管项目（上传 zip）
+const created = await client.frontHost.createProject({
+  deployType: "route",
+  routePath: "/my-app",
+  file: zipBlob,
+  name: "My App",
+});
+
+// 部署新版本
+const deploy = await client.frontHost.deployNewVersion("project-id", zipBlob);
+
+// 项目版本列表
+const versions = await client.frontHost.getProjectVersions("project-id");
+
+// 回滚版本
+await client.frontHost.rollbackVersion("project-id", "version-id");
+
+// 删除项目
+await client.frontHost.deleteProject("project-id");
+```
+
+---
+
 ## 用户与认证
 
 ### 登录
@@ -410,6 +673,41 @@ SDK 完全使用 TypeScript 编写，并自带类型声明文件。
 
 ---
 
+## CI 测试与已知差异
+
+供自动化测试与文档对齐参考。
+
+### 1. 当前 SDK 未实现的方法（请勿在测试或文档中引用）
+
+以下名称在 SDK 中**不存在**，若 CI 或文档中引用会导致失败。**其中多数在基础服务（basis-service）中也没有对应接口**，属于“后端本身未提供”而非仅 SDK 未封装：
+
+| 误用名称 | 说明 / 替代 | 基础服务是否有对应接口 |
+|----------|-------------|------------------------|
+| `auth.refreshToken` / `auth.verifyToken` | 未实现；auth 仅有 login/register/logout、temporary-token、verify-temporary-token | **无**（User-Auth 无 refresh/verify 用户 token 接口） |
+| `token.getTokenInfo` / `token.revokeToken` | 请使用 **`client.auth.getTokenInfo()`**、**`client.auth.revokeToken(token?)`**（接口在 auth 服务下） | **有**（User-Auth 已提供 GET/POST `/api/auth/token/info`、`/token/revoke`） |
+| `token.listActiveTokens` | 未实现 | **无**（需会话存储能力） |
+| `msg.getTypes` | 已实现：**`client.msg.getTypes()`**，返回消息类型枚举（system / business / notice） | **有**（msg_center 已提供 GET `/message/types`） |
+| `file.getStorageStats` | 已实现：**`client.file.getStorageStats()`**（或独立 `FileService` 实例），返回 totalSize、fileCount、quota、usedPercent；配额按角色：超管无上限、管理员 100GB、普通用户 10GB | **有**（file-service 已提供 GET `/storage-stats` 及创建文件时配额校验） |
+| `audit.getLogTypes` / `audit.exportLogs` | 未实现 | **无**（audit-log-service 仅有 POST /、POST /batch、GET / 查询） |
+| `org.resolveProject` / `org.listOrganizations` | 请使用 `org.resolve(request)`、`org.adminListOrganizations(query)` | **有等价**：org 有 POST `/org/resolve`、GET `/admin/orgs`（SDK 为 resolve / adminListOrganizations） |
+| `frontHost.getStats` | 未实现 | **无**（gateway_h5 仅有 /health，无 /stats） |
+| `ezAbility.getRequirementEnums` | 请使用 `ezAbility.enumerateRequirements(request)`（需求枚举） | **有等价**：需求枚举为 `enumerateRequirements`，无单独 getRequirementEnums 接口 |
+
+### 2. 参数与调用约定
+
+* **provider.getModel(providerId, modelId)**：两个参数均必须为**非空字符串**，传 `undefined` 会抛错。
+* **deliveryStream.listRequirements(streamId, query?, options?)** / **listVersions(streamId, query?, options?)**：第一个参数必须为 **streamId 字符串**，不能传对象。
+
+### 3. 权限要求
+
+* **org** 服务中大部分管理接口（如 `getProject`、`getProjectApps`、`adminListProjects`、`adminListApps` 等）需要 **SUPER_ADMIN** 或 **SYSTEM** 角色；使用 ADMIN 账号调用会返回权限不足。
+
+### 4. 请求体格式
+
+* 部分接口请求体在发送前会转为 **snake_case**（如 `ai.createSession`、`msg.createMessage`、`ezAbility.enumerateRequirements` / `generatePRD` / `generateMVPRD` / `nameRequirement`），与后端 API 约定一致；入参仍使用 TypeScript 的 camelCase 类型即可。
+
+---
+
 ## License
 
 MIT

package/lib/client/index.d.ts

@@ -4,6 +4,7 @@ import { AuthService } from "../service/AuthService";
 import { MsgService } from "../service/MsgService";
 import { TokenService } from "../service/TokenService";
 import { UserService } from "../service/UserService";
+import { FileService } from "../service/FileService";
 import { AuditLogService } from "../service/AuditLogService";
 import { ProviderService } from "../service/ProviderService";
 import { UsageService } from "../service/UsageService";
@@ -18,6 +19,10 @@ export declare class Client {
     readonly msg: MsgService;
     readonly user: UserService;
     readonly token: TokenService;
+    /** 文件服务（V2 新路由 /api/files） */
+    readonly files: FileService;
+    /** 文件服务（V1 兼容老项目 /api/file） */
+    readonly file: FileService;
     readonly aigc: AigcService;
     readonly ai: AiService;
     readonly audit: AuditLogService;

package/lib/client/index.js

@@ -7,6 +7,7 @@ const AuthService_1 = require("../service/AuthService");
 const MsgService_1 = require("../service/MsgService");
 const TokenService_1 = require("../service/TokenService");
 const UserService_1 = require("../service/UserService");
+const FileService_1 = require("../service/FileService");
 const AuditLogService_1 = require("../service/AuditLogService");
 const ProviderService_1 = require("../service/ProviderService");
 const UsageService_1 = require("../service/UsageService");
@@ -22,6 +23,8 @@ class Client {
         this.msg = new MsgService_1.MsgService(config);
         this.user = new UserService_1.UserService(config);
         this.token = new TokenService_1.TokenService(config);
+        this.files = new FileService_1.FileService(config, "files");
+        this.file = new FileService_1.FileService(config, "file");
         this.aigc = new AigcService_1.AigcService(config);
         this.ai = new AiService_1.AiService(config);
         this.audit = new AuditLogService_1.AuditLogService(config);
@@ -39,6 +42,8 @@ class Client {
             this.msg.setUserContext(context);
             this.user.setUserContext(context);
             this.token.setUserContext(context);
+            this.files.setUserContext(context);
+            this.file.setUserContext(context);
             this.aigc.setUserContext(context);
             this.ai.setUserContext(context);
             this.audit.setUserContext(context);
@@ -61,6 +66,8 @@ class Client {
             this.msg.setProjectId(projectId);
             this.user.setProjectId(projectId);
             this.token.setProjectId(projectId);
+            this.files.setProjectId(projectId);
+            this.file.setProjectId(projectId);
             this.aigc.setProjectId(projectId);
             this.ai.setProjectId(projectId);
             this.audit.setProjectId(projectId);
@@ -83,6 +90,8 @@ class Client {
             this.msg.setAppId(appId);
             this.user.setAppId(appId);
             this.token.setAppId(appId);
+            this.files.setAppId(appId);
+            this.file.setAppId(appId);
             this.aigc.setAppId(appId);
             this.ai.setAppId(appId);
             this.audit.setAppId(appId);
@@ -105,6 +114,8 @@ class Client {
             this.msg.setProjectAndApp(projectId, appId);
             this.user.setProjectAndApp(projectId, appId);
             this.token.setProjectAndApp(projectId, appId);
+            this.files.setProjectAndApp(projectId, appId);
+            this.file.setProjectAndApp(projectId, appId);
             this.aigc.setProjectAndApp(projectId, appId);
             this.ai.setProjectAndApp(projectId, appId);
             this.audit.setProjectAndApp(projectId, appId);
@@ -126,6 +137,8 @@ class Client {
         await this.msg.setToken(token);
         await this.user.setToken(token);
         await this.token.setToken(token);
+        await this.files.setToken(token);
+        await this.file.setToken(token);
         await this.aigc.setToken(token);
         await this.ai.setToken(token);
         await this.audit.setToken(token);
@@ -142,6 +155,8 @@ class Client {
         await this.msg.clearToken();
         await this.user.clearToken();
         await this.token.clearToken();
+        await this.files.clearToken();
+        await this.file.clearToken();
         await this.aigc.clearToken();
         await this.ai.clearToken();
         await this.audit.clearToken();

package/lib/service/AiService.js

@@ -3,6 +3,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.AiService = void 0;
 // src/service/AiService.ts
 const BaseClient_1 = require("../client/BaseClient");
+const snakeCase_1 = require("../utils/snakeCase");
 class AiService extends BaseClient_1.BaseClient {
     constructor(config) {
         super(config, 'ai');
@@ -27,7 +28,7 @@ class AiService extends BaseClient_1.BaseClient {
         return this.request('/session', {
             ...options,
             method: 'POST',
-            body: request
+            body: (0, snakeCase_1.keysToSnakeCase)(request)
         });
     }
     async getSessions(params, options) {

package/lib/service/AuthService.d.ts

@@ -1,6 +1,6 @@
 import { BaseClient } from "../client/BaseClient";
 import { ClientConfig, RequestOptions } from "../types";
-import { LoginResponse, TemporaryTokenRequest, TemporaryTokenResponse, VerifyTemporaryTokenRequest, VerifyTemporaryTokenResponse, WechatLoginCredentials, LoginCredentials, RegisterRequest, RegisterResponse } from "../types/user";
+import { LoginResponse, TemporaryTokenRequest, TemporaryTokenResponse, VerifyTemporaryTokenRequest, VerifyTemporaryTokenResponse, WechatLoginCredentials, LoginCredentials, RegisterRequest, RegisterResponse, TokenInfoResponse, RevokeTokenResponse } from "../types/user";
 export declare class AuthService extends BaseClient {
     constructor(config: ClientConfig);
     /**
@@ -29,4 +29,15 @@ export declare class AuthService extends BaseClient {
     createTemporaryToken(request?: TemporaryTokenRequest, options?: RequestOptions): Promise<TemporaryTokenResponse>;
     verifyTemporaryToken(request: VerifyTemporaryTokenRequest, options?: RequestOptions): Promise<VerifyTemporaryTokenResponse>;
     logout(token: string, options?: RequestOptions): Promise<void>;
+    /**
+     * 获取当前令牌信息（脱敏）
+     * GET /token/info，需在请求头带 Authorization: Bearer <token>
+     */
+    getTokenInfo(options?: RequestOptions): Promise<TokenInfoResponse>;
+    /**
+     * 撤销令牌
+     * 不传 token 则撤销当前请求的令牌；传 token 则撤销指定令牌（仅限本人或管理员）
+     * POST /token/revoke
+     */
+    revokeToken(token?: string, options?: RequestOptions): Promise<RevokeTokenResponse>;
 }

package/lib/service/AuthService.js

@@ -120,5 +120,32 @@ class AuthService extends BaseClient_1.BaseClient {
             }
         });
     }
+    /**
+     * 获取当前令牌信息（脱敏）
+     * GET /token/info，需在请求头带 Authorization: Bearer <token>
+     */
+    async getTokenInfo(options) {
+        return this.request('/token/info', {
+            ...options,
+            method: 'GET',
+        });
+    }
+    /**
+     * 撤销令牌
+     * 不传 token 则撤销当前请求的令牌；传 token 则撤销指定令牌（仅限本人或管理员）
+     * POST /token/revoke
+     */
+    async revokeToken(token, options) {
+        const body = token ? { token } : {};
+        return this.request('/token/revoke', {
+            ...options,
+            method: 'POST',
+            headers: {
+                ...options?.headers,
+                'Content-Type': 'application/json',
+            },
+            body: JSON.stringify(body),
+        });
+    }
 }
 exports.AuthService = AuthService;

package/lib/service/DeliveryStreamService.js

@@ -81,6 +81,9 @@ class DeliveryStreamService extends BaseClient_1.BaseClient {
      * GET /streams/:streamId/versions
      */
     async listVersions(streamId, query, options) {
+        if (typeof streamId !== "string" || streamId === "") {
+            throw new Error("DeliveryStreamService.listVersions 第一个参数必须为 streamId 字符串");
+        }
         return this.paginatedRequest(`/streams/${streamId}/versions`, {
             ...options,
             method: 'GET',
@@ -146,6 +149,9 @@ class DeliveryStreamService extends BaseClient_1.BaseClient {
      * GET /streams/:streamId/requirements
      */
     async listRequirements(streamId, query, options) {
+        if (typeof streamId !== "string" || streamId === "") {
+            throw new Error("DeliveryStreamService.listRequirements 第一个参数必须为 streamId 字符串");
+        }
         return this.paginatedRequest(`/streams/${streamId}/requirements`, {
             ...options,
             method: 'GET',

package/lib/service/EzAbilityService.js

@@ -3,6 +3,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.EzAbilityService = void 0;
 // npm/src/service/EzAbilityService.ts
 const BaseClient_1 = require("../client/BaseClient");
+const snakeCase_1 = require("../utils/snakeCase");
 /**
  * EzAbility 服务 - AI 能力服务客户端
  *
@@ -34,7 +35,7 @@ class EzAbilityService extends BaseClient_1.BaseClient {
     async enumerateRequirements(request) {
         return this.request("/requirements/enumerate", {
             method: "POST",
-            body: request,
+            body: (0, snakeCase_1.keysToSnakeCase)(request),
         });
     }
     // ==================== PRD生成 ====================
@@ -54,7 +55,7 @@ class EzAbilityService extends BaseClient_1.BaseClient {
     async generatePRD(request) {
         return this.request("/prd/generate", {
             method: "POST",
-            body: request,
+            body: (0, snakeCase_1.keysToSnakeCase)(request),
         });
     }
     /**
@@ -113,7 +114,7 @@ class EzAbilityService extends BaseClient_1.BaseClient {
     async generateMVPRD(request) {
         return this.request("/prd-mvp/generate", {
             method: "POST",
-            body: request,
+            body: (0, snakeCase_1.keysToSnakeCase)(request),
         });
     }
     /**
@@ -166,7 +167,7 @@ class EzAbilityService extends BaseClient_1.BaseClient {
     async nameRequirement(request) {
         return this.request("/requirement-naming/name", {
             method: "POST",
-            body: request,
+            body: (0, snakeCase_1.keysToSnakeCase)(request),
         });
     }
     // ==================== 任务管理 ====================

package/lib/service/FileService.d.ts

@@ -1,8 +1,12 @@
 import { BaseClient } from "../client/BaseClient";
 import { ClientConfig, RequestOptions, PaginatedResponse } from "../types";
-import { File, CreateFileRequest, UpdateFileRequest, FileListQuery, Folder, FolderItemsResponse, FolderTreeNode, CreateFolderRequest, UpdateFolderRequest, OSSConfig, GenerateOSSUploadSignRequest, GenerateOSSUploadSignResponse, OSSCallbackQuery, OSSCallbackBody, OSSCallbackResponse, TaskOptionsResponse, FolderContentsResponse, FileUrlResponse, BatchDeleteRequest, BatchDeleteResponse, BatchMoveRequest, BatchMoveResponse, FileSearchQuery, TransferUploadFileRequest, TransferUploadFileResponse } from "../types/file";
+import { File, CreateFileRequest, UpdateFileRequest, FileListQuery, StorageStatsResponse, Folder, FolderItemsResponse, FolderTreeNode, CreateFolderRequest, UpdateFolderRequest, OSSConfig, GenerateOSSUploadSignRequest, GenerateOSSUploadSignResponse, OSSCallbackQuery, OSSCallbackBody, OSSCallbackResponse, TaskOptionsResponse, FolderContentsResponse, FileUrlResponse, BatchDeleteRequest, BatchDeleteResponse, BatchMoveRequest, BatchMoveResponse, FileSearchQuery, TransferUploadFileRequest, TransferUploadFileResponse } from "../types/file";
+/**
+ * 文件服务：files（V2 新路由）/ file（V1 兼容老项目）
+ * 同一后端，仅请求路径前缀不同：/api/files 或 /api/file
+ */
 export declare class FileService extends BaseClient {
-    constructor(config: ClientConfig);
+    constructor(config: ClientConfig, serviceName?: 'files' | 'file');
     /**
      * 创建文件记录（OSS回调使用）
      * POST /api/files (网关转发到 /api/v1/files)
@@ -23,6 +27,12 @@ export declare class FileService extends BaseClient {
      * DELETE /api/files/:id (网关转发到 /api/v1/files/:id)
      */
     deleteFile(fileId: string, options?: RequestOptions): Promise<null>;
+    /**
+     * 获取存储统计与配额
+     * GET /api/files/storage-stats
+     * 按角色：超管无上限，管理员 100GB，普通用户 10GB；返回 totalSize、fileCount、quota、usedPercent
+     */
+    getStorageStats(options?: RequestOptions): Promise<StorageStatsResponse>;
     /**
      * 获取文件列表
      * GET /api/files (网关转发到 /api/v1/files)

package/lib/service/FileService.js

@@ -2,9 +2,13 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.FileService = void 0;
 const BaseClient_1 = require("../client/BaseClient");
+/**
+ * 文件服务：files（V2 新路由）/ file（V1 兼容老项目）
+ * 同一后端，仅请求路径前缀不同：/api/files 或 /api/file
+ */
 class FileService extends BaseClient_1.BaseClient {
-    constructor(config) {
-        super(config, 'files');
+    constructor(config, serviceName = 'files') {
+        super(config, serviceName);
     }
     /**
      * 创建文件记录（OSS回调使用）
@@ -66,6 +70,17 @@ class FileService extends BaseClient_1.BaseClient {
             method: 'DELETE'
         });
     }
+    /**
+     * 获取存储统计与配额
+     * GET /api/files/storage-stats
+     * 按角色：超管无上限，管理员 100GB，普通用户 10GB；返回 totalSize、fileCount、quota、usedPercent
+     */
+    async getStorageStats(options) {
+        return this.request('/storage-stats', {
+            ...options,
+            method: 'GET'
+        });
+    }
     /**
      * 获取文件列表
      * GET /api/files (网关转发到 /api/v1/files)

package/lib/service/MsgService.d.ts

@@ -1,6 +1,6 @@
 import { BaseClient } from "../client/BaseClient";
 import { ClientConfig, RequestOptions } from "../types";
-import { BatchCreateMessageRequest, BatchMarkAsReadRequest, CategoryInfo, CreateMessageRequest, FeishuMessage, MailRequest, MarkAsReadRequest, Message, MessageQueryParams, MessageStats } from "../types/msg";
+import { BatchCreateMessageRequest, BatchMarkAsReadRequest, CategoryInfo, CreateMessageRequest, FeishuMessage, MailRequest, MarkAsReadRequest, Message, MessageQueryParams, MessageStats, MessageTypeItem } from "../types/msg";
 export declare class MsgService extends BaseClient {
     constructor(config: ClientConfig);
     sendMail(request: MailRequest, options?: RequestOptions): Promise<void>;
@@ -14,6 +14,8 @@ export declare class MsgService extends BaseClient {
     deleteMessage(messageId: string, request?: MarkAsReadRequest, options?: RequestOptions): Promise<Message>;
     getUnreadStats(userId?: string, options?: RequestOptions): Promise<MessageStats>;
     getCategories(options?: RequestOptions): Promise<CategoryInfo[]>;
+    /** 获取消息类型枚举（system / business / notice），供前端筛选或展示 */
+    getTypes(options?: RequestOptions): Promise<MessageTypeItem[]>;
     createMessage(request: CreateMessageRequest, options?: RequestOptions): Promise<Message>;
     createManyMessages(request: BatchCreateMessageRequest, options?: RequestOptions): Promise<{
         createdCount: number;

package/lib/service/MsgService.js

@@ -3,6 +3,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.MsgService = void 0;
 // client/npm/src/service/MsgService.ts
 const BaseClient_1 = require("../client/BaseClient");
+const snakeCase_1 = require("../utils/snakeCase");
 class MsgService extends BaseClient_1.BaseClient {
     constructor(config) {
         super(config, 'msg');
@@ -88,12 +89,19 @@ class MsgService extends BaseClient_1.BaseClient {
             method: 'GET'
         });
     }
+    /** 获取消息类型枚举（system / business / notice），供前端筛选或展示 */
+    async getTypes(options) {
+        return this.request('/message/types', {
+            ...options,
+            method: 'GET'
+        });
+    }
     // 创建消息（需要管理员权限）
     async createMessage(request, options) {
         return this.request('/message', {
             ...options,
             method: 'POST',
-            body: request
+            body: (0, snakeCase_1.keysToSnakeCase)(request)
         });
     }
     // 批量创建消息（需要管理员权限）

package/lib/service/ProviderService.js

@@ -73,6 +73,9 @@ class ProviderService extends BaseClient_1.BaseClient {
         });
     }
     async getModel(providerId, modelId, options) {
+        if (providerId == null || providerId === "" || modelId == null || modelId === "") {
+            throw new Error("ProviderService.getModel 需要有效的 providerId 和 modelId 字符串");
+        }
         return this.request(this.path(`/models/${providerId}/${modelId}`), {
             ...options,
             method: "GET",

package/lib/types/file.d.ts

@@ -48,6 +48,16 @@ export interface FileListQuery {
     acl?: 'private' | 'public-read';
     uid?: string;
 }
+/**
+ * 存储统计与配额（getStorageStats 返回）
+ * quota 为 null 表示无上限（超管）；有值时 usedPercent 为已用百分比
+ */
+export interface StorageStatsResponse {
+    totalSize: number;
+    fileCount: number;
+    quota: number | null;
+    usedPercent?: number;
+}
 export interface Folder {
     id: string;
     name: string;

package/lib/types/msg.d.ts

@@ -94,3 +94,8 @@ export interface CategoryInfo {
         createdAt: string;
     };
 }
+/** 消息类型枚举项（getTypes 返回） */
+export interface MessageTypeItem {
+    value: 'system' | 'business' | 'notice';
+    label: string;
+}

package/lib/types/user.d.ts

@@ -105,3 +105,23 @@ export interface VerifyTemporaryTokenResponse {
     token_valid: boolean;
     project_id: number;
 }
+/** 当前令牌信息（脱敏，供前端判断身份与过期） */
+export interface TokenInfoResponse {
+    sub: string;
+    exp: number;
+    expires_at?: string;
+    project_id: number;
+    role?: string;
+    token_type?: string;
+    org_id?: string;
+    app_id?: string;
+}
+/** 撤销令牌请求（不传 token 则撤销当前请求的令牌） */
+export interface RevokeTokenRequest {
+    token?: string;
+}
+/** 撤销令牌响应 */
+export interface RevokeTokenResponse {
+    success: boolean;
+    message: string;
+}

package/lib/utils/snakeCase.d.ts

@@ -0,0 +1,4 @@
+/**
+ * 递归转换对象键为 snake_case，最大深度 3，避免深层嵌套导致问题
+ */
+export declare function keysToSnakeCase<T = unknown>(obj: T, depth?: number): T;

package/lib/utils/snakeCase.js

@@ -0,0 +1,28 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.keysToSnakeCase = keysToSnakeCase;
+/**
+ * 将 camelCase 键名转为 snake_case（用于请求体与后端 API 对齐）
+ */
+function toSnakeCase(str) {
+    return str.replace(/[A-Z]/g, (c) => `_${c.toLowerCase()}`);
+}
+/**
+ * 递归转换对象键为 snake_case，最大深度 3，避免深层嵌套导致问题
+ */
+function keysToSnakeCase(obj, depth = 0) {
+    const maxDepth = 3;
+    if (depth > maxDepth)
+        return obj;
+    if (obj === null || typeof obj !== 'object')
+        return obj;
+    if (Array.isArray(obj)) {
+        return obj.map((item) => keysToSnakeCase(item, depth + 1));
+    }
+    const result = {};
+    for (const [key, value] of Object.entries(obj)) {
+        const snakeKey = toSnakeCase(key);
+        result[snakeKey] = keysToSnakeCase(value, depth + 1);
+    }
+    return result;
+}

package/package.json

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