Coco Server 中的 AI Agent:从会话 API 到 RAG + 工具/MCP + Deep Research 的端到端链路
本文基于当前仓库代码,梳理 Coco 的 AI Agent 能力如何在后端 Go 服务与前端聊天组件之间协作:
- 包括 Assistant 配置模型、
- 会话/消息存储、
- HTTP Streaming 输出、
- RAG 检索增强、
- 工具调用(内置 Tools + MCP Server)、
- 以及 Deep Think / Deep Research 两类更复杂的 Agent 工作流。
1. 总体架构(模块视角)
Agent 的主链路可以概括为:
Browser(UI) -> /chat/_create 或 /chat/:session/_chat
-> 生成 user message(持久化)
-> 启动异步处理任务(可取消)
-> (可选) history -> tools/mcp -> search -> deep pipeline
-> LLM streaming chunk -> 持久化 assistant message -> END
后端关键模块:
- 领域模型(Assistant 配置、chat settings、tool/mcp/datasource 等):assistant.go
- 对外 API(会话/聊天/assistant CRUD 与 _ask):init.go / session.go
- Agent 主执行管线(simple / deep_think / deep_research 分支):background_job.go
- RAG 上下文(从请求参数聚合开关、datasource/mcp 交集、provider 解析):rag_context.go
- LLM 输出(Streaming + reasoning/think 分块):llm_generate.go
- 工具调用(内置工具 + MCP server 客户端适配):call_mcp_tools.go
- 企业内搜工具(直接走 document.QueryDocuments):enterprise_search.go
- 文档检索与权限过滤(RAG 的检索底座之一):service.go
2. Assistant:Agent 的可配置大脑
2.1 核心 Assistant 配置模型
Assistant 的配置集中在 Assistant:
Type:"simple" | "deep_think" | "deep_research" | ...AnsweringModel: 回答模型(provider_id / name / settings / prompt)Datasource: 数据源开关 + ids + filterToolsConfig: 内置工具开关(calculator / wikipedia / duckduckgo / scraper)MCPConfig: MCP server 列表、是否默认启用、最大迭代等ChatSettings: greeting、建议问题、history 策略(条数/压缩阈值/summary)
Deep 模式配置:
- Deep Think:
DeepThinkConfig(意图分析模型、挑文档模型、是否挑 datasource/tools 等)assistant.go - Deep Research:
DeepResearchConfig(规划/研究/综合/报告/播客等多模型配置与执行参数)assistant.go
仓库提供了 Deep Research 默认值(偏开箱即用):DefaultDeepResearchConfig
2.2 Assistant API 形态(仓库内文档)
仓库自带 assistant API 示例与 streaming 说明:assistant.md
3. API 层:会话/消息/assistant 的入口与 Streaming 协议
3.1 路由与权限
Assistant 模块注册 UI API,并通过 api.RequirePermission(...) 强制权限:
modules/assistant/api/init.go
核心接口:
POST /chat/_create:创建会话(可带首条消息)POST /chat/:session_id/_chat:往会话里发消息(Streaming)GET /chat/:session_id/_history:拉取消息历史POST /chat/:session_id/_cancel?message_id=...:取消某条消息的回复任务POST /assistant/:id/_ask:不显式指定 session 的提问入口(仍会创建/写入 session 与消息)
实现入口见:session.go
3.2 HTTP Streaming 的输出形态(Chunked JSON)
以 sendChatMessageV2 为例,流程是:
- 先保存 user message
- 立即
200返回第一段 JSON(包含新建消息的_id/_source) - 后续持续
json.Encoder.Encode(...)输出 chunk - 最终发送一个
system: ReplyEnd的结束 chunk,并持久化 assistant message
对应实现:
- API 入口:sendChatMessageV2
- 异步执行 + 最终落库 + END chunk:ProcessMessageAsync
取消机制:
- API:
cancelReplyMessage - 任务登记:API 中把
CancelFunc放入InflightMessages(见sendChatMessageV2/createChatSession/askAssistant的 Store 逻辑)
4. RAGContext:把请求开关 + assistant 配置合成一次 Agent 任务的上下文
每次消息处理前都会构建 RAGContext:
NewRagContext
它做了几件很关键的事情:
- 从 URL query 获取开关与参数:
search(是否检索数据源)deep_thinkingmcpdatasource/category/subcategory/rich_category/tagsmcp_servers
- 读取
APP-INTEGRATION-ID(即core.HeaderIntegrationID)作为集成来源标识:validate.go - 对 datasource 与 mcp_servers 做交集裁剪:确保用户请求范围不会越过 assistant 配置允许的范围
- 解析 answering model provider,并把 provider 缓存在 context 内(用于补齐模型能力,例如 reasoning)
5. Agent 主执行管线:simple / deep_think / deep_research 三分支
核心分发点在:
ProcessMessageAsync
公共步骤:
params.InputValues["query"] = reqMsg.Message- history:按
ChatSettings.HistoryMessage.Number拉取最近消息并塞进模板变量(同时构造 langchaingo 的 ChatMessageHistory):FetchSessionHistory
5.1 Simple(默认)
路径:default 分支
- 可选:工具调用(Tools/MCP)
- 可选:检索数据源(SearchDB + Datasource enabled)
- 最后:拼 prompt,调用 LLM,streaming 输出
实现:
- 主分支:background_job.go
- 最终生成(含 context 拼装:history/references/tools_output):GenerateResponse
5.2 Deep Think(深度思考/深搜)
路径:case core.AssistantTypeDeepThink -> RunDeepSearchTask
关键特性:
- 可把 datasource 列表、mcp server 列表以字符串形式塞给模型(用于让模型决定选哪些)
- 先做 Query Intent(意图分析):决定是否需要网络检索、是否需要调用工具
- 文档数量多时会二次精选并做 “in depth” 抓取(
PickingDocuments/FetchDocumentInDepth)
代码入口:
- 意图分析:
langchain.ProcessQueryIntent(入口在 deep_search)init.go - 深搜整体:deep_search/init.go
5.3 Deep Research(研究型 Agent,带规划/执行/报告)
路径:case core.AssistantTypeDeepResearch -> deep_research_v2.RunDeepResearchV2(...)
调用点:background_job.go
Deep Research v2 使用 langgraphgo 构建有向图工作流:
并且有一个 “内部优先 + 外部补充” 的搜索管理器:
- 内搜:EnterpriseSearchTool
- 外搜:TavilySearchTool
见:search_manager.go
6. RAG(检索增强)链路:数据从哪里来、怎么被检索
6.1 文档数据如何进入系统(Connectors -> Document)
仓库里大量 connectors 会把外部系统内容转成 core.Document 并进入 pipeline/收集流程,例如:
- 飞书:构造
core.Document,带 categories/hierarchy path:feishu/plugin.go - Dropbox:构造 Document、path hierarchy:dropbox/files.go
文档 API 与 refine(URL 转 preview、icon fallback 等):
6.2 检索:QueryDocuments(含权限/数据源过滤/检索模式)
Agent 内搜与 RAG 初筛依赖 document.QueryDocuments:
- 实现:service.go
能力要点:
- 支持
searchType:"semantic":走 embedding 字段ai_insights.embedding.embedding1024"hybrid":文本 fuzziness + semantic 组合"keyword":默认文本检索
- datasource 权限过滤与集成过滤:
BuildDatasourceFilter(...)会把 “用户自有 + 分享 + integration 允许 + query 指定” 合并/求交集,并过滤 disabled datasource
代码:BuildDatasourceFilter
Agent 在 simple/deep_think 分支里调用的初筛检索:
7. 工具系统:Built-in Tools + MCP Servers(Agent 的行动能力)
7.1 Built-in Tools
当 assistant.ToolsConfig.Enabled 为 true,会装配 langchaingo 的工具:
- Calculator / Wikipedia / Duckduckgo / Scraper
见:CallLLMTools
7.2 MCP Servers(多协议客户端 + LangChain 适配)
当 mcp=true 且 assistant 启用 MCP,并且 mcp_servers 与 assistant 的 MCP ids 有交集时,会初始化 MCP client。
支持协议(按代码分支):
- Streamable HTTP:
client.NewStreamableHttpClient(cfg.URL) - SSE:
client.NewSSEMCPClient(cfg.URL)+Start - Stdio:
client.NewStdioMCPClient(cfg.Command, envs, cfg.Args...)+Start
见:call_mcp_tools.go
8. Streaming 分块:Response / Think 的双通道输出
LLM streaming 的核心在 GenerateResponse:
- 先发送一个 assistant response 的空 chunk(seq=0),作为开始信号
- 如果模型支持 reasoning,则使用
WithStreamingReasoningFunc:reasoningChunk->common.Thinkchunk->common.Response
- 否则使用
WithStreamingFunc仅输出common.Response
最终用 defer 把累计的 messageBuffer 写入 replyMsg.Message,并在 ProcessMessageAsync 的 defer 中落库 + ReplyEnd。
9. 权限/认证:Agent 能力的安全边界
9.1 请求侧认证方式(四选一)
core.ValidateLogin 会按顺序尝试:
- Session access token(cookie session)
Authorization: Bearer <jwt>X-API-TOKEN: <token>(KV 存储的 access token)APP-INTEGRATION-ID(integration guest run-as)
见:validate.go
Auth Filter 会把 claims 注入 context,并加载用户权限集合:
9.2 接口级权限
assistant/chat/document 等接口都通过 api.RequirePermission(...) 做鉴权(见第 3 节 init.go)。前端的权限文案映射也在仓库里可见:
10. 可验证的行为:仓库 DSL 测试用例
仓库内已有针对 assistant/chat 的 DSL 场景用例(包括创建会话、分享/可见性等):
这些用例也能反向说明系统的权限 + 资源共享边界如何影响 assistant 的可见性与可用性。
11. 一句话总结
- Assistant 是 Agent 的配置载体:决定用什么模型、能访问哪些 datasource、能用哪些 tools/MCP、history 策略是什么。
- API 层提供 HTTP Streaming:前端能实时接收 token/think 分块,并可取消进行中的任务。
- Agent 执行是可插拔分支:simple(RAG + 生成)、deep_think(意图分析 + 二次精选 + 深挖)、deep_research(langgraph 工作流)。
- 检索与权限耦合在 document.QueryDocuments:datasource/integration/分享权限共同决定 RAG 能看到什么。
