html-artifacts

HTML 产物

Markdown 是 Agent 输出的默认格式。但对于超过几句话的内容，它并不理想：无法并排展示两个选项、绘制真正的图表、实现交互，也无法作为页面分享。当产物本身就是交付成果时，读者会对它采取行动：仔细阅读、分享、交给实现人员，或粘贴修改后的内容。此时应使用 HTML。

这项技能取决于判断，而不是切换格式。下面的大部分内容都在讲如何做出恰当判断并检查结果，因为模型已经知道如何编写 HTML。

符合以下任一情况时，优先使用 HTML

• 比较。 读者需要权衡两个或更多选项。并排展示优于上下堆叠。
• 空间信息。 差异、调用图、模块图、流程图、时间线、前后对比。位置本身承载着意义。
• 交互很重要。 缓动曲线、参数调整、状态机、模拟。读者需要亲自体验的内容。
• 参考资料。 需要非线性浏览：标签页、折叠区、边栏术语表、跳转链接。
• 颜色或层级承载意义。 严重程度、状态、语法、设计令牌、数据系列。
• 数据。 超过十几个数字、趋势、分布。可排序和筛选的表格或图表。
• 一次性编辑器。 读者要操作某个对象（拖动工单、切换标记、调整提示词），并需要将结果以文本形式取回。
• 需要分享。 面向领导的规范、供审阅者查看的 PR 说明、团队报告。人们会阅读页面；他们会快速浏览文件。
• 篇幅。 超过约 100 行 Markdown 时，导航和布局就值得采用。

以下情况保留 Markdown

• 回复是对话式的，或答案只有几句话。一个问题，一个答案，结束。
• 输出是代码、配置块、命令序列，或用户将要应用的差异。
• 用户正在快速迭代一次性内容（“只总结这个文件”“这个函数是做什么的”）。
• 文档会保存在 git 中，并在 PR 中持续进行差异比较。HTML 差异很杂乱。如果 HTML 视图有助于审阅，可以同时提供。
• 用户要求使用 Markdown、指定格式或“不要格式化”。

如果不确定，可以问自己一个问题：读者除了读一遍之外，还会对它做什么吗？ 如果不会，就用 Markdown。HTML 会消耗两到四倍的令牌，也需要更长时间；不要凭空制造使用场景。

通用规则

每个产物都必须满足以下所有要求。

1. 一个独立的 .html 文件。 CSS 放在 <style> 中，JS 放在 <script> 中，图片使用内联 SVG 或数据 URI。无需构建步骤。外部脚本只能来自目标界面允许的 CDN（参见 references/harness-mechanics.md），且只有在确实值得引入某个库时才使用。
2. 五秒内读懂。 在任何实质内容之前，先提供 <title>、一个标题，以及一段用于说明背景或概述内容的句子。
3. 真实布局，而非把 Markdown 换个样式。 对比内容应使用分栏布局。时间线应绘制出来。差异应以差异对比的形式呈现。如果页面只有标题和段落，那它本该是 Markdown。
4. 默认采用得体的设计。 排版舒适，每行 60 到 75 个字符，使用克制且能传达含义的颜色。不要使用渐变主视觉、表情符号标题，也不要为卡片网格而设计卡片网格。references/matching-your-style.md 中提供了基础 CSS 和应避免的设计特征。
5. 适配手机宽度和两种主题。 设置 viewport meta，使用相对单位，并确保布局可以换行。在 :root 中定义浅色主题变量，在 prefers-color-scheme: dark 和 [data-theme="dark"] 下重新定义，以同时支持系统偏好和手动切换。
6. 满足基本无障碍要求。 使用语义化元素、带标签的控件、键盘可操作的交互，并提供清晰可见的焦点样式；不能只靠颜色传达信息。检查清单见 references/accessibility-and-print.md。
7. 编辑器应能导出为文本。 这是不可妥协的要求。任何包含可操纵状态的内容，末尾都必须提供“复制为 Markdown / JSON / 提示词”选项。往返转换才是关键。
8. 交付前进行验证。 如果有浏览器可用（Claude Code、Cowork 或云端会话中的 Playwright 或 Chromium），则以无头模式渲染文件，在桌面和手机宽度下截图，检查控制台错误，并修复发现的问题。如果没有浏览器可用（Claude.ai 聊天、仅支持产物的界面或没有 shell），不要停下来，也不要道歉；改为执行 references/verify-before-delivering.md 中的逐项检查清单，然后交付。无论哪种情况，都要在用户看到产物前检查一次。

工作流

1. 决定。 执行上方两份清单。用一行说明你要制作什么，以及为什么使用 HTML。
2. 选择参考资料。 从下方索引中阅读匹配的文件。这些文件很短；如果请求跨越多个类别，就阅读两份。
3. 匹配用户的风格。 如果项目有设计系统、设计变量或前端设计技能，就使用它们。否则采用 references/matching-your-style.md 中的基础样式。
4. 起草。 先布局，再写内容，最后添加交互。预先填入用户提供的任何数据。
5. 验证。 遵循规则 8。修复问题后，附上路径或产物，并用一句话说明它是什么。

分类索引

如果请求涉及……	阅读……
选项比较、实施计划、确定方向前的探索	references/exploration-and-planning.md
带注释的差异、PR 说明、代码审查、模块图、“解释这段代码”	references/code-review-and-pr.md
设计令牌、组件表、模型图、动画和交互原型	references/design-and-prototypes.md
内嵌 SVG 图示、流程图、架构图	references/diagrams-and-illustrations.md
图表、仪表板、可排序和可筛选的数据表、指标	references/data-and-charts.md
状态报告、事故复盘、概念解说、学习材料	references/reports-and-research.md
幻灯片、方向键演示文稿	references/decks.md
一次性编辑器：分诊看板、标记切换、提示词调优器、标签工具	references/custom-editors.md
匹配现有视觉风格或设计系统；安全的默认选择	references/matching-your-style.md
无障碍与打印检查清单	references/accessibility-and-print.md
文件存放位置以及各界面的功能限制：Claude Code、Claude.ai artifacts、Cowork、已发布的 artifacts	references/harness-mechanics.md
交付前检查：无头和手动检查	references/verify-before-delivering.md

输出机制，简述

• 磁盘上（Claude Code、Cowork、云会话）： 在工作目录中使用描述性的 kebab-case 名称保存为 .html 文件，完成验证后，告知用户文件路径和打开方式。相关 artifacts 放在同一个文件夹中。
• Claude.ai artifacts： 使用单个 HTML artifact，而非 React，除非用户另有要求。遵守 artifact 沙箱规则：仅使用允许的 CDN，将存储视为不可靠，不使用相对链接。
• 已发布或共享的 artifacts： 可能具备运行时能力（持久化、实时数据）。仅在当前界面文档明确说明支持时使用；切勿自行假设。

各界面的详细信息见 references/harness-mechanics.md。

此技能不是什么

它并非“始终以 HTML 作答”。如果 Markdown 是更合适的形式，就使用 Markdown。难看的 HTML 不如优质的 Markdown，未经验证的 HTML 则两者皆不如。