| name | measure-utilization |
| description | 测量 HTML 演示文稿每页的空间利用率,找到过于空旷的页面。使用 Playwright 渲染 + 网格采样方法。当用户想检查页面密度、找空白页面、优化页面布局或询问"空间利用率"时使用。 |
空间利用率测量
对 HTML 演示文稿(如 Harness Deck)的每一页,用 Playwright headless Chromium 渲染后网格采样,通过 elementFromPoint 检测每个采样点是否命中有意义内容(有背景/边框/文字的元素,排除透明容器 div),计算空间利用率。
运行方式
python "<workspace>/.github/skills/html-deck-pipeline-skill/internal-skill/measure-utilization/_measure_utilization.py" <path/to/deck.html> [--threshold 30] [--json] [--parts parts.json]
html:HTML 讲稿文件路径(必填)
--threshold / -t:利用率阈值(%),低于该值标记为 <<<。默认 30%
--json:输出原始 JSON 而非格式化报告
--parts:可选的 JSON 文件,定义幻灯片章节分组,格式见下方说明
示例
python "_measure_utilization.py" 20-html/v-01/DECK-HARNESS-合并.html
python "_measure_utilization.py" 20-html/v-01/DECK-HARNESS-合并.html -t 25
python "_measure_utilization.py" 20-html/v-01/DECK-HARNESS-合并.html --parts parts.json
python "_measure_utilization.py" 20-html/v-01/DECK-HARNESS-合并.html --json
章节分组文件格式 (--parts)
[
{"name": "ch01-问题", "start": 0, "end": 2},
{"name": "ch02-body", "start": 3, "end": 5},
{"name": "ch03-五维展开", "start": 6, "end": 17},
{"name": "ch04-总结", "start": 18, "end": 20}
]
name:章节名称
start:该章节第一页的索引(从 0 开始)
end:该章节最后一页的索引
不提供 --parts 时,报告中不显示章节列,结果仍然有效。
测量方法
- 逐页渲染:Playwright 打开 HTML 文件,每次只显示一页(
display:flex)
- 网格采样:40×40 网格(1600 个采样点)均匀覆盖整个 slide
- 内容判定:每个采样点用
elementFromPoint(x, y) 获取顶层元素,沿 DOM 树向上查找,检查是否存在有意义的元素:
- 有非透明背景色
- 有可见边框
- 是内容标签(h1-h6, p, table, img, code, pre, blockquote, button, strong, em 等)
- 是包含文字的叶子节点且非纯布局标签(div, section, span 等)
- 利用率计算:命中内容的采样点 / 总采样点 × 100%
结果解读
# | Util | Flag | Part | Slide Title
----------------------------------------------------------------------------------------------------
6 | 17.9% | <<< | ch03-五维展开[0] | 📋 五个方案维度
0 | 21.1% | <<< | ch01-问题[0] | 封面
10 | 31.5% | | ch03-五维展开[4] | 信息压缩
...
5 | 65.7% | | ch02-body[2] | 约束层 vs 认知层
< 30%:标记为 <<<,页面严重偏空
30-50%:中等利用率,有优化空间
50-65%:良好利用率
> 65%:密集页面(演示文稿中通常不希望超过 70%,会显得拥挤)
注意:封面/导航/章节分隔页通常利用率偏低(10-25%),这是设计预期,不算问题。
脚本位置
测量脚本位于本技能目录:_measure_utilization.py
依赖
playwright(需 pip install playwright && playwright install chromium)
输出格式要点
- 结果按利用率从低到高排序
- 显示页码(整体索引)、所属章节、章节内页码(提供
--parts 时)
- 稀疏页面统计 + 设计豁免提示