rogee/gochat

Fork 0

Files

T

Rogee 8ac150bc7b second commit

2026-06-04 15:44:48 +08:00

18 KiB

Raw Blame History

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在线调试。

用户操作流程

管理员进入 Settings → Captain → Assistants
创建Assistant：填写名称、描述、配置（温度、产品名、功能开关）
将Assistant绑定到特定Inbox（CaptainInbox关联）
在Playground页面输入消息测试Assistant回复效果
编辑/删除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生成向量嵌入用于语义搜索。

用户操作流程

管理员在Assistant详情页上传知识文档（URL或PDF）
系统自动抓取/解析内容，状态从 in_progress → available
LLM自动从文档内容生成FAQ对（AssistantResponse），并计算嵌入向量
文档可手动触发重新同步（sync）
在对话/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）循环直到获得最终文本回复。

用户操作流程

用户在Inbox对话中发送消息
系统判定需要Captain回复（通过AssistantActionClassifierService判断动作类型）
AssistantChatService构建消息序列：system prompt + 历史 + 用户消息 + 工具定义
LLM返回回复，可能包含工具调用（如search_documentation）
工具执行后结果回填消息序列，再次调用LLM
最终文本回复发送到对话

涉及的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负责注册和管理工具集合。

用户操作流程

系统自动注册内置工具（search_documentation）
管理员可在 Settings → Captain → Custom Tools 创建自定义HTTP工具
自定义工具配置：名称、描述、HTTP方法、端点URL、参数Schema、认证方式（none/bearer/basic/api_key）
工具在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请求。

用户操作流程

Agent在对话详情页点击Copilot侧边栏
创建新Thread或继续已有Thread
输入问题（如"如何处理这个客户？"）
Copilot根据当前查看的对话上下文+知识库搜索给出建议
可在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可直接采纳或修改后发送。

用户操作流程

Agent打开一个对话，看到客户消息
点击Copilot侧边栏或"建议回复"按钮
系统自动基于对话上下文生成建议
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]）

18 KiB Raw Blame History Unescape Escape

M10 Captain AI与Copilot 功能梳理

1. Captain::Assistant CRUD — 助手模型+控制器+路由

功能描述

用户操作流程

涉及的API端点

涉及的数据模型+关键字段

涉及的业务逻辑

涉及的自动化/规则/事件

Chatwoot原实现代码路径

2. Captain::Document 知识库 — 文档上传+嵌入+搜索

功能描述

用户操作流程

涉及的API端点

涉及的数据模型+关键字段

涉及的业务逻辑

涉及的自动化/规则/事件

Chatwoot原实现代码路径

3. Captain::Llm 聊天服务 — AssistantChatService+OpenAI集成

功能描述

用户操作流程

涉及的API端点

涉及的数据模型+关键字段

涉及的业务逻辑

涉及的自动化/规则/事件

Chatwoot原实现代码路径

4. Captain::Tools 工具注册 — SearchDocumentationService+BaseTool+CustomTool

功能描述

用户操作流程

涉及的API端点

涉及的数据模型+关键字段

涉及的业务逻辑

涉及的自动化/规则/事件

Chatwoot原实现代码路径

5. Copilot对话 — CopilotMessage+CopilotThread+ChatService

功能描述

用户操作流程

涉及的API端点

涉及的数据模型+关键字段

涉及的业务逻辑

涉及的自动化/规则/事件

Chatwoot原实现代码路径

6. Copilot建议 — 建议生成+嵌入搜索+对话上下文

功能描述

用户操作流程

涉及的API端点

涉及的数据模型+关键字段

涉及的业务逻辑

涉及的自动化/规则/事件

Chatwoot原实现代码路径

交叉依赖与架构总览

关键技术选型

企业版限制

18 KiB

Raw Blame History