Skill: ldxs001/hug-html (version 3.0.3)

--- 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/ external_data_dir: 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 | ## 快速开始 ```bash # 列出所有组件类型（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 改为中文错误提示+修复建议；新增能力边界定义和错误排查指引。


Security scan verdicts — ClawScan: suspicious | static analysis: clean | VirusTotal: clean | SkillSpector: suspicious (MEDIUM)