Html

Name: Html
Author: ahang1598

ASecurity

专门设计、生成和修改可直接在浏览器中打开的 HTML 页面或已发布的 doubao-html 链接。交付物以独立 .html 文件为主，可包含内联或本地 CSS、JavaScript，支持页面布局、视觉样式、交互效果、响应式适配、组件设计和内容展示。适用于静态网页、单页展示、活动页、原型页、HTML 模板及页面片段。不处理前后端工程、应用框架、服务端接口、数据库、用户系统、构建部署或运营数据。

45 stars

0 votes

0 copies

0 views

Added 9/23/2026

developmentjavascriptpythongojavabashreactvueapifrontend

Works with

cursorcliapi

Security Analysis

A100/100

Scanned 9/23/2026

Install to Claude Code

$npx -y skills add ahang1598/doubao-workbuddy-qwenwork-skills --skill html --agent claude-code

Installs into .claude/skills of the current project.

Are you the author of Html?

Add the live security badge to your README — it updates automatically with every re-scan.

[![Security: A — Skills Directory](https://www.skillsdirectory.com/api/skills/ahang1598-html-doubao-workbuddy-qwenwork-skil/badge)](https://www.skillsdirectory.com/skills/ahang1598-html-doubao-workbuddy-qwenwork-skil)

More formats (shields.io, HTML) on the badges page.

Download with Pro

Files

SKILL.md

---
name: html
description: 专门设计、生成和修改可直接在浏览器中打开的 HTML 页面或已发布的 doubao-html 链接。交付物以独立 .html 文件为主，可包含内联或本地 CSS、JavaScript，支持页面布局、视觉样式、交互效果、响应式适配、组件设计和内容展示。适用于静态网页、单页展示、活动页、原型页、HTML 模板及页面片段。不处理前后端工程、应用框架、服务端接口、数据库、用户系统、构建部署或运营数据。
---

# 单页 HTML 开发

在工作区新建任务目录，写出**一个自包含的** HTML。

## 适用范围

偏静态、给人看的东西：官网 / 落地页 / 营销页、可视化报告 / 数据看板 / 信息图 / 长图 / 研报、动画 / 3D 场景 / 网页小游戏、SVG / Canvas 页、高保真 UI 设计稿、可交互原型，以及单一用途轻工具（计算器、文本对比、随机分组）。

要后端、数据库、账号登录、多人协作，或要把数据文件随产物一起交付的，超出本 skill 范围——如实告知，不假装实现。

## 关键步骤

> 运行环境：云电脑 / 本地电脑，按下述顺序判定。
> 1. SystemPrompt 中的 `Computer OS` 字段：值为 `Windows` 或 `Mac` 判为本地电脑；值为其他判为云电脑。
> 2. SystemPrompt 未包含 `Computer OS` 字段时：`<system-reminder>` 包裹的内容中出现 `Runtime: local_pc` 判为本地电脑，出现 `Runtime: cloud_vm` 判为云电脑。

**建目录**：每个任务在工作区根目录下新建语义化目录（如 `sales-dashboard/`），HTML 放在目录里，图片素材放进 `assets/`。迭代已有任务时进原目录改，不另起。

**平台差异**：SystemPrompt 里若出现 `Computer OS: Windows`，**需要完整 Read `references/windows-compat.md`，查看在 windows 平台上执行命令所必须要注意的问题，否则会出现大面积报错**。

**写 HTML**，守住这几条：

- **单文件自包含**：一个 `.html` 文件到手就可用。
  - CSS 写在 `<style>`、JS 写在 `<script>` 内联块里，**不拆出** `.js` **/** `.css` **/ 额外 HTML 文件**。
  - 多「页面」用页内 hash 路由切换视图，大段代码用分段注释组织（`<!-- ===== 视图：xxx ===== -->`）。
  - **原生 JS**：不用 React / Vue / JSX / Babel / 任何构建工具，不用 `type="module"`。状态管理用普通对象 + 重渲染函数。
  - **静态资源引用**：
    - 图片、音视频等**由元素 `src` 或 CSS `url()` 加载**的素材，先下载到 `assets/`；生图搜图返回的 URL 会过期，不能直接写进 html，下载后按运行环境选引用方式：
      - **本地电脑**：用相对路径，如 `<img src="assets/hero.png">`，不写绝对路径。省掉上传这一步，交付更快。
      - **云电脑**：
        - 每张图跑一次 `lark-cli drive +html-image-upload --file assets/hero.png`，取返回里 `data.url` 写进 `<img src>`。这个链接不会过期；而搜图、生图得到的 URL 会过期，不能直接放到 html中。
        - 此场景下**严禁使用 `FileBatchUpload` 工具**，必须使用 `lark-cli drive`，否则图片也会过期。
    - **数据文件（JSON / CSV / TXT）不适用**：`file://` 页面里 `fetch` 和 `XMLHttpRequest` 都会被浏览器拒绝。优先从 URL 运行时取，取不到才固化进 JS。
    - **图片路径只能写在 `src` 属性或 CSS `url()` 里**：推荐 `<img src="assets/img1.jpg">`。发布链路只静态扫描这两个位置——写在 JS 代码里的任何形式（含 `const imgs = ['assets/a.jpg']` 这样的常量数组）、以及 `data-src` / `srcset` / `poster` 等其它属性，发布后都会裂图。
- **分批写入**：一次写入过长的文件会让用户等待焦虑，最好一次 Write 10k token 内，简单向用户同步进度后，再继续分批写入。

- **注意响应式适配，宽屏窄屏电脑手机都要能看**。

- **交付与发布**：
  - 当用户没有明确的发布需求时：用 `present_files` 这类交付工具给用户交付 HTML，**同一个产物只交付一个 `.html` 文件**——按运行环境选定一种图片引用方式就够了，不要再额外附一份「以防万一」的备份版或压缩包，用户拿到两份不知道该打开哪个。交付说明如实写清：没实现的功能、用的是示例数据、做不了的能力。本地电脑下页面依赖同目录 `assets/` 时，要简单提醒用户转发时连目录一起发。
  
  - 当用户想要「发布」、「可访问的链接」、「给我链接」时：阅读 `references/lark-apps-publish.md`，将你的 html 文件发布成一个 doubao-html 网页，此时无需交付 html 文件，仅需使用 present_files 交付发布后的 doubao-html 链接。
  
  - **最终给用户的回复不要过长**：最重要的产物是你最终生成的 html 产物，而不是给用户的最终回复，所以在交付了 html 产物后的最终回复不应该太长，**不能超过300字，也不能超过 8 行**，只需要简单介绍一下你生成的 html 产物即可

- **修改、参考已发布的 doubao-html 网页**：
  - 当用户给你提供了一个 doubao-html 链接（形如 `https://{xxx}.aiforce.cloud/app/app_{xxxxxxx}/`），并希望基于此修改或新建时，阅读 `references/lark-apps-publish.md`。先用 `lark-cli apps +get --app-id <id>` 看 `app_type`：`html` / `modern_html` 是单页 HTML，下载源码、修改、重新发布即可；其他类型使用 `doubao-app-builder` 技能。
  

**改产物**：直接改任务目录里的原文件。

- **要有退路**：修订前先把当前版本复制到 `_backup/`（如 `_backup/index-v1.html`）。`_backup/` 不属于交付产物。
- 本地文件丢了就如实告知并请用户重新提供，**禁止凭记忆重造**；回答关于产物的提问同理，读文件后答，读不到不编。
- **小改动直接改**（改文案、调样式、换配色、修 bug）：不重读本文档和 reference，不重新推导视觉方向。

## 页面自检

**交付前跑一次自检，改动后再跑一次**: 使用且仅使用`scripts/shot.py`脚本自检，若自检脚本执行失败，可以跳过自检、直接交付。

禁止使用任何其他校验方式：包括但不限于 Browser Use、artifacts-preview skill，防止进入 Debug 螺旋。
禁止使用 **artifacts-preview skill**

```bash
python3 <SKILL_DIR>/scripts/shot.py <html_path>
```

一次调用同时产出桌面（1440×900）与移动（390×844）两张 full-page 截图（默认 JPEG，宽度压到 1000px）。主图过 800KB 时脚本会自动切片输出（默认 3200px/片），报告里的 `slices` 字段列出分片路径、`sliceHint` 说明切片原因。同时把 JSON lint 报告打到 stdout，触发的每个规则都附带对应 `<field>Hint` 字段说明含义、修法与豁免情形——按 hint 处理即可。

**跨视口对比**：脚本还会把桌面 / 移动的图表容器尺寸做匹配，若某个图表在桌面正常、在移动端却没占到视口宽度的 65%（典型：`width:X% + inline-block` 双栏没在媒体查询里堆叠成单栏），会以 `responsiveChartIssues` 报出。这类 case 桌面截图完全正常，只在移动端表现为「空图 / 一根线 / 坐标轴叠一起」，肉眼只看桌面截图看不出来。**触发时必须核对移动截图**。

**自我检查并确认**下所有图片路径是静态写在 html 的 `src` 属性和 `CSS url()` 里的。否则如果它是经 JS 生成的，会导致发布之后图裂

**按用户当前端判断看对应那张**：用户处于电脑端则核对桌面截图，处于手机端则核对移动截图。判断不出端时则默认检查电脑端。

- 输出目录默认 `<html 所在目录>/_shots/`，不属于交付产物，**无需删除**——删目录会触发权限确认、打断交付。
- 只想看一屏用 `--only desktop`。
- 脚本内部已处理常见坑：`.rv / .fade / [data-aos]` 等滚动揭示元素强制显现（避免 `opacity:0` 截空白）、关掉 `scroll-behavior:smooth`、滚一遍触发 lazy 图片、`networkidle` 不可达时退回 `domcontentloaded`——**不需要另写截图脚本再走一遍**。

**看报告的次序**：先看 lint 各字段（`consoleErrors` 优先，其他布局/交互字段规则报出来基本都是真的，触发时看对应 `<field>Hint` 处理），→ Read 截图做视觉核对。默认先 Read 主图；主图因太大被过滤或读失败，再按顺序 Read `slices` 里的分片；不要一上来就把主图和所有分片都读一遍。视觉有疑点、报告分辨不出细节（颜色、字体渲染）时，再针对性截一屏；先用报告定位到具体元素/错误、改代码，改完重跑 `shot.py`。


## 外部资源

**JS 库统一走 jsDelivr**：`https://cdn.jsdelivr.net/npm/<包名>@<版本>/…`。故障时的备用镜像是 **cdnjs**（`https://cdnjs.cloudflare.com/ajax/libs/<lib>/<ver>/…`，Cloudflare 官方运营，同版本文件字节一致）。**禁止** bootcdn、staticfile、polyfill.io（均有供应链投毒历史），unpkg 不作首选。

**字体走自托管镜像** `https://miaoda.feishu.cn/fonts/css2?family=…`：查询语法与 Google Fonts 的 `css2` 端点完全一致，返回的 `@font-face` 也指向自托管 CDN，两跳都不经过 Google。**不直连** `fonts.googleapis.com` **/** `fonts.gstatic.com`（部分地区不可达）。多字族就重复写多个 `family=`，例如 `<link rel="stylesheet" href="https://miaoda.feishu.cn/fonts/css2?family=Noto+Serif+SC:wght@400;600;700;900&family=Noto+Sans+SC:wght@300;400;500;700&display=swap">`。每个 `font-family` 都要带完整的系统字体 fallback 栈，字体加载失败时页面仍然成立。

## 图像素材

图片素材能显著提升产物美观度，不要默认用纯 CSS / SVG 撑起全部视觉。

**载体选型**：图标、状态标记、导航符号、简单示意图、数据图表属于符号 / 信息型，用内联 SVG 或 CSS。人物、角色、动物、具体物体、产品情境、真实场景、hero 主视觉、章节题图、叙事插画属于具象 / 氛围型，**必须用真实图片**——除非用户明确要矢量插画，禁止用手写 SVG 或 CSS 几何图形代替依赖形象可信度的具象画面。「简单图表优先使用 Echart 来进行生成，而无需使用 SVG」只适用于数据可视化，不得扩展到人物、场景和插画。

**来源按序**：① 用户提供和项目已有的素材，始终第一优先，不要擅自用生成图替换；② 图片生成能力，没有可用素材时的默认选择，prompt 写清风格、构图、配色，使产出与视觉方向一致；③ 外部检索，仅当要忠实呈现真实人物、产品、地点、Logo 等事实对象、生成会失真造假时才用。

网络图片需要先下载到本地并**用读图能力实际看过**——内容对得上、清晰完整、无水印、不是防盗链占位图，确认通过才上传引用；看不了或不符的换图或改用生成。

**来源偏好**：尽量使用用户提供的图片、项目已有的图片、以及搜索到的真实相关的图片，而不是工具生成的图片；假设这些图片不够时，你可以使用生图生成的图片进行补充

**使用图片的比例控制在 3:4 ~ 21:9**（竖版到宽条形）：Banner / Hero 用 16:9 或 21:9，章节题图 3:2，方形插图 1:1。更极端的比例（1:5 长条、9:16 竖屏）可能会导致图片在不同设备上显示不全或出现大片空白区域。

**裁切与呈现**：用 `cover` 或固定高度前，先确认任务要求看见的主体、文字、标签不落在裁切区——竖图放横框时先用 `object-position` 把主体框住，主体横跨整张图、怎么调都保不住时才改用自然比例或 `contain`。hero、banner、纯背景用 `cover` 填满即可。

## 内容要求

**数据保真**：用户给了源数据时，每个数字和结论都要从源数据实际算出、可追溯，不目测、不凑整、不编造。

**数据附件要获取下来并分析**，但**不要把数据转成** `const RAW_DATA = [...]` **固化进 JS**——那样用户换一份文件页面纹丝不动。数据能从 URL 取到就运行时取，确实取不到时才固化，并在交付说明里讲清。

**内容取舍**：不加与目标无关或没有依据的内容；内容不足以成页时合并、重构或要材料，不靠放大留白撑页。当有大量信息需要展示时，主要信息和次要信息需要重点鲜明，一个逻辑连贯的模块闭合在一屏内是更好的选择，必要时添加筛选与搜索能力。

**硬性规格逐条对照**：页数、画幅、必含模块，交付前自查。

**时间演进优先用时间轴**：涉及阶段、演进、里程碑、前后对比、路线图的内容，默认使用时间轴，而非项目符号列表或纯段落；每个节点承载：时间、事件名、一句话说明（可选）、（可选）关键指标或图标，让单个节点即可独立传达信息，注意时间轴节点与连线应该适当对齐。时间轴和附着在其上的图标（比如圆点或方块）的中心必须实现像素级对齐（0px误差）。并且额外注意时间轴的文字和轴线、文字和图标不要重叠。
推荐用 **grid 三列（时间 / 轴 / 内容）** 的形式实现时间轴：圆点用真元素放中列、`justify-self:center` 交给布局引擎居中，轴线用 `calc()` 从列宽变量推出（横向时间轴同理，三列换三行、用 `align-self:center`），确保节点与轴线对齐，且无需手算坐标。

**表格要显式给列宽**：多列表格加 `table-layout: fixed`，并给**每一列**都写宽度、加起来正好 100%（`<colgroup><col style="width:25%">` 或写在 `th` 上）。漏写一列，`auto` 布局就会把它压到一字宽、中文逐字折行，行高被撑到半屏高，同行其余列跟着变成大片空白。

## 图表及其交互设计方法

**图表服务于内容理解与判断**：依据任务和数据决定图表类型、数量与组合。图表呈现关系与证据，文字只写图表未直接呈现的解读或判断，**禁止把图表标签照抄一遍**。图表首选 ECharts；仅当其无法满足所需表达或交互时，再使用 D3 或 SVG。

**设计图表及其交互前，统一从 [references/chart/atlas.md](references/chart/atlas.md) 开始**：先确定图表选型与信息组织，再按其中的指引选读图内交互或多视图体验参考。

## 网页交互设计

**禁止僵尸按钮**：视觉上像能点的元素——按钮、导航项、卡片入口——必须有真实的 click handler、跳转或占位反馈（如 toast 提示"演示中"）。禁止 `<button>` 无 `onclick`/`addEventListener`、`<a>` 无 `href`（或 `href="#"` / `href="javascript:void(0)"` / `href="javascript:;"` 却没实际 handler）、`<div class="nav-item">` 只挂 `cursor:pointer` 却什么都不绑——这些是原型页里最高频的 slop，要么给每个入口挂真实切页/toast，要么不做这个按钮，**宁愿不要按钮也不做僵尸按钮**

## 视觉设计

**先认媒介，别默认做成网页**：HTML 只是载体，产物形态各不相同——信息图、长图、研报、看板、设计稿、动画、游戏各有各的表达惯例。只有真在做网页时才用网页那套语汇（顶部导航、hero、footer、等宽卡片栅格、底部 CTA 区）；其余形态套上网页壳子就是最典型的 slop。先想清楚这次的媒介是什么、那个领域的行家会怎么排它，再往下走。

需要在既有色板上扩色时用 oklch 派生——固定 hue 调 lightness / chroma，或沿同一 L / C 轴换 hue——不要凭空发明一个新 hex 塞进去。

动手前读 `references/design/frontend-design.md` 确立视觉方向：有品牌或既有 UI 就对齐它的视觉语言，从零起步就从主题和材料里立一个契合的方向。已给参考图、品牌体系、设计规范或媒介 reference 时以它们为准。方向实在推不出、项目又是从零起的，先问清调性、受众、颜色、情绪——**在推不出方向时硬选，slop 就是这么来的**。

字体选少量但与主题匹配的，层级靠字号、字重、行长和语义断行建立，不靠堆字体数量。背景与配色不局限于纯黑纯白，可以按内容属性和叙事节点变化，但一致性要来自共享色板和明确的颜色关系，不是逐页随机换色；强调色数量克制、同属一个体系。视觉丰富度服务内容：既不堆无信息价值的装饰，也不把「克制」做成大量留白加同一种构图。

**禁止无意义留白与失衡布局**：页面各区块须在视觉上均衡分布，禁止出现大面积无内容留白、单侧堆积、上重下空或下重上空等失衡结构；留白是用来服务于分组、呼吸或强调，不得用于填充版面。特殊布局设计除外，在特殊设计当中可以豁免。卡片组在**每个断点**的列数都不能让最后一行只剩 1 个（`N % C == 1`）——4 张走 4 → 2 → 1、跳过 3 列，别留 3 + 1。

**避免 AI slop**：滥用渐变、圆角＋左边框强调容器、被用滥的字体（Inter、Roboto、Arial、Fraunces）。

**做 hero / signature element / 复杂动效 / Canvas / WebGL / 进阶排印 / 材质纹理 / 地图 / 音频 / 音画同步 / 数学公式时先读 `references/design/visual-techniques.md`**——里面有动效工具链（IntersectionObserver / GSAP / Lottie / View Transitions / Scrollama / CSS scroll-timeline）、Canvas/WebGL 选型（three.js / p5.js / matter.js）、进阶排印（variable font / background-clip / SVG textPath / feTurbulence）、材质纹理层（grain / duotone / halftone）、地图（Leaflet / MapLibre / D3-geo / Deck.gl + 免费瓦片源）、Web Audio（Tone.js / 原生 AudioContext / sonification）、动画+声音协同（音频主时钟、三种协同模式、user gesture 门槛、mute 与 reduced-motion 双通道）、KaTeX 数学公式，以及每一层对应的 slop 红线（毛玻璃、glow border、粒子网背景、data-aos 全站铺、Leaflet 蓝大头针、Mercator 全球图、rainbow 色板、音频自动播放、音乐可视化跳舞背景等）。

**设计 3D 场景读 `references/design/3d-design.md`**，掌握材质、阴影、光照、运镜的设计方法。

**不用 emoji**：尽可能不要使用任何 emoji，也不作图标、不作装饰、不放进数据，除非用户品牌资产明确包含。需要图标体系时用内联 SVG（`<svg viewBox="0 0 24 24">`）建立风格连贯的图标语言。

**要有 favicon**：用 SVG 或 AI 生图，为产物搭配一个合适的 icon，内联进 HTML。

在既有 UI 上增补时，先理解并遵循它的视觉语汇：文案风格、配色、hover 状态、卡片布局、密度。

## 参考文档地图

### `references/`

| 文档 | 何时读 |
| --- | --- |
| [`lark-apps-publish.md`](references/lark-apps-publish.md) | 用户要「发布」「可访问的链接」，或给了 doubao-html 链接要基于它改 |
| [`windows-compat.md`](references/windows-compat.md) | SystemPrompt 出现 `Computer OS: Windows`——**必须完整 Read**，否则大面积报错 |

### `references/design/`

| 文档 | 何时读 |
| --- | --- |
| [`frontend-design.md`](references/design/frontend-design.md) | **动手前必读**，确立视觉方向 |
| [`visual-techniques.md`](references/design/visual-techniques.md) | hero / signature element / 复杂动效 / Canvas / WebGL / 进阶排印 / 材质纹理 / 地图 / 音频 / 音画同步 / 数学公式 |
| [`3d-design.md`](references/design/3d-design.md) | 设计 3D 场景（材质、阴影、光照、运镜） |

### `references/chart/`

| 文档 | 何时读 |
| --- | --- |
| [`atlas.md`](references/chart/atlas.md) | **做图表与图表交互的统一入口**：先定选型与信息组织，再按其中指引选读下面两份 |
| [`reading-interactions.md`](references/chart/reading-interactions.md) | 常规读图、固定比较、总览查看某个对象的明细（由 atlas 分流，不单独作入口） |
| [`experience-examples.md`](references/chart/experience-examples.md) | 从同一批记录筛群体做多维比较，或明确的教学实验（同上） |

Attribution

ahang1598

View source More from ahang1598 →

SSkills DirectorySkills Directory

Know which skills are safe — weekly.

Best new skills + every skill we flagged as malicious. From the team that scanned 103,619.

Join free

Is this your skill, or is something wrong with this listing? Request removal or report an issue. Author removals are honored within 72 hours.

Comments (0)

No comments yet. Be the first to comment!

--- name: html description: 专门设计、生成和修改可直接在浏览器中打开的 HTML 页面或已发布的 doubao-html 链接。交付物以独立 .html 文件为主，可包含内联或本地 CSS、JavaScript，支持页面布局、视觉样式、交互效果、响应式适配、组件设计和内容展示。适用于静态网页、单页展示、活动页、原型页、HTML 模板及页面片段。不处理前后端工程、应用框架、服务端接口、数据库、用户系统、构建部署或运营数据。 --- # 单页 HTML 开发在工作区新建任务目录，写出**一个自包含的** HTML。 ## 适用范围偏静态、给人看的东西：官网 / 落地页 / 营销页、可视化报告 / 数据看板 / 信息图 / 长图 / 研报、动画 / 3D 场景 / 网页小游戏、SVG / Canvas 页、高保真 UI 设计稿、可交互原型，以及单一用途轻工具（计算器、文本对比、随机分组）。要后端、数据库、账号登录、多人协作，或要把数据文件随产物一起交付的，超出本 skill 范围——如实告知，不假装实现。 ## 关键步骤 > 运行环境：云电脑 / 本地电脑，按下述顺序判定。 > 1. SystemPrompt 中的 `Computer OS` 字段：值为 `Windows` 或 `Mac` 判为本地电脑；值为其他判为云电脑。 > 2. SystemPrompt 未包含 `Computer OS` 字段时：`<system-reminder>` 包裹的内容中出现 `Runtime: local_pc` 判为本地电脑，出现 `Runtime: cloud_vm` 判为云电脑。 **建目录**：每个任务在工作区根目录下新建语义化目录（如 `sales-dashboard/`），HTML 放在目录里，图片素材放进 `assets/`。迭代已有任务时进原目录改，不另起。 **平台差异**：SystemPrompt 里若出现 `Computer OS: Windows`，**需要完整 Read `references/windows-compat.md`，查看在 windows 平台上执行命令所必须要注意的问题，否则会出现大面积报错**。 **写 HTML**，守住这几条： - **单文件自包含**：一个 `.html` 文件到手就可用。 - CSS 写在 `<style>`、JS 写在 `<script>` 内联块里，**不拆出** `.js` **/** `.css` **/ 额外 HTML 文件**。 - 多「页面」用页内 hash 路由切换视图，大段代码用分段注释组织（``）。 - **原生 JS**：不用 React / Vue / JSX / Babel / 任何构建工具，不用 `type="module"`。状态管理用普通对象 + 重渲染函数。 - **静态资源引用**： - 图片、音视频等**由元素 `src` 或 CSS `url()` 加载**的素材，先下载到 `assets/`；生图搜图返回的 URL 会过期，不能直接写进 html，下载后按运行环境选引用方式： - **本地电脑**：用相对路径，如 `<img src="assets/hero.png">`，不写绝对路径。省掉上传这一步，交付更快。 - **云电脑**： - 每张图跑一次 `lark-cli drive +html-image-upload --file assets/hero.png`，取返回里 `data.url` 写进 `<img src>`。这个链接不会过期；而搜图、生图得到的 URL 会过期，不能直接放到 html中。 - 此场景下**严禁使用 `FileBatchUpload` 工具**，必须使用 `lark-cli drive`，否则图片也会过期。 - **数据文件（JSON / CSV / TXT）不适用**：`file://` 页面里 `fetch` 和 `XMLHttpRequest` 都会被浏览器拒绝。优先从 URL 运行时取，取不到才固化进 JS。 - **图片路径只能写在 `src` 属性或 CSS `url()` 里**：推荐 `<img src="assets/img1.jpg">`。发布链路只静态扫描这两个位置——写在 JS 代码里的任何形式（含 `const imgs = ['assets/a.jpg']` 这样的常量数组）、以及 `data-src` / `srcset` / `poster` 等其它属性，发布后都会裂图。 - **分批写入**：一次写入过长的文件会让用户等待焦虑，最好一次 Write 10k token 内，简单向用户同步进度后，再继续分批写入。 - **注意响应式适配，宽屏窄屏电脑手机都要能看**。 - **交付与发布**： - 当用户没有明确的发布需求时：用 `present_files` 这类交付工具给用户交付 HTML，**同一个产物只交付一个 `.html` 文件**——按运行环境选定一种图片引用方式就够了，不要再额外附一份「以防万一」的备份版或压缩包，用户拿到两份不知道该打开哪个。交付说明如实写清：没实现的功能、用的是示例数据、做不了的能力。本地电脑下页面依赖同目录 `assets/` 时，要简单提醒用户转发时连目录一起发。 - 当用户想要「发布」、「可访问的链接」、「给我链接」时：阅读 `references/lark-apps-publish.md`，将你的 html 文件发布成一个 doubao-html 网页，此时无需交付 html 文件，仅需使用 present_files 交付发布后的 doubao-html 链接。 - **最终给用户的回复不要过长**：最重要的产物是你最终生成的 html 产物，而不是给用户的最终回复，所以在交付了 html 产物后的最终回复不应该太长，**不能超过300字，也不能超过 8 行**，只需要简单介绍一下你生成的 html 产物即可 - **修改、参考已发布的 doubao-html 网页**： - 当用户给你提供了一个 doubao-html 链接（形如 `https://{xxx}.aiforce.cloud/app/app_{xxxxxxx}/`），并希望基于此修改或新建时，阅读 `references/lark-apps-publish.md`。先用 `lark-cli apps +get --app-id <id>` 看 `app_type`：`html` / `modern_html` 是单页 HTML，下载源码、修改、重新发布即可；其他类型使用 `doubao-app-builder` 技能。 **改产物**：直接改任务目录里的原文件。 - **要有退路**：修订前先把当前版本复制到 `_backup/`（如 `_backup/index-v1.html`）。`_backup/` 不属于交付产物。 - 本地文件丢了就如实告知并请用户重新提供，**禁止凭记忆重造**；回答关于产物的提问同理，读文件后答，读不到不编。 - **小改动直接改**（改文案、调样式、换配色、修 bug）：不重读本文档和 reference，不重新推导视觉方向。 ## 页面自检 **交付前跑一次自检，改动后再跑一次**: 使用且仅使用`scripts/shot.py`脚本自检，若自检脚本执行失败，可以跳过自检、直接交付。禁止使用任何其他校验方式：包括但不限于 Browser Use、artifacts-preview skill，防止进入 Debug 螺旋。禁止使用 **artifacts-preview skill** ```bash python3 <SKILL_DIR>/scripts/shot.py <html_path> ``` 一次调用同时产出桌面（1440×900）与移动（390×844）两张 full-page 截图（默认 JPEG，宽度压到 1000px）。主图过 800KB 时脚本会自动切片输出（默认 3200px/片），报告里的 `slices` 字段列出分片路径、`sliceHint` 说明切片原因。同时把 JSON lint 报告打到 stdout，触发的每个规则都附带对应 `<field>Hint` 字段说明含义、修法与豁免情形——按 hint 处理即可。 **跨视口对比**：脚本还会把桌面 / 移动的图表容器尺寸做匹配，若某个图表在桌面正常、在移动端却没占到视口宽度的 65%（典型：`width:X% + inline-block` 双栏没在媒体查询里堆叠成单栏），会以 `responsiveChartIssues` 报出。这类 case 桌面截图完全正常，只在移动端表现为「空图 / 一根线 / 坐标轴叠一起」，肉眼只看桌面截图看不出来。**触发时必须核对移动截图**。 **自我检查并确认**下所有图片路径是静态写在 html 的 `src` 属性和 `CSS url()` 里的。否则如果它是经 JS 生成的，会导致发布之后图裂 **按用户当前端判断看对应那张**：用户处于电脑端则核对桌面截图，处于手机端则核对移动截图。判断不出端时则默认检查电脑端。 - 输出目录默认 `<html 所在目录>/_shots/`，不属于交付产物，**无需删除**——删目录会触发权限确认、打断交付。 - 只想看一屏用 `--only desktop`。 - 脚本内部已处理常见坑：`.rv / .fade / [data-aos]` 等滚动揭示元素强制显现（避免 `opacity:0` 截空白）、关掉 `scroll-behavior:smooth`、滚一遍触发 lazy 图片、`networkidle` 不可达时退回 `domcontentloaded`——**不需要另写截图脚本再走一遍**。 **看报告的次序**：先看 lint 各字段（`consoleErrors` 优先，其他布局/交互字段规则报出来基本都是真的，触发时看对应 `<field>Hint` 处理），→ Read 截图做视觉核对。默认先 Read 主图；主图因太大被过滤或读失败，再按顺序 Read `slices` 里的分片；不要一上来就把主图和所有分片都读一遍。视觉有疑点、报告分辨不出细节（颜色、字体渲染）时，再针对性截一屏；先用报告定位到具体元素/错误、改代码，改完重跑 `shot.py`。 ## 外部资源 **JS 库统一走 jsDelivr**：`https://cdn.jsdelivr.net/npm/<包名>@<版本>/…`。故障时的备用镜像是 **cdnjs**（`https://cdnjs.cloudflare.com/ajax/libs/<lib>/<ver>/…`，Cloudflare 官方运营，同版本文件字节一致）。**禁止** bootcdn、staticfile、polyfill.io（均有供应链投毒历史），unpkg 不作首选。 **字体走自托管镜像** `https://miaoda.feishu.cn/fonts/css2?family=…`：查询语法与 Google Fonts 的 `css2` 端点完全一致，返回的 `@font-face` 也指向自托管 CDN，两跳都不经过 Google。**不直连** `fonts.googleapis.com` **/** `fonts.gstatic.com`（部分地区不可达）。多字族就重复写多个 `family=`，例如 `<link rel="stylesheet" href="https://miaoda.feishu.cn/fonts/css2?family=Noto+Serif+SC:wght@400;600;700;900&family=Noto+Sans+SC:wght@300;400;500;700&display=swap">`。每个 `font-family` 都要带完整的系统字体 fallback 栈，字体加载失败时页面仍然成立。 ## 图像素材图片素材能显著提升产物美观度，不要默认用纯 CSS / SVG 撑起全部视觉。 **载体选型**：图标、状态标记、导航符号、简单示意图、数据图表属于符号 / 信息型，用内联 SVG 或 CSS。人物、角色、动物、具体物体、产品情境、真实场景、hero 主视觉、章节题图、叙事插画属于具象 / 氛围型，**必须用真实图片**——除非用户明确要矢量插画，禁止用手写 SVG 或 CSS 几何图形代替依赖形象可信度的具象画面。「简单图表优先使用 Echart 来进行生成，而无需使用 SVG」只适用于数据可视化，不得扩展到人物、场景和插画。 **来源按序**：① 用户提供和项目已有的素材，始终第一优先，不要擅自用生成图替换；② 图片生成能力，没有可用素材时的默认选择，prompt 写清风格、构图、配色，使产出与视觉方向一致；③ 外部检索，仅当要忠实呈现真实人物、产品、地点、Logo 等事实对象、生成会失真造假时才用。网络图片需要先下载到本地并**用读图能力实际看过**——内容对得上、清晰完整、无水印、不是防盗链占位图，确认通过才上传引用；看不了或不符的换图或改用生成。 **来源偏好**：尽量使用用户提供的图片、项目已有的图片、以及搜索到的真实相关的图片，而不是工具生成的图片；假设这些图片不够时，你可以使用生图生成的图片进行补充 **使用图片的比例控制在 3:4 ~ 21:9**（竖版到宽条形）：Banner / Hero 用 16:9 或 21:9，章节题图 3:2，方形插图 1:1。更极端的比例（1:5 长条、9:16 竖屏）可能会导致图片在不同设备上显示不全或出现大片空白区域。 **裁切与呈现**：用 `cover` 或固定高度前，先确认任务要求看见的主体、文字、标签不落在裁切区——竖图放横框时先用 `object-position` 把主体框住，主体横跨整张图、怎么调都保不住时才改用自然比例或 `contain`。hero、banner、纯背景用 `cover` 填满即可。 ## 内容要求 **数据保真**：用户给了源数据时，每个数字和结论都要从源数据实际算出、可追溯，不目测、不凑整、不编造。 **数据附件要获取下来并分析**，但**不要把数据转成** `const RAW_DATA = [...]` **固化进 JS**——那样用户换一份文件页面纹丝不动。数据能从 URL 取到就运行时取，确实取不到时才固化，并在交付说明里讲清。 **内容取舍**：不加与目标无关或没有依据的内容；内容不足以成页时合并、重构或要材料，不靠放大留白撑页。当有大量信息需要展示时，主要信息和次要信息需要重点鲜明，一个逻辑连贯的模块闭合在一屏内是更好的选择，必要时添加筛选与搜索能力。 **硬性规格逐条对照**：页数、画幅、必含模块，交付前自查。 **时间演进优先用时间轴**：涉及阶段、演进、里程碑、前后对比、路线图的内容，默认使用时间轴，而非项目符号列表或纯段落；每个节点承载：时间、事件名、一句话说明（可选）、（可选）关键指标或图标，让单个节点即可独立传达信息，注意时间轴节点与连线应该适当对齐。时间轴和附着在其上的图标（比如圆点或方块）的中心必须实现像素级对齐（0px误差）。并且额外注意时间轴的文字和轴线、文字和图标不要重叠。推荐用 **grid 三列（时间 / 轴 / 内容）** 的形式实现时间轴：圆点用真元素放中列、`justify-self:center` 交给布局引擎居中，轴线用 `calc()` 从列宽变量推出（横向时间轴同理，三列换三行、用 `align-self:center`），确保节点与轴线对齐，且无需手算坐标。 **表格要显式给列宽**：多列表格加 `table-layout: fixed`，并给**每一列**都写宽度、加起来正好 100%（`<colgroup><col style="width:25%">` 或写在 `th` 上）。漏写一列，`auto` 布局就会把它压到一字宽、中文逐字折行，行高被撑到半屏高，同行其余列跟着变成大片空白。 ## 图表及其交互设计方法 **图表服务于内容理解与判断**：依据任务和数据决定图表类型、数量与组合。图表呈现关系与证据，文字只写图表未直接呈现的解读或判断，**禁止把图表标签照抄一遍**。图表首选 ECharts；仅当其无法满足所需表达或交互时，再使用 D3 或 SVG。 **设计图表及其交互前，统一从 [references/chart/atlas.md](references/chart/atlas.md) 开始**：先确定图表选型与信息组织，再按其中的指引选读图内交互或多视图体验参考。 ## 网页交互设计 **禁止僵尸按钮**：视觉上像能点的元素——按钮、导航项、卡片入口——必须有真实的 click handler、跳转或占位反馈（如 toast 提示"演示中"）。禁止 `<button>` 无 `onclick`/`addEventListener`、`<a>` 无 `href`（或 `href="#"` / `href="javascript:void(0)"` / `href="javascript:;"` 却没实际 handler）、`<div class="nav-item">` 只挂 `cursor:pointer` 却什么都不绑——这些是原型页里最高频的 slop，要么给每个入口挂真实切页/toast，要么不做这个按钮，**宁愿不要按钮也不做僵尸按钮** ## 视觉设计 **先认媒介，别默认做成网页**：HTML 只是载体，产物形态各不相同——信息图、长图、研报、看板、设计稿、动画、游戏各有各的表达惯例。只有真在做网页时才用网页那套语汇（顶部导航、hero、footer、等宽卡片栅格、底部 CTA 区）；其余形态套上网页壳子就是最典型的 slop。先想清楚这次的媒介是什么、那个领域的行家会怎么排它，再往下走。需要在既有色板上扩色时用 oklch 派生——固定 hue 调 lightness / chroma，或沿同一 L / C 轴换 hue——不要凭空发明一个新 hex 塞进去。动手前读 `references/design/frontend-design.md` 确立视觉方向：有品牌或既有 UI 就对齐它的视觉语言，从零起步就从主题和材料里立一个契合的方向。已给参考图、品牌体系、设计规范或媒介 reference 时以它们为准。方向实在推不出、项目又是从零起的，先问清调性、受众、颜色、情绪——**在推不出方向时硬选，slop 就是这么来的**。字体选少量但与主题匹配的，层级靠字号、字重、行长和语义断行建立，不靠堆字体数量。背景与配色不局限于纯黑纯白，可以按内容属性和叙事节点变化，但一致性要来自共享色板和明确的颜色关系，不是逐页随机换色；强调色数量克制、同属一个体系。视觉丰富度服务内容：既不堆无信息价值的装饰，也不把「克制」做成大量留白加同一种构图。 **禁止无意义留白与失衡布局**：页面各区块须在视觉上均衡分布，禁止出现大面积无内容留白、单侧堆积、上重下空或下重上空等失衡结构；留白是用来服务于分组、呼吸或强调，不得用于填充版面。特殊布局设计除外，在特殊设计当中可以豁免。卡片组在**每个断点**的列数都不能让最后一行只剩 1 个（`N % C == 1`）——4 张走 4 → 2 → 1、跳过 3 列，别留 3 + 1。 **避免 AI slop**：滥用渐变、圆角＋左边框强调容器、被用滥的字体（Inter、Roboto、Arial、Fraunces）。 **做 hero / signature element / 复杂动效 / Canvas / WebGL / 进阶排印 / 材质纹理 / 地图 / 音频 / 音画同步 / 数学公式时先读 `references/design/visual-techniques.md`**——里面有动效工具链（IntersectionObserver / GSAP / Lottie / View Transitions / Scrollama / CSS scroll-timeline）、Canvas/WebGL 选型（three.js / p5.js / matter.js）、进阶排印（variable font / background-clip / SVG textPath / feTurbulence）、材质纹理层（grain / duotone / halftone）、地图（Leaflet / MapLibre / D3-geo / Deck.gl + 免费瓦片源）、Web Audio（Tone.js / 原生 AudioContext / sonification）、动画+声音协同（音频主时钟、三种协同模式、user gesture 门槛、mute 与 reduced-motion 双通道）、KaTeX 数学公式，以及每一层对应的 slop 红线（毛玻璃、glow border、粒子网背景、data-aos 全站铺、Leaflet 蓝大头针、Mercator 全球图、rainbow 色板、音频自动播放、音乐可视化跳舞背景等）。 **设计 3D 场景读 `references/design/3d-design.md`**，掌握材质、阴影、光照、运镜的设计方法。 **不用 emoji**：尽可能不要使用任何 emoji，也不作图标、不作装饰、不放进数据，除非用户品牌资产明确包含。需要图标体系时用内联 SVG（`<svg viewBox="0 0 24 24">`）建立风格连贯的图标语言。 **要有 favicon**：用 SVG 或 AI 生图，为产物搭配一个合适的 icon，内联进 HTML。在既有 UI 上增补时，先理解并遵循它的视觉语汇：文案风格、配色、hover 状态、卡片布局、密度。 ## 参考文档地图 ### `references/` | 文档 | 何时读 | | --- | --- | | [`lark-apps-publish.md`](references/lark-apps-publish.md) | 用户要「发布」「可访问的链接」，或给了 doubao-html 链接要基于它改 | | [`windows-compat.md`](references/windows-compat.md) | SystemPrompt 出现 `Computer OS: Windows`——**必须完整 Read**，否则大面积报错 | ### `references/design/` | 文档 | 何时读 | | --- | --- | | [`frontend-design.md`](references/design/frontend-design.md) | **动手前必读**，确立视觉方向 | | [`visual-techniques.md`](references/design/visual-techniques.md) | hero / signature element / 复杂动效 / Canvas / WebGL / 进阶排印 / 材质纹理 / 地图 / 音频 / 音画同步 / 数学公式 | | [`3d-design.md`](references/design/3d-design.md) | 设计 3D 场景（材质、阴影、光照、运镜） | ### `references/chart/` | 文档 | 何时读 | | --- | --- | | [`atlas.md`](references/chart/atlas.md) | **做图表与图表交互的统一入口**：先定选型与信息组织，再按其中指引选读下面两份 | | [`reading-interactions.md`](references/chart/reading-interactions.md) | 常规读图、固定比较、总览查看某个对象的明细（由 atlas 分流，不单独作入口） | | [`experience-examples.md`](references/chart/experience-examples.md) | 从同一批记录筛群体做多维比较，或明确的教学实验（同上） |