gsb-cli 0.1.2

package/skills/gsb-eval/references/decision-report-v1.md

@@ -0,0 +1,122 @@
+# GSB Decision Report v1
+
+本模板用于用户要求「分析 GSB 结果 / 生成评估报告 / 支持上线决策」时的默认分析协议。目标不是只给胜率，而是回答三个问题：
+
+1. 这次 GSB 的明确结论是什么？
+2. 候选版本为什么赢、为什么输？
+3. 哪些题型、结构指标、自然语言反馈和 case 指向后续优化方向？
+
+## 默认输出
+
+- HTML 决策报告：`workspace/tasks/<task>/report/decision_report.html`
+- JSON 结构化摘要：`workspace/tasks/<task>/report/decision_summary.json`
+
+推荐命令：
+
+```bash
+python3 scripts/build_gsb_decision_report.py \
+  --task <task_id> \
+  --task-name <display_name> \
+  --focus-version <candidate_version> \
+  --baseline-version <baseline_version> \
+  --focus-alias <candidate_alias> \
+  --baseline-alias <baseline_alias>
+```
+
+## 数据清洗协议
+
+- 跳过 `skipped=true` 或 `winner=skip` 的记录。
+- 若评估结果带 `accepted` 字段，只使用 `accepted=true` 的记录。
+- 若输入数据存在结构化澄清字段（如 `need_clarification`），任一版本为澄清则整题剔除。
+- 若没有结构化澄清字段，不使用关键词启发式剔除，避免误伤正常回答。
+- 主结论按题目维度聚合；评次维度仅作为评估者画像和一致性参考。
+- 样本量过滤要尊重任务设置：`2-3` 题用户可标记为样本极少；`10` 题左右用户不默认判为低质，只有叠加快答、低锚点一致、无评论等多信号时才标记或降权。
+- 若评估者质量/样本分层后的结果与全量结果表现相近，不在报告中展开分组表，只在锚点一致性或数据清洗部分给一句稳健性说明。
+
+## 主指标口径
+
+- 每条评次直接使用 `winner` 和 `magnitude`，不做 left/right 二次归一化。
+- 题目级得分：`much_better=2`，`slightly_better=1`，`similar=0`。
+- 每题聚合后：得分 > 0 为候选版本胜，得分 < 0 为 baseline 胜，得分 = 0 为持平。
+- 胜率默认排除持平题：候选胜 / (候选胜 + baseline 胜)。
+- 输出二项检验 p-value 和 Wilson 95% CI，作为统计参考，不替代 case 判断。
+
+## 报告结构
+
+1. 一句话结论与上线建议：必须直接说明候选版本优于、弱于或不显著区别于 baseline。
+2. 数据清洗与样本范围：说明跳过、审核过滤、澄清过滤、最终题数和评次数。
+3. 核心结果 + 题型拆分：总胜负、胜率、CI/p-value、各题型胜负。
+4. 胜负原因总览：候选版本赢/输放在一起看，按原因维度给摘要，不放题目列表冒充原因。
+5. Case 分析：候选版本高共识胜出，包含题目、票数、归因、双模型回答示意和评估者反馈。
+6. Case 分析：候选版本高共识失利，结构同上。
+7. 两版都不好 / 低于预期 case：展示共同天花板和绝对质量风险。
+8. 结构指标拆分：回答结构、商品卡形态、结论前置、风险提示等可量化指标。
+9. 锚点题一致性检查：若配置锚点题，检查参评用户是否足够一致、是否存在需要分群分析的稳定偏好。
+10. 评估者画像：评估者样本量、胜负倾向、similar/below 倾向和严苛度差异。
+
+## 锚点题一致性口径
+
+锚点题的主用途是评估参评用户是否稳定、是否需要分群分析，不是用来直接证明候选版本或 baseline 哪个更好。报告中不得把「锚点题有几题偏向某模型」写成模型胜负证据；模型胜负仍以全量题目级聚合、题型拆分、case 和评论为主。
+
+默认分析步骤：
+
+1. 读取 `_config.json` 中的 `anchor_items`，或使用评次中的 `is_anchor=true`。
+2. 对每道锚点题统计多数判断，仅作为评估者一致性的参照。
+3. 对每位评估者计算「锚点多数一致率」：该评估者在已覆盖锚点上与多数判断一致的比例。
+4. 只对锚点覆盖充分的人做一致性判断。默认口径：至少覆盖 `max(4, ceil(anchor_count * 0.5))` 道锚点；覆盖不足的人只作为弱信号。
+5. 若低一致性评估者数量少，且过滤 2-3 题用户后主结论方向不变，只输出稳健性说明，不展开质量分组表。
+6. 若锚点行为显示稳定、可解释的人群分化，再做分群报告；否则不要为了分群而分群。
+
+分群触发条件应同时满足：
+
+- 有足够锚点覆盖的评估者，通常不少于 6-8 人。
+- 至少两个群体在锚点判定模式上稳定不同，而不是单个评估者噪声。
+- 分群后在胜负、题型、case 或评论原因上出现可解释差异。
+
+报告文案建议：
+
+- 有明显分群：`锚点题显示存在稳定偏好分群，后续结论按人群分别报告。`
+- 无明显分群：`锚点题未显示需要单独分群分析的稳定人群；主报告按整体样本分析即可。`
+- 覆盖不足：`锚点覆盖不足，当前不能用锚点题判断评估者一致性或偏好分群。`
+
+## 结构指标口径
+
+结构指标用于解释「为什么读起来更清晰/更全面/更啰嗦/更像直接推荐」，不能单独作为质量结论。主报告第 8 节必须包含以下指标，并展示候选版本、baseline 和差值。
+
+| 指标 | 口径 | 解释 |
+| --- | --- | --- |
+| 平均字数 | 每题 response 原文字符数均值 | 回答总体信息量 |
+| 平均段落长度 | 去掉商品卡占位后，按空行分段，平均每段字符数 | 越高越容易形成大段文本 |
+| 标题使用率 | 含 Markdown `# / ## / ###` 标题的题占比 | 是否用标题组织内容 |
+| 表格使用率 | 含 Markdown 表格行或 HTML table 的题占比 | 是否用表格辅助对比 |
+| 列表使用率 | 含有序或无序列表的题占比 | 是否用列表拆要点/步骤 |
+| 商品卡覆盖率 | `product_cards` 非空的题占比 | 是否出现任意商品卡 |
+| Primary card 均值 | 每题 `primary_card/single_card` 或单商品 fallback 数量均值 | 明确首推/单商品推荐密度 |
+| Peer card 均值 | 每题 `peer_card/multi_card/products[]` 数量均值 | 多商品横向选择密度 |
+| Comparison card 均值 | 每题 `comparison_card/comparison_summary_card` 数量均值 | 对比卡使用密度 |
+| 结论前置率 | 前 300 字出现“建议/不建议/结论/首推/推荐/值得”等词的题占比 | 是否开头直接给判断 |
+| 风险提示率 | 出现“风险/注意/慎重/踩坑/不适合/安全”等词的题占比 | 是否提示限制、风险和适用边界 |
+
+第 8 节同时保留「按胜负分组的字数/卡片差」，用于解释结构差异是否集中出现在候选胜出题或失利题。
+
+## Case 选择规则
+
+- 高共识胜出：候选版本题目级胜出，优先选择票差大、评论信息充分、题型覆盖不同的 case。
+- 高共识失利：baseline 题目级胜出，优先选择票差大、below、多评估者指出同类问题的 case。
+- 低于预期：任一评估者标记 `quality_rating=below` 的题目，优先挑选两版共同问题或上线风险明显的题。
+- 每个 case 的反馈必须按模型分组展示，避免把 baseline 优点和候选缺点混在一个列表里。
+
+## 回答示意渲染
+
+- 复用 `app/user_render.js` 的核心思路，在报告内渲染轻量版回答示意。
+- 支持 Markdown 标题、列表、表格行压缩、加粗。
+- 支持 `<data-cb>` 商品卡占位符，按原始回答顺序渲染，不做去重或重排。
+- 支持主推卡、对比卡、多商品卡；多商品卡用横向滚动小卡片，保留图片、标题、标签和推荐理由。
+- 手机预览区域固定高度并允许纵向滚动，避免 case 卡片被长回答撑爆。
+
+## 文案规范
+
+- 必须使用用户可读别名，如 `0403RL`、`baseline`，不要在正文中反复暴露长版本号。
+- 避免把“决定性样本”“连贯性加权”等术语放在结论层；若必须出现，需解释口径。
+- 原因总览必须写原因，不要只列题目。
+- 结论要服务决策：上线、暂缓、继续观察或需要定向修复。