zfl-audit-charts — 审核结果可视化看板（共享能力）

用途

把审核/测试类技能产出的 JSON 结果，聚合为一张自包含的 HTML 看板：

• 顶部指标卡：项目数 / 文件数 / 项目通过 / 项目不通过
• 饼图：项目结论分布
• 柱状图：文件结论分布
• 趋势图（≥2 个审核日期时）：按日期的通过/不通过/待核查堆叠
• 明细表：逐文件 文件 / 类型 / 日期 / 结论
• 整改闭环工作台（audit 模式，v1.11.0）：当审核 JSON 含 files_audited[].issues[] 时，在明细下方渲染可交互面板——每条问题状态（待整改→已整改→已复核）可点击流转、localStorage 持久化、JSON 导入导出、未闭环红横幅；支持溯源/证据链/预测四字段（详见 references/json_contract.md）
• 同时落 audit_dashboard_data.json（结构化聚合，供二次处理）

默认扫 ./test-output，输出 ./test-output/audit_dashboard.html

指定目录

离线模式（需 chart.umd.js 与脚本同目录）

切换色系主题（支持：indigo, blue, green, orange, rose, gray）

• 仅依赖 Python 标准库；图表由 Chart.js 4.4.1 渲染（默认 CDN，可用 --no-cdn 走本地）。
• HTML 用「纯模板 + __TOKEN__ 占位符 .replace()」渲染，规避 f-string 嵌套花括号转义坑。

版本要点

v1.14.0 — verdict 判定条（报告结论先行思路反哺）

audit 模式看板 Hero 下方新增 verdict 判定条：主判定取项目级 overall_conclusion 多数派（通过/部分通过/不通过，绿/紫/红语义色），右侧显示首项目 confidence 置信度，底部渲染顶层可选 verdict_note 为「诚实声明」副行（如"真机/实物未实测前不判通过"）；无 overall_conclusion 时整条隐藏，无 verdict_note 时不显示副行，老 JSON 零改动兼容。来源：launch-check 报告「结论先行」样式对比反哺（2026-09-25 用户拍板双向借鉴 A/B）。

v1.13.0 — 数据时点声明（首屏徽章 + 页脚双处）

看板首屏头部新增 📅 数据截至：YYYY-MM-DD 徽章（药丸样式，半透明浮于标题栏），页脚补充 数据范围：最早~最晚。数据来源由 aggregate() 自动推断：

• audit 模式：从项目级/文件级 JSON 的 audit_date / date / timestamp 字段提取
• ops 模式：优先取 period.to，兜底取 data_ts 推断结果

适用场景：时效性审核数据（付款/竣工/测试报告）、运营日报/周报、盯标看板等——读者一眼可见数据时点，避免"看到旧数据误判"的幻觉风险。

数据契约兼容性：现有 JSON 无需任何改动，data_ts 由脚本自动推断；若 JSON 含 period 字段（ops 模式），自动用作数据时点。

v1.12.1 — 原生 Canvas 深色对比度根因修复

内置 demo 与回归自检

一键示例（--demo，v1.9.6）

改样式/加组件后，先用内置示例快速验证产物是否正常：

# 1) 跑内置 demo（自动隔离到临时目录，避免跨模式误扫）
python <skills_root>/zfl-audit-charts/scripts/make_dashboard.py --demo

# 2) 换色系主题 + 离线模式（chart.umd.js 与脚本同目录时可用）
python <skills_root>/zfl-audit-charts/scripts/make_dashboard.py --demo --theme indigo --no-cdn

# 3) 回归冒烟自检（改 make_dashboard.py 后必跑）
python <skills_root>/zfl-audit-charts/tests/smoke_test.py

示例 JSON 固化在 <skill_dir>/scripts/samples/（ops_sample.json / audit_sample.json），已含 gauge(note) + timeline(current/collapse_after) 关键能力，作为可运行契约（从脚本同目录读取、隔离到临时目录避免跨模式误扫，支持 --theme / --no-cdn）。

回归冒烟自检（tests/smoke_test.py，v1.10.0）

改动 make_dashboard.py 后，跑回归自检作为第一道安全网，防止模板替换残留（__TOKEN__）、gauge/timeline/note 失效、渲染崩溃等回归：

校验项：进程退出码、产物体积、无 __TOKEN__ 残留、输出无 [ERR]/Traceback、各 demo 关键能力标记命中（ops：gauge + timeline + current 高亮；audit：gauge + note 说明文字）。退出码 0=全部通过，1=存在失败项，可直接接 CI 门禁。

> 回归纪律（v1.13.x 固化 · 标记对齐）
> tests/smoke_test.py 的 EXPECTED_MARKERS 每个标记必须是该模式核心能力的稳定键，且与上方能力契约逐字对齐，禁止用 demo 里碰巧存在的任意文案兜底。
> - 反例（已修）：ops 曾用 "会议健康度"（某 KPI 标签）当标记，gauge 评分环回归时 smoke 仍 PASS——典型假安全网。
> - 正例：ops = gauge + timeline + 当前；audit = gauge + 建议 ≥80 + 整改闭环 + 证据链 + 总体判定（v1.14.0 verdict 判定条）。
> - 新增/修改能力时，同步更新标记与本文契约，二者必须一致；改完跑一句 python tests/smoke_test.py 确认全绿。

> 已知限制 / 改进方向（自动化触发的精细化）
> 已把本自检接成自动化任务 automation-1784674102263（每日 09:00 定时跑 tests/smoke_test.py 并报告 PASS/FAIL）。当前 WorkBuddy 自动化系统不支持"文件改动即触发"监听器，因此只能定时兜底、无法做到"改完 make_dashboard.py 立即复测"——用户手动改完仍应自己跑一句 python tests/smoke_test.py 即时验证。改进方向：若未来平台支持 on-change / 文件监听触发，将该任务从 FREQ=DAILY 改为改完即测，实现真正的即时回归门禁。（同步记录在 MEMORY.md 待办区）

逐页截图视觉验收（真实渲染门禁，v1.13.3 新增）

tests/smoke_test.py 是静态机检——只验证退出码/产物体积/__TOKEN__ 无残留/[ERR] 无输出/能力标记命中，不验证真实渲染。HTML 看板在浏览器里是否"真好看、真可读、没被截断"，静态检查测不出。

吸收 zfl-common/references/html_render_visual_gate.md（视觉真实闸 SSOT）的纪律：本技能看板在交付前须过逐页截图视觉验收——

• 触发：audit 模式长明细表（>1 屏）、ops 多项目对比（跨项目柱图）、含 gauge/timeline 的 KPI 卡、导出 PDF 前，必须逐页/逐区截图核对；
• 验收要点：① 分页/截图时正文末行是否被页码或页脚吃掉（作者踩坑点：静态全绿 0 fail，截图发现页码吃末行半行）；② 深色模式（prefers-color-scheme:dark）文字/网格对比度是否可读；③ 长表是否溢出容器、横向滚动是否破坏布局；④ 色系切换后图表是否同步重建（不残留旧色）；
• 执行：本机 Chrome/Edge 无头 --screenshot 或人工浏览器打开逐页核对；无浏览器时降级为 WARN 提示（与 --export pdf 同策略），不阻断但须在交付说明标注"未经逐页视觉验收"。

> 纪律对齐：静态 smoke 全绿 ≠ 可交付。真实渲染验收是生成后"真实闸"，与 ppt-studio 的"样张先行（方向闸）+ 逐页截图（真实闸）"双闸同源。

运营指标看板（ops 模式）

解决缺口：原脚本只吃「审核/测试 JSON」（verdict 驱动），但数据分析场景（如监理工作助手 H 模块）要的是运营过程数据（问题数、整改率、人员工作量、进度偏差、隐患等级、部位×专业热力）。ops 模式用声明式 metrics 列表 + KPI 卡补齐，复用 17 套主题与零依赖特性。

调用方式：

自动检测：目录含 ops JSON 即走 ops 渲染

显式指定

ops 数据契约（满足 dashboard_type:"ops" 或含 metrics 数组即被识别）：

• kpis：顶部指标卡，trend 正数绿↑/负数红↓；设 display:"gauge"（或 type:"gauge"）则用零依赖 SVG 评分环渲染，支持 max（默认 100）、color（覆盖自动三档配色）、note（gauge 副标题说明文字，如"建议 ≥80"，v1.9.5+）。
• metrics[].type：line / bar / doughnut / grouped_bar / heatmap / timeline（未知类型降级为提示卡）。timeline 支持 collapse_after（折叠阈值，默认 6，0=不折叠，v1.9.5+）与 items[] 的 level(low/mid/high 着色)、current(true→脉冲高亮+「当前」徽标)。完整字段与可运行示例见 references/json_contract.md。
• line/grouped_bar 用 x+series[]（多序列）；bar/doughnut 用 buckets[]。
• heatmap 用 CSS grid 渲染色块，不引入任何 Chart.js 插件，保持零依赖。
• 颜色/主题/明暗自适应/色系选择器全部复用审核看板，视觉一致。
• 对齐产品分级：建议 P1（接 OCR 时）预埋，P2 成熟 H1/H3/H4/H2；不进 MVP。

ops 多项目 KPI 对比

--mode ops --compare proj.json 把多个项目的 ops JSON 横向对比，输出「KPI 跨项目矩阵表 + 每 KPI 跨项目柱图」，服务 H2 多项目驾驶舱。manifest 格式：

• 每个 dir 下含 ops JSON（同单项目 ops 契约），脚本用 scan_ops + aggregate_ops 聚合。
• KPI 取并集（某项目缺某 KPI 则该格显示 -），柱图按项目着色。
• 复用 17 主题与色系选择器，视觉与单项目一致。
• 配套 --export docx|both：docx 输出 KPI 跨项目矩阵表（与 HTML 矩阵一致），pdf 复用通用无头打印。单项目 ops 看板同样支持 --export。

看板导出 PDF / Word

--export docx|pdf|both 在生成 HTML 后再导出，零 Python 依赖（仍不引入 pip 包）：

• docx（纯标准库）：用 zipfile + 手写最小 OOXML 生成 .docx，含 KPI 摘要 + 各指标数据表（热力图按行列矩阵、折线/分组柱按维度×序列）。审核看板导出为「结论分布 + 文件明细表」。适合产品「导出汇报」需求。
• pdf（本机浏览器）：检测本机 Chrome/Edge（--headless=new --print-to-pdf），把渲染后的图表一并打印。未装浏览器时优雅降级为 WARN 提示，并建议用浏览器「打印→另存为 PDF」，不阻断流程。
• 导出文件名与 HTML 同基名（.docx / .pdf），失败不影响已生成的 HTML。

ops 单项目导出 Word + PDF

audit 看板导出 Word（纯标准库，随处可跑）

H 模块数据分析 · 端到端接线示例

scripts/h_module_sample_pipeline.py 演示产品 H 模块（数据分析）的输出层如何把"监理工作业务数据"喂给本技能，跑通完整链路：

原始工作记录契约（单日/单次一份 JSON）：

跑通（含示例数据生成）：

聚合产出覆盖全部 5 类图表 + KPI：问题趋势（line 折线）、隐患等级（doughnut 环形）、人员工作量（柱状图）、进度对比（grouped_bar 分组柱）、部位×专业热力（heatmap 热力图）、整改率/未闭环（KPI 指标卡）。

对接真实产品：复制 aggregate_records() 的聚合与 ops 契约构造即可，把"从日志/通知单抽取"替换为你的实际数据源；下游 make_dashboard.py 零改动。对齐产品分级——P1（接 OCR 时）预埋，P2 成熟 H1/H3/H4/H2；不进 MVP。

培训运营看板 · 端到端接线示例

scripts/training_ops_sample_pipeline.py 演示企业培训体系（一线监理/施工）的运营与成效数据如何喂给本技能，跑通完整链路：

这是 ops 模式的培训域验证场景，复用 H 模块（监理工作助手）的聚合范式，证明声明式 metrics + KPI 卡能脱离"审核/测试 JSON"独立服务运营过程数据。

原始周报记录契约（单周/单次一份 JSON）：

ops 指标字典（指标 key → 培训含义）：

跑通（含示例数据生成）：

聚合产出覆盖全部 7 类指标 + 6 KPI：学习参与趋势、行为改善趋势、课程类别、隐患等级、各项目规范率、基线vs现状、部位×专业热力。

对接真实培训体系：把"培训侧" source 换成信通云学堂导出报表、"现场侧"换成监理日志/通知单/问题台账抽取（即 H 模块原始记录契约），保留 aggregate_records() 即可；下游 make_dashboard.py 零改动。基线值（默认 55/60/70）须由真实项目启动前抽样采集替换，不可用示例数字当目标。

数据契约（被扫描的 JSON 形态）

满足任一即被聚合：

1. 项目级（含 overall_conclusion 或 files_audited）：驱动饼图 + 趋势 + 明细
2. 文件级（单文件审核结果）：驱动柱状图 + 明细

> audit 顶层 kpis：项目级 JSON 可带 kpis 数组（字段与 ops KPI 完全一致），display:"gauge" 渲染零依赖 SVG 评分环，支持 note 副标题说明文字；无 kpis 时整行隐藏。完整契约与可运行示例见 references/json_contract.md。

verdict 归一化关键字：不通过 / 待核查(待查/读取失败) / 不完整(缺失) / 部分通过 / 需复测 / 证据不足 / 通过 / 其他。

与其他技能的关系

• 源自 zfl-telecom-completion-audit 评审整改，为其首次引入可视化层。
• 其他审核/生成类技能（如 pdca-verification-pattern、unicom-final-account）若需出图，
  在 SKILL.md 声明 package_dependencies: [zfl-audit-charts] 并调用本脚本，避免各写一套。
• 本技能是权威实现；各技能内部如需保留副本，应在副本顶部 @see 本技能并在升级时同步。

改进方向（规划中，未发布）

以下为 v1.4.0 之后拟推进的能力，按优先级排序。本技能目录即跨机续作的唯一可信源（用 zfl-skill-syncer 同步即可在另一台电脑继续）。

1. 打通自动调用（P1，最高优先）— 让看板成为审核流水线标准产出

• 目标：审核类技能（zfl-telecom-completion-audit / zfl-china-unicom-payment-audit / zfl-report-verifier 等）在收尾步骤强制调一次 make_dashboard.py，而不是"审完才知道要出图"。
• 实现方式（无需改脚本）：在调用方 SKILL.md 的「收尾/产出」步骤加入固定指令——输出审核 JSON 后、写报告前，用 execute_command 调用：
  make_dashboard.py 已支持标准数据契约（项目级 / 文件级 / 原始 JSON），调用方只需把 JSON 落到约定目录。
• 试点顺序：先接 zfl-china-unicom-payment-audit（案例库最规整，已有 approved/rejected 结构）→ 验证无回归 → 再推广到竣工/测试报告。
• 风险：调用方收尾步骤与看板耦合；须在试点技能内做端到端验证，避免引入回归。

2. 场景桥接 @scene#8 数据分析及可视化（P1）

• 核查结论：用宽松 frontmatter 提取 + 全字段枚举重扫 79 个自建技能，纠正了首轮"35 个无字段"的假象（首轮正则过严把一批带 tab/CRLF 的 YAML 误判为解析失败）。真实分布：① 复合式（trigger/triggers + 触发场景/trigger_scenarios）—— 41 个（含 zfl-confined-space-test-verify、zfl-china-unicom-payment-audit 等，即用户说的"触发词升级成场景触发"；注意 triggers 复数 / trigger_scenarios 是独立字段，别漏）；② 领域触发 type: domain + enforcement: suggest + priority: high —— 仅 1 个（zfl-telecom-cost-assistant）；③ 仅 trigger/triggers —— 4 个；④ 仅 description（无显式 trigger/场景字段，但 dispatcher 仍靠 description 匹配）—— 28 个；⑤ 无触发机制 —— 5 个（4 个 disable: true 的 WPS/知识库技能 + 1 个无 frontmatter 的 skill-absorption 工作流文档）。真正"无触发"的只有这 5 个，74/79 都有触发信号。 没有 scene/sceneTrigger 这类把技能绑定到原生 @scene#8 的配置字段。真正的"场景字段"是 触发场景:（场景语义描述），被 41 个技能用作给 skill-dispatcher 场景推断喂上下文，非配置式绑定。
• 可行做法（无需平台改造，P1 首选）：把本技能从"仅触发词"升级为"复合式"——在 frontmatter 新增 触发场景: 字段，描述"当用户需要把审核/测试结果 JSON 转成可视化看板、统计图表、跨源对比时使用"，与现有 trigger: 并存。这比单纯堆 description 关键词更稳，且对齐 41 个兄弟技能的主流形态。可选：若要更强硬的领域触发，可照搬 cost-assistant 的 type: domain / enforcement: suggest / priority: high（但会失去 trigger: 硬关键词，需评估）。
• 状态：frontmatter 已新增 触发场景: 字段（与 trigger: 并存，升级为复合式）。措辞对照 41 个兄弟技能风格，含"数据分析及可视化场景"字样。待另一台电脑复核措辞 + 实测调度器是否捞起。
• frontmatter 严格 YAML 清理：description: 改为 >- 折叠写法（与 16+ 兄弟技能一致）；原混在 frontmatter 内的版本笔记 + 数据契约 + verdict 归一化（line 19–44 预存在脏内容）已移出 frontmatter。归位方式：## 版本要点（v1.1.0~v1.4.0 亮点）置于 H1 标题下方；verdict 归一化（含 v1.4.0 新增的部分通过/需复测/证据不足）并入 body 已有的 ## 数据契约（被扫描的 JSON 形态） 章节（无重复）。现 yaml.safe_load(frontmatter) 通过，dispatcher 字段读取正常。
• 实测验证项（另一台电脑做）：进 @scene#8 数据分析及可视化场景，上传审核 JSON 说"出看板"，看加 触发场景: 后调度器能否稳定捞起本技能；命中则保留，未命中再补强 description 关键词。

3. 读者分层输出（P2）

--audience exec|expert 切换：管理层看结论 + 饼图，专家看明细 + 证据。对接现有 R13 置信度/证据机制。

4. 交互式仪表板（P3）

drill-down（点饼图扇区过滤明细表）+ 时间范围筛选。当前为静态 Chart.js。

5. 运营指标看板（ops 模式）— v1.5.0 已发布（原缺口，非原 1-4 路线）

吸收自 2026-07-21 监理工作助手产品头脑风暴：原脚本只吃审核/测试 JSON，无法服务 H 模块（数据分析）的运营过程数据（问题数/整改率/人效/进度偏差/隐患等级/部位×专业热力）。v1.5.0 已落地 ops 模式——声明式 metrics + KPI 卡 + line/bar/doughnut/grouped_bar/heatmap(CSS 零依赖)，覆盖 H1/H2/H3/H4/H5/E3/C3。复用 17 主题、明暗自适应、色系选择器；--mode auto 按内容自动检测。此能力不在原 1-4 路线内，属新增。

> 完整版本历史见 CHANGELOG.md。

约束与错误处理

• 本技能仅处理其声明范围内的任务，不越界执行未授权操作。
• 错误处理：输入不合法时返回明确错误说明，不静默跳过；依赖缺失时降级提示并给出替代路径。

自检与成功标准

• 成功标准：输出满足任务声明的全部要求，关键信息完整无遗漏，视为完成。
• 输出前自检：核对输出是否覆盖全部要求项、数据是否准确、格式是否符合规范。