harnessgym

<p align="center"> <img src="https://raw.githubusercontent.com/patrick-toulme/harnessgym/main/docs/assets/harnessgym.png" alt="HarnessGym logo" width="520"> </p> # HarnessGym 📖 **文档：[harnessgym.com](https://harnessgym.com)** — 文档由 `docs/` 目录下的 MkDocs Material 构建，并在每次推送到 `main` 分支时部署。 HarnessGym 是一个用于迭代式智能体强化改进的开源框架。它在一个困难的任务上运行一个编码智能体，实时反思哪些可重复使用的强化神器（harness artifact）可能帮助最大，然后在 `.harnessgym/` 目录下构建该神器，并启动下一个迭代，在一个全新的会话中，带有累计的注册表上下文。 该软件包是针对开发人员评估智能体工作流的 alpha 软件。核心软件包没有第三方运行时依赖；运行器后端使用您选择的智能体 CLI 调用外部命令。支持 Codex 和 Claude Code，确定性 `fake` 运行器可离线进行烟雾测试和演示。 ## 安装 ```bash python -m pip install harnessgym harnessgym --help ``` 对于带有测试和捆绑示例的源代码 checkout： ```bash git clone https://github.com/patrick-toulme/harnessgym.git cd harnessgym python -m pip install -e ".[dev]" python -m pytest ``` 运行器先决条件： - `--runner exec` 使用 `codex` CLI，可通过 `--codex-bin` 配置。 - `--runner claude` 使用 `claude` CLI，可通过 `--claude-bin` 配置。 - `--runner fake` 是确定性的，不需要智能体账户。 - 部分示例需要额外的本地工具，如 NumPy、C/C++ 编译器、PyTorch、Triton 或访问远程 GPU。 ## 快速入门 在现有工作区中创建或选择一个任务文件，然后针对该工作区运行 HarnessGym： ```bash harnessgym run \ --task task.md \ --workspace . \ --iterations 3 \ --attempt-timeout 45m \ --build-timeout 20m \ --runner exec ``` 对于离线烟雾测试，使用捆绑的数值调试演示： ```bash harnessgym run \ --task examples/numerical_debug_task/task.md \ --workspace examples/numerical_debug_task \ --iterations 2 \ --attempt-timeout 10s \ --build-timeout 10s \ --runner fake ``` ## CLI 优化任务可以根据目标分数停止，而不仅仅是 `status: solved`： ```bash harnessgym run \ --task task.md \ --workspace . \ --iterations 2 \ --attempt-timeout 5m \ --build-timeout 5m \ --runner exec \ --stop-score 2.0 \ --score-key best_ms ``` 对于时间盒优化任务，使用尝试后评分，以便 HarnessGym 在每次尝试后独立验证工作区，即使运行器进程在更新 `result.json` 之前被杀死： ```bash harnessgym run \ --task task.md \ --workspace . \ --iterations 5 \ --attempt-timeout 5m \ --runner exec \ --optimization-mode \ --score-key best_cycles \ --stop-score 1 \ --post-attempt-command "python3 benchmark.py --json --mode final" \ --post-attempt-score-key best_cycles ``` 在优化模式下，`summary.json` 记录基准分数、最佳分数、相对改进/减少和每次迭代的强化使用情况。这样可以避免在尝试超时后修改工作区但在写入最终结果 JSON 之前丢失真正的改进。默认情况下，HarnessGym 还会检查最佳独立评分任务工作区并在运行结束后恢复它，同时保留 `.harnessgym`、`.codex`、`.agents` 和 `.claude` 激活状态完整。使用 `--no-restore-best` 如果您想检查最终尝试状态。 使用 `--attempt-timeouts 5m,8m` 进行每次迭代的尝试预算。使用 `--build-after-solve` 当您希望已解决的运行仍然反映并构建可重复使用的强化神器以供后续重放实验。 HarnessGym 默认 `--harness-depth deep`，这有助于反射/构建面向能力构建的强化神器，而不是轻量级笔记：多工具 MCP 服务器，具有可执行检查和自动化，如编译器/IR 分析、汇编信号、基准测试历史、变体扫描、跟踪/布局工具、回滚安全实验排名和综合自测试。使用 `--harness-depth standard` 获取较小、更集中的神器。 默认情况下，生成的神器在推广到下一个新鲜尝试之前会进行资格认证。每次构建阶段后，HarnessGym 会将预运行任务工作区复制到 `.harnessgym/runs/<run_id>/qualification/`，仅复制可重复使用的 `.harnessgym/` 神器包，激活生成的技能/MCP，并在那里运行 MCP 自测试。如果资格认证失败，HarnessGym 会将确切的失败报告发送回同一个运行器会话，并允许 `--artifact-repair-attempts` 修复构建，默认为 `1`。仍然失败的神器在 `registry.json` 中标记为隔离，隐藏在未来的尝试提示和激活中，并保留修复证据。使用 `--no-qualify-artifacts` 仅在调试框架本身时。 任务状态有两种模式： ```bash # 跨迭代的复合任务进度。这是默认模式。 harnessgym run --task task.md --workspace . --task-state continue # 在每次新迭代之前恢复任务文件，同时保留累计的 .harnessgym 神器。 harnessgym run --task task.md --workspace . --task-state reset ``` 使用 `continue` 当您希望智能体继续改进同一个工作树时。使用 `reset` 当您希望每个新鲜会话都面对原始任务，仅带有生成的强化神器。 可以使用 Claude Code 代替 Codex： ```bash harnessgym run \ --task task.md \ --workspace . \ --iterations 3 \ --attempt-timeout 45m \ --build-timeout 20m \ --runner claude ``` 有用的 Claude 特定标志： - `--claude-bin`：Claude Code 可执行文件的路径，默认为 `claude`。 - `--claude-model`：可选模型别名或完整模型名称，如 `sonnet` 或 `opus`。 - `--claude-permission-mode`：默认为 `bypassPermissions`，适用于自主 HarnessGym 运行。 - `--claude-max-budget-usd`：Claude Code 打印模式的每阶段可选支出上限。 - `--claude-extra-arg`：Claude Code CLI 标志的可重复使用出口。 也支持内联任务文本： ```bash harnessgym run \ --task-text "修复失败的测试并验证它们。" \ --workspace . \ --iterations 2 ``` Replay A/B 比较支持 `compare`。这会为每个试验复制一个干净的工作区模板，仅运行尝试重放，并带有或没有生成的 `.harnessgym/` 神器包，可选运行最终的 JSON 基准测试命令，并写入 `compare_report.json`。失败的后命令被记录为无效的最坏情况结果，带有 `post_valid: false`、`post_invalid_reason` 和汇总中的无效计数。强化试验还要求至少有一个生成的 MCP 工具来激活，默认情况下；否则试验被标记为无效比较，以便损坏的神器包不会被误认为是强化胜利。使用 `--no-require-active-harness` 进行烟雾测试，故意仅复制文档/脚本。 HarnessGym 记录生成的 MCP `tools/call` 遥测到 `.harnessgym/mcp_calls.jsonl`，并在 `compare_report.json` 中显示调用计数、调用工具名称和紧凑样本。Claude 通过其 MCP 桥接器记录此信息。Codex 通过其生成的 MCP 配置文件使用的 Content-Length MCP 遥测代理和工作区本地助手 `python3 .harnessgym/runtime/mcp_call.py --server <name> --tool <tool> --arguments '<json-object>'` 记录此信息。使用 `--require-harness-tool-use` 当您希望强化试验仅在智能体实际调用至少一个生成的 MCP 工具时才计入。 ```bash harnessgym compare \ --workspace-template examples/c_flash_attention_optimization_task \ --task task.md \ --artifact-source tmp/c_flash_attention_5iter_real/.harnessgym \ --output-dir tmp/c_flash_attention_compare \ --trials 2 \ --attempt-timeout 5m \ --runner exec \ --post-command "python3 benchmark.py --json --mode final" \ --post-score-key best_cycles ``` 存储库中还包含一个已提交的张量布局强化神器包，由先前合格的运行生成。它位于工作区模板之外，因此普通试验不会看到强化神器： ```bash harnessgym compare \ --workspace-template examples/tensor_layout_pipeline_task \ --task task.md \ --artifact-source examples/tensor_layout_harness_artifacts/.harnessgym \ --output-dir tmp/tensor_layout_claude_compare_final \ --trials 1 \ --iterations 1 \ --attempt-timeout 5m \ --runner claude \ --score-key best_cycles \ --stop-score 1 \ --task-state continue \ --post-command "python3 benchmark.py --json --mode final" \ --post-score-key best_cycles \ --post-timeout 2m \ --require-harness-tool-use \ --overwrite ``` 相同的重放可用作帮助器脚本，首先检查 Claude Code 是否可以进行模型调用，然后审核生成的比较报告的有效普通/强化试验，有效的后期分数和预期的活动张量计划 MCP 工具计数。帮助器默认为 `REQUIRE_HARNESS_TOOL_USE=1`，因此强化 Claude 重放必须记录至少一个生成的 MCP 工具调用： ```bash examples/tensor_layout_harness_artifacts/run_claude_compare.sh ``` 对于配额窗口验证，设置 `WAIT_FOR_CLAUDE=1` 以重试预飞行检查，最多 `PREFLIGHT_MAX_WAIT_SECONDS` 秒，然后运行比较。 存储库还包含一个真正的 H100 支持的 Triton 任务和从验证运行生成的 HarnessGym 神器包： ```bash rm -rf tmp/h100_triton_real mkdir -p tmp/h100_triton_real cp -R examples/triton_rmsnorm_h100_task/. tmp/h100_triton_real/ HARNESSGYM_GPU_HOST=<user@h100-host> \ HARNESSGYM_GPU_PORT=<ssh-port> \ HARNESSGYM_GPU_KEY=~/.ssh/id_ed25519 \ PYTHONPATH=src \ python3 -m harnessgym.cli run \ --task tmp/h100_triton_real/task.md \ --workspace tmp/h100_triton_real \ --iterations 2 \ --attempt-timeout 5m \ --reflection-timeout 3m \ --build-timeout 5m \ --post-attempt-command 'python3 remote_h100.py --workspace h100_triton_real_post -- python3 verifier.py --json --mode final --warmup 10 --repeats 20' \ --post-attempt-score-key best_us \ --post-attempt-timeout 3m \ --score-key best_us \ --stop-score 90 \ --optimization-mode \ --runner exec ``` 记录的实验将 H100 的最终得分从 `150.016 us` 提高到 `103.328 us` 的最佳检查点，生成了一个技能和 MCP 服务器，修复了一个资格认证失败，并在下一个新鲜 Codex 会话中确认了 10 个生成的 MCP 调用。参见 `docs/experiments/h100-triton-rmsnorm.md` 和 `examples/triton_rmsnorm_h100_harness_artifacts/`。 后续的四次迭代从该生成的强化神器包开始，将 H100 的独立验证得分从 `142.848 us` 提高到 `99.744 us`。该运行将提交的 H100 MCP 扩展到 17 个活动工具，包括远程健康检查、精确/近似 SiLU 源扫描、联合源加启动搜索、重复评分和下一个实验排名。参见 `docs/experiments/h100-triton-rmsnorm-long.md`。 ## 工作流 每次迭代： 1. 启动尝试阶段的新运行器会话。 2. 尝试主要任务，直到解决、阻塞、失败或超时。 3. 在同一会话中反思最高杠杆缺失的技能、MCP 服务器、验证器、夹具、脚本、文档或工具。 4. 在同一会话中构建单个选定的改进。 5. 在干净的重放工作区中验证生成的神器，在同一会话中修复失败的强化神器（如果可能），并隔离仍然失败的神器。 6. 将可重复使用、推广的神器存储在 `.harnessgym/` 下，并在 `.harnessgym/registry.json` 中记录它们。 7. 使用累计的注册表上下文启动下一个迭代的新会话。 当迭代写入 `result.json` 且 `status: "solved"` 和 `verified: true` 或传递的验证对象时，HarnessGym 提前停止。 使用 `--task-state reset`，HarnessGym 在运行开始前快照非 `.harnessgym` 工作区，并在迭代 2..N 之前恢复它。`.harnessgym` 保持完整，因此技能、MCP 服务器、工具、夹具和注册表项会累积。 ## 神器 运行特定的日志存储在： ```text .harnessgym/runs/<run_id>/iterations/<n>/ ``` 每个迭代目录包含： - `result.json` - `<phase>.prompt.txt` - `<phase>.stdout.txt` - `<phase>.stderr.txt` - `<phase>.transcript.txt` ``` 可重复使用的神器存储在： ```text .harnessgym/skills/ .harnessgym/mcp/ .harnessgym/tools/ .harnessgym/verifiers/ .harnessgym/fixtures/ .harnessgym/tests/ .harnessgym/docs/ .harnessgym/scripts/ ``` 注册表文件 `.harnessgym/registry.json` 从这些目录同步更新。 生成的工具应具有自己的测试。对于 MCP 服务器，清单可以声明 `self_test`；`true` 表示 HarnessGym 将运行服务器命令并带 `--self-test`，而命令字符串/列表/对象可以指向单独的测试运行器。对于数值、内核、编译器或基准测试工具，生成的测试应包括已知的玩具案例、容差检查、固定种子随机化案例以及适用时的快速/开发和最终/保留模式。 失败的神器保留在磁盘上，但在 `registry.json` 中被隔离并带有资格元数据。隔离的神器不会在尝试提示中宣传，也不会注入到运行器 MCP 配置中；资格报告路径为下一个修复构建提供了确切的失败证据。 ## 智能体激活 HarnessGym 将生成的神器存储在 `.harnessgym/` 下，然后在每次新鲜尝试之前激活运行器原生部分： - 来自 `.harnessgym/skills/<name>/SKILL.md` 的技能被符号链接到 `.agents/skills/<name>` 用于 Codex 和 `.claude/skills/<name>` 用于 Claude Code。 - 来自 `.harnessgym/mcp/**/{mcp.json,server.json,harnessgym-mcp.json}` 的 MCP 清单被写入项目本地的 `.codex/config.toml`。 - MCP 服务器在激活时使用 `initialize` 和 `tools/list` 进行烟雾检查；失败被记录为警告而不是静默宣传损坏的服务器。 - MCP 服务器必须在激活期间公开一个非空的工具库存并通过清单的 `self_test` 传递；`self_test: true` 表示 HarnessGym 运行服务器命令并带 `--self-test`；命令字符串/列表/对象可以指向单独的测试运行器。 - `exec` 运行器将传递的激活记录转换为 `codex exec -c mcp_servers...` 覆盖，因为 `codex exec` 默认加载用户配置，不应要求修改全局 Codex 配置以适用于存储库生成的 MCP。 - `claude` 运行器将传递的激活记录写入 `.harnessgym/claude_mcp_config.json`，启动 Claude Code 并带 `--strict-mcp-config --mcp-config <that file>`，并授予生成的 MCP 工具与 Claude 的服务器级权限令牌 `--allowedTools=mcp__<server>`。由于 Claude Code 2.1.133 通过 stdio 发送换行符分隔的 MCP JSON，而 HarnessGym 生成的 Codex MCP 服务器使用 Content-Length 帧，运行器包装每个生成的服务器与 `harnessgym.claude_mcp_bridge`。桥接器响应超时遵循每个清单的 MCP 工具超时。 - Codex MCP 遥测代理和 Claude MCP 桥接器都记录每个生成的 MCP `tools/call` 为紧凑的 JSONL `.harnessgym/mcp_calls.jsonl`，包括服务器名称、工具名称、参数键摘要、持续时间、状态和结果大小。比较报告包括 `mcp_telemetry`、`mcp_call_count` 和 `mcp_called_tools`。 - 具有失败的烟雾检查、缺少/失败的自测试或空工具库存的生成的 MCP 服务器不会注入到运行器尝试中。 - 生成的 MCP 服务器应使用 Content-Length 帧的stdio JSON-RPC。新行 JSON 助手可能作为本地脚本很有用，但它们将失败 Codex 和 Claude 激活。 - 激活详细信息、质量门状态和活动工具计数在 `.harnessgym/activation.json`、每个迭代的 `activation.json` 和构建后激活快照中捕获。 HarnessGym 还从尝试的 stdout/stderr/transcripts 推断强化使用情况，因此超时运行仍可以报告生成的工具使用情况。 - 构建后新鲜工作区资格报告存储在每个迭代的 `qualification/attempt_<n>/qualification.json` 下，修复构建日志存储在 `repair_<n>/` 下。 器 - `exec`: MVP 后端。使用 `codex exec` 进行尝试，使用 `codex exec resume <session_id>` 进行反思/构建阶段，当 Codex 暴露会话 ID 时。它使用普通的自主提示；它不假设 `codex exec "/goal ..."` 设置目标。超时处理在进程组中启动 Codex，并终止整个组，以便生成的基准/工具子进程无法无限期保持管道打开。 - `claude`: Claude Code 后端。使用 `claude -p --output-format json` 进行尝试，使用 `claude -p --resume <session_id>` 进行反思/构建阶段。它解析 Claude 的 JSON `session_id`，捕获 stdout/stderr/转录，强制执行进程组超时，在 `.claude/skills` 下激活生成的技能，并通过存储库本地的 Claude MCP 配置和 stdio 分帧桥传递合格的 MCP 服务器。 - `tui-goal`: 实验性 PTY 后端。它启动交互式 `codex`，发送真正的 `/goal` 命令用于尝试阶段，并向同一进程发送反思/构建提示。完成情况从 `result.json` 推断，因此 `exec` 运行器是推荐的 MVP 路径。 - `fake`: 用于测试和演示的确定性离线运行器。它模拟第一次尝试失败、相同会话反思、工件创建和新的第二次尝试，使用生成的工件上下文。 ## 演示 存储库中包含一个纯 Python 数值调试任务： ```bash harnessgym run \ --task examples/numerical_debug_task/task.md \ --workspace examples/numerical_debug_task \ --iterations 2 \ --attempt-timeout 2m \ --build-timeout 2m \ --runner exec ``` 离线确定性演示： ```bash harnessgym run \ --task examples/numerical_debug_task/task.md \ --workspace examples/numerical_debug_task \ --iterations 2 \ --attempt-timeout 10s \ --build-timeout 10s \ --runner fake ``` 假演示故意阻止第一次尝试，创建 `.harnessgym/tools/harnessgym_fake_probe.py`，更新注册表，启动新的第二次尝试，并使用生成的工件上下文。 更难的优化演示： ```bash harnessgym run \ --task examples/paged_attention_optimization_task/task.md \ --workspace examples/paged_attention_optimization_task \ --iterations 2 \ --attempt-timeout 5m \ --build-timeout 5m \ --runner exec \ --stop-score 2.0 \ --score-key best_ms ``` 此基准测试从一个正确但慢的分页注意力解码内核开始。目标是减少 `best_ms` 从 `python3 benchmark.py --json`；正确性仍然是强制性的。 实际验证运行使用训练工作空间生成 Codex 技能和 MCP 服务器，然后重放原始任务，有无这些工件： - 利用复现：`best_ms=1.3588`，尝试持续时间 `112.7s`。 - 无工件重放：`best_ms=1.6759`，尝试持续时间 `144.6s`。 - 生成的工件包括 `.harnessgym/skills/paged_attention_opt/SKILL.md` 和 `.harnessgym/mcp/paged_attention_harness/`。 - 复现利用在 `.agents/skills` 中激活了技能，在 `.codex/config.toml` 中激活了 MCP 服务器。 这些数字来自这台机器上的一个真实 Codex 运行，而不是统计学上强大的基准测试。它们作为端到端证明很有用，即生成的复现工件可以减少求解时间并提高达到的分数；重复运行可能会有所不同。 CPU C 闪存注意力优化演示： ```bash harnessgym run \ --task examples/c_flash_attention_optimization_task/task.md \ --workspace examples/c_flash_attention_optimization_task \ --iterations 5 \ --attempt-timeout 3m \ --build-timeout 3m \ --runner exec \ --stop-score 1 \ --score-key best_cycles \ --task-state continue ``` 此演示优化 `kernel.c` 以获得最低的 `best_cycles`，来自 `python3 benchmark.py --json`。基准测试使用随机化的 Q/K/V 输入，验证每个计时输出，并在计时之前避免预热确切的测量情况，防止重复输入记忆化被视为真正的内核加速。 基准测试有两个模式： ```bash python3 benchmark.py --json --mode dev python3 benchmark.py --json --mode final ``` `dev` 是任务提示中使用的快速反馈情况。`final` 聚合了保留的形状/种子案例，更适合复现比较。 实际的五次迭代验证运行捕获： - Codex 之前的起始示例得分：约 `816k` 个周期。 - 迭代得分：`755231`、`189648`、`188915`、`124112`、`139087` 个最佳观察周期。 - 运行后的最终权威基准测试：`115862` 个周期，通过正确性测试。 - 生成的工件包括 `.harnessgym/skills/c-flash-attention-harness/SKILL.md` 和 `.harnessgym/mcp/c-flash-attention-harness/`。 最终状态在此运行中应为 `incomplete`，因为 `--stop-score 1` 故意无法达到；它强制执行所有五次迭代。 在用最终保留案例强化评估器后，刷新后的实际 HarnessGym 构建生成： - `.harnessgym/skills/c-flash-attention-optimizer/SKILL.md` - `.harnessgym/mcp/c-flash-attention-harness/server.py` - `.harnessgym/mcp/c-flash-attention-harness/harnessgym-mcp.json` 刷新的 MCP 服务器在新的复现工作空间中干净地激活，并暴露了 `c_flash_benchmark`、`c_flash_compare_modes`、`c_flash_compile_case` 和 `c_flash_score_ranges`。 具有相等 300 秒尝试预算的一次试验真实比较捕获： - 普通复现最终保留得分：`222581` 个周期。 - 复现利用最终保留得分：`189356` 个周期。 - 两个尝试都在 300 秒上限处超时，因此这证明在相同的模型时间预算内达到了更好的分数，而不是更低的壁钟完成时间。 - 报告路径：`tmp/c_flash_attention_1trial/compare_report.json`。 在切换到深度复现模式以要求综合生成的工具测试后，另一个实际的两次迭代生成运行构建： - `.harnessgym/skills/c-flash-attention-optimizer/SKILL.md` - `.harnessgym/mcp/c_flash_attention/server.py` - `.harnessgym/mcp/c_flash_attention/harnessgym-mcp.json` - `.harnessgym/tests/test_c_flash_attention_mcp.py` 生成的 MCP了 `run_benchmark`、`numerical_check`、`assembly_summary`、`benchmark_variant`、`score_delta_profile`、`sweep_kernel_experiments` 和 `rank_experiments`。其自测试涵盖了内容长度 JSON-R帧、每个工具、数值玩具/随机案例/final 基准测试入口点、回滚行为和无效工具/错误路径。新的复现利用激活了 MCP，没有警告，并通过了生成的自测试。 具有600 秒累计尝试预算的一次真实两次迭代 - 普通复现最终保留得分：` 个周期。 - 复现利用最终保留`169005` 个周期。 - 两个完成了两次超时 300 秒的尝试；复现分支在相同的模型时间预算内取得了更好的验证分数。 - 报告路径：`tmp/c_flash_attention_compare_deep_tests_2turn/compare_report.json`。 CPU 注意力自动调谐复现演示： ```bash harnessgym run \ --task examples/cpuotune_task/task.md \ --/cpu_attention_autotune_task \ 5 \ --attempt 2m --reflection-time2m \ --build-timeout 4m \ --runner exec \ --stop-score --score-key best_cycles \ --task-state continue \ --harness-depth deep ``` 这是 CPU 自定义内核自动调谐代理。任务仅编辑 `kernel_config.json`，验证正确性，并优化 `` 跨快速开发和保留的最终模式。 实际的五次迭代 HarnessGym 生成运行构建： - `.harnessgym/skills/cpu_attention_aut/SKILL.md` - `.harnessgym_attention_autotune/server.py` - `.harnessgym/mcp/cpu_attention_autotune/harnesscp.json` - `.harnessgym/tests/test_mcp.py` 生成的 MCP 暴露了目标配置验证、开发/最终评估、得分组件分析、确定性混合搜索、一次性自动调谐/应用/记录、邻居排名、回滚安全候选应用、历史比较和结果记录。其自测试涵盖了内容长度 MCP 分帧、基本工具、固定种子随机数值检查、开发/最终入口点、搜索模式、应用回滚和得分组件协议，与基准测试一致。 干净的实际比较命令是： ```bash harnessgym compare \ --workspace-template examples/cpu_attention_autotune_task \ --task task.md \ --artifact-source tmp/cpu_attention_autotune_harness5/.harnessgym \ --output-dir tmp/cpu_attention_autotune_compare_pg \ --trials 1 \ --iterations 5 \ --attempt-timeout 2m \ --runner exec \ --score-key best_cycles \ --stop-score 1 \ --task-state continue \ --post-command "python3 benchmark.py --json --mode final" \ --post-score-key best_cycles ``` 观察到的结果： - 普通复现：五次超时尝试，累计尝试时间 `600.08s`，最终保留得分 `1008322`。 - 复现利用：一次超时尝试，累计尝试时间 `120.02s`，最终保留得分 `130223`。 - 得分减少：保留的 `best_cycles` 降低了 `87.09%`。 - 尝试时间减少：累计尝试时间减少约 `5.0x`。 - 报告路径：`tmp/cpu_attentionune_compare_pg/compare_report.json`。 这仍然是一次试验，而不是统计学声明。它证明了生成的复现代理在新的复现工作空间中被激活，通过 MCP 被实际的 Codex 使用，更新了 `kernel_config.json`，编写了 `result.json`，通过了最终验证者，并在目标上击败了无复现基线超过 50%。 张量布局管道复现演示： ```bash harnessgym run \ --task examples/tensor_layout_pipeline_task/task.md \ --workspace examples/tensor_layout_pipeline_task \ --iterations 5 \ --attempt-timeout 5m \ --reflection-timeout 3m \ --build-timeout 6m \ --runner exec \ --stop-score 1 \ --score-key best_cycles \ --task-state continue \ --harness-depth deep ``` 此示例故意比 CPU 自动调谐代理更全面。它优化了 `kernel_plan.json`，它控制了图块大小、张量布局、向量宽度、softmax 策略、累积、DMA 阶段、预取距离、描述符突发大小、分割 K、scratchpad 大小、调度、swizzling 和外传融合。基准测试公开了快速开发案例、保留的最终案例、正确性容差和详细的跟踪 JSON： ```bash python3 benchmark.py --json --mode dev --trace trace.dev.json python3 benchmark.py --json --mode final python3 verifier.py ``` 跟踪包括描述符计数、寄存器压力、scratchpad 需求、计算/内存周期、银行冲突惩罚、DMA 惩罚和布局/调度协同作用。这为 HarnessGym 提供了足够的信号来构建更高价值的复现代理，例如张量布局分析器、DMA 描述符工具、跟踪差异工具、回滚安全计划扫描器和 MCP 自测试。起始最终得分为 `33975173` 个周期，并且有效但故意较差。 这是评估 HarnessGym 是否优于 vanilla Codex 时推荐的下一个性能证明任务。它故意比 stencil 任务更难解决，因为进度取决于检查跟踪/布局/描述符交互并自动扫描，而不是应用一个明显的内核重写。 实际的五次迭代运行生成了一个张量布局技能和 MCP 服务器，具有聚焦搜索、非脊柱搜索、候选证明、截止日期感知应用、快速聚焦应用、历史、最终门控和自测试。最终工作空间得分： ：`262005周期，从 `8348345` 下降。 - 最终：`1495982` 个周期，从 `33975173` 下降。 - 最终减少：`95.60%`。 CLI 运行仍然报告 `Solved and verified: False`，因为尝试在更改 `kernel_plan.json` 后被终止，而 Codex 完成了自己的结果写入。上述的尝试后评分模式被添加，以关闭未来运行的该间隙。 CPU top-2 MoE 内核演示： ```bash harnessgym run \ --task examples/cpu_moe_kernel_task/task.md \ --workspace examples/cpu_moe_kernel_task \ --iterations 5 \ --attempt-timeout 8m \ --reflection-timeout 3m \ --build-timeout 8m \ --runner exec \ --post-attempt-command "python3 verifier.py --mode final --json" \ --post-attempt-score-key best_cycles \ --post-attempt-timeout 2m \ --optimization-mode \ --stop850000 \ --score-key best_cycles-state continue \ --harness-depth deep 示例是一个实际 C 内核基准测试，用于 CPU top-2 混合专家推理。它优化了 `moe_kernel.c` 和 `kernel_config.json`；`benchmark.py` 编译了一个共享库，生成了确定性的路由 MoE 案例，检查了数值正确性与 Python 参考，并报告了最佳重复定时估计的周期数： ```bash python3 benchmark.py --json --mode dev --trace trace.dev.json python3 benchmark.py --json dev --assembly moe_kernel.s python3 benchmark.py --json --mode final python3 verifier.py --mode final --json ``` 开发/最终案例包括统一、Zipf、突发和对抗路由分布。跟踪记录了专家桶负载、路由偏差、工作估计和每个案例的周期数据。这旨在推动 HarnessGym 实现路由桶分析器、汇编/矢量化摘要、配置/源变体扫描器、正确性模糊器和回滚安全最终模式排名的五次迭代 HarnessGym 生成运行 - `.harnessgym/skills/cpu_moe_kernel/SKILL.md` - `.harnessgym/mcp/cpu_moe_kernel/server.py` - `.harnessgym/mcp/cpu_moe_kernel/harnessgym-mcp.json` - `.harnessgym/tests/test_cpu_moe_mcp.py` 生成的 MCP 从 10 个工具增长到 15 个活跃工具，涵盖数值测试、形状别名测试、基准测试重复、汇编诊断、回滚安全源试验、NEON 行扫描、调度扫描、微扫描、历史和排名。激活质量门在 MCP 烟雾测试和自测试通过后在强化基准测试后，一次迭代的实际干净比较具有相等的 300 秒尝试预算： - 普通复现最终得分：`43200` 个周期。 - 复现利用最终得分：`34934` 个周期。 - 得分减少：`19.13%` 降低保留的 `best_cycles`，在相同的尝试预算内。 -路径：`tmp/cpp_stencil_compare_hardened_1iter/compare_report.json`。 这是一次试验，而不是统计学声明。其主要价值在于它端到端锻炼了实际的 HarnessGym 路径：生成的工件复制到新的工作空间，技能/MCP 激活，MCP 自测试，Codex 的活跃工具使用，最终后评分和无效后评分处理。 ## 开发 ```bash python -m pytest ``` 待办事项： - 为多运行比较报告添加更丰富的统计评分。 - 如果 Codex 或 Claude Code CLI 输出更改，则添加更丰富的会话 ID 解析。 - 在交互完成强化 `tui-goal` 运行器。