Harness Engineering 04能力 Harness工具和检索的可靠性工程activity-dev-harness 最初给 Developer Agent 配了 12 个工具。逻辑很直觉能力越多 → 覆盖越全 → 效果越好。结果恰好相反Developer Agent 工具调用统计12 工具版本 指标 数值 ────────────────── ────── 工具调用准确率 68% 错误类型分布 选错工具 41% ← 最大问题 参数传错 28% 该调没调漏调用 18% 重复调用 13% 12 个工具时模型在选哪个上的决策负担太重。 它不是不会用而是选不对。把工具集从 12 砍到 5 后Developer Agent 工具调用统计5 工具版本 指标 12 工具 5 工具 变化 ────────────────── ──────── ──────── ────── 工具调用准确率 68% 91% 23pp 选错工具 41% 8% -33pp 参数传错 28% 15% -13pp 任务通过率 45% 71% 26pp同样的故事在 RAG 上也发生了AIReview 接入规则知识库后团队以为有知识就更准。实测发现某些场景下接入 RAG 反而导致准确率下降——检索噪声污染了原本正确的判断。工具和检索都是能力但能力接入不等于可靠。从能用到可靠之间隔着一整层工程设计。手记系列讲了工具和检索怎么设计这篇讲怎么让它们可靠手记 04 / 06 的视角 本篇的视角 ────────────────── ──────────────────── RAG 知识供应链怎么搭 RAG 接入后怎么验证真的有增益 工具集怎么设计 工具接入后怎么保证调用可靠 Agent 编排模式 能力层面的可靠性工程Tool Harness六项可靠性能力工具调用从能用到可靠需要补上六层工程能力┌──────────────────────────────────────────────────────────────────────┐ │ Tool Harness 六层可靠性 │ ├────────────┬─────────────────────────────┬───────────────────────────┤ │ 能力层 │ 解决什么问题 │ 没有会怎样 │ ├────────────┼─────────────────────────────┼───────────────────────────┤ │ ① 分级 │ 哪些工具高风险/低风险 │ 所有动作同一个安全等级 │ │ ② 校验 │ 参数合法性、必填项 │ 垃圾参数直接打到下游 │ │ ③ 约束 │ 调用频率、并发、范围限制 │ 无限重试、重复调用 │ │ ④ 确认 │ 高风险动作执行前确认 │ 删除/写入等动作自动执行 │ │ ⑤ 异常 │ 超时、失败、降级处理 │ 一个工具超时拖垮整条链路 │ │ ⑥ 审计 │ 谁调了什么、参数、结果 │ 出事后无法追溯 │ └────────────┴─────────────────────────────┴───────────────────────────┘错误示范 vs 正确示范工具权限设计❌ 错误示范所有工具平权 Developer Agent 工具集 ├── file_read 读文件 ├── file_write 写文件 ├── grep 搜索代码 ├── pytest 跑测试 ├── dry_run 模拟执行 ├── git_commit 提交代码 ← 高风险和读文件同一权限等级 ├── deploy_staging 部署测试环境 ← 高风险 ├── db_query 查数据库 ├── db_write 写数据库 ← 极高风险 ├── shell_exec 执行 shell ← 极高风险 ├── api_call 调外部 API └── config_update 改配置 ← 高风险 所有工具同一个权限等级 → Agent 可以无确认直接写数据库 ✅ 正确示范分级 角色隔离activity-dev-harness 实际设计 Developer Agent读写角色 Reviewer Agent只读角色 ────────────────────── ────────────────────── L1 自由调用无需确认 L1 自由调用 ├── file_read ├── SH-01: 文件存在性检查 ├── grep ├── SH-02: 空壳代码检测 └── dry_run ├── SH-03: 参数一致性 └── SH-04~10: 其他只读检查 L2 需要校验参数合法性 ├── file_write限 combat/ 目录 L2 需要校验 └── pytest限 tests/ 目录 └── DC-01~07: 深度一致性检查 L3 需要确认高风险 L3 不存在 └── 无 ← Developer 没有 L3 权限 ← Reviewer 完全没有写权限 关键设计 1. Reviewer 只有读权限 → 审查独立性不能顺手改了 2. Developer 没有 L3 权限 → 危险动作走人工审批 3. file_write 限定目录 → 不能改到 _generated/ 或 _archive/工具可靠性 Checklist每个工具接入前过一遍这张表检查项 PASS 标准 你的工具 ──────────────── ──────────────────── ──────── 风险分级 L1/L2/L3 已标记 □ 参数校验 必填项检查 类型校验 □ 返回值规范 成功/失败/异常 三态明确 □ 超时处理 有超时时间 超时后行为定义 □ 重试策略 幂等工具可重试非幂等不重试 □ 并发限制 同一工具同时调用数有上限 □ 范围约束 操作范围目录/表/API已限定 □ 异常降级 工具不可用时的备选方案已定义 □ 审计记录 调用参数返回值耗时 自动记录 □ 通过 7 项以上 → 可进入生产 通过 5-6 项 → 需要补关键防护 通过 4 项以下 → 只能用于实验环境RAG Harness接入不等于增益RAG 最常见的错觉“有知识就更准”。现实是检索可以增强决策也可以污染决策。关键不是接没接而是能不能证明接了之后确实更好。AIReview 规则检索的 A/B 测试数据 场景 无 RAG 有 RAG 增益 ──────────────── ────── ────── ────── 常见规则命名规范等 78% 82% 4pp ← 略有提升 复杂规则性能/安全 45% 71% 26pp ← 显著提升 模糊边界风格/建议 68% 61% -7pp ← 反而下降 分析 复杂规则模型参数里没有RAG 真正补上了知识缺口 → 增益大 常见规则模型参数里大概知道RAG 只是确认 → 增益小 模糊边界检索到的建议性内容和禁止性规则混在一起 Rerank 把建议排前面禁止规则被截断 → 反而退化“接了 RAG不等于系统更强”。必须分场景验证增益找出 RAG 真正帮了哪些场景、反而害了哪些场景。RAG 决策增益验证框架┌──────────────────────────────────────────────────────────────────────┐ │ RAG 增益四层验证 │ ├──────────────────────────────────────────────────────────────────────┤ │ │ │ Layer 1: 召回验证 │ │ ├── 目标文档是否在召回列表中 │ │ ├── 排序是否合理禁止性规则 建议性内容 │ │ └── 指标召回率、MRRMean Reciprocal Rank │ │ │ │ Layer 2: 拼装验证 │ │ ├── 召回片段是否被正确放入上下文 │ │ ├── 片段之间有没有版本冲突 │ │ └── 指标上下文内规则覆盖率、冲突检测率 │ │ │ │ Layer 3: 使用验证 │ │ ├── 模型是否真的引用了检索到的内容 │ │ ├── 引用是否对应最终结论不是装饰性引用 │ │ └── 指标引用准确率、空引用率 │ │ │ │ Layer 4: 决策增益验证 │ │ ├── 有 RAG vs 无 RAG 的准确率对比 │ │ ├── 哪些场景增益、哪些场景退化 │ │ └── 指标增益率 (有RAG准确率 - 无RAG准确率) │ │ │ │ 只验到 Layer 1 只知道找到了 │ │ 验到 Layer 4 知道找到了、用了、而且用对了 │ └──────────────────────────────────────────────────────────────────────┘真实案例AIReview 的 RAG 优化过程问题AIReview 检索同步 IO 禁止在主线程规则时经常漏报 排查过程按增益四层验证 Layer 1 召回验证 搜索 同步 IO → 召回 8 条结果 目标规则在召回列表中 ✓ → 召回没问题 Layer 2 拼装验证 Top-3 截断后传入上下文 #1: 建议使用异步 IO 提升性能 ← 建议性内容 #2: IO 操作最佳实践汇总 ← 综述类内容 #3: 禁止在主线程使用同步 IO ← 目标规则排第三 Rerank 把建议性内容排在禁止性规则前面 ✗ Layer 3 使用验证 模型引用了 #1 和 #2给出建议优化而非必须禁止 关键的禁止性规则虽然在上下文里但被前两条淹没了 ✗ 修复 1. 规则文档加分类标签[MUST] / [SHOULD] / [MAY] 2. Rerank 策略调整[MUST] 标签的文档权重 ×2 3. 拼装策略[MUST] 规则强制排在上下文最前 修复后效果 禁止性规则命中率60% → 92% 整体规则检测准确率72% → 85%工具 检索的联合可靠性在真实系统里工具和检索经常是联动的。可靠性问题也会联动放大联动风险场景配置表风险评估系统 ┌────────────┐ ┌────────────┐ ┌────────────────┐ │ RAG 检索 │────→│ 规则匹配 │────→│ 风险等级判定 │ │ 配表规则 │ │ 工具调用 │ │ 高/中/低 │ └────────────┘ └────────────┘ └────────────────┘ │ │ │ ▼ ▼ ▼ 如果检索到旧版 如果工具参数 如果判定为低风险 规则 → 漏报 传错 → 误报 但实际是高风险 → 上线事故 真实故障案例 配表规则文档上午更新下午系统还在引用旧版 原因索引重建是每日批量任务增量更新缺失 后果新版禁止某字段超过 100的规则没生效 高风险配表被自动放行 这不是模型判断差是 RAG 时效性问题 × 工具链路问题的叠加能力可靠性的分级治理不是所有工具和检索都需要同样等级的可靠性工程。投入应该和风险成正比风险等级 工具/检索类型 需要的可靠性层级 ──────── ──────────────── ────────────────────────────── L1 低 只读查询grep, file_read 参数校验 超时处理 信息类检索文档问答 L2 中 写操作file_write L1 范围约束 结果确认 判断类检索规则匹配 L1 增益验证 版本检查 L3 高 执行操作deploy, db_write L2 人工确认 回滚路径 合规类检索安全/法规规则 L2 强制 [MUST] 标签 溯源不同项目的能力 Harness 差异项目 工具可靠性重点 RAG 可靠性重点 ──────────── ────────────────── ────────────────────── activity-dev 权限分层读写隔离 不依赖 RAG harness pytest 超时/重试策略 知识在仓库结构里 AIReview 工具较少可靠性需求低 规则检索精度是核心 [MUST]/[SHOULD] 分级 增益 A/B 验证 配置表风险 批处理吞吐是重点 规则时效性是核心 评估 单工具多次调用的幂等性 增量索引 vs 批量重建 Crashsight 历史 crash 查询工具 历史根因检索质量 长文本处理能力 错误根因污染检测早期团队的最小可靠性方案Week 1: 给每个工具标上风险等级L1/L2/L3 2 小时 Week 1: 给 L2 工具加参数校验和超时处理 半天 Week 2: 给写操作加范围约束限定可操作目录/表 半天 Week 3: RAG 做一次有/无 A/B 对比找到增益和退化场景 1 天 Week 4: 给退化场景的检索加标签分级和 Rerank 调整 1 天 不要先做什么 ❌ 通用工具调用中间件先用 if-else 硬编码安全检查 ❌ RAG 评测平台先用脚本跑 A/B ❌ 全量审计系统先记 L3 工具的调用日志能力 Harness 的核心判断工具和检索都是 Agent 的能力接口但接入不等于可靠。工具可靠性的关键是分级治理——不是所有动作都需要同样的防护等级。RAG 可靠性的关键是增益验证——不是所有检索都在帮忙有些在添乱。Harness 的价值不是让 Agent 能做更多事而是让它做的每一件事都可控、可验证、可追溯。