crm-ai/docs/migration-plan.md

迁移方案与取舍（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 天）

• 独立目录 + compose（LibreDesk + 独立 pg/redis）
• crm-tools 服务（4 工具 + 鉴权 + 验证门控 + 单测）
• 配置/注册/冒烟脚本 + 文档
• 按 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 导入、质量旁路。