业务侧 SDK

业务侧 SDK 是接入便利层，不是新的授权系统。稳定边界仍是 OpenAPI + x-agent-capability + HMAC + 业务最终授权。

可选套餐开通

Node UsageIssuerClient 与 PHP7 UsageClient 提供 listBillingPlans、grantBillingPlan、controlBillingPlan 和 getBillingSummary，使用独立服务端 issuer 凭据与 /usage/v1/external/billing/。Node 的类型入口为 @bailinghub/connect/usage。套餐开通保留原请求键、原参数和修订，不自动重试。具体职责、客户额度展示与套餐范围身份见模型服务与套餐计费。

支持范围

运行时	能力
PHP 8+	Attribute 工具声明、SpecServer、验签、票据、HubClient
PHP 7.3+	Builder 工具声明，与 PHP 8 SDK 保持同一 wire 契约
Node.js / Python	spec builder、票据、工具与 callback 验签、授权探针、HubClient
Java 11+ / Go 1.21+ / .NET 8+	基于标准库的企业后端参考 SDK
其他语言	直接实现 OpenAPI/ACC、HMAC 和授权探针即可接入

SDK 负责什么

1. 生成可被中枢编译的工具 spec；
2. 验证来自中枢的签名工具调用；
3. 验证任务完成回调；
4. 为网页聊天签发短期业务身份票据；
5. 实现 fail-closed 授权探针；
6. 通过 HubClient 调用 /run 和 /jobs/{id}。

Node 示例

import { buildOpenApiSpec, param, tool } from '@bailinghub/connect';

const spec = buildOpenApiSpec({
  title: 'CRM Tools',
  version: '1.0.0',
  authzProbe: { method: 'POST', path: '/.well-known/bailing/authz-probe' },
  tools: [
    tool({
      name: 'member_query',
      method: 'GET',
      path: '/api/members/{id}',
      description: '查询会员资料',
      scope: 'member.read',
      requiresSubject: true,
      params: [param('id', { in: 'path', required: true })],
    }),
  ],
});

业务接口验签成功后仍要调用自己的权限服务；不要把 authorize 写成恒真回调。

授权主体名称与生命周期

业务侧可以在可信的授权确认流程中提供 subject_display.name。从已登录主体对应的业务记录读取名称；不要接收客户端任意填写的值作为真实身份。它只是展示信息，可以表示组织、账户、项目或门店，不参与授权匹配。

Core 0.9.0 的 PHP/PHP 7 helper 配套支持本接入方的授权与会话查询、撤销、主体名同步。旧授权可更新名称，不需要更换原 Agent Session。使用其他语言时可按相同 HTTP 契约接入；具体方法以各语言 SDK 为准，不能假设所有 helper 都已提供同一方法。

参阅 Agent Auth 接口和升级说明。

两套 SDK 不要混淆

• 业务侧 SDK 位于 Core 的 sdk/*，运行在业务后端，负责声明与验签。
• Agent Client SDK / MCP Server 是独立包 bailinghub-mcp-server，运行在本地 Agent 一侧，负责浏览器授权、多连接和治理工具调用。

完整语言示例见 v0.9.0 SDK 指南 和各语言目录。