name: hug-html
tags: []
version: 3.0.3
author: Ldxs
license: MIT
description: 组件式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.
sensitive_access: false
critical_write: false
permission_weight: LOW
data_dir: ../.standardization/hug-html/data/
externaldatadir: true
trigger: 生成 HTML 模板/编辑 HTML/HTML 模块/网格布局/单元格合并/可视化编辑/输出自包含 HTML
trigger_negative: 只是简单文本编辑/不涉及 HTML 生成/使用其他框架

hug-html

→ 详见 references/antipatterns.md

→ 详见 references/faq.md

触发场景

当用户提到以下内容时触发本技能：

• "生成 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 语法概念，无文件生成需求
• 用户明确请求其他特定技能

四层架构（细化）

骨架 (Skeleton)
├── 骨架结构 — N×M 网格、行列数、单元格合并(rowspan/colspan)、gap间距
├── 骨架样式 — 底板背景/渐变/透明度、外阴影、外边框、圆角、内外边距
└── 约束模式 — fill(完全贴合) / fit(等比缩放) / clip(裁剪遮挡)

模块 (Module)  ← 组件组合 = {组件声明 + 约束 + 比例} 自由搭配
├── 组件组合 — 8种原子组件自由搭配（text/image/icon/qrcode/table/divider/spacer/group）
├── 组合逻辑 — 方向(row/column)、比例(ratios)、对齐(align/cross_align)
└── 约束传递 — 骨架约束模块 → 模块约束组件（递归）

组件 (Component)  ← 8种原子类型
├── text     — 纯文本（title/body/caption 三种变体）
├── image    — 图片（支持 fit/cover/fill 填充模式）
├── icon     — 图标（FontAwesome / SVG内联）
├── qrcode   — 二维码（API生成）
├── table    — 数据表格（表头+行）
├── divider  — 分割线
├── spacer   — 空白占位
└── group    — 组合容器（递归包含子组件）

基础样式 (Base)
└── CSS原语 — 字体/颜色/渐变/圆角/间距/阴影/边框

编辑粒度（可视化编辑器内）：
| 可更新 | 不可更新（需改 Grid Spec） |
|--------|---------------------------|
| ✓ 图片内容（点击输入URL / 拖放文件替换） | ✗ 骨架结构（行列数、合并方式、gap） |
| ✓ 基础样式（每个文字元素独立：字体家族/字重/字号/字色） | ✗ 模块结构（组件的HTML骨架） |
| ✓ 模块样式（通过 cell style 覆盖背景色/内边距） | ✗ 骨架样式（底板色/外阴影等） |

大模型使用流程（自由生成模式）：

1. 理解用户需求 → 确定骨架结构：几行几列、哪些单元格需要合并
2. 确定约束模式：fill/fit/clip → 决定骨架对模块、模块对组件的约束
3. 描述需要的组件 → 从8种原子组件中自由组合，放入对应骨架位置
4. 配置组合逻辑：方向、比例、对齐方式
5. 生成 HTML → 可直接用 module_assembler.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 | 向后兼容 | 旧格式 "module": "composite:xxx" 仍然支持 |

能力边界

明确这个技能能做什么、不能做什么，避免使用时"不知道支不支持"。

✅ 支持的场景

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

❌ 不支持 / 不适合的场景

| 场景 | 为什么不支持 | 替代方案 |
|------|-------------|---------|
| 复杂前端应用（SPA / 数据可视化大屏） | 本技能面向静态 HTML+CSS 卡片，不支持路由/状态管理/API调用 | 手写 React/Vue 项目 |
| 多页面 HTML 站点 | 本技能是单页面自包含 HTML 生成器，不处理页面间导航 | 手写或使用静态站点生成器 |
| PDF / 图片输出 | 本技能输出 HTML 文件，不直接生成图片或 PDF | 生成 HTML 后用浏览器打印或截图 |
| 外部 CSS/JS 框架集成 | 本技能强调零外部依赖的自包含 HTML | 手动引入 CDN 或在 scripts 字段写自定义 JS |
| 非网格布局的自由排版 | 本技能基于 CSS Grid 网格系统，不适合绝对定位的自由排版 | 使用自由生成模式直接手写 HTML |
| 后端交互 / 数据库读写 | 本技能是纯前端 HTML，无后端能力 | 搭配 Node.js / Flask 等后端框架 |

⚠️ 需要注意的边界情况

| 情况 | 说明 |
|------|------|
| 网格越界 | 单元格的 row/col 索引 + rowspan/colspan 不能超过网格总行列数，否则 CSS Grid 会异常渲染 |
| 毛玻璃裁剪 | backdrop-filter 需要容器有 overflow:hidden，否则内容可能被裁剪 |
| JSON 模板路径 | --spec 参数支持绝对路径、相对路径和内置模板名；文件不存在会输出中文错误提示 |
| 文件编码 | 所有输入输出文件必须为 UTF-8 编码；其他编码可能导致乱码 |
| 编辑模式兼容性 | Ctrl+E 编辑模式需要现代浏览器（Chrome/Edge/Firefox），不支持 IE |

快速开始

# 列出所有组件类型（v3 新！）
python scripts/module_assembler.py --list-components

# 导出完整的组件接口定义
python scripts/module_assembler.py --export-interfaces "data/output/interfaces.json"

# 生成组件系统演示HTML
python scripts/module_assembler.py --demo

# 查看所有模板（向后兼容）
python scripts/grid_builder.py --list-templates

# 从内置模板生成 HTML
python scripts/template_generator.py --type harmony-app -o "data/output/card.html"

# 使用自定义 Grid Spec（支持新旧两种格式）
python scripts/grid_builder.py --spec "data/templates/3x3-merge.json" -o "data/output/grid.html"

# 导出完整接口定义（供大模型参考）
python scripts/grid_builder.py --export-interfaces "data/output/interfaces.json"

工作流程

本技能支持两种生成模式，每次生成完成后必须输出生成说明（print_generation_guide() 自动输出）：

模式 A：结构化模式（推荐）

1. 解析需求 — 理解用户需要的布局（行列数、合并、内容类型）
2. 选择/创建 Grid Spec — 选择内置模板或用 JSON 定义自定义网格
3. 引用模块 — 从模块库中选择 base/composite 模块放入格子
4. 生成 HTML — 调用 grid_builder.py 生成，自动执行审计
5. 生成编辑界面（可选）— 调用 visual_editor.py
6. 内容填充（可选）— 调用 content_filler.py
7. 输出结果 — 用 preview_url 展示，deliver_attachments 交付

模式 B：自由生成模式（省 token）

🛑 [MANDATORY] 每次生成完成后，必须阅读 print_generation_guide() 输出的生成说明并向用户展示。

1. 参考模块库 — 先执行 python scripts/grid_builder.py --list-modules 查看可用的 base/composite 模块
2. 参考模板范例 — 先执行 python scripts/grid_builder.py --list-templates 查看内置模板风格
3. 参考样式预设 — 先执行 python scripts/grid_builder.py --list-presets 查看可用风格
4. AI 自由生成 — 基于上述参考，直接编写自包含 HTML（使用 data-field 标记可编辑区域）
5. 保存到文件 — 使用 Write 工具写入 data/output/
6. 审计 [MANDATORY] — 调用 python scripts/grid_builder.py --audit <文件>，不可跳过
7. 输出结果 — 用 preview_url 展示

自由生成模式适用场景：简单卡片、快速原型、不需要网格拆分的页面。

结构化模式适用场景：复杂网格布局、需要批量生产、可复用模板。

权限说明

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

• 不会访问系统敏感路径或凭证文件
• 不会向外部网络发送数据
• 不会执行用户 Shell 配置文件

错误处理说明

v2.1.0 起，所有脚本均集成了中文错误处理机制：

1. 所有错误输出中文 — 不再显示英文 Traceback，改为 ❌ [错误类型] 说明 + 💡 修复建议
2. 参数校验前置 — 缺少必填参数时会输出中文提示和"--help 查看参数说明"
3. 文件操作安全 — 文件不存在/编码不对/JSON格式错误，都有详细中文指引
4. 调试模式 — 添加 --debug 参数可显示完整堆栈（仅供开发调试用）
5. 常见错误快速查 — 见下方"错误排查"章节或 references/faq.md

如果遇到报错看不懂、或者修复建议不管用的情况，查阅 references/faq.md 或直接要求 AI 协助排查。

附录：详细文档索引

| 文档 | 内容 |
|------|------|
| references/guide.md | 完整使用教程（v3 组件式架构） |
| references/module-library.md | 组件系统 + 约束系统 + 组合示例（v3 新版） |
| references/permissions.md | 权限扫描报告和风险说明 |
| references/style-presets.md | 样式预设系统说明 |
| references/call-chains.md | 调用链定义（skill-sub） |
| references/antipatterns.md | 反模式手册 |
| references/faq.md | 常见问题解答 |

错误排查（快速入门）

脚本报错了？不要慌。所有错误提示已改为中文，并附带修复建议。

| 错误现象 | 可能原因 | 怎么做 |
|----------|---------|--------|
| ❌ [文件错误] 找不到文件 | 路径写错了 | 检查路径是否存在，用绝对路径试试 |
| ❌ [JSON错误] 格式错误 | JSON 语法有问题 | 用 jsonlint.com 校验，或检查多了一个逗号 |
| ❌ [模板错误] 未知模板 | 模板名写错了 | 用 --list-templates 查看所有可用模板 |
| ❌ [参数错误] 缺参数 | 命令写少了参数 | 用 --help 查看完整参数说明 |
| ⚠️ 审计警告 | HTML 有小问题但不致命 | 检查输出的 [WARN] 内容，逐一修正 |
| 浏览器打开是空白 | HTML 文件编码问题 | 确认文件是 UTF-8 编码保存的 |

完整错误排查指南见 references/faq.md。

版本 2.1.2 — 全面中文异常处理：所有脚本输出的英文 Traceback 改为中文错误提示+修复建议；新增能力边界定义和错误排查指引。