初始化 LibreDesk 本地实例部署仓库

- docker compose 部署：app / db / redis / tls(nginx) / bridge-tools，宿主端口错开避免与本机服务冲突 - bridge-tools 内联进仓库（compose build 路径改为 ./bridge-tools），仓库自包含可部署 - 部署说明 README、crm-new 对照与 bridge-tools 方案文档、备份与隧道脚本 - .gitignore 排除 .env、config.toml、uploads/、tls 私钥/证书、backups/、logs/
2026-10-29 13:24:13 +08:00
commit 39986f10f2
26 changed files with 6345 additions and 0 deletions
@@ -0,0 +1,133 @@
+# crm-new vs 本实例（yehwang-ai/libredesk）差距与补充方案
+
+> 生成时间：2026-10-28　对比基准：crm-new `docker-compose.yml` + 运行中的 `crmnew-*` 容器 + `crmnew-postgres/libredesk` 库实际数据
+> 本实例：`/home/dev/code/yehwang-ai/libredesk`（LibreDesk v2.9.1 + PG18 + Redis + nginx TLS）
+
+## 0. 一句话结论
+
+本实例目前只是「**能登录的 LibreDesk 空壳**」（0 渠道、0 AI 助手、0 工具、0 知识库、0 自动化），
+crm-new 是一条**完整跑通的 AI 客服业务链**（三渠道 + bridge 工具 + Twenty CRM + 公网入口 + 一大套配置脚本与上线文档）。
+差的不是「几个开关」，而是**整条链的组件、配置、凭据和运维资产**。
+
+## 1. 能力矩阵（均为实测，不是看代码猜的）
+
+| 能力 | crm-new | 本实例 | 缺口 |
+| --- | --- | --- | --- |
+| 容器编排 | LibreDesk + Twenty(server/worker) + bridge + imap-proxy + public-gateway + cloudflared + PG + Redis（9 个） | LibreDesk + PG + Redis + nginx TLS（4 个） | Twenty、bridge、imap-proxy、public-gateway、cloudflared |
+| 渠道 inbox | **3 个**：Website(livechat) / Email 163 / WhatsApp | **0** | 全部 |
+| 邮件通知 | `notification.email.*`：smtp.163.com:465 TLS，已启用 | 无 | 全部 |
+| Live chat | inbox + widget + 身份锚定方案（SITE_JWT / IDENTITY_*，bridge 侧） | 无 | 全部 |
+| WhatsApp | inbox + 6 个模板 + Meta Cloud API 凭据 + 回调 | 无 | 全部 |
+| AI provider | 2 个已配：completion=`qwen-plus-latest`(DashScope, openai 兼容)、embedding=`text-embedding-v4` | 2 行**空壳**默认记录，api_key 为空 | 填 key/模型/默认项 |
+| AI assistant | 1 个（B2B 助手；max_turns=8；handoff 开；guardrails/expectation/tone） | 0 | 全部 |
+| AI tools | **11 个** HTTP 工具：search_products / search_orders / search_inventory / search_kb / search_email_history / collect_info / send_verification_code / verify_email_code / handoff_to_human / create_opportunity / get_customer_info | 0 | 全部 |
+| 知识库 | 帮助中心 1 个（`yehwang-help`）+ **108 篇已发布文章**；bridge 侧 pgvector RAG（快照 594 chunks） | 0 | 全部 |
+| 自动化规则 | 3 条：AI 分配、邮件→Wholesale、WhatsApp→Wholesale | 0 | 全部 |
+| 团队/坐席 | 1 个 team（Wholesale Support，时区 Asia/Shanghai）+ 3 agent + 2 角色；库内 27 用户（含 contact/visitor 历史） | 1 个用户（System）+ 2 个默认角色 | 团队、坐席、角色细分 |
+| Webhook | 1 条：Bridge AI → `http://bridge:4100/libredesk/webhook` | 0 | 全部 |
+| 公网入口 | public-gateway（只放 WhatsApp webhook + 帮助中心）+ cloudflared quick tunnel；root_url 指向临时 trycloudflare 域名（隧道重启即变，不可当长期入口） | nginx 自签 TLS（仅内网 9443）；`root_url=http://localhost:9000` | 域名、证书、白名单反代 |
+| 数据库 | PG 3 库（libredesk / twenty / bridge）+ pgvector | 单库 libredesk | 若接 Twenty/bridge 需建库 |
+| 网络 | 额外接入外部网络 `spug-net`，bridge 直连 yehwang RPC（9503/9505/9506/9509） | 独立 bridge 网络 | 网络互联 |
+| 配置脚本 | bootstrap.sh、render-config.js、configure-ai/email、add-email-inbox、add-whatsapp-inbox、register-tools、import-kb-helpcenter、set-public-url、set-wa-webhook、smoke.sh、e2e-*、eval-*、kb-* 等约 25 个 | 无 | 全部 |
+| 文档 | architecture / api-mapping / environments / go-live / runbook / human-routing / libredesk-setup / migration-plan / plan-a / deploy-wangliang | 只有一个 README | 上线、运维、切流文档 |
+| 备份 | runbook 有 pg_dump / Twenty 文件存储 / KB 快照命令 | 只有我这次升级时手工做的两次 dump，**无定时任务** | 定时备份 + 恢复演练 |
+
+**基础配置本身就有错**（两边都有，但本实例更明显）：
+
+- 本实例 `app.root_url = http://localhost:9000`（邮件/帮助中心链接会指向 localhost）
+- 本实例 `app.timezone = Africa/Cairo`（荷兰业务差 1 小时）
+- crm-new 的 `app.timezone = ""`、`root_url` 是已失效的临时隧道域名
+
+## 2. 建议补充方案（分 6 期，按依赖排序）
+
+### P0 正确性与安全（约 0.5h，先做）
+
+| 事项 | 说明 |
+| --- | --- |
+| root_url 改为 `https://192.168.31.61:9443` | 影响邮件通知、帮助中心、widget 链接 |
+| timezone 改 `Europe/Berlin`（UI）或 `Europe/Amsterdam`（API） | 两者规则等价，见时区分析 |
+| 建个人管理员账号，改掉 System 密码 | 避免共用超级账号 |
+| 备份脚本落地（pg_dump + uploads，保留 7/30 天）+ 恢复演练一次 | 目前没有定时备份 |
+| （可选）`9001` 只监听 `127.0.0.1` | 减少明文暴露面 |
+
+验收：设置页不再出现 localhost/Cairo；备份能被 `pg_restore -l` 读出；个人账号可登录。
+
+### P1 渠道最小闭环（约 1–2h）
+
+1. **Live Chat inbox + widget**（Website 渠道），把这套的 widget 代码嵌到目标站点；
+2. **Email inbox**：先定用哪个邮箱 —— 163 需要 imap-id-proxy（LibreDesk 不发 IMAP ID）；建议换企业邮箱/自建 SMTP 省掉代理；
+3. 配置 `notification.email.*`（OTP/通知邮件走同一 SMTP）；
+4. 建 **Team**（Wholesale Support）+ 分配规则（邮件/WhatsApp 转人工）；
+5. 建 **Help Center**，导入 crm-new 的 108 篇文章（可参考 `import-kb-helpcenter.js`）。
+
+验收：widget 能落会话；邮件收发一轮打通；帮助中心可搜索；新会话按规则进人工团队。
+
+### P2 AI 能力（约 2–4h）
+
+1. 填 AI provider（复用 crm-new 的 DashScope key，或新申请），确认默认 provider；
+2. 配 AI assistant（instructions / guardrails / handoff / languages / max_turns）；
+3. 知识库二选一：
+   - **A**：用 LibreDesk 内置 KB/snippets + embedding（新栈自包含，但要重新灌数据）；
+   - **B**：沿用 bridge 的 pgvector RAG（数据现成，但依赖 bridge 运行）；
+4. Live Chat 开启 AI 接管，跑 preview/retrieval 验证与转人工。
+
+验收：AI 回答能引用知识库；越界时按 guardrails 转人工；有可复跑的检索评测。
+
+### P3 业务工具 + CRM（约 0.5–1d，取决于复用方式）
+
+三条路线（需拍板）：
+
+- **A. 复用 crm-new 的 bridge**：新实例 webhook 指向同一个 `crmnew-bridge:4100`，工具注册表复制一份；改动最小，但两套环境共享 bridge/数据；
+- **B. 新建 bridge 实例**：复制代码 + 独立 `.env`（RPC 地址、DashScope、SMTP、Redis 库分开），隔离好但维护两份；
+- **C. 只接 Twenty CRM**：不做商品/订单工具，仅联系人/商机同步，工作量最小。
+
+再补：注册 11 个工具（`register-tools.js` 适配新实例 API key）、OTP 邮件、输出护栏与质量指标（bridge 自带，复用即得）。
+
+验收：搜商品/查订单/建商机一条 e2e 跑通。
+
+### P4 公网渠道（约 0.5–1d，依赖域名/凭据）
+
+1. 固定域名 + Let's Encrypt（推荐）或 Cloudflare 命名隧道；**quick tunnel 不可持续**（crm-new 的 root_url 就是临时域名，cloudflared 一重启就变）；
+2. WhatsApp：Meta Cloud API 凭据（WABA/phone number/token/verify token）+ 回调地址 + 模板；
+3. 复用 public-gateway 白名单思路（只暴露 WhatsApp webhook + 帮助中心，其余 404）；
+4. root_url 与帮助中心域名统一。
+
+验收：Meta 回调校验通过；公网只可达白名单路径；帮助中心/客服入口 HTTPS 正常。
+
+### P5 运维与上线（约 2–4h）
+
+- smoke.sh / e2e 脚本适配新实例；健康检查（已有 `/health`）+ 日志/告警；
+- 定时备份 + 恢复演练纳入 runbook；
+- 上线文档（范围、切流、验收、回滚）——可沿用 crm-new 的 go-live/runbook 结构；
+- 版本策略：跟随稳定版（当前 v2.9.1），AI/WhatsApp 属较新功能，建议低流量验证。
+
+## 3. 需要你拍板的决策点
+
+1. **本实例定位**：独立演示/联调环境，还是将来生产？（决定域名、证书、备份等级）
+2. **和 crm-new 的关系**：并存做隔离验证，还是最终替代它？
+3. **邮件渠道**：继续 163（要 imap-proxy），还是换正式邮箱？
+4. **AI key**：复用 crm-new 的 DashScope key，还是新申请？知识库走 LibreDesk 内置还是 bridge RAG？
+5. **Twenty / bridge**：复用现有实例（A 路线），还是新建（B 路线），或只接 CRM（C 路线）？
+6. **公网**：有没有可用域名？走 Cloudflare 隧道还是自有 nginx + 证书？
+7. **多站点**：是否要搬 crm-new 的 `sites.json` 多站点路由（www / us + 商品搜索兜底）？
+
+## 4. 不建议照搬的部分
+
+- 旧栈 `crm/`（chatwoot / twenty:flywheel）不要动；
+- crm-new 的 quick tunnel 与临时域名（不可持续）；
+- 全量商品页 sitemap（www 32,691 / us 22,625 URL）——除非要做商品搜索兜底；
+- 27 个历史用户（含 visitor/contact 测试数据）——新实例只建必要坐席即可。
+
+## 5. 风险提示
+
+- **163 IMAP 限制**：必须靠 imap-id-proxy 才能 SELECT，换邮箱可去掉这层；
+- **凭据复制**：把 crm-new 的 key/token 复制到新实例前先确认责任边界，建议新实例用独立凭据；
+- **两套并存**：本机已跑 20+ 容器（内存 14G，当前用 6G），再加 Twenty 一套会明显吃资源，需先规划；
+- **RC/beta 功能**：WhatsApp、AI 相关功能较新，上线前跑一轮 e2e；
+- **公网入口**：没有固定域名则 WhatsApp 回调无法长期用。
+
+## 6. 推荐路径
+
+先做 **P0 + P1（半天内）** 得到「人工渠道 + 帮助中心」可用闭环；
+确认本实例定位后，再决定 P2 AI 是否立刻上、P3/P4 是否复用 crm-new 资源。
+不建议一上来复制整套栈——两套并存的维护成本和数据一致性风险不划算。
@@ -0,0 +1,40 @@
+# Live Chat 端到端验证（2026-10-28）
+
+环境：LibreDesk v2.9.1（https://192.168.31.61:9443）+ bridge-tools（4 个 AI 工具）
+Inbox：Website（livechat，uuid `81b679b0-33fb-4796-9f83-dcc0f43231cc`）
+自动化：新会话 → 分配给 Yehwang Assistant（user_id=2）
+
+## 验证流程与结果
+
+| 步骤 | 结果 |
+| --- | --- |
+| 1. widget 匿名发起会话（`POST /api/v1/widget/chat/conversations/init`，第一条消息=退货政策） | 200，会话创建 |
+| 2. 自动化规则触发 | 会话 assigned_user_id=2（Yehwang Assistant） |
+| 3. AI 自动回复 | 约 5 秒返回，内容与知识库一致（非质量问题不退，质量问题 7 天内），带 sources |
+| 4. 访客问订单状态 | AI 要求邮箱验证 |
+| 5. 访客给邮箱 | AI 调用 `set_contact_email` + `send_email_verification`（OTP 走 163 SMTP） |
+| 6. 从 Redis 取码（`ai:otp:pending:<uuid>`）并回复 | AI 调用 `check_email_verification`，验证通过 |
+| 7. 重试 `search_orders` | bridge-tools 日志：`tool=search_orders verified=true ok=true`；回复「没有找到该邮箱的订单」 |
+| 8. 会话状态 | Open，contact email 已更新 |
+
+## 发现的问题（已处理）
+
+在第 4 步之前，模型曾自行声称「已把验证码发到 example@example.com」——这是一个**编造的邮箱和编造的动作**（当时联系人的邮箱为空）。
+已在 assistant instructions 里加护栏：
+
+> Never invent or assume the customer's email address: ask for it. Only say a verification code or email was sent after the send_email_verification tool succeeds.
+
+仍建议上线前用真实客户跑一轮回归，重点看「无邮箱时是否会索要邮箱」以及「是否只在工具成功后声称已发送」。
+
+## 复现命令
+
+widget 匿名发起：
+
+```bash
+curl -sk -X POST https://localhost:9443/api/v1/widget/chat/conversations/init \
+  -H 'Host: 192.168.31.61:9443' -H 'Content-Type: application/json' \
+  -H 'X-Libredesk-Inbox-ID: 81b679b0-33fb-4796-9f83-dcc0f43231cc' \
+  -d '{"message":"What is your return policy?"}'
+```
+
+发送后续消息需 `Authorization: Bearer <session_token>` + `X-Libredesk-Inbox-ID`。
@@ -0,0 +1,147 @@
+# 方案：bridge 只保留 tools，其余用 LibreDesk 内置能力
+
+> 2026-10-28 评估。依据：LibreDesk v2.9.1 源码（`internal/aiagent/`、`internal/ai/tools.go`、`schema.sql`）+ crm-new 运行数据。
+> 结论：**可行**，而且 LibreDesk 内置能力比预期多——bridge 可以从 11 个工具收缩到 4–6 个业务工具。
+
+## 0. 已确认的决策（2026-10-28）
+
+| 决策点 | 结论 |
+| --- | --- |
+| bridge-tools 部署 | **方案 A**：并入本实例 compose（服务名 `bridge-tools`，同 `libredesk` 网络） |
+| `create_opportunity`（Twenty） | **先不留** |
+| `search_email_history` / `collect_info` | **先删** |
+| 程序化输出护栏 | **先接受降级**（后续用 LibreDesk webhook 外采质量指标） |
+| `get_customer_info` | **保留**（业务需要） |
+| 保留工具清单 | `search_products` / `search_orders` / `search_inventory` / `get_customer_info` |
+
+## 1. 关键证据：LibreDesk v2.9.1 已经内置了什么
+
+AI agent 每次回复时自动注册的内置工具（`internal/aiagent/worker.go:290-314`）：
+
+| 内置工具 | 作用 | 对应 crm-new bridge 的什么 |
+| --- | --- | --- |
+| `search_knowledge_base` | 检索 snippets + 帮助中心文章（向量），支持引用计数 | `search_kb`（bridge 的 pgvector RAG） |
+| `handoff`（`handoff_enabled`） | 转人工（`fallback_team_id`） | `handoff_to_human` |
+| `get_previous_conversations` | 拉该客户近 N 天其他会话 | `search_email_history`（部分覆盖） |
+| `send_email_verification` | 发 OTP 到联系人邮箱（走通知邮箱 SMTP；Redis 存码，10 分钟有效，30 分钟验证态） | `send_verification_code` |
+| `check_email_verification` | 校验 OTP，3 次尝试上限、重发上限 | `verify_email_code` |
+| `set_contact_email` | 访客改邮箱后再发码 | （bridge 无对应，新增能力） |
+| `resolve` | 结束时给会话打结果 | 无 |
+
+其他内置：
+
+- **工具调用上下文自动注入**（`internal/ai/tools.go:250-270`）：`X-Libredesk-Contact-Id` / `-External-Id` / `-Type` / `-Email` / `-Verified` / `X-Libredesk-Conversation-UUID` / `X-Libredesk-Inbox-Id` —— bridge 的多站点路由（sites.json）和身份判断可以直接用这些头，不再需要自己发验证 token。
+- **工具级验证开关** `ai_tools.requires_verification`：不验证的客户调私有数据工具会被拦，并引导模型走内置 OTP 流程（`tools.go:186`）。
+- **工具鉴权** `ai_tools.auth`（自定义 header，支持加密存储）：bridge 的 shared key 直接配在工具上。
+- **AI 助手配置**：instructions / guardrails / expectation / tone / response_length / max_turns / fallback_team_id / handoff_enabled / citations_enabled / languages / enabled。
+- **知识库**：`ai_knowledge_base`（snippet 类）+ 帮助中心文章都会作为 embedding 源（`internal/ai/embedsource.go`）。
+- **Widget 身份**：inbox secret 的 JWT 校验（`cmd/chat.go`），站点后端签 JWT 即可，不需要 bridge 的 identity 服务。
+- **通知邮件 / OTP 发信**：`notification.email.*`（crm-new 里就是 163 SMTP）。
+
+## 1.5 落地进度
+
+| 期 | 状态 | 说明 |
+| --- | --- | --- |
+| P0 root_url / timezone | ✅ 完成 | `root_url=https://192.168.31.61:9443`、`timezone=Europe/Berlin`（API 已写入并回读） |
+| P0 SMTP / embedding key | ✅ 完成 | 复用 crm-new 的 163 SMTP（smtp.163.com:465 TLS）和 DashScope key；completion 实际用 **qwen-max**（见下） |
+| P2 瘦身 bridge | ✅ 完成 | `bridge-tools/`（零第三方依赖，4 个工具，9 个单测通过），已并入 compose 并 healthy |
+| P3 工具注册 | ✅ 完成 | LibreDesk `ai_tools` 已注册 4 个，`search_orders`/`get_customer_info` 带 `requires_verification` |
+| P1 帮助中心/assistant | ✅ 完成 | Team「Wholesale Support」+ 帮助中心（108 篇，已嵌入）+ Assistant「Yehwang Assistant」（4 个工具、fallback team、handoff/citations 开）；预览已能基于文章回答并返回 sources |
+| P4 渠道 | 🟡 部分完成 | **Website livechat 已建 + 自动化分配到 Assistant + 端到端验证通过**（含 OTP → search_orders）；email / WhatsApp 待做 |
+
+### ⚠️ 模型选择的关键发现
+
+`qwen-plus-latest` / `qwen-plus` 在 LibreDesk 这套较长的 system prompt 下**不会调用工具**（实测 tool_calls=0），直接凭模型自身知识作答，还会编造 `[[cite:45]]` 这种不存在的引用（第一次预览回答「30 天退货」，而知识库实际是「非质量问题不退，质量问题 7 天内」）。
+换成 **`qwen-max`** 后工具调用正常（sources 命中 5 篇，score 0.33–0.61），回答与知识库一致。因此 completion 配置为 `qwen-max`；如果以后换模型，务必用「退货政策/预购时效」这类问题验证是否会调用 `search_knowledge_base`。
+
+## 2. bridge 收缩后保留什么
+
+| crm-new 现有工具 | 处理 | 说明 |
+| --- | --- | --- |
+| `search_products` | **保留** | 业务 RPC 商品搜索，LibreDesk 无替代 |
+| `search_orders` | **保留**（`requires_verification=true`） | 私有数据，用内置 OTP 把关 |
+| `search_inventory` | **保留** | 库存/ETA |
+| `get_customer_info` | 保留（可选） | 若 Twenty 客户资料要查；也可并进 orders |
+| `create_opportunity` | 保留（可选） | Twenty 商机写入，LibreDesk 无替代；不做 CRM 则去掉 |
+| `search_kb` | **删除** | 用内置 `search_knowledge_base`；108 篇帮助文章已在 LibreDesk 里 |
+| `search_email_history` | 先删 | 内置 `get_previous_conversations` 覆盖「本系统内历史」；旧邮件库不再接入 |
+| `collect_info` | 先删（可选保留） | lead 槽位采集改为 assistant 指令 + 联系人自定义属性；要做销售漏斗再保留 |
+| `handoff_to_human` | **删除** | 内置 handoff + fallback_team_id |
+| `send_verification_code` | **删除** | 内置 OTP 工具 |
+| `verify_email_code` | **删除** | 内置 OTP 工具 |
+
+**结果：bridge = 一个只暴露 3–5 个 HTTP 工具的瘦服务**（+ 多站点配置、RPC 客户端、Twenty 客户端、shared key 鉴权、健康检查）。
+
+## 3. 明确会被「降级」的能力（要接受或后补）
+
+| 现有能力 | 用内置后的状态 | 建议 |
+| --- | --- | --- |
+| 程序化输出护栏（URL 白名单、价格/库存数字校验、幻觉重写） | **没有等价物**；只有 assistant 的 `guardrails` 提示词约束 | 先接受（低流量验证）；需要时用 LibreDesk webhook → 独立质量服务补 |
+| 质量飞轮 / 指标 / 日报 / 引用检查 / A-B | 无等价物；LibreDesk 只有基础报表 | 后续用 webhook 采集到外部（bridge 加一个 consumer，不做实时改回复） |
+| 旧 bridge Hybrid RAG（parent-child + 向量 + 全文 + RRF + rerank） | 退化为向量 top-k（snippets + 文章） | 用真实问题跑检索评测对比；不满意可把 snippet 切细或补 FAQ |
+| 邮件历史检索（旧 `kb_mail_docs`） | 只覆盖 LibreDesk 内会话 | 需要历史邮件时再做离线 ingest |
+| lead 槽位（Redis 跨轮） | 没有 | 用 assistant instructions + 自定义属性；或保留 `collect_info` 工具 |
+
+## 4. 实施分期
+
+### P0 前置（0.5h）
+
+- 配置 `notification.email.*`（OTP + 通知都依赖它，必须有可用 SMTP）；
+- AI provider：completion + **embedding**（内置 KB 检索依赖 embedding，必须配）；
+- 修 `root_url`、`timezone`（见时区方案）。
+
+### P1 LibreDesk 内置能力配置（2–4h）
+
+1. 帮助中心 + 108 篇文章（从 crm-new 导出后导入，或按原源重灌）；
+2. 需要时补 snippets（FAQ 短答案）；
+3. AI assistant：instructions / guardrails / tone / max_turns / languages / citations / fallback_team_id / handoff_enabled；
+4. 团队（Wholesale Support）+ 自动化规则（AI 分配、邮件/WhatsApp 转人工）。
+
+验收：AI 能基于帮助中心回答并带引用；越界/复杂问题按 fallback_team 转人工；OTP 流程能发码、验码（先用 livechat 访客验证）。
+
+### P2 瘦身 bridge（0.5–1d）
+
+- **新建目录 `bridge-tools/`（从 `crm-new/bridge` 裁剪，不改 crm-new 本身）**，保留：
+  `server.js`（只留工具路由 + healthz）、`tools.js`（裁剪）、`rpc.js`、`product-query.js`、`sitemap.js`、`opportunity.js` / `twenty.js`（若保留）、`redis.js`、`auth.js`、`config.js`、`security.js` + 对应测试；
+- 删除：agent.js、prompts.js、llm*.js、rag.js、kb-*.js、embedding.js、reranker.js、verification.js、smtp.js、identity.js、jwt.js、libredesk-webhook.js、metrics/quality/citation-checker/output-guard/flywheel/audit/experiments/trace 等；
+- 依赖精简：PG 可去掉（若不做 lead/质量库），Redis 保留（RPC 缓存/限流）；
+- 单测裁剪后必须 `npm test` 通过。
+
+验收：`/healthz` 正常；5 个工具逐个用 curl + shared key 调通；容器内存/镜像明显变小。
+
+### P3 工具注册到 LibreDesk（2–4h）
+
+- 适配 `register-tools.js`：URL 指向 `bridge-tools:4100`，`auth` 带 shared key header；
+- `search_orders` / `create_opportunity` 设 `requires_verification=true`；
+- 绑定 assistant 的 tool allowlist；
+- 多站点：`X-Libredesk-Inbox-Id` 映射 sites.json（不需要改协议，LibreDesk 已经带）。
+
+验收：livechat 里问「查订单」→ 触发 OTP → 验码后返回订单；问商品 → 返回价格/库存/链接。
+
+### P4 渠道（2–4h）
+
+- Live Chat inbox + widget（站点用 inbox secret 签 JWT 做身份锚定）；
+- Email inbox（决定用 163 走 imap-proxy，还是换企业邮箱直连）；
+- WhatsApp（依赖公网域名/隧道，单独排期）。
+
+### P5 公网/运维/质量（按需）
+
+- 固定域名 + 证书 + public-gateway 白名单；
+- 备份定时化、监控、smoke/e2e、上线文档；
+- 若需要质量护栏：LibreDesk webhook → 轻量质量服务（不改 AI 回复，只记指标）。
+
+## 5. 风险与前提
+
+- **SMTP 必须可用**：内置 OTP 依赖通知邮箱，livechat 访客验证走它；没有就会卡住「查订单」这类工具。
+- **embedding provider 必须配**：内置 KB 检索是向量检索，缺 key 时 `search_knowledge_base` 不可用。
+- **RPC 网络**：bridge-tools 仍需要访问 yehwang RPC（crm-new 是靠外部网络 `spug-net`），新 compose 要接同一网络或走隧道。
+- **内置 OTP 的边界**：只对「email 渠道会话」或「非 contact 类型联系人（访客）」提供；已存在且非访客的 contact 不会自动有 OTP 工具（`worker.go:308`），要确认业务场景。
+- **检索质量下降**：内置 top-k vs 旧 hybrid；上线前用 20–30 个真实问题对比命中率。
+- **两套并存**：bridge-tools 与 crm-new bridge 可共用 RPC/Redis 配置，但建议独立 redis db 和独立 shared key。
+
+## 6. 需要拍板
+
+1. `create_opportunity` / Twenty 商机要不要保留？（决定 bridge 留 3 个还是 5 个工具）
+2. `search_email_history`、`collect_info` 先删还是保留？
+3. 程序化输出护栏：先接受降级，还是一开始就按 webhook 方案补？
+4. bridge-tools 部署位置：同一台机新 compose，还是并到本实例 compose？