Agent Harness 05：框架地图与选型
先按研究问题选，不按功能数量选
不同项目常被一起称为 Agent framework，但它们位于不同层：
| 项目 | 主要层次 | 最适合 | 不应期待它自动解决 |
|---|---|---|---|
| mini-SWE-agent | 最小 coding harness | 模型/提示基线、教学、批量轨迹 | 丰富 ACI、完整产品权限治理 |
| SWE-agent | 可配置 ACI 研究框架 | 工具集、history processor、编辑接口实验 | 通用桌面/业务流程 |
| OpenHands | 通用软件 Agent 平台 | 沙箱、事件流、浏览器、多 Agent、基准接入 | 证明某个组件带来因果提升 |
| DSPy | 可优化 LM program | signature、模块、prompt/demo 优化 | OS 沙箱、真实副作用事务 |
| BrowserGym + AgentLab | 浏览器环境与实验管理 | 统一网页 observation/action、跨基准实验 | 代码仓库与任意桌面应用 |
| OSWorld | 桌面环境与 benchmark | 跨应用 GUI、环境初始化与执行式验收 | 生产权限与企业集成 |
| τ-bench | 工具—用户—政策 benchmark | 多轮客服、数据库终态、pass^k | 通用 Agent 产品运行时 |
| AgentDojo | 安全 benchmark | prompt injection 攻防与效用联合评估 | 完整生产防御方案 |
BrowserGym 的统一生态论文发表于 TMLR 2025；SWE-agent、OpenHands、OSWorld、τ-bench 与 AgentDojo 的会议和贡献见论文谱系。
最小实现、研究框架、平台的分工
需要看清每一行控制流？
└─ mini_harness / mini-SWE-agent
需要研究工具接口或上下文处理？
└─ SWE-agent
需要完整软件 Agent 平台与多种执行环境？
└─ OpenHands
需要公平评测浏览器、桌面、客服或安全？
└─ BrowserGym / OSWorld / tau-bench / AgentDojo一个严谨项目通常会组合两类：用最小或完整 runtime 运行策略，用独立 benchmark harness 初始化和判分。不要让被测 Agent 同时控制 evaluator。
mini-SWE-agent 与 SWE-agent：一个重要的时代变化
SWE-agent 的 NeurIPS 2024 论文证明了定制 ACI 的价值。到 2026 年，官方仓库明确把 mini-SWE-agent 作为默认选择：更强模型已经能直接使用 shell，线性历史和独立命令更易调试、隔离和扩展；原 SWE-agent 则继续适合研究不同工具集和 history processor。
这不是“A CI 研究被推翻”，而是最优接口随模型能力变化：
| 条件 | 更可能合适的接口 |
|---|---|
| 模型较弱、编辑易错 | 小而专用、反馈明确的工具 |
| 模型已充分学会 shell | 简单 shell + 强沙箱可能更有效 |
| 动作含高风险业务副作用 | 结构化工具 + 参数策略 + 审批 |
| 需要循环和多 API 组合 | 受限 CodeAct / 脚本执行环境 |
因此 ACI 必须跟模型一起做消融，不能把 2024 年最佳工具集永久固化。
选型问题清单
1. 你研究的是策略还是基础设施？
- 新规划/反思/训练方法：尽量复用现成环境和 evaluator；
- 新工具/上下文/沙箱方法：固定模型与任务集；
- 产品落地：优先权限、恢复、审计与运行成本，benchmark 名次次之。
2. 环境状态能否程序化验收？
- 仓库补丁：测试、静态检查、diff 约束；
- 浏览器：后端数据库或 DOM/应用状态，避免只看截图；
- 桌面：文件、应用内部状态与跨应用不变量；
- 客服：目标数据库状态 + 政策过程断言。
若现成框架只支持模型裁判，而任务可执行验证，应先补 evaluator。
3. 副作用风险到哪一级？
| 级别 | 示例 | 最低控制 |
|---|---|---|
| R0 | 纯文本、只读离线数据 | 预算、Trace |
| R1 | 临时 workspace 写入 | 路径限制、快照、清理 |
| R2 | 网络读取、外部 API 查询 | egress allowlist、凭据隔离 |
| R3 | 发信、提交代码、改数据库 | 参数策略、审批、幂等、审计 |
| R4 | 支付、生产部署、删除 | 多方授权、事务/回滚、强隔离 |
框架有“confirm”按钮不等于已经满足 R3/R4。
4. 能否固定版本并导出原始轨迹？
最低要求：
- 代码 commit 与配置；
- prompt 和 tool schema；
- 模型精确版本与请求 id；
- 环境 image digest；
- 每轮原始输出、策略决策与工具结果；
- evaluator 版本和逐项结果；
- token、费用、step 与时延。
拿不到这些数据的框架不适合作为严谨实验底座。
三套推荐组合
A. 学习与组件消融
本专题 mini_harness
+ ScriptedModel 做协议测试
+ 一个真实 ModelAdapter
+ 自建 20–50 个程序化任务优势是每个机制都看得见；缺点是执行隔离、批量调度和 UI 要自己补。适合先回答“某个组件到底有没有用”。
B. 软件工程研究
mini-SWE-agent 或 SWE-agent
+ 固定容器镜像
+ SWE-bench 类任务/evaluator
+ 独立轨迹分析研究模型和训练时优先 mini-SWE-agent，减少 scaffold 混杂；研究 ACI 和 history 时用 SWE-agent。复杂平台对照可加入 OpenHands，但要控制模型、预算和镜像。
C. 通用交互与安全
自有策略/Agent
+ BrowserGym 或 OSWorld 的环境层
+ AgentDojo 风格攻击集
+ tau-bench 风格重复可靠性正常效用、安全、成本分别报告。不要从 WebArena 成功率直接推断生产浏览器 Agent 安全。
对通用编排框架的判断
图编排、handoff、多 Agent、durable workflow 很有用，但它们通常只解决“节点怎样连接”。选用前仍要确认：
- Tool schema 之后是否有参数级 Policy；
- checkpoint 是否位于副作用前后；
- retry 是否理解幂等；
- 工具执行是否真正隔离；
- observation 是否带来源与信任域；
- evaluator 是否独立于 Agent；
- Trace 是否能重放实际模型输入。
若答案是否定的，编排框架只是 harness 的控制流部分。
迁移原则
把自己的系统保持在四个稳定接口上，框架才可替换：
ModelAdapter.next_action(context) -> Action
Policy.authorize(identity, action, state) -> Decision
Executor.execute(action, capability) -> Observation
Evaluator.evaluate(task, final_state, events) -> Score业务工具、权限和 evaluator 不应依赖某个 prompt 模板；模型 provider 字段不应泄漏到每个节点；框架事件应转换成自己的审计 schema。
当前建议
- 用本专题的最小实现理解并测试边界；
- coding agent 基线从 mini-SWE-agent 起步；
- 研究 ACI 时加入 SWE-agent 做对照；
- 需要完整软件 Agent 平台时评估 OpenHands；
- 按任务域接 BrowserGym、OSWorld、τ-bench 或 AgentDojo，而不是自创不可比较的 demo；
- 无论选哪个框架，都用评测与安全门禁约束发布。