fix: P0-1 RateLimiter并发写安全 + P0-2工单操作错误码区分 + P1 rows.Close修复

P0-1 (limits.go): Allow()方法改为全程使用写锁保护counters map读写，避免RLock写入时的data race P0-2 (ticket_workflow.go+ticket_handler.go): Assign/Resolve/Close操作先查询ticket存在性和状态，返回明确的CS_TICKET_4001/CS_TKT_4002/CS_TICKET_4092/CS_TICKET_4093错误码，handler根据错误前缀路由HTTP状态码 P1-1 (ticket_store.go): 移除GetStats中3处手动rows.Close()，只保留defer Close()
2026-05-01 20:56:25 +08:00
parent bd2d848009
commit cf46b27610
103 changed files with 16428 additions and 0 deletions
--- a/specs/功能清单.md
+++ b/specs/功能清单.md
@@ -0,0 +1,288 @@
+# AI Customer Service 功能清单（按钮级任务版）
+
+> 版本：v1.0
+> 日期：2026-04-27
+> 说明：每个任务 5 分钟可完成，可直接安排进任务管理
+
+---
+
+## Phase 1：Widget 渠道 + RAG 知识库 + 基础对话
+
+### 模块 1.1：网页 Widget 接入
+
+#### 1.1.1 Widget 嵌入
+- [ ] **任务**：实现 Widget 组件（HTML snippet + JS），可通过 `<script>` 标签嵌入任意网页
+- [ ] **任务**：Widget 组件渲染浮动按钮（右下角，点击展开对话窗口）
+- [ ] **任务**：对话窗口渲染：标题栏（"智能客服"）/ 消息区（滚动）/ 输入框（支持 Enter 发送）/ 发送按钮
+- [ ] **任务**：实现 Widget 最小化按钮，点击后收起为悬浮球
+- [ ] **任务**：实现 Widget 消息气泡：用户消息（右侧蓝色）/ 机器人消息（左侧灰色）
+- [ ] **任务**：机器人消息支持 Markdown 格式渲染（支持代码块、粗体、链接）
+- [ ] **任务**：机器人消息支持展示链接按钮（点击可跳转外部页面）
+
+#### 1.1.2 Webhook 对接
+- [ ] **任务**：实现 Widget Webhook 端点 `POST /api/v1/ai-customer-service/webhook/widget`
+- [ ] **任务**：Webhook 接收消息后，解析 `session_id`（从 cookie 或 localStorage 生成）、`user_message`、`channel=widget`
+- [ ] **任务**：Webhook 返回 HTTP 200（异步处理模式），消息处理结果通过 WebSocket 推送回 Widget
+- [ ] **任务**：实现 WebSocket 连接管理（Widget 端建立长连接 `/ws/widget`）
+
+### 模块 1.2：对话引擎
+
+#### 1.2.1 意图识别
+- [ ] **任务**：实现 `IntentEngine.Recognize()` 接口，输入用户消息，输出意图 + 置信度
+- [ ] **任务**：实现意图分类列表：api_key_管理 / 模型路由配置 / 配额计费 / 错误码诊断 / 账户问题 / 转人工
+- [ ] **任务**：实现置信度计算，阈值：>=0.85 = 高置信 / 0.60-0.85 = 中置信 / <0.60 = 低置信
+- [ ] **任务**：低置信度意图自动触发转人工流程
+- [ ] **任务**：实现"退款/账户封禁/数据泄露"等敏感意图识别（关键词匹配 + 意图分类），命中时强制转人工
+
+#### 1.2.2 RAG 检索
+- [ ] **任务**：实现知识库向量库初始化脚本（使用 Qdrant / PGVector），接入产品文档内容
+- [ ] **任务**：实现 `RAGEngine.Retrieve(query, top_k)` 接口，输入用户问题，输出 top_k 相关知识库片段
+- [ ] **任务**：RAG 检索使用混合策略：sentence embedding（语义）+ keyword match（关键词兜底）
+- [ ] **任务**：实现检索结果重排序（使用 cross-encoder 对 top_k*2 结果重新打分，取 top_k）
+- [ ] **任务**：RAG 检索 P99 延迟目标 <200ms
+
+#### 1.2.3 回复生成
+- [ ] **任务**：实现 `ReplyGenerator.Generate(ctx, intent, rag_results, conversation_history)` 接口
+- [ ] **任务**：Prompt 模板：System Prompt（你是立连桥智能客服，专回答产品使用问题，只引用知识库内容）+ User Query + RAG 结果 + 对话历史
+- [ ] **任务**：实现回复 Markdown 渲染（飞书/企微渠道），代码示例使用语法高亮
+- [ ] **任务**：涉及用户个人数据查询时，在 Prompt 中注入 `user_id`，强制模型只返回当前用户数据
+- [ ] **任务**：实现回复缓存（Redis，相同意图+相同用户问题的回复缓存 5 分钟）
+
+### 模块 1.3：会话管理
+
+#### 1.3.1 会话状态机
+- [ ] **任务**：实现会话状态枚举：initializing / waiting / bot_replied / waiting_human / closed
+- [ ] **任务**：实现会话超时逻辑：用户 30 分钟无消息 → 自动发送"还在吗？"；仍无回复 → 30 分钟后关闭会话
+- [ ] **任务**：实现会话关闭事件记录：用户点击"已解决"或超时关闭 → 记录 `session_resolved`
+
+#### 1.3.2 上下文管理
+- [ ] **任务**：实现上下文窗口：保留最近 5 轮对话（用户+机器人各 5 条）
+- [ ] **任务**：上下文存储在 Redis（Key = `cs:session:{session_id}`，TTL = 24 小时）
+- [ ] **任务**：实现跨会话用户识别：Widget 用户首次访问时生成 `anonymous_id` 存入 cookie
+
+### 模块 1.4：知识库管理
+
+#### 1.4.1 知识库后台
+- [ ] **任务**：实现知识库管理页路由 `/cs/dashboard/knowledge`
+- [ ] **任务**：知识库列表每行显示：条目ID / 标题 / 分类 / 覆盖意图 / 引用次数 / 状态 / 操作
+- [ ] **任务**：渲染"新增条目"按钮，点击进入条目编辑器
+- [ ] **任务**：知识库编辑器字段：标题（必填）/ 分类（下拉：API Key/路由/配额/错误码/账户/其他）/ 正文（Markdown 富文本）/ 覆盖意图标签（多选）/ 状态（草稿/发布）
+- [ ] **任务**：编辑器实现 Markdown 实时预览
+- [ ] **任务**：条目发布后，自动触发向量库更新（异步，30 秒内生效）
+- [ ] **任务**：每个知识库条目支持上传附件（PDF/图片），附件存储在 OSS
+- [ ] **任务**：知识库列表支持按分类筛选 / 按标题搜索 / 按引用次数排序
+
+#### 1.4.2 知识库导入导出
+- [ ] **任务**：实现"批量导入"按钮，支持上传 Markdown zip 包批量导入条目
+- [ ] **任务**：实现"导出全部"按钮，导出为 Markdown zip 包
+
+---
+
+## Phase 2：Telegram + Discord + 意图识别 + 转人工
+
+### 模块 2.1：多渠道接入适配
+
+#### 2.1.1 Telegram Bot 接入
+- [ ] **任务**：申请 Telegram Bot（通过 @BotFather），获取 Bot Token
+- [ ] **任务**：实现 Telegram Webhook 端点 `POST /api/v1/ai-customer-service/webhook/telegram`
+- [ ] **任务**：Webhook 解析 Telegram Update：提取 `chat.id`（作为 user_id）、`message.text`（作为 user_message）
+- [ ] **任务**：实现 Telegram 回复方法：调用 Bot API `sendMessage`，传入 `chat.id` 和回复内容
+- [ ] **任务**：实现 Telegram 消息格式化：Markdown → Telegram MarkdownV2 格式转换
+- [ ] **任务**：在 Gateway 配置 Telegram Bot Webhook URL 指向本系统
+
+#### 2.1.2 Discord Bot 接入
+- [ ] **任务**：创建 Discord Application，开通 Bot 功能，获取 Bot Token
+- [ ] **任务**：实现 Discord Webhook 端点 `POST /api/v1/ai-customer-service/webhook/discord`
+- [ ] **任务**：Webhook 解析 Discord interaction：提取 `channel_id` / `member.user.id` / `content`
+- [ ] **任务**：实现 Discord 回复方法：调用 Discord Webhook API 或 Bot sendMessage
+- [ ] **任务**：Discord 支持 slash command（如 `/客服问题`）触发对话
+- [ ] **任务**：在 Gateway 配置 Discord Webhook 指向本系统
+
+#### 2.1.3 统一消息格式
+- [ ] **任务**：实现 `ChannelAdapter` 接口族（TelegramAdapter / DiscordAdapter / WidgetAdapter / WechatAdapter）
+- [ ] **任务**：每个 Adapter 将各自渠道的消息格式统一转换为 `UnifiedMessage`（包含：message_id / channel / open_id / user_id / content / timestamp）
+- [ ] **任务**：实现统一会话 ID 生成规则：`{channel}:{open_id}`
+
+### 模块 2.2：身份核验
+
+#### 2.2.1 绑定用户身份识别
+- [ ] **任务**：实现 `GET /api/v1/ai-customer-service/auth/check?channel={ch}&open_id={id}` 接口，返回绑定状态
+- [ ] **任务**：已绑定用户：返回 `{bound: true, user_id: "xxx"}`
+- [ ] **任务**：未绑定用户：返回 `{bound: false}`，触发身份核验流程
+
+#### 2.2.2 邮箱验证码核验
+- [ ] **任务**：未绑定用户输入邮箱后，点击"验证"按钮，POST `/api/v1/ai-customer-service/auth/verify-code/send`
+- [ ] **任务**：后端验证邮箱是否存在（调用 `supply-api` 的邮箱查询接口），存在则发送 6 位数字验证码（有效期 5 分钟）
+- [ ] **任务**：用户输入验证码，POST `/api/v1/ai-customer-service/auth/verify-code/check`
+- [ ] **任务**：验证成功后，将 `{channel, open_id, user_id}` 写入 `cs_user_bindings` 表
+- [ ] **任务**：验证失败 3 次后，自动触发转人工工单（标签：identity_verification_failed）
+
+#### 2.2.3 API Key 前缀核验
+- [ ] **任务**：用户输入 API Key 前缀，POST `/api/v1/ai-customer-service/auth/apikey/lookup`
+- [ ] **任务**：后端用前缀模糊查询 `supply_api_keys` 表（前 8 位），返回匹配到的账户列表（隐藏中间位）
+- [ ] **任务**：若匹配到 1 个 → 直接绑定；若匹配到多个 → 要求补充邮箱二次确认；若 0 个 → 提示"未找到账户"
+- [ ] **任务**：验证过程不存储用户输入的完整 API Key，仅记录前缀用于关联
+
+### 模块 2.3：转人工流程
+
+#### 2.3.1 触发转人工
+- [ ] **任务**：实现转人工触发条件检测：a）用户发送"人工客服/找人工/投诉"关键词 b）意图置信度 <0.60 c）身份核验失败 3 次 d）用户反馈"未解决"累计 3 轮
+- [ ] **任务**：触发转人工时，更新会话状态 = waiting_human
+- [ ] **任务**：触发转人工时，显示机器人消息："正在为您转接人工客服，请稍候..."
+
+#### 2.3.2 工单生成
+- [ ] **任务**：触发转人工时，自动写入 `cs_tickets` 表（字段：ticket_id / session_id / user_id / channel / priority / status=open / created_at / 原始问题 / 会话历史摘要）
+- [ ] **任务**：转人工时，若用户处于多轮对话，附加最近 5 轮对话历史到工单 `conversation_history` 字段
+- [ ] **任务**：触发转人工时，发送飞书通知到客服群（包含用户ID/渠道/问题摘要/排队位置）
+- [ ] **任务**：实现 `GET /api/v1/ai-customer-service/tickets/queue-position?ticket_id={id}`，返回当前排队人数
+
+#### 2.3.3 人工接管
+- [ ] **任务**：客服人员点击"接单"按钮，POST `/api/v1/ai-customer-service/tickets/{id}/accept`
+- [ ] **任务**：接单后，工单状态更新为 processing，locked_by = 客服ID
+- [ ] **任务**：机器人向用户发送："人工客服已接单，预计 {X} 分钟内回复"
+- [ ] **任务**：客服在工单处理页发送消息，POST `/api/v1/ai-customer-service/tickets/{id}/reply`，消息推送给用户
+
+---
+
+## Phase 3：微信渠道 + 用户数据查询 + 工单后台
+
+### 模块 3.1：微信接入
+
+#### 3.1.1 微信公众号 Webhook
+- [ ] **任务**：配置微信公众号服务器地址（URL + Token + EncodingAESKey）
+- [ ] **任务**：实现微信公众号 Webhook 验证（GET 请求，验证 Token）
+- [ ] **任务**：实现微信公众号消息接收 `POST /api/v1/ai-customer-service/webhook/wechat`
+- [ ] **任务**：解析微信 XML 消息格式：提取 `FromUserName`（作为 open_id）、`MsgType`、`Content`
+- [ ] **任务**：实现被动回复（用户发消息后，微信服务端在 5 秒内必须回复，否则重试）
+- [ ] **任务**：支持接收事件推送（用户关注/取关）
+
+#### 3.1.2 微信公众号客服消息
+- [ ] **任务**：实现模板消息发送（用于通知类消息，如工单状态变更）
+- [ ] **任务**：客服在后台发送的消息，通过微信公众号客服消息接口推送（调用 `https://api.weixin.qq.com/cgi-bin/message/custom/send`）
+
+### 模块 3.2：用户数据查询（只读）
+
+#### 3.2.1 Token 消耗查询
+- [ ] **任务**：用户发送"我的 Token 消耗是多少"，识别意图为 quota_check
+- [ ] **任务**：后端调用 `GET /api/v1/ai-customer-service/diagnostics/token-usage?user_id={uid}&date=today`
+- [ ] **任务**：内部调用 `platform-token-runtime` 的只读接口获取今日 Token 消耗
+- [ ] **任务**：机器人回复格式："今日已消耗 {N} Tokens，剩余配额 {M} Tokens（{percent}%）"
+
+#### 3.2.2 错误日志诊断
+- [ ] **任务**：用户发送"我的请求报错了"或错误码，识别意图为 error_diagnosis
+- [ ] **任务**：后端调用 `GET /api/v1/ai-customer-service/diagnostics/recent-errors?user_id={uid}&limit=5`
+- [ ] **任务**：内部调用 `supply-api` 的只读接口获取用户最近 5 条错误日志
+- [ ] **任务**：机器人回复展示：请求时间 / 错误码 / 错误描述 / 建议操作
+
+#### 3.2.3 供应商状态查询
+- [ ] **任务**：用户发送"供应商X是不是挂了"，识别意图为 supplier_status_check
+- [ ] **任务**：后端调用 `GET /api/v1/ai-customer-service/diagnostics/supplier-status?supplier={name}`
+- [ ] **任务**：内部调用 `supply-intelligence` 的供应商状态 API
+- [ ] **任务**：机器人回复格式："供应商 {X} 当前状态：正常运行（延迟 {N}ms）/ 部分可用（{详情}）"
+
+### 模块 3.3：工单后台
+
+#### 3.3.1 工单列表页
+- [ ] **任务**：实现工单列表页路由 `/cs/dashboard/tickets`
+- [ ] **任务**：工单列表顶部渲染状态 Tab：全部 / 待处理（open）/ 处理中（processing）/ 已关闭（closed）
+- [ ] **任务**：工单列表顶部渲染优先级 Tab：全部 / P1（红色）/ P2（橙色）/ P3（灰色）
+- [ ] **任务**：工单列表每行显示：工单ID / 用户ID / 渠道图标 / 问题摘要 / 优先级 / 状态 / 等待时长 / 客服 / 创建时间
+- [ ] **任务**：工单行按优先级（P1>P2>P3）和等待时长升序排列
+- [ ] **任务**：工单行渲染"接单"按钮（仅 open 状态且未锁定的工单可见）
+- [ ] **任务**：工单行渲染"查看"按钮，点击进入工单详情页
+
+#### 3.3.2 工单详情页
+- [ ] **任务**：工单详情页路由 `/cs/dashboard/tickets/{ticket_id}`
+- [ ] **任务**：详情页左侧渲染会话历史时间线（用户消息+机器人回复+系统消息）
+- [ ] **任务**：详情页右侧渲染工单信息面板：用户ID / 渠道 / 优先级 / 状态 / 等待时长 / 关联会话数
+- [ ] **任务**：详情页底部渲染回复输入框（支持 Markdown + 附件上传）+ "发送"按钮
+- [ ] **任务**：发送回复后，通过对应渠道推送给用户
+- [ ] **任务**：详情页渲染"关闭工单"按钮（仅 processing 状态），点击后确认，确认后状态 = closed
+- [ ] **任务**：详情页渲染"转交"按钮（选择其他客服接手）
+
+#### 3.3.3 统计分析
+- [ ] **任务**：实现统计页路由 `/cs/dashboard/stats`
+- [ ] **任务**：统计页渲染转人工原因分布饼图（Top 10）
+- [ ] **任务**：统计页渲染每日会话量柱状图（近 30 天）
+- [ ] **任务**：统计页渲染自助解决率趋势折线图（近 30 天）
+- [ ] **任务**：统计页渲染平均首次响应时长趋势（近 30 天）
+- [ ] **任务**：统计页渲染知识库未命中率趋势（近 30 天）
+
+### 模块 3.4：模型 Failover
+
+#### 3.4.1 多模型配置
+- [ ] **任务**：实现模型配置页路由 `/cs/dashboard/settings/models`
+- [ ] **任务**：模型列表每行显示：模型名称 / 类型（主/备） / 供应商 / 状态（启用/禁用） / 操作
+- [ ] **任务**：渲染"添加备选模型"按钮，点击后弹出配置表单（模型名称 / API Endpoint / API Key / 优先级）
+- [ ] **任务**：模型配置支持拖拽排序（设置优先级顺序）
+
+#### 3.4.2 Failover 执行
+- [ ] **任务**：主模型 API 调用超时（5 秒内无响应）→ 自动切换到优先级最高的可用备模型
+- [ ] **任务**：主模型 API 返回 5xx → 自动切换到备模型，记录 failover 事件
+- [ ] **任务**：备模型也失败时（双故障）→ 返回兜底静态回复 + 生成工单
+- [ ] **任务**：Failover 事件写入 `cs_model_failover_events` 表（字段：session_id / from_model / to_model / reason / occurred_at）
+
+#### 3.4.3 兜底回复
+- [ ] **任务**：预配置兜底回复模板（静态文本，不依赖大模型）
+- [ ] **任务**：双故障时返回兜底回复："抱歉，当前客服系统繁忙，请稍后再试，或联系 support@example.com"
+- [ ] **任务**：双故障时，飞书通知技术负责人（P1 告警）
+
+---
+
+## 全局模块
+
+### 模块 G1：权限与认证
+- [ ] **任务**：实现 JWT 认证中间件（与立连桥统一认证打通）
+- [ ] **任务**：实现客服角色：客服（处理工单）/ 运营（知识库+统计）/ 管理员（全部）
+- [ ] **任务**：权限不足返回 HTTP 403，错误码 `CS_AUTH_1001`
+
+### 模块 G2：健康检查
+- [ ] **任务**：实现 `GET /actuator/health` / `/actuator/health/live` / `/actuator/health/ready`
+- [ ] **任务**：Readiness probe 检查：PostgreSQL 连接 + Redis 连接 + Qdrant 连接
+
+### Module G3: OpenAPI
+- [ ] **任务**：实现 Swagger UI 路由 `/docs`
+- [ ] **任务**：实现 OpenAPI 3.0 spec 端点 `/openapi.json`
+
+### 模块 G4：Webhook 安全
+- [ ] **任务**：实现 Telegram Webhook Secret Token 校验（X-Telegram-Bot-Api-Secret-Token）
+- [ ] **任务**：实现 Discord Request Signature 校验（X-Signature-Ed25519）
+- [ ] **任务**：实现微信消息体签名校验（msg_signature）
+- [ ] **任务**：校验失败返回 HTTP 403
+
+---
+
+## 技术基础设施
+
+### T1：项目骨架
+- [ ] **任务**：初始化 Go module `github.com/lijiaoliao/ai-customer-service`
+- [ ] **任务**：创建 `cmd/ai-customer-service/main.go`，支持 `api` 和 `worker` 两种运行模式
+- [ ] **任务**：创建 `internal/` 目录结构（domain/service/handler/infrastructure/repository）
+- [ ] **任务**：配置 Viper 读取 `config.yaml`
+- [ ] **任务**：配置 `log/slog` 结构化日志
+- [ ] **任务**：创建 PostgreSQL schema migration，表前缀 `cs_`
+- [ ] **任务**：配置 Redis 连接池
+- [ ] **任务**：配置 Dockerfile 和 docker-compose.yml
+
+### T2：单元测试
+- [ ] **任务**：为 domain 层函数编写单元测试，覆盖率 >= 70%
+- [ ] **任务**：为 service 层函数编写单元测试，覆盖率 >= 80%
+- [ ] **任务**：配置 GitHub Actions CI
+
+### T3：IntegrationPlugin 接口
+- [ ] **任务**：实现 `IntegrationPlugin` 接口
+- [ ] **任务**：实现插件模式下各渠道的开关配置
+- [ ] **任务**：实现 Webhook 路径前缀可配置（默认 `/api/v1/ai-customer-service/`）
+
+---
+
+## 任务估算汇总
+
+| Phase | 模块 | 任务数 | 估计工时 |
+|-------|------|--------|---------|
+| Phase 1 | 1.1 Widget + 1.2 对话引擎 + 1.3 会话 + 1.4 知识库 | 38 | 5 人天 |
+| Phase 2 | 2.1 TG/Discord + 2.2 身份核验 + 2.3 转人工 | 30 | 4 人天 |
+| Phase 3 | 3.1 微信 + 3.2 数据查询 + 3.3 工单后台 + 3.4 Failover | 38 | 5 人天 |
+| 全局 | G1 权限 + G2 健康 + G3 文档 + G4 Webhook安全 | 14 | 1.5 人天 |
+| 技术基础设施 | T1 骨架 + T2 测试 + T3 插件 | 12 | 1.5 人天 |
+| **合计** | | **132** | **~17 人天** |
--- a/specs/竞品分析.md
+++ b/specs/竞品分析.md
@@ -0,0 +1,137 @@
+# AI Customer Service 竞品深度分析
+
+> 版本：v1.0
+> 日期：2026-04-27
+> 内容：12 个竞品全景矩阵、功能逐项对比、技术分析、市场定位
+
+---
+
+## 一、市场概览
+
+- 全球客服软件市场（CCaaS）：2025 年约 **$80-100 亿**，AI 客服细分 $30-40 亿
+- 国内客服市场：¥200-300 亿
+- Intercom Fin 报告 AI 解决 50%+ 会话；Zendesk Freddy AI 自动化 80% 交互
+- Intercom Fin 定价：$74+/seat/月（中小企业负担重）
+- 人工客服单 ticket 成本：$5-15；首次响应时间 AI 可 <10 秒（全天候）
+- **差异化机会**：开发者 API 客服是新兴细分，传统方案（Zendesk/Intercom）面向通用场景，对"API Key 配置/Token 消耗/错误码诊断"等开发者问题支持极弱
+
+---
+
+## 二、竞品全景矩阵（12 个）
+
+| 竞品 | 类型 | 多渠道 | 开发者场景深度 | RAG | 工单系统 | 定价 | 私有化部署 |
+|------|------|--------|-------------|-----|---------|------|----------|
+| **Intercom Fin** | SaaS | Web/FB/WhatsApp | ❌ 弱 | ✅ | ✅ | $74+/seat/月 | ❌ |
+| **Zendesk + Freddy AI** | SaaS | 全渠道 | ❌ 弱 | ✅ | ✅ | $55+/agent/月 | ⚠️ 贵 |
+| **Drift** | SaaS | Web/Chat | ⚠️ 中 | ✅ | ⚠️ 弱 | $250+/mo | ❌ |
+| **Freshdesk Freddy** | SaaS | 全渠道 | ❌ 弱 | ✅ | ✅ | $15+/agent/月 | ✅ |
+| **Chative.io** | SaaS | 多渠道 | ❌ 弱 | ✅ | ✅ | $29+/seat/月 | ❌ |
+| **Dify（开源）** | 开源 | ⚠️ 需二次开发 | ⚠️ 中 | ✅ | ❌ 无 | 免费 | ✅ |
+| **FastGPT（开源）** | 开源 | ⚠️ 需二次开发 | ⚠️ 中 | ✅ | ❌ 无 | 免费 | ✅ |
+| **容联·容犀** | SaaS/私有 | 微信/企微强 | ❌ 弱 | ✅ | ✅ | 面议 | ✅ |
+| **智齿科技** | SaaS | 全渠道 | ❌ 弱 | ✅ | ✅ | 面议 | ✅ |
+| **LindY AI** | SaaS | 多渠道 | ⚠️ 中 | ✅ | ✅ | $39+/seat/月 | ❌ |
+| **Crisp** | SaaS | Chat/Email | ⚠️ 中 | ⚠️ 弱 | ⚠️ 弱 | 免费+$ | ❌ |
+| **OneAlert** | SaaS | 告警优先 | ❌ 无 | ❌ 无 | ⚠️ 弱 | 免费 | ❌ |
+| **立连桥 ai-customer-service** | 内部工具 | Widget/TG/Discord/微信 | ✅ **深度集成** | ✅ | ✅ | 内部成本 | ✅ |
+
+---
+
+## 三、功能逐项对比（16 项）
+
+```
+功能项                          Intercom  Zendesk  Dify  容联/智齿  LindY  Crisp  ai-cs
+多渠道接入                       ✅        ✅       ⚠️      ✅        ✅     ⚠️    ✅
+RAG 知识库                       ✅        ✅       ✅      ✅        ✅     ⚠️    ✅
+意图识别                         ✅        ✅       ⚠️      ✅        ✅     ⚠️    ✅
+多轮对话                         ✅        ✅       ✅      ✅        ✅     ⚠️    ✅
+身份核验（API Key）              ❌        ❌       ❌      ❌        ❌     ❌    ✅
+Token 消耗查询（只读）           ❌        ❌       ❌      ❌        ❌     ❌    ✅
+供应商状态查询                   ❌        ❌       ❌      ❌        ❌     ❌    ✅
+最近错误日志检索                 ❌        ❌       ❌      ❌        ❌     ❌    ✅
+敏感意图自动转人工               ⚠️        ⚠️       ❌      ⚠️        ⚠️     ❌    ✅
+工单系统                         ✅        ✅       ❌      ✅        ✅     ⚠️    ✅
+知识库管理后台                   ✅        ✅       ⚠️      ✅        ⚠️     ⚠️    ✅
+模型 Failover                   ⚠️        ⚠️       ⚠️      ⚠️        ⚠️     ⚠️    ✅
+对话埋点/监控                    ✅        ✅       ⚠️      ✅        ⚠️     ⚠️    ✅
+大模型供应商自选                  ❌        ❌       ✅      ❌        ❌     ❌    ✅
+开发者场景深度集成               ❌        ❌       ⚠️      ❌        ⚠️     ⚠️    ✅
+定价门槛（中小团队可接受）        ❌        ⚠️       ✅      ⚠️        ⚠️     ⚠️    ✅
+```
+
+---
+
+## 四、市场定位结论
+
+### 4.1 竞品空白
+
+**Intercom/Zendesk/Drift 等通用客服方案：**
+- 面向电商/在线客服场景
+- 对"API Key 配置/模型路由/Token 消耗/错误码诊断"等开发者问题支持极弱
+- 价格高（$55-74+/seat/月），中小企业负担重
+
+**Dify/FastGPT 等开源方案：**
+- LLM 应用平台，需要二次开发才能成为客服产品
+- 缺乏工单系统、多渠道接入、知识库管理后台等完整能力
+- 开发者友好但运维成本高
+
+**竞品不提供（立连桥独有）：**
+1. 对接 `platform-token-runtime` 查询用户真实 Token 消耗
+2. 对接 `supply-api` 查询供应商账号状态
+3. 最近 5 条错误日志诊断
+4. 开发者友好的代码示例/错误码解释
+
+### 4.2 ai-customer-service 差异化定位
+
+```
+通用客服（Intercom/Zendesk）
+  └─ 场景：电商/在线客服
+  └─ 价格：$55-74+/seat/月
+  └─ 开发者场景：❌ 不支持 API Key/Token/错误码
+
+开源方案（Dify/FastGPT）
+  └─ 场景：LLM 应用平台
+  └─ 价格：免费
+  └─ 完整客服能力：❌ 需二次开发
+
+───────────────────────────────────
+立连桥 ai-customer-service = 开发者 API 客服
+  ✅ 对接真实用户数据（Token/配额/错误日志）
+  ✅ 多渠道（Widget/Telegram/Discord/微信）
+  ✅ 工单系统 + 知识库管理
+  ✅ 模型 failover（OpenAI + Claude 双备）
+  ✅ 价格：内部成本（低成本替代 Intercom）
+```
+
+---
+
+## 五、关键技术差异
+
+### 5.1 多渠道接入对比
+
+| 方案 | 渠道覆盖 | 接入复杂度 | 统一管理 |
+|------|---------|----------|--------|
+| Intercom Fin | Web/FB/WhatsApp | 低（SaaS） | ✅ |
+| Zendesk | 全渠道 | 低（SaaS） | ✅ |
+| Dify | 需开发 | 高 | ⚠️ |
+| **ai-customer-service** | Widget/TG/Discord/微信 | 中 | ✅ |
+
+### 5.2 开发者场景深度对比
+
+| 方案 | API Key 核验 | Token 消耗查询 | 错误日志诊断 | 代码示例回复 |
+|------|------------|--------------|-----------|-----------|
+| Intercom Fin | ❌ | ❌ | ❌ | ⚠️ 通用 |
+| Zendesk | ❌ | ❌ | ❌ | ⚠️ 通用 |
+| **ai-customer-service** | ✅ | ✅ | ✅ | ✅ |
+
+---
+
+## 六、技术选型建议
+
+| 组件 | 推荐方案 | 理由 |
+|------|---------|------|
+| 向量数据库 | Qdrant | P99 延迟 <200ms，Rust 实现性能好，部署简单 |
+| 对话历史存储 | PostgreSQL | 持久化需求强，工单关联 |
+| 模型供应商 | OpenAI + Claude 双备 | 质量+覆盖率平衡 |
+| 多渠道接入 | 统一消息总线 | 减少耦合，channel 层薄 |
+| RAG 策略 | sentence embedding + keyword 混合 | 中文语义检索质量+关键词兜底 |