SuperAPI AI 工具集

html-artifacts

通用与其它

查看项目

更新于 10-16 15:57

技能介绍

用途

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。