BailingHub for Business Operations

BailingHub MCP 服务

0.8.0：支持更大的工具输入，并按需获取知识

无需受小型适配器的限制，即可保存完整页面内容；只读取相关业务指导；并可独立于服务上限选择模型默认值。配套使用 Core 0.10.0 / SDK 0.8.0 / DSH 0.8.0。现有授权、审批和原始操作恢复机制仍然有效；自动继续任务由宿主负责。

变更 · 升级

简体中文 | English

让兼容 MCP 的 AI Agent 通过自然语言请求，经由 BailingHub查询和操作您的 商店、SaaS、CRM、ERP 或其他业务系统。

根据业务系统明确开放的功能，以及此连接允许使用的路由，Agent 可以执行例如以下操作：

• 查找库存少于 10 件的商品，并准备补货建议；
• 更新员工或客户资料；
• 提交退款申请；如果配置的路由要求人工审批，则等待审批。

Agent 不会获得管理员或业务系统凭据。BailingHub 会保留路由边界、审批状态、执行记录和审计轨迹，而下游业务系统仍会做出最终授权决定。

0.5.0 中引入：在同一对话中处理商店和库存

宿主可以让用户提出这样的请求：“检查随行杯的库存；如果有货，将对应的商店商品价格改为 59 并上架。”此 SDK 新增了同一 Hub 中不同系统的原始目标检查、工具搜索前的系统描述，以及由业务系统提供的授权名称。相关操作必须由业务系统开放、商品映射必须经过确认，并且必须遵循原有审批流程。

这些扩展需要使用 Core 0.10.0 + SDK 0.8.0 和兼容的宿主，并且必须位于同一 Hub 和同一管理员审计域内。宿主负责显式选择和持久化作用域；独立 MCP 服务不会因此获得多系统选择界面。

场景、变更和升级步骤

0.4.0 中引入对话存档

当 Agent 客户端宿主启用对话存档后，BailingHub 管理员可以一并查看用户请求、助手展示的回复以及由此产生的业务操作。 例如，管理员可以在一个对话中比较两家分别授权的商店，同时保留每家商店各自的原始执行记录。请使用 BailingHub Core 0.10.0 和能够捕获并同步对话的宿主。存档 API 的最低要求为 Core 0.6.0。

0.4.0 版本引入了此同步 API。它本身不会捕获对话。原生宿主（例如 DSH 插件）负责账户选择和对话界面。独立 MCP 服务保留现有的工具接口。

哪些人应升级，以及从何处开始

你的配置	下一步
你使用具有固定业务路由的 MCP 应用	使用下方的 MCP 配置指南安装此软件包的 0.8.0 版本。现有的 Client Token 和 Agent Session 流程仍保持兼容。
你使用原生 Agent 客户端，例如 DSH	通过该宿主对应的发行版本升级，并遵循其账户选择指南。仅安装此 MCP 命令不会添加多账户对话界面。
你开发 Agent 客户端宿主	安装 [email protected]，使用 Core 0.10.0 以获得完整功能集，并遵循 SDK 指南。

此 SDK 升级无需更改业务 API 声明。现有的读写、审批和调用恢复行为保持不变。对话上传重试会使用相同的事件 ID，且绝不会重复执行业务操作；只有部署中获授权的管理员才能读取合并后的存档。隐藏推理不会包含在内。

此软件包是一个轻量集成适配器。它不内嵌 BailingHub，不授予业务权限，也不取代下游业务系统的最终授权。它同时支持现有的由操作员配置的 Client Token 模式，以及 Agent Session 模式；在该模式下，用户通过系统浏览器批准一个本地 Agent。

它提供的功能

工具	用途
submit_governed_job	将不可信的任务文本提交到一个由操作员配置的 BailingHub 路由
get_governed_job	读取由凭据拥有的任务当前公开状态
wait_for_governed_job	轮询一个任务，最长 60 秒，不会重新提交该任务

Agent Session MCP 路径从七个精简的元工具开始，用于回合引导、能力与参考知识的搜索/读取、受治理的调用/恢复，以及可见的运行完成。随后，BailingHub 会为当前回合返回至多 12 个活跃业务工具；每次替换都会移除先前的活跃工具集，避免模型上下文无限增长。

工具简短描述可能会在开始/搜索结果中包含 description_truncated 和 usage_guidance_available 标志。如需仅查看某个已加载工具的有限使用指南，请在开始回合后调用 search_business_capabilities，并传入 {"tool_name":"the_exact_loaded_name","include_usage_guidance":true}。这是绑定到当前运行、授权和目录版本的只读参考，不会调用业务工具。请保留返回的截断和大小元数据。不支持详情的旧客户端会返回兼容性错误；普通搜索仍保持兼容。

宿主实现者应使用宿主无关的 Agent 客户端 SDK 指南。

路由、BailingHub URL 和凭据均为本地进程配置，绝不会由模型提供为 MCP 工具参数。SDK 宿主可以发布一组固定的可用授权引用，供单个系统内按调用进行选择；宿主会将每个引用解析为其捕获的连接，并保留连接管理权。请参阅授权引用指南。

认证模式

• Agent Session： 运行一次 bailinghub-mcp-server login。CLI 使用随机的本地回环回调和 PKCE，打开系统浏览器，并将获批的会话存储在平台专用的安全凭据存储中。随后 MCP 工具会使用 /agent-api/v1/*，并在本地刷新轮换后的令牌。
• 客户端令牌（兼容模式）： 存在 BAILINGHUB_CLIENT_TOKEN 时，适配器会继续使用 POST /run 和 GET /jobs/{job_id}，与之前完全相同。

这两种模式都不允许模型提供凭据、路由、代行主体或审批结果。Agent Session 会记录经 Hub／业务授权边界批准的身份；下游业务系统仍会做出最终授权决定。

MCP Registry 的 server.json 仅描述兼容的独立 stdio／客户端令牌安装方式，因此该条目仍将 BAILINGHUB_CLIENT_TOKEN 标记为必需项。原生 DSH 插件不使用该 Registry 配置：它将此软件包的 /sdk 子路径作为普通库依赖导入，并通过浏览器建立 Agent Session。请勿根据 Registry 表单为 DSH 插件添加客户端令牌字段。

安全模型

MCP host / model
    |
    | request_id + untrusted input
    v
BailingHub MCP Server
    |
    | fixed route + Client Token or approved Agent Session
    v
BailingHub
    |
    | governed dispatch
    v
Business system
    |
    +-- resolves trusted subject and performs final authorization

适配器有意不接受：

• 代行主体或身份声明；
• 作为工具输入的客户端令牌、管理员令牌或业务系统凭据；
• 审批决定或审批凭证；
• 执行者身份；
• 任意元数据或回调 URL；
• 任意路由。

在兼容的客户端令牌模式下，请使用仅限于为此服务进程配置的单一路由的专用令牌。如果不同 MCP 客户端需要不同的路由边界，请运行单独的服务实例。

安装

先决条件：

• Node.js 20.15 或更高版本；
• 可访问的 BailingHub 部署；
• 一个限定路由的 BailingHub 客户端令牌，或一个已注册且可获批访问所需路由的公共 Agent 客户端。

对于旧版静态任务模式，请配置 MCP 主机以启动：

{
  "mcpServers": {
    "bailinghub": {
      "command": "npx",
      "args": ["-y", "[email protected]"],
      "env": {
        "BAILINGHUB_BASE_URL": "https://hub.example.com",
        "BAILINGHUB_CLIENT_TOKEN": "replace-with-a-route-scoped-client-token",
        "BAILINGHUB_ROUTE": "order_assistant"
      }
    }
  }
}

Agent Session 登录

启动不带客户端令牌的 MCP 主机前，请授权一个已注册的公共 Agent 客户端和一条固定路由：

npm install --global [email protected]

bailinghub-mcp-server login \
  --base-url https://hub.example.com \
  --client-app-id merchant-agent \
  --route order-assistant

bailinghub-mcp-server status
bailinghub-mcp-server logout

登录回调仅绑定到随机的 127.0.0.1 端口，并使用 state 和 PKCE S256。访问令牌和刷新令牌绝不会出现在 CLI 输出中。macOS 使用 Keychain。Linux 和其他 POSIX 平台需要明确选择启用 BAILINGHUB_ALLOW_FILE_CREDENTIAL_STORE=true；此回退方式会拒绝所有者不是当前用户或权限不是 0600 的文件。Windows 使用受当前用户 DPAPI 保护、位于用户 LocalAppData 目录下的文件。如果 Windows PowerShell 或 DPAPI 不可用，Agent Session 会安全失败，不会回退到明文存储。所有受支持的平台仍可使用兼容的客户端令牌模式。

对于本地 BailingHub 进程，可使用本地回环 HTTP：

BAILINGHUB_BASE_URL=http://127.0.0.1:3000

默认情况下会拒绝非本地回环 HTTP。BAILINGHUB_ALLOW_INSECURE_HTTP=true 仅适用于由运营者控制、且 TLS 在其他位置终止的专用网络。请勿在不可信网络中使用此设置。

正确的任务流程

1. 为一项业务请求创建稳定的 request_id。
2. 使用该 ID 和任务文本调用 submit_governed_job。
3. 保留返回的 job_id。
4. 调用 wait_for_governed_job 进行短时间的有界等待，或稍后调用 get_governed_job。
5. 如果必须重试提交，请重复使用完全相同的 request_id 和任务含义。

queued、running 和 dispatched 均为非终态。done、error 和 rejected 为终态。等待超时不代表任务失败，也不得因此重新提交任务。

首次成功与反馈

请将 MCP 集成路径作为规范的起始页面。当 MCP 主机通过由操作员固定的路由提交请求、同一 job_id 达到终态、BailingHub 保留其审批和审计状态，并且 MCP 主机从未收到管理员或业务系统凭据时，即表示首次集成成功。

请通过 BailingHub 独立验证表单报告通过、部分通过或失败，并选择 MCP 跟踪类别。切勿包含令牌、模型密钥、个人信息或生产业务数据。

项目边界

依赖方向是单向的：

bailinghub-mcp-server -> BailingHub public Client API / Agent API
BailingHub may consume ACC declarations
ACC has no dependency on either implementation

请参阅：

• 项目边界
• 威胁模型
• 兼容性契约
• Agent 客户端 SDK
• 生成图像交付
• 隐私
• 安全策略

开发

npm install
npm run verify
npm pack --dry-run

客户端令牌模式使用稳定的 bailing.client-api.v1 接口：

• POST /run
• GET /jobs/{job_id}

Agent 会话模式使用附加的 Agent Auth v1 和 Agent API v1 接口：

• POST /agent-auth/v1/authorizations
• POST /agent-auth/v1/token
• GET /agent-auth/v1/session
• POST /agent-auth/v1/revoke
• GET /agent-api/v1/workspaces
• GET /agent-api/v1/workspaces/{route}/bootstrap
• POST /agent-api/v1/workspaces/{route}/turns
• POST /agent-api/v1/workspaces/{route}/capabilities/search
• POST /agent-api/v1/tool-invocations
• POST /agent-api/v1/tool-invocations/{invocation_id}/resume
• POST /agent-api/v1/runs/{run_id}/complete

主机 SDK 还会使用 Core 0.6.0 起提供的会话审计写入 API。对于新的跨系统模式、系统描述和授权名称，请使用 Core 0.8.0。这些 API 不会作为 MCP/模型工具公开：

• POST /agent-api/v1/conversation-audits
• POST /agent-api/v1/conversation-audits/{conversation_id}/confirm
• POST /agent-api/v1/conversation-audits/{conversation_id}/events

bailinghub-mcp-server/sdk 子路径还提供与主机无关的 Agent 客户端工厂。它负责浏览器登录、具名本地选择器、隔离凭据、令牌刷新以及 Core DTO 映射。在相同的 Hub/客户端/工作区绑定中，只有当 Core 报告相同且可信的 on_behalf_of 时，它才会替换较旧的本地连接；不同的业务身份仍可独立选择。Core 会解析业务授权条目，因此 DSH 等主机适配器不会询问业务 URL，也不负责凭据或 BailingHub HTTP 端点细节。

此适配器不会调用任何管理员、执行器、审批决策、工具代理、配置或直接业务 API。