Kuse Cowork进阶原理:MessageBuilder如何组装请求、解析执行计划并追踪每一步进度

原创2026-10-29 09:31:26880 阅读

Kuse Cowork进阶原理:MessageBuilder如何组装请求、解析执行计划并追踪每一步进度

Kuse Cowork 是一款开源、轻量的桌面 AI 协同工作智能体(Cowork Agent),是 Claude Cowork 的模型无关开源替代品。本文深入剖析其 Rust 后端的核心机制:MessageBuilder 如何组装大模型请求、执行计划如何被解析、每一步进度又如何被实时追踪,帮助新手理解一个 AI Agent 的完整工作原理。

一、项目背景:先认识 Agent 的四大模块

Kuse Cowork 采用 Tauri + Rust 构建后端,纯 Rust 实现 Agent 核心,支持 BYOK(自带 API Key),可对接 Anthropic、OpenAI、Google Gemini 乃至本地模型 🚀

理解本文之前,先认识后端的核心目录结构(位于 src-tauri/src/):

模块 路径 职责
Agent 核心循环 src-tauri/src/agent/ 组装请求、调用模型、执行工具、追踪进度
内置工具集 src-tauri/src/tools/ 读写文件、执行命令、搜索代码等 9 个工具
MCP 协议支持 src-tauri/src/mcp/ 接入外部 MCP 工具服务器
Skills 技能系统 src-tauri/src/skills/ 扩展文档处理等预设技能(docx/pdf/pptx/xlsx)

其中 agent/ 模块由四个文件协作完成(见 mod.rs):

二、MessageBuilder 是什么:不是"消息",而是完整请求的组装流水线

很多人误以为 MessageBuilder 只是拼一条聊天消息。实际上,它的职责是把"系统设定 + 全部工具 + 完整对话历史"打包成一个可直接发送的 API 请求 📦

它本身只持有 5 个字段(见 message_builder.rs#L33-L39):

字段 作用
config Agent 配置:系统提示词、最大轮数、工具白名单、项目路径
model 要调用的模型名称
max_tokens 单次回复的最大 token 数
temperature 温度参数(可选)
mcp_manager MCP 管理器(可选,用于注入外部工具)

采用典型的 Builder 设计模式:先通过 new() 创建基础实例,再调用 with_mcp_manager() 按需挂接 MCP 能力。这个组合在 agent_loop.rs#L54-L59 中完成,一次构造、每轮复用。

1. 内置工具:按白名单筛选,而非全量暴露

组装请求的第一步是收集工具定义。调用 tools::get_tools() 时并非把所有工具一股脑塞给模型,而是按 allowed_tools 白名单过滤(见 tools/mod.rs#L31-L35)。

默认白名单(定义在 types.rs#L100-L120 的 AgentConfig)包含 10 个工具:

read_file、write_file、edit_file、bash、glob、grep、list_dir、docker_run、docker_list、docker_images

这样做的好处是:模型只能看到被允许的工具,既控制提示词体积,也收紧了权限边界。

2. MCP 工具:只收"在线"服务器的工具,并统一改名

如果配置了 MCP 管理器,get_mcp_tools 会遍历所有 MCP 服务器的连接状态,只收集状态为 Connected 的服务器上的工具——离线的服务器不会污染请求。

每个 MCP 工具还会被"翻译"成统一的命名规则(见 message_builder.rs#L94-L103):

  • 工具名统一改写为 mcp_{服务器ID}_{工具名} 格式,其中的 - 和 : 替换为 _,保证名字在各类 API 中都合法
  • 描述自动追加来源标注,如 (MCP tool from server '文件服务'),让模型清楚工具的出处

这个前缀命名与 tool_executor.rs#L28 中的路由规则一一对应:模型一旦调用 mcp_ 开头的工具,执行器就知道该转发给 MCP 管理器。

3. 消息转换:三种内容形态统一为 API 格式

对话历史中的每条消息内容都有三种可能形态(AgentContent,定义在 types.rs#L83-L89):

形态 含义 典型场景
Text 纯文本 用户输入的普通指令
Blocks 文本 + 工具调用块混合 模型回复"边说边调用工具"
ToolResults 一批工具执行结果 把执行结果"回喂"给模型

convert_messages 会把这三者统一转成 API 消息格式,其中后两种会被序列化为内容块数组——这正是"多轮工具调用"能持续进行的关键:工具的调用请求和返回结果都以消息的形式留在对话里。

4. 组装产物:一个"万能"请求结构

三步之后,build_request()(message_builder.rs#L57-L77)产出最终的 ClaudeApiRequest(message_builder.rs#L7-L18):

字段 说明
model / max_tokens / temperature 模型与生成参数
system 系统提示词(含计划输出规范的"行为宪法")
messages 转换后的完整对话历史
tools 内置工具 + MCP 工具的合并列表(空时自动省略)
stream 固定为 true,启用流式输出

有意思的是:这个结构虽然以 ClaudeApiRequest 命名,但它其实是 Kuse Cowork 的内部通用请求格式——真正发给 OpenAI 或 Gemini 时,Agent 循环会再把它翻译成对应的协议(下文详述)。

三、系统提示词:让模型"先列计划再干活"的宪法

进度追踪之所以可能,根源在于系统提示词对模型的强约束。默认的 DEFAULT_SYSTEM_PROMPT(types.rs#L122-L170)规定了两件事:

  1. 任何任务开始前,必须先输出一个计划,且格式固定:
<plan>
1. [第一步描述]
2. [第二步描述]
</plan>
  1. 执行过程中用标记汇报进度:开始某步时输出 [STEP 1 START],完成时输出 [STEP 1 DONE]

此外,build_system_prompt() 还会动态追加当前可用的 Skills 清单(如 docx、pdf 技能),告诉模型技能文件的位置与调用方式——系统提示词因此是"静态规则 + 动态能力"的混合体。

四、解析执行计划: 标签背后的两步正则

模型回复回来后,parse_plan 负责从中"抠出"结构化计划,分两步走:

  1. 抓计划块:用正则 (?s)<plan>(.*?)</plan> 提取 <plan> 与 </plan> 之间的全部内容
  2. 切步骤:再用正则 (\d+)\.\s*(.+) 匹配形如 1. 描述 的编号行,每一行解析为一个 PlanStepInfo { step, description }(types.rs#L228-L232)

只要解析出至少一个步骤,就通过事件通道发出 AgentEvent::Plan,前端随即渲染出可勾选的计划清单 ✅ 如果没有匹配到任何编号步骤,则静默忽略——容错处理保证了即使模型"偷懒"没按格式输出,流程也不会中断。

五、追踪每一步进度:从 STEP 标记到实时事件流

计划是"事前",进度是"事中"。emit_step_markers 用两条正则扫描模型每轮输出的文本:

正则模式 触发事件 前端效果
[STEP 3 START] StepStart { step: 3 } 第 3 步标记为"进行中"
[STEP 3 DONE] StepDone { step: 3 } 第 3 步标记为"已完成"

这些标记和模型的自然语言回复混在同一段文本里,解析后既不打断阅读,又能驱动 UI 状态变化——这就是你在界面里看到"计划列表逐项打勾"的完整链路:

模型输出 [STEP 2 START]  →  正则命中  →  发送 StepStart 事件  →  界面高亮第2步

Agent 事件全览:进度追踪的"词汇表"

整个执行过程中,Agent 只对外发出 9 种事件(AgentEvent,定义在 types.rs#L207-L226),前端只需订阅它们就能还原一切:

事件 触发时机
Text 模型流式输出文本(累积内容实时推送)
Plan 成功解析出 <plan> 计划块
StepStart / StepDone 命中 STEP 开始/完成标记
ToolStart / ToolEnd 工具调用前/后(含参数、结果、成败标志)
TurnComplete 一轮"模型调用 + 工具执行"结束
Done 任务完成,附总轮数
Error 出错或达到最大轮数上限

六、Agent 主循环:把一切串起来的闭环

以上部件最终由 run_with_history 串联成完整循环,每一轮(turn)执行以下 6 个动作:

  1. 组装并发送请求:MessageBuilder 产出请求,send_request 按提供商分发到对应 API,SSE 流式解析中逐字推送 Text 事件,实现打字机效果
  2. 解析响应:parse_response 把返回内容拆成"纯文本 + 工具调用列表"两部分
  3. 解析计划:命中 <plan> 则发 Plan 事件
  4. 解析进度标记:命中 STEP 标记则发 StepStart/StepDone 事件
  5. 分支判断:若本轮没有任何工具调用,说明模型认为任务完成,发送 Done 并退出循环
  6. 执行工具并回喂:每个工具调用依次发送 ToolStart → 由 ToolExecutor 执行 → 发送 ToolEnd;所有结果打包成一条 ToolResults 用户消息追加到历史,进入下一轮

其中 ToolExecutor 的路由规则非常清晰(tool_executor.rs#L24-L97):mcp_ 前缀走 MCP、docker_ 前缀走容器隔离执行、其余匹配内置工具——与 MessageBuilder 注入工具时的命名规则严丝合缝。

另外还有一道安全阀:轮数超过 max_turns(默认 20)时强制终止并报错,防止模型陷入"无限调用工具"的死循环。

七、多模型适配:一份请求结构,三种 API 协议

Kuse Cowork 的"模型无关"特性,得益于前面设计的内部通用请求格式。同一个 ClaudeApiRequest 会按 ProviderConfig 被翻译成三种协议(agent_loop.rs#L224-L231):

提供商 翻译要点
Anthropic 原样 POST 到 /v1/messages,解析 Claude 风格 SSE 事件
OpenAI 兼容 convert_to_openai_format:系统提示词并入 messages、工具改为 function 类型、按模型名智能选择 max_tokens 或 max_completion_tokens、对推理系模型自动跳过 temperature
Google Gemini convert_to_google_format:角色改为 user/model、工具调用改为 functionCall 部件,并特别保留 Gemini 3 所需的 thoughtSignature 用于函数调用配对

也就是说,MessageBuilder 只负责"语义正确",协议差异全部由转换层吸收——这正是它值得作为架构样板来学习的原因。

八、小结

Kuse Cowork 用一个精巧的组合把"会思考的 Agent"拆成了四个可独立理解的部件:

  • MessageBuilder:按"白名单内置工具 + 在线 MCP 工具 + 转换后历史"三步组装统一请求
  • 系统提示词:以 <plan> 和 [STEP N START/DONE] 标记约定模型行为
  • 解析层:两步正则把非结构化文本还原成结构化计划与进度
  • 事件流:9 种 AgentEvent 让前端实时呈现计划、步骤、工具调用的全貌

对想要自建 AI Agent 的开发者来说,这套"通用请求格式 + 协议翻译层 + 标记驱动的进度追踪"方案,几乎是可直接借鉴的蓝图。建议从 src-tauri/src/agent/message_builder.rs 读起,再沿 agent_loop.rs 的主循环走一遍,一个完整 Agent 的骨架就清晰了 🎯

登录后查看全文
kuse_cowork