测试发现工具返回一个空列表，Agent 回答“项目没有测试”。实际原因可能是目录无权限、扫描超时，或规则配置无法读取。工具把失败伪装成空结果，模型再谨慎也很难恢复丢失的信息。

诊断响应的目标，是让 Agent 知道完成了什么、缺了什么，以及下一步是否可行。它不需要整段内部堆栈，也不能只收到一个笼统的“失败”。

无匹配与失败分别表示

范围存在、扫描完成且没有候选，可以返回成功的空列表。范围不存在、权限不足、资源预算耗尽和配置无效，应使用不同的状态或错误码。

尤其要区分文件级规则扫描与框架收集。前者按命名约定找候选，后者可能导入项目代码并受到环境影响。工具返回 discovery_mode，Agent 才知道空结果究竟证明了什么。

没有发现候选，最多说明当前规则与范围未找到，不能推断整个仓库没有测试；收集失败，也不能写成测试失败，因为测试主体可能根本没有执行。

诊断保留四类信息

第一是请求身份：仓库、修订、范围与发现方式。第二是失败类型：参数、路径、权限、预算或内部错误。第三是已完成范围与截断状态。第四是可行下一步，例如修正目录、缩小范围或等待环境恢复。

{
  "status": "partial",
  "discovery_mode": "file_pattern_scan",
  "error_code": "SCAN_BUDGET_EXCEEDED",
  "scope": "tests",
  "items": [],
  "complete": false,
  "retryable": false,
  "suggested_action": "缩小到目标模块目录"
}

这是接口示意，实际返回值由工具填写。retryable 只是工具判断，不能替代流程限制；即便允许重试，也应有次数与时间预算。

图中的拒绝不绕过，指权限与范围限制保持有效。Agent 不能因为一个目录被拒绝，就尝试读取其他未授权位置。

部分成功要说明完整性

扫描了几个目录后预算耗尽，已经找到的候选可以保留，但要标明它们是部分结果。不要只返回候选列表而省略未扫描范围，也不要给出全仓库总数。

已完成范围适合用目录集合、游标或明确区间表示。并行扫描时，“最后一个目录”不一定代表前面的全部完成，断点结构应匹配实际执行方式。

候选路径里有敏感名称或内部信息时，按授权规则处理。完整堆栈、环境变量和凭据无需进入模型上下文。日志关联标识足以帮助维护者查内部详情，公开诊断只保留行动所需的信息。

错误决定是否继续

参数错误应修改输入，不用原参数无限重试。目录不存在可以回到受限搜索确认位置。权限错误报告阻塞；网络或临时服务故障可以有限重试。预算耗尽则缩小范围或明确当前证据不足。

工具描述应告诉模型这些区别，但程序仍强制执行重试上限与范围。不要让模型独自承担资源管理，也别把每次工具失败都升级成要求用户处理。

如果框架收集失败，可以在产品允许时降级到文件级候选扫描，但必须明确模式变化。不能用文件名扫描结果冒充框架已成功收集的测试项。

最终回答保留关键缺口

Agent 可以说“在目标目录找到这些候选，但扫描因预算停止，列表不完整”。这比“找到全部相关测试”更准确，也给用户明确的后续方向。

验证时模拟空目录、无权限、规则错误、扫描中断与临时失败。检查工具状态是否不同，模型是否正确解释，是否会把发现失败写成测试未通过。

一个好的诊断接口，不必把内部细节全部暴露出来。只要让完成范围、失败原因与可行下一步足够清楚，就能减少很多错误结论和无意义重试。