qing-client

Qing 平台统一 SDK - 插件化架构

特性

• 插件化架构：服务按需注册，类似 Vue.use() / Fastify.register()
• 完整类型推导：通过 Module Augmentation 实现类型自动补全
• 前后端统一：一套 SDK 支持前端（网关）和后端（直连）两种模式
• 自动 Token 管理：全局 setToken/clearToken 自动同步到所有服务
• 服务隔离：每个服务独立目录，互不影响
• HTTP 错误监控：支持 onHttpError / onUnauthorized 回调，便于统一处理

安装

npm install qing-client

快速开始

前端模式

import { 
  Client, 
  AuthService, 
  MsgService,
  AiService,
  ImService 
} from 'qing-client';

// 创建客户端并注册需要的服务
const client = new Client({
  gatewayUrl: 'https://api.example.com',
  projectId: 'your-project-id',
  appId: 'your-app-id',
})
  .use(AuthService)
  .use(MsgService)
  .use(AiService)
  .use(ImService);

// 登录
const loginRes = await client.services.auth.loginJson({
  username: 'user',
  password: 'pass',
});

// 设置 Token（全局生效）
await client.setToken(loginRes.access_token);

// 使用服务（完整类型推导）
const messages = await client.services.msg.getMessages({ isRead: false });
const groups = await client.services.im.listGroups();

后端模式

import { Client, AuthService, MsgService } from 'qing-client';

const client = new Client({
  authServiceUrl: 'http://auth-service',
  msgServiceUrl: 'http://msg-service',
  userContext: {
    userId: '123',
    role: 'ADMIN',
    projectId: 'project-1',
  },
})
  .use(AuthService)
  .use(MsgService);

await client.setToken('xxx');

可用服务（16 个）

核心服务

| 服务 | 说明 | 注册名 | API 文档 | |------|------|--------|----------| | AuthService | 认证与登录 | auth | auth.md | | MsgService | 消息中心 / 邮件 / 飞书 | msg | msg.md | | UserService | 用户管理 | user | user.md | | TokenService | 微信 Token 管理 | token | token.md | | FileService | 文件与文件夹管理 | file | file.md |

AI 相关

| 服务 | 说明 | 注册名 | API 文档 | |------|------|--------|----------| | AiService | AI 对话 / 助手 / 会话 | ai | ai.md | | AigcService | AIGC 生成与图像处理 | aigc | aigc.md | | ProviderService | 大模型供应商管理 | provider | provider.md | | UsageService | Token 用量统计 | usage | usage.md |

业务服务

| 服务 | 说明 | 注册名 | API 文档 | |------|------|--------|----------| | AuditLogService | 审计日志 | audit | audit.md | | FrontHostService | 前端 HTML 托管 | fronthost | fronthost.md | | OrgService | 组织 / 项目 / 应用管理 | org | org.md | | DeliveryStreamService | 投递流 / 版本 / 需求 | deliveryStream | delivery-stream.md | | EzAbilityService | AI 需求枚举与 PRD 生成 | ezAbility | ez-ability.md | | ImService | IM 群组与消息 | im | im.md | | HubService | 能力枢纽（大盘统计 / Worker / Task） | hub | hub.md |

注册名 即 client.services.<注册名> 中的 key。完整 API 参考见 docs/api/。

插件注册

链式注册

const client = new Client(config)
  .use(AuthService)
  .use(MsgService)
  .use(FileService)
  .use(AiService)
  .use(ImService);

批量注册

import { 
  AuthService, MsgService, FileService,
  AiService, ImService, OrgService 
} from 'qing-client';

const client = new Client(config).useAll([
  AuthService,
  MsgService,
  FileService,
  AiService,
  ImService,
  OrgService,
]);

Token 管理

全局设置

// 设置 Token（自动同步到所有服务）
await client.setToken('your-token');

// 清除 Token
await client.clearToken();

自定义 Token 存储

const client = new Client({
  gatewayUrl: '...',
  tokenStorage: {
    async getToken() {
      return localStorage.getItem('token') || undefined;
    },
    async setToken(token) {
      localStorage.setItem('token', token);
    },
    async clearToken() {
      localStorage.removeItem('token');
    },
  },
});

多租户支持

前端模式

// 方式一：初始化时配置
const client = new Client({
  gatewayUrl: '...',
  projectId: 'project-1',
  orgId: 'org-1',
  appId: 'app-1',
});

// 方式二：运行时设置
client.setProjectOrgApp('project-1', 'org-1', 'app-1');

后端模式

client.setUserContext({
  userId: '123',
  role: 'ADMIN',
  projectId: 'project-1',
  orgId: 'org-1',
  appId: 'app-1',
});

HTTP 错误监控

const client = new Client({
  gatewayUrl: '...',
  onHttpError(statusCode, error, ctx) {
    console.error(`[${ctx.serviceName}] ${ctx.path} → ${statusCode}`);
    if (statusCode >= 500) reportToSentry(error);
  },
  onUnauthorized() {
    router.push('/login');
  },
});

新增服务

参见 SDK-GENERATION.md

1. 在 src/services/{name}/ 创建服务目录
2. 生成 types.ts 和 {Name}Service.ts
3. 在 src/index.ts 添加导出
4. 使用方通过 .use(YourService) 注册

目录结构

src/
├── core/                    # 核心框架
│   ├── Client.ts            # 主客户端（插件注册）
│   ├── BaseClient.ts        # 服务基类
│   └── index.ts
├── types/                   # 公共类型和契约
│   ├── common.ts            # 通用类型（ApiResponse / TokenStorage 等）
│   ├── config.ts            # 配置类型（ClientConfig）
│   ├── service-contract.ts  # 服务契约（ServicePlugin / TokenAware 等）
│   └── index.ts
├── services/                # 服务目录（16 个服务）
│   ├── auth/                # 认证服务
│   ├── msg/                 # 消息服务
│   ├── user/                # 用户服务
│   ├── token/               # Token 服务
│   ├── file/                # 文件服务
│   ├── ai/                  # AI 服务
│   ├── aigc/                # AIGC 服务
│   ├── provider/            # 供应商服务
│   ├── usage/               # 用量服务
│   ├── audit/               # 审计日志服务
│   ├── fronthost/           # 前端托管服务
│   ├── org/                 # 组织服务
│   ├── delivery-stream/     # 投递流服务
│   ├── ez-ability/          # Ez 能力服务
│   ├── im/                  # IM 服务
│   ├── hub/                 # 能力枢纽服务
│   └── index.ts
├── docs/
│   └── SDK-GENERATION.md    # 服务生成指南
└── index.ts                 # 包入口

开发

# 安装依赖
npm install

# 构建
npm run build

# 发布
npm run rele

License

MIT