本文给出一套通用项目中的 harness 部署步骤。每一步都说明“为什么这样做”和“解决什么问题”。这套步骤适合从零部署，也适合给已有项目补 harness。

总体原则

部署 harness 时不要一上来追求复杂自动化。先让项目具备四个能力：

1. Agent 能快速理解项目。
2. Agent 能在边界内行动。
3. Agent 能用命令验证结果。
4. 人和下一轮 agent 能复盘本轮发生了什么。

推荐目录

项目根目录/
├── AGENTS.md
├── docs/
│   ├── ARCHITECTURE.md
│   ├── DECISIONS.md
│   └── harness/
│       ├── PROGRESS.md
│       ├── feature-list.json
│       ├── runbook.md
│       ├── eval-plan.md
│       └── runs/
├── scripts/
│   └── harness/
│       ├── init.sh
│       ├── verify.sh
│       ├── verify-static.sh
│       ├── verify-smoke.sh
│       └── run-evals.sh
└── evals/
    └── tasks/

这些文件不是一次都必须建完。可以按下面的阶段逐步部署。

阶段 1：建立入口地图

创建根目录 AGENTS.md，只放高密度导航，不写成百科全书。

建议包含：

# Agent 工作指南

## 项目简介
本项目解决什么问题，核心用户是谁。

## 先读顺序
1. docs/ARCHITECTURE.md
2. docs/harness/PROGRESS.md
3. docs/harness/feature-list.json

## 常用命令
- 初始化: bash scripts/harness/init.sh
- 快速验证: bash scripts/harness/verify-static.sh
- 完整验证: bash scripts/harness/verify.sh

## 硬约束
- 不修改无关文件。
- 不绕过测试。
- 没有验证证据不能声明完成。
- 涉及 secret、生产数据、破坏性命令时必须请求人类确认。

## 完成定义
见 docs/harness/runbook.md#完成定义。

为什么这样做：

• 入口文件短，agent 更愿意读完。
• 它像地图，帮助 agent 找到权威上下文。
• 它把项目知识从人脑搬进仓库。

解决的问题：

• Agent 乱猜启动方式。
• Agent 忽略已有架构。
• 每次会话都要重新解释项目。

阶段 2：把仓库变成记录系统

补齐几类文档：

文件	内容	解决的问题
docs/ARCHITECTURE.md	模块边界、数据流、依赖方向、关键设计选择	防止 agent 乱跨层修改。
docs/DECISIONS.md	重要决策及原因	防止重复讨论和推翻旧决策。
docs/harness/PROGRESS.md	当前任务、已完成、阻塞、下一步	支撑跨会话连续性。
docs/harness/feature-list.json	功能清单、状态、验收标准	控制范围，避免同时半做多个功能。
docs/harness/runbook.md	开工、验证、收尾流程	固定 agent 生命周期。

feature-list.json 可以先很简单：

[
  {
    "id": "feature-001",
    "title": "用户登录",
    "status": "todo",
    "scope": ["后端接口", "前端表单", "基础测试"],
    "acceptance": [
      "登录成功后返回 session",
      "密码错误时返回明确错误",
      "pytest tests/auth -q 通过"
    ],
    "exclusions": ["第三方 OAuth", "管理员后台"]
  }
]

为什么这样做：

• Agent 需要可见的任务状态。
• JSON 这类结构化文件可以被脚本检查。
• 验收标准写在功能旁边，比散落在聊天记录里可靠。

解决的问题：

• 长任务断档。
• Agent 过度扩展范围。
• 下次会话不知道前一次做到了哪里。

阶段 3：固定初始化流程

创建 scripts/harness/init.sh，让每轮 agent 开工前先确认环境健康。

典型检查：

#!/usr/bin/env bash
set -euo pipefail

python --version
python -m pip check
python -m compileall src tests
python tests/verify_all.py --skip 4,6,7

实际项目中可以拆分为：

• 依赖检查
• 环境变量检查
• 数据库迁移检查
• 服务启动检查
• 最小 smoke test

为什么这样做：

• 初始化是独立阶段，不应该混在实现任务里。
• 如果环境本身坏了，agent 应该先修环境或报告阻塞，而不是继续写功能。

解决的问题：

• 依赖缺失导致后续误判。
• Agent 把环境问题当代码问题修。
• 多会话之间环境状态不一致。

阶段 4：建立三层验证门

不要让 agent 只跑一个单测就宣布完成。建议把验证分成三层。

层级	例子	意义
静态层	format、lint、type check、compileall	低成本发现语法和结构问题。
行为层	unit test、integration test、服务启动	证明代码真的能运行。
用户路径层	e2e、CLI smoke、浏览器操作、真实 API smoke	证明关键场景真的可用。

scripts/harness/verify.sh 可以组织这些命令：

#!/usr/bin/env bash
set -euo pipefail

bash scripts/harness/verify-static.sh
bash scripts/harness/verify-smoke.sh
bash scripts/harness/run-evals.sh

错误信息要对 agent 友好：

错误: 完整流程测试没有生成 final_report。
修复提示: 检查 route_orchestrator 的 generate_report 分支，以及 present_preliminary_node 对“没问题”的处理。
证据位置: artifacts/harness/runs/20260605-120102/state.json

为什么这样做：

• Agent 自我判断偏乐观。
• 三层验证把“代码写了”推进到“系统能用”。
• 可执行错误提示可以让 agent 自我修复。

解决的问题：

• 过早宣布完成。
• 集成问题被单测掩盖。
• 失败后 agent 不知道下一步修哪里。

阶段 5：加可观测性

每次 agent 或应用运行都应该产生 run id，并记录到 docs/harness/runs/ 或 artifacts/harness/runs/。

建议 JSONL 事件结构：

{
  "run_id": "20260605-120102",
  "ts": "2026-06-05T12:01:02+08:00",
  "phase": "verification",
  "step": "pytest",
  "status": "failed",
  "summary": "tests/test_graph.py::test_route failed",
  "evidence": "artifacts/harness/runs/20260605-120102/pytest.log"
}

至少记录：

• 任务输入
• 读过的关键文件
• 修改过的文件
• 执行过的命令
• 工具调用失败
• 验证结果
• 最终结论
• 未验证事项

为什么这样做：

• 没有 trace 就没有复盘。
• 长任务跨上下文时，下一轮需要直接接住证据。
• 可观测性让 harness 能持续改进。

解决的问题：

• 失败原因只能靠猜。
• 下次会话重复诊断。
• 无法比较 harness 改动是否有效。

阶段 6：建立 eval

当项目进入稳定开发后，把常见任务写成 eval。

一个 eval task 至少包含：

evals/tasks/
└── task-001-report-disclaimer/
    ├── instruction.md
    ├── expected.md
    └── test.py

评分可以先用确定性检查：

• 输出是否包含风险提示
• 状态图是否到达指定节点
• 关键字段是否非空
• 文件是否按规范生成
• 外部 API 失败时是否降级

然后再引入 LLM-as-judge 或人工评分。

为什么这样做：

• Harness 改动本身也会引入回归。
• eval 让“感觉更好”变成“分数更好”。
• AutoAgent 这类元循环必须依赖可重复评分。

解决的问题：

• 改 prompt 或工具后无法判断是否真变好。
• 修好一个任务，弄坏另一个任务。
• 人类 review 成为唯一瓶颈。

阶段 7：部署安全边界

安全不是阻止 agent 工作，而是把危险操作放进明确审批和隔离里。

建议规则：

• 默认使用 sandbox 或临时环境。
• 生产数据库、真实交易、删除文件、密钥读取必须审批。
• .env 只允许检查变量是否存在，不允许打印值。
• 外部网络调用区分离线、mock、真实 provider 三种模式。
• destructive command 必须在 run ledger 记录原因和证据。

为什么这样做：

• Agent 需要工具能力，但能力越大，边界越重要。
• 权限策略清楚时，人类不用每一步都盯着。

解决的问题：

• 密钥泄漏。
• 误删、误写、误调用生产接口。
• 因权限过宽导致不可控副作用。

阶段 8：让 harness 持续演进

参考 AutoAgent，建立一个简单的实验循环：

1. 固定模型和任务集。
2. 跑未修改 baseline。
3. 根据失败日志归因。
4. 只选择一个通用 harness 改进。
5. 跑完整 eval。
6. 记录到 results.tsv。
7. 如果通过数提升，保留；如果通过数不变但 harness 更简单，保留；否则丢弃。

results.tsv 建议列：

commit  avg_score   passed  cost    status  description

为什么这样做：

• Harness 会像代码一样腐化，需要实验治理。
• 单点 task hack 容易过拟合。
• 可量化结果能避免“改了很多但没变好”。

解决的问题：

• Harness 越改越复杂。
• 没有 baseline，不知道改动效果。
• 只优化当前任务，泛化能力下降。

部署完成检查表

检查项	完成标准
入口地图	根目录有 AGENTS.md，能在 100 到 150 行内指向关键文档和命令。
状态记录	有 progress、feature list 或任务票据，能说明当前任务状态。
初始化	有一条命令能检查基础环境健康。
验证	有静态、行为、用户路径三层验证，至少前两层可本地运行。
可观测性	每次重要运行有日志、run id 和结论。
安全	真实外部服务、secret、破坏性操作有明确边界。
Eval	至少有一组可重复任务，用来比较 harness 改动。
收尾	每次会话结束前更新状态、记录证据和未完成事项。