业务侧 SDK

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

0.10.1 声明生成修复

使用 Core v0.10.1 标签内的业务 SDK 与同版 Core 配套验证。生成器现在保留显式 risk: low/medium/high、readonly: false/true、idempotent: false/true，未设置字段继续省略；ACC 规范 1.0.6 与声明 version: 1 不变。独立 MCP / Agent Client SDK 0.8.0、DSH 0.8.0 无需因此换版。

先重建并核对声明差异：原先丢失显式 low 的非只读 POST 可能由 medium 恢复为 low，须由业务负责人确认；GET 显式 readonly=false 且未设 risk 则应为 medium。审批、主体及最终业务授权仍独立生效。不要把所有写操作设为 low，也不要为验收重放业务。

只更新生成器或消费者可能留下另一侧缺陷。直接读取中间工具对象的自定义代码还需接受未设置 risk 的空值。PHP7 保持 PHP 7.3 兼容；PHP8 Attribute 版要求 PHP 8.1+。取得配套包后核对制品与逐文件摘要，再按原流程刷新工具源，保留原调用和审批记录。详见 0.10.1 升级指南。

可选套餐开通

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

支持范围

运行时	能力
PHP 8.1+	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 负责什么

生成可被中枢编译的工具 spec；
验证来自中枢的签名工具调用；
验证任务完成回调；
为网页聊天签发短期业务身份票据；
实现 fail-closed 授权探针；
通过 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.10.1 的 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.10.1 SDK 指南和各语言目录。