codestable__codestable/docs/cs-skill-e2e-eval-plan.md

cs skills 端到端效果评测方案（e2e outcome eval）

状态：方案（未实施）。作者：eval-cs-skill 闭环 campaign（2026-07-07）收口时整理。 前置阅读：experiments/cs-issue-routing-001/results.md（routing 层 verdict 与方法学）、 .claude/skills/build-cs-skill/references/cs-skill-quality-gates.md（Measured Rules）。

动机

已完成的 routing eval 证明的是代理指标：模型能读懂 skill 文档、在给定仓库状态下走对下一步 （七 skill 均值 original 0.807 → 重构后 0.965，[measured]）。它不能证明"最终干出来的活更好"。 软件研发 skill（cs-issue / cs-feat / cs-epic）有个天然优势：产出可以用测试机械判定—— 这是把评测升级到 outcome 层的抓手（对标 SWE-bench 思路）。

总体设计

场景包 = 种子仓库（真实小项目：有代码、有测试、有提交历史、已 onboard .codestable/）
       + 一个任务（bug 报告 / feature 需求 / 大需求，用户口吻）
       + 隐藏验收测试（hidden tests：模型不可见，跑完后取出判分）

种子仓库：自建，不 fork 开源项目（已决策，2026-07-07）

• 数据污染是 outcome eval 的头号效度杀手：知名 repo 在模型训练语料里，测出来的是记忆 不是能力（SWE-bench 的已知问题）。自建新代码零污染。
• cs skills 的设计环境是 onboarded .codestable/ 仓库——自建才能原生满足（效度教训： bare-input 0.31 vs 带环境 0.92）。
• 成本可控：seed 须千行级、测试秒级、零第三方依赖；真实项目的体量/依赖树在沙箱里失控。
• 自建的两个风险及化解：①太干净不像真的 → 演进式构建 + 刻意做旧（多阶段提交历史、 风格漂移、TODO/废弃模块、测试覆盖不均）；②作者偏差（建 repo/种 bug/出题同一人）→ bug 取自真实模式库 + hidden test 先写后种 + L2 对照对两组同等作用，相对差仍有效。
• 入库形态：构建脚本 + 阶段快照（experiments/seeds/<name>/build-seed.py 逐 commit 构建到 tmp，固定日期确定性输出）——避免嵌套 git repo，可 diff review。
• 种 bug 铁律：注入点必须落在 seed 自带测试的暗角（注入后自带回归仍绿）——否则 agent 一跑测试就看到失败点，难度骤降且不真实；做旧的"覆盖不均"正是为此准备。
• fork 的唯一合理变体：用 owner 自己的私有真实项目快照（模型没见过、可真 onboard）， 作为后期补充轨道。

执行：真 agent harness（claude-headless / codex-cli，eval-cs-skill 已有适配器）在沙箱 worktree 里按 skill 完整跑流程——不是单次问答。

打分（全机械 [measured]）：

指标	判法
活干成没有（主指标）	隐藏验收测试 红→绿 通过率
有没有干坏别的	种子仓库既有测试套件仍全绿（回归）
过程守没守规矩	产物契约（fix-note / design / checklist 存在且合规，复用 dod_gate scorer）；该停的 checkpoint 停了没（从产物状态判）
成本	tokens / turns / wall time（metrics.py 现成）

三个 skill 的场景设计

cs-issue（P0，最先做）

• 种真 bug 三档：单行逻辑错（易）/ 跨函数状态错（中）/ 需读多文件推理根因（难）。
• 验收：hidden test 红→绿 + 回归绿 + fix-note.md 根因正确（关键词/judge 双轨）。
• 陷阱场景：bug 报告实为新需求 → 正确动作是转 cs-feat 而非硬修（防"无脑往前冲"）。

cs-feat（P1）

• 需求含显式验收标准 + 隐含边界（如"导出 CSV"隐含空数据/逗号转义）；hidden tests 覆盖隐含项——design 阶段认真挖需求才会过。
• 测 checkpoint 遵守：design-review passed 后是否停等确认（headless 下判产物状态： design 保持 draft + 输出含等待确认，而非自批准进实现）。

cs-epic（P2/P3）

• P2 便宜版：只评拆解质量——items.yaml 与专家拆解对比（覆盖度/依赖顺序）+ 各 child design 验收标准质量。
• P3 全程版：3-4 child 小 epic 跑到底，集成测试判定 + 过程合规（批量 design、 统一确认、不逐个停）。做前单独确认预算。

对照组（决定"证明了什么"）

对照	回答的问题
L1：重构前 vs 重构后 skill 文档	本轮 prompt-as-code 重构在 outcome 层是否仍有增益
L2：有 skill vs 裸 agent 同任务	skill 本身值不值得存在（最有说服力，此前从未测过）
L3：便宜模型+skill vs 贵模型裸奔	性价比：skill 能否让便宜模型达到贵模型水平

效度铁律（承接 routing campaign 的教训）

1. hidden tests 模型不可见——可见即应试。
2. 种子仓库要像真的：提交历史 + 既有测试 + .codestable/。已验证教训：把 skill 拉出设计环境测，测出的全是假象（bare-input 0.31 vs 补上下文 0.92）。
3. 出题先自证可解：每个场景先用参考实现跑通 hidden tests（oracle 校准的事前版）。
4. 必须含"该停/该拒绝"场景：全是"往前冲得分"的题会把 skill 优化成莽夫。
5. 分诊纪律：分数异常先看 transcript / 产物，分类 oracle 问题 vs fixture 缺陷 vs skill 真缺陷 vs 模型行为差异；live 优化两轮为限；受影响变体重跑统一口径。
6. feature 场景：显式/隐含要用不同的出题与自证标准（2026-07-08 两次实证后修订）：
   • explicit hidden：接口细节（子命令/参数形式/输出格式/列名）必须以用法示例写进 需求文本（否则合理实现被误判：sonnet --output vs hidden 锁位置参数 → exit 2）； 自证 = 第三方视角只读需求文本实现，explicit 应全绿。
   • implicit hidden：隐含边界绝不写进需求文本——写进去它就不再隐含（第一版修复 把 f02/f03 的隐含全集显式化，直接摧毁了"design 挖隐含需求"的测量对象 H3）。 其自证标准不是"只读需求满分"（逻辑上不可能），而是"资深工程师标准的参考实现 应全绿"——断言只许覆盖专业共识边界（合理工程师即使需求没写也会处理的），且 implicit 断言不得依赖任何接口自由度（只测行为语义，经由 explicit 已锁定的接口触达）。
   • 两条自证矛盾的仲裁：某断言既过不了"资深标准自证"又不能写进需求 → 删掉该断言。
   • 观测通道规则（第三轮实证后补）：隐含行为必须经某个通道观测，通道无契约 = 接口 锁定换形态回归（f03 断言 untagged 字面桶名 → 四变体全挂 0/24）。implicit 断言只测 状态/数据行为（查库、或解析 explicit 已锁定接口输出中的数据，数值比较不比字符串）； 呈现细节（桶名/报错文案/exit code）要么补进接口契约、要么宽容匹配。判别力校验： f01 的 RFC4180 断言四格全过 = csv.writer 免费获得，判别力≈0——低判别断言留作下界 锚点可以，但不能是 implicit 组的主体。
7. skill 的环境依赖要么提供要么豁免（同日实证）：cs-feat 的实现阶段设计为经可见 Task agent goal driver 派发——headless 无 driver 时 agent 守规矩 handoff 退出（design 完打印 /goal），实现零落地。inject_context 豁免块须显式覆盖"driver 不可用：本会话 内直接完成"，否则测出的是环境缺失不是 skill 能力。
8. 生成型/拆解型 eval 必须校验 output 未撞 max_tokens 上限（2026-07-08 cs-epic 实证）： 36/36 撞 2048 时覆盖率测成"上限内塞得下多少文本"，冗长格式（roadmap 含阶段/依赖/验收） 被砍更狠，差点误导出 H4 NULL。修 adapter_api.py（默认 8192 + CS_EVAL_MAX_TOKENS 覆盖） 后 edge 优势才现。撞上限的批次数据作废，须重跑。
9. 拆解/生成型覆盖度只能用语义 judge，token recall 不可作 measured 下界（同日）： planted_defect（token）对自然语言拆解系统性低估 32pp（0.49 vs opus judge 0.81）；决定性 案例同一 roadmap planted=0.43（漏 4 项含 obvious）vs judge=1.0（7 项全覆盖）。措辞自由度高 token 匹配必漏。diff-based 缺陷召回仍可用 token（缺陷文本相对固定），自然语言拆解不行。
10. 认知诚实标注不变：[measured]/[soft]/[underpowered]；hypotheses 先于运行注册。

框架衔接（复用现有 eval-cs-skill）

• 已有可复用：harness 注册表（claude-headless/codex-cli/api）、dod_gate scorer、 checkpoint/resume + 分段、per-cell 容错 + 重试、--dry-run 成本护栏、认知诚实 tag。
• 需新建：
  • fixtures/e2e/：每场景一个目录（seed-repo/ + hidden-tests/ + scenario.json）； 新 answerType e2e-outcome。
  • runner 的 e2e 模式：workdir=解压 seed → agent harness 跑 skill → 执行 hidden tests 与回归套件 → 收集产物/transcript。
  • e2e_outcome scorer：测试通过率 + 回归 + 产物契约合成。
• 沙箱隔离：每 cell 独立 tmp workdir（既有约定），不触宿主仓库。

成本与分期

期	内容	估算	前置
P0	cs-issue ×8 场景、单模型、k=3	~$10-20	无
P1	cs-feat ×6 + 裸 agent 对照（L2）	~$30-50	P0 管线
P2	cs-epic 拆解质量版	~$10	P0
P3	cs-epic 全程版	$50+	单独确认预算

单次 cs-feat 全流程 50-200k tokens，比 routing 选择题贵 50-100 倍——P0 先跑通管线， 后续只是换场景。统计功效：每 skill ≥6 场景 × k≥3；hidden tests 为二元判定，方差低于 LLM judge，所需样本量小于 soft 指标。

风险与开放项

• headless harness 的 checkpoint 交互：等确认类场景需注入"用户确认"脚本或以 "停在正确状态"为判分点——实施时定。
• 种子仓库维护成本：每场景一个可跑项目，优先共享 1-2 个 seed（同仓库种不同 bug/需求）。
• cs-epic 全程版的长时执行受环境 kill 影响——依赖既有 resume 机制，必要时分 child 分段。