article-to-html

article-to-html

将一份文档（来自对话上下文或指定的 markdown 文件）转换为独立的 HTML 文件，并沿用 references/template.html 中定义的“论文提案”设计系统：衬线正文 + 等宽元数据 + 编号章节 + 内嵌 SVG 图表 + 提示框 + 表格 + 可选的 JS 交互功能。

触发后的流程

1. 获取源文件。 如果用户提供了文件路径，则用 Read 读取。如果草稿在对话上下文中，则直接使用。
2. 提取文档骨架。 标题、副标题、TL;DR、章节列表、是否需要图表、是否需要表格、是否需要交互功能。
3. 读取模板。 用 Read 读取 references/template.html，并将其完整 CSS 和结构用作脚手架。
4. 读取组件参考。 用 Read 读取 references/components.md，并挑选本次需要的片段。
5. 如果需要图表： 查阅 references/svg-figures.md，并使用内嵌 SVG 绘制（不引用外部图片，确保文件可移植）。
6. 如果需要交互功能： 查阅 references/interactive.md，并在 </body> 前添加 <script> 块。
7. 输出。 写入 {same dir as source or current working dir}/{slug}.html。文件名为标题对应的英文 slug，或使用用户指定的文件名。
8. 报告。 用一句话提供文件路径，以及一行用于在浏览器中打开文件的命令。

设计原则（不得违反）

• 单文件。 所有 CSS / SVG / JS 均内嵌。不使用外部字体、CDN 或远程图片。
• 不要更改 paper 配色。 --paper: #f7f7f5 + --ink: #1a1a1a 是此技能的视觉标志。如果用户明确要求不同的氛围（深色模式、不同的强调色），可以更改 --accent / --warn，但需保留 paper/ink。
• 衬线正文 + 等宽元数据。 body 使用 ui-serif；每个“元数据槽位”（.doc-eyebrow / .doc-meta / th / code / figcaption / .num）使用 ui-monospace。这种组合是标志性设计。
• 章节编号前缀。 <h2><span class="num">01</span>Section title</h2> —— 小号等宽字体、浅灰色，与标题间隔 14px。即使源文档没有编号，也要添加。
• 图表需要 figcaption。 <figcaption><span class="fig-num">FIG 1</span>caption text</figcaption>，其中 FIG N 使用强调色。
• TL;DR 始终置顶。 如果源文档没有 TL;DR，则将开头一到两段浓缩为约 60 个词的摘要，并置于此处。
• 不要添加“由 AI 生成”页脚水印，除非用户明确要求。

组件速查表

如果源文档包含……	使用……
引言 / 摘要	.tldr 块
引文	.callout.cite（带 .cite-source）
警告 / 提醒	.callout.warn
通用旁注	.callout（默认白色背景）
三个并列的概念 / 角色	.cards（三列卡片）
N 个并列的概念	.cards cols-2 / cols-4
对比 / 供应商矩阵	<table>
流程 / 架构 / 时序 / 条形图	内嵌 SVG 图表，参见 references/svg-figures.md
待解决问题列表	<ol>，每项都以加粗的引导短语开头
参考链接	包含 <ul> 的 <footer>

交互元素（可选）

默认情况下，模板是静态的。当文档明显受益于交互功能时，应主动添加：

• 折叠 / 展开章节（长文档）
• 代码块上的“复制”按钮
• 表格筛选 / 排序（非常适合供应商对比表）
• 深色模式切换（状态保存到 localStorage）
• 目录 + 滚动定位
• 表单（例如用于 RFC / 决策文档的“投票 / 留言”表单，状态保存到 localStorage）

具体片段见 references/interactive.md。默认不添加交互功能，除非 (a) 文档较长——≥3 个章节 + ≥2 个图表，或 (b) 源文档本身适合交互（教程、决策文档、供应商选择）。

命名和输出位置

• 文件名：使用标题的英文 slug，全部小写，以连字符分隔，长度 ≤40 个字符。对于中文标题，使用拼音或译文关键词提示，例如《新基建提案》→ infra-proposal.html。
• 输出位置：
  • 如果用户提供了源 Markdown 文件路径，则输出到同一目录。
  • 否则，输出到当前工作目录。
  • 如果用户指定了路径，则按指定路径输出。
• 如果存在同名文件，则追加 -v2 / -v3。绝不要在不告知用户的情况下覆盖现有输出文件。

常见错误

• **重新着色 CSS。**除非用户要求“换一种配色”，否则不要改动纸张色、墨色或强调色。视觉一致性正是全部要点。
• 将正文改为无衬线字体。“提案纸张”的整体质感依赖于衬线正文。更改字体会破坏视觉效果。
• **使用 emoji 作为图标。**此技能的字符体系是大写等宽标签 + 小色块（.mascot / .layer-icon）。除非用户明确要求，否则不要使用 emoji。
• **使用外部 <img src="https://...">。**这会破坏可移植性。请改用内联 SVG、base64，或省略。
• 遗漏 figcaption 编号。FIG 1 / FIG 2 / FIG 3 递增标签是营造“学术论文”质感的关键。
• **每个段落都添加提示框。**提示框用于强调一两个段落，而非装饰。每份文档的提示框总数 ≤ 5。
• **将 5 个项目硬塞进三列卡片。**改用 repeat(N, 1fr)（或使用 .cols-N 修饰符），不要强行换行。
• **泄露示例中的领域专用名称。**模板是空白的；如果源内容没有提到 Crewlet / Anthropic / 等名称，HTML 中也不应出现。

文件清单

• references/template.html — 空白框架（包含完整 CSS 和占位结构）。从这里开始。
• references/components.md — 每种组件的可复制粘贴 HTML 片段。
• references/svg-figures.md — 五种常见 SVG 图示框架（架构、时序、柱状对比、分层结构、生命周期）。
• references/interactive.md — JS 代码片段（折叠、复制、表格筛选/排序、目录、深色模式、表单 → localStorage、阅读进度、图示缩放）。
• assets/example.html — 完整的参考渲染示例（保留原始中文 article.html 作为视觉基准）。