机器人的商店数据
聊天中的 AI 机器人不仅能依据知识库作答，还能使用商店的实时数据回复：订单到哪了、运单号是多少、商品是否有货、配送费用多少、如何退货。如果您允许，它还能取消未付款的订单，或将退货和更改配送的申请转交给商店。为此，商店通过 MCP（Model Context Protocol）协议连接到机器人：机器人调用商店的工具，商店返回数据。
任何套餐都可以连接商店，而机器人与聊天中的所有 AI 功能一样，需在付费套餐上使用：基于商店数据的回复与普通 AI 回复一样从项目余额中扣费，参见付款。
连接
最简单的方式是使用我们的商店模块。保存设置时，模块会自动启动服务器并将其连接到项目：
| 平台 | 启用位置 |
|---|---|
| WooCommerce | WooCommerce → Settings → OneTrace.ru → AI chat bot: store MCP |
| Magento 2 | Stores → Configuration → OneTrace.ru → AI chat bot: store MCP → Connect to the chat bot |
| 1C-Bitrix | 模块设置 → 站点选项卡 → AI chat bot: store MCP 区块 → Connect to the chat bot |
模块的私密密钥需要“将商店 MCP 服务器连接到 AI 机器人”（chats.manage）权限。密钥创建后无法更改权限：如果模块的密钥没有该权限，请您在 API 密钥中创建一个新密钥，保留原有权限并加上该权限，然后在模块设置中填写该密钥。同一项目的多个站点只需连接一次。
基于 PHP 或 Laravel 的自有商店可使用 PHP 库和 Laravel 包中的现成服务器连接，开发者只需编写工具处理程序。其他任何实现了商店 MCP 约定的服务器都可以手动连接：在**聊天 → 聊天设置 → 机器人 → 商店（MCP）**中填写 https://… 地址、商店签发的访问密钥和名称。描述工具、错误和客户验证的约定见开发者指南部分。
在**商店（MCP）**部分可以看到服务器是否正常运行，以及商店允许机器人使用哪些工具。开关可暂时停用服务器，刷新按钮会重新检查服务器并重新读取工具（平台每天也会自动执行一次）。
机器人能做什么
具体允许机器人做什么，由商店在模块设置中决定。默认只启用只读工具：
| 工具 | 机器人的作用 |
|---|---|
| 客户的订单、订单 | 查找客户的订单并介绍订单详情：商品、金额、付款、配送方式、地址 |
| 物流跟踪 | 告知快递公司和运单号，并提供跟踪链接 |
| 库存和价格 | 按名称或货号查找商品，告知是否有货以及有哪些规格 |
| 配送 | 列出配送方式及其价格和免运费门槛 |
| 退货条款 | 转述商店的退货条款 |
在商店允许之前，操作均处于关闭状态：
| 操作 | 结果 |
|---|---|
| 取消订单 | 机器人取消尚未付款且尚未发货的订单 |
| 退货申请 | 申请发送给商店：作为订单备注，并通过邮件通知员工 |
| 更改配送 | 关于新地址、日期或时间的申请以同样方式发送给商店 |
工具面向模型的描述由平台而非商店设定，机器人将商店的响应视为数据而非指令。如果机器人的回复中出现商店数据里没有的价格、期限或承诺，回复检查会阻止它发给客户。
客户验证
订单及相关操作仅对已验证的客户开放：机器人不会显示他人的订单，甚至不会确认该订单是否存在。验证客户有两种方式：
- 网站登录。 如果客户已登录商店账户，模块会向聊天小部件传递签名令牌，机器人立即就知道是谁在发消息。
- 验证码。 在即时通讯工具中以及对于访客，机器人会询问客户在商店中使用的邮箱，商店向该邮箱发送 6 位验证码，客户在聊天中输入验证码。验证码有效期为 10 分钟，每个地址每小时最多发送 5 个验证码。
验证有效期为 24 小时。客服可在会话窗口中看到验证状态：“客户已确认：已登录网站”或“客户已通过验证码确认”。客户令牌以加密方式保存在会话中，模型和客服都看不到。
商店中的操作
机器人仅在客户明确同意后才执行操作：
- 机器人说明将要执行的操作（订单号、商品），并请求确认。
- 客户在聊天中表示同意，例如“好的，取消吧”。
- 独立的评分模型会检查客户同意的确实是这项操作。提问、犹豫或其他请求都不算同意。
- 商店执行操作；重复调用同一操作不会重复执行。
聊天记录中会出现一行带结果的“机器人已在商店执行：…”，项目的审计日志中会出现“机器人在商店中的操作”记录。客服的草稿只以只读方式使用商店数据：操作由客服本人在商店中完成。
开发者指南
只要实现了商店 MCP 约定第 1 版，您自己的服务器即可连接。PHP 和 Laravel 已实现该约定：PHP 库中的 StoreMcp\Server 类和 Laravel 包中的 POST /onetrace/mcp 路由，您只需编写工具处理程序。
传输。 MCP Streamable HTTP，协议版本 2025-06-18：单一地址，使用 JSON-RPC 2.0 的 POST 请求，响应为 JSON 或只含一个响应的 text/event-stream 流。地址只能是公网 IP 上的 https://，不允许重定向。响应时间不超过 10 秒，大小不超过 256 KB。平台会调用 initialize、notifications/initialized、tools/list 和 tools/call；支持 Mcp-Session-Id 请求头，但不是必需的。
访问。 每个请求都带有 Authorization: Bearer <密钥>；密钥由商店创建，至少 32 个随机字符。没有密钥或密钥不匹配的请求返回 401。
约定标记。 服务器在 initialize 的响应中声明 capabilities.experimental["onetrace/store"] = { "version": 1 }，没有该标记的服务器无法连接。
工具。 名称必须与表中完全一致，tools/list 只返回所有者允许的工具。每个工具都带有注解 readOnlyHint: true（读取）或 destructiveHint: true（操作），以及 _meta["onetrace/auth"]：customer 表示需要已验证的客户，none 表示不需要。结果为 structuredContent，并在 content[0].text 中以文本形式提供同样的 JSON。金额格式为 { "amount": 1250.5, "currency": "RUB" }，日期为 ISO 8601。
| 工具 | 访问 | 输入 | 结果 |
|---|---|---|---|
store_start_verification |
none | contact、order |
sent、channel、destination |
store_verify |
none | contact、code |
customer_token、expires_at |
store_get_customer |
customer | — | id、email、phone、first_name |
store_find_orders |
customer | status、limit（最多 20） |
orders：order、created_at、status、status_label、total、items_count |
store_get_order |
customer | order |
订单，含 items、total、payment、shipping、can_cancel、can_return |
store_get_tracking |
customer | order |
carrier、tracking_number、tracking_url、status、events |
store_check_availability |
none | query、sku 或 product_id |
products（最多 10 个），含 in_stock、quantity、variants |
store_get_delivery_options |
none | country、city、postcode、total |
methods：name、price、free_from、min_days、max_days |
store_get_return_policy |
none | — | days、conditions、text、url |
store_cancel_order |
customer | order、reason |
order、status、message |
store_create_return |
customer | order、items、reason |
return_id、status、instructions |
store_change_delivery |
customer | order、address、date、time_window |
order、message |
订单状态为以下之一：pending、processing、on_hold、shipped、delivered、completed、cancelled、refunded、failed。请求其他客户的订单时返回 not_found，如同订单不存在。
客户。 customer_token 由商店签发和校验，有效期不超过 24 小时。验证码由商店自行发送，无论该客户是否存在，响应都相同；验证码为 6 位数字，有效期 10 分钟，最多尝试 5 次，每个地址每小时最多 5 个验证码。对于已登录的客户，页面会将令牌传给跟踪器：cdp.chatCustomer('…')。
调用上下文位于 params._meta：onetrace/customer_token、onetrace/language（会话语言）、onetrace/conversation，操作类工具还带有 onetrace/confirmed: true 和 onetrace/idempotency_key。服务器拒绝没有 onetrace/confirmed 的操作；使用相同幂等键的重复调用返回相同结果，不会再次执行操作。
错误格式为 isError: true 和 structuredContent: { "error": "<代码>", "message": "<给客户的文本>" }：
| 代码 | 何时返回 |
|---|---|
auth_required |
需要已验证的客户 |
invalid_code |
验证码错误或已过期 |
not_found |
没有该订单或商品 |
not_allowed |
当前状态下无法执行该操作，或所有者已关闭该操作 |
invalid_input |
参数无效 |
rate_limited |
请求或验证码过多 |
unavailable |
商店暂时故障 |
从模块连接。 模块使用具有 chats.manage 权限的私密密钥注册自己的服务器：带 url、key、name、platform 的 PUT /api/v1/chat/store-mcp 用于连接或更新服务器，带 url 的 DELETE /api/v1/chat/store-mcp 用于断开连接。