libredesk（crm-new/libredesk）
位于 /home/dev/code/crm-new/libredesk 的 LibreDesk 版 CRM 客服栈，与旧项目 /home/dev/code/crm/crm-ai-demo 完全隔离（独立目录、独立 git、独立 Postgres/Redis、独立端口）。
- 定位：验证「LibreDesk 作为客服平台 + 内置 AI Assistant + 外部业务工具」能否替代现有 Chatwoot + bridge 架构。
- 当前阶段：POC 骨架（可启动、工具服务可跑、含单元测试），尚未接入真实 widget 和生产数据。
- 旧系统不受影响：
crm-ai-demo仍在 3000/3001/4000 端口运行。
当前状态（2026-10-21）
| 项 | 状态 |
|---|---|
| 目录/配置/脚本脚手架 | ✅ 完成 |
| crm-tools 服务（4 工具 + 鉴权 + 验证门控） | ✅ 单测 18/18 通过，本机 :4010 可运行 |
| config.toml 渲染 / compose 校验 | ✅ 通过 |
| LibreDesk 容器 | ✅ 运行中（v2.9.0-rc.10，health 200）；Postgres 18 / Redis 健康 |
| 后台 AI/工具/助手配置 | ⏳ 登录 http://localhost:9000 后按 docs/libredesk-setup.md 执行 |
当前运行 v2.9.0-rc.10：渠道已包含
email / livechat / whatsapp，WhatsApp 表已迁移完成。 RC 属于预发布版本，功能可用但生产使用前需评估稳定性（回滚方法见「镜像拉取」）。
架构
访客 ──► LibreDesk Live Chat Widget (:9000)
│
▼
LibreDesk AI Assistant ──HTTP tool calls──► crm-tools (:4010)
（snippets 向量检索 / 内置 OTP 验证） │
├──► 商品推荐 RPC (recommend)
├──► 订单 RPC (trading-service)
├──► 库存/ETA RPC (eta-service)
└──► Twenty CRM GraphQL (商机/备注/任务)
关键设计：业务数据与身份验证不放进 LibreDesk 代码里，而是通过它的自定义 HTTP 工具回调 crm-tools；工具服务二次校验 X-Libredesk-Contact-Verified，不信任模型参数里的邮箱。
目录
crm-new/libredesk/
├── docker-compose.yml # LibreDesk + 独立 Postgres(5433) + Redis(6380)
├── .env.example # 环境变量模板（bootstrap 自动生成 .env）
├── config/
│ └── config.toml.example # LibreDesk 配置模板（渲染成 config.toml，不入库）
├── scripts/
│ ├── bootstrap.sh # 生成密钥 + 渲染配置 + 启动 LibreDesk
│ ├── start-tools.sh # 宿主机启动 tools 服务
│ ├── render-config.js # config.toml 渲染
│ ├── register-tools.js # 把工具注册进 LibreDesk（可选）
│ └── smoke.sh # 冒烟测试
├── services/tools/ # 业务工具服务（Node 20+，零外部依赖）
│ ├── src/
│ │ ├── server.js # HTTP 入口 + 鉴权 + 验证门控
│ │ ├── tools.js # 4 个工具：商品/订单/库存/建商机
│ │ ├── twenty.js # Twenty GraphQL 客户端
│ │ ├── rpc.js # JSONRPC-TCP 客户端（Hyperf 协议）
│ │ ├── config.js / auth.js / errors.js
│ └── test/ # node:test 单元测试
├── docs/
│ ├── architecture.md # 架构与数据流
│ ├── libredesk-setup.md # 后台配置步骤（AI/工具/助手/自动化/Widget）
│ ├── api-mapping.md # Chatwoot → LibreDesk 接口/事件/字段对照
│ └── migration-plan.md # 6 层拆分、方案 A/B/C、代码存废清单
├── deploy/nginx.conf.example
└── uploads/ # LibreDesk 上传目录（运行时）
快速开始
网络提示：本机可直连 Docker Hub。镜像直接使用
libredesk/libredesk、pgvector/pgvector、redis、twentycrm/twenty；如网络受限可在 Docker daemon 配 registry mirror。详见文末「镜像拉取」一节。
cd /home/dev/code/crm-new/libredesk
# 1) 启动 LibreDesk（自动生成 .env / config.toml，首次拉镜像）
bash scripts/bootstrap.sh
# 2) 另开终端，启动工具服务 :4010
bash scripts/start-tools.sh
# 3) 按 docs/libredesk-setup.md 配置 AI Provider / Inbox
# 然后在 Admin → Teammates → System 生成 API key，填入 .env
# 4) 自动注册 4 个 AI 工具（失败也可按文档手工创建）
node scripts/register-tools.js
# 5) 冒烟
bash scripts/smoke.sh
| 组件 | 地址 | 说明 |
|---|---|---|
| LibreDesk | http://localhost:9000 | System + bootstrap 生成的密码 |
| crm-tools | http://localhost:4010 | /healthz、/tools/manifest、/tools/<name> |
| Postgres | localhost:5433 | 独立实例，库 libredesk |
| Redis | localhost:6380 | 独立实例 |
工具清单
| 工具 | 需要验证 | 作用 |
|---|---|---|
search_products |
否 | 商品关键词搜索（recommend RPC） |
search_orders |
是 | 订单/物流查询，邮箱强制取自已验证身份头 |
search_inventory |
否 | SKU 实时库存 + ETA |
create_opportunity |
是 | Twenty 建商机 + 聊天摘要备注 + 3 天跟进任务，按邮箱去重 |
测试
cd services/tools && npm test
覆盖：地址解析、鉴权 fail-closed、验证门控、邮箱作用域/IDOR 防护、商机去重。
本阶段边界（未做）
- 未接入真实网站 widget（JWT 签发仍是下一步）
- 未做 Chatwoot → LibreDesk 数据迁移（当前旧库仅 2 条会话，可忽略）
- 未接入观测/评估/飞轮（需要时按 docs/migration-plan.md 的 L6 保留 bridge）
- WhatsApp 需 v2.9 预发布版（见 setup 文档最后一节）
镜像拉取
本机可直连 Docker Hub，直接拉取：
docker pull libredesk/libredesk:v2.9.0-rc.10
.env：
LIBREDESK_IMAGE=libredesk/libredesk:v2.9.0-rc.10
回滚到稳定版 v2.8.0
sed -i 's#^LIBREDESK_IMAGE=.*#LIBREDESK_IMAGE=libredesk/libredesk:latest#' .env
docker compose up -d --force-recreate app # 跨版本回退需用备份库，见下
与旧系统的关系
旧栈 crm-ai-demo |
新栈 crm-new/libredesk |
|
|---|---|---|
| 客服平台 | Chatwoot 4.16（Rails） | LibreDesk（Go 单二进制） |
| AI 编排 | bridge 自研 agent loop | LibreDesk AI Assistant（POC 目标） |
| 业务工具 | bridge 内置 | 独立 services/tools |
| 数据 | crm-postgres:5432 | 独立 postgres:5433 |
| 端口 | 3000/3001/4000 | 9000/4010 |
两套可以并行跑，方便同一批问题做 A/B 对比。