名称： evaluate-presets
描述： 用于测试 Ralph 的帽子集合预设、验证预设配置，或审计预设库中的错误和用户体验问题。

评估预设

概述

使用 Shell 脚本系统性地测试所有帽子集合预设。直接通过 CLI 调用，无需复杂的元编排。

使用时机

• 变更后测试预设配置
• 审计预设库的质量
• 验证新预设是否正常工作
• 修改帽子路由逻辑后

快速开始

评估单个预设：

./tools/evaluate-preset.sh tdd-red-green claude

评估所有预设：

./tools/evaluate-all-presets.sh claude

参数说明：
- 第一个参数：预设名称（不带 .yml 扩展名）
- 第二个参数：后端（claude 或 kiro，默认为 claude）

Bash 工具配置

重要提示： 通过 Bash 工具调用这些脚本时，请使用以下设置：

• 单个预设评估： 设置 timeout: 600000（最长 10 分钟）和 run_in_background: true
• 所有预设评估： 设置 timeout: 600000（最长 10 分钟）和 run_in_background: true

由于预设评估可能运行数小时（尤其是完整套件），请务必在后台模式下运行，并使用 TaskOutput 工具定期检查进度。

调用模式示例：

使用 Bash 工具，设置：
  command: "./tools/evaluate-preset.sh tdd-red-green claude"
  timeout: 600000
  run_in_background: true

启动后，使用 TaskOutput 并设置 block: false 来检查状态，而无需等待完成。

脚本功能

evaluate-preset.sh

1. 从 tools/preset-test-tasks.yml 加载测试任务（如果 yq 可用）
2. 创建包含评估设置的合并配置
3. 运行 Ralph 并启用 --record-session 以捕获指标
4. 捕获输出日志、退出码和计时信息
5. 提取指标：迭代次数、激活的帽子、发布的事件

输出结构：

.eval/
├── logs/<预设名称>/<时间戳>/
│   ├── output.log          # 完整的 stdout/stderr
│   ├── session.jsonl       # 录制的会话
│   ├── metrics.json        # 提取的指标
│   ├── environment.json    # 运行时环境
│   └── merged-config.yml   # 使用的配置
└── logs/<预设名称>/latest -> <时间戳>

evaluate-all-presets.sh

顺序运行所有 12 个预设并生成摘要：

.eval/results/<套件ID>/
├── SUMMARY.md              # Markdown 报告
├── <预设名称>.json         # 每个预设的指标
└── latest -> <套件ID>

待评估的预设

结果解读

evaluate-preset.sh 的退出码：
- 0 — 成功（达到 LOOP_COMPLETE）
- 124 — 超时（预设挂起或耗时过长）
- 其他 — 失败（检查 output.log）

metrics.json 中的指标：
- iterations — 事件循环的周期数
- hats_activated — 触发了哪些帽子
- events_published — 发出的事件总数
- completed — 是否达到完成承诺

帽子路由性能

关键点： 根据原则 #1（“新鲜上下文即可靠性”），验证每个帽子是否获得新鲜上下文。

良好表现

每个帽子应在自己的迭代中执行：

迭代 1: Ralph → 发布起始事件 → 停止
迭代 2: 帽子 A → 执行工作 → 发布下一个事件 → 停止
迭代 3: 帽子 B → 执行工作 → 发布下一个事件 → 停止
迭代 4: 帽子 C → 执行工作 → 循环完成

危险信号（同迭代帽子切换）

不良情况： 单个迭代中出现多个帽子角色：

迭代 2: Ralph 执行蓝队 + 红队 + 修复者工作
        ^^^ 全部在一个臃肿的上下文中！

检查方法

1. 在 session.jsonl 中统计迭代次数与事件数：

# 统计迭代次数
grep -c "_meta.loop_start\|ITERATION" .eval/logs/<预设名称>/latest/output.log

# 统计发布的事件数
grep -c "bus.publish" .eval/logs/<预设名称>/latest/session.jsonl

预期： 迭代次数 ≈ 发布的事件数（每次迭代一个事件）
不良迹象： 2-3 次迭代但有 5+ 个事件（所有工作都在单个迭代中）

2. 在 output.log 中检查同迭代帽子切换：

grep -E "ITERATION|Now I need to perform|Let me put on|I'll switch to" \
    .eval/logs/<预设名称>/latest/output.log

危险信号： 帽子切换短语之间没有 ITERATION 分隔符。

3. 检查 session.jsonl 中的事件时间戳：

cat .eval/logs/<预设名称>/latest/session.jsonl | jq -r '.ts'

危险信号： 多个事件具有相同的时间戳（在同一迭代中发布）。

路由性能诊断

根本原因检查清单

如果帽子路由损坏：

1. 检查 hatless_ralph.rs 中的工作流提示词：

   • 是否包含“关键：发布后停止”？
   • DELEGATE 部分是否清晰地说明了让出控制权？

2. 检查帽子指令传播：

   • HatInfo 是否包含 instructions 字段？
   • 指令是否在 ## HATS 部分呈现？

3. 检查事件上下文：

   • build_prompt(context) 是否使用了 context 参数？
   • 提示词是否包含 ## PENDING EVENTS 部分？

自主修复工作流

评估后，将修复任务委派给子代理：

步骤 1：分析结果

阅读 .eval/results/latest/SUMMARY.md 并识别：
- ❌ 失败 → 创建代码任务进行修复
- ⏱️ 超时 → 调查无限循环
- ⚠️ 部分完成 → 检查边界情况

步骤 2：分发任务创建

针对每个问题，生成一个 Task agent：

"使用 /code-task-generator 为以下问题创建修复任务：[来自评估的问题]
输出到：tasks/preset-fixes/"

步骤 3：分发实现

针对每个创建的任务：

"使用 /code-assist 实现：tasks/preset-fixes/[任务文件].code-task.md
模式：自动"

步骤 4：重新评估

./tools/evaluate-preset.sh <已修复的预设> claude

先决条件

• yq（可选）：用于从 YAML 加载测试任务。安装：brew install yq
• Cargo：必须能够构建 Ralph

相关文件

• tools/evaluate-preset.sh — 单个预设评估
• tools/evaluate-all-presets.sh — 完整套件评估
• tools/preset-test-tasks.yml — 测试任务定义
• tools/preset-evaluation-findings.md — 手动发现文档
• presets/ — 正在评估的预设集合