# InvesResearch Agent · Harness 工程最佳实践调研报告

> 2025–2026 年 AI Agent harness 工程领域的实践共识与本项目的取舍 · **版本 v1.0**
>
> 关联文档:[工程 PRD](./engineering-prd.md)(其架构设计大量引用本报告)· [架构决策](./architecture-decisions.md)
>
> 本报告的定位:工程 PRD 把 harness 工程的结论"用"了起来,这份报告则把这些结论的**来龙去脉**讲清楚——为什么 harness 与 agent 要解耦、八个子系统从何而来、上下文为什么要这样管、评估为什么要驱动开发。它是工程 PRD 背后的方法论底稿。

---

## 1. 核心范式:Harness 与 Agent 解耦

2025–2026 年 agent 工程领域最重要的一个范式转变,是把"承载运行的工程骨架(harness)"与"可替换的模型与 agent 逻辑"显式分开。

这件事为什么重要,可以用一个反复出现的现象来理解:**大模型每升级一次,围绕它搭建的复杂度就要被重新定价。** 今天为了弥补模型短板而写的一堆 guardrail——循环检测、格式纠正、重试包装——明天换一个更强的模型可能就成了纯粹的累赘。如果这些防护逻辑和业务逻辑、状态管理纠缠在一起,你就没法干净地删掉它们,只能任由复杂度累积。

解耦的架构让你能在不动核心业务逻辑的前提下,既给 harness 做加法,也做减法。这是本项目把系统拆成 Harness / Agent Logic / Capability 三层(见架构说明)的根本动因。

---

## 2. Harness 的八个子系统(业界共识)

把 harness 这一层展开,业界逐渐收敛出八个职责清晰的子系统。本项目直接采纳这套分层。

会话层负责持久化状态(本项目用 LangGraph 的 Postgres checkpointer);控制平面负责编排循环本身;上下文构建器负责上下文调度与压缩;工具路由器负责把动作意图分发到正确的工具;沙箱负责隔离执行不可信代码;凭证代理负责守住凭证边界(agent 永远看不到密钥);追踪层负责记录全过程;评估层负责对结果做评判。

每个子系统单一职责、边界清晰,可独立测试、独立替换——这是这套分层最大的工程价值。

---

## 3. 上下文工程:用最小高信号 token 驱动 agent

上下文是有限资源,且边际收益递减。业界四个公认手段,本项目全部采用。

**压缩(compaction):** 在上下文使用接近窗口上限时触发。参照 Claude Code 的经验,在估计达到窗口 90% 时压缩、75% 时先预警。采用两阶段 fallback——先把过大的工具返回截断,仍不够则对中间内容做摘要、保留头尾。

**子代理隔离:** 这是最强的上下文防御。每个子 agent 在独立窗口里工作,只把结构化摘要回传,而非把全部原始数据塞回主上下文。好处是双重的——一个失败的子代理不会拖垮整个编排;一次消耗五万 token 的探索可以被压缩成两千 token 的摘要回传。当某个操作预计消耗超过上下文利用率的四到六成时,就应主动派生子代理。

**渐进披露:** 由 Skills 机制天然实现。启动时只加载所有 Skill 的名称和描述(每个约一百 token),激活某个 Skill 时才加载完整正文,正文引用的详细文档再按需加载。

**外置与检索:** 历史调研、研报、电话会、新闻存在向量库里,需要时动态检索,而非常驻上下文。

---

## 4. 编排框架选型:为什么是 LangGraph

在与 CrewAI、AutoGen、OpenAI Agents SDK 的对比中,LangGraph 在生产可控性上最强:显式状态机(有向图 + 条件边)、内建 checkpointing 与 durable execution、interrupt 机制支持人工介入、子图支持模块化、Send 原语支持并行 fan-out。

成本是关键差异:独立基准显示 CrewAI 在简单工作流上的 token 开销约为 LangGraph 的三倍,而 AutoGen 的群聊模式每个任务要消耗 20 次以上 LLM 调用,成本最高。对一个既要多 agent 协作、又要严格控成本和保证可恢复性的系统,LangGraph 是当前最稳妥的选择。

这个决策有明确的可逆点:如果某次迭代退化成纯单 agent 调工具,可降级用更轻的 OpenAI Agents SDK;如果需要超过五个角色的复杂协作且预算充足,可重新评估 Microsoft Agent Framework。

---

## 5. 成本与模型路由

成本控制应内建在编排里,而非事后优化。核心手段是 model routing:不同角色分配不同档位模型——规划、估值终审、PM 结论、多空辩论用强模型(Opus、GPT-5);情绪打分、新闻摘要、数据格式化、资料检索用廉价模型(Haiku、DeepSeek、Qwen)。路由经 LiteLLM 或 OpenRouter 网关实现,网关同时提供 provider 级 failover。每个节点执行后更新成本计数,触及单会话预算 80% 告警、100% 熔断。

---

## 6. 评估驱动开发

这是 harness 工程区别于普通后端工程的核心:把"什么算做对了"变成可执行的检查。采用离线 + 在线双层评估。

离线评估基于一个代表性任务数据集,每个任务配黄金答案或参考研报,既建立基线也做回归——每当 prompt 或模型变更,在同一数据集上重跑对比指标。评估方法分两种:确定性检查(能否反序列化、是否符合 schema、引用覆盖率、数值是否落在合理区间)用于一切可机械判定处,因为快速、便宜、可靠;LLM-as-judge 用于需主观判断处,但必须配人工校准。

一个必须警惕的陷阱:LLM judge 有系统性偏差,对表层线索、文本长度、选项顺序敏感,且 agent 的思维链不一定忠实反映真实推理。因此关键决策点绝不能只靠 LLM judge,要用确定性检查兜底,并定期用人工标注校准。评估应集成进 CI,任何影响 agent 行为的变更在通过回归前不得合并。

---

## 7. 安全:MCP 与 Skills 是新攻击面

MCP 和 Skills 是 2025–2026 年新增的主要攻击面,安全必须内建。遵循 OWASP MCP Top 10 做检查清单,重点防范:prompt injection 与 tool poisoning(工具输出当数据非指令处理,剥离可疑标签);供应链投毒(第三方 Skill 和 MCP server 上线前完整源码审计 + CI 扫描,本地 MCP 容器沙箱隔离);凭证泄露(凭证代理边界,agent 看不到任何密钥);过度权限(每个 Skill 的 `allowed-tools` 白名单,最小权限授予)。任何破坏性操作要求人工批准。

---

## 8. 结论

这套 harness 最佳实践不是凭空选择,而是从本项目的具体约束——多 agent 协作、严格控成本、要可恢复、要可观测、面向机构有数据主权要求——推导出来的。它的精髓是:把会变的(模型、数据源)和稳定的(流程知识、编排骨架)分层隔离,用最小高信号上下文驱动 agent,用评估而非直觉驱动迭代,把安全内建而非事后补。

---

> **免责声明** — 本报告引用的技术基准、框架对比、成本数据为 2025–2026 年快照,部分来自厂商博客与社区文章,实施前请核对官方文档。本报告仅用于工程设计参考。