企业官网建设流程全解析

Harness² 是一个即插即用的Agent 框架优化框架，它围绕一个"冻结"的模型，暴露了8 大可编辑组件：System Prompt、Guardrails、Memory、Tool Guidance、Subagents、Skills、Scripts 和 Plugins。本文带你逐一拆解这 8 个组件——它们分别控制上下文构建、工具接口、任务委派与工具循环中的行为，并给出 Harness² 自动优化这些组件的完整路径和上手清单。

什么是 Harness：为什么优化 Agent 框架比换模型更重要

先建立一个概念：

Harness（执行框架）是模型外围的整套系统：提示词、工具、记忆、技能、编排方式等。Harnessing（框架调优）就是优化这套系统的过程。

换句话说，Agent 的表现不只取决于模型本身，更取决于包裹模型的那层"外壳"。Harness² 的核心思路是：模型权重完全不动，只递归地优化外壳。它在两个层级上工作：

• 任务级递归（Task-Level Recursion）：针对当前任务，通过 Propose–Probe–Compose 三步——提出修改、实测修改效果、综合出改进后的 harness——在不依赖标准答案的情况下精化执行框架；
• Harnessing 级递归：把每个任务中被采纳的 harness 和有证据支撑的经验沉淀到"改进型 harness"中，指导后续任务。

这套流程的整体管线如下图所示：

8大可编辑组件总览：一张图看懂分工

Harness² 把模型周围的 8 个组件按运行时角色分成四组，每组职责清晰、成本不同：

组件编号与文件路径的对应关系定义在基线清单 harness.yaml 中，各组件的编辑面规则（校验、路径、frontmatter 要求）集中在 harness2/core/tree.py。

关键概念：常驻组件是"昂贵选项"

理解 8 个组件最重要的一条规则是成本分层：

• 常驻（ALWAYS ON）组件（C1–C4）的每个字都出现在每一次运行的上下文里，与模型自身的输出预算直接竞争。最昂贵的失败模式就是"模型把预算耗在思考上、最终什么都没产出"——往常驻文本里加字只会让这种情况更糟；
• 按需（ON DEMAND）组件（C5–C8）在被调用之前零成本。

因此 Harness² 给出的修改优先级顺序是：Skill → Script → Subagent → Plugin，最后才考虑加常驻文本。这也是所有优化动作的底层逻辑。

逐一拆解：8个组件是什么、怎么写

C1 System Prompt：Agent 的角色说明书

System Prompt 定义 Agent"是谁、按什么流程干活"。在 OpenCode 执行器中它写入systemprompt.md，运行时会以追加模式拼在标准 provider 提示词之上（见 harness.yaml 中的 compose_order）；在 Codex 执行器中，它并入唯一的常驻文件AGENTS.md。

优化要点：角色与步骤要短而可执行；它属于 INV（不变量）维度——描述"怎么干活"，不写领域知识。

C2 Guardrails：常设规则护栏

guardrails.md存放"每次运行都必须遵守"的短规则，比如输出纪律、验证顺序、收尾检查。它是常驻组件，但和 C1 不同：System Prompt 讲流程，Guardrails 讲底线。

优化要点：每条规则应适用于该领域下的几乎所有任务；只有一条被反复证据支持违反时才值得用防御性机制（见 C8）兜底。

C3 Memory：持久领域事实

LongTermMEMORY.md用于存放"对每个任务都成立的短领域事实"，例如文件间的关联关系、字段单位、惯用术语。

优化要点：这里存的是通用事实而非本次任务的答案——任务级结论（"1月1日费率涨到250"）写进来会成为下一个任务的错误锚点。加一条常驻事实，就要删一条旧的来"付账"。

C4 Tool Guidance：工具使用说明

tool_descriptions/tool_guidance.md专门教模型"怎么用好工具集"：常见格式坑、解析技巧、报错时的有界回退。

优化要点：区分"输入错误 / 超时 / 权限 / 输出不可读"四类工具错误，各给一个有界回退和停止条件，绝不写"盲目重试"——这是 C4 最常见的优化方向。

C5 Subagents：有界子任务的委派通道

sub_agents/<name>/AGENT.md定义一个在独立上下文中运行的子 Agent：它看不到主对话，只看到自己的文件与调用说明，最终返回文本。

优化要点：它只适合一种形状的问题——输入大、答案小（例如"读 12 份 PDF，返回一张归一化表格"）。如果子任务输出和输入一样大，委派就是亏本买卖。frontmatter 需要mode: subagent和description:，否则会被静默丢弃。

C6 Skills：按需加载的可复用工作流

skills/<name>/SKILL.md是"认出触发场景才加载"的完整流程：某种文档类型该怎么处理、某种格式该核对什么。frontmatter 需要与目录名一致的name:和description:。

优化要点：技能必须被"点名"才存在——它的目录名要原样出现在 System Prompt 或 Guardrails 的触发句里（如"遇到 XX 场景时，加载<name>技能"）。未被点名的技能是死重。Skill 是新增指令的默认载体，优先于任何常驻文本。

C7 Scripts：确定性辅助脚本

scripts/<name>.py存放确定性操作：反复出现的提取、转换、格式校验，让模型调用脚本而不是每次现编代码。

优化要点：文件名为 snake_case 且必须能通过编译；被 Skill 引用的脚本必须随同一份提案一起交付（Skill 自带辅助脚本放在skills/<skill-name>/scripts/下），引用了不存在的文件会导致整个 harness 在校验时被整体丢弃。

C8 Plugins：工具循环里的"强制执行"

plugin/<name>.ts（Codex 侧对应.codex/hooks.json）是唯一作用于工具循环内部而非提示词内部的组件——文字说明可以"停止阅读"，钩子却不可能被跳过。典型用法：写文件后立即重开校验、在重复报错签名后追加定向提示、给失控的工具设置上限。

优化要点：它不占常驻预算、又不可能被忽略，是把"本该用文字反复重复的知识"低成本承载起来的方式；但只应在轨迹证据显示该失败真实存在时才添加。

Harness² 如何自动优化这8个组件

理解组件之后，Harness² 的优化循环分两级（细节见 docs/EXPERIMENTS.md）：

1. Propose（提案）：harness 编辑器阅读同一任务的多条执行轨迹，从INV 维度（Agent 怎么工作：工具、脚本、子 Agent）和DOM 维度（领域专家知道什么：事实、技能、交付契约）分别提出修改——每一处修改都必须能追溯到轨迹中的具体时刻；
2. Probe（探测）：候选 harness 在同一个任务上真实执行，用行为对比代替标准答案评判效果；
3. Compose（综合）：composer 只保留有证据支持的修改，合并出最终 harness；若无候选明显优于基线，KEEP_BASE（保持不变）也是合法结论。

任务级递归支持两种扩展方式，--k控制递归预算：

• Parallel（并行）：探测 K 个通用 + K 个领域候选，从共享证据中综合出 K 个成品——"探索得更宽"；
• Sequential（串行）：把精化后的 harness 与累积证据带入 K 个连续的 Propose–Probe–Compose 步骤——"精化得更深"。

每完成一个任务，Experience Reflector 会把被采纳的 harness 与经验写回改进型 harness，形成跨任务的经验库（context/library/），下一个任务可直接复用已验证的组件。

快速上手：3步跑通本地 Demo

Harness² 本地 demo 使用确定性编辑器和真实 Python 执行，无需任何模型凭证，是最快的验证路径（完整环境要求见 docs/SETUP.md）：

uv venv --python 3.12 .venv source .venv/bin/activate uv pip install -e '.[render]' harness2-demo --output runs/demo --k 2

跑通 demo 后，即可对真实基准（JobBench / LAB / WorkBuddy-Bench）做模型级优化实验：

harness2-setup lab 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

各基准的数据、领域与评分方式详见 docs/BENCHMARKS.md。

新手避坑清单：3条会"丢掉整个提案"的校验规则

Harness² 在每次 rollout 前都会校验 harness 树，不通过则整体丢弃（校验逻辑见 harness2/core/tree.py）。新手最常踩的三个坑：

1. 技能没有触发句：skills/<name>/SKILL.md的目录名必须在同一次编辑中、原样出现在常驻文本里，否则技能永远不会被加载；
2. 常驻文本里混入模板花括号：这些文件会以 Jinja StrictUndefined 渲染，成对的{{占位符会直接让任务在开工前失败；
3. 脚本引用悬空：被点名的scripts/<file>.py必须真实随附，Skill 的辅助脚本若丢在错误目录会被静默丢弃。

另外两个高频陷阱：往常驻文本里加字却不删别的东西（预算只会被挤占），以及让 harness 改变交付物形状——harness 只改变 Agent怎么工作，绝不能改变任务要求的交付形态。

相关资源

• 组件编辑面与提示词定义：harness2/core/prompts.py
• 组件树校验与 diff：harness2/core/tree.py
• 基线 harness（OpenCode 版）：third_party/jb_runner/harness_baseline_oc/
• 实验与网络限制配置：docs/EXPERIMENTS.md
• 环境安装与执行器配置：docs/SETUP.md
• 三大基准指南：docs/BENCHMARKS.md

掌握这 8 个组件的成本分层与触发规则，你就拥有了 Harness² 的完整优化清单：先问"这个失败属于 INV 还是 DOM"，再选"最便宜的组件"去修，最后让 Propose–Probe–Compose 用证据说话。