Printable HTML Skill

供支持 skill 的 AI agent 使用，基于 Tailwind CSS Typography 生成可编辑、可打印的 HTML 报告、方案和长文档。颜色集中维护，内容自然分页；先用至少五页的样式样本确认视觉效果，再填正式内容。主要执行和打印验收平台是 Windows + Google Chrome。

让正在使用的 agent 添加 skill

将本 README 或仓库链接交给正在使用的 agent，发送下面的指令即可。由 agent 根据自身的 skill 加载与注册机制确定安装位置和使用方式。

请读取这个仓库的 README.md 和 printable-html/SKILL.md，
将 printable-html skill 添加到你当前使用的 skill 系统：
https://git.internal.physical-law.cn/qiaoling/html_skill.git

请根据你自身的加载、注册和作用域机制完成添加，保留整个 skill 目录，
检查安装完整性，并告诉我实际安装位置、作用范围和如何使用。
如果存在同名 skill，请先比对，保留已有定制，避免重复嵌套安装。
如果你没有持久安装机制，请如实说明，并在当前任务中读取 SKILL.md 使用。

给执行添加操作的 agent

1. 阅读本 README 和 SKILL.md，根据宿主环境实际提供的能力确定添加方式、目标位置以及项目或个人作用域；沿用用户已指定的范围，不假定统一的安装路径。
2. 从仓库获取整个 printable-html/ 目录，保留 SKILL.md、scripts/、references/、assets/、toolchain/、依赖锁文件和许可证。只复制 SKILL.md 无法使用配套脚本和资源。
3. 按自身机制完成目录放置及必要注册。若目标已有同名 skill，先比对内容，保留已有定制，避免重复嵌套目录。
4. 检查入口可读、相对资源路径正确、脚本与基础 CSS 齐全，并通过自身支持的方式确认能识别或读取这个 skill。添加 skill 与安装可选构建依赖是两个步骤，按本次任务需要准备运行环境。
5. 向用户报告实际位置、作用范围、调用方式及尚缺的运行能力。没有持久安装机制时，可以显式读取 SKILL.md 在当前任务中执行，但应说明这种使用方式不会完成持久安装；没有执行打印检查时也不能声称打印已验证。

Skill 名称为 printable-html，入口是 printable-html/SKILL.md。添加过程不依赖特定 agent 的界面元数据；加载目录、注册配置和调用语法由对应 agent 自行适配。

如何使用

添加后，向正在使用的 agent 发送：

请使用 printable-html skill 制作项目报告。主要组件是标题、段落、表格和图片，
风格简洁，主色深绿色。请先制作至少五页的样式样本，用 Windows Chrome
打印后展示 PDF 页面预览，等待我确认，再填写正式内容。

流程中会先确认组件、图片和视觉需求，保存命名模板，再展示真实打印 PDF 及页面图片。必须等用户确认样式后才填正文；正文完成后再次检查打印并确认，再导出分享文件。新增组件或更改样式时会返回设计与确认步骤。

模板默认保存在当前项目 ./html/templates/{template_name}/。下次可说“使用「模板名称」模板”，skill 会先在当前项目的这个目录查找名称和别名。模板可以复用，示例正文不会作为正式报告内容沿用。

每份报告默认放在 ./html/reports/{report_name}/：

层次	文件	用途
第一层	source.html，以及外联的 styles/、可选 scripts/、assets/	内容编辑入口；HTML 无内联样式和脚本
第二层	deliverables/standalone.html	完全离线的单文件，双击打开即可分享和打印
第三层	deliverables/minimal.html	编译、移除未使用样式并压缩后的离线单文件

以后修改第一层并重新导出第二、三层。图片、图标和所需字体一并内嵌到分享文件，打开成品不需要 Python、Node 或网络。没有可用编译工具链时交付第二层，并说明第三层未生成。

运行环境

• 主要验收环境：Windows + 本机安装的 Google Chrome。 默认 A4 纵向、100% 缩放、启用背景图形、关闭浏览器自带页眉页脚。
• Python 3.10+：初始化模板和生成第二层，仅使用 Python 标准库。已有预编译的 Typography 基础 CSS，无须先安装 npm。
• 可选 Node.js 20.19+ 和 npm：生成第三层、重新编译 Tailwind，以及用 Chrome 自动打印 PDF 和渲染页面预览。安装工具链需要下载依赖；成品不需要这些工具。

工具链按需安装。将下面路径替换为实际安装位置和 Python 可执行文件：

$SkillDir = 'C:\path\to\printable-html'
$Python = 'C:\path\to\python.exe'
& $Python --version
npm.cmd ci --prefix (Join-Path $SkillDir 'toolchain')
$env:PRINTABLE_HTML_PYTHON = $Python
$env:PRINTABLE_HTML_TOOLCHAIN = Join-Path $SkillDir 'toolchain'

Windows 使用 npm.cmd 可避免 npm.ps1 的执行策略问题。不要混用 Windows 和 WSL 的运行时或依赖目录。安装缺失或打印工具不可用时，skill 应说明实际限制，不将未执行的检查标为通过。

详细命令见 构建与离线交付，分页和完整性检查见 打印验收。

维护与复测

更新 skill 时保留完整目录结构。修改样式、导出或打印逻辑后，在 Windows 原生 PowerShell 中运行测试；下面沿用上面的环境变量：

& $Python -m unittest discover -s (Join-Path $SkillDir 'scripts\tests') -p 'test_*.py'
node --test (Join-Path $SkillDir 'scripts\tests\test_build_minimal.mjs') (Join-Path $SkillDir 'scripts\tests\test_compile_typography.mjs') (Join-Path $SkillDir 'scripts\tests\test_print_paths.mjs')
$RunDir = Join-Path (Get-Location) ('validation\windows-' + (Get-Date -Format 'yyyyMMdd-HHmmss'))
node (Join-Path $SkillDir 'scripts\tests\windows_acceptance.mjs') $RunDir
$ImageRunDir = Join-Path (Get-Location) ('validation\image-table-' + (Get-Date -Format 'yyyyMMdd-HHmmss'))
node (Join-Path $SkillDir 'scripts\tests\windows_image_table.mjs') $ImageRunDir

验收脚本要求新的输出目录，生成 result.json、PDF 和逐页预览，用于比较三层文件及修改内容后的分页。图片表格专项测试覆盖 2 列 × 8 个数据行、16 张图片的跨页打印，以及换高竖图、增加文字后的重排。自动检查后仍需查看页面，检查边框、表头、图片及内容完整性；Chrome PDF 验收不等同于物理打印机验收。

validation/ 和 .cache/ 是本地验证输出，不提交到仓库。可复现的测试源码保存在 printable-html/scripts/tests/。