原始内容
displayName: hug-html name: hug-html tags: ['html', 'grid', 'template', 'visual-editor', 'module-library', 'style-presets', 'layout', 'chinese-error-handling'] version: 3.3.1 author: Ldxs license: MIT description: 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 sensitive_access: false critical_write: false permission_weight: LOW data_dir: ../.standardization/hug-html/data/ external_data_dir: true trigger: 生成 HTML 模板/编辑 HTML/HTML 模块/网格布局/单元格合并/可视化编辑/输出自包含 HTML trigger_negative: 仅询问概念/无文件生成需求/要求使用其他工具 meta_field_sync: true create_permissions_md: true license_compliance: true
hug-html
→ 详见核心能力的渐进式文件索引
限制
- 本技能的能力边界分为支持场景、不支持场景和边界情况三类。
- 生成推广卡片 — 应用推广、活动宣传、产品介绍的毛玻璃卡片。触发词："生成一个 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 文件 系统执行：
python scripts/template_generator.py --type promo -o "data/output/card.html"
系统输出：data/output/card.html — 毛玻璃风格推广卡片，含二维码、产品名、宣传语
场景：可视化编辑 用户需求：给这个卡片加一个在线编辑功能，输出可编辑 HTML 系统执行：
python scripts/visual_editor.py --template data/output/card.html -o data/output/editor.html
系统输出：data/output/editor.html — 带 Ctrl+E编辑界面，双击文字可更新
场景：生成周历仪表板 用户需求：做一个带假日管理的周历交互 HTML，输出仪表板 系统执行：
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 配置文件