codex-app-server/docs/harness2.md

Harness² 融合说明

状态：方法层（cloud/harness2.py + cloud/tests/test_harness2.py + examples/harness2_demo.py）与接线层（cloud/harness2_tasks.py + cloud/tests/test_harness2_tasks.py + examples/harness2_run.py） 均已落地，在独立分支 feat-harness2（已 rebase 到生产 #133 的 c757810）上，不碰主线与生产，未合并、未部署。控制台评审页 与 auto_apply 开关仍是下一步，见文末。

上游是什么

Google Research 的 harness2（Apache 2.0，arXiv:2610.14224）：模型权重 不动，只优化模型周围的 harness——系统提示、guardrails、记忆、工具 指引、子代理、技能、脚本、插件。两层递归：

• 任务层：Propose–Probe–Compose。对同一任务提 INV（通用做法）与 DOM （领域做法）两类候选 harness，每个候选真实跑一次（探针），合成器 只把有行为证据支撑的改动合成终版；没有标准答案，靠行为对比。
• 经验层：采纳后反思出一条有证据的经验（cue / lesson / evidence）， 连同被采纳 harness 的完整树存进分领域经验库，供后续任务参考。

上游报告：单步改进在三个专业 benchmark 上最高 +11.5 / +4.5 / +11.8 个点；k=5 并行递归在 WorkBuddy 上到 80.8。这些数字是上游 benchmark 上的，不是本项目的承诺——本项目没有 benchmark，接线后 必须先在自己的重复任务集上跑 base 对照，才能谈收益。

融合映射：照搬 / 改写 / 不引

上游东西	本项目做法
c1–c8 可编辑树（codex surface）	照搬：AGENTS.md（8000 字符上限）、.agents/skills/*/SKILL.md、.agents/skills/*/scripts/*、sub_agents/*/AGENT.md、scripts/*.py、.codex/hooks.json；白名单外一律不读不写；校验含技能 description、触发行、脚本 compile、脚本引用存在、钩子 JSON 与事件名
Propose–Probe–Compose，parallel / sequential	照搬语义，改写实现：run_parallel / run_sequential，提议被拒给一次按反馈修正的机会，再拒回落到当前 harness；探针失败记为死探针，不炸整轮
匿名选择（只比产物）	照搬：终版产物按任务+k+模式定种子洗牌匿名化，选择器看不到 harness 来源；选失败回落到已交付终版；k=1 且终版池只有唯一候选时 trivial 直出（与选择器是否提供无关；2026-10-29 对照纠正了此前“无选择器才 trivial”的误写）
经验库（分领域、整树 + EXPERIENCE.md + INDEX.md）	照搬存储格式，改写生效语义：入库 ≠ 自动生效（见下）
Ledger（会话/探针账本）与成本	改写：成本汇总进 ModeResult.total_cost_usd，由调用方接现有 cloud/cost.py / 租户配额计费；另有 budget_usd 超支门与 max_sessions 会话数门（计探针 + 阶段尝试会话；edit 内 fmt2 纠正与选择/反思会话不计入）：任一超支后不再调用编辑器/探针，剩余阶段回落，且该轮不入库；上游的 R=4k/P=3k 事后强校验未引（本项目结构与上游计数不完全同构，门控代替断言）
run_tag 形状与建任务前预检	对照补齐：validate_run_tag（字符集、首字符不为 -、不以 s 数字段开头）与 preflight_checks（base 目录与 AGENTS.md、source 目录、提示、tag、控制面 health 探针）；CLI --check 只预检不建任务
分角色模型（SOLVER / IMPROVER / JUDGE）	已引（机制）：run_improvement_via_tasks 的 role_models（probe / editor / selector / reflector）+ CLI --model-<角色>；非空值覆盖该角色，缺键回落共享 --model，两者都空走服务端默认——默认行为不变，模型选择权仍在调用方（有价模型产生真实成本）
产物资产（deliverable_files / deliverable_assets / images）与选择 assets note	已引（两层）：①服务端 GET /tasks/{id}/files（任务 worktree 读取，路径安全解析、文本 ≤256KB、列表 ≤200 条；本地任务走本地 worktree，租户 Docker 任务走 tenants/<项目>/work/host-worktrees/<任务id>——worker 按任务建子目录，只 serves 任务级子目录、绝不 serves 共享的 /app/work 本身；cloud/跨机任务 409）；②探针回复里的 DELIVERABLE FILE 块（所有执行器可用，端点结果优先、坏块丢弃不炸轮次）。产物进 Rollout.deliverable_files，并写入选择/编辑/反思上下文的 deliverables/<label>/files/。images（二进制产物）未引：端点只读 UTF-8 文本
sweep 层（多任务批量、跨任务 library restore、dead 隔离、report 汇总）	已引：run_sweep + CLI examples/harness2_sweep.py（共享 library_root、单轮失败隔离、sweep-report.json 汇总；manifest 预检不过不建任务，默认只打印计划，--yes 才真跑）
提示词	改写短版（中文项目语境下的英文任务提示，结构同上游，措辞自写），不抄上游长提示
Benchmark 适配器（JobBench / LAB / WorkBuddy）、评分器、rubric	不引。任务就是一个普通 codex 任务，delivered 由 adapter 定义（如产物存在且非空）
Proposer 通道（Claude CLI / OpenCode）、Vertex 配置	不引。编辑器/选择器/反思器是调用方注入的协议，真实接线时是 codex 任务（见下）
上游执行默认：网络不受限、Codex sandbox 禁用	明确不引，见安全一节
上游 ThreadPool 并行探针	不引。核心循环串行跑探针；并行是调用方在 adapter 层把每个探针发成独立 codex 任务来实现，避免核心循环抢同一个 Worker/DB

安全偏差（刻意与上游不同，勿“纠回”上游）

1. 执行面与本模块解耦。 cloud/harness2.py 不跑任何命令、不拼 任何 codex exec 参数。真实 adapter 必须走 Worker 已有的 Docker / gVisor 沙箱、租户隔离与 egress 白名单，绝不加 --dangerously-bypass-approvals-and-sandbox。上游 README 明写其 Codex 执行是 sandbox 禁用、网络不受限——那是 benchmark 实验的 默认，不是生产服务的默认。
2. 采纳 ≠ 自动铺开。 多租户下，一个编辑器写出的 AGENTS.md 若 自动改写别人的任务，是质量与越权双重风险。所以 improve_task 的 auto_apply 默认关：库只是“待评审的经验”，提议器可读， 但任何任务的 base 永远是项目自己的 base harness；只有项目显式 开启 auto_apply 后，调用方才在下一轮的 base_harness() 里取库 中最新采纳树。这个开关的服务端接线（项目设置 + 控制台评审页） 是下一步。
3. 预算是硬门。 k 硬上限 3；parallel 一轮最多 10 次执行 （1 base + 2k 候选 + k 终版），sequential 同样最多 10 次。 budget_usd 超支后不再花钱，且该轮不入库——超支轮次的“经验” 是不完整证据，不配进库。
4. 编辑器写出的东西先校验后采纳。 校验失败的提议给一次修正 机会，再失败就回落，绝不把坏树（空 AGENTS.md、坏钩子、不编译 的脚本、无触发行的技能）铺到探针里。

接口（调用方视角）

from cloud.harness2 import improve_task, Library
from pathlib import Path

result = improve_task(adapter, editor,
                      selector=selector, reflector=reflector,
                      work_dir=Path("runs/h2-task-1"), k=1, mode="parallel",
                      library=Library(Path("runs/library"), domain="accounting"),
                      budget_usd=5.0)
result.to_dict()  # 阶段、回落、选择、经验、入库位置、总成本

• TaskAdapter：task_id / domain / prompt 属性；base_harness()； execute(label, harness) -> Rollout（失败也返回 Rollout，不抛）； 可选 validate_tree() 做项目特有校验。
• Editor.edit(mission, context_dir, label) -> EditResult：读 context_dir 下的 task.md / rollouts / deliverables / harness / library，改 context/harness/，返回改完的树（tree=None 时 框架自动从 context/harness/ 读回——真实 codex 任务接线就用这条 路）；notes 是编辑器最终消息里 <notes> 块的解析结果，由调用 方在构造 EditResult 时填好。
• Selector.select(mission, context_dir) -> (id, why, cost)：读 context_dir/candidates/<id>.md（匿名产物），返回 choice id。
• Reflector.reflect(mission, context_dir) -> dict：返回含 cue / lesson / evidence（可含 confidence / edits）的经验，三项不全 返回 {} 即表示无可入库经验。

证据上下文由 build_context 生成：证据以文件形式给模型，prompt 只写指针，不把轨迹截断后塞进 prompt（截断过的轨迹会编造缺陷， 这是上游明确反对的做法）。

接线层（已落地，cloud/harness2_tasks.py）

只用控制面已有的 API，不新增任何服务端端点：POST /uploads → POST /tasks（upload_id 绑定 + idempotency_key 幂等）→ GET /tasks/{id} 轮询终态 → GET /tasks/{id}/trace 读轨迹 → GET /tasks/{id}/cost 读 usd_micros → 超时 POST /tasks/{id}/cancel。 认证是 X-API-Key 请求头；密钥只由调用方持有，接线层不读、不存、 不打印密钥。

• 探针：bundle = 源文件 + harness 树，Worker 派发时经 host.py --seed-dir 拷进 worktree，harness 文件覆盖仓库同名文件 ——同一任务在不同 harness 下跑。prompt = 原任务 prompt + 交付脚注。
• 结果读取：控制面返回的 result_text 是一层 JSON 信封 （task / thread_id / cwd / status / text / usage），agent 的最终 回复在 text 字段里。run_task 是四路共用的 choke point， 在此用 unwrap_result_text 拆信封；直接拿信封当回复会让 行首锚定的文件块解析永远看不见块（2026-10-29 三轮真实轮次 的真根因：编辑明明发了块，却被判成无改动/格式错误）。
• 编辑：bundle = context/ 前缀的证据树；agent 在 worktree 的 context/harness/ 里改文件，最终回复用文件块（=== HARNESS FILE: 路径 === … === END HARNESS FILE ===）只输出改动文件，没改的 省略即继承，外加 <notes> 块；接线层解析后落到 fallback 树上再 走核心校验。格式契约（2026-10-29 两轮真实轮次后收紧）：只在 <notes> 里声称改动、却不发文件块，不再算“无需改动”——无改动 必须用显式 <no-change>理由</no-change> 标记；文件块与标记同 时出现、路径越界、块未闭合都算格式错误，接线层用独立幂等键 带反馈重试一次（.fmt2），两次都错才如实回落，绝不静默采纳。
• 选择 / 反思：同款 bundle + 最终回复解析（```choice + <why>；<experience> + <edits>），不读 worktree 文件。
• 幂等：idempotency_key = h2-{run_tag}-{role}-{label}，同一 run_tag 重跑复用已有任务（断点续跑）；想从头重跑必须换 run_tag， 换了 harness 内容却沿用旧 run_tag 时旧结果会被复用、白跑一轮。
• 成本与审批：接线层不拼任何 codex 参数、不改任务默认值； model / effort / approval / environment_id / executor 全由调用方 透传，缺省走 Worker 默认值；任务走与普通任务完全相同的执行器、 沙箱、租户隔离、配额门与审计；单任务超时默认 3600 秒，超时先 取消再记失败/回落；长任务走 #133 的自动续跑。
• 接线层最大的适用边界：探针交付物 = 最终回复文本。文件型 产物（代码 diff、报告文件）目前只能靠 agent 在最终回复里复述/ 摘要：worktree 快照 API 只给 diff 截断（20000 字）与未跟踪文件 列表、不给完整文件内容，跨主机还读不到。文件产物评审需要新增 文件读取端点，另行评审，不在本层假装已解决。

用真实任务跑一轮（先 dry-run 看计划，确认后加 --yes）：

export CODEX_API_KEY='...'   # 密钥只走环境变量，不接受命令行参数
python3 examples/harness2_run.py --base-url http://127.0.0.1:8765 \
    --project-id <测试项目> --prompt-file task.md \
    --base-harness-dir ./my-base-harness --source-dir ./task-source \
    --mode parallel --k 1 --budget 5 --output runs/h2-real-1
# 计划无误后，加 --yes 重跑；同一 run_tag 可断点续跑

仍未做的事（需另行评审）

1. 人工关口：采纳的 harness 先在控制台以“待评审经验”展示， 项目负责人点“采纳为 base”后才影响后续任务；auto_apply 开关 默认关，开启需项目负责人显式操作并记审计。目前 run_improvement_via_tasks 的 auto_apply 恒为 False，库只是 待评审经验。
2. 文件产物评审：新增读取已终态任务 worktree 文件的端点（权限、 跨主机、大小上限都要定），或让探针任务把产物文件内容写进最终 回复的约定成为正式契约——前者是服务端改动，后者是提示词契约， 各有利弊，需评审。
3. 效果验证：先在 3–5 个重复性任务（如固定格式的对账、周报 生成）上跑 base 对照：同一任务、同一模型，base 产物 vs 改进后 产物由人工或固定检查脚本判定，记录执行次数与成本；没有对照 就不宣称收益。

演示与测试（无模型、无网络）

python3 examples/harness2_demo.py --mode parallel    # 应输出 Total: 85.15 并入库
python3 examples/harness2_demo.py --mode sequential
python3 -m unittest discover -s cloud/tests -p "test_harness2*.py" -v  # 25 项

接线层单测用进程内假客户端（探针真跑 bundle 里的脚本、编辑按 文件块格式回改动）跑通完整轮次，并对本地假服务端实测了 HTTP 客户端（建任务、轮询、成本、轨迹、密钥头、multipart 与服务端 解析器往返）。真实任务链路尚未实测：第一次真实运行请用测试项目， 并先跑 examples/harness2_run.py 不带 --yes 的计划模式。

演示账本 100.25 / -20.10 / 5.00：base 脚本只加正数得 105.25， 改进后带符号和为 85.15；演示用的编辑器/选择器/反思器是确定性的， 只为证明循环本身，真实收益必须用第 4 步的对照来量。