工具调用决策架构

这份规则描述的是在执行编程任务时，如何决策调用哪些工具、以什么顺序调用、如何处理结果、以及如何从失败中恢复的完整决策体系。工具调用是 AI Agent 能力的核心体现，但工具使用的质量差距非常大。低质量的工具使用是盲目的、串行的、不加评估的；高质量的工具使用是目的驱动的、最大化并行的、对结果有批判性评估的。这份文档覆盖从"应该调用什么工具"到"调用结果说明了什么"的完整链路。

一、工具调用前的决策

1.1 明确调用目的

每一次工具调用之前，必须能够清晰回答：这次调用要获取什么信息或完成什么操作，获取这个信息或完成这个操作对当前任务步骤是否必要，以及没有这次调用是否可以继续推进任务。

如果不能清晰回答这三个问题，说明对当前的任务状态还不够清晰，需要先整理思路再决定调用什么工具。盲目的工具调用会产生大量噪声信息，反而降低任务执行的质量。

1.2 选择最合适的工具

不同的工具有不同的适用场景，选择错误的工具会得到低质量的结果。

语义搜索（基于含义的搜索）适合：在不知道具体位置的情况下找到与某个功能或概念相关的代码，理解一个不熟悉的代码库的整体结构，找到所有处理某类业务逻辑的代码。

符号搜索（基于精确名称的搜索）适合：找到某个具体的类、函数或变量的定义，找到所有引用了某个符号的地方（评估修改影响范围），确认某个接口的所有实现。

文件读取适合：已经知道需要读哪个文件，需要理解文件的完整内容和上下文。

目录浏览适合：需要了解项目的整体结构，确认文件的存在和组织方式。

正则表达式搜索适合：需要查找符合特定文本模式的内容，比如所有使用某个特定字符串格式的地方。

flowchart TD
    A[需要获取信息] --> B{知道具体文件路径吗}
    B -- 是 --> C[直接读取文件]
    B -- 否 --> D{知道确切的符号名称吗}
    D -- 是 --> E[使用符号搜索]
    D -- 否 --> F{知道功能的描述吗}
    F -- 是 --> G[使用语义搜索]
    F -- 否 --> H[先浏览目录结构建立宏观认知]
    H --> F

二、并行与串行的决策规则

2.1 并行是默认选择

能够并行执行的工具调用应该总是并行执行，而不是串行执行。并行执行不仅节省时间，也能在更短的时间内建立起对问题的全面认知。

判断两个工具调用是否可以并行的标准只有一个：第一个调用的结果，是否是第二个调用所需参数的一部分。如果不是，它们就可以并行。

可以并行的典型场景：读取多个不同的文件、在不同目录中进行多次搜索、对不同问题进行独立的信息收集、同时获取不同模块的上下文信息。

2.2 必须串行的情况

只有当确实存在依赖关系时，才使用串行执行：读取一个配置文件，然后根据配置文件中的内容决定读取哪个其他文件；搜索一个函数的定义，然后根据定义中的内容进一步搜索它调用的函数；先创建一个文件，再修改这个文件。

flowchart TD
    A[需要执行多个工具调用] --> B[分析每个调用的输入依赖]
    B --> C{任何调用是否需要另一个调用的输出作为输入}
    C -- 否，所有调用独立 --> D[全部并行执行]
    C -- 是，存在依赖 --> E[识别依赖链]
    E --> F[将独立的调用分组并行]
    F --> G[依赖链内的调用串行执行]
    D & G --> H[汇总所有结果]

2.3 信息收集阶段最大化并行

在任务开始时的信息收集阶段，通常需要了解多个方面的信息，这些信息的收集之间往往没有依赖关系，应该全部并行。

常见的可以并行收集的信息：相关代码文件的内容、同类型的其他文件（了解模式）、被依赖的工具函数、项目的目录结构。

三、结果处理的标准流程

3.1 相关性过滤

工具返回的结果不一定全部与当前任务相关。特别是搜索类工具，经常会返回看起来相关但实际上不相关的内容。在使用搜索结果之前，需要主动过滤出真正相关的部分。

判断相关性的标准：这个结果是否直接与当前需要解决的问题相关，它是否提供了新的信息（而不是重复已知的信息），它是否可能影响当前的决策。

3.2 完整性检查

文件读取可能返回截断的内容（文件太大），搜索可能只返回部分匹配项。在基于工具结果做决策之前，评估结果的完整性：看到的内容是否足以支撑判断，是否有明显的截断迹象，是否需要追加查询来获取完整信息。

3.3 一致性检查

当多个工具调用的结果涉及同一个事物时，检查这些结果是否相互一致。如果发现矛盾，不能随意选择其中一个忽略另一个，而是需要弄清楚矛盾的原因。

矛盾的常见来源：代码库中有多个版本的同一功能（旧代码和新代码共存）；不同文件中对同一概念有不同的命名；某个接口有多个实现，不同实现的行为有差异。

flowchart TD
    A[工具返回结果] --> B[相关性过滤\n去掉与任务无关的内容]
    B --> C[完整性检查\n结果是否被截断]
    C --> D{是否完整}
    D -- 不完整 --> E[追加查询补充缺失信息]
    E --> C
    D -- 完整 --> F[一致性检查\n与其他已知信息是否矛盾]
    F --> G{是否存在矛盾}
    G -- 是 --> H[分析矛盾原因]
    H --> I[解决矛盾后整合]
    G -- 否 --> J[整合进任务上下文]
    I --> J
    J --> K[继续执行任务]

四、写操作工具的特殊规则

4.1 写操作前必须充分准备

读操作的成本是时间，写操作的成本包括引入错误的风险。因此写操作（文件创建、文件修改）需要比读操作更充分的准备。

在执行写操作之前，必须已经：理解了要修改的目标文件的完整结构、确认了修改的内容和位置、分析了修改可能产生的影响。

4.2 写操作必须串行

多个写操作绝对不能并行执行。写操作并行执行可能导致：文件内容出现意外的交叉、后一个写操作覆盖了前一个写操作的结果、难以追踪每个写操作的具体效果。

写操作必须按照依赖顺序串行执行：被依赖的文件先修改，依赖它的文件后修改。

4.3 每次写操作后验证

每次写操作完成后，验证操作的结果是否符合预期。不要等到所有写操作都完成再统一验证，这样当发现问题时难以定位是哪次操作引入的。

五、搜索策略的层次化方法

5.1 从高层次到低层次

搜索的顺序应该从高层次（功能描述、业务概念）到低层次（具体的符号名称、代码片段）。先用高层次的查询建立宏观认知，再用低层次的查询定位具体细节。

跳过高层次直接搜索低层次，容易因为不知道"整体图"而在错误的地方深挖，或者找到了一个相关的东西就以为理解了全貌。

5.2 搜索没有结果时的策略

搜索没有返回有用的结果时，不应该简单地放弃或向用户声明"找不到"，而应该尝试调整搜索策略：

用不同的关键词描述同一个概念（开发者可能用不同的术语）、扩大搜索范围到父目录、从相关功能或模块切入（通过已知的相关代码找到未知的代码）、检查是否因为关键词太具体而遗漏了相关内容。

flowchart TD
    A[搜索没有返回有用结果] --> B[分析可能的原因]
    B --> C{关键词是否太具体}
    C -- 是 --> D[使用更通用的关键词重新搜索]
    C -- 否 --> E{搜索范围是否太窄}
    E -- 是 --> F[扩大搜索范围]
    E -- 否 --> G{是否可以从相关模块切入}
    G -- 是 --> H[先找到相关模块\n再从相关模块出发搜索]
    G -- 否 --> I[尝试完全不同的角度描述需求]
    D & F & H & I --> J{是否找到有用结果}
    J -- 是 --> K[继续执行任务]
    J -- 否，多次尝试后仍无结果 --> L[明确说明未找到相关实现\n并说明已尝试的搜索方向]

5.3 不要在第一个结果停止

找到一个看起来相关的文件或函数时，不要立即停止搜索。复杂的功能通常分散在多个文件中，只读一个文件往往只能看到局部。

在开始深入阅读第一个结果之前，先评估：还可能有哪些其他文件与当前任务相关，这些文件的信息是否可以并行获取，确保在开始处理之前已经建立了足够全面的认知。

六、工具调用失败的恢复策略

6.1 分析失败原因再重试

工具调用失败时，不应该立即使用相同的参数重试。立即重试只在瞬时性失败（网络超时、临时不可用）的情况下有意义。

在重试之前，分析失败的原因：是参数错误（路径不存在、格式有误）、权限问题（没有读写权限）、资源不存在（文件已删除、搜索无结果）、还是瞬时性失败（服务暂时不可用）。不同的失败原因需要不同的处理方式。

6.2 替代方案的准备

对于重要的工具调用，考虑是否有替代的方式可以获取同样的信息或完成同样的操作。如果主要方式失败，能够通过替代方式继续任务，而不是完全卡住。

6.3 失败信息的透明告知

如果工具调用失败且无法通过重试或替代方案解决，清晰地向用户说明：发生了什么失败，为什么会失败，以及由于这个失败哪些部分的任务无法完成或质量受到了影响。

透明地说明失败比假装成功或产出一个明知有缺陷的结果要好得多，它让用户能够做出知情的决策。