81 lines
6.1 KiB
Markdown
81 lines
6.1 KiB
Markdown
# Chatwoot → LibreDesk 对照表
|
||
|
||
迁移旧 `bridge` 时按此表逐项替换。字段/事件均已对照 LibreDesk 源码与文档核对（v2.8.0 / v2.9.0）。
|
||
|
||
## 1. HTTP API
|
||
|
||
| 用途 | Chatwoot（旧） | LibreDesk（新） |
|
||
|---|---|---|
|
||
| 鉴权头 | `api_access_token: <token>` | `Authorization: token <key>:<secret>` 或 Basic |
|
||
| 发回复 | `POST /api/v1/accounts/:aid/conversations/:id/messages` `{content, message_type:'outgoing'}` | `POST /api/v1/conversations/{uuid}/messages` `{message:"...", sender_type:"agent"}` |
|
||
| 私密备注 | 同上 + `private:true` | 同上 + `private:true`（可带 `mentions`） |
|
||
| 改会话状态 | `POST .../toggle_status` `{status:'resolved'}` | `PUT /api/v1/conversations/{uuid}/status`（默认状态 Open/Snoozed/Resolved/Closed） |
|
||
| 拉历史消息 | `GET .../conversations/:id/messages` | `GET /api/v1/conversations/{uuid}/messages` |
|
||
| 会话详情 | `GET .../conversations/:id` | `GET /api/v1/conversations/{uuid}` |
|
||
| 联系人查询 | `GET .../contacts/search?q=` | `GET /api/v1/contacts/search` |
|
||
| 联系人详情 | `GET .../contacts/:id` | `GET /api/v1/contacts/{id}` |
|
||
| 新建联系人 | `POST .../contacts` | **无独立端点**：通过 `POST /api/v1/conversations`（带 `contact_email`）或 widget 创建 |
|
||
| 会话 ID | 数字 id | **UUID**（API 路径用 uuid；webhook 同时带 `conversation_id` 与 `conversation_uuid`） |
|
||
| 交互式消息 | `content_type: input_select/input_email/form` + `content_attributes.submitted_values` | **不支持**（只有 message/attachments/private/to/cc/bcc） |
|
||
|
||
## 2. Webhook / 事件
|
||
|
||
| Chatwoot 事件 | LibreDesk 事件 | 字段差异 |
|
||
|---|---|---|
|
||
| `message_created`（incoming） | `message.created` | `type: incoming/outgoing/activity`、`sender_type: contact/agent`、`content`/`text_content`、`conversation_uuid`、`private` |
|
||
| `message_updated`（OTP 表单提交） | `message.updated` | 无 `content_attributes.submitted_values`；OTP 改由平台内置流程 |
|
||
| `conversation_opened` | `conversation.created` | 带 `uuid`/`id`/`contact`/`inbox_channel`/`tags` |
|
||
| `webwidget_triggered` | 无直接对应 | 用 `conversation.created` + contact custom attributes 触发欢迎语 |
|
||
| （无） | `conversation.status_changed` / `assigned` / `unassigned` / `tags_changed` | 新增能力 |
|
||
| 签名头 | `x-chatwoot-signature` + `x-chatwoot-timestamp`，HMAC(ts.body) | `X-Libredesk-Signature: sha256=<hmac(body)>`，**无时间戳**（需自行防重放） |
|
||
| 投递 | AgentBot 推送 | 通用 webhook；**失败不重试、5s 超时、队列满丢弃** |
|
||
|
||
## 3. 身份与 Widget
|
||
|
||
| 能力 | Chatwoot（旧） | LibreDesk（新） |
|
||
|---|---|---|
|
||
| 身份锚定 | `window.$chatwoot.setUser(identifier, payload)` + cookie | `window.LibredeskSettings.userJWT`（HS256，服务端用 inbox secret 签） |
|
||
| 可信邮箱 | contact `custom_attributes.verified_email`（由 `/identity` 写入） | widget JWT 的 `email` + `external_user_id`；工具侧 `X-Libredesk-Contact-Email` |
|
||
| 自定义属性 | `setCustomAttributes({locale, site})` | JWT `contact_custom_attributes` / `PUT /api/v1/contacts/{id}` |
|
||
| 语言 | `window.chatwootSettings.locale` + 自研欢迎语 | widget `language` + assistant Languages；欢迎语可用 assistant expectation message 或 automation `send_reply` |
|
||
| 验证 | 自研 OTP + 交互组件 + `verified_email` | 平台内置 verified contact OTP；工具请求带 `X-Libredesk-Contact-Verified` |
|
||
| 多站点 | contact custom attribute `site` + 多 widget | 多个 livechat inbox，各自 secret/widget；联系人全局共享 |
|
||
| 会话连续性 | `identifier` cookie | JWT `external_user_id` |
|
||
| 主动消息/帮助中心 | 无 | 有（v2.9 rc 起 widget 内帮助中心 + proactive messages） |
|
||
|
||
## 4. bridge 代码改造点（旧仓库）
|
||
|
||
| 文件 | 用途 | 处理 |
|
||
|---|---|---|
|
||
| `bridge/utils/cwClient.js` | Chatwoot API 封装 | 换成 `libredeskClient`（本仓库未新建，POC 用平台 AI，不需要） |
|
||
| `bridge/crm/chatLogger.js` | 发回复/备注/查联系人 | 同上 |
|
||
| `bridge/middleware/auth.js` | HMAC + timestamp 验签 | 换成 `X-Libredesk-Signature`，自行补时间窗/重放缓存 |
|
||
| `bridge/router.js` `/agent-bot`、`/chatwoot-webhook` | 事件分发 | 换成 `/libredesk-webhook`，事件名/字段按上表映射 |
|
||
| `bridge/router.js` 交互组件/OTP | OTP 按钮表单 | 删除；改用平台 verified OTP |
|
||
| `bridge/identity/identityManager.js` | 读 `verified_email` | 改读工具身份头 / 平台验证状态 |
|
||
| `bridge/mail/mailDigest.js` | 往 Chatwoot 建会话投摘要 | 改发邮件或调报表 API |
|
||
| `bridge/register_agent_bot.js` | 注册 AgentBot | 删除；webhook 在 Admin → Integrations 配 |
|
||
| `bridge/escalation/manager.js`、`agent/agentRunner.js` | `toggle_status` | 改 `PUT /conversations/{uuid}/status` |
|
||
| 6 个测试文件 | mock `/api/v1/accounts` | 重写 mock |
|
||
|
||
## 5. 数据模型影响
|
||
|
||
- 旧表 `agent_metrics` / `flywheel_samples` / `trace_steps` 里的 `conversation_id` 是 Chatwoot 数字 id；换平台后新数据用 LibreDesk UUID，**新旧不可直接 join**
|
||
- 建议新表统一存 `conversation_uuid`，`conversation_id` 只做历史字段
|
||
- 旧 Chatwoot 数据无导入器可用（LibreDesk 只有 CSV 导入 agent）；当前旧库仅 2 会话/2 联系人，可直接放弃
|
||
|
||
## 6. 能力缺口（换平台后必须外部实现或放弃）
|
||
|
||
| 能力 | 旧实现 | LibreDesk | 结论 |
|
||
|---|---|---|---|
|
||
| 商机自动创建 | `leadPipeline` + Twenty | 无 | 本仓库 `create_opportunity` 工具 |
|
||
| 订单/库存/商品 RPC | `toolExecutor` | 无（仅通用 HTTP tools） | 本仓库 `crm-tools` |
|
||
| hybrid 检索 + rerank | `rag/retriever.js` | 纯向量 snippets | 降级或保留旧服务 |
|
||
| 引用/幻觉打分 | `citation_checker` | 仅帮助中心 `[[cite]]` | 缺失 |
|
||
| 情绪 + 3 级升级 | `escalation/*` | 仅 handoff | 降级 |
|
||
| 离线评估 | `eval/*` | 无 | 保留旧服务（可选） |
|
||
| 数据飞轮 | `flywheel_*` | `learn from resolved`（弱） | 部分替代 |
|
||
| 指标/告警/追踪 | OTel + Prometheus + alerter | 无 | 保留旧服务（可选） |
|
||
| A/B 实验 | `config/experiments` | 无 | 缺失 |
|
||
| 注入防护 | `security/injectionGuard` | 仅 prompt guardrails | 降级 |
|