| 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 的输出。流转：
- 通过仪表盘提交 → 存为结构化记录。
- Schema：
{result_id, trace_id, reporter_role, feedback_type, original_result, corrected_value, comment, timestamp}。
- 记录喂入
evolution-loop 作为已确认的失败。
- 后续仪表盘里呈现反馈趋势（纠正率随时间变化、最被报错的问题、纠正率最高的规则）。
技术约束
自包含的 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。一条用户已经在读的简短状态消息，胜过一份还要他去打开的仪表盘。
