html-doc

HTML 文档

将一份完整的 Markdown PRD 或技术设计转换为一个经过验证的静态 HTML 页面。Markdown 保持为规范版本。只改变呈现方式，不改变含义。

边界

• 接受现有 Markdown 文件或原样内联 Markdown。
• 仅支持 prd 和 design 两种文档类型。
• 对于 REQUIREMENTS.md，传入 --kind prd。对于 ARCHITECTURE.md 或 spec.md，传入 --kind design。
• 将 prd.md 归类为 prd，将 design.md 归类为 design。对于其他名称，使用请求指定的类型；如果类型不明确，则询问。
• 不要编写需求、决定设计方案、概述缺失内容或编辑源文件。
• 如果源文件只是粗略简报，请先使用合适的编写技能。
• 不要手动编辑生成的 HTML。应修改模板或渲染器，然后重新生成。
• 除非用户另行提出要求，否则不要发布或托管结果。

要求

生成需要 Python 3.11 或更高版本、Pandoc 3 或更高版本、Node.js 22.12 或更高版本以及 npm。技能目录中包含已锁定的 Mermaid 依赖树。

首次渲染 Mermaid 之前，运行：

npm ci --prefix <skill-directory>

所有生成和生命周期操作都使用此技能目录中的 scripts/html_doc.py。

工作流

1. 阅读并分类源文件

阅读完整的源文件。确认其大小不超过 2 MiB。根据请求或上述基本文件名映射确定文档类型。

将内容问题与呈现问题分开处理。如果 Markdown 自相矛盾、遗漏了必要决策或包含无效图表，请报告源文件的问题。不要擅自修正其含义。

2. 创建候选文件

对于文件源：

python3 <skill-directory>/scripts/html_doc.py render <source.md> --kind <prd-or-design> --out <output.html>

仅当基本文件名恰好为 prd.md 或 design.md 时，才可省略 --kind。省略 --out 时，将在同一目录下创建 HTML 文件。

对于原样内联 Markdown，通过标准输入传入，并同时指定类型和输出路径：

python3 <skill-directory>/scripts/html_doc.py render --inline --kind <prd-or-design> --out <output.html>

该命令会返回包含 candidate、output 和 token 的 JSON。它不会替换最终输出。保留这些确切值，以便验证和最终处理。

如果输出锁已存在，不要自动删除。它可能代表另一项待处理的渲染任务。报告其路径。只有确认该状态已弃用时，才使用 discard --force-stale。

3. 在真实浏览器中验证候选文件

将候选文件作为本地文件打开。不要将检查源代码视为浏览器验证。

检查以下各项：

• 桌面端：1440 CSS 像素；
• 平板端：768 CSS 像素；
• 移动端：390 CSS 像素；
• A4 和 US Letter 打印预览；
• 目录链接和章节目标；
• 从跳过链接到导航和文档链接的键盘顺序；
• 可见的焦点指示器；
• 一个 main 地标以及合理的标题大纲；
• DOM ID 唯一；
• 水平溢出、文字裁切、代码、表格和图表；
• 实用的图表替代文本和可访问的展开控件；
• 控制台错误和资源请求失败；
• 浏览器禁用网络访问时的运行情况。

将 main 中的规范内容与 Markdown 抽象语法树进行比较。导航、源文件元数据和派生的无障碍文本不属于规范内容。每个顶层源文件块都必须对应一个有序的 data-source-block 节点，包含其 SHA-256 标识且嵌套内容完整。Mermaid 块必须对应一个图表，其精确源代码在展开内容中出现一次。

如果呈现缺陷源于共享渲染器或样式，请修复相应源文件并重新生成。如果属于内容缺陷，则保持源文件和候选文件不变，并报告该问题。

4. 完成或丢弃

只有在所有检查均通过后，才以原子方式安装候选文件：

python3 <skill-directory>/scripts/html_doc.py finalize --out <output.html> --token <token>

如果任何检查失败，只移除当前待处理的候选文件：

python3 <skill-directory>/scripts/html_doc.py discard --out <output.html> --token <token>

最终处理会在同一目录中执行一次原子替换。它绝不会先删除之前的输出。渲染、检查或替换失败时，之前经过验证的输出必须保持逐字节不变。

输出标准

最终页面必须：

• 保留源文案及其顺序；
• 使用规范的 prd 或 design 机器元数据；
• 记录源文件路径和 SHA-256 哈希值；
• 使用语义化 HTML、内联 CSS，且不包含运行时 JavaScript；
• 不包含外部运行时资源；
• 使用克制的蓝灰色视觉系统；
• 确保无需颜色、鼠标、宽屏或网络连接也能轻松阅读；
• 包含响应式和打印样式；
• 将经过验证的 Mermaid SVG 嵌入为 base64 图片，并在折叠内容中保留完全一致的源代码。

返回

验证后的候选版本定稿后即停止。报告输出路径、源文件哈希值以及执行过的浏览器检查。