假装工具成功了，继续基于不存在的信息编造答案。无限重试，浪费 token 和时间。直接甩锅给用户：“工具失败了”，但不给下一步选项。把底层异常原样暴露出来，用户看不懂，也不知道该做什么。忘记当前目标，重新规划成一个更大的任务，越跑越偏。

工具超时或空返回，不应该只是一个 exception；它应该被设计成 Agent 工作流中的一种“可解释状态”。

Prompt 的作用不是替代工程错误处理，而是告诉 Agent：看到这种状态后，如何判断、如何重试、何时停止、如何向用户反馈、如何请求用户决策。

一、为什么“工具失败反馈”必须写进 Prompt？

用户：修复 UserService 里登录失败的问题。

Agent：调用 grep UserService。

工具返回：超时。

Agent：调用 read_file src/user/UserService.ts。

工具返回：空字符串。

Agent：继续猜测代码结构，生成一个补丁。

最终：补丁改错文件，用户不信任 Agent。

二、先定义：什么叫“超时”和“空值”？

三、整体架构：不要把异常直接丢给 LLM

四、Prompt 设计的核心原则

1. 不要让 Agent “静默失败”

当工具调用超时、返回空值、返回空数组、返回 null、返回格式不可解析时，不得假设工具成功。

必须把该结果视为不完整观察，并在继续推理前判断是否需要重试、换工具、缩小范围或向用户反馈。

2. 空结果不是错误，但也不是成功

如果工具返回空结果，先判断该工具的“空结果语义”：

• 搜索类工具空结果：可能是关键词、路径或索引范围问题。

• 文件读取空结果：可能是空文件，也可能是读取失败或路径错误。

• 数据查询空结果：可能是业务上没有数据，也可能是过滤条件过窄。
除非有额外证据，否则不得把空结果当成最终事实。

3. 重试必须有预算

对同一工具、同一参数，最多自动重试 1 次。

对同一目标，可以换一种工具或缩小参数范围再尝试 1 次。

如果仍失败，停止自动尝试，向用户反馈当前状态和可选下一步。

4. 反馈要有“下一步选项”

工具调用失败了，请稍后再试。

我尝试读取 src/user/UserService.ts，但文件读取工具连续两次超时。当前还不能安全修改代码。你可以选择：

1. 让我改用全局搜索定位相关文件；

2. 你直接贴出 UserService.ts 内容；

3. 先跳过读取，基于已有报错给出排查方案，但不会直接生成补丁。

5. 区分“对模型可见”和“对用户可见”

向用户反馈时，只展示任务相关、可行动的信息。

不展示内部堆栈、密钥、完整请求头、敏感路径。

如果需要技术细节，仅提供摘要和错误类别。

五、可直接使用的 System Prompt 模板

Tool Failure & Empty Result Policy

You are an AI coding agent. Tool results are external observations and may be incomplete, stale, empty, delayed, or failed.

When a tool call returns timeout, null, empty string, empty list, malformed output, permission error, or an error status:

1. Do not assume the tool succeeded.

2. Do not fabricate missing code, files, API responses, logs, or test results.

3. Classify the observation as one of: timeout, empty, invalid_args, permission_denied, rate_limited, fatal, or unknown.

4. Decide whether the issue is:
• system-recoverable: retry with the same tool once;
• model-recoverable: fix arguments, narrow scope, or use another tool;
• user-fixable: ask the user for missing input, permission, credentials, file content, or confirmation;
• fatal: stop and report a concise failure summary.

5. Use at most one retry for the same tool arguments. Use at most one alternative tool attempt for the same subgoal.

6. After retry budget is exhausted, provide user feedback with:
• what you tried;
• what failed or returned empty;
• what you can and cannot safely conclude;
• two or three concrete next-step options.

7. If user input is required, ask one focused question or present a small set of choices.

8. Continue only when there is enough evidence to avoid unsafe code changes.

Never hide tool failure from the user when it affects correctness, safety, or the ability to complete the task.

分类失败 → 控制重试 → 停止幻想 → 给用户可执行选项。

六、工具描述也要写清“空结果语义”

成功返回的结构。空结果代表什么。什么时候可能超时。失败后 Agent 应该怎么做。

Tool: code_search

Purpose: Search source files by keyword, symbol, or regex.

Success: returns a non-empty list of matching file paths and snippets.

Empty result semantics:

• [] means no match was found in the indexed search scope.

• It does not prove the symbol does not exist in the repository.

• The agent should retry once with a broader keyword, path, or symbol variant before concluding no match.

Timeout semantics:

• Timeout may happen on large repositories, broad regex, or cold index.

• On timeout, narrow the path or simplify the query before retrying.

User feedback rule:

• If both the original search and the narrowed/broadened retry fail, tell the user what was searched and ask whether to provide a file path, paste relevant code, or allow a slower full-repo scan.

七、把用户反馈做成固定格式

我遇到了一个工具调用问题，当前不能安全地继续假设结果。

已尝试：{tools_and_args_summary}

结果：{timeout_or_empty_summary}

当前能确定：{confirmed_facts}

当前不能确定：{unknowns}

你可以选择：

1. {option_1}

2. {option_2}

3. {option_3}

我建议先选择：{recommended_option}，因为 {reason}。

If the failure is minor and does not affect correctness, summarize briefly. If it blocks the task or may cause unsafe code changes, use the full feedback format.

八、OpenSpec 化：把失败反馈写成可审查规格

九、源码实现：工具包装器

统一识别 null、undefined、空字符串、空数组、空对象。不把空结果直接当成功。给模型和用户分别准备不同粒度的信息。rawError 只保留在日志里，不默认暴露给用户。把 retryable 和 userActionRequired 显式结构化。

十、源码实现：把 Observation 注入 Prompt

十一、源码实现：Agent 决策伪代码

十二、图解：超时后的正确路径

十三、图解：空结果后的正确路径

十四、用户反馈话术示例

场景 1：工具超时

我尝试读取 src/services/UserService.ts 来定位登录失败问题，但文件读取工具连续两次超时。

当前能确定：需要查看实际代码后才能安全修改。

当前不能确定：UserService 的真实路径、登录逻辑实现、错误处理分支。

你可以选择：

1. 让我改用全局搜索定位 UserService 和 login 相关代码；

2. 你直接贴出相关文件内容；

3. 我先基于报错信息给出排查清单，但暂不生成补丁。

我建议选择第 1 项，因为它仍然可以保持自动化，同时不会基于缺失代码瞎改。

场景 2：搜索为空

我搜索了 refreshToken、loginWithToken 和 auth/session，但当前索引范围内没有匹配结果。

这不能证明项目里没有登录逻辑，可能是命名不同、路径未被索引，或者代码在另一个模块。

下一步可以：

1. 扩大到全仓库搜索 token / session / auth；

2. 你提供登录入口文件路径；

3. 先从路由或测试文件反向定位调用链。

我建议先从第 3 项开始，因为入口调用链通常比关键词更稳定。

场景 3：权限失败

我需要读取仓库文件来继续分析，但当前工具返回了权限错误。

我不能访问相关文件，因此不能安全生成代码修改。

你可以：

1. 授权文件读取工具；

2. 粘贴相关文件内容；

3. 让我只基于你提供的报错和目录结构做静态排查建议。

十五、Claude Code / MCP 场景怎么接？

When a PostToolUseFailure, PermissionDenied, timeout, or empty MCP tool result is observed, convert it into a normalized ToolObservation.

If the observation is user-fixable, use AskUserQuestion instead of guessing.

Ask at most one focused question, and include concrete options.

十六、Skill 化：做一个 tool-failure-feedback Skill

十七、如何测试这个 Prompt 是否有效？

是否说明了工具失败？

是否没有编造结果？

是否给出了下一步选项？

是否没有无限重试？

是否没有泄露敏感信息？

是否在需要用户输入时提出了明确问题？

十八、常见反模式

反模式 1：只写“如果失败就重试”

错误写法：

工具失败时自动重试。

正确写法：

同一工具同一参数最多重试一次；如果仍失败，换一种工具或向用户反馈。

反模式 2：空数组直接当事实

错误写法：

搜索为空，说明代码不存在。

正确写法：

搜索为空，只说明当前查询没有匹配。需要扩大范围、换关键词或请求用户提供路径。

反模式 3：用户反馈没有选项

错误写法：

我失败了，请重试。

正确写法：

我尝试了 A 和 B，但都失败。你可以选择授权、贴代码、允许慢查询，或让我给出不改代码的排查方案。

反模式 4：把所有错误都交给模型自由发挥

反模式 5：把底层异常直接暴露给用户

十九、最终推荐落地方案

第一层：Tool Wrapper

统一 timeout、empty、null、permission、rate limit、fatal 等状态，生成 ToolObservation。

第二层：System Prompt

写清失败分类、重试预算、禁止编造、用户反馈格式。

第三层：Skill / OpenSpec

把工具失败反馈策略沉淀为 tool-failure-feedback skill 或 OpenSpec change，成为团队规范。

第四层：Runtime Hook

在 PostToolUseFailure、timeout、empty result、permission denied 等事件中注入 observation，并在需要时触发用户询问。

二十、总结

先把失败结构化，

再让 Prompt 驱动 Agent 分类决策，

然后用有限重试和替代工具自恢复，

最后在无法安全继续时，给用户明确、简短、可行动的反馈。

Prompt 不是用来掩盖工具失败的，而是用来定义 Agent 在失败后的协作协议。

真正可靠的 AI Coding Agent，不是永远不失败，而是失败后知道如何停、如何说、如何让用户重新掌控方向。