构建用工具做调查的 AI 智能体，并用能识破瞎猜的测试来检验

## 把调查引擎和各服务的插件分开 将系统划分为明确的层：面向用户的入口、配置加载、调查引擎、工具管理器，以及可插拔的信息源、工具集、提示词和目标位置。入口应转发请求并建立日志记录；配置层应验证设置并构建集成功能；引擎应选择工具、收集证据、分析结果，并可选择将调查结果返回到获授权的目标位置。 将提供方特有的行为置于插件之后，使核心循环可以根据稳定的工具契约进行推理。从已验证的配置中动态加载集成功能，并将信息源摄取、调查和写入目标位置这几类操作彼此分开，确保只读诊断不会在不知情的情况下变成外部状态变更。 ## 工具做成薄封装，失败时准确返回查了什么、在哪里查 优先为单个外部端点或操作提供轻量封装。为每项集成功能提供一个经过验证的小型配置对象、明确的先决条件或健康检查，以及参数与底层请求直接对应的工具函数。如果透明的传输调用更便于检查行为和错误，就不要使用复杂的客户端抽象层。 返回足够的失败背景，让调用方能够自行纠错：准确的查询或命令、时间范围、筛选条件、相关参数、响应状态和底层错误消息。无数据的结果必须说明搜索了什么以及在哪里搜索。保留访问控制，验证可执行命令，让工具默认保持只读，并且绝不能暴露或提交秘密信息。 ## 在 AI 读取之前，限制工具返回的数据量 绝不能通过工具公开无界集合。对于可能返回大量结果集的端点，必须使用服务器端筛选条件；同时应设计相应模式，确保调用方无法省略最重要的范围参数。无限制列表操作导致的令牌或内存溢出属于工具契约缺陷，而不是提示词问题。 如果远程服务无法充分筛选，请添加明确的客户端控制，例如最大深度、结果上限、字段选择或结构化查询表达式。报告截断情况及所应用的限制。让默认响应保持简洁，同时允许在调查需要更多证据时进行有针对性的扩展。 ## 让旧配置名继续可用，并把共用行为放在合适的类层级 重命名配置字段时，将弃用名称作为额外输入接受，将其映射到当前字段，并发出弃用警告。公共模式和序列化输出中只保留当前名称，避免兼容性处理污染生成的配置或下游逻辑。 向指定集成功能添加字段、方法、超时或重试策略之前，应检查其类层次结构和同类实现。将共享行为放在真正需要它的最通用层级。使用经过验证、能够明确规定尝试次数和延迟策略的重试机制；只有标准机制无法表达需求时，才编写自定义循环，并记录原因。 ## 从单元测试到智能体评估，分三层进行测试 使用三个相互补充的层级。单元测试隔离本地行为，集成测试检验工具与服务的边界，智能体评估则通过真实的提示词和测试夹具验证端到端调查行为。新的本地行为需要单元测试覆盖，新的集成功能需要边界覆盖，复杂调查需要评估用例。 让源代码结构与测试结构保持一致。测试请求行为时，应使用传输层HTTP模拟对象，使标头、URL、参数和适配器得到实际检验，而不是替换高层函数。只有在有意配置的环境中才运行实际工具，并区分普通的确定性测试与需要模型凭据或外部服务的评估。 ## 设计能识破编造答案（幻觉）的评估 让每个提示词索取评估所检查的确切事实。优先使用只能通过查询发现的预期值，例如预先植入的唯一标识符、准确数量、标题或错误代码。预期答案必须对智能体保持不可见。如果答案过于宽泛，无法证明实际发现过程，就要求提供调用了正确工具的证据。 测试发现能力，而不是识别能力。使用中性的资源名称、真实场景，以及不会泄露实现或可能解决方案的提示词。避免模型可以根据领域知识猜出的宽泛断言。只使用已注册的测试标签、唯一的资源名称、固定的依赖项或镜像版本；如果设置无法证明服务正常运行，则应明确以失败状态退出。 ## 让多次测试运行共用云资源而互不破坏 应假设来自多个分支、以云服务为基础的评估可能在同一账户上重叠。设置必须具有幂等性：资源已经存在时不得失败，而应创建或复用资源。清理过程绝不能删除其他运行仍可能使用的静态共享资源；应省略清理，或将其限制到某个运行范围内的唯一标识符。 通过真实的API响应验证功能，而不能只看就绪状态。使用次数受限的重试进行轮询，以处理创建时的竞争；如果预期内容始终没有出现，应尽早失败，并在超时时收集诊断信息。当多个测试需要同一服务时，复用标准化的共享基础设施，但要隔离每项测试的数据和标识符。 ## 根据实际运行记录查找终端显示错位和评估退步的原因 对于交互式终端缺陷，通过伪终端复现并捕获原始转义序列。将光标移动和擦除操作与渲染帧的高度进行比较，然后通过强制设置为终端的内存流测试渲染器。修复造成偏移的帧或刷新契约；当终端底部的行为不同时，不要盲目修补光标移动。 对于智能体评估回归，在依赖源代码差异或汇总统计之前，先针对同一测试和模型比较一条基准跟踪记录与一条当前跟踪记录。检查渲染后的提示词、工具调用顺序、每次调用的指标和返回的证据。模板在源代码中可能变长，但在运行时反而缩短；汇总方差也可能掩盖每次运行中确定性的变化。在仅还原疑似修订中最显眼的文件之前，应先阅读完整的变更集。 ## 只对范围内的文件做格式化和检查，未经许可不推送 遵循存储库特有的样式、类型、测试和版本控制策略；但是，对于已知会修改无关文件的大范围自动修复、格式化或存储库级检查，除非用户或适用的工作流明确要求，否则不要运行。将自动格式化和静态检查限制在范围内的文件，并通过相应测试让评审保持聚焦。 按照项目约定放置导入项和共享实用工具，保留可逆的历史记录，并避免强制改写历史，除非获得明确授权。本地任务本身并不授权提交、推送、发布或更改外部状态。报告执行了哪些验证，以及有意排除了哪些检查。 ## 文档页面或标题变动时，更新所有引用 在查阅公共网站之前，先将存储库文档作为项目行为的主要来源。当页面移动、文件名改变或标题的锚点发生变化时，在整个存储库中搜索旧路径和旧锚点，包括文档、源代码字符串、顶层指南和注释，然后更新所有受影响的引用。 更新文档系统实际使用的导航来源，而不是名称相似但未启用的配置。保留渲染器特有的结构，包括必需的空行和有效的标题层级。避免过时的功能列表和重复的安全填充内容；优先采用简洁示例和整合后的故障排除区块。添加集成功能时，应同时更新其概述、索引、专用页面、导航条目和视觉资源。