dashboard-reporting

name	dashboard-reporting
tier	meta-meta
description	生成 HTML 仪表盘，让开发者用户可视化核查结果、系统进度、质量指标。在测试轮次完成、生产批次跑完、开发者用户想看可视化报告，或他们明确要求时使用。仪表盘是自包含的 HTML 文件。**仅在确实有"值得可视化的东西"时使用** —— 不要当成默认交付物。日常状态汇报用 KC 的 TUI 即可。HTML 仪表盘是对直接汇报的补充，不是替代。

Dashboard Reporting

仪表盘只是众多渠道之一 —— 而且并不总是最经济的那个 —— 让开发者用户了解情况。KC 在 TUI 里已经能直接汇报状态；HTML 仪表盘存在的理由是值得可视化看的东西：分布、时间线、热力图、并列对比、可钻取的表格。

不要把生成仪表盘当成"满足这条 skill"的打卡项。把它当成开发者用户真要的交付物，或者一张图确实比读 TUI 输出 / JSON 更省时间的场景。

最低限 vs 锦上添花

开发者用户要仪表盘时，先做到最低限，能真带来价值再扩展。

最低限

一份够用的仪表盘的底线：

• 一个汇总头：总文档数，顶层 通过 / 失败 / 缺失 数。
• 一张按规则汇总的表：rule_id、准确率、pass / fail / NA 计数，可选的置信度列。
• 一份失败 case 的列表，用户能点开看详情（规则、抽取值、期望值、 comment）。

够发了。开发者用户能在 3 秒内回答"这一批健不健康，哪些规则出了问题"，最低限就达成。

锦上添花

下面这些只在数据或用户需求确实证明合理时才加：

• 置信度分布直方图（在置信度已经校准、用户在意分布形状时才有用）。
• 准确率随时间的折线图（只有累积了足够的历史能画出有意义曲线时才有用）。
• 按产品类型 / 按签发方的分项（语料有明显分群时才用）。
• 成本指标（成本是当下关切时才用，否则跳过）。
• 钻取导航（汇总 → 规则 → 文档）。
• 内嵌反馈控件（点击改值、一键标记错误）。

不要为了显得周到而加一节。一张空的"置信度分布"图（背后根本没有校准过的数据）比没有图更糟。

仪表盘类型（什么时候用哪种）

结果仪表盘

处理完一批文档后。上面的最低限通常就够了。

进度仪表盘

按需生成，展示系统跨阶段演化。每条规则的生命周期状态、规则目录表、演化时间线。多在开发者用户想要"现在到哪了"的中段快照时有用。

质量仪表盘

QC 复核周期结束后。准确率趋势、抽样率走势、待处理标记、成本。在 QC 已经跑了足够多周期、能画出趋势时才有用。

如果当下只有一种对开发者用户真正有帮助，就只做那一种。不要默认三种都生成。

反馈采集（在适用时是锦上添花）

当仪表盘要给会真去复核结果的人看时（开发者用户、终端用户、领域专家），加上反馈控件。当仪表盘只是开发者用户构建过程中的自查工具时，反馈控件通常多余 —— 它假装存在一个用户根本不打算走的流程。

开发者用户反馈

能看到完整结果细节。有用的控件：

• 字段级修正：点抽取值，给出正确值。
• 结果覆盖：把 pass 改为 fail（或反过来），带理由。
• comment：自由文本注释。

终端用户反馈

只能看到简化结果。有用的控件：

• 一键标记错误。
• comment：简要文本说明。
• 严重性指示：关键 / 重要 / 次要。

反馈即 ground truth

用户报错就是 ground truth，覆盖 agent 判定和 worker LLM 的输出。流转：

1. 通过仪表盘提交 → 存为结构化记录。
2. Schema：{result_id, trace_id, reporter_role, feedback_type, original_result, corrected_value, comment, timestamp}。
3. 记录喂入 evolution-loop 作为已确认的失败。
4. 后续仪表盘里呈现反馈趋势（纠正率随时间变化、最被报错的问题、纠正率最高的规则）。

技术约束

自包含的 HTML，内嵌 CSS / JavaScript。

• 零外部依赖。无 CDN、无 npm、无服务器。全部内联。
• 不依赖服务器。开发者用户双击 HTML 文件即可打开。
• 响应式布局。桌面和移动端都能用。
• 暗 / 亮模式：遵循系统偏好或提供切换。

图表用内联 SVG，或把轻量图表库以 <script> 标签内联。

数据来源

仪表盘读取：

• Output/ 的核查结果。
• logs/ 的演化与测试历史。
• versions.json（或 git log）的当前系统状态。
• QC 复核记录（与 Output/ 并列存放）。

生成脚本应接收输入路径，输出单个 HTML 文件。

生成时机

什么时候生成：

• 测试轮次完成，并且有足够数据值得可视化时。
• 生产批次结束，并且开发者用户想看可视化时。
• QC 复核周期完成时。
• 开发者用户明确要求时。

不要在每个小事件后都自动生成 —— 仪表盘会迅速堆积，用户大部分都不会打开。不确定时，问一下用户（"要不要我生成一份仪表盘？"），而不是不问就生成。

生成的仪表盘存到 Output/dashboards/，文件名带时间戳留作历史。

设计原则

• 汇总在前。开发者用户应能在 3 秒内看清健康状况。
• 按需钻取。汇总 → 规则级 → 文档级。不要一次性堆细节。
• 配色：绿色 = 通过/健康，红色 = 失败/严重，黄色 = 警告/需关注。简单且通用。
• 可行动。每条标记的问题都建议下一步该做什么。

scripts/generate_dashboard.py 是一个起步脚本。按具体场景改写 —— 当一半 section 都没有内容可放时，删掉那一半。一份能回答用户问题的小仪表盘，胜过一份用户不需要的"全面"仪表盘。

与 TUI 汇报的分工

KC 的 TUI 本身就支持在运行时做丰富的状态汇报。TUI 用来：

• 持续的进度叙述。
• 每个阶段的小结。
• 快速的"刚才发生了什么"。
• 一切能用几行文字说清楚的事。

HTML 仪表盘用来：

• TUI 容纳不了的视觉产物（分布、图表、可筛选表格）。
• 交付给非 KC 用户（开发者用户事后复核、终端用户群体）。
• 需要持久保留、回头再看的记录。

不确定时优先用 TUI。一条用户已经在读的简短状态消息，胜过一份还要他去打开的仪表盘。