Harness² 项目架构

1. 项目目的：金字塔顶端

Harness² 是一个面向开放世界专业任务的递归 Agent Harness 优化框架。

它不训练或修改模型权重，而是持续优化模型运行时周边的 Harness：系统提示词、约束、长期记忆、工具指导、子 Agent、Skills、脚本和插件/Hook。目标是让 Agent 在完成一个任务后，根据实际执行证据改进当前任务的执行方式，并将可迁移经验沉淀给同领域的后续任务。

目标：提升 Agent 在陌生专业任务中的执行质量
  └── 方法：递归优化 Agent Harness，而非训练模型权重
      ├── 任务级递归：Propose -> Probe -> Compose
      └── 任务间递归：Adopt -> Reflect -> Library

项目定位是研究型、本地 CLI 实验框架，不是业务 Web 系统：没有项目内前端页面、业务数据库或长期运行的服务集群。

2. 总体架构

分层边界

harness2/core/spec.py 中的 BenchmarkAdapter 和 SubstrateLike 协议是核心边界：新增 benchmark 或运行时应通过实现协议接入，而不是修改递归算法。

3. 功能分类

4. Harness 的可编辑面

项目优化的是 Agent Harness 文件树，而不是模型参数。

可编辑面由 harness2/substrate/opencode.py 的 OPENCODE_SURFACE 和 harness2/substrate/codex.py 的 CODEX_SURFACE 定义，通用校验由 harness2/core/tree.py 的 validate() 完成。

5. 递归核心：代码定位

5.1 递归入口和调度

5.2 任务级递归：Propose -> Probe -> Compose

核心实现全部在 harness2/core/recursion.py。

5.3 并行递归的精确流程

harness2/core/recursion.py::run_parallel()：

基础 Harness 的 k 次 rollout
  -> 并发生成 k 个 INV（通用）候选
  -> 并发生成 k 个 DOM（领域）候选
  -> 并发执行全部 2k 个候选
  -> 基于候选 Harness 与其执行证据，生成 k 个 AGG（组合）候选
  -> 并发执行 k 个 AGG 候选
  -> AGG1..AGGk 作为最终选择池

其中：

• INV：不依赖特定领域的通用行为改动。
• DOM：针对当前领域的行为改动。
• AGG：根据前两类候选的实际执行差异组合出的最终 Harness。

5.4 串行递归的精确流程

harness2/core/recursion.py::run_sequential()：

第 1 轮：base -> inv1 + dom1 -> c1
第 2 轮：c1   -> inv2 + dom2 -> c2
...
第 k 轮：c(k-1) -> invk + domk -> ck

c1..ck 是可供选择的最终 checkpoint。

两种模式均从 k 次基础 Harness rollout 开始。每种模式每任务预算为：

R = 4k 次 executor rollout
P = 3k 次 improver session

预算账本在 harness2/core/ledger.py，其一致性校验由 run_parallel() 和 run_sequential() 末尾的 ledger.assert_identity() 执行。

6. 递归中的证据、选择和经验闭环

7. Benchmark 和 Runtime 的交互

Benchmark Adapter

每个 benchmark 实现 BenchmarkAdapter 协议，向核心算法提供：

tasks()                发现任务
domain_of()            获取任务所属领域
task_prompt()          提供去除评分标准后的任务描述
task_files()           提供任务原始资料
execute()              执行基础或优化后的 Harness
trajectory()           读取执行轨迹
deliverable_text()     读取产物文本
base_harness()         提供原始 Harness
validate_tree()        执行 benchmark 专属校验
score()                对最终选择结果评分

Substrate

Adapter 负责“做什么任务、怎么真正执行”，Substrate 负责“怎么把 Harness 变成该 Agent Runtime 能加载的形式”。

8. 评分、报告和结果保存

harness2
  -> 生成/选择 Harness 和 rollout
  -> 写 summary.json、selection.json、reflection、Harness Tree

harness2-judge
  -> core/judge.py::judge_selections()
  -> 仅评分已选择的 rollout
  -> 写 judged.json

harness2-report
  -> core/report.py::summarise()
  -> core/report.py::render()
  -> 输出指标、选择来源、回退和未评分告警

评测结果不会反馈给 Propose、Probe、Compose 或选择过程。core/judge.py 明确要求评分失败返回未评分，而不是零分；报告时未评分数据不进入分母。

主要结果目录：

runs/
  <benchmark>/
    adapt/<namespace>/<task>/
      summary.json
      harnesses/
      context/
      selection/
      reflection/
    library/<benchmark>/k<k>-<runtime>/<mode>/<domain>/
      INDEX.md
      harnesses/<task>/harness/
      harnesses/<task>/EXPERIENCE.md
    _audit/
    _sweeps/
    judged.json

9. 安全、可复现与运行约束

安全边界

• core/context.py::assert_no_leak_paths() 阻止 benchmark 指定的答案文件进入改进模型上下文。
• core/context.py::assert_no_grader_verdicts() 阻止 judge verdict 或通过率等结果进入模型上下文。
• core/tree.py 会在 Harness 被执行和保存前再次校验，避免评分信息随 Harness 被传递到后续任务。

可复现性

• core/schedule.py::stream_order() 按 seed 生成稳定的领域和任务顺序。
• cli/run_sweep.py::_check_identity() 将模型、任务集、seed、端点等写入 config.json，阻止不兼容实验复用同一结果目录。
• core/schedule.py::_resume() 校验已选 Harness 指纹、运行目录和产物，确保恢复运行不是盲目复用缓存。
• install.py 固定上游 commit、打 patch、复制 runner overlay，减少外部依赖漂移。

外部风险

执行器默认网络不受限，公开 benchmark 的 rubric 可能可从 GitHub 或 Hugging Face 获取。正式评测需要在网络层限制执行器访问这些站点；项目本身不会自动做网络隔离。

10. 一句话总结

Harness² 是一个以 Benchmark Adapter + Agent Runtime Substrate + Recursive Harness Optimizer 为核心的实验框架：它用真实执行行为验证 Harness 改动，通过匿名选择采用更优结果，再将经过证据支持的经验保存给同领域后续任务，从而让 Agent 的运行外壳持续演进。

11. Agent 底座：安装、接入与运行

11.1 什么是底座

在 Harness² 中，Agent Runtime 通过 Substrate（底座）接入。底座不是模型供应商配置；它负责让 Harness² 能将可优化 Harness 安装到实际 Agent Runtime，并发起执行、读取轨迹和进行运行前检查。

当前原生底座：

DSH、OpenCode2 等其他 Runtime 当前不是已注册底座。若其文件格式或启动协议与 OpenCode/Codex 不完全兼容，应新增独立 Substrate，而不是直接复制配置文件。

11.2 第一步：安装并配置 Runtime

先让 Runtime 能在本机、容器或远程服务中被调用；这一步本身不等于 Harness² 已能驱动它。当前项目将安装逻辑集中在 harness2-setup，其入口为 harness2/cli/setup.py，具体安装动作位于 harness2/install.py。

OpenCode 的实际安装和运行

uv venv --python 3.12 .venv
source .venv/bin/activate
uv pip install -e '.[render]'

harness2-setup lab
harness2-check --bench lab
harness2 --bench lab --substrate oc --k 1 --mode parallel

当前项目从源码通过 Bun 启动 OpenCode，并非依赖全局安装的 OpenCode CLI。若“OpenCode2”指不同主版本或不同产品，必须验证其 Harness 文件格式、插件机制、启动命令和日志格式与当前 OpenCode 是否兼容。

Codex 的实际安装和运行

Codex 除了安装 CLI，还需要一个兼容 Responses API 的模型端点。项目可通过 harness2-bridge 用 LiteLLM 将 Vertex 模型暴露为该端点。

uv pip install -e '.[render,bridge]'

# 单独终端启动；将输出的 HARNESS2_CODEX_* 配置写入 .env。
harness2-bridge

harness2-setup lab --substrate cx
harness2-check --bench lab --substrate cx
harness2 --bench lab --substrate cx --k 1 --mode parallel

harness2-bridge 是模型服务 Bridge，不是新的 Agent Runtime。它只解决“Codex 使用哪个模型端点”的问题。

DSH 的预期安装体验

DSH 目前未被实现为底座。完成接入后，期望用户使用统一命令：

# 以下是接入 DSH 后的目标命令，不是当前仓库可执行命令。
harness2-setup lab --substrate dsh
harness2-check --bench lab --substrate dsh
harness2 --bench lab --substrate dsh --k 1 --mode parallel

因此，DSH 若需在本机或容器中运行，应在 harness2/install.py 增加类似 install.dsh() 的安装函数，并由 harness2/cli/setup.py 在 --substrate dsh 时调用；若 DSH 是远程服务，则实现配置和预检即可。

11.3 第二步：接入一个新底座的协议

新 Runtime 应实现 harness2/substrate/base.py::Substrate：

class Substrate(Protocol):
    name: str

    def surface(self) -> SurfaceSpec: ...
    def materialise(self, tree_dir, spec, ctx) -> Install: ...
    def execute(self, task_ref, install, run_ids, timeout) -> list[Path]: ...
    def read_trajectory(self, stream_path, *, obs_trunc, max_chars, args_trunc=400) -> str: ...
    def preflight(self) -> None: ...

建议的新文件为 harness2/substrate/dsh.py，参考 opencode.py 和 codex.py。若 DSH 支持 Codex 的 AGENTS.md、Skills、Hook 和 JSONL 轨迹格式，可复用部分 Codex 逻辑；但只有验证其加载语义一致后才能复用。

11.4 第三步：底座实际运行流程

11.5 第四步：Runtime 正确加载不等于 Agent 一定使用

“Runtime 正确加载”指 Codex、OpenCode 等执行器确实在预期目录、预期启动参数和权限配置下加载了 Harness 文件。例如，Codex 必须以包含 AGENTS.md 的工作目录启动；若启动目录错误，或 Hook 未被 Runtime 信任，文件存在也不会生效。

但正确加载只代表组件可用，不代表模型一定主动使用。应区分三层：

core/tree.py::autotrigger() 会在新增 Skill 未被常驻文本提及时，尝试在 OpenCode 的 guardrails.md 或 Codex 的 AGENTS.md 自动补充触发语句。core/tree.py::validate() 会拒绝没有被常驻文本提及的 Skill，避免出现模型无法发现的“死组件”。

11.6 插件、工具和模型服务的不同接入方式

项目中的 harness2-bridge 属于模型服务 Bridge，而不是新 Agent Runtime：它使用 LiteLLM 将 Vertex 模型暴露为 Codex 所需的 Responses API。WorkBuddy 的 Docker/Harbor 接入属于 benchmark 执行基础设施，也不是新底座。

11.7 如何选择接入方案

对“建议性行为”可使用系统提示和 Skill；对“绝不能跳过”的行为，如敏感信息扫描、发布前校验、权限检查或工具调用阻断，应使用 Hook、Plugin、服务端策略或执行 wrapper，不能只依赖模型遵循提示词。

12. Hook 生命周期：最后的强制控制层

Hook 是 Agent Runtime 在固定事件发生时自动调用的程序或命令。它不是模型“想起来才执行”的提示词，也不是一个需要模型主动加载的 Skill。

12.1 Hook 在什么时候运行

当前 Codex 底座在 harness2/substrate/codex.py::CODEX_SURFACE 中声明可配置的生命周期事件：

12.2 Hook 与提示词、Skill 的区别

例如，“生成报告前检查敏感信息”若仅写入系统提示，模型可能忘记执行；若在 Stop Hook 中执行扫描脚本，扫描失败可阻断结束并将原因反馈给模型，直到其修复产物。

12.3 Hook 覆盖范围

Hook 只在它监听的事件发生时执行。若 Hook 只监听 PreToolUse 且只匹配 Bash：

模型调用 Bash 工具  -> Hook 执行
模型调用 Write 工具 -> Hook 不执行
模型只输出文本     -> Hook 不执行

因此应根据约束目标选择事件：

若 DSH 提供原生生命周期事件，应将其映射到上述 Hook 概念并放入 DSH 的可编辑 Harness Surface；若 DSH 没有 Hook/Plugin，则可用 CLI/SDK wrapper、容器 sidecar 或最终产物校验模拟部分强制控制，但无法获得相同的工具循环覆盖度。

13. 模型服务 Bridge：协议桥接开发层

Bridge 是模型服务的 HTTP 协议适配器，不是手机通信，也不是 Agent Runtime 底座。它解决的是“某个 Agent Runtime 如何调用模型”的问题；Substrate 解决的是“Harness² 如何安装、运行和观测该 Agent Runtime”的问题。

13.1 当前项目中的 Bridge

harness2-bridge 的实现位于 harness2/cli/bridge.py。它启动本地 LiteLLM HTTP 服务，使 Codex 可通过 OpenAI Responses API 访问 Vertex AI 模型。

Codex CLI
  -> HTTP Responses API
  -> harness2-bridge（LiteLLM）
  -> Vertex AI API
  -> Gemini 或其他可用 Vertex 模型

它会：

1. 读取 GOOGLE_CLOUD_PROJECT 和 Google Application Default Credentials。
2. 生成并保存本地服务端口和访问密钥。
3. 写入 LiteLLM 的模型路由配置。
4. 输出 HARNESS2_CODEX_BASE_URL、HARNESS2_CODEX_API_KEY 和 HARNESS2_CODEX_MODEL，供 Codex 配置使用。
5. 对 WorkBuddy 容器场景，支持监听 0.0.0.0，并提供容器访问宿主机的 URL。

该 Bridge 是 HTTP 请求/响应服务，不使用 WebSocket 长连接。

13.2 Bridge、Substrate 与 Harness 的边界

即使 DSH 完全复用现有 Bridge，仍需要 DSH 的 Substrate；反之，DSH 已有可用模型端点，也不代表它已经接入 Harness²。

13.3 DSH 对现有 Bridge 的复用判断

13.4 开发 DSH Bridge 的工作清单

若 DSH 不能直接复用现有 Bridge，建议保持 harness2-bridge 的职责边界，新增独立的 DSH bridge 配置或启动入口，而不要将 DSH 的 Runtime 执行逻辑混入 Bridge。

13.5 DSH 的完整操作链路

1. harness2-setup ... --substrate dsh
   -> 安装或校验 DSH Runtime
   -> 安装或配置 DSH 所需的 Bridge

2. harness2-check ... --substrate dsh
   -> 检查 DSH CLI/SDK、Harness 加载、Bridge 连通性、认证和模型路由

3. harness2 ... --substrate dsh
   -> DshSubstrate 将 Harness Tree 物化为 DSH 配置
   -> benchmark launcher 启动 DSH
   -> DSH 通过 Bridge 或原生 API 调用模型
   -> Harness² 读取 DSH 轨迹、产物并进入递归优化流程