hug-html

8种原子组件自由组合 + 3级约束, cell merging, two-level module system (base + composite), 7+ built-in templates, grid-aware visual editor, style presets, post-generation audit, user template save-as, Chinese error handling

→ 详见核心能力的渐进式文件索引

限制

• 本技能的能力边界分为支持场景、不支持场景和边界情况三类。
• 生成推广卡片 — 应用推广、活动宣传、产品介绍的毛玻璃卡片。触发词："生成一个 APP 推广 HTML 卡片"
• 生成信息面板 — 带表格、参数、二维码的信息展示面板。触发词："做一个带二维码和参数描述的 HTML"
• 生成可视化编辑模板 — 带 Ctrl+E 可编辑的 HTML。触发词："生成一个可视化编辑的 HTML 模板"
• 生成日历/周历仪表板 — 假日管理、年份控制、工日统计的交互仪表板。触发词："生成一个周历交互 HTML"
• 生成双端对比卡片 — 左应用右元服务/双实体的对比展示。触发词："生成一个双端推广卡片"
• 内容填充 — 自动/手动填充 data-field 标记的文字和图片。触发词："给这个 HTML 模板填充示例内容"
• 方案模板固化 — 将当前设计保存为可复用的用户模板。触发词："把这个模板保存为 my-card"
• 自由创作 HTML — AI 参考模块库直接编写自包含 HTML。触发词："帮我写一个毛玻璃风格的首页"

不支持的场景：

• 复杂前端应用 — 不支持路由/状态管理/API 调用（替代：手写 React/Vue）
• 多页面 HTML 站点 — 不处理页面间导航（替代：静态站点生成器）
• PDF / 图片输出 — 不直接生成图片或 PDF（替代：浏览器打印或截图）
• 外部 CSS/JS 框架集成 — 强调零外部依赖（替代：手动引入 CDN）
• 非网格布局的自由排版 — 基于 CSS Grid（替代：自由生成模式）
• 后端交互 — 纯前端 HTML，无后端能力。影响：数据持久化需额外方案。替代：搭配 Flask/Node.js

边界情况：

• 网格越界 — row/col + rowspan/colspan 不能超过网格总行列数。影响：CSS Grid 异常渲染
• 毛玻璃裁剪 — backdrop-filter 需要 overflow:hidden 容器
• JSON 模板路径 — --spec 支持绝对/相对路径和内置名，不存在有中文错误提示
• 文件编码 — 必须 UTF-8，其他编码会导致乱码
• 编辑模式兼容性 — Ctrl+E 需要 Chrome/Edge/Firefox，不支持 IE

触发条件

正向触发：

• "生成 HTML 模板" / "HTML template" / "hug html"
• "编辑 HTML" / "可视化编辑 HTML" / "visual edit HTML"
• "HTML 模块" / "HTML module library"
• "网格布局" / "grid layout" / "N×M 网格"
• "单元格合并" / "rowspan" / "colspan"
• 输出格式：自包含 HTML 文件（毛玻璃卡片风格）
• "我需要一个 APP 推广卡片，要有个二维码—可以用，支持"
• "帮我做一个带表格和参数配置的 HTML 面板—支持，用 data-table + param-panel 模块"
• "生成一个双端对比的推广页面—支持，用 header-dual + qr-dual"
• "这个模板我想保存下来以后用—支持，用 --save-as 固化"
• "给我生成的 HTML 加一个可视化编辑界面—支持，用 visual_editor.py"

否定条件：

• 不触发：用户仅询问 HTML 语法概念，无文件生成需求
• 不触发：用户明确请求其他特定技能

核心能力

📚 渐进式加载：本技能采用渐进式 MD 体系，SKILL.md 为入口（≤230行），详细内容拆分到 references/*.md 按需加载。

#	能力	说明
1	骨架结构	N×M 网格、行列数、单元格合并（rowspan/colspan）、gap 间距
2	骨架约束	3级约束（fill/fit/clip），递归传递到组件级别
3	组件体系	8种原子组件（text/image/icon/qrcode/table/divider/spacer/group），自由组合
4	组合逻辑	方向(row/column)、比例(ratios)、对齐(align)、8方向位置
5	方案模板库	内置 7+ 预置{骨架+组件+样式}组合 + 用户可自定义固化
6	样式预设	5 种内置风格：商务/科研/喜庆/丧事/技术，一键切换配色字体
7	基础编辑	每个文字元素独立控制：字体家族(8种)/字重(100-900)/字号(9-48px)/字色/透明度
8	图片编辑	点击输入 URL + 拖放文件替换，所有图片组件均支持
9	生成后审计	自动检查 HTML 结构完整性、标签平衡、图片属性、网格越界、渲染风险
10	统一接口	--export-interfaces 导出完整接口定义 JSON，大模型可直接理解
11	方案模板固化	--save-as <名> 将任意生成固化为用户模板，后续按名引用
12	自由生成模式	AI 参考组件库，理解需求确定骨架→组合组件→约束→生成→审计
13	参数约束	行列数 1-10, span≥1, gap 4-24px, 字号 9-48px, 字重 100-900
14	向后兼容	旧格式 "module": "composite:xxx" 仍然支持
14	中文错误处理	所有脚本内置中文错误提示、参数校验前置、安全文件操作、调试模式

渐进式文件索引

文件名	分类	包含内容	审计关联
references/LICENSE.md	许可协议	开源许可证声明（MIT）。包含：MIT 许可证完整文本。	R-26
references/antipatterns.md	规范指南	skill 编写中的常见反模式。包含：错误做法示例、正确做法示例、避坑指引。	R-18
references/architecture.md	架构设计	skill-standardization 整体架构。包含：模块关系、数据流、核心设计决策。	无
references/call-chains.md	参考文档	本文件定义 hug-html 技能的调用链，供 skill-sub 读取和执行。	无
references/changelog.md	版本管理	版本更新日志。包含：版本号、更新类型、修复项、升级说明。	R-24
references/examples.md	使用示例	各场景完整执行示例。包含：CLI 命令、执行过程、输出结果。	R-25 C-17
references/faq.md	常见问题	常见疑问与解答。包含：问题分类、原因分析、解决方案。	R-19, R-25 C-19
references/guide.md	使用指南	三种执行模式操作教程。包含：audit/create/refactor 流程、参数说明、注意事项。	无
references/module-library.md	参考文档	```	无
references/permissions.md	权限与测试	权限扫描说明与测试结论。包含：风险等级、高权限操作说明、测试概览、计时统计。	R-15, R-16
references/style-presets.md	参考文档	hug-html 支持 5 种常见风格的样式预设，通过 content_filler.py --preset 应用。	无

快速开始

场景：生成推广卡片 用户需求：帮我做一个 APP 推广卡片，要有二维码，输出 HTML 文件 系统执行：

bash

python scripts/template_generator.py --type promo -o "data/output/card.html"

系统输出：data/output/card.html — 毛玻璃风格推广卡片，含二维码、产品名、宣传语

场景：可视化编辑 用户需求：给这个卡片加一个在线编辑功能，输出可编辑 HTML 系统执行：

bash

python scripts/visual_editor.py --template data/output/card.html -o data/output/editor.html

系统输出：data/output/editor.html — 带 Ctrl+E编辑界面，双击文字可更新

场景：生成周历仪表板 用户需求：做一个带假日管理的周历交互 HTML，输出仪表板 系统执行：

bash

python scripts/template_generator.py --type calendar-dashboard -o "data/output/calendar.html"

系统输出：data/output/calendar.html — 交互式周历，支持年份切换和工日统计

工作流程

本技能的执行流程包含以下编号列表（按顺序执行）：

• ① 解析需求 — 输入 用户需求描述 → 输出 需求规格
• ② 选择/创建 Grid Spec — 输入 需求规格 → 输出 grid_spec.json
• ③ 引用模块 — 输入 grid_spec.json, modules/ → 输出 module_config.json
• ④ 生成 HTML — 输入 grid_spec.json, module_config.json → 输出 *.html
• ⑤ 生成编辑界面（可选） — 输入 *.html → 输出 editor.html
• ⑥ 内容填充（可选） — 输入 editor.html → 输出 filled.html
• ⑦ 方案模板固化（可选） — 输入 filled.html → 输出 interfaces.json
• ⑧ 输出结果 — 输入 最终 HTML → 输出 预览

权限说明

工具	访问级别	用途
Read	只读	读取 Grid Spec、模块库、样式预设
Write	写入	将输出 HTML 写入 data/output/
Bash	受限	运行内部处理脚本（限制在 scripts/ 目录内）

• 不会访问系统敏感路径或凭证文件
• 不会向外部网络发送数据
• 不会执行用户 Shell 配置文件
• 不会更新系统注册表或环境变量
• 不会执行用户 Shell 配置文件