# 复核 HTML 回归冒烟守门 - id: `review-html-regression-smoke` - kind: `diagnostic-tool` - risk: `low` - value: `high` ## 1.1 摘要 这个主题有效：多个 session 里反复出现复核 HTML 的产物定位错误、对话展示降级、标签编辑面板缺失和解决率口径回归。它适合沉淀成一个发布前/重生成后的冒烟诊断工具，用稳定检查项守住复核页面的核心能力。 ## 1.2 证据 | session_id | cwd | snippet | | --- | --- | --- | | 019dfc7b-f02b-7083-950d-237f0321ea58 | ~/Documents/product-bu | user: 我之前做过一个html看用户对话的东西，帮我打开。随后指出“不是这个”，说明历史分析 HTML 没有可检索的产物索引，agent 先打开了错误页面。 | | 019dfc7b-f02b-7083-950d-237f0321ea58 | ~/Documents/product-bu | assistant: 找到另一个更像“看用户对话”的页面：商品域最终体系_生命周期映射_session复核_2026-04-28_v1.html，它有 messages_readable 和 session 复核卡片。 | | 019dfd90-dc67-7f03-bfd8-c23ab364be52 | ~/Documents/job-bu | user: 你怎么把这里的对话展示弄没了。assistant: 底表里的 messages_readable 没丢，是我重生成 HTML 时沿用了脚本里的简化 transcript 样式，变成 USER/AGENT 块。 | | 019dfd90-dc67-7f03-bfd8-c23ab364be52 | ~/Documents/job-bu | user: 我之前 html里能修改case的标签分类，现在这个功能没了。assistant: 服务端保存接口还在，问题是前端模板里确实没有编辑面板了。 | | 019dfc7b-f02b-7083-950d-237f0321ea58 | ~/Documents/product-bu | assistant: 解决率变成 0 的原因是筛选未解决后，汇总表之前用筛选后的集合重算解决率，分子已解决数全是 0；已改成解决率按全量口径显示。 | ## 1.3 拟议改动 1. 新增工具入口 `/Users/bytedance/Documents/job-bu/data-analysis-workspace/tools/review_html_smoke.py`。输入来源：待检查 HTML、生成脚本路径、源表 xlsx/csv、可选 baseline HTML 或 manifest。核心检查步骤：解析 HTML DOM 与内嵌数据，确认 `messages_readable` 或等价对话字段被渲染为可读多轮对话，确认 session 复核卡片存在，确认标签分类编辑面板和保存接口入口存在，确认解决率按全量口径而不是筛选后集合计算。成功信号：所有必需 selector/字段/口径断言通过并输出 `PASS`；失败信号：缺 selector、字段未渲染、编辑入口缺失、指标分母异常或解决率全 0。落地路径：作为每次重生成复核 HTML 后的本地命令和 Night Gym 子检查运行。 2. 新增产物索引 `/Users/bytedance/Documents/job-bu/data-analysis-workspace/artifacts/review_html_manifest.jsonl`，并在 HTML 生成脚本末尾追加一条记录：文件名、绝对路径、生成时间、源表、主题标签、包含能力如 `conversation_view`、`label_editor`、`save_api`、`resolution_summary`。工具入口先查 manifest 再 fallback 到文件名/标题检索，降低“打开错 HTML”的概率。 3. 新增回归 fixture `/Users/bytedance/Documents/job-bu/data-analysis-workspace/tests/fixtures/review_html_smoke_cases.yml`：至少包含一个有 `messages_readable` 的 case、一个可编辑标签 case、一个未解决筛选但全量解决率非 0 的 case。核心检查步骤用 Playwright 或静态 DOM 解析双模式执行；成功信号是 fixture 生成出的 HTML 与 baseline feature contract 一致。 4. 新增 skill 文档 `/Users/bytedance/.codex/skills/review-html-regression-smoke/SKILL.md`，规定处理“复核 HTML / 看用户对话 / 标签编辑没了 / 解决率不对”时先跑 smoke，再解释字段来源。建议补充学习概念：feature contract、DOM smoke test、artifact manifest、aggregation denominator invariant。 ## 1.4 示例 ## 诊断流程样例 ### 入口 ```bash python /Users/bytedance/Documents/job-bu/data-analysis-workspace/tools/review_html_smoke.py \ --html /Users/bytedance/Documents/job-bu/data-analysis-workspace/projects/xxx/session复核.html \ --source /Users/bytedance/Documents/job-bu/data-analysis-workspace/projects/xxx/session底表.xlsx \ --manifest /Users/bytedance/Documents/job-bu/data-analysis-workspace/artifacts/review_html_manifest.jsonl ``` ### 检查表 | 检查项 | 输入来源 | 成功信号 | 失败信号 | | --- | --- | --- | --- | | 产物定位 | manifest + HTML title | 命中目标主题且路径唯一 | 多个相似 HTML、标题不含复核主题 | | 对话展示 | 源表 `messages_readable` + DOM | 页面存在可读多轮对话卡片 | 只剩 USER/AGENT 简化块或空白 | | 标签编辑 | DOM selector + JS handler | 存在分类编辑面板和保存按钮 | 保存接口存在但前端入口缺失 | | 解决率口径 | 源表全量集合 + 当前筛选集合 | 未解决筛选下仍展示全量解决率 | 解决率因筛选未解决被重算成 0 | ### 示例输出 ```text PASS artifact: 商品域最终体系_生命周期映射_session复核_2026-04-28_v1.html PASS conversation_view: 20/20 sampled sessions rendered from messages_readable PASS label_editor: edit panel + save endpoint detected FAIL resolution_summary: displayed solved_rate=0 but full_dataset solved_rate=63.4% 建议：修正汇总计算函数，解决率分母固定使用全量 dataset；筛选只影响列表，不影响全局摘要。 ``` ### 失败后的落地动作 1. 如果产物定位失败，先更新 `review_html_manifest.jsonl`，不要继续猜文件名。 2. 如果对话展示失败，回到 HTML 模板恢复 `messages_readable` 卡片渲染，不改源表。 3. 如果标签编辑失败，恢复编辑面板 selector 与保存按钮，再用本工具重跑。 4. 如果指标口径失败，检查聚合函数的分母来源，保证全量口径和筛选口径分离。