agent-html

# Agent HTML 设计系统与组件化规范 本规范指导 AI Agent 如何生成**高信息密度、工业级质感、零外部依赖、双击秒开**的单文件 HTML。 --- ## 零、价值研判准则：何时用 HTML，何时坚决不用 (Judgment Rules) > **黄金法则**：*Markdown 是事实来源（Source of Truth），HTML 是人类决策与评审表面（Human Review Surface）。* 并不是所有输出都需要制作成 HTML。在动手前，AI Agent 必须先做价值研判： ### 1. 优先使用 HTML 的场景（具备以下任一特征）： - **空间性与多维性 (Spatial)**：宽屏数据大盘、左右双栏日志审查器、指标统计网格、密集状态看板； - **并行与对比性 (Parallel / A-B)**：基准 vs 挑战者、版本 Diff、模型评测、方案取舍矩阵； - **可交互与即时过滤 (Interactive / Filterable)**：包含数十条记录需毫秒级搜索、多 Tab 切换、手风琴折叠展开； - **供人类正式决策/归档 (Human Review Surface)**：正式架构评审、面试录用报告、技术复盘白皮书、发布日志。 ### 2. 坚决不要使用 HTML 的场景（留在终端 Markdown 即可）： - **线性单线条内容**：普通的问答、短解释、单次代码段说明（< 200 字）； - **纯终端命令/脚本**：用户需要立即在终端复制执行的 shell 命令； - **无空间结构的信息**：没有表格、没有对比、没有维度的流水账文本；强行输出 HTML 会打断用户终端心流并浪费 Token。 ### 3. 定了要用 HTML 之后，再定粒度 (Output Granularity) 这是**第二问**，和第一问同等重要。判错粒度会让用户拿到一份远超或远低于预期的东西： | 粒度 | 交付物 | 什么时候用 | | :--- | :--- | :--- | | **片段** | 单个组件卡片 / 一张图 / 一个表格 | 单点结论、单个对比，用户只想看一眼 | | **证据页** | 一页：KPI 概览 + 图表 + 关键明细表 | 2–3 个独立结论，需要摆证据但不需要完整叙事 | | **整页母版** | 七种通用母版之一（见「通用布局母版」一节） | 完整叙事交付：报告、复盘、评审、白皮书 | **默认档位是「证据页」，不是「整页母版」。** 用户说「分析一下这组数据」「帮我把这个看板做出来」但**没有**说「报告 / 白皮书 / 年报 / 复盘 / 评审」时： - **必须先交付证据页**（KPI + 最强的一张或两张图 + 关键明细），并在回复里用一句话提示「如需完整报告可以再展开」； - **不得**因为「数据很丰富」「结论很多」「用户说了分析」就自行升格为整页母版； - 反过来，用户明确要了「报告 / 白皮书」时，也不得只交付一张图。 拿不准时**选更细的粒度**：多给一张卡片，用户会自己说「再展开」；多给一份六章节报告，用户只会觉得被淹没。 --- ## 一、反模式规避清单 (Anti-Patterns to Avoid) 在生成 HTML 时，严禁出现以下常见 AI 反模式。分两组：**工程与交付层**（1–10，多数可被 `scripts/validate.mjs` 机器判定）与**数据与语义层**（11–17，多数只能人眼复核）。 ### 1. 工程与交付层（1–10） 1. **穿 HTML 外衣的普通 Markdown (Markdown in an HTML Trenchcoat)**：只是用 `<p>` 和 `<h1>` 包裹几大段流水账文字，完全没用上卡片、网格、状态徽章与 Callout。 2. **偷渡外网 CDN / 远程字体**：引入 Tailwind CDN、Google Fonts、CDN 脚本。在离线环境、内网机房直接白屏失效。 3. **交互死胡同 (Dead-end UI / No Copy-back)**：用户在页面上做了筛选、勾选或人工审核，但页面没有任何“复制结果”或“导出 Markdown”按钮，导致操作无法带回终端给 Agent。 4. **硬编码固定高度截断 (Fixed-height Truncation)**：设置 `height: 400px; overflow: hidden;`，在不同系统或字体大小下导致内容直接被切断。 5. **假装支持暗黑模式**：部分元素硬编码 `#ffffff` 或 `#000000`，在暗黑模式下文字或背景融为一体不可见。 6. **缺乏移动端/小屏响应式**：未加 `<meta name="viewport">` 或缺乏 `@media` 断点，分屏小窗口下横向滚动条爆炸。 7. **缺乏空状态处理 (Empty State)**：表格或列表在搜索无果时白茫茫一片，未提供“暂无匹配记录”提示。 8. **打印样式缺失 (@media print)**：报告类页面未做 `@media print` 样式优化，用户需要导出 PDF 时按钮乱飞。 9. **图表引入重型第三方库**：为了画简单折线图引入 Chart.js/ECharts（有断网白屏风险），必须坚持纯原生矢量 SVG。 10. **丢失关键元数据与数据精度**：过度美化排版却丢掉了关键错误码、时间戳、原始 ID 或 Trace，导致失去工程核验价值。 ### 2. 数据与语义层（11–17） 这一组是**「把图画错」而不是「把页面写坏」**。它们不会让页面报错、不会白屏，校验器也测不出来，但会让读者**得出错误结论**——比技术 bug 更危险，因为看不出来。 11. **面积/半径编码未开方**：用半径或圆点大小表示数值时，必须 `Math.sqrt(v)`。直接拿数值当半径会让**面积按平方增长**——2 倍的差异被画成 4 倍，系统性夸大差距。 12. **柱状图断轴**：柱的契约是**长度 ∝ 数值**，截断 Y 轴等于毁约。极端值场景的正确做法只有三条：① 让极端值冲天（最诚实）② 主图 + 放大镜小图 ③ 撕柱不撕轴（明说画不下）。 13. **聚合数冒充原始记录**：把「37%」摊成 37 个点是可以的，但**必须在副标题或底注写明 `1 点 = 1 个百分点`**；不许为了凑密度编造不存在的个体记录。 14. **取整不认账**：占比取整后加总不足 100（如 49+27+14+5+3 = 98）时，底注写明「另外 2% 被四舍五入吃掉了」。**不凑假数据把它补到 100。** 15. **颜色无数据含义**：禁止「拿到五个颜色平均撒到所有元素上」。颜色必须连接真实维度——序数梯接数值、分类色接类目、强调色只给唯一主角——并在底注写清它在编码什么。去掉颜色后，图的结构仍应读得懂。 16. **演示数据不确定**：演示/占位数据禁用 `Math.random()`，必须用确定性伪随机。**刷新两次必须长得一样**，否则截图、录屏、回归对比全部失效。 17. **给无真实记录的元素加交互**：给纯装饰元素加 hover / 点击是欺骗。加交互前先问「这个元素背后有没有一条真实记录？」——完整判定流程见「交互」一节的**三问**。 > 📕 **失败记忆**：以上反模式的**成因、真实案例与复查方式**见 `references/failures.md`（12 条）。写新组件前先扫一眼——规范告诉你该做什么，失败记忆告诉你不要再重蹈什么。该文档末尾有一张索引表，诚实标注了哪些教训已经变成机器约束、哪些还只能靠人。 --- ## 二、为什么这样设计？(Design Principles & The "Why") 1. **为什么坚决追求纯单文件与零外部依赖（Zero-Dependency Standalone）？** - 很多可视化报告、用例审查工具常在内网机房、无公网访问的隔离环境（Air-gapped）、或本地离线存档中打开。 - 引入 Tailwind CDN (`cdn.tailwindcss.com`) 或第三方字体库，会在弱网下引发白屏（FOUC）、CDN 节点下线失效或公司 CSP 策略拦截。因此必须将精炼的 CSS 变量与极简微脚本直接内嵌。 2. **为什么严格采用 shadcn/ui 的 Zinc/Slate 中性色体系？** - 大模型在自由发挥时容易产生“AI审美漂移”——随机的大圆角、大面积刺眼渐变色、过大的无意义留白。 - shadcn 的核心是：**冷灰中性底色、精准 1px 微细浅色边框、高信息密度、语义化状态点（Green/Amber/Red）**。这种排版能让任何数据报表看起来都像资深前端工程师耗费数日精心调校过的专业企业级产品。 3. **为什么必须原生内置暗黑模式（Light / Dark Theme）？** - 工程师与运维人员大量在暗黑 IDE/终端环境下工作。通过 CSS 变量原生映射，仅需 5 行原生 JS 即可实现丝滑切换，零构建成本却能极大提升使用体验。 --- ## 三、七大通用布局母版与渐进式披露 (Progressive Disclosure) 不要从零手写完整页面。接到需求后，首先从以下 7 种**通用布局母版**中选择最贴近的骨架。支持中英文双语母版体系，根据用户输入语言对齐： - **英文场景**：参考 `assets/templates/en/<name>.html` - **中文场景**：参考 `assets/templates/zh/<name>.html` > 🗂 **本仓库的资产分三层，别搞混：** > > | 层 | 位置 | 是什么 | 怎么用 | > |---|---|---|---| > | **骨架（母版）** | `assets/templates/zh|en/*.html` | 整页版式的正本 | 复制整份作为起点，替换内容 | > | **零件（组件字典）** | `references/components.md` | 按钮/卡片/图表等片段的正本 | 按需取用单个片段 | > | **成文（案例）** | `examples/`（仅仓库） | 真实数据走完全流程、且通过全部门禁的成品 | **拿不准交付物长什么样就先看这里** | > > **交付给用户的永远是单文件成品**，是从母版或组件拼装出来的。 > **每个资产只有一个正本。** 同一段代码不允许在两处各存一份——两份手抄副本必然漂移（见 `references/failures.md` F-014）。发现重复时，保留一处、另一处改为指针。 > `examples/README.md` 逐条记录了那个案例示范了哪几条容易忘的规矩，包括一条**门禁测不出、只能靠人眼**的图表刻度错误（F-015）。 > > 📌 **本文件里所有相对路径都相对于本 Skill 的根目录**（即 `SKILL.md` 所在目录），不是相对于你当前的工作目录。安装到 `~/.agents/skills/agent-html` 后，`scripts/validate.mjs` 指的是 `~/.agents/skills/agent-html/scripts/validate.mjs`。 | 布局模式 | 读者时间 | 信息密度 | 核心交互 | 中文母版路径 | 英文母版路径 | 适用需求与核心结构 | | :--- | :--- | :--- | :--- | :--- | :--- | :--- | | **Report 报告**<br>(Document / Report) | 30s+ | 中 | 悬浮目录 ScrollSpy、折叠手风琴 | `assets/templates/zh/report.html` | `assets/templates/en/report.html` | **技术选型、架构审查、故障复盘、面试报告、需求说明、发布日志**。<br>结构：自适应宽屏容器（默认 1200px ~ 1280px，支持宽屏自适应扩展至 96%，避免宽屏下表格被挤扁）、悬浮目录（Sticky TOC with ScrollSpy）、核心结论 Callout、KPI 概览栏、多章节 `<details>` 折叠手风琴、一键复制为 Markdown 导出。 | | **Dashboard 数据面板**<br>(Dashboard & Data Grid) | <10s | 高 | 实时双重过滤、复制表格 | `assets/templates/zh/dashboard.html` | `assets/templates/en/dashboard.html` | **资源监控、用量大盘、考勤/调休管理、订单/任务流管理**。<br>结构：宽屏网格，顶部操作栏、4 列自适应 KPI 统计卡、原生 SVG 走势图与柱状图、实时双重过滤表格、一键复制表格 (MD)。 | | **Inspector 审查工作台**<br>(Master-Detail Workbench) | 逐条读 | 高 | Master-Detail 联动、人工裁决 | `assets/templates/zh/inspector.html` | `assets/templates/en/inspector.html` | **日志/Trace 审查、Prompt 调试器、JSONL 编辑器、配置管理**。<br>结构：视口充满（100vh），左侧条目列表过滤，右侧动态联动渲染选中条目详情、人工审查裁决条（Pass/Fix/Reject）、复制审查结论发回 Agent。 | | **Compare 对比**<br>(Side-by-Side Comparison) | ~30s | 中 | 并排对照、Delta 判定 | `assets/templates/zh/compare.html` | `assets/templates/en/compare.html` | **模型 A/B 测试、Prompt 改版前后对比、架构版本 diff、产品套餐/特性矩阵**。<br>结构：并排双栏卡片（基准 vs 挑战者）、核心裁决 Callout、量化差异对照表（Delta 胜负判定标签）、一键导出 Markdown。 | | **Timeline 时间线**<br>(Timeline & Postmortem) | 30s+ | 中 | 折叠诊断日志 | `assets/templates/zh/timeline.html` | `assets/templates/en/timeline.html` | **发布路线图 (Roadmap)、变更历史 (Changelog)、突发事件复盘 (Postmortem)**。<br>结构：左侧单轨垂直时间线、状态节点小圆点、精确时间戳与操作人 Tag、可展开诊断日志、一键复制时间轴为 Markdown。 | | **Kanban 看板**<br>(Triage & Agile Kanban) | <10s | 中 | 原生 HTML5 拖拽排序 | `assets/templates/zh/kanban.html` | `assets/templates/en/kanban.html` | **缺陷分类整理、需求优先级排序、任务状态流转**。<br>结构：4 列敏捷看板（Backlog, In Progress, Blocked, Done）、纯原生 HTML5 拖拽排序（零依赖）、一键复制分拣结果回 Agent 闭环。 | | **Review 代码审查**<br>(Diff Review) | 逐条读 | 高 | 行级发现项、逐文件裁决 | `assets/templates/zh/review.html` | `assets/templates/en/review.html` | **PR / 分支代码审查、补丁评审、重构前后差异说明**。<br>结构：原样粘贴 `git diff` 到 `<script type="text/plain" id="diffSource">` 即自动解析为统一 diff；发现项按「新版本行号」锚定并以行内评论呈现（blocker / major / minor / nit + 建议修改）；每个文件分段单选裁决（通过 / 评论 / 要求修改）；文件树过滤 + 空状态；Tabs 切换 diff 与发现项列表；一键复制审查结论回 Agent。 | > **用「读者时间」和「信息密度」选型，不要按行业词选型。** 母版名字里的「报告」「看板」「复盘」描述的是**版式性格**，不是使用场景限制——「时间线」可以承载个人生活数据，「对比」可以承载两个方案的取舍。选型看的是：读者愿意花几秒、内容有多密、需不需要特定的交互。 > ⚠️ **中英母版必须结构同构。** zh 与 en 是同一套骨架的两个语言版本，不是两个平行维护的模板；改动其一必须同步另一个。`scripts/validate.mjs` 的 `[ZH_EN_PARITY]` 会把「中文有而英文没有的 `<nav>` / `<aside>` / `<details>`」判为阻断。 > 💡 **组件字典查阅**：所有按钮变体、胶囊徽章、32 个矢量图标、原生纯 SVG 图表、Tabs、表单控件与交互脚本的完整代码，都在 `references/components.md`。**它是组件代码的唯一正本**——本文件不再重复任何组件代码。 --- ## 四、微 CSS 核心基座 (Micro-CSS Base) 在生成 HTML 时，务必将以下约 75 行 CSS 基座放入 `<head><style>` 中，它是所有组件质感一致的基石： ```css :root { --bg: #fafafa; --card: #ffffff; --card-fg: #09090b; --popover: #ffffff; --popover-fg: #09090b; --primary: #18181b; --primary-fg: #fafafa; --primary-hover: #27272a; --secondary: #f4f4f5; --secondary-fg: #18181b; --secondary-hover: #e4e4e7; --accent: #f4f4f5; --accent-fg: #18181b; --destructive: #dc2626; --destructive-fg: #fafafa; --muted: #f4f4f5; --muted-fg: #71717a; --border: #e4e4e7; --input: #e4e4e7; --ring: #18181b; --radius: 8px; --radius-sm: 6px; --radius-lg: 12px; --shadow-sm: 0 1px 2px 0 rgba(0, 0, 0, 0.05); --shadow: 0 1px 3px 0 rgba(0, 0, 0, 0.1); --shadow-md: 0 4px 6px -1px rgba(0, 0, 0, 0.1); --shadow-lg: 0 10px 15px -3px rgba(0, 0, 0, 0.1); --ok: #16a34a; --ok-bg: #f0fdf4; --ok-border: #bbf7d0; --warn: #d97706; --warn-bg: #fffbeb; --warn-border: #fde68a; --err: #dc2626; --err-bg: #fef2f2; --err-border: #fecaca; --info: #2563eb; --info-bg: #eff6ff; --info-border: #bfdbfe; /* 图表专用色（Tremor 风格）。语义固定，不可当作装饰色随机分配： 每个色相各承担一种数据含义，见「轻量原生图表规范」一节。 */ --chart-indigo: #6366f1; /* 主指标时序走势 */ --chart-emerald: #10b981; /* 正常 / 健康 / 增长 / 放行 */ --chart-amber: #f59e0b; /* 警戒 / 抖动 / 温和上升 */ --chart-rose: #f43f5e; /* 异常瓶颈 / 错误峰值 / 降级 */ --chart-violet: #8b5cf6; /* P95 / P99 峰值高亮 */ --chart-cyan: #06b6d4; /* 辅助对比时序 / 出向流量 */ --chart-slate: #64748b; /* 低优对比柱 / 中性刻度 */ } [data-theme="dark"] { --bg: #09090b; --card: #121215; --card-fg: #fafafa; --popover: #121215; --popover-fg: #fafafa; --primary: #fafafa; --primary-fg: #18181b; --primary-hover: #e4e4e7; --secondary: #27272a; --secondary-fg: #fafafa; --secondary-hover: #3f3f46; --accent: #27272a; --accent-fg: #fafafa; --destructive: #ef4444; --destructive-fg: #fafafa; --muted: #18181b; --muted-fg: #a1a1aa; --border: #27272a; --input: #27272a; --ring: #d4d4d8; --shadow-sm: 0 1px 2px 0 rgba(0, 0, 0, 0.5); --shadow: 0 1px 3px 0 rgba(0, 0, 0, 0.5); --shadow-md: 0 4px 6px -1px rgba(0, 0, 0, 0.5); --shadow-lg: 0 10px 15px -3px rgba(0, 0, 0, 0.5); --ok: #4ade80; --ok-bg: #052e1680; --ok-border: #166534; --warn: #fbbf24; --warn-bg: #451a0380; --warn-border: #854d0e; --err: #f87171; --err-bg: #450a0a80; --err-border: #991b1b; --info: #60a5fa; --info-bg: #17255480; --info-border: #1e40af; --chart-indigo: #818cf8; --chart-emerald: #34d399; --chart-amber: #fbbf24; --chart-rose: #fb7185; --chart-violet: #a78bfa; --chart-cyan: #22d3ee; --chart-slate: #94a3b8; } *, *::before, *::after { box-sizing: border-box; margin: 0; padding: 0; } body { font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, "Helvetica Neue", Arial, sans-serif; background-color: var(--bg); color: var(--card-fg); line-height: 1.5; -webkit-font-smoothing: antialiased; } .card { background: var(--card); border: 1px solid var(--border); border-radius: var(--radius); box-shadow: var(--shadow-sm); overflow: hidden; } .btn { display: inline-flex; align-items: center; justify-content: center; gap: 6px; font-size: 13px; font-weight: 500; height: 34px; padding: 0 12px; border-radius: var(--radius-sm);