# 迁移方案与取舍（2026-10-21 决策记录）

## 结论

**不能把整套实现完全搬进 LibreDesk。** 可以做到的是：

> LibreDesk 承担「渠道 + 客服工作台 + 大部分对话 AI」，原 bridge 从 ~11.7k 行压缩到 ~2–3k 行的业务工具 / 质量服务。

原因是旧系统分 6 层，其中 L5（业务集成）和 L6（质量工程）不在 LibreDesk 的产品边界内；L3/L4 可以迁但会降级。

## 1. 六层拆分

| 层 | 旧实现 | 代码量* | LibreDesk 原生 | 判定 |
|---|---|---|---|---|
| L1 渠道 | Chatwoot | — | Live chat / Email / WhatsApp(rc) | 完全替代 |
| L2 工作台 | Chatwoot | — | SLA/CSAT/宏/自动化/角色/自动分配/报表/审计 | 完全替代 |
| L3 知识库/RAG | pgvector + 向量+全文+RRF+rerank+翻译 | ~1.9k | snippets/帮助文章纯向量检索 | 降级替代 |
| L4 对话编排 | agentRunner/意图/情绪/升级/上下文/引用打分/A-B | ~3.2k | AI assistant + HTTP tools + handoff | 替代 ~70% |
| L5 业务集成 | Twenty + 4 个 RPC + 槽位采集 | ~1.1k | 无（仅通用 HTTP tools） | 必须外挂 |
| L6 质量工程 | eval/飞轮/metrics/告警/注入防护 | ~2.4k | 仅 learn-from-resolved + 报表 | 必须外挂或放弃 |

\* 按旧仓库模块行数估算，非精确切分。

## 2. 三种终态

| 方案 | 架构 | 保留能力 | 工作量 | 风险 |
|---|---|---|---|---|
| **A. 平台换、AI 留 bridge** | LibreDesk L1+L2；bridge 保留 L3–L6，webhook/API 对接 | 全部保留，白得 email/WhatsApp/SLA/CSAT/报表 | 6–8 人日 | 低；webhook 无重试需轮询兜底 |
| **B. 平台 + AI 都换**（本 POC 验证目标） | LibreDesk AI + tools 承担 L3/L4；bridge 缩成 L5（+可选 L6） | 失去 hybrid RAG、情绪/3 级升级、引用审计、A-B、注入防护、评估/飞轮/告警 | 10–14 人日 | 中；AI beta、RAG 降级、质量不可观测 |
| **C. 全内建（fork Go）** | 把 L5/L6 写进 LibreDesk | 理论全保留 | 15–20+ 人日 | 高；AGPL、升级维护 |

**推荐路径：先用本 POC 验证 B 的 L3/L4 是否够用；生产切换走 A，再按数据决定是否把 L4 也迁走。**

## 3. 方案 B 代码存废清单

保留（~3k 行）：
- `crm/twentyClient.js` → 已提炼为 `services/tools/src/twenty.js`
- `agent/toolExecutor.js` 的 RPC 部分 → 已提炼为 `services/tools/src/tools.js`
- 可选：`eval/`、`middleware/alerter`、`faq`/`sitemap` 同步脚本

退役（~8k 行）：
- `agent/agentRunner`、`intentClassifier`、`contextManager`、`llmCache`
- `rag/*`、`prompts/*`、`escalation/*`
- `mail/*`（交 LibreDesk 邮箱）
- `identity/otp*`、router 的交互组件/欢迎语/两个 webhook
- `crm/chatLogger`、`utils/cwClient`、`middleware/auth`（改 LibreDesk 验签）
- `config/experiments`、`security/injectionGuard`（除非保留）

## 4. 分阶段计划

### Phase 0 — POC（本仓库，1–2 天）
- [x] 独立目录 + compose（LibreDesk + 独立 pg/redis）
- [x] crm-tools 服务（4 工具 + 鉴权 + 验证门控 + 单测）
- [x] 配置/注册/冒烟脚本 + 文档
- [ ] 按 `docs/libredesk-setup.md` 配 AI/工具/助手/自动化
- [ ] 20–30 轮真实问题对比：bridge vs LibreDesk AI（质量/工具成功率/延迟/成本）

### Phase 1 — 平台切换（方案 A，4–6 天）
- LibreDesk 接 Live chat + Email（旧 mail 模块退役）
- bridge 改 `libredeskClient`（发消息/备注/状态/历史）
- webhook 改 `X-Libredesk-Signature` + 轮询补偿
- widget JWT 签发替换 `us-site/ai-snippet.js`
- 灰度：一个 inbox 走 LibreDesk，其余保持 Chatwoot

### Phase 2 — AI 迁移（视 Phase 0 结果，4–6 天）
- KB → snippets 批量导入 + 抽检
- 助手 instructions/guardrails/tools 调优
- 情绪/升级/引用/评估：接受降级或保留为独立服务

### Phase 3 — 质量服务（可选）
- 保留 bridge 的 `eval/` + `flywheel_*` + alerter，改成读 LibreDesk 报表/UUID
- 或直接放弃，用平台报表 + `learn from resolved` 代替

## 5. 必须提前接受的损失（方案 B）

1. RAG：hybrid + rerank + 翻译兜底 → 纯向量 top-k
2. 引用/幻觉：citation_score / hallucination_flag / 告警全部缺失
3. 情绪与 3 级升级：只能 max turns + fallback team 近似
4. 逐会话质量指标、A/B 实验、注入防护：无
5. 历史 `agent_metrics.conversation_id` 与新 UUID 不可 join

## 6. 风险清单

| 风险 | 影响 | 缓解 |
|---|---|---|
| AI Assistant 处于 beta | 回复质量不稳定 | 先低流量 inbox，保留人工兜底 |
| WhatsApp 仅 v2.9-rc | 不能直接上生产 | 等 stable 或用方案 A 保留旧桥 |
| webhook 无重试 | 丢事件 | 轮询补偿 + 本地队列 |
| AGPL-3.0 | 修改后对外提供需开源 | 不改源码，工具外置（本方案） |
| 无 Chatwoot 导入器 | 历史数据丢失 | 当前数据量小，接受 |
| RAG 降级 | EU 语种召回下降 | 迁移后用 golden 问题抽检，必要时保留旧 RAG 服务 |
| 单工作区 | 多站点只能多 inbox，联系人共享 | 用 JWT 的 site 属性 + 隐私口径评审 |

## 7. 版本核实（2026-10-26 更新）

- LibreDesk 稳定版：**v2.9.0**（2026-10-22），渠道 `email/livechat/whatsapp`
- 升级前为预发布 **v2.9.0-rc.10**（2026-10-21）；rc.10 → v2.9.0 无 DB migration、无 config 变更
- 本套环境已于 2026-10-26 升到 v2.9.0（升级前 `pg_dump` 备份，回滚只需切回 rc.10 镜像）
- AI Assistant / AI tools / verified contact 为 v2.8 已有能力，标注 beta


---

## 8. 2026-10-21 决策记录

- **选择方案 B**：LibreDesk 内置 AI 回复客户；bridge 收缩为业务工具/集成；Twenty 起全新实例。
- **完全新建**：不迁旧数据、不保留 Chatwoot 兼容层、不复制旧 bridge 代码；旧栈保持只读并存。
- **渠道范围**：Live chat + Email + WhatsApp（后者依赖 v2.9 RC）。
- **业务内容复用**：`customer-service-kb` 知识库与销售规则沿用，迁移为 LibreDesk snippets。
- 已落地：全栈 compose（LibreDesk :9000 / Twenty :3100 / bridge :4100 / PG :5440 / Redis :6390）、4 个 AI tools、注册/冒烟脚本。
- 待补齐：AI Provider、inbox/assistant/automation 配置、Twenty API key、KB 导入、质量旁路。