Cherry Studio递归工具调用机制深度解析

在现代AI应用开发中，工具调用（Tool Calling）已成为大语言模型与外部系统交互的核心机制。Cherry Studio作为一款先进的AI对话客户端，实现了一套完整的递归工具调用系统，能够让AI助手在执行复杂任务时自动调用多个工具，并根据执行结果智能决策下一步操作。本文将深入解析这套机制的设计原理、实现细节和实际应用。

什么是递归工具调用？

递归工具调用是指AI系统在执行任务过程中，根据当前执行结果自动决定是否需要调用更多工具来完成任务的机制。与传统的单次工具调用不同，递归调用允许AI在一个对话回合中连续执行多个相关操作，直到任务完成或达到预设限制。

举个实际例子：当用户要求"分析我的网站并生成性能报告"时，AI可能需要：

1. 1.调用网站爬取工具获取页面内容
2. 2.调用性能分析工具检测加载速度
3. 3.调用SEO分析工具评估搜索优化
4. 4.调用报告生成工具创建最终文档

这个过程中，每一步的结果都会影响下一步的执行，形成了一个动态的工具调用链。

核心架构设计

1. 递归深度控制

Cherry Studio通过 McpToolChunkMiddleware.ts 中的常量来控制递归深度：

const MAX_TOOL_RECURSION_DEPTH = 20

这个限制确保了系统不会陷入无限循环，同时为复杂任务提供了足够的调用深度。当递归深度超过限制时，系统会抛出明确的错误信息：

if (depth >= MAX_TOOL_RECURSION_DEPTH) {
  throw new Error(`Tool recursion depth exceeded: ${depth}/${MAX_TOOL_RECURSION_DEPTH}`)
}

2. 执行流程控制

核心执行函数 executeWithToolHandling 根据递归深度采用不同的执行策略：

• 深度为0（初始调用）：直接调用下一个中间件，启动正常的LLM推理流程
• 深度>0（递归调用）：使用增强的completion函数，跳过某些中间件以优化性能

if (depth === 0) {
  stream = await next()
} else {
  stream = await enhancedCompletions({
    ...params,
    recursionState: { depth, isRecursive: true }
  })
}

3. 工具调用检测与处理

系统通过 createToolHandlingTransform 函数创建流式处理管道，实时检测LLM输出中的工具调用信息：

if (chunk.type === 'tool-call' || chunk.type === 'tool-call-delta') {
  // 检测到工具调用，异步执行
  pendingToolCalls.push(executeToolAsync(chunk))
}

当流结束时，系统会检查是否有待执行的工具调用：

if (pendingToolCalls.length > 0) {
  const toolResults = await Promise.all(pendingToolCalls)
  if