DEVELOPER DOCS · 官方接入文档

把你的业务系统接进 AI 中枢

这份文档面向业务系统开发者和私有部署方。你可以从一条触发路由开始，也可以进一步暴露工具源、接入知识库、配置审批与审计，让 Agent 在可控边界内查数据、办业务。

QUICKSTART

20 分钟跑通第一条闭环

最快体验方式是 Docker Compose。它会启动中枢、MySQL 和 demo 业务系统，并自动创建示例路由、工具源、接入方和后台账号。生产部署请使用环境变量或密钥管理器注入敏感项，不要把真实密钥写进配置文件。

bailing-ai
$ docker compose up --build

→ Console: http://localhost:18900/console/
→ Demo route: demo_support
→ Demo business tools: /.well-known/bailing/tools.json

全新 Ubuntu/Debian 服务器可以用一键安装脚本快速体验：curl -fsSL https://www.bailinghub.com/install.sh | sh。脚本只封装 Docker 安装、开源分发包下载、生成 .env 和 docker compose up -d --build，完整说明见 Docker Demo 文档。

完整 demo 业务系统、审批闭环、故障排障和 smoke 流程见 Docker Demo 文档。

1
建模型凭证。在控制台「模型凭证」填 OpenAI 兼容端点与 key。配置完成后，内置 cloud-llm 调度目标即可使用。
2
建触发路由。在「触发路由」定义业务场景、调度目标、会话策略、知识、工具、送达和预算。
3
发接入方钥匙。在「接入方」创建业务系统 token，并限定它能触发哪些路由。
4
触发任务。业务系统调用 POST /run，拿到 job_id 后轮询 GET /jobs/{job_id}，或配置 callback / delivery 接收结果。
MENTAL MODEL

先理解五个对象

路由

一个业务场景。它决定请求进来后用哪个大脑、怎么续聊、注入哪些知识、允许哪些工具、结果送往哪里。

接入方

一个业务系统的钥匙。中枢用它做鉴权、路由白名单、限速与预算约束。

调度目标

一个可被路由选择的大脑插座。可以是内置 LLM，也可以是远端 executor 或后续更多适配器。

工具源

业务系统暴露给 AI 的可调接口清单。中枢把它编译成统一 ToolDefinition，再套治理闸门。

SDK

业务侧生成工具 spec、验签、验 callback 和实现授权探针的接入包。PHP / PHP7 / Node / Python 使用同一套契约。

知识库

领域资料的检索入口。路由选择知识库后，中枢在派发前检索并注入上下文。

对话总账

中枢自己的状态库。消息、trace、审计、审批和任务记录都在这里，Agent 会话只是可重建缓存。

ROUTES

触发路由：把一个业务场景配完整

后台「触发路由」页负责定义 AI 任务的编排规则。业务侧只需要传一个稳定的 route，中枢负责选择目标、装配上下文、执行工具治理、记录 trace，并把结果回送。

基础与大脑

配置场景标识、展示名称、调度目标、模型凭证、系统提示词和预算。场景标识是业务调用时的稳定路由 key。

知识

选择知识库和检索参数。知识故障按降级处理，不阻断任务主流程。

送达

结果可通过轮询、callback webhook 或送达适配器返回业务侧。callback 建议开启 HMAC 验签。

工具治理

路由只暴露被 allow 白名单命中的工具 scope。高风险工具进入审批，批准后只放行对应调用快照。

字段说明建议
route业务调用使用的场景标识。用稳定、短小、可读的英文名，例如 order_assistant。
target调度目标。默认可使用 cloud-llm。先用内置 LLM 跑通，再按需接远端 executor。
session_policy会话策略：新会话、按业务 key 续聊、固定会话。客服、订单跟进等多轮场景使用按 key 续聊。
knowledge路由级知识检索配置。只给需要资料增强的路由开启，避免无意义成本。
tools路由可见的工具源和 scope 白名单。按最小权限开放，先只开放只读查询工具。
HTTP API

业务系统与中枢的接口契约

详细字段说明、回调载荷和机器可读 schema 已拆到 API 契约 子页。这里保留最小调用形状，方便第一次接入快速定位。

业务系统只通过稳定 HTTP 契约和中枢对话。不要 import 中枢代码，也不要让中枢直接依赖业务库结构。

POST/run
{
  "request_id": "order-10001-ai-001",
  "route": "order_assistant",
  "input": "帮我分析这个订单为什么迟迟未发货",
  "metadata": {
    "tenant_id": "t_100",
    "operator_uid": "u_42",
    "order_id": "SO20260701001"
  },
  "callback": "https://biz.example.com/ai/callback"
}
GET/jobs/{job_id}
{
  "id": "job_...",
  "status": "queued | running | done | error",
  "result": { "summary": "...", "detail": {} },
  "error": null
}
POST业务侧 callback URL
X-Bailing-Signature: sha256=<hmac>
X-Bailing-Timestamp: 1782912000

{
  "job_id": "job_...",
  "route": "order_assistant",
  "status": "done",
  "result": { "summary": "..." }
}

调用方鉴权使用接入方 token。callback / delivery 的验签密钥由路由或接入方配置提供，业务侧必须先验签再消费结果。

约束说明
request_id业务侧幂等键。同一接入方下重复提交同一个 request_id 不应产生重复任务。
metadata业务上下文，只消费对象形态。不要把 JSON 字符串塞进 detail / metadata，避免不同语言二次解析不一致。
callback适合 fire-and-forget 场景。需要强一致展示时，业务侧仍应按 job_id 做兜底查询。
TOOLS

工具源：让 AI 安全调用业务接口

工具源完整接入、OpenAPI 扩展字段、SDK 与验签说明已拆到 工具源文档 子页。

工具源不是把所有接口丢给大模型，而是把业务明确允许的接口声明成 ToolDefinition。中枢统一做白名单、风险、限流、审计、审批和签名出口，业务侧继续负责最终权限裁决。

OpenAPI + x-ai

业务系统发布 OpenAPI，并用 x-ai-* 或 SDK 注解声明 scope、risk、subject、description、参数语义等治理信息。

SDK 方式

PHP / PHP7 / Node / Python SDK 都能生成同一份工具 spec，并提供工具调用验签、callback 验签和授权探针 helper。

自动刷新

工具源可以配置 spec URL。业务新增接口后，发布新的 tools.json，中枢刷新后自动对账并审计变化。

业务授权

中枢负责 reach，业务负责 authority。工具请求带 X-Bailing-On-Behalf-Of，业务按自家权限表裁决。

最小 tools.json 形状

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

业务侧验签与授权

POST业务工具接口
X-Bailing-Signature: sha256=<hmac>
X-Bailing-Timestamp: 1782912000
X-Bailing-Tool: order.get
X-Bailing-Job-Id: job_...
X-Bailing-On-Behalf-Of: u_42

不要只验签就放行。验签只能证明请求来自中枢，不能证明这个用户此刻有权限操作这条业务数据。业务系统必须用 on_behalf_of 进入自己的权限表做二次裁决。

SDK 与任意语言接入

PHP 8+ / PHP 7.3+

PHP 8+ 使用注解声明工具；PHP 7.3+ 使用 builder 声明工具。两者都提供 spec 生成、验签、callback 验签和授权探针。

Node / Python

Node 包名 @bailing-ai/connect，Python 包名 bailing-connect。两者都提供 spec 构建、验签和 authorize 探针 helper。

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

完整 SDK 用法见 SDK 文档。其他语言不需要等待 SDK：只要能发布 OpenAPI + x-ai-* 扩展，并实现 HMAC 验签，就能作为工具源接入。

KNOWLEDGE

知识库：把业务资料注入路由

知识库入库、查询和删除接口已拆到 知识库文档 子页。

知识库用于把文档、FAQ、制度、商品资料等变成可检索上下文。业务侧可以通过推送 API 同步资料，也可以在后台配置数据源连接器拉取。

PUT/kb/{kb_id}/docs/{source_key}
{
  "title": "售后退款规则",
  "content": "markdown 或纯文本内容",
  "metadata": {
    "tenant_id": "t_100",
    "source": "help-center"
  }
}
GET/kb/{kb_id}/docs
{
  "items": [
    { "source_key": "refund-rule", "status": "ready", "chunk_count": 8 }
  ]
}
DELETE/kb/{kb_id}/docs/{source_key}
{ "ok": true }

知识库 token 仍然来自接入方。建议每个业务系统只拿自己需要的知识库权限，路由再决定是否检索注入。

APPROVALS

审批意图：高风险动作交给业务侧裁决

审批意图投递、业务侧裁决和 args_hash 快照约束已拆到 审批意图文档 子页。

审批不是必须发生在中枢后台。中枢负责暂停高风险工具调用、固化参数快照、生成审批意图，并接收业务侧的批准或驳回决策。业务侧负责谁能审、在哪审、走几级审。

POST业务侧审批意图接收 URL
{
  "kind": "tool_approval_request",
  "approval_id": 123,
  "job_id": "job_...",
  "route": "store_ops",
  "subject": "tenant_1:user_1001",
  "provider": "demo-business",
  "tool": "inventory.adjust",
  "scope": "store.inventory.write",
  "risk": "high",
  "args": { "store_id": 8, "sku_id": 10086, "delta": -20 },
  "args_hash": "sha256:..."
}
POST/approvals/{approval_id}/decision
{
  "kind": "tool_approval_decision",
  "schema_version": "bailing.approval-decision.v1",
  "approval_id": 123,
  "job_id": "job_...",
  "args_hash": "sha256:...",
  "decision_id": "oa:approval:9001",
  "decision": "approved",
  "approver": "user_2002",
  "comment": "确认处理"
}

批准时必须回传 args_hash。中枢只放行已冻结的同一份调用快照，业务侧审批期间如果参数被改动，本次批准不应生效。

SECURITY

安全边界

中枢管 reach

哪些工具能被 AI 看见、哪些路由能调用、频率和预算是多少，由中枢统一治理。

业务管 authority

某个用户能不能操作某条数据，由业务系统按自己的权限、租户、状态机做最终裁决。

审批不绑定中枢后台

高风险动作会形成审批意图。生产环境可以把审批交给业务侧流程，中枢控制台只是兜底车道。

trace 一等公民

任务、工具调用、审批、模型调用、送达都进入统一 trace，方便调试和审计。

OPERATIONS

部署与运维

生产部署、密钥注入、集中限速、DB 调度和观测检查清单已拆到 部署运维文档 子页。

生产环境推荐 Node 22 + MySQL，敏感配置通过环境变量或密钥管理器注入。MySQL 后端启用集中限速、任务账本、审计、审批意图、知识库和控制台配置。

生产配置

设置 BAILING_ENV=production，按 .env.example 注入数据库、服务 token、模型凭证、告警与对象存储配置。

数据库结构

执行 npm run db:init 初始化和同步结构。SQL 文件按序号演进，结构版本可在 /version 查看。

控制台账号

执行 npm run admin:create -- admin 创建后台账号，登录 /console/ 做路由、凭证、接入方、工具源配置。

健康检查

GET /health 返回服务状态，GET /version 返回应用版本、契约版本与数据库结构版本。

控制台配置，官网读文档

后台页面里的「开发文档」入口会跳转到本页对应章节。控制台负责配置和调试，官网负责完整说明和接口阅读。

看触发路由 看工具源 看知识库