工具源 · 百灵中枢开发者文档

OpenAPI + ACC

发布 OpenAPI，并用 x-agent-capability 声明 scope、risk、subject、approval、execution 等 Agent 触达边界。

SDK 方式

当前 SDK 覆盖 PHP、Node、Python、Java、Go、.NET，产出同一份工具 spec，并提供验签、票据、callback、授权探针和 HubClient 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-agent-capability": {
          "version": 1,
          "enabled": true,
          "scope": "order.read",
          "risk": { "level": "low" },
          "subject": { "required": true }
        }
      }
    }
  }
}

不要把所有接口直接暴露给 Agent。默认不可见，只把有明确业务边界、scope 和风险定义的接口注册为工具。

接口清单谁能读取

URL 托管的工具源必须显式声明 spec_access_policy，且只有下面两项可配置。这个选项只控制 OpenAPI / tools.json 清单的读取方式，不会放宽任何真实工具调用的验签和业务授权。

策略	适用场景	中枢行为
`signed_required`	默认、推荐。能力清单只对持有工具源密钥的中枢开放。	正确签名读取后，再用未签名和错误签名做两次负向探测；三项都符合预期才更新缓存。
`public_allowed`	管理员明确接受任何能访问该 URL 的人看到路径、参数、scope 与风险声明。	只发未签名请求，不会在公开读取失败后悄悄改用签名。

内联 spec 不通过 URL 拉取，不受这两种 URL 访问策略影响。控制台会分开展示“期望策略”与“最近实测”，配置为签名保护不等于已经验证受保护。

探测状态与错误判定

观测	结论	中枢动作
正确签名返回 2xx 且清单有效；未签名、错误签名都返回 401 / 403 / 404	`protected`	应用新清单。
要求签名保护，但任一负向请求返回 2xx	`public`	策略与实测不匹配，拒绝更新。
正确签名不是 2xx，或负向请求返回 3xx、429、5xx，或超时 / 网络失败	`inconclusive`	无法形成安全结论，拒绝更新。
`public_allowed` 的未签名请求返回 2xx 且清单有效	`public`	按管理员选择应用新清单。

正确签名的主请求必须返回 2xx；404 只有出现在未签名 / 错误签名负向探测时才表示“已拒绝”。任何失败都不覆盖旧缓存，已在运行的 Agent 继续使用上一份有效清单。

拉取边界和缓存安全

直达最终 URL

signed_required 与 public_allowed 都不跟随重定向。spec_url 必须直接指向最终响应；3xx 会被记为无法判定。

有界响应

每个请求最长等待 10 秒，spec 正文上限 5 MiB。超时、超限或 OpenAPI 解析失败都保留旧缓存。

受保护响应禁止缓存

签名保护端点必须返回 Cache-Control: private, no-store，避免代理或 CDN 把一次合法响应变成公开副本。

实测不等于 CDN 证明

protected 证明直连探测符合预期，不能证明所有中间缓存都遵守配置；仍需核对源站、网关与 CDN。

最小接入心智

不需要一开始填满所有字段。最快路径是：选一个后台已有动作，按 ACC 声明成工具，然后在业务接口里验签并按 X-Bailing-On-Behalf-Of 走原有权限表。Agent 不是获得新权限，而是替这个操作主体调用同一套业务动作。

后台已有权限

如果某个用户能在 Web 后台删除员工，Agent 以这个用户主体调用删除员工接口时，也应走同一套权限判断。

中枢负责治理

中枢负责工具白名单、风险闸、签名、限流和审计；业务系统继续判断这个人此刻能不能操作。

ACC 字段怎么用

字段	控制什么	开发者心智
`enabled`	是否暴露给 Agent	位于 `x-agent-capability` 内；不启用就不可见。
`scope`	路由白名单	路由 `allow` 命中后才会进入工具清单。
`risk.level`	Agent 自动触发风险	`low`/`medium` 直接调用并留痕；`high` 进入中枢审批车道。
`approval.required`	强制人工确认	不管风险等级，每次调用前都冻结参数并等待审批。
`approval.when`	参数级确认	例如金额超过阈值、跨租户、敏感字段命中时才审批。
`subject.required`	主体闸	没有可信操作主体时，工具对 Agent 不可见。
`audit.sensitive`	审计脱敏	只记参数键名，不记录敏感参数值。
`execution.readonly`	语义只读	POST 查询接口需要显式声明；GET 默认只读。

风险等级怎么选

查询类

查订单、查员工、查库存：GET 或 execution.readonly:true，风险通常是 low。

业务流程类

创建退款申请、提交删除员工申请：通常是 medium，审批由业务系统自己的流程承接。

直接副作用

立即退款、直接删除员工、改权限、批量外发：通常是 high 或 confirm-required。

按参数升级

小额直接处理、大额审批：用 approval.when 表达阈值，不要把规则藏在提示词里。

先设计 Agent 工具，再贴 ACC 字段

不要把后台 CRUD 原样暴露给 Agent。优先暴露业务门面：查询、预检、申请、草稿；真正执行型接口再进入高风险或确认车道。

工具形态	示例	推荐处理
查询	`order.get`、`staff.search`	`low` / `execution.readonly:true`
预检 / 试算	`refund.preview`、`employee_remove.impact`	`low` 或 `medium`，返回影响摘要
申请 / 草稿	`refund.request.create`、`permission.request.create`	`medium`，业务系统自己的审批流承接
真实执行	`refund.execute`、`employee.delete`	通常 `high` 或 `confirm-required`
批量执行	`coupon.batch_send`、`price.batch_update`	通常 `high`，再用 `confirm-when` 控制数量/金额阈值

POST推荐的业务流程响应

{
  "ok": true,
  "status": "pending_approval",
  "message": "已提交退款申请，等待主管审核。",
  "business_id": "refund_req_1001",
  "url": "https://business.example.com/refunds/refund_req_1001"
}

这不是强制 schema，但建议业务接口用 status 和 message 明确区分“已执行”“已提交申请”“已创建草稿”“失败”。AI 会据此稳定回复用户，trace 排障也更清楚。

行业模板

下面不是强制规范，而是常见系统的起步模板。开发者可以先照这个形态拆工具，再映射到自己的接口。

电商 / 交易

order.get 查询订单；refund.preview 试算退款；refund.request.create 创建申请；refund.execute 真实退款，通常 high 或按金额 confirmWhen。

HR / OA

staff.search 搜索员工；staff_remove.impact 返回删除影响；staff_remove.request.create 提交申请；staff.delete 直接删除，通常确认。

CRM / 客服

customer.search 查客户；followup.create 新增跟进；deal.stage.update 改成交阶段，跨负责人或高金额时参数级确认。

运维 / 财务

deploy.preview 先预检，deploy.request.create 建发布单；payment.request.create 建付款申请，真实付款/作废票据走高风险。

JS三种典型工具

tool({ name: 'order_get', method: 'GET', scope: 'order.read', path: '/api/orders/{id}' })

tool({
  name: 'refund_request_create',
  method: 'POST',
  scope: 'refund.request',
  risk: 'medium',
  path: '/api/refunds/requests'
})

tool({
  name: 'refund_execute',
  method: 'POST',
  scope: 'refund.execute',
  risk: 'medium',
  confirmWhen: [{ param: 'amount', op: '>', value: 500 }]
})

接入调试

在控制台「工具源」里的「工具清单」可以选择工具、填写参数表单并发起真实签名调用。调试结果会展示请求摘要、参与签名的字段、HTTP 状态、响应预览和常见 401/403/404 排障提示。高风险或需审批工具默认阻断，避免接入期误执行写操作。