需要在固定基座模型下自动搜索并优化任务特定…

适用于用自动化 meta-loop 为 LLM 任务搜索更好的 memory/retrieval/prompt/tool scaffolding，而不是手工调提示和记忆系统。

适用场景

解决思路

1. 按四个概念组织实现：Harness（基座模型周围所有代码：记忆、检索、提示构建、工具使用）、Proposer Agent（提出新 harness 变体的 LLM，如 Claude Code）、Evaluator（在 benchmark 上运行 harness 并返回分数）、Meta-Loop（propose → evaluate → feedback 迭代循环）。
2. 安装：进入 `reference_examples/text_classification` 后运行 `uv sync`；进入 `reference_examples/terminal_bench_2` 后运行 `uv sync`。不要全局 `pip install`，依赖按实验通过 `pyproject.toml` 管理。
3. 文本分类快速开始：`cd reference_examples/text_classification`，运行 `uv run python meta_harness.py --iterations 1` 跑 1 轮；需要更好优化时运行 `uv run python meta_harness.py --iterations 10`（或参考实验中的 `--iterations 20 --dataset ag_news`）。
4. Terminal-Bench 2 快速开始：`cd reference_examples/terminal_bench_2`，先跑 smoke test：`uv run bash scripts/run_eval.sh agents.baseline_kira:AgentHarness full 1 1 -i extract-elf`。通用格式为 `run_eval.sh <agent_module:AgentClass> <split> <num_tasks> <num_workers> [flags]`。
5. 应用到新领域：在你的 AI 编码助手（Claude Code、Cursor 等）中打开 `ONBOARDING.md`，围绕你的领域进行对话，产出 `domain_spec.md`。
6. 在 `domain_spec.md` 中写清：harness 在你的领域控制什么、如何评估 harness 质量（benchmark/指标）、proposer agent 应修改什么、约束与预算考虑。
7. 为新领域准备最小目录 `my_domain/`，包含 `pyproject.toml`、`domain_spec.md`、`meta_harness.py`、`harness.py`、`evaluator.py`、`claude_wrapper.py`。
8. 实现 harness：用 `HarnessConfig` 配置 `model`、`memory_strategy`、`k`、`retrieval_enabled`、`system_prompt`；用 `AgentHarness` 包装基座模型并管理上下文/记忆/工具。
9. 在 `AgentHarness` 中实现 `reset()` 清空 memory；实现 `_build_context(new_input)` 作为核心 harness 逻辑，决定模型看到什么（如 `last_k` 取最近 k 条、`all` 取全部、否则为空），并拼接新用户输入。
10. 在 `AgentHarness.step(user_input)` 中调用 `_build_context`，用配置的 system prompt 和 messages 调用基座模型，把 user/assistant 消息追加到 memory，并返回响应。
11. 实现 evaluator：在 `evaluator.py` 中写 `evaluate_harness(config, dataset) -> float`，实例化 `AgentHarness`，对每个样例先 `reset()`，调用 `step` 得到 prediction，用 `grade` 与 label 比较，返回正确率。
12. 实现任务特定 `grade(prediction, label)`，例如 `label.lower().strip() in prediction.lower()`。
13. 实现 meta 循环 `meta_harness_loop(iterations, train_dataset, val_dataset)`：维护 `history`、`best_score`、`best_config`，循环进行 propose → evaluate → feedback。
14. 每轮循环第 1 步 Propose：调用 `run_proposer(history=history, task_description=..., code_context=Path("harness.py").read_text())` 让 proposer agent 提出新的 harness 变体。
15. 每轮循环第 2 步 Evaluate：用 `parse_proposal(proposal)` 解析新配置，调用 `evaluate_harness(new_config, train_dataset)` 打分；异常时把 `score=0.0` 并打印失败原因。
16. 每轮循环第 3 步 Record：把 `iteration`、`proposal`、`score` 记入 `history`，打印 score；若 `score > best_score`，更新 `best_score` 与 `best_config`。
17. 循环结束后，如果存在 `best_config` 和 `val_dataset`，在留出集上运行 `evaluate_harness(best_config, val_dataset)` 做最终验证并打印最终 val score；返回 `best_config` 和 `history`。
18. 实现 proposer wrapper：在 `claude_wrapper.py` 中写 `run_proposer(history, task_description, code_context)`，先用 `build_proposer_prompt` 构造 prompt，再通过 Anthropic API 调用 Claude（`anthropic.Anthropic()` 使用 `ANTHROPIC_API_KEY`），`messages.create(model="claude-opus-4-5", max_tokens=4096, messages=[...])`，取 `response.content[0].text`。
19. 在 `run_proposer` 中把 prompt 和 response 作为 JSONL 追加写入 `proposer_log.jsonl`，保证可复现，然后返回结果。
20. 在 `build_proposer_prompt` 中包含任务描述、当前 `harness.py` 代码上下文，以及最近 5 轮 `iteration/score/proposal` 历史；要求 proposer 输出 JSON 配置 dict，后接代码改动。
21. 设置环境变量：必需 `export ANTHROPIC_API_KEY=...`；可选 `export PROPOSER_MODEL=claude-opus-4-5`、`export EVALUATOR_MODEL=claude-3-5-sonnet-20241022`。
22. 文本分类参考实验：让 proposer 修改 memory strategy、retrieval settings、prompt templates；evaluator 在留出分类 benchmark 上打分；保存优化后的 config 供复用。
23. Terminal-Bench 2 参考实验：用该流程进化 computer-use/terminal 任务的 agent scaffolding；运行 baseline agent 命令形式为 `uv run bash scripts/run_eval.sh <module:Class> <split> <num_tasks> <num_workers> [task_filter]`；优化产物见 `stanford-iris-lab/meta-harness-tbench2-artifact`。
24. 保存/加载优化配置：用 `json.dump(asdict(best_config), f, indent=2)` 保存到 `best_config.json`；用 `json.load` 读取后通过 `HarnessConfig(**data)` 恢复。
25. 加入 early stopping：设 `PATIENCE=3`、`no_improve=0`；每轮若 `score > best_score + 1e-4` 则更新 best_score 并重置 `no_improve=0`，否则 `no_improve += 1`；当 `no_improve >= PATIENCE` 时打印提前停止并 break。
26. 并行评估：用 `concurrent.futures.ProcessPoolExecutor` 写 `batch_evaluate(configs, dataset, num_workers=4)`，对每个 config 提交 `evaluate_harness`，收集 `f.result()`。
27. 排障：`uv sync` 失败通常是 Python 版本缺失，用 `pyenv` 安装 Python 3.11+；proposer 返回不可解析 JSON 时在 prompt 中加入显式 JSON schema；分数不提升时增加 `--iterations` 并收窄配置空间；API 限流时加 `time.sleep()` 或批处理；找不到 Claude Code 时运行 `npm install -g @anthropic-ai/claude-code`。
28. 引用论文时使用给定 BibTeX：`Meta-Harness: End-to-End Optimization of Model Harnesses`，作者 Yoonho Lee 等，arXiv 2603.28052，URL `https://arxiv.org/abs/2603.28052`。

适用边界 · 注意事项

• 领域任务质量无法转成可比较的数值分数，或没有 benchmark/evaluator 时，Meta-Harness 的 meta-loop 无法有效搜索。
• 不能使用 Anthropic API、Claude Code 或其他 proposer LLM，或不允许自动调用外部模型/产生 API 成本时，不要使用默认实现。
• 搜索空间很小、手写 harness 已足够，或迭代成本和延迟不可接受时，不值得运行自动 meta-harness 优化。