30秒快速回答: Harness(脚手架)是模型之外那层让它”能干活”的代码与配置——工具循环、文件与 Shell 访问、权限系统、上下文管理、反馈回路。Harness Engineering 就是有意识地设计这一层,而不是让 SDK 默认值说了算。2026 年业界流行的一句概括是:Agent = Model + Harness。
核心价值一句话: 模型选型你多半左右不了,Harness 才是你天天在改却不自知的那层——把它当架构决策,不是工具偏好。
一、三个”工程”,解决三个不同层次的问题
行业话术从”提示词写得好不好”演进到”上下文喂得对不对”,2026 年多出来的这层管执行。三者是分层关系。
| 层次 | 管什么 | 典型症状 | 交付物 |
|---|---|---|---|
| Prompt Engineering | 单次对话怎么问 | 问得含糊,答得飘 | 一段提示词 |
| Context Engineering | 这一步该看到哪些 token | 越聊越笨、关键信息被挤掉 | 检索与压缩策略 |
| Harness Engineering | 模型之外整个执行系统怎么搭 | 工具调错、跑飞、改一处崩三处 | 权限模型、沙箱、循环、验收信号 |
常见误解是把 Harness 等同于”选个 Agent 框架”。框架只是骨架,差别在执行细节:同一个模型,放进只读工具、每步必须跑测试的 Harness,和放进有 root 权限、循环不设上限的 Harness,就是两个物种。
二、Harness 的六层组件
主流实现横着切开,几乎是同一套分层:
| 层 | 职责 | 缺了会怎样 |
|---|---|---|
| 工具注册表 | 工具名、参数 Schema、描述 | 反复幻觉出不存在的工具 |
| 权限与审批 | 允许 / 询问 / 拒绝三档、审批门 | 一次误删就是事故 |
| 隔离与沙箱 | 限定可写目录、网络、执行范围 | 提示注入变成任意代码执行 |
| 上下文管理 | 压缩、卸载、渐进披露、跨会话记忆 | 长任务跑到一半忘目标 |
| 循环控制器 | 迭代次数、终止条件、失败升级 | 无限循环烧钱,或提前放弃 |
| 反馈与验证 | 测试、构建、类型检查、结构化输出 | 收敛到自信的空话 |
最下面那层值得强调:验证层是模型无法补偿的部分。给它客观信号(测试红了、Schema 不合法),它就有方向;只让它重读输出,只会越读越确信。
三、隔离策略:OS 级沙箱,还是应用层权限
这是搭 Harness 第一个要拍板的决策,两条路线都成熟:
| 维度 | OS 级沙箱 | 应用层权限 |
|---|---|---|
| 强制方式 | 内核默认拒绝,限定文件系统与网络 | 规则 + 钩子,调用前拦截 |
| 典型代表 | Codex 类容器隔离 | Claude Code 类 allow / ask / deny 规则 |
| 优点 | 兜得住模型”没想到”的越界 | 灵活、可读、易调试 |
| 弱点 | 配错一次就全局敞开 | 钩子漏一处就漏一条路 |
| 适用 | 不可信输入、跑生成代码 | 内部可信任务、需细粒度审批 |
结论不是二选一。 面向不可信输入时,应用层权限做语义过滤(这个工具该不该调),OS 沙箱做物理兜底(调了也只能碰这个目录)。两条都上才有纵深。
四、循环工程:形状、终止、验证
Agent 循环不是既定事实,而是设计面。最容易被忽略的是终止——别写 while not done,让模型自己宣布完成。
MAX_ITER, BUDGET = 12, 800_000 # 迭代上限与预算
def run_agent(task, tools, call_model, verify):
state, used = [{"role": "user", "content": task}], 0
for i in range(MAX_ITER):
resp = call_model(state, tools) # 推理
used += resp.usage
if used > BUDGET: # 2. 预算熔断
return {"status": "budget_exceeded", "iter": i}
if not resp.tool_calls: # 3. 想收工?先过验证
ok, why = verify() # 客观信号
if ok:
return {"status": "ok", "answer": resp.content}
state.append({"role": "user",
"content": f"验证未通过:{why}\n请修复后重试。"})
continue
for call in resp.tool_calls: # 执行并回填
result = tools[call.name](**call.args)
state.append({"role": "tool", "name": call.name,
"content": str(result)[:4000]})
return {"status": "max_iter_reached", "state": state}
三条可复用判断:
- 循环形状决定成本:单轮”生成→验证→修复”便宜但易进死胡同;”先计划再执行”稳但多一轮;”分支子 Agent 再合并”能并行,但合并须验证。
- 终止必须是外部条件:测试通过、构建成功、迭代上限、超预算,四个都要有。
- 长任务靠外置状态:把进度写进
progress.md,上下文重置后能读回来接着干。
五、上下文文件与记忆:可移植的知识,可审查的记忆
把项目约定放进版本化文件而非工具私有设置,是 Harness 可替换的前提:
# 项目约定
- 包管理器:pnpm(禁止 npm install)
- 提交前必须通过:pnpm lint && pnpm test
- 数据库迁移只能新增,不许修改历史 migration
# 已知坑
- 本地起服务需先 source .env.local,否则报 DB 连接失败
- 测试里的时间断言统一用 fakeTimers,别用 sleep
这份 AGENTS.md 喂给 Claude Code、Codex、Cursor 都成立,换工具不换知识。但记忆要当不可信输入对待:Agent 写回的记忆很有用,一旦写进错误结论,会安静地污染之后每次运行。稳妥做法是把记忆与指令变更纳入版本控制和代码评审。
六、三个最容易踩的坑
- 审批疲劳:什么都弹确认框,用户第三次开始闭眼点同意,审批门就成了橡皮图章。只留给不可逆操作、外部通信、凭证、生产系统四类。
- 审批界面本身是攻击面:被提示注入劫持的 Agent 能把请求写得很合理。审批卡片要展示原始参数,而不是润色过的说明。
- 工具越多越笨:工具集膨胀带来工具空间干扰,选错概率上升。宁可拆多个窄 Agent。
总结
Harness 不是某个框架的功能,而是你架构里的四个决定:权限模型怎么定、隔离在哪一层、循环怎么终止、反馈信号从哪来。这四件事定下来,具体工具都可替换。
三条落地建议:权限与沙箱模型先写进设计文档;项目约定集中到 AGENTS.md 并纳入 Git;给每个循环配一个不依赖自述的验证信号。做完这三步,就比”接个 SDK 上线”稳一个量级。
延伸阅读建议: 本博客《上下文腐烂(Context Rot)》《规格驱动开发(SDD)》《验证税(Verification Tax)》《工具空间干扰(TSI)》四篇,正好覆盖 Harness 最易出问题的四个角落——上下文、规格、验收与工具设计。