339 lines
18 KiB
Markdown
339 lines
18 KiB
Markdown
# M10 Captain AI与Copilot 功能梳理
|
||
|
||
> 版本标注：Chatwoot Enterprise v3.13+
|
||
> 模块定位：企业版核心功能，为客服团队提供AI助手（Captain）与智能副驾驶（Copilot）能力
|
||
|
||
---
|
||
|
||
## 1. Captain::Assistant CRUD — 助手模型+控制器+路由
|
||
|
||
### 功能描述
|
||
Captain Assistant 是企业版的AI助手实体，每个Account可创建多个Assistant，分别绑定不同Inbox，提供自动回复、FAQ检索、Copilot副驾驶等能力。支持CRUD全生命周期管理及Playground在线调试。
|
||
|
||
### 用户操作流程
|
||
1. 管理员进入 Settings → Captain → Assistants
|
||
2. 创建Assistant：填写名称、描述、配置（温度、产品名、功能开关）
|
||
3. 将Assistant绑定到特定Inbox（CaptainInbox关联）
|
||
4. 在Playground页面输入消息测试Assistant回复效果
|
||
5. 编辑/删除Assistant
|
||
|
||
### 涉及的API端点
|
||
| 方法 | 路径 | 说明 |
|
||
|------|------|------|
|
||
| GET | `/api/v1/accounts/{id}/captain/assistants` | 列表 |
|
||
| GET | `/api/v1/accounts/{id}/captain/assistants/{id}` | 详情 |
|
||
| POST | `/api/v1/accounts/{id}/captain/assistants` | 创建 |
|
||
| PATCH | `/api/v1/accounts/{id}/captain/assistants/{id}` | 更新 |
|
||
| DELETE | `/api/v1/accounts/{id}/captain/assistants/{id}` | 删除 |
|
||
| POST | `/api/v1/accounts/{id}/captain/assistants/{id}/playground` | Playground调试 |
|
||
| GET | `/api/v1/accounts/{id}/captain/assistants/tools` | 获取可用工具列表 |
|
||
| CRUD | `/api/v1/accounts/{id}/captain/assistants/{id}/inboxes` | 绑定/解绑Inbox |
|
||
|
||
### 涉及的数据模型+关键字段
|
||
- **captain_assistants** 表
|
||
- `id`, `account_id`(必填), `name`(必填), `description`(必填)
|
||
- `config` (jsonb): `temperature`, `feature_faq`, `feature_memory`, `feature_contact_attributes`, `product_name`
|
||
- `guardrails` (jsonb): 限制性规则
|
||
- `response_guidelines` (jsonb): 回复指导方针
|
||
- 关联：`documents` → Captain::Document, `responses` → Captain::AssistantResponse, `captain_inboxes` → CaptainInbox, `copilot_threads`, `scenarios`
|
||
|
||
### 涉及的业务逻辑
|
||
- Playground调试分两路：v2启用 → AgentRunnerService；否则 → AssistantChatService
|
||
- `available_agent_tools` 方法合并内置工具 + account下enabled的CustomTool
|
||
- Assistant创建后可作为消息sender（`messages, as: :sender`），在对话中自动回复
|
||
|
||
### 涉及的自动化/规则/事件
|
||
- Assistant创建/删除时，通过CaptainInbox自动关联/清理Inbox
|
||
- Playground调用实时LLM生成回复
|
||
|
||
### Chatwoot原实现代码路径
|
||
- `enterprise/app/models/captain/assistant.rb`
|
||
- `enterprise/app/controllers/api/v1/accounts/captain/assistants_controller.rb`
|
||
- `config/routes.rb` → namespace :captain → resources :assistants
|
||
|
||
---
|
||
|
||
## 2. Captain::Document 知识库 — 文档上传+嵌入+搜索
|
||
|
||
### 功能描述
|
||
Document是Captain的知识来源，支持两类来源：URL网页抓取和PDF文件上传。文档创建后自动触发抓取/解析Job，内容通过LLM生成FAQ（AssistantResponse），再经EmbeddingService生成向量嵌入用于语义搜索。
|
||
|
||
### 用户操作流程
|
||
1. 管理员在Assistant详情页上传知识文档（URL或PDF）
|
||
2. 系统自动抓取/解析内容，状态从 in_progress → available
|
||
3. LLM自动从文档内容生成FAQ对（AssistantResponse），并计算嵌入向量
|
||
4. 文档可手动触发重新同步（sync）
|
||
5. 在对话/Copilot中通过SearchDocumentationService语义检索
|
||
|
||
### 涉及的API端点
|
||
| 方法 | 路径 | 说明 |
|
||
|------|------|------|
|
||
| GET | `/api/v1/accounts/{id}/captain/documents` | 列表（支持过滤/搜索/分页） |
|
||
| GET | `/api/v1/accounts/{id}/captain/documents/{id}` | 详情 |
|
||
| POST | `/api/v1/accounts/{id}/captain/documents` | 创建（URL或PDF） |
|
||
| DELETE | `/api/v1/accounts/{id}/captain/documents/{id}` | 删除 |
|
||
| POST | `/api/v1/accounts/{id}/captain/documents/{id}/sync` | 手动重新同步 |
|
||
|
||
### 涉及的数据模型+关键字段
|
||
- **captain_documents** 表
|
||
- `id`, `account_id`(必填), `assistant_id`(必填)
|
||
- `external_link`(必填，URL来源), `name`, `content`(最大200K)
|
||
- `status`: in_progress(0) / available(1)
|
||
- `sync_status`: syncing(0) / synced(1) / failed(2)
|
||
- `metadata` (jsonb): `content_fingerprint`, `last_sync_error_code`, `sync_step`, `openai_file_id`
|
||
- `content_fingerprint` (string): 内容哈希，用于判断是否需要重新生成FAQ
|
||
- `pdf_file`: ActiveStorage附件（PDF类型文档）
|
||
- 关联：`responses` → Captain::AssistantResponse (as: documentable), `assistant` → Captain::Assistant
|
||
|
||
### 涉及的业务逻辑
|
||
- 创建后自动触发 `enqueue_crawl_job`（URL用FirecrawlService/SimplePageCrawlService抓取）
|
||
- PDF文档用 `PdfProcessingService` 解析
|
||
- 内容变更后通过 `enqueue_response_builder_job` → FaqGeneratorService 生成FAQ
|
||
- FAQ生成后由 `EmbeddingService` 调用RubyLLM计算向量嵌入
|
||
- 搜索时先 `TranslateQueryService` 将查询翻译为目标语言，再在approved responses中语义搜索
|
||
- 文档数量有上限限制（`LimitExceededError`）
|
||
|
||
### 涉及的自动化/规则/事件
|
||
- `after_create_commit :enqueue_crawl_job` — 自动抓取
|
||
- `after_create_commit :update_document_usage` — 更新用量统计
|
||
- `after_commit :enqueue_response_builder_job` — 自动生成FAQ+嵌入
|
||
- `after_destroy :update_document_usage` — 删除后更新用量
|
||
- 同步超时阈值：`SYNC_STALE_TIMEOUT = 2.hours`
|
||
|
||
### Chatwoot原实现代码路径
|
||
- `enterprise/app/models/captain/document.rb`
|
||
- `enterprise/app/controllers/api/v1/accounts/captain/documents_controller.rb`
|
||
- `enterprise/app/services/captain/documents/sync_service.rb`
|
||
- `enterprise/app/services/captain/documents/single_page_fetcher.rb`
|
||
- `enterprise/app/services/captain/llm/embedding_service.rb`
|
||
- `enterprise/app/services/captain/llm/faq_generator_service.rb`
|
||
|
||
---
|
||
|
||
## 3. Captain::Llm 聊天服务 — AssistantChatService+OpenAI集成
|
||
|
||
### 功能描述
|
||
AssistantChatService是Captain核心LLM对话引擎，继承BaseAiService，负责构建system prompt + 历史消息 + 工具调用链，与OpenAI（通过RubyLLM）交互生成回复。支持工具调用（function calling）循环直到获得最终文本回复。
|
||
|
||
### 用户操作流程
|
||
1. 用户在Inbox对话中发送消息
|
||
2. 系统判定需要Captain回复（通过AssistantActionClassifierService判断动作类型）
|
||
3. AssistantChatService构建消息序列：system prompt + 历史 + 用户消息 + 工具定义
|
||
4. LLM返回回复，可能包含工具调用（如search_documentation）
|
||
5. 工具执行后结果回填消息序列，再次调用LLM
|
||
6. 最终文本回复发送到对话
|
||
|
||
### 涉及的API端点
|
||
间接调用，主要通过 `POST /api/v1/accounts/{id}/captain/assistants/{id}/playground` 触发
|
||
|
||
### 涉及的数据模型+关键字段
|
||
- 依赖 `Captain::Assistant`（config, guardrails, response_guidelines）
|
||
- 依赖 `Captain::AssistantResponse`（FAQ知识对，嵌入向量）
|
||
- 依赖 `Captain::CustomTool`（自定义HTTP工具）
|
||
|
||
### 涉及的业务逻辑
|
||
- **System Prompt构建**：由 `SystemPromptsService.assistant_response_generator` 生成，包含产品名、回复指导方针、护栏规则
|
||
- **工具构建** (`build_tools`)：内置 SearchDocumentationService + account下enabled的CustomTool（→ CustomHttpTool）
|
||
- **对话循环**：`request_chat_completion` → 若返回tool_call → 执行tool → 回填结果 → 再请求 → 直到文本回复
|
||
- **消息格式**：`generate_response(additional_message:, message_history:, role:)` 拼接历史+新消息
|
||
- 继承 `Llm::BaseAiService` 使用RubyLLM与OpenAI通信
|
||
- 包含 `Captain::ChatHelper` 模块（共享辅助方法）
|
||
|
||
### 涉及的自动化/规则/事件
|
||
- Assistant自动回复触发：当Inbox配置了Captain Assistant且用户消息到达
|
||
- ActionClassifierService判断是否需要AI回复 vs 转人工
|
||
- 工具调用循环由RubyLLM的function calling机制驱动
|
||
|
||
### Chatwoot原实现代码路径
|
||
- `enterprise/app/services/captain/llm/assistant_chat_service.rb`
|
||
- `enterprise/app/services/captain/llm/system_prompts_service.rb`
|
||
- `enterprise/app/services/captain/llm/assistant_action_classifier_service.rb`
|
||
- `enterprise/app/services/captain/open_ai_message_builder_service.rb`
|
||
- `app/services/llm/base_ai_service.rb`
|
||
|
||
---
|
||
|
||
## 4. Captain::Tools 工具注册 — SearchDocumentationService+BaseTool+CustomTool
|
||
|
||
### 功能描述
|
||
Captain工具系统为LLM提供function calling能力。BaseTool是所有工具的基类（继承RubyLLM::Tool），SearchDocumentationService是内置核心工具（语义搜索知识库），CustomTool允许企业自定义HTTP API工具。ToolRegistryService负责注册和管理工具集合。
|
||
|
||
### 用户操作流程
|
||
1. 系统自动注册内置工具（search_documentation）
|
||
2. 管理员可在 Settings → Captain → Custom Tools 创建自定义HTTP工具
|
||
3. 自定义工具配置：名称、描述、HTTP方法、端点URL、参数Schema、认证方式（none/bearer/basic/api_key）
|
||
4. 工具在Assistant对话/Copilot对话中被LLM自动调用
|
||
|
||
### 涉及的API端点
|
||
| 方法 | 路径 | 说明 |
|
||
|------|------|------|
|
||
| CRUD | `/api/v1/accounts/{id}/captain/custom_tools` | 自定义工具管理 |
|
||
| POST | `/api/v1/accounts/{id}/captain/custom_tools/test` | 测试自定义工具 |
|
||
|
||
### 涉及的数据模型+关键字段
|
||
- **Captain::Tools::BaseTool** (非DB模型，继承RubyLLM::Tool)
|
||
- `assistant`, `@user` 属性
|
||
- `active?` 方法（默认true）
|
||
- `user_has_permission(permission)` 权限检查
|
||
- prepend `Captain::Tools::Instrumentation`（监控埋点）
|
||
- **captain_custom_tools** 表
|
||
- `id`, `account_id`, `slug`(唯一), `title`, `description`
|
||
- `endpoint_url`, `http_method`(GET/POST), `auth_type`(none/bearer/basic/api_key)
|
||
- `auth_config` (jsonb), `param_schema` (jsonb), `request_template`, `response_template`
|
||
- `enabled`(bool, 默认true)
|
||
- 每account上限15个（`MAX_PER_ACCOUNT = 15`）
|
||
|
||
### 涉及的业务逻辑
|
||
- **SearchDocumentationService**：接收query参数 → TranslateQueryService翻译 → 在assistant.responses.approved中语义搜索 → 格式化返回FAQ+来源链接
|
||
- **CustomHttpTool**：将CustomTool配置转为LLM可调用的工具定义 → LLM触发时执行HTTP请求 → 按response_template格式化结果
|
||
- **ToolRegistryService**：`register_tool(tool_class)` → 检查active? → 存入@tools字典 → 支持 `method_missing` 动态调用
|
||
- 工具名slug有64字符限制（OpenAI function name限制）
|
||
|
||
### 涉及的自动化/规则/事件
|
||
- CustomTool创建前自动生成slug（`before_validation :generate_slug`）
|
||
- CustomTool创建前检查数量上限（`before_create :ensure_within_limit`）
|
||
- Instrumentation模块自动记录工具调用监控数据
|
||
|
||
### Chatwoot原实现代码路径
|
||
- `enterprise/app/services/captain/tools/base_tool.rb`
|
||
- `enterprise/app/services/captain/tools/search_documentation_service.rb`
|
||
- `enterprise/app/services/captain/tools/custom_http_tool.rb`
|
||
- `enterprise/app/services/captain/tool_registry_service.rb`
|
||
- `enterprise/app/services/captain/tools/instrumentation.rb`
|
||
- `enterprise/app/models/captain/custom_tool.rb`
|
||
|
||
---
|
||
|
||
## 5. Copilot对话 — CopilotMessage+CopilotThread+ChatService
|
||
|
||
### 功能描述
|
||
Copilot是面向客服代理（Agent）的AI副驾驶，在侧边栏提供实时对话辅助。每个代理拥有独立的CopilotThread（对话线程），消息通过CopilotMessage记录，ChatService构建含上下文（当前查看对话、历史消息）+ 多工具的LLM请求。
|
||
|
||
### 用户操作流程
|
||
1. Agent在对话详情页点击Copilot侧边栏
|
||
2. 创建新Thread或继续已有Thread
|
||
3. 输入问题（如"如何处理这个客户？"）
|
||
4. Copilot根据当前查看的对话上下文+知识库搜索给出建议
|
||
5. 可在Thread中持续追问
|
||
|
||
### 涉及的API端点
|
||
| 方法 | 路径 | 说明 |
|
||
|------|------|------|
|
||
| GET | `/api/v1/accounts/{id}/captain/copilot_threads` | Thread列表（仅当前用户） |
|
||
| POST | `/api/v1/accounts/{id}/captain/copilot_threads` | 创建Thread+首条消息 |
|
||
| GET | `/api/v1/accounts/{id}/captain/copilot_threads/{id}/copilot_messages` | 消息列表 |
|
||
| POST | `/api/v1/accounts/{id}/captain/copilot_threads/{id}/copilot_messages` | 发送消息 |
|
||
|
||
### 涉及的数据模型+关键字段
|
||
- **copilot_threads** 表
|
||
- `id`, `account_id`(必填), `user_id`(必填), `assistant_id`(可关联Assistant)
|
||
- `title`(必填，默认为首条消息内容)
|
||
- **copilot_messages** 表
|
||
- `id`, `copilot_thread_id`(必填), `account_id`
|
||
- `message` (jsonb, 必填): `{ content: "..." }`
|
||
- `message_type`: user(0) / assistant(1) / assistant_thinking(2)
|
||
|
||
### 涉及的业务逻辑
|
||
- **Thread创建**：CopilotThreadsController.create 事务中同时创建Thread + 首条user消息 → enqueue_response_job
|
||
- **消息创建**：CopilotMessagesController.create 创建user消息 → `enqueue_response_job` 触发Copilot::ResponseJob
|
||
- **ResponseJob** → 调用 `Captain::Copilot::ChatService.generate_response`
|
||
- **ChatService构建**：
|
||
- system_message: `SystemPromptsService.copilot_response_generator`（含产品名+工具摘要）
|
||
- account_id_context: 注入当前account信息
|
||
- previous_history: 从copilot_thread.previous_history加载
|
||
- current_viewing_history: 如果有conversation_id，注入当前对话内容作为上下文
|
||
- **工具集**：SearchDocumentation + Copilot专用工具（GetConversation, SearchConversations, GetContact, GetArticle, SearchArticles, SearchContacts, SearchLinearIssues）
|
||
- 回复生成后 `account.increment_response_usage` 计量
|
||
|
||
### 涉及的自动化/规则/事件
|
||
- `after_create_commit :broadcast_message` — 消息创建后通过ActionCable实时推送
|
||
- CopilotMessage创建 → `enqueue_response_job` → ResponseJob异步执行
|
||
- Thread创建时检查用量限制（`usage_limits[:captain][:responses][:current_available]`）
|
||
- 用量耗尽时返回限制提示消息而非AI回复
|
||
|
||
### Chatwoot原实现代码路径
|
||
- `enterprise/app/models/copilot_thread.rb`
|
||
- `enterprise/app/models/copilot_message.rb`
|
||
- `enterprise/app/controllers/api/v1/accounts/captain/copilot_threads_controller.rb`
|
||
- `enterprise/app/controllers/api/v1/accounts/captain/copilot_messages_controller.rb`
|
||
- `enterprise/app/services/captain/copilot/chat_service.rb`
|
||
- `enterprise/app/services/captain/tools/copilot/` (7个专用工具)
|
||
|
||
---
|
||
|
||
## 6. Copilot建议 — 建议生成+嵌入搜索+对话上下文
|
||
|
||
### 功能描述
|
||
Copilot建议功能允许Agent在查看对话时一键获取AI生成的回复建议。系统基于当前对话上下文 + 知识库语义搜索 + 对话历史，自动生成针对客户问题的建议回复，Agent可直接采纳或修改后发送。
|
||
|
||
### 用户操作流程
|
||
1. Agent打开一个对话，看到客户消息
|
||
2. 点击Copilot侧边栏或"建议回复"按钮
|
||
3. 系统自动基于对话上下文生成建议
|
||
4. Agent选择采纳建议，或在此基础上编辑后发送
|
||
|
||
### 涉及的API端点
|
||
| 方法 | 路径 | 说明 |
|
||
|------|------|------|
|
||
| POST | `/api/v1/accounts/{id}/captain/tasks/reply_suggestion` | 生成回复建议 |
|
||
| POST | `/api/v1/accounts/{id}/captain/tasks/summarize` | 对话摘要 |
|
||
| POST | `/api/v1/accounts/{id}/captain/tasks/rewrite` | 重写回复 |
|
||
|
||
### 涉及的数据模型+关键字段
|
||
- 复用 `Captain::Assistant`, `Captain::AssistantResponse`（嵌入向量）
|
||
- 复用 `CopilotThread`, `CopilotMessage`
|
||
- Tasks控制器处理独立建议任务（不走Thread流程）
|
||
|
||
### 涉及的业务逻辑
|
||
- **回复建议生成**：基于当前对话最后几条消息 + SearchDocumentationService搜索相关FAQ → 构建prompt → LLM生成建议回复
|
||
- **对话摘要**：提取对话内容 → LLM压缩为关键信息摘要
|
||
- **回复重写**：Agent输入草稿 → LLM润色优化语气/格式
|
||
- **上下文注入**：`current_viewing_history(conversation_id)` 将当前对话消息注入system context
|
||
- **Copilot工具**提供对话/联系人/文章/工单检索能力，使建议基于真实数据
|
||
|
||
### 涉及的自动化/规则/事件
|
||
- 建议生成异步执行（通过Captain::Copilot::ResponseJob）
|
||
- 回复建议可配置自动触发或手动触发
|
||
- 用量限制检查：每次建议生成消耗response_usage
|
||
|
||
### Chatwoot原实现代码路径
|
||
- `enterprise/app/controllers/api/v1/accounts/captain/tasks_controller.rb`
|
||
- `enterprise/app/services/captain/copilot/chat_service.rb`
|
||
- `enterprise/app/services/captain/tools/copilot/` (7个上下文检索工具)
|
||
- `enterprise/app/services/captain/llm/search_reply_documentation_service.rb`
|
||
|
||
---
|
||
|
||
## 交叉依赖与架构总览
|
||
|
||
```
|
||
Captain::Assistant (核心实体)
|
||
├── Captain::Document (知识库)
|
||
│ ├── EmbeddingService (向量嵌入)
|
||
│ ├── FaqGeneratorService (FAQ自动生成)
|
||
│ └── AssistantResponse (FAQ对 + 向量)
|
||
├── Captain::CustomTool (自定义HTTP工具)
|
||
├── Captain::Llm::AssistantChatService (对话引擎)
|
||
│ ├── SystemPromptsService (prompt构建)
|
||
│ ├── Tools: SearchDocumentationService + CustomHttpTool
|
||
│ └── BaseAiService → RubyLLM → OpenAI
|
||
└── Copilot (副驾驶)
|
||
├── CopilotThread + CopilotMessage (对话线程)
|
||
├── Captain::Copilot::ChatService (专用引擎)
|
||
│ ├── 7个Copilot专用工具
|
||
│ └─ current_viewing_history (对话上下文注入)
|
||
└── Tasks (独立建议：reply_suggestion/summarize/rewrite)
|
||
```
|
||
|
||
### 关键技术选型
|
||
- **LLM SDK**: RubyLLM（统一OpenAI/其他Provider接口）
|
||
- **嵌入模型**: 可配置（`CAPTAIN_EMBEDDING_MODEL`），默认`LlmConstants::DEFAULT_EMBEDDING_MODEL`
|
||
- **向量搜索**: 基于AssistantResponse的嵌入向量，通过pgvector或类似机制语义检索
|
||
- **异步Job**: Sidekiq（crawl_job, response_builder_job, copilot_response_job）
|
||
- **实时推送**: ActionCable（CopilotMessage broadcast_message）
|
||
|
||
### 企业版限制
|
||
- 所有Captain/Copilot功能仅Enterprise版本可用
|
||
- Document数量上限（`LimitExceededError`）
|
||
- CustomTool每account上限15个
|
||
- Copilot回复有用量配额限制（`usage_limits[:captain][:responses][:current_available]`） |