用途
html-artifacts 用于决定何时将输出从 Markdown 切换为单个自包含的 .html 文件。其默认立场是:其他地方一律继续使用 Markdown。只有当“结构或交互是承重”的时候,才使用 HTML 输出。
何时使用(YES)
以下输出类型适合使用 HTML:
- 具有 3 个及以上维度的对比(选项 × 标准 × 取舍),并且能从可排序 / 可筛选表格中获益。
- 需要导航、决策面或可点击地图的复杂计划。简单线性计划仍用 Markdown。
- 带注释 diff、模块图或调用 / 数据流图的代码审查。
- 时间线、流程图、架构 / 系统图、ERD 式关系视图、概念图或信息图能比散文更清楚表达关系的视觉解释。
- 包含精确计数、验证矩阵、决策日志和“下一步”界面的长时间工作状态快照(参见 references/status-snapshot.md)。
- 一次性工具(交互式编辑器)——拖拽、滑块、实时筛选等,用户操作输入并导出决策(参见 references/interactive-editor.md)。
- SVG 流程解释器,用于 ASCII 或 Markdown 列表丢失空间关系的情况。
何时不使用(NO)
以下情况保持 Markdown:
- 简短回答、终端风格回复。
- 纯代码输出(返回代码块,不要包裹进 HTML)。
- 线性步骤、无需导航决策的简单计划。
- 已经能干净放进几段话的散文式总结。
- 用户明确要求 Markdown 的任何内容。
如果不确定,默认使用 Markdown。
输出路径
仓库的全局忽略规则(**/docs/.ai/)会将这些目录排除在 git 之外,除非强制添加。
| 意图 | 路径 | 跟踪 |
|---|---|---|
| 持久记录 | docs/.ai/artifacts/<slug>.html | 被忽略。如需跟踪,提示用户执行 git add -f <path>。 |
| 一次性工具 | docs/.ai/tools/<slug>.html | 被忽略。将决策导出回 Markdown 或任务列表后再丢弃。 |
若父目录不存在则创建:
mkdir -p docs/.ai/artifacts # 或 docs/.ai/tools
<slug> 取自当前计划、issue 或主题。使用 kebab-case,无空格,无时间戳。
格式规则
- 单文件。全部内联:HTML5、<style> 中的原生 CSS、<script> 中的原生 JS。无构建步骤。
- 无外部资源。禁止 CDN <script src=>、指向远程样式表的 <link href=>、@import url(http…)、<img src=https…>、运行时 fetch(...)、动态 import(...)。使用内联 SVG;必要时可用 base64 嵌入小位图。
- 除非项目已使用框架,否则不使用框架;若已使用则与之保持一致。
- 仅真实内容。使用来自提示、仓库、计划或命令输出的精确数据。不要 lorem ipsum、假指标、假时间线或占位行,除非它们被明确标记为示例。
- 避免默认 AI 美学。不要无端渐变、玻璃拟态、新拟态、emoji 标题、“✨”闪烁装饰。选择一个强调色、一个字体栈、克制的间距。
- 默认无障碍。使用真实标题、真实按钮、键盘可达交互、可见焦点状态、有标签的颜色 / 状态含义;如果提供深色样式,则使用 prefers-color-scheme。
- 默认响应式。在 360px 宽度下检查布局。不要依赖仅悬停控件、隐藏横向陷阱、过小标签或在移动端裁剪内容的固定高度。
- 动效保持可选。如果使用动画,遵循 prefers-reduced-motion,并确保状态变化在无动效时仍可理解。
- 无追踪、无遥测、无分析。
写入后自检
写完文件后、报告完成前,运行自检。将 <path> 替换为刚写入的文件(docs/.ai/artifacts/<slug>.html 或 docs/.ai/tools/<slug>.html):
rg -n "<script[^>]+src=|<link[^>]+href=|src=['\"]https?://|href=['\"]https?://|url\\(['\"]?https?://|@import|\\bfetch\\s*\\(|\\bimport\\s*\\(" <path>
任何匹配都必须移除(或证明其为惰性内容 / 示例文本,而非可执行标记)。
对于视觉、空间或交互 artifact,在报告完成前还需运行 references/visual-quality.md 中的检查清单。
语音交接(可选)
仅当用户要求语音,或向 /artifact 传入 --voice 时,才调用 speak 技能,并提供不超过 100 词的摘要。speak 技能通过已注册的 say MCP 服务器(mcp-tts)路由,并按 google → openai → elevenlabs → say 回退,因此可获得较好的云端语音,而非本地 say 默认值。
不要从此处直接调用 tts-notify.py——那是 Stop/Notification 钩子路径,不是 agent 原语。不要在未提示时调用任何语音路径;Stop 钩子已经会朗读回合完成,重复朗读很烦人。如果用户未要求语音,则把朗读文本块作为普通输出返回,让用户自行触发 TTS。
参考
- references/visual-quality.md——视觉分类、独立设计规则、无障碍 / 响应式检查,以及交接前检查清单。
- references/status-snapshot.md——长时间工作状态快照模板(时间线、计数、验证矩阵、决策日志、语音文本块)。
- references/interactive-editor.md——一次性编辑器模式(拖拽、滑块、导出为 Markdown)。
返回格式
写入文件后,告知用户:
- 仓库相对路径(docs/.ai/artifacts/<slug>.html 或 docs/.ai/tools/<slug>.html)。
- 如何打开(macOS 上用 open <path>)。
- 它是持久的还是一次性的;若持久,则给出 git add -f <path> 指令。
- 你朗读的任何语音摘要,或者——如果未请求语音——朗读文本块,以便用户自行触发 TTS。