Kuse Cowork进阶原理:MessageBuilder如何组装请求、解析执行计划并追踪每一步进度
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):
- message_builder.rs:请求组装器,本文主角
- agent_loop.rs:Agent 主循环,负责多轮调用与进度事件
- tool_executor.rs:工具执行器,真正干活的手脚
- types.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)规定了两件事:
- 任何任务开始前,必须先输出一个计划,且格式固定:
<plan>
1. [第一步描述]
2. [第二步描述]
</plan>
- 执行过程中用标记汇报进度:开始某步时输出
[STEP 1 START],完成时输出[STEP 1 DONE]
此外,build_system_prompt() 还会动态追加当前可用的 Skills 清单(如 docx、pdf 技能),告诉模型技能文件的位置与调用方式——系统提示词因此是"静态规则 + 动态能力"的混合体。
四、解析执行计划: 标签背后的两步正则
模型回复回来后,parse_plan 负责从中"抠出"结构化计划,分两步走:
- 抓计划块:用正则
(?s)<plan>(.*?)</plan>提取<plan>与</plan>之间的全部内容 - 切步骤:再用正则
(\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 个动作:
- 组装并发送请求:
MessageBuilder产出请求,send_request 按提供商分发到对应 API,SSE 流式解析中逐字推送Text事件,实现打字机效果 - 解析响应:parse_response 把返回内容拆成"纯文本 + 工具调用列表"两部分
- 解析计划:命中
<plan>则发Plan事件 - 解析进度标记:命中 STEP 标记则发
StepStart/StepDone事件 - 分支判断:若本轮没有任何工具调用,说明模型认为任务完成,发送
Done并退出循环 - 执行工具并回喂:每个工具调用依次发送
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 的骨架就清晰了 🎯