1. Harness 到底是什么？#

最小 Agent 很容易写：

1
用户任务
2
  ↓
3
LLM
4
  ↓
5
工具调用
6
  ↓
7
工具结果
8
  └────────→ LLM（循环）

给模型 read、write、bash 三个工具，它已经可以表现得很像 Coding Agent。

问题是，demo 能跑不代表系统能长期跑。

Harness 可以理解为包在模型外面的执行控制层。 它决定：

1
模型能看到什么
2
模型能调用什么
3
每个工具能做什么
4
危险动作什么时候需要批准
5
代码在哪里执行
6
旧上下文什么时候被压缩/删除
7
失败后如何恢复
8
什么条件才算“任务完成”

所以同一个模型放进不同 Harness，实际 Coding 体验可以差得非常大。

这也是为什么只比较 SWE-bench 或某个模型的 coding score，经常无法解释真实开发体验。

2. 第一层：Tool Loop 不是 while(true) 那么简单#

一个成熟的工具循环至少需要区分三类状态：

1
Reasoning / Planning
2
        ↓
3
Tool Execution
4
        ↓
5
Observation
6
        ↓
7
Continue / Verify / Stop

最危险的实现，是让“模型说完成”直接等于任务完成。

更稳妥的做法是把停止条件拆开：

1. 模型认为任务已经完成；
2. Harness 检查是否满足验证条件；
3. 必要时执行 typecheck / lint / test / build；
4. 验证失败，把结构化错误重新交给 Agent；
5. 验证成功，才允许结束。

这其实是在把自然语言承诺变成机器可验证的完成条件。

例如：

1
const gates = [
2
  "pnpm typecheck",
3
  "pnpm lint",
4
  "pnpm test",
5
  "pnpm build",
6
]

真实项目不一定四项全跑，但思路很重要：Agent 的“我完成了”不能成为唯一 truth source。

3. 第二层：工具描述其实就是 Agent 的 API#

很多人会花大量时间调 system prompt，却只给工具写一句：

1
bash: execute shell commands

这相当于给人一把万能钥匙，却没有告诉他哪扇门可以开。

Vercel 的 Harness 教程强调把工具描述做成更明确的 contract。工程上可以把每个工具至少写成：

1
WHEN TO USE
2
WHEN NOT TO USE
3
INPUT CONTRACT
4
SAFETY / SIDE EFFECTS
5
EXAMPLES

例如 writeFile 和 editFile 应该明确区分：

• 新文件优先 writeFile；
• 已存在文件的小范围修改优先 editFile；
• 不允许用 write 静默覆盖未知内容；
• 修改后需要重新读取关键区域或运行验证。

这里有一个容易忽略的结论：

工具描述并不只是文档，它本身就是模型的“动作选择接口”。

工具越多，如果契约越模糊，Agent 反而越容易选错。

4. 第三层：不要把 bash 权限问题交给 Prompt#

“请不要执行危险命令”不是安全边界。

因为 Prompt 是行为引导，不是权限系统。

更合理的结构应该是：

1
LLM
2
 ↓
3
Tool Request
4
 ↓
5
Policy / Approval Gate
6
 ├─ safe → execute
7
 ├─ uncertain → ask / review
8
 └─ blocked → reject
9
 ↓
10
Sandbox

例如只读命令可以自动执行：

1
pwd
2
ls
3
cat
4
rg
5
git diff
6
git status

而下面这些操作应该进入更严格的策略：

1
rm
2
sudo
3
curl | sh
4
git push
5
npm publish
6
数据库 destructive migration
7
生产环境变更

真正可靠的 Agent 应该做到：模型即使判断错了，执行层仍能兜底。

5. 第四层：Sandbox 不是“云服务器换个名字”#

Coding Agent 天然需要执行不完全可信的内容：

• 用户仓库里的脚本；
• npm/pip install 的依赖；
• 测试命令；
• Agent 自己生成的代码；
• Issue 中提供的复现脚本。

因此把 Agent 直接放在宿主机执行，本质上是在把模型输出升级成系统权限。

Vercel 的思路是把工具依赖到统一的 Sandbox interface，而不是直接依赖 Node child_process：

1
interface Sandbox {
2
  readFile(path: string): Promise<string>
3
  exec(command: string): Promise<ExecResult>
4
  stop(): Promise<void>
5
}

底层可以替换为：

1
Local Sandbox
2
In-memory Sandbox
3
Remote MicroVM / Cloud Sandbox

这样工具层不需要知道代码究竟跑在哪里。

这个抽象非常关键，因为个人开发阶段可以用本地环境快速迭代，真正允许 Agent 接触陌生仓库时再切隔离执行层，而不用重写全部工具。

6. Context Pruning：长上下文不等于可以不管理上下文#

这是目前 Coding Agent 最容易被低估的一层。

假设 Agent 每轮读取：

1
文件：12K tokens
2
测试日志：8K tokens
3
搜索结果：5K tokens

10 轮之后，即使模型拥有非常大的 context window，也会出现两个问题。

第一是成本。大量已经失去价值的 observation 仍会参与后续请求。

第二是注意力污染。旧日志、旧代码和已经修复的错误继续存在，模型可能反复引用过时状态。

因此 Context Pruning 不只是为了“塞得下”，更是为了维持信息的新鲜度。

一种简单策略是：

1
永久保留：
2
- system / policy
3
- 用户原始目标
4
- 当前计划
5
- 最近关键决策
6

7
有限保留：
8
- 最近 N 次工具结果
9
- 当前正在修改文件的关键片段
10

11
压缩或删除：
12
- 已解决错误日志
13
- 大段重复文件内容
14
- 旧搜索结果
15
- 成功命令的冗长 stdout

甚至可以给工具输出设置硬上限：

1
rg → 最多 100 matches
2
build log → 保留 error + 前后窗口
3
readFile → 默认按 range 读取

这往往比单纯换一个 1M context 模型更有效。

7. 为什么 Explorer 和 Executor 应该分开？#

当任务变复杂后，一个 Agent 同时负责：

1
理解仓库
2
搜索实现
3
设计方案
4
修改代码
5
跑测试
6
排查失败

上下文很快就会变成一锅粥。

子代理真正有价值的地方，不是“多开几个模型显得高级”，而是隔离上下文和权限。

例如：

1
read
2
grep
3
git log
4
目录遍历

1
相关文件
2
调用链
3
可能修改点
4
风险

1
edit
2
write
3
bash（受控）
4
test

8. AGENTS.md 的价值不是“再加一份 Prompt”#

项目级 Agent 配置最有价值的信息通常不是“你是一名优秀工程师”，而是仓库事实：

1
# Project Rules
2

3
- package manager: pnpm
4
- run `pnpm lint` before finishing
5
- do not modify generated files under src/generated
6
- database migrations must be additive
7
- use existing UI components before adding dependencies

这些规则应该由 Harness 在进入仓库时自动发现并注入，而不是每次让用户重新说明。

更进一步，可以按目录加载局部规则：

1
repo/AGENTS.md
2
repo/frontend/AGENTS.md
3
repo/backend/AGENTS.md

这样 Agent 在处理 frontend 时不需要携带全部 backend 约束。

本质上，这是一种按作用域加载 context 的机制。

9. 一个个人开发者能复现的最小 Harness#

如果不是要造下一个 Claude Code，而只是想做自己的 Coding Agent，我会从下面这个版本开始：

1
                ┌──────────────┐
2
                │  User Goal   │
3
                └──────┬───────┘
4
                       ↓
5
              ┌─────────────────┐
6
              │   Main Agent    │
7
              └───┬─────────┬───┘
8
                  │         │
9
          explore │         │ execute
10
                  ↓         ↓
11
          ┌───────────┐  ┌───────────┐
12
          │ Explorer  │  │ Executor  │
13
          └─────┬─────┘  └─────┬─────┘
14
                │              ↓
15
                │       Approval Policy
16
                │              ↓
17
                └──────→   Sandbox
18
                               ↓
19
                     typecheck/lint/test
20
                               ↓
21
                         Verify Gate

第一版只需要做好六件事：

1. read / grep / edit / write / bash 工具；
2. bash allowlist + destructive command gate；
3. 每个工具限制输出大小；
4. 自动读取项目级 AGENTS.md；
5. stale tool result pruning；
6. 完成前强制 verification。

先把这六个做扎实，再考虑 browser、MCP、memory、多 Agent swarm。

10. 怎么 benchmark Harness，而不是只 benchmark 模型？#

我更推荐准备一个固定仓库，重复做五类任务：

然后分别测试：

1
A. 不 pruning
2
B. pruning tool output
3
C. pruning + Explorer subagent
4
D. pruning + subagent + verification gate

模型保持不变。

如果 D 的成功率明显提升，你测到的就是 Harness 带来的收益，而不是把所有改进都归功于 LLM。

同时记录：

1
TTFT
2
总输入 tokens
3
总输出 tokens
4
工具调用次数
5
失败工具调用次数
6
测试执行次数
7
最终 wall-clock time

这样才有机会回答“更复杂的 Agent 架构到底值不值”。

11. 一个越来越重要的工程判断：Context Window 是资源，不是垃圾桶#

过去一年模型上下文不断变长，很容易形成一种错觉：

既然能塞 200K、1M tokens，那就全部塞进去。

Coding Agent 恰好说明了为什么这不成立。

Agent 的问题不是只有“记不住”，还有：

1
记住了太多过期信息
2
不知道哪条信息仍然有效
3
工具结果重复
4
状态与文件系统现实脱节
5
验证结论已经变化

因此未来优秀 Harness 的竞争点，很可能不是“支持最大上下文”，而是：

能否持续把最相关、最新、可验证的信息留在工作集里。

这也是 context engineering 和普通 prompt engineering 最大的区别之一。

12. 结论#

Vercel 这套 Coding Agent Harness 教程真正值得看的，不是某个 TypeScript API，而是它把 Agent 工程拆成了清晰的控制面：

1
模型负责判断
2
工具负责能力
3
Policy 负责权限
4
Sandbox 负责隔离
5
Context Manager 负责工作集
6
Subagent 负责上下文分工
7
Verification 负责事实闭环
8
Lifecycle 负责长期运行

当模型能力越来越接近时，这些外围系统反而越来越决定实际体验。

如果你的 Agent 经常“前十分钟很聪明，半小时后开始失忆”，先别急着换模型。

先检查：是不是把所有工具输出都永久塞在 context 里？是不是没有验证门？是不是 bash 没有执行层权限控制？是不是探索和实现共享了一份越来越脏的上下文？

很多时候，Coding Agent 真正需要升级的不是 brain，而是 harness。

参考资料#

• Vercel Academy — Build Your Own AI Coding Agent Harness: https://vercel.com/academy/build-ai-agent-harness
• Vercel Academy — Builders Guide to the AI SDK: https://vercel.com/academy/ai-sdk
• Vercel Sandbox 文档与实践指南: https://vercel.com/docs/vercel-sandbox
• Anthropic — 2026 Agentic Coding Trends Report: https://resources.anthropic.com/2026-agentic-coding-trends-report
• Bui, Building AI Coding Agents for the Terminal: Scaffolding, Harness, Context Engineering, and Lessons Learned, arXiv<2603>.05344

注：本文对 Harness 架构、benchmark 设计和最小实现的部分属于基于公开资料给出的工程分析，并非 Vercel 官方性能结论。文中没有把未经复现的社区数据作为实测结果。