适用场景与目标

适用场景：

• 你在用 AI 编程助手（Cursor、Copilot）但 AI 经常”跑偏”——删错文件、忽略项目规范、陷入无限循环
• 你在构建 AI Agent，需要让它稳定完成多步骤任务，而不只是生成一次性的回答
• 你的团队想让 AI 自主完成长时任务（数小时），但缺乏可靠的容错和恢复机制
• 你在考虑如何把 AI 落地到真实生产环境，而不是停留在 Demo 阶段

核心目标： 在不更换底层大模型的前提下，通过优化 AI 的”运行环境”（即 Harness），让 AI 任务成功率翻倍、成本下降、线上事故减少。

一句话理解： 大模型是”算力 CPU”，Harness 是包裹在它外围的”操作系统”——你不能让 CPU 自己踩刹车，你得在它外面装一套。

---

最小可行方案（MVP）步骤

第一步：从一份 AGENTS.md 起步（Day 1）

在项目根目录创建 AGENTS.md，这是 Harness 的最简化起点：

# AGENTS.md — AI Agent 工作规范

## 项目概述
[描述项目是做什么的]

## 行为红线（绝对禁止）
- 不执行 `rm -rf /` 或任何删除根目录操作
- 不修改非当前任务相关文件
- 不在未确认的情况下执行破坏性 Git 操作（force push、直接删除分支）

## 文件修改规范
- 每次修改前读取文件内容，确认目标位置
- 修改后运行对应测试，验证不破坏现有功能
- 单次 PR 只解决一个问题，拒绝"顺便改一下"

## 工具使用规范
- 优先使用 `read` 查看文件，再用 `edit` 修改
- 复杂重构前先在本地备份（`git commit`）
- 删除文件前确认该文件已无用且有版本记录

## 长任务规范
- 任务超过 10 个步骤时，每完成 5 步向人类报告一次进度
- 遇到不确定操作时，停下来询问，不要猜测
- Token 消耗超过 500K 时主动暂停，汇报当前状态

## 上下文管理
- 每个任务单独开一个会话，不跨任务共享上下文
- 重要结论必须写入文件，不能只"留在对话里"

为什么有效： Mitchell Hashimoto 说过：“每当 AI 犯错，就工程化一个方案，让它永远不再犯同样的错。” AGENTS.md 就是那个”方案”——AI 每次读到这个文件，就像新员工读入职手册。

第二步：引入安全沙箱（Day 2-3）

用 OpenClaw（国产”龙虾”）或类似的管控平台，搭建安全沙箱：

# 安装 OpenClaw（示例）
npm install -g openclaw
openclaw init my-agent-project
cd my-agent-project
openclaw config set --key sandbox.enabled --value true
openclaw config set --key sandbox.allowDelete --value false
openclaw config set --key sandbox.maxConcurrentAgents --value 5

核心配置原则：

• allowDelete: false — 删除操作必须人工二次确认
• sandbox.maxConcurrentAgents — 防止多 Agent 锁竞争（参考 Cursor 的教训：20 个 Agent 并发时吞吐量下降到 2-3 个的效率）
• 设置单次任务 Token 上限，避免无限循环烧钱

第三步：构建分层架构（Day 4-5）

参考 Stripe 的 Blueprint 编排系统，将 Agent 工作流拆分为：

确定性节点（Deterministic）: linter、格式化、测试运行
Agentic 节点（Agentic）     : 功能实现、代码审查、架构设计

配置文件示例：

# blueprint.yaml
nodes:
  - name: lint
    type: deterministic
    command: "npm run lint"
    failOnError: true
    
  - name: implement
    type: agentic
    model: gpt-4o
    maxSteps: 20
    allowedTools: ["read", "edit", "grep", "exec"]
    blockedTools: ["rm", "git push"]
    
  - name: test
    type: deterministic
    command: "npm test"
    requirePreviousNodeSuccess: true

第四步：设置 CI/CD 拦截门禁（Day 6-7）

# .github/workflows/agent-guard.yml
name: Agent Guard
on: [push, pull_request]

jobs:
  harness-check:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      
      - name: 运行 Linter
        run: npm run lint
        
      - name: 运行测试套件
        run: npm test -- --coverage --ci
        
      - name: Agent 修改量检查
        run: |
          CHANGES=$(git diff --stat | tail -1 | awk '{print $1}')
          if [ "$CHANGES" -gt 50 ]; then
            echo "⚠️ 单次修改超过 50 个文件，请拆分 PR"
            exit 1
          fi
          
      - name: 敏感操作审计
        run: |
          if git log -1 --pretty=%B | grep -iE "rm|deleting|drop"; then
            echo "🚨 检测到敏感操作，需要人工审核"
            exit 1
          fi

---

关键实现细节

多 Agent 并发防撞车机制

Cursor 团队的教训：20 个 Agent 并发时互相锁死。解决方案是”工头-工人”模式（参考 Anthropic 的 Git 锁文件方案）：

# coordinator_mode.py
import asyncio
from collections import defaultdict

class PermitDesk:
    """许可单系统：同一操作同一时间只有一个人能领"""
    def __init__(self):
        self._permits = defaultdict(asyncio.Lock())
        
    async def request_permit(self, agent_id: str, operation: str) -> bool:
        """返回 True 表示拿到许可，False 表示被占用"""
        key = f"{operation}"
        async with self._permits[key]:
            # 检查是否已被其他 Agent 领取
            if self._permits[key].locked():
                return False
            self._permits[key].acquire()
            return True
    
    def release_permit(self, operation: str):
        key = f"{operation}"
        self._permits[key].release()

# 使用示例
async def worker(agent_id: str, desk: PermitDesk, task: str):
    if await desk.request_permit(agent_id, "write:src/main.py"):
        try:
            await execute_task(task)
        finally:
            desk.release_permit("write:src/main.py")
    else:
        print(f"Agent {agent_id} 等待中，操作被占用")

上下文”腐烂”治理：持久化记忆方案

# memory_persistence.py
import json
from pathlib import Path
from datetime import datetime

class AgentMemory:
    """给 Agent 装上"外置硬盘"，防止上下文腐烂"""
    
    def __init__(self, project_path: str):
        self.memory_file = Path(project_path) / ".agent" / "memory.json"
        self.memory_file.parent.mkdir(exist_ok=True)
        
    def save(self, key: str, value: dict):
        """保存记忆"""
        data = {}
        if self.memory_file.exists():
            data = json.loads(self.memory_file.read_text())
        data[key] = {"value": value, "updated_at": datetime.now().isoformat()}
        self.memory_file.write_text(json.dumps(data, indent=2, ensure_ascii=False))
        
    def load(self, key: str) -> dict | None:
        """加载记忆，防止 Agent 遗忘"""
        if not self.memory_file.exists():
            return None
        data = json.loads(self.memory_file.read_text())
        return data.get(key, {}).get("value")
    
    def summarize_long_term(self) -> str:
        """生成摘要塞入上下文，解决窗口不够用"""
        if not self.memory_file.exists():
            return ""
        data = json.loads(self.memory_file.read_text())
        lines = ["[Agent Long-term Memory]"]
        for k, v in data.items():
            lines.append(f"- {k}: {v['value']} (updated: {v['updated_at']})")
        return "\n".join(lines)

---

常见坑与规避清单

坑	现象	规避方案
Agent 锁竞争	多 Agent 并发时吞吐量归零	工头-工人模式 + 许可单系统；并发数不超过 CPU 核心数
上下文腐烂	任务执行到一半 AI 忘了目标	每 5 步强制写入记忆文件；启动时读取 .agent/memory.json
删除生产数据	AI 执行了 DROP TABLE	sandbox.allowDelete=false；删除操作必须二次确认
Token 账单爆炸	AI 陷入循环调用，费用飞涨	maxSteps 上限 + Token 计数器 + 自动暂停
假进度（Cursor 教训）	Agent 发现代码被占用就去改注释	PR 修改量检查（>50 文件拒绝）；设置最小改动阈值
Harness 过度复杂	花了 3 周搭 Harness，忘了业务本身	”Start Simple. Build to Delete.”：先跑通再迭代，不追求一步到位
工具过多决策混乱	500 个工具让 Agent 选择困难	每个 Agent 只暴露精选子集（Stripe 做法：最多 10-15 个）
幻觉文档	Agent 生成了不存在的 API 文档	文档树必须版本化；AI 不得自创文档路径

---

成本/性能/维护权衡

成本

方案	月均成本（参考）	适用规模
AGENTS.md + 人工 review	$0	个人 / 小团队
OpenClaw 托管	$99/月（基础版）	5-20 人团队
自建微内核 Harness	$500+/月（服务器 + 运维）	中型团队，高定制需求

关键洞察： Vercel 实测：移除 80% 复杂工具后，AI 准确率从随机飙升到 100%，Token 成本暴降 40%。Less is More。

性能

• 任务通过率：优化 Harness 后，同一模型在编程基准上可以从 42% 提升到 78%（Nate B Jones 数据）
• 执行时间：Harness 引入的延迟在 100-500ms 范围内（主要是沙箱校验），对整体任务时间影响可忽略
• 并发能力：未优化时 20 Agent 并发实际吞吐 ≈ 2-3 个；优化后可接近线性扩展

维护

• AGENTS.md：每次 AI 犯错时更新一条规则，属于”持续迭代”型维护
• Blueprint 配置：业务逻辑变更时需要同步更新节点定义，建议用 Git 管理并做 Code Review
• 记忆文件：建议每周做一次”记忆垃圾回收”，清理过时上下文，防止文件膨胀
• Harness 版本：跟随 OpenClaw 等基础平台升级，不需要自己维护底层

---

一周内可执行行动清单

Day 1（30 分钟）

• 在项目根目录创建 AGENTS.md，复制模板并填入项目实际信息
• 跑一次当前工作流，记录 AI 犯过的错，补充到 AGENTS.md 的”行为红线”中

Day 2（1 小时）

• 安装并配置 OpenClaw 沙箱：openclaw init
• 设置 allowDelete: false 和并发上限
• 跑一个典型任务，观察 AI 是否触发沙箱限制

Day 3（2 小时）

• 阅读团队现有 CI/CD 配置，识别可以加拦截门禁的位置
• 创建 .github/workflows/agent-guard.yml（或对应 CI 平台配置）
• 手动测试：故意让 AI 执行一次违规操作，验证拦截生效

Day 4（1.5 小时）

• 引入 Blueprint 分层架构，将任务拆分为确定性节点 + Agentic 节点
• 给每个 Agentic 节点设置 maxSteps 上限
• 验证”许可单”机制：在并发场景下测试文件锁定

Day 5（1 小时）

• 部署 AgentMemory 持久化方案，验证：任务中断后重启，AI 能读取之前状态
• 配置 Token 计数器，设置单任务 Token 上限

Day 6（1 小时）

• 审查所有 AI 修改的 PR：修改文件数 < 50 的要求是否合理，调整阈值
• 运行一周数据：任务通过率、Token 消耗、人工介入次数

Day 7（2 小时，周末可选）

• Review 这周积累的”AI 犯错日志”，更新 AGENTS.md 规则
• 制定下一阶段迭代计划：当前最大瓶颈是哪个？
• 关注 LangChain / OpenClaw 社区的 Harness 更新，保持依赖最新

---

总结一句话： Harness Engineering 的本质不是让 AI 更聪明，而是给它装上一套”运行环境”，让它在生产环境里守规矩、不跑偏、能恢复。从一份 60 行的 AGENTS.md 到生产级的微内核管控平台，是一条渐进路径——第一周就能跑起来，第二周看到效果，第三周持续迭代。