SDK · 百灵中枢开发者文档

PHP / PHP7

PHP 8+ 可用注解声明工具；PHP 7.3+ 可用 builder 声明工具。两种方式都遵循同一套 spec 与签名契约，并提供 HubClient。

Node.js / Python

提供 spec builder、signTicket、工具调用验签、callback 验签、授权探针和 HubClient。

Java / Go / .NET

面向企业后端的参考 SDK，使用标准库实现票据、验签、工具 spec、授权探针和中枢主动 API 调用。

任意语言

没有官方 SDK 的语言可直接发布 OpenAPI + x-agent-capability ACC 声明，并实现 HMAC 验签与授权探针。

安装

GETPHP SDK 包（自托管实例提供）

curl -O {中枢地址}/connect/bailing-connect-php.tgz
curl -O {中枢地址}/connect/bailing-connect-php7.tgz

NPM@bailinghub/connect

npm install @bailinghub/connect

PIPbailing-connect

pip install bailing-connect

REFJava / Go / .NET

sdk/java
sdk/go
sdk/dotnet

PHP / PHP7 托管受保护或公开 spec

PHP 8+ 与 PHP 7.3+ 的 SpecServer 使用同一组运行时 API。控制台只有 signed_required 和 public_allowed 两项可配置策略：新建 URL 工具源默认选前者；只有业务确认能力清单可以被任何 URL 访问者读取时，才选后者。

PHP裸 PHP：两种模式二选一

use Bailing\Connect\SpecServer;

// 受保护：中枢用工具源 secret 签名拉取；会自动输出 private, no-store。
SpecServer::respond($spec, $toolProviderSecret);

// 显式公开：与上面二选一，并在控制台选 public_allowed。
SpecServer::respondPublic($spec);

PHP框架路由：返回 body 时别丢响应头

// 受保护
[$status, $body] = SpecServer::handle(
    $spec, $toolProviderSecret, $method, $originalPathWithQuery, $requestHeaders
);
$responseHeaders = SpecServer::responseHeaders($toolProviderSecret);
// 发送前把 $responseHeaders 的每一项写入框架响应。

// 显式公开（与上面二选一）
[$status, $body] = SpecServer::handlePublic(
    $spec, $method, $originalPathWithQuery, $requestHeaders
);

旧的 handle(..., null, ...) / respond(..., null, ...) 仍然兼容，但显式 public helper 更能让安全意图留在代码里。使用旧版 PHP SDK 的业务可继续验签；升级后建议重新下载 SDK 包，或至少手动给受保护响应加 Cache-Control: private, no-store。

不使用 PHP SDK：通用 HTTP 约定

任意语言都可以托管 spec。signed_required 端点验证与工具调用相同的 sha256= HMAC；spec 拉取是 GET，body、X-Bailing-On-Behalf-Of 和 X-Bailing-Job-Id 均为空串。

GET/bailing/tools.json

X-Bailing-Timestamp: <unix 秒>
X-Bailing-Signature: sha256=<hex hmac-sha256>

canonical = "<ts>.GET.<path?query>.<sha256hex(empty-body)>.."
signature = "sha256=" + HMAC_SHA256(tool_provider_secret, canonical)

请求	受保护端点	公开端点
正确签名 GET	2xx + 有效 OpenAPI，并返回 `Cache-Control: private, no-store`	2xx + 有效 OpenAPI
未签名 GET	401 优先；403 / 404 也可用于隐藏端点	2xx + 有效 OpenAPI
错误签名 GET	401 优先；403 / 404 也可用于隐藏端点	按公开端点处理

新策略不跟随 3xx，请把 spec_url 直接配成最终 URL。单请求超过 10 秒、正文超过 5 MiB、响应不可解析，或签名保护的两次负向探测无法形成结论时，中枢会拒绝更新并保留旧清单。

Node 最小工具源

JStools.json

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

export default buildOpenApiSpec({
  title: 'CRM 工具源',
  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 })]
    })
  ]
});

三种典型工具

实际接入时不必一次写满所有字段。先从查询、申请、真实执行三类各挑一个代表，跑通验签、授权和 trace。

JSquery / request / execute

tool({
  name: 'order_get',
  method: 'GET',
  path: '/api/orders/{id}',
  description: '查询订单详情',
  scope: 'order.read',
  requiresSubject: true,
  params: [param('id', { in: 'path', required: true, description: '订单 ID' })]
})

tool({
  name: 'refund_request_create',
  method: 'POST',
  path: '/api/refunds/requests',
  description: '创建退款申请',
  scope: 'refund.request',
  risk: 'medium',
  requiresSubject: true,
  whenToUse: '只创建业务审批单，不立即打款',
  returns: '{code:1, data:{request_id,status,message,url}}',
  params: [
    param('order_id', { required: true, description: '订单 ID' }),
    param('amount', { type: 'number', required: true, description: '退款金额，单位元' }),
    param('reason', { required: true, description: '退款原因' })
  ]
})

tool({
  name: 'refund_execute',
  method: 'POST',
  path: '/api/refunds/execute',
  description: '执行退款',
  scope: 'refund.execute',
  risk: 'medium',
  requiresSubject: true,
  confirmWhen: [{ param: 'amount', op: '>', value: 500, label: '超过 500 元退款需人工确认' }],
  params: [
    param('order_id', { required: true, description: '订单 ID' }),
    param('amount', { type: 'number', required: true, description: '退款金额，单位元' })
  ]
})

Python 最小工具源

PYtools.json

from bailing_connect import build_openapi_spec, param, tool

spec = build_openapi_spec(
    title="CRM 工具源",
    version="1.0.0",
    authz_probe={"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})],
        )
    ],
)

验签纪律

SDK 验签只能证明“这次请求来自中枢且未被篡改”。工具接口必须继续使用 X-Bailing-On-Behalf-Of 回到业务权限表做授权裁决。不要把验签成功等同于授权成功。

能力	PHP	Node	Python	Java / Go / .NET
工具源 spec	注解 / builder	`buildOpenApiSpec`	`build_openapi_spec`	`BuildOpenApiSpec`
访客票据	`Ticket::sign`	`signTicket`	`sign_ticket`	`SignTicket`
工具调用验签	`Verify::gate`	`verifyToolCall`	`verify_tool_call`	`VerifyToolCall`
callback 验签	`Verify::callback`	`verifyCallback`	`verify_callback`	`VerifyCallback`
授权探针	`SpecServer::authzProbe`	`authzProbeResponse`	`authz_probe_response`	`AuthzProbeResponse`
主动调中枢	`HubClient`	`HubClient`	`HubClient`	`HubClient`