用途
html-doc 用于把一份完整的 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，通过标准输入传入并提供 kind 与输出：
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 块映射为一个 figure，其精确源码在其展开控件中出现一次。
如果呈现缺陷来自共享渲染器或样式，应修复该来源并重新生成。如果是内容缺陷，保持源文件与候选文件不变并报告。
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 图片嵌入，并在展开控件中保留精确源码。
返回
当验证过的候选文件被定稿后停止。报告输出路径、源哈希以及所执行的浏览器检查。
暂未提供
关于作者、版本历史、许可证、定价模式及使用限制等信息，资料中暂未提供。