Skip to main content

4.3 Harness Engineering：约束环境工程

Harness Engineering 强调通过构建受控环境，让 Agent 在约束下高效可靠地完成长周期复杂任务。包含围绕 Agent 构建约束机制、反馈回路、可靠上下文等等一系列工程实践。

为什么需要 Harness？​

Agent 的"失控"风险​

给 Agent 完全自由 = 危险

可能发生：
❌ 误删文件
❌ 执行危险命令
❌ 无限循环烧钱
❌ 把系统搞崩
❌ ...

Harness 的作用​

Harness = Agent 的"安全绳"

✅ 安全地探索
✅ 犯错也不会造成大问题
✅ 出了问题可以回滚
✅ 始终在可控范围内

Harness 的核心设计原则​

1. 最小权限原则​

Agent 只拥有完成任务必需的权限，不多给。

❌ 不好的设计：给 Agent 完整 sudo 权限
✅ 好的设计：只给 Agent 某个目录的读写权限

2. 所有操作可回滚​

任何改变都可以撤销。

文件修改 → 自动备份 → 出问题一键恢复
Git 操作 → 在临时分支 → 不满意可以删除
命令执行 → 先 Dry Run → 用户确认后才真正执行

3. 渐进式披露​

不是一开始给所有信息和权限，按需逐步给。

第一步：只读权限 → 可以看文件
第二步：用户确认 → 可以修改少量文件
第三步：用户再次确认 → 可以执行命令
...

核心约束机制​

1. 沙箱环境​

┌─────────────────────────────────┐
│         Agent 沙箱                  │
│  ┌───────────────────────────┐  │
│  │   临时工作目录           │  │
│  │   隔离的进程空间        │  │
│  │   受限的网络访问        │  │
│  └───────────────────────────┘  │
│                                 │
│  所有改变可以一键销毁          │
└─────────────────────────────────┘

实现方式：

  • Docker 容器
  • 临时目录
  • 白名单网络
  • 资源限制（CPU/内存/磁盘）

2. 操作审计​

所有操作都有记录，出了问题可以追溯。

[2024-01-15 10:30:00] READ file: src/utils.py
[2024-01-15 10:30:05] EDIT file: src/utils.py
[2024-01-15 10:30:10] RUN command: npm test
[2024-01-15 10:30:15] DELETE file: temp.txt

审计日志包含：

  • 时间戳
  • 操作类型
  • 操作内容
  • 执行结果
  • 耗时

3. 批准门（Approval Gates）​

危险操作需要用户确认。

风险等级评估：
  🟢 低风险：自动执行
    - 读取文件
    - 列出目录
    - 运行测试

  🟡 中风险：询问确认
    - 修改代码
    - 安装依赖
    - 网络请求

  🔴 高风险：必须强确认
    - 删除文件
    - 生产环境部署
    - 发送消息
    - 花钱的 API 调用

4. 资源限制​

防止 Agent 消耗太多资源。

⏱️ 超时限制：单个命令最多运行 30 秒
💾 磁盘限制：最多使用 1GB 磁盘
🔄 调用次数：API 调用频率限制
💰 成本限制：每天最多花费 $5

反馈回路设计​

实时进度可见性​

用户随时知道 Agent 在做什么：

🔄 正在执行：第 3/5 步
   ├─ ✅ 已完成：读取配置文件
   ├─ ✅ 已完成：分析依赖关系
   ├─ 🔄 进行中：重构代码
   ├─ ⏳ 待执行：运行测试
   └─ ⏳ 待执行：提交代码

预计还需：2 分钟

人机交互回路​

Agent：我需要执行一个危险操作，请确认：
> 操作：删除 node_modules 目录
> 原因：重新安装依赖
> 风险：可能需要 5 分钟下载时间

[✅ 批准 | ❌ 拒绝 | ✏️ 修改方案

中断与回退机制​

用户随时可以：
  ⏸️ 暂停执行
  ⏹️ 停止执行
  ↩️ 回滚到上一步
  🔄 重新开始

长周期任务的可靠性工程​

状态持久化​

任务执行到一半中断了可以恢复。

每完成一步保存一次状态：
  state = {
    "step": 3,
    "completed": ["读取文件", "分析代码"],
    "current": "重构中",
    "history": [...],
    "checkpoints": ["2024-01-15T10:30:00"]
  }

中断后恢复：
  读取状态 → 从上次的地方继续

检查点与回滚​

关键节点创建检查点，可以随时退回去。

开始
  ↓
执行步骤 1 → 检查点 1
  ↓
执行步骤 2 → 检查点 2
  ↓ 出问题了！
  ↓
回滚到检查点 1 → 重新尝试

错误处理与重试​

操作失败：
  ↓
是临时错误吗？→ 重试 3 次
  ↓
还是失败？
  ↓
尝试替代方案
  ↓
还是不行？
  ↓
停下来问用户怎么办

Claude Code 的 Harness 设计​

分层权限模型​

Level 0：完全隔离
  - 只能读取，不能改变任何东西

Level 1：开发模式
  - 可以修改项目文件
  - 可以运行测试

Level 2：完全模式
  - 可以执行任意命令
  - 可以提交代码
  - 危险操作需要确认

渐进式授权​

用户："帮我写个功能"
  ↓
Claude Code：我需要修改文件权限，可以吗？
  ↓ 用户批准
Claude Code：开始写代码...
  ↓
Claude Code：我需要运行测试，可以吗？
  ↓ 用户批准
Claude Code：运行测试...

透明的操作过程​

📝 修改了文件：src/auth.js
   显示 diff：+15 -3 行

✅ 运行了命令：npm test
   输出：12 测试通过，0 失败

...

Harness 的权衡艺术​

约束 vs 效率的平衡​

约束太多 → Agent 什么都做不了 → 效率低下
约束太少 → 太危险 → 容易出问题

找到平衡点：
  安全前提下尽可能给最大自由

自动化 vs 人工干预​

全自动：快但可能出错
全人工：安全但慢

→ 自动化低风险，人工审核高风险

Harness Engineering 不是限制 Agent，而是解放它。有了安全绳，才敢让它跑更快、做更复杂的任务。

Last updated on by Kimi Gao