把业务 API 声明为 Agent 工具

BailingHub 的工具源不是把整套 OpenAPI 原样交给模型，而是把明确允许的业务动作编译成受治理工具。

最小 OpenAPI + ACC 声明

{
  "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 }
        }
      }
    }
  }
}

没有 enabled: true 的接口默认不进入工具目录。路由还要用精确 scope/operation 白名单做第二次裁剪。

工具目录读取策略

URL 工具源必须显式选择：

策略	使用条件
`signed_required`	默认。中枢签名读取 spec，并对未签名/错误签名做负向探测
`public_allowed`	管理员明确接受任何能访问 URL 的人看到路径、参数和治理声明

工具目录公开不等于工具调用公开。所有真实工具调用仍需验签、可信主体和业务最终授权。受保护的 spec 响应应返回 Cache-Control: private, no-store；两种策略都不跟随 3xx。

工具调用的两道闸

中枢管 reach：路由白名单、风险、审批、限流、幂等、签名出口与审计。
业务管 authority：验签后按 X-Bailing-On-Behalf-Of、租户、资源归属和实时状态判断是否执行。

签名只证明请求来自中枢，不能证明该主体此刻有权修改这条数据。

从业务动作而不是 CRUD 开始

形态	示例	建议
查询	`order.get`、`staff.search`	只读、低风险
预检	`refund.preview`	返回影响，不产生副作用
申请/草稿	`refund.request.create`	交给业务流程继续处理
真实执行	`refund.execute`	高风险或按参数审批
批量执行	`price.batch.update`	精确 operation 白名单和更严格审批

不要用提示词代替 scope、风险或权限规则。字段级定义见 ACC 和 v0.9.0 工具模型文档。