OpenAPI + x-ai
发布 OpenAPI，并用 x-ai-scope、x-ai-risk、x-ai-requires-subject 等字段声明治理信息。
SDK 方式
PHP / PHP7 / Node / Python SDK 都产出同一份工具 spec，并提供验签和授权探针 helper。
签名出口
中枢调用业务工具时带 HMAC 签名、任务号和操作主体。业务侧必须验签。
业务授权
验签后继续按 X-Bailing-On-Behalf-Of 回到业务权限表裁决。
GET/.well-known/bailing/tools.json
{
"openapi": "3.1.0",
"info": { "title": "订单系统工具", "version": "1.0.0" },
"paths": {
"/orders/{id}": {
"get": {
"operationId": "order.get",
"summary": "查询订单",
"x-ai-scope": "order.read",
"x-ai-risk": "readonly",
"x-ai-requires-subject": true
}
}
}
}不要把所有接口直接暴露给 AI。默认不可见，只把有明确业务边界、scope 和风险定义的接口注册为工具。
接入调试
在控制台「工具源 → 工具清单」可以选择工具、填写参数表单并发起真实签名调用。调试结果会展示请求摘要、参与签名的字段、HTTP 状态、响应预览和常见 401/403/404 排障提示。高风险或需审批工具默认阻断，避免接入期误执行写操作。
相关文档
SDK 文档 · tool-definition.schema.json · tool-spec.schema.json