docs: 整理文档目录结构 — 清理过时文档、归集功能子目录、统一命名规范

清理:
- 删除 34 份过时文档（gap reports/QA临时报告/验收报告/阶段性文档）
- 删除 docs/.hermes/skills 第三方 skills 副本（16 文件）
- 删除 skills-lock.json

目录归集:
- 根目录仅保留 README.md 索引
- product/ — 产品与架构设计（PRD + ARCHITECTURE + P2设计文档 + AI/企业路线图）
- tracking/ — Chatwoot parity 开发跟踪
- requirements/ — M01-M12 模块需求
- plans/ — 历史实现计划
- parity/ — 路由 parity 与前端契约
- qa/ — QA 报告与测试计划
- ops/ — 运维部署

命名规范:
- 全小写 kebab-case，禁止全大写文件名
- product/tracking/ops 用 NN- 序号前缀
- requirements 用 MNN- 两位零填充模块号
- plans/qa 用 YYYY-MM-DD- 日期前缀
- requirements M1-M9 零填充为 M01-M09（修复字典序）

同步更新:
- backend/cmd/route_parity/main.go 路径默认值
- backend/scripts/parity_frontend_smoke.sh 报告路径
- 所有 docs 内部交叉引用
- .gitignore 排除编译产物 (backend/gochat, backend/route_parity)
- 新增迁移 000052/000053
- 前端 WS 相关修改

docs/product/08-ai-roadmap.md

@@ -0,0 +1,634 @@
+# GoChat AI 功能支持评估与开发路线图
+
+> 调研日期：2026-07-08（初版）/ 2026-07-09 更新
+> 基于代码库：main 分支 @ 805402f
+> 对标项目：Chatwoot Captain AI (enterprise edition)
+> 注：2026-07-09 状态更新 — Eino 框架已替换手写 LLM 层，多 LLM Provider（OpenAI/Anthropic）已接入，
+> Function Calling 已实现，Help Center pgvector 语义搜索已实现，AutoReplyRule 已集成到消息流程。
+
+---
+
+## 目录
+
+1. [评估摘要](#1-评估摘要)
+2. [当前 AI 基础设施盘点](#2-当前-ai-基础设施盘点)
+3. [Chatwoot AI 功能对照表](#3-chatwoot-ai-功能对照表)
+4. [关键缺口分析](#4-关键缺口分析)
+5. [开发路线图](#5-开发路线图)
+6. [风险评估与依赖](#6-风险评估与依赖)
+7. [附录：关键文件索引](#7-附录关键文件索引)
+
+---
+
+## 1. 评估摘要
+
+GoChat 已搭建了一套对标 Chatwoot Captain AI 的完整基础设施，覆盖了 LLM Provider 抽象层、
+数据模型、Service 业务逻辑、Handler/路由、前端 UI 组件和后台 Worker。**约 90% 的 AI 代码
+已经写好**，但存在若干"最后一公里"接缝未缝合的问题，导致部分功能无法实际运行。
+
+核心结论：
+
+- **可用功能**：Copilot 侧边栏对话、回复建议、会话摘要、改写润色、标签建议、跟进任务、
+  会话洞察、文档同步、批量 AI 操作、助手 CRUD/Playground、帮助中心文章 AI 翻译
+- **代码就绪但未接入**：RAG 知识库问答（路由未注册）、自动回复规则（未接入消息流程）、
+  CaptainConversationService（被 `_ =` 忽略）
+- **完全缺失**：帮助中心语义搜索、AgentBot + Captain 端到端 AI 客服、多 LLM Provider 支持
+- **配置缺口**：config.yaml 无 captain 配置段，LLM API Key 未注入，AI 功能处于"空转"状态
+
+整体评估：基础设施成熟度高（9/10），功能可用度中等（5/10），需补齐配置与接缝工作。
+
+---
+
+## 2. 当前 AI 基础设施盘点
+
+### 2.1 LLM Provider 层
+
+**文件**：`backend/internal/llm/provider.go` + `openai_provider.go`
+
+- `Provider` 接口定义三个核心能力：
+  - `ChatCompletion` — 同步对话补全
+  - `CreateEmbedding` — 文本向量化
+  - `ChatCompletionStream` — SSE 流式对话补全（callback 模式）
+- `OpenAIProvider` 实现完整：
+  - 支持自定义 `baseURL`（兼容国内厂商如火山引擎/豆包/通义千问）
+  - SSE 流式解析（自研 `sseReader` + `sseLineScanner`，处理 `[DONE]` 信号）
+  - 指数退避重试（1s→2s→4s，最多 3 次，429/5xx 可重试）
+  - API 错误结构化解析（`APIError` 类型）
+- 数据结构：`ChatRequest`/`ChatResponse`/`ChatMessage`/`EmbeddingRequest`/`EmbeddingResponse`/
+  `StreamChunk`/`ToolDefinition`/`ToolFunction`
+- **问题**：`ToolDefinition` 已定义但从未在调用时传入 LLM
+
+### 2.2 数据模型层
+
+**文件**：`backend/internal/model/captain_models.go` + `copilot_models.go` + `auto_reply_rule_models.go` + `article_embedding.go`
+
+| 模型 | 表名 | 说明 |
+|------|------|------|
+| `CaptainAssistant` | `captain_assistants` | AI 助手核心实体（config/guardrails/response_guidelines JSONB） |
+| `CaptainDocument` | `captain_documents` | 知识库文档（网页/PDF，含 content_fingerprint 去重） |
+| `CaptainAssistantResponse` | `captain_assistant_responses` | FAQ 条目，带 pgvector 1536 维 embedding |
+| `CaptainScenario` | `captain_scenarios` | 多场景 agent 配置（instruction + tools JSONB） |
+| `CaptainCustomTool` | `captain_custom_tools` | 自定义 HTTP 工具（endpoint/auth/param_schema/request_template） |
+| `CaptainInbox` | `captain_inboxes` | 助手↔收件箱绑定 |
+| `CaptainPreference` | `captain_preferences` | 账户级 AI 偏好（tone/language/auto_label/auto_reply 等） |
+| `CaptainAutoReplyRule` | `captain_auto_reply_rules` | 自动回复规则（static/llm/mixed 三模式） |
+| `CopilotThread` | `copilot_threads` | Copilot 对话线程（account_id + user_id + assistant_id） |
+| `CopilotMessage` | `copilot_messages` | 线程消息（JSONB content，支持 thinking/tool_result） |
+| `CopilotSuggestionMessage` | `copilot_suggestion_messages` | 会话级建议（reply/suggestion/summary，pending/accepted/rejected） |
+| `ArticleEmbedding` | `article_embeddings` | 帮助中心文章向量嵌入（JSONB 存储向量） |
+
+- `CopilotThread.PreviousHistory()` 方法将消息历史转为 LLM `[]ChatMessage` 格式
+- `CopilotMessage.BeforeSave()` 验证 JSONB key 白名单（content/reasoning/function_name/reply_suggestion）
+
+### 2.3 Service 层
+
+| Service | 文件 | 职责 | LLM 依赖 |
+|---------|------|------|----------|
+| `CaptainAssistantService` | `captain_assistant_service.go` | 助手 CRUD + Playground 对话 + `GenerateResponse` RAG 问答 | ✅ |
+| `CaptainTaskService` | `captain_task_service.go` | 回复建议 / 摘要 / 改写（含 Stream 版本） | ✅ |
+| `CaptainTaskExtendedService` | `captain_task_extended_service.go` | 批量标签建议 + 跟进任务 | ✅ |
+| `CopilotService` | `copilot_service.go` | Copilot 线程管理 + 异步响应生成 | ✅ |
+| `CopilotContextService` | `copilot_context_service.go` | 会话上下文组装（消息/联系人/历史） | ✅ |
+| `RAGService` | `rag_service.go` | RAG 全流程：embedding→pgvector 搜索→LLM 生成 | ✅ |
+| `ConversationInsightService` | `conversation_insight_service.go` | 参与者分析 / 行动项 / 标签建议 | ✅ |
+| `CaptainConversationService` | `captain_conversation_service.go` | 会话级 AI 自动响应（handoff 模式） | ✅ |
+| `CaptainDocumentService` | `captain_document_service.go` | 文档爬取/同步/embedding 生成 | ✅ |
+| `CaptainBulkActionService` | `captain_bulk_action_service.go` | 批量 AI 操作 | ✅ |
+| `CaptainAssistantResponseService` | `captain_assistant_response_service.go` | FAQ 生成与处理 | ✅ |
+| `SystemPromptBuilder` | `system_prompt_builder.go` | 统一 prompt 构建 | — |
+| `LLMArticleTranslationBackend` | `article_service.go` | 帮助中心文章 AI 翻译 | ✅ |
+
+### 2.4 Handler + 路由层
+
+**已注册路由**（`/api/v1/accounts/:account_id/captain/`）：
+
+```
+# Assistant CRUD + 关联
+assistants                     GET/POST/PUT/DELETE
+assistants/:id/inboxes         GET/POST/DELETE
+assistants/:id/playground      POST
+assistants/:id/documents       POST/GET/DELETE
+assistants/:id/scenarios       POST/GET/PUT/DELETE
+
+# Document / Scenario / CustomTool
+documents                      GET/POST/DELETE + /:id/sync
+scenarios                      GET/POST/PUT/DELETE
+custom_tools                   GET/POST/PUT/DELETE
+
+# Copilot
+copilot_threads                GET/POST/GET/:id/DELETE/:id
+copilot_threads/:id/copilot_messages  GET/POST
+copilot_threads/:id/messages   POST
+copilot_messages               GET/POST
+copilot/suggest_replies        POST
+copilot/summarize              POST
+copilot/translate              POST
+copilot/stream                 GET (SSE)
+
+# Tasks (AI 任务)
+tasks/reply_suggestion         POST (+ /stream SSE)
+tasks/summarize                POST (+ /stream SSE)
+tasks/rewrite                  POST (+ /stream SSE)
+tasks/label_suggestion         GET
+tasks/follow_up                GET
+
+# Insight
+conversation_insights/:id/analyze_participants   POST
+conversation_insights/:id/extract_action_items   POST
+conversation_insights/:id/suggest_labels         POST
+
+# Preference / Response / Bulk
+preferences                    GET/PUT
+assistant_responses            CRUD + /process
+bulk_actions                   POST
+```
+
+### 2.5 前端层
+
+| 组件/文件 | 路径 | 说明 |
+|-----------|------|------|
+| Captain 设置页 | `routes/dashboard/settings/captain/Index.vue` | 模型选择 + 功能开关（label_suggestion/help_center_search/audio_transcription） |
+| ModelSelector | `routes/dashboard/settings/captain/components/ModelSelector.vue` | 按 feature 选择 LLM 模型 |
+| FeatureToggle | `routes/dashboard/settings/captain/components/FeatureToggle.vue` | AI 功能开关 |
+| CopilotContainer | `components/copilot/CopilotContainer.vue` | 侧边栏 Copilot 聊天面板 |
+| Copilot (next) | `components-next/copilot/Copilot.vue` | 新版 Copilot 组件 |
+| useCaptain | `composables/useCaptain.js` | Captain 功能开关/配额/错误处理 |
+| useCopilotReply | `composables/useCopilotReply.js` | 回复建议/改写/摘要的 composable |
+| useLabelSuggestions | `composables/useLabelSuggestions.js` | 标签建议 |
+| API 客户端 | `api/captain/` | 12 个文件：assistant/document/tasks/copilotThreads/copilotMessages/preferences/scenarios/tools/bulkActions/inboxes/customTools/response |
+
+**Feature Flags**（`featureFlags.js`）：
+- `CAPTAIN` = `captain_integration`
+- `CAPTAIN_V2` = `captain_integration_v2`
+- `CAPTAIN_TASKS` = `captain_tasks`
+- `CAPTAIN_CUSTOM_TOOLS` = `custom_tools`
+- `CAPTAIN_DOCUMENT_AUTO_SYNC` = `captain_document_auto_sync`
+
+### 2.6 后台 Worker
+
+| Worker | 文件 | 任务类型 | 说明 |
+|--------|------|----------|------|
+| CaptainDocumentWorker | `captain_document_worker.go` | 6 种任务 | 文档同步/爬取/页面解析/embedding 更新/调度 |
+| CopilotResponseWorker | `copilot_response_worker.go` | 1 种任务 | 异步 Copilot 响应生成 |
+| CaptainConversationWorker | `captain_conversation_service.go` 内 | 1 种任务 | 会话响应构建（但 service 被 `_ =` 忽略） |
+
+### 2.7 配置层
+
+**文件**：`backend/internal/config/config.go`
+
+`CaptainConfig` 结构体已定义：
+```go
+type CaptainConfig struct {
+    Enabled         bool
+    LLMProvider     string  // openai, azure, custom
+    LLMModel        string  // gpt-4o, gpt-3.5-turbo
+    LLMAPIKey       string
+    LLMBaseURL      string  // 自定义端点
+    EmbeddingModel  string  // text-embedding-3-small
+    EmbeddingDims   int     // 1536
+    MaxTokens       int
+    Temperature     float64
+}
+```
+
+- `LLMConfig()` 方法将 `CaptainConfig` 转为 provider 友好格式
+- 支持热重载（`config.go` reloader 中包含 captain 字段）
+- ENV 映射：`GOCHAT_CAPTAIN_ENABLED` / `GOCHAT_CAPTAIN_LLM_PROVIDER` / `GOCHAT_CAPTAIN_LLM_MODEL` /
+  `GOCHAT_CAPTAIN_LLM_API_KEY` / `GOCHAT_CAPTAIN_LLM_BASE_URL` 等
+
+**问题**：`backend/configs/config.yaml` 中**没有 captain 配置段**，所有 Captain 字段为默认零值。
+bootstrap.go:536 创建 OpenAIProvider 时传入空 API Key 和空 BaseURL。
+
+---
+
+## 3. Chatwoot AI 功能对照表
+
+| Chatwoot Captain 功能 | GoChat 状态 | 说明 |
+|------------------------|-------------|------|
+| Captain Assistant（AI 助手配置） | ✅ 完整 | 模型/服务/handler/路由/前端全链路 |
+| Copilot（客服侧边栏 AI 助手） | ✅ 完整 | 含 SSE 流式 + 异步 Worker |
+| Reply Suggestion（回复建议） | ✅ 完整 | 含流式 + RAG 上下文 |
+| Summarize（会话摘要） | ✅ 完整 | 含流式 |
+| Rewrite（改写润色） | ✅ 完整 | 含流式，7 种操作 |
+| Label Suggestion（标签建议） | ✅ 完整 | 单会话 + 批量 |
+| Follow-up Task（跟进任务） | ✅ 完整 | 批量 |
+| Knowledge Base / RAG（知识库问答） | ⚠️ 代码完整，路由未注册 | RAGService + RAGHandler 存在但未接入 |
+| Document Sync（文档爬取同步） | ✅ 完整 | 6 种 Worker 任务 |
+| Custom Tools（Function Calling 定义） | ✅ 模型+服务完整 | 但 LLM 调用时未传 tools 参数 |
+| Captain Preferences（AI 偏好） | ✅ 完整 | tone/language/auto_label/auto_reply |
+| Auto-Reply Rules（自动回复规则） | ⚠️ 模型完整，未接入 | 模型+基础 service，无路由，无消息钩子 |
+| Conversation Insight（会话洞察） | ✅ 完整 | 参与者分析/行动项/标签 |
+| Bulk Actions（批量 AI 操作） | ✅ 完整 | |
+| Help Center 语义搜索 | ❌ 缺失 | ArticleEmbedding 表存在但无搜索方法 |
+| AgentBot + Captain（端到端 AI 客服） | ❌ 缺失 | AgentBot 仅支持 webhook 类型 |
+| Captain Conversation Auto-Response | ⚠️ 代码存在，被忽略 | bootstrap.go:594 `_ = captainConversationService` |
+| Article AI 翻译 | ✅ 完整 | LLMArticleTranslationBackend |
+| Multi-Provider LLM | ❌ 仅 OpenAI | 无 Anthropic/国内模型 provider 实现 |
+| Token 用量统计与配额 | ❌ 缺失 | 前端有 captainLimits 结构，后端无统计 |
+| AI 审计日志 | ❌ 缺失 | |
+
+---
+
+## 4. 关键缺口分析
+
+### 缺口 G1：config.yaml 缺少 captain 配置段
+
+- **影响**：所有 AI 功能无法实际调用 LLM（API Key 为空）
+- **位置**：`backend/configs/config.yaml` 缺少 captain 段；`bootstrap.go:536` 传入空值
+- **修复成本**：极低（加几行 YAML + .env 注入）
+
+### 缺口 G2：RAG 路由未注册
+
+- **影响**：知识库问答 API 无法访问
+- **位置**：`RAGHandler` 代码完整（`rag_handler.go`），但 `bootstrap.go` 未实例化
+  `RAGService`/`RAGHandler`，`router.go` 未注册 `/captain/rag/*` 路由
+- **修复成本**：低（~20 行 bootstrap + router 代码）
+
+### 缺口 G3：AutoReplyRule 未接入
+
+- **影响**：无法实现"消息进来 → AI 自动回复"
+- **位置**：`auto_reply_rule_models.go` 模型完整（static/llm/mixed），但：
+  - 无完整的条件匹配引擎
+  - 无消息接收时的规则匹配钩子
+  - 无路由注册
+- **修复成本**：中（需实现条件匹配 + 消息流程集成）
+
+### 缺口 G4：CaptainConversationService 被忽略
+
+- **影响**：会话级 AI 自动响应（handoff 模式）不可用
+- **位置**：`bootstrap.go:594` `_ = captainConversationService`
+- **修复成本**：中（需接入消息接收流程 + handoff 逻辑）
+
+### 缺口 G5：AgentBot 仅支持 Webhook
+
+- **影响**：无法实现"AgentBot 绑定 Captain Assistant → 端到端 AI 客服"
+- **位置**：`agent_bot.go` 只有 webhook 推送模式
+- **修复成本**：中高（需扩展 AgentBot 类型 + 消息路由）
+
+### 缺口 G6：Help Center 语义搜索缺失
+
+- **影响**：帮助中心文章无法语义搜索
+- **位置**：`ArticleEmbedding` 表存在，`article_service.go` 无搜索方法
+- **修复成本**：中（需实现 embedding 生成 + pgvector 搜索 + API + 前端）
+
+### 缺口 G7：Function Calling 未实际使用
+
+- **影响**：CustomTool 定义了但 LLM 调用时未传 tools 参数，AI 无法调用工具
+- **位置**：`llm/provider.go` 的 `ToolDefinition` 已定义；
+  `captain_task_service.go` / `captain_conversation_service.go` 的 `ChatRequest` 未设置 `Tools` 字段
+- **修复成本**：中（需实现 tool_call 循环 + HTTP 执行 + 结果回传）
+
+### 缺口 G8：多 LLM Provider 支持
+
+- **影响**：仅支持 OpenAI 兼容 API，无法直接使用 Anthropic/本地模型
+- **位置**：`llm/` 下只有 `openai_provider.go`
+- **修复成本**：中（每个 provider ~200 行实现 + 接口适配）
+
+---
+
+## 5. 开发路线图
+
+### 阶段 1：激活现有 AI 功能（P0，1-2 天）
+
+**目标**：让已写好的 90% 代码真正跑起来，实现"配置即可用"。
+
+**前提**：需要一个可用的 LLM API Key（OpenAI 或兼容端点）。
+
+#### 任务 1.1：config.yaml 添加 captain 配置段
+
+**文件**：`backend/configs/config.yaml`
+
+```yaml
+captain:
+  enabled: true
+  llm_provider: "openai"          # openai, azure, custom
+  llm_model: "gpt-4o-mini"        # 可按需改为 gpt-4o / gpt-3.5-turbo
+  llm_api_key: ""                 # 通过 .env: GOCHAT_CAPTAIN_LLM_API_KEY 注入
+  llm_base_url: "https://api.openai.com/v1"  # 国内可改为火山引擎/豆芽等端点
+  embedding_model: "text-embedding-3-small"
+  embedding_dims: 1536
+  max_tokens: 1024
+  temperature: 0.7
+```
+
+同时更新 `config.dev.yaml` 和 `config.prod.yaml` 的 captain 段（如有）。
+
+**验收**：`go run cmd/gochat/main.go serve` 启动后，日志输出 LLM provider 初始化成功。
+
+#### 任务 1.2：注册 RAG 路由
+
+**文件修改**：
+
+1. `backend/internal/app/bootstrap.go`：
+   - 实例化 `RAGService`（注入 `captainAssistantResponseRepo` + `captainAssistantRepo` + `llmProvider`）
+   - 实例化 `RAGHandler`（注入 `RAGService`）
+   - 添加到 `Handlers` 结构体
+
+2. `backend/internal/router/router.go`：
+   ```go
+   // RAG Knowledge Base Q&A
+   rag := captain.Group("/rag")
+   {
+       rag.POST("/query", h.RAG.Query)
+       rag.POST("/index/:response_id", h.RAG.IndexResponse)
+   }
+   ```
+
+**验收**：`curl -X POST /api/v1/accounts/1/captain/rag/query -d '{"assistant_id":1,"question":"test"}'`
+返回非 404。
+
+#### 任务 1.3：取消 CaptainConversationService 忽略
+
+**文件**：`backend/internal/app/bootstrap.go:594`
+
+将 `_ = captainConversationService` 改为注入到 Handlers 或消息处理流程。
+
+最小改动：将其传入 `CaptainAssistantHandler` 或新建一个 handler 方法，
+供后续阶段 2 的 AgentBot 集成使用。
+
+**验收**：编译通过，`captainConversationService` 不再被忽略。
+
+#### 任务 1.4：端到端验证
+
+配置真实 LLM API Key 后测试：
+1. Playground 对话：`POST /captain/assistants/:id/playground`
+2. 回复建议：`POST /captain/tasks/reply_suggestion`
+3. RAG 问答：`POST /captain/rag/query`
+4. Copilot 流式：`GET /captain/copilot/stream`
+5. 前端 Copilot 面板对话
+
+**交付物**：AI 功能在开发环境完整可用。
+
+---
+
+### 阶段 2：自动回复与端到端 AI 客服（P1，3-5 天）
+
+**目标**：实现"客户消息进来 → AI 自动响应"的闭环。
+
+#### 任务 2.1：AutoReplyRule 完整接入
+
+**子任务**：
+
+1. **条件匹配引擎**（`auto_reply_rule_service.go`）：
+   - 实现 `MatchRules(ctx, accountID, conversationID, messageContent) ([]CaptainAutoReplyRule, error)`
+   - 支持 condition 字段：`message_content`（contains/regex/equals）、`sender_type`、
+     `conversation_status`、`language`、`keywords`
+   - 按 priority 排序，返回第一个匹配的规则
+
+2. **消息钩子集成**：
+   - 在消息接收流程（`channel/incoming.go` 或 `message_service.go`）中，
+     消息入库后调用 `AutoReplyRuleService.MatchRules`
+   - 匹配到规则时：
+     - `static` 模式：直接发送 `ResponseText`
+     - `llm` 模式：调用 `CaptainAssistantService.GenerateResponse` 生成回复
+     - `mixed` 模式：static 前缀 + LLM 正文
+   - 尊重 `DelaySeconds` 和 `OneTimeOnly` 配置
+   - 通过 WorkerPool 异步执行（避免阻塞消息接收）
+
+3. **路由注册**：
+   ```go
+   autoReplyRules := captain.Group("/auto_reply_rules")
+   {
+       autoReplyRules.GET("", h.AutoReplyRule.List)
+       autoReplyRules.POST("", h.AutoReplyRule.Create)
+       autoReplyRules.GET("/:rule_id", h.AutoReplyRule.Get)
+       autoReplyRules.PUT("/:rule_id", h.AutoReplyRule.Update)
+       autoReplyRules.DELETE("/:rule_id", h.AutoReplyRule.Delete)
+   }
+   ```
+
+4. **前端**：
+   - 复用 Chatwoot 前端 auto-reply 设置页（如已 vendored）
+   - 新增 API 客户端 `api/captain/autoReplyRules.js`
+
+**验收**：创建一条 llm 模式规则 → 发送匹配消息 → AI 自动回复。
+
+#### 任务 2.2：AgentBot + Captain 集成
+
+**子任务**：
+
+1. **扩展 AgentBot 模型**（`agent_bot.go`）：
+   - 新增 `BotType` 字段：`webhook`（现有） / `captain`（新增）
+   - `captain` 类型时关联 `AssistantID`
+
+2. **消息路由**：
+   - 在消息分配逻辑中，当 inbox 的 AgentBot 类型为 `captain` 时，
+     消息直接路由到 `CaptainConversationService.BuildConversationResponseByAccount`
+   - AI 生成的回复作为 `agent_bot` 消息发送到会话
+
+3. **Handoff 逻辑**：
+   - `CaptainConversationResponse.Action == "handoff"` 时，将会话转给人工客服
+   - 更新会话 status + assignee
+
+4. **前端**：
+   - AgentBot 管理页支持选择 `captain` 类型 + 关联 Assistant
+
+**验收**：配置一个 captain 类型 AgentBot → 客户发消息 → AI 自动回复 → AI 判断需转人工时 handoff。
+
+#### 任务 2.3：CaptainConversationService 完整接入
+
+**子任务**：
+
+1. **工具调用实现**：
+   - 将 `CaptainCustomTool` 列表转为 `llm.ToolDefinition` 传入 `ChatRequest.Tools`
+   - 解析 LLM 返回的 `tool_call` → 执行 HTTP 请求（按 CustomTool 的 endpoint/auth/template）
+   - 将 tool 结果回传 LLM → 继续生成
+
+2. **可用工具**（`AvailableTools` 已定义 7 个）：
+   - `add_contact_note` / `add_private_note` / `update_priority`
+   - `add_label_to_conversation` / `faq_lookup` / `resolve_conversation` / `handoff`
+   - 实现每个工具的执行函数
+
+**验收**：AI 能在对话中调用自定义工具（如查询订单、添加标签）。
+
+---
+
+### 阶段 3：增强 AI 能力深度（P2，1-2 周）
+
+#### 任务 3.1：Help Center 语义搜索
+
+**子任务**：
+
+1. `article_service.go` 添加 `SearchByEmbedding(ctx, query, limit)` 方法
+   - 调用 `llmProvider.CreateEmbedding` 生成查询向量
+   - pgvector 余弦相似度搜索 `ArticleEmbedding` 表
+2. 文章创建/更新时自动生成 embedding（通过 Worker 异步）
+3. API：`GET /api/v1/portals/:portal_id/articles/search?q=...`
+4. 前端帮助中心搜索框接入
+
+**验收**：搜索"如何重置密码"能找到相关文章（即使标题不含"重置"）。
+
+#### 任务 3.2：Function Calling 完整实现
+
+详见阶段 2 任务 2.3 的工具调用实现。此阶段将其推广到所有 AI 服务：
+- `CopilotService` — Copilot 对话中可调用工具
+- `CaptainTaskService` — 回复建议时可调用 FAQ 查询工具
+- `CaptainAssistantService.GenerateResponse` — Playground 对话中可调用工具
+
+#### 任务 3.3：多 LLM Provider 支持
+
+**子任务**：
+
+1. `llm/anthropic_provider.go` — Claude 系列（不同 API 格式，需适配）
+2. `llm/volcengine_provider.go` — 火山引擎/豆包（OpenAI 兼容，可能只需 baseURL 配置）
+3. `llm/qwen_provider.go` — 通义千问（OpenAI 兼容）
+4. Provider 工厂函数：根据 `config.captain.llm_provider` 选择实现
+5. 前端 `ModelSelector` 已有 UI，后端按 feature（editor/assistant/copilot）支持不同模型
+
+**验收**：配置 `llm_provider: "anthropic"` 后，AI 功能使用 Claude 模型。
+
+#### 任务 3.4：上下文窗口优化
+
+**子任务**：
+
+1. `CopilotContextService` 实现 token 计数（tiktoken Go 库或近似估算）
+2. 滑动窗口截断：超过 token 上限时，截断早期消息
+3. 长会话自动摘要：超过阈值时，用 LLM 摘要历史消息作为 system 上下文
+4. 配置项：`captain.max_context_tokens`（默认 4096）
+
+**验收**：100+ 条消息的长会话不会超出 token 限制，AI 仍能理解上下文。
+
+---
+
+### 阶段 4：企业级能力（P3，2-4 周，按需）
+
+#### 任务 4.1：AI 用量统计与配额
+
+- 按 account/user 统计 token 消耗（prompt_tokens + completion_tokens）
+- 存储到 `captain_usage_logs` 表
+- 配额限制：前端 `captainLimits` 结构已存在，后端实现拦截逻辑
+- 用量仪表盘：`GET /captain/usage` 返回统计数据
+- 前端设置页展示用量进度条
+
+#### 任务 4.2：AI 响应质量管控
+
+- `CopilotSuggestionMessage` 的 `accepted`/`rejected` 状态反馈循环
+- 基于反馈优化 prompt（few-shot 示例注入：被接受的回复作为正例）
+- A/B 测试框架：同一请求发到两个模型/prompt 配置，比较接受率
+- 质量指标：接受率、拒绝率、编辑率（用户发送前修改了多少）
+
+#### 任务 4.3：多语言 AI
+
+- `CaptainPreference.Language` 传入 LLM system prompt
+- 回复建议/摘要/改写尊重目标语言
+- Help Center 文章跨语言语义搜索（embedding 包含语言信息）
+- Auto-Reply Rule 的 `language` 条件匹配
+
+#### 任务 4.4：AI 审计日志
+
+- 记录每次 AI 调用：prompt / response / model / token 消耗 / user / timestamp / feature
+- 存储到 `captain_audit_logs` 表
+- API：`GET /captain/audit_logs`（管理员可见）
+- 合规审计支持：导出 CSV / 按时间范围筛选
+
+---
+
+## 6. 风险评估与依赖
+
+### 6.1 技术风险
+
+| 风险 | 影响 | 缓解措施 |
+|------|------|----------|
+| LLM API 调用超时/失败 | AI 功能不可用 | 已有重试机制（3 次指数退避）；需加 fallback 策略（降级到静态回复） |
+| pgvector 维度不匹配 | RAG 搜索失败 | 当前固定 1536 维（text-embedding-3-small）；更换 embedding 模型时需迁移 |
+| Token 消耗成本 | 生产环境费用 | 阶段 4 实现配额限制；阶段 1-3 开发环境用 gpt-4o-mini 控制成本 |
+| SSE 连接稳定性 | 流式响应中断 | 已有 `X-Accel-Buffering: no`；需加心跳机制和断线重连 |
+| 并发 LLM 调用 | 速率限制 | 需实现请求队列 + 限流（令牌桶） |
+
+### 6.2 外部依赖
+
+| 依赖 | 用途 | 状态 |
+|------|------|------|
+| LLM API（OpenAI/兼容） | Chat + Embedding | 需配置 API Key |
+| pgvector 扩展 | 向量搜索 | ✅ 已安装（PG 17 + pgvector） |
+| 帮助中心爬取 | 文档同步 | 需 HTTP 客户端（已有 resty） |
+
+### 6.3 前端依赖
+
+前端代码来自 Chatwoot Vue 3 vendored，AI 相关 UI 组件已存在（CopilotContainer、Captain 设置页、
+ModelSelector、FeatureToggle）。阶段 1-2 的前端改动极小，主要是确保 API 端点与前端调用路径一致。
+
+---
+
+## 7. 附录：关键文件索引
+
+### 后端
+
+| 文件 | 说明 |
+|------|------|
+| `backend/internal/llm/provider.go` | LLM Provider 接口 + 数据结构 |
+| `backend/internal/llm/openai_provider.go` | OpenAI 兼容 Provider 实现 |
+| `backend/internal/model/captain_models.go` | Captain 全部数据模型 |
+| `backend/internal/model/copilot_models.go` | Copilot 线程/消息/建议模型 |
+| `backend/internal/model/auto_reply_rule_models.go` | 自动回复规则模型 |
+| `backend/internal/model/article_embedding.go` | 帮助中心文章 embedding |
+| `backend/internal/config/config.go` | CaptainConfig 配置结构 |
+| `backend/internal/app/bootstrap.go` | 依赖注入（LLM Provider + Captain Services） |
+| `backend/internal/router/router.go` | 路由注册（captain 命名空间 ~L1319-1489） |
+| `backend/internal/service/captain_assistant_service.go` | 助手 CRUD + Playground + RAG |
+| `backend/internal/service/captain_task_service.go` | 回复建议/摘要/改写（含 Stream） |
+| `backend/internal/service/captain_task_extended_service.go` | 批量标签/跟进 |
+| `backend/internal/service/copilot_service.go` | Copilot 线程管理 |
+| `backend/internal/service/copilot_context_service.go` | 会话上下文组装 |
+| `backend/internal/service/rag_service.go` | RAG 全流程 |
+| `backend/internal/service/conversation_insight_service.go` | 会话洞察 |
+| `backend/internal/service/captain_conversation_service.go` | 会话级 AI 响应（被忽略） |
+| `backend/internal/service/captain_document_service.go` | 文档同步 |
+| `backend/internal/service/captain_document_worker.go` | 文档 Worker |
+| `backend/internal/service/copilot_response_worker.go` | Copilot 响应 Worker |
+| `backend/internal/service/system_prompt_builder.go` | Prompt 构建 |
+| `backend/internal/handler/api/v1/rag_handler.go` | RAG Handler（未接入） |
+| `backend/internal/handler/api/v1/sse_stream_handler.go` | SSE 流式 Handler |
+| `backend/internal/handler/api/v1/captain_assistant_handler.go` | 助手 Handler |
+| `backend/internal/handler/api/v1/captain_task_handler_test.go` | 任务 Handler 测试 |
+| `backend/internal/handler/api/v1/auto_reply_rule_handler.go` | 自动回复规则 Handler |
+
+### 前端
+
+| 文件 | 说明 |
+|------|------|
+| `frontend/app/javascript/dashboard/routes/dashboard/settings/captain/Index.vue` | Captain 设置页 |
+| `frontend/app/javascript/dashboard/routes/dashboard/settings/captain/components/ModelDropdown.vue` | 模型下拉选择 |
+| `frontend/app/javascript/dashboard/components/copilot/CopilotContainer.vue` | Copilot 侧边栏 |
+| `frontend/app/javascript/dashboard/components-next/copilot/Copilot.vue` | 新版 Copilot 组件 |
+| `frontend/app/javascript/dashboard/composables/useCaptain.js` | Captain composable |
+| `frontend/app/javascript/dashboard/composables/useCopilotReply.js` | 回复建议 composable |
+| `frontend/app/javascript/dashboard/composables/useLabelSuggestions.js` | 标签建议 composable |
+| `frontend/app/javascript/dashboard/api/captain/*.js` | 12 个 API 客户端 |
+| `frontend/app/javascript/dashboard/featureFlags.js` | Feature flags 定义 |
+
+### 配置
+
+| 文件 | 说明 |
+|------|------|
+| `backend/configs/config.yaml` | 基础配置（**缺少 captain 段**） |
+| `backend/internal/config/config.go` | CaptainConfig 结构体 + ENV 映射 |
+
+### 文档
+
+| 文件 | 说明 |
+|------|------|
+| `docs/requirements/M10-captain-and-copilot.md` | Captain AI 与 Copilot 功能需求梳理 |
+| `docs/product/01-product-requirements.md` | 产品需求文档 |
+
+---
+
+## 路线图时间线总览
+
+```
+阶段 1 (P0, 1-2天)     阶段 2 (P1, 3-5天)      阶段 3 (P2, 1-2周)       阶段 4 (P3, 2-4周)
+┌─────────────────┐   ┌─────────────────┐     ┌─────────────────┐     ┌─────────────────┐
+│ 1.1 config.yaml │   │ 2.1 AutoReply   │     │ 3.1 HC 语义搜索 │     │ 4.1 用量统计    │
+│     captain 段  │   │     规则接入     │     │ 3.2 Function    │     │ 4.2 质量管控    │
+│ 1.2 RAG 路由    │   │ 2.2 AgentBot +  │     │     Calling 推广│     │ 4.3 多语言 AI   │
+│ 1.3 取消忽略    │   │     Captain 集成 │     │ 3.3 多 Provider │     │ 4.4 审计日志    │
+│ 1.4 端到端验证  │   │ 2.3 工具调用实现 │     │ 3.4 上下文优化  │     │                 │
+└─────────────────┘   └─────────────────┘     └─────────────────┘     └─────────────────┘
+  ▲ 激活现有功能        ▲ 自动回复闭环          ▲ 智能化增强            ▲ 企业级能力
+  │                     │                       │                       │
+  └── 最高优先级 ───────┴── 核心价值 ──────────┴── 渐进增强 ───────────┴── 按需实现
+```
+
+---
+
+*文档结束。如需开始执行阶段 1 的修改，请告知。*