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,“链接页面章节”)。
其他情况:使用最少的章节来回答问题。
图表:仅限泳道图
有两种图表类型,且仅有两种:
- 泳道图: 流程图,每个角色或系统对应一个盒子,步骤位于执行该步骤的盒子内部,当工作流转时箭头在盒子间移动(
references/diagrams.md)。 - 可播放泳道图: 同上的泳道图,但附带重置/后退/下一步/播放按钮,每次按下一个箭头,下方显示说明文字(
references/playable.md)。“可播放”、“可播放泳道图”、“可播放图表”和“可播放前后对比”均指此类型。“泳道图”单独使用时指普通的泳道图。
其他任何对图表的请求(“一个Mermaid图表”、“画出流程”、“一个这样的图表”)均使用泳道图。
工作流程
- 这是否为主页面的解释器页面? 在工单的文件夹中搜索请求中的独特短语,即使用户仅粘贴了某个项目的文本且未命名主页面也要搜索。如果匹配,则新页面是该主页面的解释器:使用主页面的文件名前缀,并在同一次更改中双向链接(
references/page.md)。 - 创建文件(
references/page.md,“文件”),从assets/template.html复制而来。填充{{…}}占位符,并将localStorage键toc-open-CHANGE-ME更改为该页面唯一的键值。 - 决定章节:根据“请求获取哪些章节”决定,并只编写这些章节。
- 绘制泳道图(
references/diagrams.md)。在渲染之前,列出相关代码中的所有循环、分支、失败路径和提前返回路径,并检查每个路径是否都已绘制。 - 链接每个文件引用,并使用
#L<line>指定行号。检查每个路径是否存在,且目标行确实包含文本所声明的内容。 - 运行下面的检查项, 然后在聊天中回复页面的链接(见下文)。如果代码的任何操作未在图表中体现,请在回复中说明。
完成前需要检查的项目
- 页面仅包含请求所需的章节:无问题章节除非是解释问题,无任务章节除非任务已讨论,无表格除非被要求,图表下方无内容。
- 若页面解释某人所说或所想,其第一句应以用户会使用的词汇表述该人的意图(
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需要手动提取。