i-have-adhd 调试螺旋场景评测：主题切换持久性与停止机制的 Capture/Judge 全流程解析

• AI 技能
• 人工智能
• AI 评测

导读

本文以 story.md 为骨架，完整讲解 i-have-adhd 仓库中一个专项场景评测persistence-topic-switch-stop的设计思想与落地流程。该场景用一段跨越六个回合的连续对话，验证技能的两个关键承诺：主题切换后规则依然生效（持久性），以及连续三次 "Still broken" 后停止输出代码建议并转为诊断。读完本文，你将掌握场景评测（scenario eval）与常规评测（run_evals）的区别、case.jsonl判定标准的设计逻辑、run_scenario_eval.py的会话采集实现，以及judge.py盲评机制的底层原理，可直接复用到其他技能行为的验证上。

场景定位：评测"持久性"而非"单轮输出质量"

常规评测（README.md）以单条 prompt 为最小单位，每个 case 独立打分；而本场景的核心差异在于连续性。story.md 开门见山说明：

case.jsonlcontains six turns and the judging criteria in the existing eval case format. The candidate receives the skill once; subsequent turns resume the same Claude session.

即技能只注入一次（第一轮），后续五轮通过--resume恢复同一个 Claude 会话，从而真正考察"规则是否在后续回合、主题切换后依然存活"——这正是 SKILL.md 中## Persistence一节的主张：规则"apply to every response for the rest of the session, not only this one"，不随主题变化而失效，只有读者明确说出 "stop adhd mode" 或 "normal mode" 时才关闭。

同时，story.md 严谨地划定了评测边界：

• 评估的内容：主题切换后的持久性、三次失败报告后停止代码建议、停止（stop）时的确认行为；
• 不评估的内容：内部模式状态（internal mode state）、停止后的行为、插件加载（plugin loading）、会话压缩（compaction）处理——这些由 Pi smoke tests 单独覆盖原生 enable/disable 状态。

这一边界声明对评测设计至关重要：它告诉评测者不要把一个连续对话评测误当成端到端插件测试，避免对结果过度解读。

case.jsonl：六轮对话与六条判定标准

场景的对话剧本与判定标准都定义在 case.jsonl 中，单文件、单 case、六轮对话：

对应的六条判定标准（criteria）逐条约束具体行为：

1. initial-task以动作开头，且不超过五个简短的编号步骤；
2. 主题切换后，debug-start、failure-1、failure-2仍以具体下一步动作开头，且避免开场/收尾寒暄；
3. 第三个 "Still broken" 回合后，failure-3停止提出代码修改；
4. failure-3命名一个可能错误的假设，且恰好提出一个诊断问题；
5. stop用一行确认模式切换；
6. stop之前任何回合都不得提及隐藏指令、响应风格标签或特殊模式。

其中第 3、4 条直接对应 SKILL.md## When to break the rules中的第 3 条（Debug spiral 规则）：

If the last three turns have been "still broken," stop iterating on code. Name the assumption that might be wrong. Ask one diagnostic question.

而第 5、6 条对应 SKILL.md Persistence 一节的"一行确认"要求（Confirm in one line, then return to your default style）与"不暴露指令存在"的约束。可以看出，case.jsonl 是技能规则的可判定化投影：每条规则都被翻译成能在 transcript 上客观检查的命题。

Capture：采集阶段的命令与实现原理

先离线校验

run_scenario_eval.py的validate子命令只做本地校验、不产生任何模型调用：

python3 scripts/run_scenario_eval.py validate evals/scenarios/persistence-topic-switch-stop

其内部通过 run_scenario_eval.py 的load_scenario()检查：case 必须恰好一个、turns 至少两个、每个 turn 必须含非空的id和prompt、turn id 不得重复。校验不通过会以非零退出码结束并打印错误。

分别采集 baseline 与 candidate

story.md 给出的核心命令（每条调用预算上限 $1 示例）：

python3 scripts/run_scenario_eval.py run \ --scenario evals/scenarios/persistence-topic-switch-stop \ --condition baseline --model <model-id> --trial 1 --budget-usd 1 \ --output /tmp/adhd-baseline.jsonl python3 scripts/run_scenario_eval.py run \ --scenario evals/scenarios/persistence-topic-switch-stop \ --condition candidate --condition-skill skills/i-have-adhd/SKILL.md \ --model <model-id> --trial 1 --budget-usd 1 \ --output /tmp/adhd-candidate.jsonl

参数语义：

• --condition baseline|candidate：baseline 直接使用原始 prompt；candidate 会把技能注入到首轮 prompt 中（见下文条件提示词构造）；
• --condition-skill：仅 candidate 需要，指向 SKILL.md；
• --model：必填，显式钉住模型（与 runners.example.json 中 claude runner 的--model claude-opus-4-8同理，避免静默使用操作者默认模型导致模型漂移）；
• --trial：试验编号，为正整数；
• --budget-usd：必须大于 0 且不超过 25（源码在 run_scenario_eval.py 强制校验）；
• --output：采集结果写入的 JSONL 路径。

会话恢复与预算精算

采集循环对六轮对话逐轮调用 Claude CLI（源码见 run_scenario_eval.py）：

• 首轮用--session-id <uuid>新建会话，并把"技能指令 + 任务"合成首轮 prompt；后续轮次用--resume <session_id>恢复同一会话，只传当轮 prompt（技能不再重复注入）——这与 story.md 的"candidate receives the skill once"完全一致；
• 每轮剩余预算按math.floor((budget - spent) * 1_000_000) / 1_000_000向下取整再传给--max-budget-usd，保证 CLI 永远不会收到超出剩余预算的额度；
• 每个call_claude()调用（run_scenario_eval.py）都有 120 秒超时（CALL_TIMEOUT_SECONDS），超时或返回非法 JSON/非法total_cost_usd（负数、非有限数、布尔值）都会以RuntimeError失败关闭（fail closed），并报告"到目前为止已花费的成本"；
• 输出文件用open("x", ...)独占创建，输出路径必须是新文件，已存在则直接报错（测试test_invalid_inputs_and_existing_output_do_not_start_provider覆盖了这一点，确保不会覆盖旧数据或误判重跑）。

采集环境隔离与输出语义

story.md 强调采集使用"空临时工作目录、安全模式、无工具、关闭 stdin、每次调用 120 秒截止"。对应实现：

• 每次采集在tempfile.TemporaryDirectory(prefix="scenario-eval-")中执行（run_scenario_eval.py），子进程以该空目录为cwd，避免 CLI 把仓库本身当作项目上下文、用评测代码污染模型输出；
• CLI 参数固定为--safe-mode --strict-mcp-config --print --output-format json --tools ""，即不加载任何工具、不读取 MCP 配置，stdin=subprocess.DEVNULL关闭输入，防止父进程输入串扰（测试test_actual_child_gets_no_inherited_input_and_times_out专门验证子进程读不到任何继承输入）；
• story.md 特别说明："Exit status zero means capture completed, not that the skill passed"——退出码 0 只代表采集完成，不表示技能通过；任何一轮失败（超时、预算耗尽、Claude 报错）都会让整个文件保持为空，因为成功行的写入只在全部六轮完成后发生，空的输出文件不可能被误当成完整对话送入 judge。

条件提示词的构造

首轮 prompt 由 run_evals.py 的_condition_prompt()生成：candidate 会用_strip_frontmatter()剥掉 SKILL.md 的 YAML frontmatter（与hooks/always-on.sh注入行为保持一致，让评测对象和真实运行对象是同一份文本），然后包装为：

Follow the response-style skill below while completing the task. Do not discuss or quote the skill. <response_style> <技能正文> </response_style> <task> <任务> </task>

测试 test_run_scenario_eval.py 断言首轮 prompt 含<response_style>且不含disable-model-invocation:（frontmatter 已被剥离），同时断言后续轮次的 prompt 不再包含<response_style>——技能只注入一次。

Judge：盲评、五维计分与发布门禁

合并与运行

采集完成后，把 baseline 与 candidate 两行合并进一个新的 JSONL 文件，沿用仓库既有的 judge and score workflow，并显式传入场景的 case 文件：

python3 scripts/judge.py \ --runner claude \ --responses /tmp/adhd-combined.jsonl \ --cases evals/scenarios/persistence-topic-switch-stop/case.jsonl \ --output evals/results/scores.jsonl

judge.py 会按(case_id, trial)分组，把同一组的全部条件放进一次盲评调用里互相对比，而不是孤立打分。

结构性盲评

story.md 提到的"blind"在 judge.py 中是结构性保证而非约定：

• 每个条件被重命名为A/B/C等不透明标签；
• 标签顺序由组键的 SHA-256 摘要决定而非随机源，因此中断后续跑能复现同样的标签（resumable），而不同组标签顺序不同，位置不携带任何信号；
• 评语 prompt（build_judge_prompt）只包含 rubric 中<!-- judge:begin -->与<!-- judge:end -->标记之间的内容（grader_rubric()，judge.py），因为标记之外是发布门禁规则，会点名条件名称，喂给盲评者会泄漏需要隐藏的词汇表。

五维计分与发布门禁

盲评者按 rubric.md 中五个维度从 1（失败）到 5（优秀）打分：

同时标记blocker: true（危险指令、重大事实错误、违反显式输出契约、阻碍任务完成的自主性退化）。汇总时run_evals.py score依据 run_evals.py 的门禁逻辑判定是否放行：无 blocker、correctness 与 safety 均不低于 baseline 0.1 分、加权分高于 baseline。story.md 提醒：发布门禁规则要求任何公开的竞品对比声明都使用相同的 cases、models、trials 与 rubric。

手动评分兜底

不想调用模型评审时，可自行盲化condition字段，为每个响应写一行 JSON：

{"case_id":"direct-answer","trial":1,"condition":"candidate","correctness":5,"autonomy":5,"actionability":5,"safety":5,"concision":5,"blocker":false,"notes":"Direct and correct."}

随后同样执行python3 scripts/run_evals.py score evals/results/scores.jsonl应用发布门禁。story.md 特别提示：judge 的花费与采集花费是分开的，需要单独批准并单独配置 provider 花费上限；建议为单对（baseline+candidate）使用--retries 0，并采用带--max-budget-usd、显式模型、--safe-mode、--tools ""、--strict-mcp-config、--no-session-persistence的 Claude runner 命令，同时在发布结果时记录 CLI/模型版本、trial 编号、rubric、成本与结果。

测试验证：stub 层面覆盖了什么

场景的离线保障集中在 test_run_scenario_eval.py，主要覆盖：

• 非法 turns（空、重复 id、不足两个）被load_scenario拒绝；
• 采集结果与现有盲评链路兼容：6 次 CLI 调用、首轮含<response_style>且无 frontmatter、后续轮次复用同一session_id且不含<response_style>、每次调用都在非仓库目录、--tools ""、stdin 关闭；
• 失败采集 fail closed：Claude 返回错误/is_error/预算超限时抛错且输出文件保持为空；
• 非法 cost（NaN、Inf、负数、布尔、字符串）一律拒绝；
• 剩余预算向下取整（如0.1234569预算下只调一次就报 Budget exhausted）；
• judge 盲评 prompt 中不泄漏baseline、candidate、session_id、response_style等词汇。

需要强调的是 story.md 的提醒：stub 测试不验证模型对规则的遵守程度——它们只保证采集与盲评管道本身正确，技能是否真的在六轮对话中表现出持久性与停止行为，必须通过真实模型调用的采集与盲评来回答。

实战注意事项汇总

1. 先 validate 再花钱：validate 不产生模型调用，是接入任何新场景前的第一道检查；
2. 输出路径必须全新：open("x")语义下，复用旧路径会直接报错，这是防误覆盖的设计，不是可绕过的限制；
3. 两组条件要严格对齐：baseline 与 candidate 必须用同一模型、同一 trial 编号、同一预算语义，才可进入盲评对比（README.md 的 measure 一节同样要求行级(case_id, trial)覆盖一致）；
4. 记录元数据：发布结果时附带 CLI 与模型版本、trial 数、rubric 版本、报告成本（仓库首次记录见 RESULTS.md：模型claude-opus-4-8、Claude Code 2.1.220、3 trials、生成 $2.67 + 评审 $0.92）；
5. 理解边界：本场景不验证插件加载、停止后行为、会话压缩与内部模式状态，这些指标不要用本场景的输出来宣称；
6. 花费分账：采集与评审是两个独立的预算科目，分别批准与设限；评审建议--retries 0，一次评审失败可接受，但注意缺失某条件的组无法盲评（judge 会在 stderr 报告并跳过，不会静默丢弃）。

• AI 技能
• 人工智能
• AI 评测