beautiful-article

Beautiful Article

背景原则

AI 生成内容越复杂，输出媒介越重要。HTML 的价值在于同时提升信息密度、视觉清晰度、分享便利性和交互能力：表格、SVG、CSS、代码片段、可调控件、复制与导出按钮，可以让读者不只是“看完”，而是能比较、定位、调整、复查和继续使用。Beautiful Article 的目的，是把原本枯燥、线性、难以消化的文字材料，转换成视觉体验更漂亮、阅读节奏更清晰、也更容易审阅和分享的单文件网页文章。

边界（先判断要不要进这个 Skill）

• 最终主产物是 single HTML 文章，不是网页应用。
• 文章可以有 Raw 自由层（任意 HTML / CSS / JS / React：交互、布局排版、动效、小工具、 按需的 SVG / canvas 图解），但必须服务阅读、解释、论证、节奏或审美。
• 不生成：后台、表单、拖拽工作台、完整 dashboard、产品原型、通用 Web App。
• 信息密度由用户确认；默认保留 100% 信息，生成长文式网页文章。

如果用户要的是应用而不是文章，停下来澄清，不要进入本 Skill。

工作流总览

Phase 0  Intake            判断是否进入本 Skill + 初步文章类型
   ▼
Phase 1  Source → Markdown URL/PDF/DOCX/MD/文本 → source.md + extraction-notes.md
         └ 主 Agent 内联 5 条 checklist 自查（仅复杂/低置信源升级 SubAgent）
   ▼
Phase 2  Editorial Planning 一份 plan.md（Brief / Outline / Theme / Assets 四段）
         └ 主 Agent 内联自查（无 SubAgent、无 review 文件）
   ▼

工作区结构（脚手架创建；这些文件是 Skill 的长期记忆，不要只依赖聊天上下文记决策）：

硬性质检协议（贯穿整个 Skill）

质检方式按节点区分 —— 不是所有质检都要开 SubAgent，也不是所有质检都要写文件。 误开 SubAgent / 误写文件是首要性能问题，按下表严格执行：

铁律：

1. Plan Checkpoint（Phase 2 → Checkpoint 1）严禁开 SubAgent 做质检。主 Agent 写完 plan.md 后就地对照 5 条清单（见 references/review-checklist.md 的 Plan 自查段）核查、按结论 改完 plan/plan.md，不要写任何 review 文件，然后进入 Checkpoint 1。
2. First Spread / Final 必须用 SubAgent（这两个节点 SubAgent 价值 > 开销）；只有探测不到 SubAgent 环境才由主 Agent 兜底，并在文件首注明"无 SubAgent 环境，主 Agent 兜底"。
3. Section Reviewer 用 SubAgent，但返回值是消息（pass / fail + 修复点）；fail 项主 Agent 收到后直接修，不要让 SubAgent 写 review/section-NN-review.md 文件。
4. 拿到任何质检结论 —— 先按 fail 项把产出改完，再汇报"做完了 + 自检结论 + 改了什么"。 直接拿原始结论汇报但不修复 = 违规。
5. 决策收集铁律 · 禁止静默替用户选择：在每个 Checkpoint（1 / 2 / 3），所有需要用户确认的 决策项必须每项独立列出 + 等用户答复。Agent 可以推荐（"我推荐 X，因为 …"），但 不能"已经替你定了 X，如果不对再说" —— 这等于剥夺选择机会。
   • 优先：如果环境有 AskQuestion 工具，每个决策项作为一个独立 question（一次调用可 传多个 question），用户能用选择卡逐项确认。
   • 否则：停下来在消息里把所有问题编号列出（每个问题独占一段、写清推荐项 + 理由 + 备选项），明确说"我等你逐项答复后再继续"，不要继续做任何后续工作。
   • 绝不：把多项决策打包成一个"全选我推荐的 / 全部 OK 吗？"yes/no 问题；也不要在 "推荐一句话"后默认直接进下一步。

各节点的 checklist 与 SubAgent prompt 模板见 references/review-checklist.md。

各阶段文件读取指南（渐进加载，别一次全读）

长会话里 agent 容易遗忘原则 —— Phase 5 会重复实现 N 个 Section，每次开工 前回看 component-policy.md + raw-policy.md + 当前主题 theme-profiles/<id>.md。

Phase 0 —— Intake

判断是否进入本 Skill，给出初步文章类型与输出模式（默认 single HTML）。

捕获目标语言：开场就记录用户期望的最终文章语言（如用户提到"用中文/做成英文版"等）。

• 用户指定了语言 → 记进 plan/plan.md Brief 段的"目标语言"。若与源材料语言不一致，Phase 1 需先产出一份地道翻译版源文，后续基于翻译版编写（见 Phase 1）。
• 用户未指定 → 默认最终文章语言跟随源材料语言，不做翻译。

自检：用户要的是文章还是网页应用？是否需要完整信息？是否要先索取更多素材？ 用户有没有指定最终语言？与源语言是否一致？

Phase 1 —— Source → Markdown

把任意输入统一成 source/source.md，把不确定项写进 source/extraction-notes.md。 规则与各类输入处理见 references/source-to-markdown.md；可借助 MarkItDown 主路径或轻量 fallback 脚本做 PDF/DOCX/HTML 抽取。

落盘后由主 Agent 内联自查（references/source-to-markdown.md 的 5 条 checklist），按结论修复 再进入 Phase 2；仅当 extraction-notes.md 标记低置信 / 复杂源时，才升级为独立 Source Reviewer SubAgent 并对照 original.* 做 diff 式核查（写 review/source-review.md）。

语言处理（紧接抽取之后）：判断 source.md 的语言。

• 用户未指定目标语言，或目标语言与源一致 → 不翻译，后续直接基于 source.md 编写， 最终文章语言 = 源语言。
• 用户指定了目标语言且与源不一致 → 先产出地道翻译版 source/source.<lang>.md （如 source.zh.md / source.en.md），作为后续 Phase 2+ 的事实底座；原文 source.md 保留 备查。翻译要求：用地道的目标语言、去除翻译腔（按目标语言的表达习惯重组句子，不逐字直译， 不留生硬的外语语序 / 被动堆叠 / 异国标点），术语 / 数字 / 代码 / 公式 / 引用保持准确，结构与 信息保留比例不变。翻译说明写进 extraction-notes.md。

Phase 2 —— Editorial Planning

形成编辑方案，不直接写 HTML。只产出一份 plan/plan.md（四段：Brief / Outline / Theme / Assets），模板见 references/plan-template.md：

• Brief：目标读者 / 文章类型 / 信息保留比例 / 必须保留 / 可删减 / 语气 / 主要观点 / 阅读目标 / 目标语言 / 版式宽度 / TOC / 配图策略。
• Outline：Hero / Lead / Summary / Section 列表 / 每节保留哪些信息 / 每节是否需要 Raw·Table·CodeBlock·Formula·Image / 结尾方式。
• Theme：选定主题 + 理由 + 冲突说明（见 references/theme-selection.md）。
• Assets：配图策略与逐图计划（见 references/asset-policy.md；none 模式下本段 写一句话即可）。

文章类型路由见 references/article-types.md；信息密度与组件比例见 references/information-density.md。

自检方式 · 强约束：写完 plan/plan.md 后由主 Agent 内联对照 5 条 Plan 自查清单核查 （见 references/review-checklist.md 的 Plan 自查段），按结论改完 plan/plan.md，直接进入 Checkpoint 1，禁止开 SubAgent，禁止写 review/plan-review.md。

Phase 3 —— Plan Checkpoint（★硬节点 · Checkpoint 1，必须停）

铁律：禁止静默替用户选择。每个决策项必须独立列出、独立等用户答复。

可以推荐（"我推荐 X，因为 …"），不能说"已经替你定了 X，如果不对告诉我"——后者等于把 默认值偷渡过去、剥夺选择机会。

收集方式（按环境二选一）：

• 优先 AskQuestion 工具：每项作为一个独立 question 传入（一次调用可传多个 question）， 用户用选择卡逐项确认。
• 无 AskQuestion 工具：停下来在消息里把每个问题**编号列出 + 独占一段 + 写清推荐项 + 理由
  • 备选项**，明确说"我等你逐项答复后再继续"，不要继续做任何后续工作。

无论哪种方式：每个独立决策对应一个独立问题，不要打包成"全部 OK 吗？" yes/no。

必须独立确认的 5 项（缺一不可）：

TOC 默认开：因为它只有一个开关 + 几乎所有文章都该开，可以在 Plan Checkpoint 开场说明 里以"默认 TOC 开，要关告诉我"一句话带过，不必单独成题。

已经走默认值、不必单独问的事项（仍然要在开场说明里明示"如要改请告诉我"，给用户机会 反悔，不能完全藏起来）：

• 最终文章语言：跟随源语言（除非用户已经在前文指定 / 已经翻译完成）。
• 是否允许编辑删减、重组、改写语气：默认允许（按上面的信息保留比例执行）。
• 是否要先看首屏样张：默认会先做（这就是 Phase 4）。
• TOC：默认开。

主题用户说"你定" → 取你推荐的第一个，在选项里仍要把它和其它候选并列，标"默认 · AI 推荐"，留反悔余地，不能直接跳过主题问题。

如何偏离信息保留比例的"标配"：每个文章类型都自带一个推荐保留比例（见上表）。绝大 多数情况走标配即可。如果用户想精修（比如 "longform 但只要 60%" → 一篇被深度编辑过的长文）， 让用户在开场说明后的自由文本里写一句"我要 <类型> + <X%>" 覆盖。AI 收到覆盖后要在 plan/plan.md 的 Brief 段同时记下"类型 / 标配保留 / 用户覆盖到 X%"，并提醒用户这是"非标配 组合"——这类组合需要主 Agent 在写每节时手动调整正文/视觉比例。

Plan Checkpoint 开场消息模板（在收集决策之前先发一条简短说明）：

发完上面这条说明后，立刻用 AskQuestion 传 5 个 question（或在无工具环境下编号列出 5 个问题、停下等答复）。5 项全部收齐答复才能进 Phase 4；若用户在自由文本里给了"非标配保留 比例"，先确认 AI 已经记进 plan/plan.md 再进 Phase 4。

Phase 4 —— First Spread（文章版"第一章验收"）

先做"封面（若开） + 首屏 + 第一节 + 一个代表性视觉块"。脚手架在这里创建工作区：

它创建 Vite + React + TS 工作区（从 npm 安装 reacticle 最新发布版）+ source/ plan/ review/ 记忆目录 + assembler article/Article.tsx + 一个示例 section 组件 （+ 默认 article/Cover.tsx，除非 --no-cover）。详见 references/scaffold.md。

首屏（Hero / Lead）写进 assembler article/Article.tsx；第一个 Section 必须写成独立组件 article/sections/01-*.tsx（这是后续并行的代码锚点，见 references/section-build.md）。 封面（若开）替换 article/Cover.tsx 里的 <CoverPlaceholder /> 为按主题 + 文章主旨 定制的图文构图，外壳（3:4 容器 + 打印分页）不要动。封面设计指南见 references/cover.md。 npm run dev 预览。它决定标题气质 / 字号 / 内容密度 / Raw 风格 / 配图方式 / 主题是否合适。

第一个 Section 完成后，按硬性质检协议创建 First Spread Reviewer SubAgent，写 review/first-spread-review.md（含封面 5 条自检，见 references/cover.md），改完 再进 Checkpoint 2。

Checkpoint 2 · First Spread（★硬节点，必须停）

让用户验收首屏 + 第一个 Section，并选定后续开发模式。同样适用 Checkpoint 1 的决策收 集铁律：两项独立确认，禁止打包；优先 AskQuestion，无工具则编号列出、停下等答复。

先发一条简短消息：

然后用 AskQuestion 传两个独立 question（或编号列出两个问题，停下等答复）：

1. 验收结论 —— 选项：通过 · 进入完整生成 / 局部修改 · 我会另起一条说改哪里 / 主题或版式不合适 · 回到 Checkpoint 1。
2. 后续开发模式 —— 选项：A · 单 Agent 顺序（默认 · 最稳 · 风格最统一） / B · 多 Agent 并行（最快 · 风格轻微差异）。

不要把这两件事打包成"通过 + A，OK 吗？" —— 用户可能"通过验收但想用 B"或反之。 两题都收齐答复后进入 Phase 5。

Phase 5 —— Full Article Build

按 Checkpoint 2 选定的开发模式生成完整文章。详见 references/section-build.md + references/component-policy.md + references/raw-policy.md。

铁律 · 每个 Section 必须是独立组件文件（article/sections/NN-*.tsx），坚决不允许把 多个 Section 直接写进一个组件。article/Article.tsx 只是 assembler：import 并排序各 Section，由主 Agent 拥有。大型 Raw 同样隔离到 article/raw-blocks/NN-*.tsx。文件级隔离 是多 Agent 并行的前提。

开发模式（Checkpoint 2 选定）：

• A · 单 Agent 顺序（默认）：主 Agent 顺序写每个 sections/NN-*.tsx，最稳、风格最统一。
• B · 多 Agent 并行：subagent 各拥有一个 sections/NN-*.tsx 文件并行开发；主 Agent 负责合并与稳定性 —— 维护 Article.tsx 的 import 与顺序、跑 npm run typecheck / build、 兜底主题与风格一致、解决冲突。subagent prompt 模板见 references/section-build.md。

其余原则：正文是主体；所有 Raw 用 --ra-* 主题 token，禁止野生样式；100% 信息保留以长文 结构为主、Raw / 配图做增强；低信息密度可提高视觉块比例，但仍必须是文章形态。

每个 Section 完成后必须按硬性质检协议走 Section Reviewer SubAgent：是否完成 outline 任务 / 是否符合信息保留比例 / 是否与前后衔接 / 是否过度组件化 / 是否有足够正文 / Raw 与 配图是否有明确目的 / 本节序号自洽。

SubAgent 以消息返回 pass/fail + 修复点（pass 则一行 OK；fail 则列出修复点），不要写 review/section-NN-review.md 文件。主 Agent 收到 fail 项后直接修对应 section 文件， 然后再汇报本节交付。

Phase 6 —— Final Review（三视角终审）

从读者 / 主题 / 技术三个视角验收，产出 review/final-review.md + 修复列表。 完整硬性清单见 references/review-checklist.md。推荐三个 Reviewer（无 Teams 时至少 一个独立 SubAgent）：

1. Editorial Reviewer：文章性、信息取舍、结构。
2. Visual Reviewer：主题、Raw、配图、移动端。
3. Technical Reviewer：构建、控制台、代码 / 公式、可访问性。

核心红线：它仍是一篇文章（不是应用）· 信息保留比例符合 Plan · 必须保留的信息没丢 · 主题气质统一 · Raw 无野生样式 · 没有明显 AI 味 · 桌面 + 移动端可读 · HTML 可构建可打开可分享。

Phase 7 —— Repair（最小切片）

按最小单位修复，规则见 references/repair-policy.md。禁止：只反馈一处就重写整篇 / 为修视觉改动已确认的文章结构 / 为压缩信息删掉用户指定必须保留的内容。有修复才写 review/repair-log.md（无修复 / 一次过则不写）。

Checkpoint 3 · Final（★交付确认）

终审改完后，停下来让用户独立确认交付决策（不要"我打算导出 HTML 了，没问题就这样" 直接跳过）。优先 AskQuestion，无工具则在消息里编号列出问题、停下等答复。

• 交付决策 —— 选项：通过 · 导出 HTML 交付 / 通过 · 同时导出 HTML + PDF / 还有局部修复 · 我会列出具体修哪里 / 先停一停 · 我要再看看。

只有这一项决策，但仍要主动停下来问，不要静默走默认导出 HTML。

Phase 8 —— Delivery

构建并交付（命令见 references/html-output.md）：

• article/article.html（自包含单页，CSS + JS 内联，断网可打开）—— 主交付物。
• 可选 article/article.pdf：仅当 Checkpoint 3 用户选了"通过 · 同时导出 HTML + PDF" 时才生成。命令：

  bash <path-to-beautiful-article>/scripts/html-to-pdf.sh
  脚本探测系统已装的 chromium-family 浏览器，注入 @media print 覆盖（TOC 从左右栅格塌 成上下排布、TOC 独占首页），headless 打印。零 npm 依赖。详细原理 / 故障排除见 references/pdf-output.md。
• 简短编辑说明：文章类型 / 信息保留比例 / 主题 / 配图策略 / 主要编辑取舍。

默认策略

• 输出 single HTML；文章类型 longform；信息保留 100%。
• 语言：用户未指定则跟随源材料语言；指定且与源不一致则先产出地道翻译版 source/source.<lang>.md 再据此编写（去翻译腔，见 Phase 1）。
• 主题：技术 / 证据优先 tufte，叙事 / 评论优先 press（按源材料推荐）。
• 版式：宽度默认 regular、TOC 默认开（与主题解耦，见 references/layout.md，均在 Checkpoint 确认）。
• 配图：配图模式是 Checkpoint 1 必选项（none / user-assets / placeholders / ai-generated），只决定是否使用外部 Image，不主动生成 AI 图片。
• Raw：与配图正交、始终默认存在，鼓励多用，但必须服务具体段落、用主题 token。选 none 不影响 Raw。
• 自检：Plan 内联自查（无 SubAgent、无文件）；First Spread 与 Final 用 SubAgent + 写文件； Section 用 SubAgent + 消息返回（不写文件）。详见"硬性质检协议"段。
• 决策收集：Checkpoint 1 / 2 / 3 每项独立确认 · 禁止静默替用户选择。可推荐，不能跳过。 优先 AskQuestion 工具（每项一个独立 question）；无工具则停下、编号列出问题等用户答复。
• 修复：最小切片，有修复才写 review/repair-log.md。
• Colophon · 不可移除：scaffold 在 article/Article.tsx 末尾自带 colophon Raw 块 （Made with [beautiful-article](github 仓库) · <主题> theme，低对比小字、theme token 自适应）。 每篇文章必须保留，禁止删除、禁止移到 Hero 旁边或浮动到角落。切换主题时同步更新 colophon 里的主题名 + main.tsx 的 <ThemeProvider theme="..."> 两处。
• 封面 · 默认开 · 必须图文并茂：scaffold 默认在 article/Cover.tsx 创建屏幕 3:4 + PDF 独占首页的书封式题图外壳 + 占位（--no-cover 关闭）。封面位于 TOC + Hero + 正文之上， 独立存在。Phase 4 First Spread 时主 Agent 把 <CoverPlaceholder /> 替换为按 主题 + 文章主旨 定制的图 + 字构图。硬约束：外壳比例 / 打印分页不可动、必须有视觉元素
  • 文字、只用 --ra-* token、不要远程图片、不要重复 Hero 内容。视觉技术全开放： SVG / CSS / Canvas / 复杂 React 组件 / 任意混搭由 Agent 自选，效果好就行。详见 references/cover.md（含 5 条自检 + 5 个构图模板 + 各主题封面起手）。PDF 导出会自动让 封面独占首页、TOC 从第二页开始。
• PDF 导出 · 可选：主交付物始终是 article/article.html。仅当 Checkpoint 3 用户选了 "通过 · 同时导出 HTML + PDF"，才跑 bash <skill>/scripts/html-to-pdf.sh 生成 article/article.pdf；不选则不动。不要替用户默认导。详见 references/pdf-output.md。

成功标准

• 它首先是一篇文章。
• 最终文章语言符合用户意图（未指定=跟随源语言；指定=全文统一为目标语言，地道、无翻译腔、 无残留源语言片段）。
• 用户确认的信息密度被尊重；源材料关键内容没有意外丢失。
• 主题气质统一；配图和 Raw 都服务阅读。
• 页面比 Markdown 更值得读；HTML 可直接打开和分享。
• 40% 信息时读起来像被编辑过的文章，而非缩水摘要；100% 信息时像被精修过的长文， 而非原文搬运。

相关资源（按"何时读"标注）