6.1 KiB
6.1 KiB
Chatwoot → LibreDesk 对照表
迁移旧 bridge 时按此表逐项替换。字段/事件均已对照 LibreDesk 源码与文档核对（v2.8.0 / v2.9.0-rc）。
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 | 降级 |