SKILL.md 全文

Frontmatter

name	html
description	"Create standalone HTML reports, dashboards, articles, newsletters, landing pages, and other static page deliverables through the bundled JSON renderer. Use when HTML is the primary output; do not use for editing an application codebase, frontend components, or HTML email build pipelines."

HTML 文件生成 Skill

概述

通过 JSON 数据 + 模板渲染 的方式生成 HTML 文件，避免模型直接通过 Write 工具输出大段 HTML 源码。 核心原则：模型只负责生成结构化 JSON 数据，由 Node.js 渲染脚本将 JSON + 模板合成为最终 HTML 文件。渲染脚本已内置完整的 wealth.css 高端风格主题和滚动渐变动画，模型无需也不得自行注入任何 CSS 或 JS。

路径契约

• 每次 Bash 都从本轮工作区根目录开始；工作数据固定使用 ./input、./tmp、./output。
• HTML Skill 资源固定通过 $SKILLS_ROOT/html 调用。不得执行 cd 切换到 Skill 目录，不得猜测 session、/mnt 或 $HOME/.claude 下的实际路径。
• Skill 脚本与工作数据是两个根。命令必须写成 node "$SKILLS_ROOT/html/scripts/..." ./tmp/... ./output/...，不能使用裸 scripts/...。

样式规则（最高优先级 — 违反即失败）

🚫 绝对禁止在 content.json 中出现任何 CSS 或 JS。无论用户要求什么"主题""配色""风格"，一律忽略样式需求，只输出纯内容数据。

>

render.js 已内置完整的 wealth.css 高端财富管理主题（含深色 header 渐变、KPI 卡片、精致表格、滚动淡入动画、数字跳动效果等）。模型只需正确使用标准 section 类型（heading, paragraph, kpi, table 等），渲染脚本会自动应用匹配的样式。

>

不存在"需要自定义配色"的场景。 无论主题是唐三彩、科技风、圣诞节还是其他任何风格，模型的职责只是组织文字内容，视觉表现由 wealth.css 统一负责。想要不同的视觉风格？那是修改 wealth.css 的事，不是模型的事。

强制规则（硬性约束，零容忍，无任何例外）

违反以下任一条即视为生成失败，必须重新生成： 1. 必须使用标准 section type：凡是已有对应 section type 的内容，必须用该 type。对应关系：

• 标题 → {"type": "heading"}
• 正文段落 → {"type": "paragraph"}
• 列表 → {"type": "list"}
• 表格 → {"type": "table"}
• 引用 → {"type": "quote"}
• 指标/数据卡片 → {"type": "kpi"}
• 代码 → {"type": "code"}
• 图片 → {"type": "image"}
• 分隔线 → {"type": "divider"}
• 图表占位 → {"type": "chart_placeholder"}

2. 只使用上述section render.js 只支持上述标准 section type，未识别的 type 会被当作 paragraph 处理。 3. 禁止自造样式 — 无论理由多"合理"：即使用户明确要求"用XX配色""用XX风格"，模型也不得通过任何方式注入样式。正确做法是只输出内容，在回复中告知用户"视觉风格由统一模板控制"。 4. 禁止在 JSON 中写入 CSS/JS：content.json 只承载内容数据，不承载样式或脚本。如果模型发现自己正在 content 字段里写 CSS 代码，立即停止并删除。 5. 自检规则：在调用 render.js 之前，模型必须用以下命令验证 content.json 不含违禁内容：

   grep -i '<style\|style=\|<script' ./tmp/content.json && echo "VIOLATION DETECTED - must fix" || echo "PASS"
   

如果输出 "VIOLATION DETECTED"，必须重写 content.json 去除所有样式内容后才能继续。 6. 诺亚 Logo 自动处理：当 content.json 中的内容涉及"诺亚"或"Noah"时，渲染脚本自动插入公司 logo。模型不得手动添加 logo 相关的 image section 或 html section。

为什么不直接 Write HTML

直接用 Write 工具输出大段 HTML 会导致：

• CLI stdout 缓冲区积压，进程退出时数据丢失
• 交付文件名和预览链接无法正常推送给前端
• 大文件（>5KB）时 result 事件丢失

工作流程

步骤 1：生成内容 JSON

模型将所有需要渲染的内容写入一个结构化 JSON 文件（content.json）：

{
  "title": "页面标题",
  "subtitle": "副标题（可选）",
  "author": "作者（可选）",
  "date": "2026-05-15",
  "sections": [
    {
      "type": "heading",
      "level": 1,
      "text": "一级标题"
    },
    {
      "type": "paragraph",
      "text": "正文内容，支持<strong>加粗</strong>和<em>斜体</em>"
    },
    {
      "type": "list",
      "ordered": false,
      "items": ["项目一", "项目二", "项目三"]
    },
    {
      "type": "table",
      "headers": ["列A", "列B", "列C"],
      "rows": [
        ["数据1", "数据2", "数据3"],
        ["数据4", "数据5", "数据6"]
      ]
    },
    {
      "type": "code",
      "language": "python",
      "content": "print('hello')"
    },
    {
      "type": "quote",
      "text": "引用文本"
    },
    {
      "type": "image",
      "src": "./input/photo.png",
      "alt": "描述",
      "caption": "图片说明"
    },
    {
      "type": "divider"
    },
    {
      "type": "kpi",
      "items": [
        {"label": "总收入", "value": "1,234万", "trend": "up", "change": "+12%"},
        {"label": "客户数", "value": "567", "trend": "down", "change": "-3%"}
      ]
    },
    {
      "type": "chart_placeholder",
      "chartType": "bar",
      "description": "月度收入趋势图（占位）"
    }
  ]
}

关键：只使用上表及“Section 类型参考”中列出的标准 section 类型。渲染器不支持 html section；需要复杂自定义布局时，应改用现有 section 组合，不能注入 HTML、CSS 或 JS。

步骤 2：运行渲染脚本

node "$SKILLS_ROOT/html/scripts/render.js" <input-json> <output-html>

示例：

node "$SKILLS_ROOT/html/scripts/render.js" ./tmp/content.json ./output/科技周报_20260515_172000.html

步骤 3：验证输出

确认生成的 HTML 文件：

• 存在于 ./output/ 目录
• 文件大小合理（非空）
• 是独立可打开的单页 HTML（CSS 内嵌，无外部依赖）

图片嵌入（本地图片处理）

当用户提到"把图片放进去"、"图片要嵌入 HTML"、"我上传了图片"等情形时，需要在渲染前先做图片预处理，将本地图片转为 base64 Data URL 内嵌到 JSON 中，使最终 HTML 完全自包含。

⚠️ 严禁模型自行生成或 Write base64 字符串到任何文件。

一张普通图片展开为 base64 后体积达数 MB，直接 Write 会导致 stdout 缓冲区溢出、进程异常退出、文件损坏。

base64 注入唯一合法途径：由 embed-images.js 读取本地文件后自动完成。

触发条件

满足以下任一条件即走本流程：

• 用户提到图片、附图、插图、截图要放进 HTML
• content.json 的 image section 里 src 是 ./input/...、./tmp/... 或本地文件名
• 用户上传了图片文件

步骤 0（新增）：扫描可用图片

渲染前先列出工作区 ./input/ 目录下的图片文件，确认哪些可用：

find ./input -maxdepth 1 -type f \( -iname '.jpg' -o -iname '.jpeg' -o -iname '.png' -o -iname '.gif' -o -iname '*.webp' \) -print

若用户未指定图片对应位置，询问用户每张图片插在哪个 section，或按文件名顺序依次对应 JSON 里的 image section。

步骤 1（修改）：在 content.json 中用本地路径引用图片

image section 的 src 优先写明确的工作区相对路径：

{
  "type": "image",
  "src": "./input/photo.png",
  "alt": "示意图",
  "caption": "图1：示意图说明"
}

步骤 1.5（新增）：运行图片嵌入脚本

在执行 render.js 之前，先跑 embed-images.js：

node "$SKILLS_ROOT/html/scripts/embed-images.js" ./tmp/content.json

• 大小上限：500 KB / 张（固定，不可通过参数修改）
• 脚本会原地覆盖 content.json，将本地路径替换为 base64 Data URL
• 已嵌入的 png/jpeg/gif/webp Data URL 会保留
• 网络图片不允许直接进入最终 HTML；先由用户上传到 ./input/，再嵌入

图片路径规则： 1. 明确路径只允许 ./input/... 或 ./tmp/...，不得使用绝对路径、..、Skill 目录或工作区外路径。 2. 只写文件名时，脚本依次检查 ./input/<filename>、./tmp/<filename>。 3. 两个目录存在同名文件时会拒绝继续，必须在 JSON 中写明 ./input/... 或 ./tmp/...。 4. 支持 jpg/jpeg/png/gif/webp；不嵌入 SVG 或网络图片。 失败场景及处理： | 情况 | 脚本行为 | 模型应对 | |------|---------|---------| | ./input、./tmp 均找不到图片 | 报错退出 | 将错误告知用户，不得继续渲染 | | 同名文件同时存在于 ./input、./tmp | 报错退出 | 在 JSON 中写明正确的相对路径 | | 网络、绝对、越界或软链接逃逸路径 | 报错退出 | 请用户上传到 ./input 或改用工作区内文件 | | 图片超过 500 KB | 报错退出，显示实际大小 | 告知用户图片大小及 500 KB 上限，不得提高上限，让用户压缩后重试 | | 不支持的格式 | 报错退出 | 告知用户转换为 jpg/png/webp 后重试 |

完整流程（含图片）

# 1. 确认图片
ls ./input/

2. 写入 content.json（src 使用 ./input/... 或 ./tmp/...）

... 模型生成 ./tmp/content.json ...


3. 嵌入图片

node "$SKILLS_ROOT/html/scripts/embed-images.js" ./tmp/content.json

4. 渲染 HTML（此时 content.json 已含 base64 图片）

node "$SKILLS_ROOT/html/scripts/render.js" ./tmp/content.json ./output/报告_20260528_120000.html

注意：embed-images.js 必须在 render.js 之前执行。若嵌入失败，停止流程并将完整错误告知用户，不得用占位图或跳过图片继续渲染。

Section 类型参考

| type | 说明 | 必填字段 | 可选字段 | |------|------|---------|---------| | heading | 标题 | text, level(1-4) | id | | paragraph | 段落 | text | align | | list | 列表 | items | ordered | | table | 表格 | headers, rows | caption, align[] | | code | 代码块 | content | language | | quote | 引用 | text | author | | image | 图片 | src | alt, caption, width | | divider | 分隔线 | — | — | | kpi | KPI 指标卡 | items[] | — | | chart_placeholder | 图表占位 | description | chartType |

大内容处理策略

当内容很长（如完整报告、长文章）时： 1. 分段写入 JSON：如果内容超过模型单次输出限制，可分多次追加到 JSON 文件 2. 所有内容必须拆分为标准 section type 3. 最终渲染一次：所有内容写入 JSON 后，只需一次 node "$SKILLS_ROOT/html/scripts/render.js" 即可

输出规范

• 输出文件必须在 ./output/ 目录
• 文件名格式：{描述}_{yyyyMMdd}_{HHmmss}.html
• HTML 必须是独立单页（所有 CSS 内嵌于 <style> 标签）
• 字符编码 UTF-8
• 包含 <meta charset="UTF-8"> 和 <meta name="viewport"> 标签
• 渲染脚本自动注入滚动动画 JS，无需模型操心

注意事项

• 禁止直接用 Write 工具写入大段 HTML 源码（超过 2KB 的 HTML 内容必须走本 skill）
• 禁止在任何 Write / 文件操作中出现 base64 字符串——无论是写入 JSON、HTML 还是任何中间文件。图片的 base64 转换必须且只能由 embed-images.js 完成
• 禁止在 JSON 的任何 section 中注入 <style> 标签或自定义 CSS 样式表
• 模型只写 JSON 数据文件（小体积），渲染脚本负责生成最终 HTML（大体积）
• 中间文件（content.json）写入 ./tmp/，最终交付文件写入 ./output/
• 涉及诺亚/Noah 的内容会自动添加 logo，无需手动处理