工作区 (Workspaces)

工作区 (Workspace) 是你作为服务商 (SP / 合作方) 拥有的一个计费与成员边界。 client.workspaces 把已发布的工作区接口（/api/v2/workspaces/*）原样封装成 SDK 方法：开通成员、为成员签发会话、发放积分、读取用量报表。一个工作区由它的 slug 标识。

这是服务端到服务端的集成能力，面向用自己的产品承载 OpenHex 能力的合作方。它和应用内的「工作区切换」界面是两回事。

鉴权与权限

所有方法都用客户端配置的 Bearer 令牌鉴权。你传哪种令牌，决定了能调用哪些方法：

令牌	解锁的能力
工作区 API Key（sk_ws_…）	whoami、开通 / 停用成员、签发会话、列出成员、发放积分
工作区所有者 JWT	以上全部，外加报表（ledger / insights / 成员账本）与 API Key 管理
无	公开的短信注册接口（sendSmsCode / verifySmsCode）

import { OpenhexClient } from '@openhex/agent-sdk';

// 合作方后端用工作区 API Key 鉴权
const client = new OpenhexClient({ apiKey: 'sk_ws_...' });

slug 绑定句柄

大多数方法的第一个参数都是 slug。用 client.workspace(slug) 拿一个绑定好的句柄，就不必每次重复传：

const me = await client.workspaces.whoami(); // 确认 key 属于哪个工作区
const ws = client.workspace(me.slug);        // 之后调用都省去 slug 参数

下文示例都基于这个 ws 句柄；每个方法也都有等价的 client.workspaces.<方法>(slug, …) 形式。

确认身份：whoami

新合作方往往只拿到一个 sk_ws_… 令牌，却还不知道对应的 slug。whoami 一次性返回工作区身份：

const me = await client.workspaces.whoami();
// → { workspace_id, slug, display_name, status, api_key_id }

成员

开通（或查找）成员

按你自己的用户引用 sp_user_ref 幂等开通成员：首次调用创建成员并返回 created: true，再次调用返回既有 id（created: false）：

const member = await ws.provisionMember({
  sp_user_ref: 'user-42',
  display_name: 'Ada', // 可选
});
// → { member_id, billing_account_id, created }

列出成员

const { members } = await ws.listMembers();
// 每个成员含 user_id、sp_user_ref、status、joined_at、balance（当前积分余额）

停用成员

软停用，把状态置为 suspended（幂等）：

await ws.suspendMember(member.member_id);

积分

从工作区积分池给成员发放积分。idempotency_key 保证幂等——重复请求会返回首次的发放结果，不会重复扣减：

const grant = await ws.grantCredits(member.member_id, {
  amount: 500,
  idempotency_key: `signup-bonus:${member.member_id}`,
});
// → { balance, purchase_id, idempotent }

会话

为已开通的成员签发一个会话 JWT。你的服务在自己这边完成对人的认证后，用同一个 sp_user_ref 调用本接口，拿到的令牌交给成员的客户端（网页 / 小程序 / 原生端）向平台出示：

const session = await ws.mintSession({
  sp_user_ref: 'user-42',
  ttl_seconds: 3600, // 可选，最长 86400
});
// → { token, user_id, expires_at }

报表（需所有者 JWT）

以下读取接口需要所有者 JWT：

const owner = new OpenhexClient({ apiKey: ownerJwt, loginType: 'phone' });
const ws = owner.workspace('acme');

const { entries } = await ws.ledger();        // 本工作区内所有者发放的积分记录（最近 100 条）
const insights = await ws.insights();          // 近 30 天：每日消耗趋势 + Top 成员 + Top Agent
const memberLog = await ws.memberLedger(memberId); // 单个成员的账本：发放入账、Agent 运行扣减

API Key 管理（需所有者 JWT）

const { keys } = await ws.listApiKeys();        // 仅元数据，绝不返回明文
const issued = await ws.issueApiKey({ label: 'ci' });
// ⚠️ issued.token 是明文，只在此处出现一次——务必当场保存，事后无法找回
await ws.revokeApiKey(issued.id);               // 软吊销（幂等）

⚠️ 新签发的 API Key 明文只返回一次。 响应里的 token 之后无法再取回，请在拿到的当下安全保存。

公开短信注册（无需鉴权）

供工作区开启了公开短信注册时使用。注意：客户端仍需带一个令牌占位（接口本身忽略它）：

const pub = new OpenhexClient({ apiKey: 'unused' }); // 这些接口忽略令牌

await pub.workspaces.sendSmsCode('acme', { phone: '13800000000' });
const session = await pub.workspaces.verifySmsCode('acme', {
  phone: '13800000000',
  code: '123456',
});
// 验证通过即返回一个成员会话 JWT

不在 SDK 内的接口

工作区生命周期 CRUD（创建 / 列出 / 查看 / 修改工作区本身）是服务商管理后台的职责，不在已发布的 API 内，因此 SDK 也不提供——通过 app.openhex.tech 的管理界面完成即可。

完整 REST 参考

SDK 是这套 REST 接口的薄封装。想看每个端点的请求 / 响应字段、状态码与在线试用，见顶部导航 API → Workspace API 的完整参考。

下一步

• 对话 (Chat) — 让成员通过会话令牌和 Agent 对话
• API 参考 — 客户端配置与错误处理
• Workspace API 参考 — 完整的 REST 端点文档