名称: 评估预设 描述: 用于测试Ralph的hat集合预设、验证预设配置或审计预设库中的bug和UX问题。
评估预设
概述
使用shell脚本系统性地测试所有hat集合预设。直接CLI调用——无元编排复杂性。
使用时机
- 更改后测试预设配置
- 审计预设库的质量
- 验证新预设正常工作
- 修改hat路由逻辑后
快速开始
评估单个预设：
./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
启动后，使用 block: false 的 TaskOutput 检查状态，无需等待完成。
脚本功能
evaluate-preset.sh
- 从
tools/preset-test-tasks.yml加载测试任务（如果yq可用） - 创建包含评估设置的合并配置
- 使用
--record-session运行Ralph以捕获指标 - 捕获输出日志、退出代码和计时
- 提取指标：迭代次数、激活的hat、发布的事件
输出结构：
.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>
评估中的预设
| 预设 | 测试任务 |
|---|---|
tdd-red-green |
添加 is_palindrome() 函数 |
adversarial-review |
审查用户输入处理器的安全性 |
socratic-learning |
理解 HatRegistry |
spec-driven |
指定并实现 StringUtils::truncate() |
mob-programming |
实现 Stack 数据结构 |
scientific-method |
调试失败的模拟测试断言 |
code-archaeology |
理解 config.rs 的历史 |
performance-optimization |
分析hat匹配性能 |
api-design |
设计 Cache trait |
documentation-first |
记录 RateLimiter |
incident-response |
响应“CI中测试失败” |
migration-safety |
规划v1到v2配置迁移 |
结果解释
来自 evaluate-preset.sh 的退出代码：
0— 成功（达到LOOP_COMPLETE）124— 超时（预设挂起或耗时过长）- 其他 — 失败（检查
output.log）
metrics.json 中的指标：
iterations— 事件循环周期数hats_activated— 触发了哪些hatevents_published— 发布的事件总数completed— 是否达到完成承诺
Hat路由性能
关键： 验证每个hat根据原则#1（“新鲜上下文即可靠性”）获得新鲜上下文。
良好表现
每个hat应在自己的迭代中执行：
迭代 1: Ralph → 发布起始事件 → 停止
迭代 2: Hat A → 执行工作 → 发布下一个事件 → 停止
迭代 3: Hat B → 执行工作 → 发布下一个事件 → 停止
迭代 4: Hat C → 执行工作 → LOOP_COMPLETE
危险信号（同迭代hat切换）
不良： 一个迭代中多个hat角色：
迭代 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 中检查同迭代hat切换：
grep -E "ITERATION|Now I need to perform|Let me put on|I'll switch to" \
.eval/logs/<预设>/latest/output.log
危险信号： hat切换短语之间没有ITERATION分隔符。
3. 在 session.jsonl 中检查事件时间戳：
cat .eval/logs/<预设>/latest/session.jsonl | jq -r '.ts'
危险信号： 多个事件具有相同时间戳（在同一迭代中发布）。
路由性能诊断
| 模式 | 诊断 | 行动 |
|---|---|---|
| 迭代次数 ≈ 事件数 | ✅ 良好 | Hat路由工作正常 |
| 迭代次数 << 事件数 | ⚠️ 同迭代切换 | 检查提示是否有STOP指令 |
| 迭代次数 >> 事件数 | ⚠️ 恢复循环 | 代理未发布所需事件 |
| 0 事件 | ❌ 损坏 | 事件未从JSONL读取 |
根本原因检查清单
如果hat路由损坏：
-
检查工作流提示 在
hatless_ralph.rs中：- 是否说“关键：发布后停止”？
- DELEGATE部分是否明确关于放弃控制？
-
检查hat指令传播：
HatInfo是否包含instructions字段？- 指令是否在
## HATS部分渲染？
-
检查事件上下文：
build_prompt(context)是否使用context参数？- 提示是否包含
## PENDING EVENTS部分？
自主修复工作流
评估后，将修复委托给子代理：
步骤1: 诊断结果
读取 .eval/results/latest/SUMMARY.md 并识别：
❌ 失败→ 创建代码任务进行修复⏱️ 超时→ 调查无限循环⚠️ 部分→ 检查边缘情况
步骤2: 分发任务创建
对于每个问题，生成任务代理：
“使用 /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/— 正在评估的预设集合