html-explainer

HTML 讲解页

先选择分支，再选择模型。以指定角色收集证据、组装内容、进行验证，并检查可视化产物。派遣独立的资料整理工作器之前，必须通过 shared/references/model-preview.md 获取或复用且仅复用一个已批准的快照。

制作一个独立的 HTML 文件，依据代码库中的真实代码，向读者讲解一个实际系统的工作原理。

成果主线

• **结果：**一个独立的 .html 文件，内含 CSS、JavaScript 和 SVG，分三个深度讲解主题。
• **后续使用者：**用户及其队友，可直接在浏览器中打开文件——无需服务器，也无需构建步骤。
• **完成标准：**文件存在于约定路径，scripts/validate_explainer.py 以状态码 0 退出，并且文件已交付给用户或渲染给用户查看。
• **意图：**每个代码片段都是真实代码，因此页面值得信赖。读者可通过 path:line 栏跳转到代码库中的对应位置。

适用于所有工作的两条规则

• 原样引用，否则不展示——每个代码片段都必须从代码库中原样复制，并标注其 path:line 范围，否则不得出现在页面上。切勿凭记忆重写代码；删节时，须将来源栏标记为 (abridged)，且只能删去完整的行。如果某个说法无法追溯到文件，就用正文陈述，不要附代码片段；或者直接删去该说法。
• 逐层深入约定——页面必须支持三个深度：速览（可点击的全景图 + 一段式导读）、浏览（章节摘要、表格、图表）、深入（可展开的代码面板）。任何要点都不能只放在深入层；速览层也不能放过多内容。

工作流程

1. 确定范围

明确主题（一个子系统、服务或流程——将无关主题拆分为单独页面）、受众，以及页面必须回答的问题。

选择一种受众：_新手_需要全局图景和通俗导读；_实现者_需要扩展点和惯例；_审查者_需要了解边界、不变量和依赖方向。如果该主题已有概览页面，应复用其范围和证据，而不是重新探索。

当用户只说“解释 X 的工作原理”时，默认回答以下问题：架构、所用技术及其在代码中的位置、端到端数据流（输入 → 输出）、授权与租户隔离，以及日志记录和可观测性。遵循用户提出的任何补充要求。

默认输出路径：项目代码库中的 docs/<topic>-explainer.html。用户明确要求更新该产物，即授权在指定范围内编辑。如果现有目标文件未被选定为替换对象，则使用新路径，或询问用户要更新哪个产物；保留无关内容。

2. 收集证据

证据规则见 shared/references/grounded-evidence.md。阅读后，按其定义为每个子系统建立一份证据资料：包括机制、2–5 段带有准确 path:line 的原样代码片段、注意事项，以及代码注释中的经验教训；完成后再编写 HTML。

典型拆分方式（根据主题调整）：入口与基础设施 + 部署、主要处理流水线、数据访问 + 安全机制、可观测性与日志记录。仅当子系统相互独立、内容充实且需要实质性证据时，才派遣工作器整理资料。每个被选派的工作器都必须使用已批准的快照。嵌套工作器不得重新解析路由，也不得再派遣工作器。其他情况下，直接探索代码，并将范围限制在三层页面实际需要的内容：对于计划中的每个章节，拿到导读内容、图表所需事实和 2–5 段代码片段后就停止阅读。

资料的结构可作为参考，但发布的代码片段必须遵守“原样引用，否则不展示”规则：发布前，将任何看起来像经过改写的片段与源文件逐一核对。

3. 组装

将此技能目录中的 assets/template.html 复制到输出路径，然后替换其中的占位符槽位。先阅读 shared/references/html-page-conventions.md，了解自包含、三种深度、转义和验证要求。然后阅读 references/page-anatomy.md，了解各个槽位、SVG 图示的实现方式和代码片段转义规则。

重要的顺序要求：

• 大局图必须放在最前面，且每个主要框都带有 onclick="jump('sec-…')"，指向真实的 section id。
• 各节须编号，并按数据流排序（边缘 → 内部 → 数据 → 横切关注点），而非按发现顺序排序。
• 每个 .code 块都要有一个 .code-src 栏，标注仓库相对路径和行号（path:line）。
• 对代码片段文本中的 &、<、> 进行转义。TypeScript 泛型最容易出错——Promise<Foo> 必须写为 Promise<Foo>，否则浏览器会悄悄吞掉它。

4. 验证

运行确定性检查：

SKILL_DIR="<absolute path of the directory containing the SKILL.md you just read>";
python3 "$SKILL_DIR/scripts/validate_explainer.py" <output-file.html>

修复所有问题，直到退出码为 0。然后，如果有可用的浏览器界面，就渲染文件并确认大局图能正常绘制，且点击 jump() 后会打开对应的节；验证时遵循共享约定中的步骤（首屏以下使用 DOM 查询，而非截图）。

5. 交付

将文件发送给用户或渲染出来。摘要开头先写文件路径和导航方法（点击图示、展开面板）；每个节用一行列出。注明任何无法通过视觉方式验证的部分。

注意事项

• 档案中的代码片段若没有 path:line，就是改写内容的警示信号——重新阅读文件，或者删掉该片段（原文照录，否则不保留）。
• 密钥、在线主机名以及受管控或已编辑的内容：一律遵循共享证据合约第 6 节——注明密钥及其解析位置，并按代码库自身的方式进行编辑处理。
• 不要让页面只增加节数而没有深度：编号节数上限为 6–9 节；超出时应合并或拆分页。