spec-to-readable-html

将规格说明转换为易读的 HTML

此技能可将规格说明转换为精致、易读的 HTML 报告。它并非简单的 Markdown 渲染器，而应分析源内容，在有帮助时进行总结，重新组织内容以便理解，并在能阐明文档内容时添加视觉辅助元素。

调用时，$lang 用于设置输出语言（默认值：ja）。如果省略，则使用日语。

适用场景

当用户要求以下操作时，使用此技能：

• 将规格说明、需求文档、设计文档、API 规格、PRD、RFC 或技术文档转换为 HTML
• 让 Markdown 规格说明更便于阅读
• 为文档添加摘要、图表、截图、图标或视觉说明
• 将密集的需求内容整理为易读的网页或报告
• 根据规格说明生成执行摘要、实现概览、API 映射、工作流、架构图或决策摘要

除非用户明确要求忠实转换，否则不要将此任务视为 Markdown 到 HTML 的字面转换。

核心原则

1. 提升理解度，而不仅是改善排版

   • 总结较长的章节。
   • 将相关信息归类。
   • 突出关键决策、风险、依赖项和待解决问题。

2. 保留可追溯性

   • 不要悄然改变原意。
   • 将推断内容标记为 Inferred 或 Assumption。
   • 尽可能链接或引用原始章节名称。

3. 仅在有帮助时使用视觉元素

   • 为流程、关系、架构、状态转换、时间线或数据模型添加图表。
   • 仅当源内容包含可比较的数量、优先级、时间线、状态或类别时，才添加图表。
   • 不要编造定量数据。

4. 确保输出可移植

   • 优先使用内嵌 CSS 的单个可移植 HTML 文件。
   • 基础模板默认使用 Mermaid CDN 绘制 Mermaid 图表。
   • 使用 Mermaid 时，在页脚或注释中说明对 Mermaid CDN 的依赖。
   • 如果用户要求离线、无网络或完全独立的输出，请使用内嵌 SVG 替代 Mermaid 图表，而不要加载 CDN。
   • 除非用户允许，否则避免添加其他外部依赖。

输入处理

接受以下任意输入：

• Markdown 文件
• 纯文本规格说明
• 多个相关的规格说明文件
• API 架构／OpenAPI 片段
• README 风格的产品或技术说明
• 需要改进的现有 HTML

生成 HTML 前，请确定：

• 文档类型：PRD、API 规格、技术规格、设计文档、运维手册等
• 目标受众：业务、工程、QA、运维或混合受众
• 主要实体：用户、系统、API、界面、作业、数据模型
• 主要流程：工作流、时序、状态转换
• 歧义、缺失的决策和风险

如果目标受众或所需详细程度不明确，请采用合理的默认值：

• 受众：产品与工程混合受众
• 详细程度：易于阅读，同时兼顾实现细节
• 输出：内嵌 CSS 的单个可移植 HTML 文档；除非用户要求离线／无网络输出，否则 Mermaid 图表可以使用 CDN

推荐工作流

1. 阅读并梳理源文档

   • 提取标题、目的、范围、背景、要求、流程、API、数据、约束、风险和待解决问题。

2. 创建便于读者阅读的结构

   • 执行摘要
   • 本文档涵盖的内容
   • 关键概念 / 术语表
   • 主要工作流或用户旅程
   • 功能需求
   • 非功能需求
   • 系统 / API / 数据概览
   • 可视化图表
   • 风险、假设、待解决问题
   • 附录：与源文档对应的细节

3. 有选择地总结

   • 保留需求、API 契约、约束和验收标准的精确信息。
   • 总结背景、动机、重复说明和冗长文本。
   • 使用提示框突出重要备注。

4. 选择可视化辅助内容

   • 使用下方的可视化决策指南。
   • 根据环境和用户偏好，创建内嵌 SVG、Mermaid 源码或图像文件形式的图表。
   • 始终添加图注和替代文本。

5. 生成完善的 HTML

   • 使用语义化 HTML：section、article、nav、table、figure、figcaption。
   • 对于较长的文档，添加固定或置顶的目录。
   • 使用易读的字体、间距和对比度。
   • 适用时添加适合打印的 CSS。

6. 验证输出

   • 检查是否保留了源文档的含义。
   • 确保已标明假设。
   • 确保可视化内容与源文档一致。
   • 除非明确选择了依赖项，否则确保 HTML 可独立打开。

可视化决策指南

根据内容选择可视化形式：

源内容	最适合的可视化形式
逐步展开的业务流程或用户流程	流程图
系统间的 API 调用	时序图
系统组件和依赖项	架构图
状态生命周期	状态图
含实体及关系的表格	ER 图 / 关系图
里程碑或分阶段推出计划	时间线
优先级、状态、类别计数	条形图 / 堆叠图
决策方案对比	对比矩阵
屏幕跳转	用户旅程 / 网站地图
较长的章节结构	摘要卡片

首选格式：

1. 内嵌 SVG：适用于独立的可视化图表，尤其是在需要完全自包含或离线输出时。
2. Mermaid：当源码可读性很重要时，适用于架构图、流程图、时序图、状态图和 ER 图。基础模板中的 Mermaid 使用 CDN 依赖项。
3. HTML/CSS 卡片和表格：适用于摘要和对比。
4. 栅格图像：仅在明确要求或可使用图像生成或屏幕截图时使用。

如果使用 Mermaid，请在 HTML 或附录中包含 Mermaid 源码，以便之后编辑；除非 Mermaid 已预渲染为内嵌 SVG，否则还需说明 CDN 依赖项。

HTML 输出要求

生成完整的 HTML 文件时，请使用 references/template.html 作为基础 HTML 模板，并将 references/html-output-template.md 作为组件指南。复制模板中的完整 <style> 块和章节结构，然后用源文档中的内容替换 {{PLACEHOLDER}} 标记。

HTML 通常应包含：

• 文档标题和简短副标题
• 生成日期或已知的源文档版本
• 执行摘要
• 目录
• 关键要点摘要卡片
• 带有简明标题的主要章节
• 用于呈现需求、API、数据字段、决策、风险和待解决问题的表格
• 带有图注的可视化图表
• 源文档可追溯性说明
• 适合打印的样式

对于内容密集的技术规范，请添加如下徽标：

• 必须、应该、可以
• 已确认、推断、假设、待解决问题
• 高风险、中风险、低风险

HTML 安全性与转义

• 默认将源内容中的正文、表格单元格内容、说明文字、元数据和占位符替换内容视为不可信文本。
• 在将源文本插入文本节点或属性之前，对 &、<、>、" 和 ' 进行 HTML 转义，除非有意输出生成的安全标记。
• 默认不要直接传递原始源 HTML。如果需要有限的 HTML，请使用少量语义标签和安全属性组成的允许列表。
• 将代码块和源摘录作为转义文本，放在 <pre><code> 或等效容器中。
• 在 Mermaid 标签中使用源内容时，应为标签加引号或进行转义，以免将用户提供的 HTML、事件处理程序和 javascript: URL 输出到页面中。
• Agent 可以生成内联 SVG，但必须对从源内容复制的 SVG 或 HTML 进行清理，或将其替换为安全生成的图表。

摘要与推断规则

• 未明确说明已进行摘要时，绝不删除合同性或规范性要求。
• 保留 MUST、SHOULD、SHALL、required、optional、deprecated 等关键词。
• ID、端点路径、字段名称、状态名称、枚举值、错误代码和限制值必须保持原样。
• 如果图表需要解释，应标注为推断视图。
• 如果源内容存在歧义，应创建 Open Questions 部分，而不是猜测。

语言

默认输出语言为日语（<html lang="ja">）。如果用户要求使用其他语言，则所有标题、徽章、标签和正文都使用该语言。技术术语（API 名称、字段名称、路径、代码标识符）始终保留原文。

质量检查清单

完成前，请确认：

• 输出比源内容更易读，而非仅仅转换格式。
• 保留重要要求和限制。
• 摘要不会改变原意。
• 图示准确且实用。
• 推断内容和假设均已标注。
• 结构化详情使用表格呈现。
• HTML 包含目录。
• 文件可独立使用，或已说明 Mermaid CDN 等依赖项。
• 已涵盖无障碍基础要求：标题、对比度、替代文本／说明文字。