Harness²快速上手教程:免模型密钥5分钟跑通本地Demo
Harness²快速上手教程:免模型密钥5分钟跑通本地Demo
Harness² 是一个开源的「递归 Agent Harness 优化」框架(recursive agent harnessing):它不改动模型权重,而是围绕模型自动迭代改进提示词、工具、记忆、技能与编排组成的「harness」。本教程无需任何模型 API 密钥和云端账号,5 分钟左右即可在本机跑通官方 Demo,直观理解 Harness² 的递归优化流程。
30秒看懂Harness²是什么 🎯
Harness 是模型外围、让它能像 Agent 一样行动的系统:提示词、工具、记忆、技能、编排等;Harnessing 就是优化这套系统的过程。Harness² 把两层递归连接起来:
| 层级 | 做什么 |
|---|---|
| 任务级递归 | 在当前任务上做 Propose–Probe–Compose:提出编辑 → 探测编辑在同一任务上的效果 → 组合出更好的 harness,全程不需要标准答案反馈 |
| Harness 级递归 | 每个任务结束后,把被采用的 harness 和有证据支撑的经验沉淀进持久的 改进 harness(improvement harness),指导后续任务 |
Harness² 向外暴露 8 个可编辑组件(system prompt、guardrails、memory、skills、tool guidance、scripts、subagents、plugins),分别控制上下文构建、工具接口、任务委派和工具循环中的行为:
环境前置条件:只需准备3样东西
- ✅ Linux 环境
- ✅ Python 3.12(安装包同时支持 3.13)
- ✅ uv 包管理器
💡 机器上没有对应版本的 Python 也没关系,
uv venv --python 3.12会自动拉取 CPython 并创建虚拟环境。
首先克隆源码并进入目录:
git clone https://gitcode.com/gh_mirrors/ha/harness2
cd harness2
4步完成安装与快速开始
在仓库根目录依次执行以下 4 条命令即可:
uv venv --python 3.12 .venv
source .venv/bin/activate
uv pip install -e '.[render]'
harness2-demo --output runs/demo --k 2
- 前 3 条:创建 Python 3.12 虚拟环境并安装 Harness²(含
openpyxl等 render 可选依赖); - 最后一条运行本地 Demo:
--output runs/demo指定输出目录,--k 2表示递归预算为 2。
命令入口在 pyproject.toml 中注册,harness2-demo 的实现位于 harness2/cli/demo.py。看到类似下面的输出即表示成功:
Local demo: 2 tasks completed; 0 failed. /path/to/runs/demo/demo.json
Demo到底在跑什么?🔍
Demo 采用确定性编辑器 + 真实 Python 执行,不依赖模型服务、不依赖基准评测裁判,因此完全不需要模型密钥:
- 准备 2 个「对账」任务(ledger-1 / ledger-2),各自带一份含正负金额的
ledger.csv; - 初始 harness 附带求和脚本
scripts/summarize.py,其中有个「只加正数」的小瑕疵——基线运行会漏掉负数(贷方),答案偏大; - 编辑器提出修复(移除正数过滤),候选探针真实执行脚本并产生输出,composer 依据执行结果的行为对比组合出正确的 harness;
- 任务收尾时,反思环节把「求和要保留正负两种符号」这一课沉淀进经验库。
Demo 实现见 harness2/demo.py。结果(任务摘要、采用的 harness、反思笔记等)都写在 runs/demo/ 下,汇总文件为 demo.json。
--k与递归模式参数速查表
Demo 默认同时跑两种模式(--mode both)。后续跑真实基准时需要二选一:
| 参数 | 含义 |
|---|---|
--k 1 |
执行 1 轮 Propose–Probe–Compose |
--k K --mode parallel |
并行探测 K 个通用 + K 个领域候选,再产出 K 个组合。探索得更宽 |
--k K --mode sequential |
连续 K 轮精化,harness 与证据逐轮传递。精化得更深 |
--output <dir> |
Demo 结果输出目录,默认 runs/demo |
并发(--workers)、可复现种子(--seed)、Codex 执行器(--substrate cx)等更多参数见 docs/EXPERIMENTS.md。
下一步:从Demo走向真实基准 🚀
本地 Demo 零成本;跑真实任务需要模型 API(Vertex AI)以及 Node.js 20+、Google Cloud CLI 等依赖。标准流程如下:
harness2-setup lab # 安装基准(lab / jb / wb 三选一)
harness2-check --bench lab # 检查依赖、凭据与配置
harness2 --bench lab --k 1 --mode parallel --max-tasks 1 # 跑一个任务
harness2-judge --bench lab --k 1 --mode parallel # 评分
harness2-report --bench lab --k 1 --mode parallel # 出报告
当前支持三个专业基准:JobBench(专业工作,harness2-setup jb)、LAB(法律工作,lab)、WorkBuddy-Bench(办公/网页/代码,wb)。模型配置、认证方式与 Codex 执行器的完整说明在 docs/SETUP.md;各基准的数据、领域与评分规则见 docs/BENCHMARKS.md。
⚠️ 模型驱动的运行动辄消耗 API 费用。建议先用
--max-tasks限制任务数(注意该参数限制的是每个领域的任务数,不是全局),或加--dry-run先预览任务选择、不发起任何模型调用。
常见问题FAQ
Q:真的不需要模型密钥吗?
A:harness2-demo 用确定性规则替代模型调用,整条流程可离线完成。只有跑真实基准时才需要配置 .env 并执行 gcloud auth application-default login。
Q:结果存在哪里?能续跑吗?
A:默认都在 runs/ 下,按基准与子集组织。重复执行同一命令即可断点续跑;更换模型或任务选择时,请换一个新的 HARNESS2_RUNS_DIR。
Q:Python 版本有要求吗?
A:官方推荐 Python 3.12(3.13 也可),uv venv --python 3.12 会自动处理缺失的运行时。
总结
Harness² 的核心理念是「模型不动,harness 进化」:任务级递归打磨单个任务的执行 harness,Harness 级递归把经验沉淀给下一个任务。按本文 4 条命令即可免模型密钥跑通本地 Demo,亲眼看到两层递归如何协作;之后只需配置模型凭据,就能用 JobBench、LAB、WorkBuddy-Bench 验证它带来的分数提升。


