SDK · 百灵中枢开发者文档

PHP

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

任意语言

没有官方 SDK 的语言可直接发布 OpenAPI + x-ai-* 扩展，并实现 HMAC 验签与授权探针。

Node.js

@bailing-ai/connect，提供 buildOpenApiSpec、verifyToolCall、verifyCallback 和 authzProbeResponse。

Python

bailing-connect，提供 build_openapi_spec、verify_tool_call、verify_callback 和 authz_probe_response。

安装

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

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

NPM@bailing-ai/connect

npm install @bailing-ai/connect

PIPbailing-connect

pip install bailing-connect

Node 最小工具源

JStools.json

import { buildOpenApiSpec, param, tool } from '@bailing-ai/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 })]
    })
  ]
});

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
工具源 spec	注解 / builder	`buildOpenApiSpec`	`build_openapi_spec`
工具调用验签	`Verify::gate`	`verifyToolCall`	`verify_tool_call`
callback 验签	`Verify::callback`	`verifyCallback`	`verify_callback`
授权探针	`SpecServer::authzProbe`	`authzProbeResponse`	`authz_probe_response`