Token 报告渲染器

概述

读取一个本地 Excel（.xlsx） 文件，按 PCG 公共事务部 7月新版「Token 使用诊断与管理建议」的样式，渲染成单文件 HTML 报告。报告含：头部 + KPI 卡 + 职族拆分 + 各中心柱状图 + 逐人使用强度 + 方案对比 + 推荐方案 + 70% 额度缺口 + 6月预估更新 + 部门沟通话术 + Footer。

整套样式、组件结构封装在 assets/template.html，渲染逻辑在 scripts/render_token_report.py，数据规范在 references/data_schema.md，组件清单在 references/components.md。

何时使用

用户说"生成/渲染/出 PCG Token 报告"。
用户提供一份 token 用量 .xlsx，要看 HTML 版的诊断报告。
用户已有 assets/sample_token_data.xlsx 模板，要换一批数据再生成。

不适用：

通用数据可视化报告（用别的 skill，如 hr-design-refs）。
不在 PCG 公共事务部场景下的报告（本 skill 样式是 PCGPA 的 6 章节版式）。

工作流程

检查输入：
- 用户给的是 .xlsx（多 Sheet）→ 走完整流程。
- 用户只贴了一份 Excel 截图 / 一段描述 → 先用 python3 scripts/init_sample_data.py 生成模板，提示用户在 Excel 里填数，再渲染。
- 用户只给了 CSV → 提示 CSV 只能渲染 meta 表部分信息，建议改成 .xlsx。
确认数据：
- 让用户打开 assets/sample_token_data.xlsx 对照结构（也可直接说"按模板的 sheet 名和列名填"）。
- 数据量大时，先检查 sheet 是否齐全（缺哪个章节）：必填 meta / kpis / byfamily / bycenter / persons，推荐 overage / schemes / standard，可选 overage_est / scripts。
执行渲染：
```
python3 scripts/render_token_report.py <input.xlsx> [output.html]
```
- 默认 output.html = 同目录同名 .html。
- 渲染成功后提示用户用 preview_url 打开预览。
展示结果：
- 在 IDE 内置浏览器中预览 HTML（preview_url 工具，url = file:///<绝对路径>）。
- 用户确认后交付；如要改文案/数据，回第 1 步。
如果用户改了数据要重新渲染：再次执行第 3 步；模板和数据规范不变。

资源

scripts/

render_token_report.py — 核心渲染脚本（读 xlsx → 拼 HTML）。
init_sample_data.py — 生成示例 Excel（脱敏自 PCG 公共事务部 7月版）。

assets/

template.html — 完整 HTML 模板，含所有 CSS 与组件结构。
sample_token_data.xlsx — 示例数据（结构与真实 PCG 报告 1:1）。

references/

data_schema.md — Excel 字段规范、Sheet 列表、字段语义、命名提示。
components.md — 组件库说明（CSS 变量、class、颜色语义、自定义方法）。

快速开始（给用户的对话模板）

我用 token-report-renderer 给你出一份 HTML 报告。

先看一下模板文件结构 → assets/sample_token_data.xlsx

把数据按 sheet 填好（参考 references/data_schema.md）

跑一行命令：python3 scripts/render_token_report.py 你的数据.xlsx

浏览器打开同名 .html 即可查看

渲染结果示例

打开 /tmp/test_token_report.html 可看效果：完整 6 章节、4 张 KPI、2 行职族拆分、4 中心柱状图、85 人使用强度表、2 方案对比、推荐卡 + 标准对比卡 + 缺口表 + 6月预估表 + 沟通话术 3 条。

验证（自检）

每次渲染完做这 3 步：

打开 HTML，检查头部 H1 + 4 张 KPI 卡 + 6 章节标题是否齐全。
逐人列表的行数 = persons sheet 的行数。
缺口表缺口数字前不出现 ++（修复了 overage_est 中硬编码 + 的 bug）。

已知限制

仅支持 3 个月度（M1/M2/M3），不支持 4+ 月。
不做权限控制：拿到 .xlsx 就能渲染。
样式绑定 PCG 公共事务部场景；其他部门用需手动改 CSS 变量。