Harness²快速上手教程:免模型密钥5分钟跑通本地Demo

原创2026-10-19 23:00:162,217 阅读
文章标签:人工智能AI AgentAgent 框架

Harness²快速上手教程:免模型密钥5分钟跑通本地Demo

Harness² 是一个开源的「递归 Agent Harness 优化」框架(recursive agent harnessing):它不改动模型权重,而是围绕模型自动迭代改进提示词、工具、记忆、技能与编排组成的「harness」。本教程无需任何模型 API 密钥和云端账号,5 分钟左右即可在本机跑通官方 Demo,直观理解 Harness² 的递归优化流程。

Harness²递归Agent Harness流水线:任务级递归与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),分别控制上下文构建、工具接口、任务委派和工具循环中的行为:

Harness²八个harness组件结构图:上下文构建、工具接口、编排与中间件

环境前置条件:只需准备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 执行,不依赖模型服务、不依赖基准评测裁判,因此完全不需要模型密钥:

  1. 准备 2 个「对账」任务(ledger-1 / ledger-2),各自带一份含正负金额的 ledger.csv;
  2. 初始 harness 附带求和脚本 scripts/summarize.py,其中有个「只加正数」的小瑕疵——基线运行会漏掉负数(贷方),答案偏大;
  3. 编辑器提出修复(移除正数过滤),候选探针真实执行脚本并产生输出,composer 依据执行结果的行为对比组合出正确的 harness;
  4. 任务收尾时,反思环节把「求和要保留正负两种符号」这一课沉淀进经验库。

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

Harness²并行与串行递归模式对比图:宽探索与深精化

并发(--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 验证它带来的分数提升。

登录后查看全文
harness2