@aiservicer/sdk

AIServicer 平台的官方 TypeScript SDK —— 覆盖 Agent / 交易 / Bot / 知识库 / 渠道 / 对话 / 分析 / Auth / AgentX / Chat / API Key / LightRAG / Admin / 编排 / 定时任务 / 企业内 Agent（企业知识库 + 监控）等全部资源。支持 Gateway（/api/v1）、Server（/api）与 Admin（/api/admin）三类 API 域。

• 运行时：Node.js >= 18（ESM）
• 类型：完整 TypeScript 类型定义（自带 dist/index.d.ts）
• License：MIT

安装

npm install @aiservicer/sdk

快速开始

方式一：API Key（推荐，服务端 / 简单集成）

import { AIServicerClient } from "@aiservicer/sdk";

const client = new AIServicerClient({
  baseUrl: "https://aiservicer.0xainet.top",        // Gateway 根地址（生产域名，走 HTTPS）
  serverBaseUrl: "https://aiservicer.0xainet.top",  // Server 根地址（auth/chat/lightrag/admin 等，同域名）
  apiKey: "aisvc-xxx",                          // 商户 API Key
});

// 列出 agent
const { agents } = await client.agents.list({ projectId: "project-xxx" });

// 与 agent 对话
const { reply, transaction } = await client.agents.chat({
  message: "我想在 Base 上铸造一个 NFT",
  userAddress: "0x1234...",
  chainId: 8453,
});
console.log(reply);

方式二：JWT 登录（需数学验证码）

生产环境 login/register 强制要求验证码，SDK 已内置 auth.getCaptcha() 求解接口：

import { AIServicerClient } from "@aiservicer/sdk";

const client = new AIServicerClient({
  baseUrl: "https://aiservicer.0xainet.top",
  apiKey: "aisvc-xxx", // 构造时必填 apiKey 或 token 之一
});

// 1. 获取数学验证码（svg 为 data URI，算式 a + b = ? / a - b = ?，结果恒非负）
const { token, svg } = await client.auth.getCaptcha();
const svgText = Buffer.from(svg.replace(/^data:image\/svg\+xml;base64,/, ""), "base64").toString("utf-8");
const m = svgText.match(/(\d+)\s*([+-])\s*(\d+)/)!;
const answer = m[2] === "+" ? Number(m[1]) + Number(m[3]) : Number(m[1]) - Number(m[3]);

// 2. 登录（签发 7 天 JWT，无 refresh 端点 → 到期需提前重登）
const { token: jwt } = await client.auth.login("username", "password", { token, answer });
client.setToken(jwt); // SDK 不会自动接线，需手动 setToken 切换为 JWT 模式

JWT 续期约定：login 签发 7 天有效 JWT 且无 refresh 机制，请提前 1 天重新登录并 setToken。完整实现见 examples/cryptchat-multitenant.ts 的 ensureToken()。

认证方式

| 方式 | 配置 | 生效域 | |------|------|--------| | API Key | config.apiKey | 所有请求带 X-API-Key Header | | 商户 JWT | client.setToken(jwt) | 覆盖 API Key，带 Authorization: Bearer（auth/agentx/chat/lightrag/orchestration/scheduledTasks 等） | | 管理员 JWT | client.admin 前置 setToken（管理员账号） | Admin 资源（/api/admin/*） |

setToken() 是全局切换，调用后所有资源请求优先使用 JWT。

集成方（API Key）对话：BYOK / 平台 LLM 授权

通过 API Key（X-API-Key）接入的集成方调用对话（agents.chat / chat.send）时的 LLM 选择（2026-08-11 起生效）：

• Bot 已配置自有 LLM Provider（BYOK） → 走商户自有 LLM（不计平台配额）；
• Bot 未配置 BYOK 且商户为付费套餐（获平台 LLM 授权）→ 回退平台 LLM（按商户套餐 token 配额计费）；
• Bot 未配置 BYOK 且商户未授权 → 返回 400：

{
  "error": "byok_required",
  "code": "BYOK_REQUIRED",
  "reply": "该 Bot 未配置自己的 LLM Provider，且商户未获平台 LLM 使用授权。请为该 Bot 配置自有 LLM（BYOK），或升级付费套餐获取平台 LLM 授权后重试。"
}

• 平台 LLM（DeepSeek）按商户授权使用：平台登录用户（JWT）按套餐配额；API Key 集成方在商户获得平台 LLM 授权后也可回退使用。
• 判定依据：网关转发对话请求时透传 X-Auth-Mode（API Key → api-key，JWT → jwt）。
• 集成方 LLM 策略可配置（server 环境变量 API_KEY_LLM_POLICY）：
  • authorized（默认）：API Key 无 BYOK 时按商户平台 LLM 授权判定——付费套餐（price_monthly>0）即授权 → 回退平台 LLM（按商户套餐 token 配额计费）；未授权 → 400 byok_required；
  • strict：强制 BYOK，关闭授权回退（平台 LLM 不向 API Key 集成方开放）。
  • 切换后需重启 aiservicer-server 生效（见 docs/DEPLOY.md）。

为 Bot 配置 BYOK（平台后台「Bot → LLM Provider」，或 merchant API，需商户 JWT）：

POST /api/merchant/projects/:projectId/bots/:botId/llm-config
Content-Type: application/json
Authorization: Bearer <merchant-jwt>

{ "provider": "custom", "endpointUrl": "https://api.your-llm.com/v1", "apiKey": "sk-...", "model": "your-model" }

• provider ∈ platform | deepseek | openai | anthropic | gemini | qwen | glm | kimi | custom
• custom 必须同时提供 endpointUrl + apiKey；预置 provider 至少填 apiKey（endpoint 可空走预置端点）
• platform = 删除配置回退平台 LLM（仅 JWT 用户可用）
• 完整示例见 examples/cryptchat-multitenant.ts 的 configureBotByok() / chatAsIntegrator()

请求级 BYOK：按次对话传入用户自己的 LLM Key（0.9.0+）

chat.send / agents.chat 支持在单次请求中传入调用方自己的 LLM API Key（不消耗商户配额，优先级高于 Bot 后台配置）：

await client.chat.send({
  message: '你好',
  projectId: 'p_xxx',
  botId: 'bot_xxx',
  userAddress: '0x...',
  llmApiKey: 'sk-user-own-key',   // 可选：本次对话使用该 Key 调用 LLM
  llmEndpoint: 'https://api.your-llm.com/v1', // 可选：OpenAI 兼容端点（默认平台端点）
  llmModel: 'your-model',          // 可选：模型名（默认平台模型）
});

• 携带 llmApiKey：本次对话走调用方 Key（BYOK），不扣商户月度配额、不计入平台用量日志；
• 未携带：保持现状（Bot 配置的 provider，或平台 LLM 按套餐配额）。
• 无效/欠费 Key 错误（结构化错误码）：

| 场景 | HTTP | code | |------|------|------| | Key 无效 / 欠费（上游 401/403） | 400 | LLM_KEY_INVALID | | 上游 5xx / 超时 | 502 | LLM_UPSTREAM_ERROR |

响应 usage 明细（0.9.0+）

chat.send / agents.chat 成功响应新增 usage 字段（真实 input/output token 拆分，多轮工具调用按轮次累加）：

{
  "reply": "...",
  "tokensUsed": 167,
  "usage": { "input_tokens": 98, "output_tokens": 69 }
}

tokensUsed 保持兼容（= input + output）；无明细时 usage 省略。

资源概览（client.*）

| 资源 | 主要能力 | API 域 | |------|----------|--------| | client.project | 项目 CRUD、列表 | Gateway | | client.bot | Bot（客服/销售/交易/自定义）CRUD、启停、统计 | Gateway | | client.agents | Agent 列表/详情/能力声明/对话/构造交易 | Gateway | | client.knowledge | 知识文档 CRUD、推荐 | Gateway | | client.channel | 渠道（telegram/whatsapp/webwidget）创建与配置 | Gateway | | client.conversation | 对话记录与消息 | Gateway | | client.analytics | 仪表盘数据、Bot 指标、按用户用量汇总（summaryByUser） | Gateway | | client.transaction | 交易意图解析/构造/模拟、协议/合约/calldata 查询 | Gateway | | client.auth | 验证码（getCaptcha）、登录、注册、钱包登录 | Server | | client.agentx | 市场、订阅、监控、Skills、发布 | Server | | client.chat | 服务端对话（含 function calling tools、A2A 编排） | Server | | client.apiKeys | API Key 创建/列表/吊销 | Gateway | | client.lightrag | RAG Key 管理 + 文档 CRUD + 查询（per-user namespace） | Server | | client.orchestration | 对话编排（多 task × 多 agent） | Server | | client.scheduledTasks | 主 agent 定时任务管理 | Server | | client.internal | 企业内 Agent：企业级共享知识库 + 监控连接器/事件（internal bot） | Server | | client.abis | 商户租户合约 ABI 管理：list/add/remove（交易 agent 上传 ABI 后即可按函数构造链上调用） | Server | | client.admin | 平台仪表盘、商户、计费、LLM 设置（需管理员 JWT） | Admin |

按用户地址的 token 用量汇总（0.9.0+）

对账接口：按 userAddress 汇总平台 LLM 调用的 token 用量（日维度 + 累计），用于成本核算与双方对账：

const summary = await client.analytics.summaryByUser('0x...', 7);
// {
//   userAddress: '0x...',
//   days: 7,
//   daily: [{ day: '2026-08-10', tokens_in: '1200', tokens_out: '800', calls: '5' }],
//   totals: { tokensIn: 1200, tokensOut: 800, calls: 5 },
// }

• 对应 HTTP：GET /api/v1/usage/summary?userAddress=<address>&days=<N>（days 默认 7，1~365）
• 口径：仅统计平台 LLM 调用（消耗商户配额的部分）；请求级 llmApiKey 的 BYOK 调用消耗调用方自身 Key，不计入。

多租户隔离（chat / lightrag）

• 会话与记忆隔离：chat.send / agents.chat 传 userAddress，平台按 (tenant, bot, userAddress) 隔离会话与记忆。
• 知识库隔离：lightrag.insertDocument / lightrag.query 传 namespace（per-user）；缺省回退到 botId = 全租户共享，多租户场景必须显式传。
• 完整示例见 examples/cryptchat-multitenant.ts。

Function Calling（工具回调）

chat.send / agents.chat 支持 tools 参数（OpenAI function calling 兼容格式）。平台执行工具时 POST 到 callback_url，回调体 { tool, arguments }，携带 X-AIServicer-Tool + X-Tool-Key 头。

平台不代验签——回调服务必须自行校验 X-Tool-Key（推荐 timingSafeEqual）。15s 超时 / 最多 5 轮循环。示例见 cryptchat-multitenant.ts 的 validateToolCall()。

示例

| 示例 | 说明 | |------|------| | examples/quickstart.ts | 最简上手：API Key 认证 + 列 agent + 对话 | | examples/cryptchat-multitenant.ts | 多租户完整接入：JWT 自动续期 + CAPTCHA + chat.send + LightRAG namespace 隔离 + 回调鉴权 |

环境变量模板

复制 .env.example 为 .env 并按需填写（.env 已被仓库 .gitignore 忽略，不会提交）：

cp .env.example .env

• AISERVICER_* 前缀变量供多租户示例使用（含 API Key / 账号密码 / 项目与 Bot ID / 回调密钥）
• examples/quickstart.ts 使用简写变量：BASE_URL / SERVER_URL / API_KEY

发布流程（维护者）

cd sdk
npm version 0.8.3 --no-git-tag-version   # 小版本递增，紧贴 API 变更
npm run build                            # tsc → dist
npm publish                              # token 在 ~/.npmrc（@aiservicer 组织）
npm dist-tag ls @aiservicer/sdk          # 确认 latest
cd .. && git add sdk/package.json sdk/package-lock.json
git commit -m "chore(sdk): 发布 @aiservicer/[email protected]"

已发布版本：0.8.3（0.8.2 验证码登录 getCaptcha / login / register captcha、orchestration、scheduledTasks；0.8.3 顶层补导出 CaptchaResponse / CaptchaAnswer 类型）。SDK 发布后需同步升级 @aiservicer/mcp-server 的 SDK 依赖并重新发布（见 mcp-server/README.md）。