# bridge-tools

LibreDesk 的**业务工具服务**（从 `crm-new/bridge` 裁剪）：只保留 AI 助手需要的 4 个 HTTP 工具，
其余能力（AI 编排、RAG/知识库、OTP 验证、转人工、身份签发、质量飞轮）全部由 LibreDesk v2.9.1 内置实现。

## 工具

| 工具 | 需要验证 | 作用 |
| --- | --- | --- |
| `search_products` | 否 | 商品搜索（价格/库存/图片/product_id/URL），catalog 失败时退回 autocomplete 和站点地图类目链接 |
| `search_orders` | **是** | 订单列表/详情（状态、商品、金额、地址、物流）；邮箱只取 LibreDesk 身份头 |
| `search_inventory` | 否 | 实时库存 + 预购 ETA |
| `get_customer_info` | **是** | 会员资料（等级、积分、余额、注册时间等） |

## 接口

- `GET /healthz` — 健康检查（公开）
- `GET /tools/manifest` — 工具清单（`X-Tools-Key`），可用来在 LibreDesk 批量注册
- `POST /tools/<name>` — 执行工具（`X-Tools-Key` + LibreDesk 注入的 `X-Libredesk-*` 身份头）

## 与 LibreDesk 的约定

- LibreDesk 调用自定义工具时会注入身份头：
  `X-Libredesk-Contact-Id` / `-External-Id` / `-Type` / `-Email` / `-Verified`、`X-Libredesk-Conversation-UUID`、`X-Libredesk-Inbox-Id`；
- 邮箱、验证状态一律以这些头为准（不信任模型参数）；
- `search_orders` / `get_customer_info` 在 LibreDesk 侧应设置 `requires_verification=true`，客户验证（内置 OTP）后才会被放行；
- 工具鉴权：在 LibreDesk 的工具 Headers 里配置 `X-Tools-Key`，值等于本服务的 `TOOLS_SHARED_KEY`。

## 本地运行 / 测试

```bash
node --test "test/*.test.js"     # 单测（mock RPC，不需要外部服务）
node src/server.js               # 本机启动（需环境变量，见 .env.example）
```

## 部署

作为服务并入 `../libredesk/docker-compose.yml`（服务名 `bridge-tools`），
与 LibreDesk 同一 Docker 网络，LibreDesk 侧工具 URL 用 `http://bridge-tools:4100/tools/<name>`。