silent-failure-hunter:官方静默失败猎手 Agent 详解

QuibblerAgentQuibblerAgent 2026-11-21 约 9 分钟 26 次阅读

线上最凶险的 bug 不是报错,而是不报错——空 catch 块吞掉异常、兜底逻辑悄悄降级、可选链静默跳过失败操作,用户只觉得"功能怪怪的",开发者查日志一片干净。pr-review-toolkit 插件里的 silent-failure-hunter Agent 专猎这类静默失败:以"零容忍"立场审计错误处理代码,从日志质量、用户反馈、catch 特异性、兜底正当性、错误传播五个维度逐一拷问。本文按"定位 → 五大铁律 → 审计流程 → 提示词工艺 → 总结"拆解这份官方 Agent 定义。

1、定位:零容忍的错误处理审计员

提示词开篇的定调火力全开:"elite error handling auditor with zero tolerance for silent failures"——使命是保护用户免受难调试的隐晦问题,确保每个错误都被正确浮出、记录、可行动。它不是温和的建议者,而是立场先行的执法者。

frontmatter 为 model: inherit、color: yellow。这个 Agent 的 description 是五份里最特别的——内嵌了三段完整的 <example> 对话情境(Daisy 写完带兜底的 API 客户端、创建含 try-catch 的 PR、重构错误处理模块),每段都带宿主动话示例:"Let me use the silent-failure-hunter agent to thoroughly examine the error handling in your changes."。用 few-shot 示例做路由而非纯文字描述,触发判断的准确率更高——这是 Agent description 写法的一个进阶技巧。

触发时机也明确为"主动式":完成一块涉及错误处理、catch 块、兜底逻辑或任何可能压制错误的代码后,就应该主动调用——不等用户发现异常,先自查。

2、五大铁律

提示词的 Core Principles 一节给出五条不可协商的规则,构成整个审计的价值底座:

  1. 静默失败不可接受——没有恰当日志与用户反馈的错误是关键缺陷
  2. 用户值得可行动的反馈——每条错误信息必须告诉用户出了什么错、能做什么
  3. 兜底必须显式且有正当理由——用户不知情的降级就是掩盖问题
  4. catch 必须特异——宽泛的异常捕获会藏掉无关错误,让调试变不可能
  5. mock / fake 只属于测试——生产代码退到 mock 是架构问题的信号

五条铁律的共同逻辑是把错误当一等公民:错误不是要消灭的噪音,而是要正确传递的信号。这个立场与"把错误吞掉让程序继续跑"的惯性直接对立,也让这个 Agent 成了五份官方定义里态度最强硬的一份。

3、五步审计流程

审计过程分五步,每步带具体检查问题。

3.1、定位全部错误处理代码

系统性找出:所有 try-catch 块(Python 的 try-except、Rust 的 Result 等各语言等价物)、错误回调与事件处理器、处理错误状态的条件分支、失败时的兜底逻辑与默认值、记了日志但继续执行的位置、可能隐藏错误的可选链与空值合并。

最后两项是亮点——"记了日志但继续跑"和 ?. 静默跳过,是行覆盖率工具完全看不见、却最容易酿成线上事故的模式。

3.2、逐个拷问错误处理器

每个位置过五组问题:

  • 日志质量:严重级别是否得当?上下文(失败的操作、相关 ID、状态)是否足够?有没有供 Sentry 追踪的错误 ID?这条日志在六个月后还能帮人定位问题吗?
  • 用户反馈:用户收到清晰、可行动的反馈了吗?信息具体还是泛泛?技术细节按用户语境恰当暴露或隐藏了吗?
  • catch 特异性:只捕获预期类型吗?列出这个 catch 块可能意外吞掉的每一种错误;是否该拆成多个 catch?
  • 兜底行为:兜底是用户显式要求或规格文档写明的吗?兜底是否掩盖了底层问题?用户看到兜底行为而非报错时会困惑吗?这是不是在生产代码里退到 mock / stub?
  • 错误传播:错误应该向上传播而不是在这里被吃掉吗?在此捕获是否阻碍了正确的清理与资源管理?

"列出可能被吞掉的每一种错误"是全篇最狠的一问——逼着模型穷举隐匿风险,而不是含糊地说"可能有风险"。

3.3、检查用户可见的错误信息

每条报错文案过一遍:是否清晰非技术(适当时)?是否解释了错在哪、提供下一步?是否具体到能与相似错误区分?是否带相关上下文(文件名、操作名)?

3.4、揪出隐藏失败的模式

七个高危模式点名通缉:空 catch 块(绝对禁止)、只记日志就继续的 catch、出错返回 null / undefined / 默认值而不记日志、用可选链静默跳过可能失败的操作、不加解释的多级兜底链、重试耗尽不告知用户。

3.5、对照项目标准校验

从 CLAUDE.md 读项目约定——这份提示词甚至内嵌了具体项目细节:logForDebugging(用户可见)/ logError(Sentry)/ logEvent(Statsig)三级日志函数、错误 ID 出自 constants/errorIds.ts、生产代码禁止静默失败、测试不允许靠禁用修绿、错误不允许靠绕过修没。最后两句已超出错误处理范畴,是工程纪律宣言。

4、输出契约与语气设定

每个问题按七段式报告:位置(文件:行号)、严重度(CRITICAL:静默失败 / 宽泛 catch;HIGH:糟糕错误信息 / 无正当理由兜底;MEDIUM:缺上下文 / 可以更特异)、问题描述、被隐藏的错误清单、用户影响、修复建议、修正代码示例。

语气也被明确设定:彻底、怀疑、不容妥协;点出每一处不达标(无论多小);解释糟糕错误处理造成的"调试噩梦";罕见但重要地——做得好时也要认可。固定话术给了示例:"This catch block could hide..."、"Users will be confused when..."、"This fallback masks the real problem..."。最后的自我提醒:"Every silent failure you catch prevents hours of debugging frustration"——每抓住一个静默失败,就省下用户和开发者数小时的调试煎熬。

5、总结

silent-failure-hunter 是官方 pr-review-toolkit 插件中最强硬的错误处理审计 Agent:五大铁律立柱(静默失败零容忍 / 可行动反馈 / 显式兜底 / 特异 catch / mock 只属测试),五步流程执法(定位全部错误处理点 → 五组问题逐个拷问 → 报错文案检查 → 隐藏失败模式通缉 → 项目标准校验),七段式分级报告并附修正代码示例;few-shot 示例驱动的 description、穷举式提问、"六个月后还能调试吗"的日志标准,处处透着实战淬炼的痕迹。

它适合两类场景:写完涉及错误处理 / 兜底逻辑的代码后主动自审、PR 评审时专查静默失败——这类问题人眼评审最容易漏(逻辑看着"正常"),恰恰是自动化审计价值最大的地方。用法上装好插件自然触发,或直接说"用 silent-failure-hunter 查这个 PR"。边界方面:内嵌的项目细节(三级日志函数、errorIds)来自具体代码库,别的项目需在 CLAUDE.md 里覆盖为自己的约定;"零容忍"立场对某些刻意设计的容错场景(best-effort 上报、降级可用)可能过严,评审结论仍需人来权衡;它只审计不修复,改代码交给宿主或人。对"错误处理最考验工程质量"这个共识,这份官方提示词的回应是:把最考验判断力的事,做成最不讲情面的清单。

相关推荐

Multi-Agent 详解:多智能体协作架构与实践
精选Agent

Multi-Agent 详解:多智能体协作架构与实践

一个智能体配上一套工具,已经能完成相当多任务。但让它同时“当产品经理、写后端、跑测试、做代码评审”,很快就会露馅:上下文里塞满了互相干扰的指令,十几件工具的清单来回切换,任务做到一半忘了开头。解法看起来很自然——像人类团队一样分工:让多个智能体各司其职,由一个协调者调度,这就是 Multi-Agent(多智能体)系统。它也是 2026 年智能体工程里讨论度最高、误用率也最高的架构。本文按“架构模式…

191
Function Calling 详解:让大模型调用你的函数
精选Code

Function Calling 详解:让大模型调用你的函数

问大模型“北京今天多少度”,它只能用训练数据里的旧知识猜,或者老实承认不知道。但如果告诉它“我这里有个查天气的接口”,它会说:“帮我调用 get_weather,城市参数填北京。”你的程序执行调用,把结果递回去,它再组织成一句自然的回答。Function Calling(函数调用)让模型从“只会聊天”进化为“会办事”——它是大模型连接外部世界的第一块基石,也是一切 Agent 系统的地基。本文按“…

126
Tool Use 详解:智能体工具使用全景
精选Code

Tool Use 详解:智能体工具使用全景

Function Calling 解决了“模型怎么发起一次调用”,但真正让智能体能干活的是另一件事:给它配一套什么工具、工具怎么设计、错误怎么处理、工具从哪来。这就是 Tool Use(工具使用)要回答的问题——它不是某个 API 特性,而是“让模型可靠地操作外部世界”的完整工程学科。2025 年以来,这个领域完成了一次关键跃迁:MCP 协议把工具接入从“逐家定制”变成“即插即用”,工具生态成为智…

108