Communitygithub.com

HTML解释器页面构建指南

指导AI代理如何规划、构建或修改“HTML解释器”页面,确保输出可直接使用的副本或脚本。适用于需要创建这种特定风格页面的新任务。

HTML解释器页面构建指南 是什么?

该技能为AI代理提供了一套严格的、文档化的流程,用于创建和交付“HTML解释器”页面。这些页面是高度结构化的HTML文档,用于向开发人员解释复杂的软件流程、架构或问题,设计目标是使读者能够快速通过泳道图(swimlane)理解流程,而无需阅读冗长的段落。技能文档详细规定了项目的所有文件资产(如模板、设计参考、编写指南和可播放泳道图脚本),并定义了页面的三类核心链接:文件链接、跳转链接和同页章节链接。它强制要求页面始终保持深色主题,并遵循“极简主义”原则,仅包含用户明确请求的内容,禁止添加任何无关的总结、表格或备注。该技能深入阐述了如何根据不同类型的用户请求(如“解释问题”、“实现功能”、“了解原理”)来决定页面应包含的章节和泳道图类型。泳道图是该技能唯一允许的图表形式,并且支持可交互的“可播放”版本。工作流程包括通过搜索引擎建立主页面与解释器页面的关联、从模板创建文件、填充内容、绘制并验证图表,以及执行详尽的发布前检查清单,最终提供可直接粘贴至浏览器的文件路径。

兼容平台~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/frhn-xo/html-explainer/tree/HEAD/skills/html-explainer

在你喜欢的 AI 中提问

打开一个已预加载此 Agent Skill 的新对话。

文档

HTML解释器页面

用户会在浏览器中阅读这些页面,并通过Cmd+点击直接跳转到VS Code中的相应位置。用户通过泳道图理解流程的速度远快于阅读段落文字,他们希望每个页面能精确回答所问问题,不多不少。

本技能包含的文件

  • assets/template.html:每个页面的起点。复制该文件,切勿从头编写新页面。
  • references/DESIGN.md:每个页面都遵循的设计规范,始终采用深色主题,所有链接均为蓝色药丸样式(references/page.md,“外观”)。当页面需要某个颜色或模板中未包含的元素时,请阅读此文件。
  • references/page.md:定义页面文件名、位置、侧边栏、文件链接、任务章节、链接页面章节、主页面和解释器页面。创建新页面或调整结构时请阅读此文件。
  • references/writing.md:问题章节及所有散文内容。撰写文本前请阅读此文件。
  • references/diagrams.md:泳道图的外观及如何检查。绘制或编辑任何图表前请阅读此文件。
  • references/playable.md、assets/player.js、assets/player.css:可播放的泳道图。当用户提到“可播放”时,或编辑包含div.player的页面时,请阅读这些文件。

外观

每个页面均遵循references/DESIGN.md,始终采用深色主题,所有链接均为蓝色药丸样式以突出其可点击性:文件链接使用下划线,页面跳转链接使用↗,同页章节链接不使用标记(references/page.md,“外观:DESIGN.md,始终深色”和“三种链接类型”)。模板已实现这些样式。每个图表都位于一个可调整大小、缩放和拖动的面板中(references/diagrams.md,“图表块”)。

保持页面极简

页面只包含用户所问的内容。每一个额外的章节、表格或备注,都是用户为了找到答案而必须阅读过去的内容。

  • 章节: 只包含请求所需的章节。一个泳道图搭配简短段落构成一个章节。切勿添加用户未要求的任何章节:无总结、无清单、无“原因”章节、无过往决策记录。
  • 表格: 仅当用户明确要求时才使用表格。优先使用段落和泳道图。
  • 图表下方: 不留任何内容。无文件列表、无备注、无“未绘制”行。如果需要一句话来解释图表,应将其放在图表的段落之前。

请求获取哪些章节

根据问题调整页面结构:

  • “问题是什么”、调试、修复错误: 首先放置问题章节(references/writing.md),包含一个描述错误的泳道图(在主页面中,使用可播放版本,references/playable.md)。然后放置解释所需的任何后续泳道图。

  • 实现功能或修复错误,且任务已讨论完毕: 在问题章节正下方放置任务章节(references/page.md,“任务章节”)。当用户仍在研究问题时,不应有任务章节。

  • “这是如何工作的”、“这个项目是关于什么的”: 无问题章节,无任务章节。放置一个描述流程的泳道图,并附上简短段落作为辅助。

  • “我该如何构建类似的东西”: 一个章节:包含通常的泳道图、可以添加的额外功能以及如何继续。

  • 任何与其他页面链接的页面(主页面及其解释器,或用户要求链接的页面):在页面最底部添加链接页面章节(references/page.md,“链接页面章节”)。

其他情况:使用最少的章节来回答问题。

图表:仅限泳道图

有两种图表类型,且仅有两种:

  1. 泳道图: 流程图,每个角色或系统对应一个盒子,步骤位于执行该步骤的盒子内部,当工作流转时箭头在盒子间移动(references/diagrams.md)。
  2. 可播放泳道图: 同上的泳道图,但附带重置/后退/下一步/播放按钮,每次按下一个箭头,下方显示说明文字(references/playable.md)。“可播放”、“可播放泳道图”、“可播放图表”和“可播放前后对比”均指此类型。“泳道图”单独使用时指普通的泳道图。

其他任何对图表的请求(“一个Mermaid图表”、“画出流程”、“一个这样的图表”)均使用泳道图。

工作流程

  1. 这是否为主页面的解释器页面? 在工单的文件夹中搜索请求中的独特短语,即使用户仅粘贴了某个项目的文本且未命名主页面也要搜索。如果匹配,则新页面是该主页面的解释器:使用主页面的文件名前缀,并在同一次更改中双向链接(references/page.md)。
  2. 创建文件(references/page.md,“文件”),从assets/template.html复制而来。填充{{…}}占位符,并将localStorage键toc-open-CHANGE-ME更改为该页面唯一的键值。
  3. 决定章节:根据“请求获取哪些章节”决定,并只编写这些章节。
  4. 绘制泳道图(references/diagrams.md)。在渲染之前,列出相关代码中的所有循环、分支、失败路径和提前返回路径,并检查每个路径是否都已绘制。
  5. 链接每个文件引用,并使用#L<line>指定行号。检查每个路径是否存在,且目标行确实包含文本所声明的内容。
  6. 运行下面的检查项, 然后在聊天中回复页面的链接(见下文)。如果代码的任何操作未在图表中体现,请在回复中说明。

完成前需要检查的项目

  • 页面仅包含请求所需的章节:无问题章节除非是解释问题,无任务章节除非任务已讨论,无表格除非被要求,图表下方无内容。
  • 若页面解释某人所说或所想,其第一句应以用户会使用的词汇表述该人的意图(references/writing.md,“解释某人意图”)。
  • 页面保持模板外观:始终深色,所有颜色来自references/DESIGN.md,所有链接为蓝色药丸样式并带有其标记,未添加prefers-color-scheme浅色主题(references/page.md,“外观”)。
  • 图例标注含义而非颜色(例如“出错位置”,而非“赭色 = …”);页面无自定义颜色列表(references/page.md)。
  • 每个图表均为泳道图:页面无sequenceDiagram、stateDiagram、classDiagram或其他图表类型。
  • 使用mermaid-cli渲染每个图表并查看生成的PNG图片(references/diagrams.md,“渲染以检查”)。页面加载时不能有Mermaid语法错误。
  • 每个发送、写入、调用或读取的盒子,其文本中应说明发往或来自何处,且箭头应指向对应系统的盒子。每次对其他系统的调用应为一个向外箭头,如果下一步骤需要使用该回答,则需加上一个返回箭头。
  • 泳道图的泳道:在源代码中搜索[" "]和ghost,应无匹配项。在PNG中,没有盒子超出其步骤所需尺寸。
  • 可播放泳道图:在浏览器中从头到尾逐步执行并返回。
  • 每个侧边栏的href和data-href应指向页面上的一个id,且每个文件链接的路径相对于页面存在。
  • 解释器页面:该主题的主页面应链接到解释器页面,且解释器页面的开头应链接回主页面。
  • 链接页面:每个页面应在“链接页面”章节中列出其他页面,该章节位于页面末尾,且每个链接指向一个现有文件。
  • 更改任务状态后:使用grep命令列出每个任务的复选框类名和标签,所有已完成任务外观应一致(references/page.md)。
  • 由自动化打开的浏览器标签通常位于后台(document.visibilityState === "hidden"),因此滚动事件不会触发。通过在每个scrollIntoView()后调用markActive()来测试滚动监听,不要断定其已损坏。

在聊天中提及页面

每当聊天回复提到一个HTML页面时,应提供两行用户可以直接粘贴到浏览器地址栏的内容,每行独占一行:

file:///Users/<your_username>//_/.html

/Users/<your_username>//_/.html

第一行为完整的file:/// URL,第二行为磁盘上的绝对路径。每一行内不能包含其他内容:无散文、无反引号、无Markdown链接、无项目符号、无>块引用。如果需要,可以在上一行添加简短标签(例如“粘贴到您的浏览器:”)。若指代某个特定章节,请在确认id存在后向URL添加#id。聊天中的代码文件保持常规的相对链接。

原因: 相对链接会在VS Code中打开HTML源代码,而file:///链接会在浏览器中打开渲染后的页面。隐藏在一句话中或包裹在Markdown中的URL需要手动提取。

相关技能