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 文件）
   ▼
Phase 3  Plan Checkpoint   ★Checkpoint 1 必须停。逐项确认 5 件事：文章类型（含标配保留比例）/ 主题 / 版式 / 配图模式 / 封面
   ▼
Phase 4  First Spread      首屏 + 第一节 + 一个代表性视觉块（脚手架在此创建）
         └ First Spread Reviewer SubAgent（写 review/first-spread-review.md）
         └ ★Checkpoint 2 必须停。逐项确认 2 件事：验收结论 / 开发模式 A/B
   ▼
Phase 5  Full Article Build 生成完整网页文章（默认单 Agent，超长可按 Section 隔离）
         └ Section Reviewer SubAgent（以消息返回 pass/fail，无须写 review 文件）
   ▼
Phase 6  Final Review      Editorial / Visual / Technical 三视角终审（写 review/final-review.md）
   ▼
Phase 7  Repair            最小切片修复，有修复才写 repair-log.md
   ▼
Phase 8  Delivery          ★Checkpoint 3 必须停。逐项确认交付决策 → 交付 article.html + 简短编辑说明

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

<workspace>/
  source/   original.*  source.md  source.<lang>.md(需翻译时)  extraction-notes.md
  plan/     plan.md                                    # 单一规划文件：Brief / Outline / Theme / Assets 四段
  article/  Cover.tsx(默认)  Article.tsx  sections/  raw-blocks/  assets/  article.html(产物)
  review/   first-spread-review.md  final-review.md   # 仅这两份是常规产物
            source-review.md(仅复杂源)  repair-log.md(仅有修复时)
  index.html  package.json  vite.config.ts  tsconfig*.json   (构建工装)

---

硬性质检协议（贯穿整个 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 开场消息模板（在收集决策之前先发一条简短说明）：

plan/plan.md 已经写好（自检通过）。我会逐项跟你确认 5 件事：文章类型 / 主题 / 版式宽度 /
配图模式 / 封面。

我的推荐先放在这里供参考（不会替你选）：
- 类型：<X>（含标配信息保留 <Y%>。理由：…）
- 主题：<theme>（理由：…）
- 版式宽度：<width>（理由：…）
- 配图模式：<策略>（理由：…）
- 封面：开 / 关（理由：…；若开，构图想法：…）

默认走但你可以推翻：语言跟随源语言；允许编辑删减重组；TOC 开；接下来会先做首屏样张。
信息保留比例如要偏离类型标配，下面回答完直接告诉我具体百分比（如 "longform 但只要 60%"）。

下面逐项请你确认。

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

---

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

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

# 默认开封面
bash <path-to-beautiful-article>/scripts/scaffold.sh ./my-article --theme=<id>
# Checkpoint 1 用户选了"封面 · 关"
bash <path-to-beautiful-article>/scripts/scaffold.sh ./my-article --theme=<id> --no-cover
bash <path-to-beautiful-article>/scripts/scaffold.sh --list-themes

它创建 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，无工具则编号列出、停下等答复。

先发一条简短消息：

首屏 + 第一个 Section 做好了，npm run dev 在 localhost 预览。
质检结论见 review/first-spread-review.md（已按 fail 项改完，列出修了哪些）。
下面两件事请你独立确认：1) 验收结论 2) 后续开发模式。

然后用 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% 信息时像被精修过的长文，

而非原文搬运。

---

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

Beautiful Article Skill — Turn any source into a beautiful article

A skill for AI agents to edit and design any source material (URL / PDF / DOCX / Markdown / plain text / screenshots / pasted notes) into a beautiful, share-ready article that is easier to read, archive, and pass around than the original.

中文文档 · Back to collection root

---

Powered by ReActicle

beautiful-article is the editorial harness (methodology, checkpoints, theme picker, sub-agent reviewers); `reacticle` is the underlying runtime component protocol the skill writes against — prose-first React components plus a token-based Raw escape hatch, all wired into the same theme system.

beautiful-article  (this skill · methodology + harness)
        │  composes
        ▼
reacticle          (npm package · components / themes / Raw / export)

The two pair very well but are independently useful: the skill works because it has ReActicle to target, and ReActicle is a perfectly usable React library on its own.

---

Showcase — articles built with beautiful-article + ReActicle

Real long-form articles, each authored end-to-end by an AI agent running this skill against the `reacticle` component protocol. Click any cover to open the live, single-file HTML article.

<table> <tr> <td width="50%" valign="top" align="center"> <a href="https://mmh1.top/#/ai-article/tools"> <img src="https://raw.githubusercontent.com/ConardLi/assets/main/imgs/article/tools.webp" alt="Agent Tools 设计的最佳实践" width="320"> <br><b>Agent Tools 设计的最佳实践</b> </a> <br>_{Theme · Freddie · 长文 · 21 min} <br>^{Anthropic 工程团队关于 Tools 的五条原则，与一套评测驱动的方法。} </td> <td width="50%" valign="top" align="center"> <a href="https://mmh1.top/#/ai-article/skill"> <img src="https://raw.githubusercontent.com/ConardLi/assets/main/imgs/article/skill.webp" alt="Agent Skill 是如何进化的？" width="320"> <br><b>Agent Skill 是如何进化的？</b> </a> <br>_{Theme · Freddie · 解释文 · 8 min} <br>^{把 Skill 文档当成被训练的对象，而不是被复制粘贴的 prompt。} </td> </tr> <tr> <td width="50%" valign="top" align="center"> <a href="https://mmh1.top/#/ai-article/harness"> <img src="https://raw.githubusercontent.com/ConardLi/assets/main/imgs/article/harness.webp" alt="Agent Harness 的解剖图" width="320"> <br><b>Agent Harness 的解剖图</b> </a> <br>_{Theme · Vignelli · 长文 · 12 min} <br>^{智能在模型里；让智能变得有用的，是它周围的那套系统。} </td> <td width="50%" valign="top" align="center"> <a href="https://mmh1.top/#/ai-article/prompt-cache"> <img src="https://raw.githubusercontent.com/ConardLi/assets/main/imgs/article/prompt-cache.webp" alt="提示词缓存对 Agent 有多重要？" width="320"> <br><b>提示词缓存对 Agent 有多重要？</b> </a> <br>_{Theme · Bayer · 长文 · 15 min} <br>^{缓存命中率是 Agent 的 SLO，Claude Code 团队的反直觉经验。} </td> </tr> <tr> <td width="50%" valign="top" align="center"> <a href="https://mmh1.top/#/ai-article/context"> <img src="https://raw.githubusercontent.com/ConardLi/assets/main/imgs/article/context.webp" alt="面向 Agent 的高效上下文工程" width="320"> <br><b>面向 Agent 的高效上下文工程</b> </a> <br>_{Theme · Tufte · 长文 · 16 min} <br>^{本文探讨如何高效地筛选与管理驱动 AI Agent 运转的上下文。} </td> <td width="50%" valign="top" align="center"> <a href="https://mmh1.top/#/ai-article/transformer"> <img src="https://raw.githubusercontent.com/ConardLi/assets/main/imgs/article/transformer.webp" alt="Attention Is All You Need" width="320"> <br><b>Attention Is All You Need</b> </a> <br>_{Theme · Tufte · 长文 · 30 min} <br>^{一篇重塑现代 AI 的论文，逐层拆给你看。} </td> </tr> <tr> <td width="50%" valign="top" align="center"> <a href="https://mmh1.top/#/ai-article/agent-eval"> <img src="https://raw.githubusercontent.com/ConardLi/assets/main/imgs/article/agent-eval.webp" alt="把 AI Agent 的评测讲清楚" width="320"> <br><b>把 AI Agent 的评测讲清楚</b> </a> <br>_{Theme · Tufte · 长文 · 25 min} <br>^{让 Agent 有用的那些能力，恰恰让它难以评测 — 来自 Anthropic 的指南。} </td> <td width="50%" valign="top" align="center"> <a href="https://mmh1.top/#/ai-article/agent-loop-codex"> <img src="https://raw.githubusercontent.com/ConardLi/assets/main/imgs/article/agent-loop-codex.webp" alt="Codex 的 Agent Loop 是怎么做的？" width="320"> <br><b>Codex 的 Agent Loop 是怎么做的？</b> </a> <br>_{Theme · Sottsass · 长文 · 18 min} <br>^{OpenAI 官方分享：在 Responses API 之上，一条对话是如何被反复"展开"的。} </td> </tr> </table>

---

Theme Gallery — one specimen article per theme

11 themes shipped. Full theme contracts (.css token bundle + .md authoring profile, anti-patterns, code/media style) are documented at Theming.

Every theme ships with a long-form specimen article that lives the theme end-to-end — typography, photography, code, formulas, Raw blocks, the works. Click any cover to read the live article; click the theme name to jump to that theme's section in the docs.

<table> <tr> <td width="33%" valign="top" align="center"> <a href="https://rearticle.mmh1.top/#/gallery/caffeine-half-life"> <img src="https://raw.githubusercontent.com/ConardLi/assets/main/imgs/article/theam-tufte.webp" alt="Tufte · Data-Ink" width="260"> <br><b>Tufte</b> · Data-Ink </a> <br>_{咖啡因与睡眠 · 数据笔记} <br>^{Edward Tufte 数据墨水，证据优先，发丝级图表与最朴素的版式。} </td> <td width="33%" valign="top" align="center"> <a href="https://rearticle.mmh1.top/#/gallery/movable-type"> <img src="https://raw.githubusercontent.com/ConardLi/assets/main/imgs/article/theam-press.webp" alt="Press · 书卷" width="260"> <br><b>Press</b> · 书卷 </a> <br>_{活字之后 · 随笔} <br>^{Stripe Press 式书卷长读物：会落定的标题、氧化血红首字母、纯正文之美。} </td> <td width="33%" valign="top" align="center"> <a href="https://rearticle.mmh1.top/#/gallery/pool-exhaustion"> <img src="https://raw.githubusercontent.com/ConardLi/assets/main/imgs/article/theam-shannon.webp" alt="Shannon · 工程暗色" width="260"> <br><b>Shannon</b> · 工程暗色 </a> <br>_{连接池耗尽 · 故障复盘} <br>^{贝尔实验室技术论文血统，暗底黄金信号、回压依赖、夜间作战气质。} </td> </tr> <tr> <td width="33%" valign="top" align="center"> <a href="https://rearticle.mmh1.top/#/gallery/orbit-spec"> <img src="https://raw.githubusercontent.com/ConardLi/assets/main/imgs/article/theam-vignelli.webp" alt="Vignelli · 瑞士" width="260"> <br><b>Vignelli</b> · 瑞士网格 </a> <br>_{Orbit 设计系统规格 · 规格} <br>^{Massimo Vignelli 网格至上、grotesque 字族、瑞士红只承载结构。} </td> <td width="33%" valign="top" align="center"> <a href="https://rearticle.mmh1.top/#/gallery/linear-attention"> <img src="https://raw.githubusercontent.com/ConardLi/assets/main/imgs/article/knuth.png" alt="Knuth · 学术" width="260"> <br><b>Knuth</b> · 学术 </a> <br>_{线性化自注意力 · 预印本} <br>^{Donald Knuth / Computer Modern，编号小节、命题与证明、arXiv 草稿气质。} </td> <td width="33%" valign="top" align="center"> <a href="https://rearticle.mmh1.top/#/gallery/first-newsletter"> <img src="https://raw.githubusercontent.com/ConardLi/assets/main/imgs/article/theam-freddie.webp" alt="Freddie · 暖黄" width="260"> <br><b>Freddie</b> · 暖黄 </a> <br>_{第一封 Newsletter · 上手指南} <br>^{Mailchimp Freddie 黑字荧光，亲和插画 + 不端着的产品上手语气。} </td> </tr> <tr> <td width="33%" valign="top" align="center"> <a href="https://rearticle.mmh1.top/#/gallery/slow-breathing"> <img src="https://raw.githubusercontent.com/ConardLi/assets/main/imgs/article/theam-andy.webp" alt="Andy · 静谧" width="260"> <br><b>Andy</b> · 静谧 </a> <br>_{把呼吸放慢 · 练习} <br>^{柔软圆润、呼吸-神经跷跷板，让人慢下来的练习气质。} </td> <td width="33%" valign="top" align="center"> <a href="https://rearticle.mmh1.top/#/gallery/front-page"> <img src="https://raw.githubusercontent.com/ConardLi/assets/main/imgs/article/theam-bodoni.webp" alt="Bodoni · 报刊" width="260"> <br><b>Bodoni</b> · 报刊 </a> <br>_{头版的消亡 · 特稿} <br>^{高对比 Didone 报刊气质，黑白大报、对折线之上的分量。} </td> <td width="33%" valign="top" align="center"> <a href="https://rearticle.mmh1.top/#/gallery/geometry-of-meaning"> <img src="https://raw.githubusercontent.com/ConardLi/assets/main/imgs/article/theam-bayer.webp" alt="Bayer · 包豪斯" width="260"> <br><b>Bayer</b> · 包豪斯 </a> <br>_{形、色、网格 · 教学} <br>^{Herbert Bayer 包豪斯三原色几何，形有性格、色有重量。} </td> </tr> <tr> <td width="33%" valign="top" align="center"> <a href="https://rearticle.mmh1.top/#/gallery/rate-limiter-spec"> <img src="https://raw.githubusercontent.com/ConardLi/assets/main/imgs/article/theam-fuller.webp" alt="Fuller · 蓝图" width="260"> <br><b>Fuller</b> · 蓝图 </a> <br>_{限流器设计规格 · 系统设计} <br>^{Buckminster Fuller 工程蓝图，方格纸拓扑、令牌桶模拟，可照着实现。} </td> <td width="33%" valign="top" align="center"> <a href="https://rearticle.mmh1.top/#/gallery/color-clash"> <img src="https://raw.githubusercontent.com/ConardLi/assets/main/imgs/article/theam-sottsass.webp" alt="Sottsass · 孟菲斯" width="260"> <br><b>Sottsass</b> · 孟菲斯 </a> <br>_{撞色不翻车 · 设计随笔} <br>^{Memphis 80s 撞色，黑描边、硬投影、轻微旋转的不正经语法。} </td> <td width="33%" valign="top" align="center"> &nbsp; </td> </tr> </table>

Browse all specimens with theme switching, search and filters at the live gallery: <https://rearticle.mmh1.top/#/gallery>.

---

What it does

beautiful-article turns dry, linear, hard-to-digest source material into a polished, visually clear, share-ready article. It is not a web-app builder — the focus is always the article: better reading, better pacing, better aesthetics. The article is delivered as a self-contained file that opens offline (with optional companion PDF), but that's a delivery detail, not the goal.

It is designed for:

• Repackaging long URLs / PDFs / DOCX / Markdown into a beautiful HTML long-form
• Producing briefings, explainers, tutorials, post-mortems, design / proposal reviews
• Visual essays, dialogue / interview transcripts, interactive learning explainers
• Any time you want a better reading medium than raw Markdown — with tables, SVG, code, formulas, copy / export buttons baked in

The skill is primarily a methodology + collaboration harness. It ships a Vite + React + TypeScript scaffold built around the `reacticle` component protocol — the agent does not hand-write naked HTML / CSS, it composes prose-first semantic components plus a theme-constrained Raw free layer.

---

Core ideas

• Article first, not app — the focus is the article. Raw layers, SVGs, mini-tools must serve reading / explanation / pacing / aesthetics, not stand on their own.
• Source → Plan → Build → Review harness — every project flows through six numbered phases with three hard checkpoints in between.
• Component protocol via `reacticle` — semantic prose components (Hero, Lead, Section, Quote, Callout, Image, Formula, CodeBlock, Table, …) plus a Raw escape hatch that must use theme tokens (--ra-*).
• Theme-driven design — pick from a registry of authoring profiles (tufte, press, bayer, bodoni, vignelli, sottsass, freddie, andy, fuller, knuth, shannon) — each profile is a Markdown contract for the agent, not a CSS file.
• 100% information retention by default — the article type carries a recommended retention ratio (longform ~100%, briefing ~50%, visual-essay ~40%, …) which the user can override.
• Hard collaboration checkpoints — the agent pauses for the plan, the first-spread proof, and the final delivery decision; every decision must be confirmed item-by-item, never silently bundled.
• Cover by default — a 3:4 book-style cover sits above the TOC, locked container, theme-token only, no remote images.
• Optional PDF export — the main deliverable is a self-contained HTML file; PDF is opt-in via a zero-npm html-to-pdf.sh headless-browser script.

---

Workflow

Phase 0  Intake
   │
Phase 1  Source → Markdown      (URL / PDF / DOCX / MD / text → source.md)
   │
Phase 2  Editorial Planning     (one plan.md: Brief / Outline / Theme / Assets)
   │
★ Checkpoint 1  Plan            (5 independent decisions confirmed)
   │
Phase 4  First Spread           (cover + hero + first section + one signature visual)
   │
★ Checkpoint 2  First Spread    (acceptance + dev mode A/B)
   │
Phase 5  Full Article Build     (single-agent sequential or multi-agent parallel)
   │
Phase 6  Final Review           (Editorial / Visual / Technical)
   │
Phase 7  Repair                 (minimal-slice fixes only)
   │
★ Checkpoint 3  Delivery        (HTML, or HTML + PDF, or pause to revise)
   │
Phase 8  Delivery               (article.html, optional article.pdf)

The agent owns a per-project workspace directory that is its long-term memory:

<workspace>/
  source/   original.*   source.md   source.<lang>.md (if translated)   extraction-notes.md
  plan/     plan.md
  article/  Cover.tsx   Article.tsx   sections/   raw-blocks/   assets/   article.html (output)
  review/   first-spread-review.md   final-review.md
            (source-review.md only on complex sources, repair-log.md only when there are repairs)
  index.html  package.json  vite.config.ts  tsconfig*.json  (build harness)

---

Skill structure

skills/beautiful-article/
├── SKILL.md                            Main skill (frontmatter name: beautiful-article)
├── manifest.json                       Release manifest
├── README.md  /  README.zh-CN.md       This document
├── references/
│   ├── article-types.md                Article-type router
│   ├── article-types/                  briefing / dialogue / essay / explainer / full-report
│   │                                    interactive-explainer / longform / review / tutorial / visual-essay
│   ├── information-density.md          Retention ratios vs. component / visual mix
│   ├── plan-template.md                Single plan.md template (Brief / Outline / Theme / Assets)
│   ├── theme-selection.md              Theme picker, density / theme decoupling rules
│   ├── layout.md                       Width modes, TOC defaults
│   ├── cover.md                        3:4 book-style cover guide (5 self-checks, 5 layouts)
│   ├── asset-policy.md                 Image strategy (none / user-assets / placeholders / ai-generated)
│   ├── component-policy.md             Reacticle component contract, prose-first
│   ├── raw-policy.md                   Raw allow / deny list, token-driven, self-checks
│   ├── section-build.md                One-section-one-file rule, sub-agent prompt templates
│   ├── source-to-markdown.md           Per-format extraction rules + 5-item self-check
│   ├── scaffold.md                     Scaffold script behaviour, workspace layout
│   ├── html-output.md                  dev / build / single-file commands
│   ├── pdf-output.md                   html-to-pdf.sh usage + print CSS overrides
│   ├── review-checklist.md             Per-phase reviewer checklists & sub-agent prompts
│   ├── repair-policy.md                Minimal-slice repair table
│   └── harness.md                      Skill-as-harness perspective
├── theme-profiles/
│   ├── index.json                      Theme registry
│   └── andy / bayer / bodoni / freddie / fuller / knuth / press / shannon / sottsass / tufte / vignelli
├── scripts/
│   ├── scaffold.sh                     One-shot workspace bootstrap
│   ├── html-to-pdf.sh                  Optional HTML → PDF (headless browser, zero npm deps)
│   ├── pdf-print-overrides.css         @media print overrides injected into the HTML
│   ├── source-to-markdown-markitdown.py  Main extraction path (PDF / DOCX / HTML)
│   └── source-to-markdown.py           Lightweight fallback (Markdown / TXT / simple HTML)
└── assets/
    └── scaffold-template/              Vite + React + TS template the scaffold script copies

---

How it works (highlights)

1. Quality protocol per node

Different phases use different quality-checking approaches — over-using sub-agents and over-writing review files is the #1 perf trap, so the skill makes the rules explicit:

2. No silent default decisions

At every checkpoint each decision is asked independently — the agent may recommend, but never sneak through "I went ahead with X, tell me if it's wrong". Five independent decisions on Plan Checkpoint: article type (with recommended retention), theme, width, image mode, cover on/off.

3. Article type → retention bundles

The 10 article types all carry a recommended retention ratio: longform · ~100%, tutorial · ~90%, full-report · ~80%, explainer · ~80%, dialogue · ~80%, review · ~70%, essay · ~70%, briefing · ~50%, visual-essay · ~40%, interactive-explainer · ~25% excerpt + 75% AI-rebuild. Users can override with a single sentence.

4. One-section-one-file rule

Every Section is its own component file in article/sections/NN-*.tsx. Article.tsx is just the assembler — owned by the main agent, who imports & orders sections, runs typecheck / build, and resolves theme drift. This is the precondition for sub-agent parallelism in dev-mode B.

5. Theme tokens everywhere

Raw blocks must consume --ra-* theme tokens — no wild colors / fonts. Switching theme rewires every Raw block in one place. Each theme ships a Markdown authoring profile telling the agent how to write & style content under that theme.

---

Setting up a project

This skill does not pre-create a workspace — every project gets its own. From the SKILL's Phase 4:

# Default: cover on
bash <path-to-skill>/scripts/scaffold.sh ./my-article --theme=tufte

# Cover off
bash <path-to-skill>/scripts/scaffold.sh ./my-article --theme=press --no-cover

# List available themes
bash <path-to-skill>/scripts/scaffold.sh --list-themes

The scaffold spins up a Vite + React + TS workspace, installs the latest published reacticle from npm, and seeds source/ plan/ review/ plus article/Article.tsx, article/Cover.tsx, and article/sections/01-opening.tsx so the agent has a known starting shape.

After Phase 5 the agent runs the build to produce a single inlined HTML:

npm run build           # → article/article.html (CSS + JS inlined)

Optional PDF export (only if Checkpoint 3 selects HTML + PDF):

bash <path-to-skill>/scripts/html-to-pdf.sh

---

Best practices

Recommended

1. Pick the article type before anything else — its retention ratio anchors the whole plan. 2. Trust the harness phases — don't skip Plan checkpoint just because you can guess the answer. 3. Use theme tokens for every Raw block — --ra-* only. No raw hex / font names. 4. One section per file — even if a section is small, isolate it. It pays off in review and repair. 5. Cover should reflect theme + article gist — not just a placeholder gradient.

Avoid

1. ❌ Treating the skill as "make me an HTML page" — the deliverable is an article. 2. ❌ Bundling multiple checkpoint decisions into one yes/no. 3. ❌ Letting Raw blocks bring their own colors / typography (theme drift). 4. ❌ Writing all sections inside Article.tsx (kills sub-agent parallelism). 5. ❌ Removing the colophon / cover container (they are part of the contract).

---

FAQ

*Q1: When should I not use this skill?* When the user actually wants a web app, dashboard, form, prototype, or generic landing page — those go to web-design-engineer, not here. If in doubt, the skill stops and asks rather than silently producing the wrong artifact.

Q2: Does it always produce 100% information retention? No — that is just the longform default. The article type sets the ratio, and the user can override at Checkpoint 1.

Q3: Can the article be in a different language than the source? Yes. If the user specifies a target language different from the source, Phase 1 produces an idiomatic translation source/source.<lang>.md first, and Phase 2+ writes from that file.

Q4: What if my agent runtime has no SubAgent / Task tool? The skill notes this case explicitly: the main agent backfills the SubAgent's job and writes "no SubAgent environment, main-agent fallback" at the top of the resulting review file.

Q5: Why React + Vite + reacticle instead of plain HTML? Because the agent needs a stable, prose-first component contract that survives multi-section parallel work, theme switching, and Raw escape hatches. The npm run build step always inlines everything back into a single HTML for delivery.

---

Tool requirements

The skill assumes the agent runtime can:

• Spawn shell commands (for scaffold.sh, html-to-pdf.sh, npm builds)
• Read / write files in a project workspace
• (Optionally) launch sub-agents for First Spread / Section / Final review nodes
• (Optionally) run MarkItDown (Python) for high-fidelity PDF / DOCX / HTML extraction; otherwise the lightweight fallback script handles Markdown / TXT / simple HTML

---

License

MIT

Beautiful Article Skill —— 把任意素材编辑成一篇精美的文章

一个面向 AI Agent 的 Skill：把任意素材（URL / PDF / DOCX / Markdown / 纯文本 / 截图 / 粘贴材料）编辑、设计成一篇比原文更易读、更便于分享和归档的精美文章。

English · 返回集合首页

---

由 ReActicle 驱动

beautiful-article 是编辑型 harness（方法论、checkpoint、主题选型、sub-agent reviewer）；`reacticle` 是 Skill 在运行时调用的底层组件协议 —— prose-first 的 React 语义组件 + 基于主题 token 的 Raw 自由层，统一接到同一套主题系统上。

beautiful-article  （本 Skill · 方法论 + harness）
        │  调用
        ▼
reacticle          （npm 包 · 组件 / 主题 / Raw / 导出）

二者搭配最佳但相互独立：Skill 因为有 ReActicle 这个稳定目标层才能跑通；ReActicle 单独作为 React 组件库使用也完全立得住。

---

文章实例 —— 用 beautiful-article + ReActicle 写出来的真实文章

每一篇都是 AI Agent 用本 Skill 调用 `reacticle` 组件协议端到端写完的真实长文。点封面即可在线打开单文件 HTML 版本。

<table> <tr> <td width="50%" valign="top" align="center"> <a href="https://mmh1.top/#/ai-article/tools"> <img src="https://raw.githubusercontent.com/ConardLi/assets/main/imgs/article/tools.webp" alt="Agent Tools 设计的最佳实践" width="320"> <br><b>Agent Tools 设计的最佳实践</b> </a> <br>_{Theme · Freddie · 长文 · 21 min} <br>^{Anthropic 工程团队关于 Tools 的五条原则，与一套评测驱动的方法。} </td> <td width="50%" valign="top" align="center"> <a href="https://mmh1.top/#/ai-article/skill"> <img src="https://raw.githubusercontent.com/ConardLi/assets/main/imgs/article/skill.webp" alt="Agent Skill 是如何进化的？" width="320"> <br><b>Agent Skill 是如何进化的？</b> </a> <br>_{Theme · Freddie · 解释文 · 8 min} <br>^{把 Skill 文档当成被训练的对象，而不是被复制粘贴的 prompt。} </td> </tr> <tr> <td width="50%" valign="top" align="center"> <a href="https://mmh1.top/#/ai-article/harness"> <img src="https://raw.githubusercontent.com/ConardLi/assets/main/imgs/article/harness.webp" alt="Agent Harness 的解剖图" width="320"> <br><b>Agent Harness 的解剖图</b> </a> <br>_{Theme · Vignelli · 长文 · 12 min} <br>^{智能在模型里；让智能变得有用的，是它周围的那套系统。} </td> <td width="50%" valign="top" align="center"> <a href="https://mmh1.top/#/ai-article/prompt-cache"> <img src="https://raw.githubusercontent.com/ConardLi/assets/main/imgs/article/prompt-cache.webp" alt="提示词缓存对 Agent 有多重要？" width="320"> <br><b>提示词缓存对 Agent 有多重要？</b> </a> <br>_{Theme · Bayer · 长文 · 15 min} <br>^{缓存命中率是 Agent 的 SLO，Claude Code 团队的反直觉经验。} </td> </tr> <tr> <td width="50%" valign="top" align="center"> <a href="https://mmh1.top/#/ai-article/context"> <img src="https://raw.githubusercontent.com/ConardLi/assets/main/imgs/article/context.webp" alt="面向 Agent 的高效上下文工程" width="320"> <br><b>面向 Agent 的高效上下文工程</b> </a> <br>_{Theme · Tufte · 长文 · 16 min} <br>^{本文探讨如何高效地筛选与管理驱动 AI Agent 运转的上下文。} </td> <td width="50%" valign="top" align="center"> <a href="https://mmh1.top/#/ai-article/transformer"> <img src="https://raw.githubusercontent.com/ConardLi/assets/main/imgs/article/transformer.webp" alt="Attention Is All You Need" width="320"> <br><b>Attention Is All You Need</b> </a> <br>_{Theme · Tufte · 长文 · 30 min} <br>^{一篇重塑现代 AI 的论文，逐层拆给你看。} </td> </tr> <tr> <td width="50%" valign="top" align="center"> <a href="https://mmh1.top/#/ai-article/agent-eval"> <img src="https://raw.githubusercontent.com/ConardLi/assets/main/imgs/article/agent-eval.webp" alt="把 AI Agent 的评测讲清楚" width="320"> <br><b>把 AI Agent 的评测讲清楚</b> </a> <br>_{Theme · Tufte · 长文 · 25 min} <br>^{让 Agent 有用的那些能力，恰恰让它难以评测 —— 来自 Anthropic 的指南。} </td> <td width="50%" valign="top" align="center"> <a href="https://mmh1.top/#/ai-article/agent-loop-codex"> <img src="https://raw.githubusercontent.com/ConardLi/assets/main/imgs/article/agent-loop-codex.webp" alt="Codex 的 Agent Loop 是怎么做的？" width="320"> <br><b>Codex 的 Agent Loop 是怎么做的？</b> </a> <br>_{Theme · Sottsass · 长文 · 18 min} <br>^{OpenAI 官方分享：在 Responses API 之上，一条对话是如何被反复"展开"的。} </td> </tr> </table>

---

主题概览 —— 每套主题一篇样品文章

11 套主题已上架。每套主题的完整契约（.css token 包 + .md authoring profile、anti-patterns、code/media style）见 Theming。

每套主题都附一篇样品长文，从字体到摄影、代码、公式、Raw 块通通走一遍。点封面在线阅读，点主题名跳到该主题在文档站的章节。

<table> <tr> <td width="33%" valign="top" align="center"> <a href="https://rearticle.mmh1.top/#/gallery/caffeine-half-life"> <img src="https://raw.githubusercontent.com/ConardLi/assets/main/imgs/article/theam-tufte.webp" alt="Tufte · Data-Ink" width="260"> <br><b>Tufte</b> · Data-Ink </a> <br>_{咖啡因与睡眠 · 数据笔记} <br>^{Edward Tufte 数据墨水，证据优先，发丝级图表与最朴素的版式。} </td> <td width="33%" valign="top" align="center"> <a href="https://rearticle.mmh1.top/#/gallery/movable-type"> <img src="https://raw.githubusercontent.com/ConardLi/assets/main/imgs/article/theam-press.webp" alt="Press · 书卷" width="260"> <br><b>Press</b> · 书卷 </a> <br>_{活字之后 · 随笔} <br>^{Stripe Press 式书卷长读物：会落定的标题、氧化血红首字母、纯正文之美。} </td> <td width="33%" valign="top" align="center"> <a href="https://rearticle.mmh1.top/#/gallery/pool-exhaustion"> <img src="https://raw.githubusercontent.com/ConardLi/assets/main/imgs/article/theam-shannon.webp" alt="Shannon · 工程暗色" width="260"> <br><b>Shannon</b> · 工程暗色 </a> <br>_{连接池耗尽 · 故障复盘} <br>^{贝尔实验室技术论文血统，暗底黄金信号、回压依赖、夜间作战气质。} </td> </tr> <tr> <td width="33%" valign="top" align="center"> <a href="https://rearticle.mmh1.top/#/gallery/orbit-spec"> <img src="https://raw.githubusercontent.com/ConardLi/assets/main/imgs/article/theam-vignelli.webp" alt="Vignelli · 瑞士" width="260"> <br><b>Vignelli</b> · 瑞士网格 </a> <br>_{Orbit 设计系统规格 · 规格} <br>^{Massimo Vignelli 网格至上、grotesque 字族、瑞士红只承载结构。} </td> <td width="33%" valign="top" align="center"> <a href="https://rearticle.mmh1.top/#/gallery/linear-attention"> <img src="https://raw.githubusercontent.com/ConardLi/assets/main/imgs/article/knuth.png" alt="Knuth · 学术" width="260"> <br><b>Knuth</b> · 学术 </a> <br>_{线性化自注意力 · 预印本} <br>^{Donald Knuth / Computer Modern，编号小节、命题与证明、arXiv 草稿气质。} </td> <td width="33%" valign="top" align="center"> <a href="https://rearticle.mmh1.top/#/gallery/first-newsletter"> <img src="https://raw.githubusercontent.com/ConardLi/assets/main/imgs/article/theam-freddie.webp" alt="Freddie · 暖黄" width="260"> <br><b>Freddie</b> · 暖黄 </a> <br>_{第一封 Newsletter · 上手指南} <br>^{Mailchimp Freddie 黑字荧光，亲和插画 + 不端着的产品上手语气。} </td> </tr> <tr> <td width="33%" valign="top" align="center"> <a href="https://rearticle.mmh1.top/#/gallery/slow-breathing"> <img src="https://raw.githubusercontent.com/ConardLi/assets/main/imgs/article/theam-andy.webp" alt="Andy · 静谧" width="260"> <br><b>Andy</b> · 静谧 </a> <br>_{把呼吸放慢 · 练习} <br>^{柔软圆润、呼吸-神经跷跷板，让人慢下来的练习气质。} </td> <td width="33%" valign="top" align="center"> <a href="https://rearticle.mmh1.top/#/gallery/front-page"> <img src="https://raw.githubusercontent.com/ConardLi/assets/main/imgs/article/theam-bodoni.webp" alt="Bodoni · 报刊" width="260"> <br><b>Bodoni</b> · 报刊 </a> <br>_{头版的消亡 · 特稿} <br>^{高对比 Didone 报刊气质，黑白大报、对折线之上的分量。} </td> <td width="33%" valign="top" align="center"> <a href="https://rearticle.mmh1.top/#/gallery/geometry-of-meaning"> <img src="https://raw.githubusercontent.com/ConardLi/assets/main/imgs/article/theam-bayer.webp" alt="Bayer · 包豪斯" width="260"> <br><b>Bayer</b> · 包豪斯 </a> <br>_{形、色、网格 · 教学} <br>^{Herbert Bayer 包豪斯三原色几何，形有性格、色有重量。} </td> </tr> <tr> <td width="33%" valign="top" align="center"> <a href="https://rearticle.mmh1.top/#/gallery/rate-limiter-spec"> <img src="https://raw.githubusercontent.com/ConardLi/assets/main/imgs/article/theam-fuller.webp" alt="Fuller · 蓝图" width="260"> <br><b>Fuller</b> · 蓝图 </a> <br>_{限流器设计规格 · 系统设计} <br>^{Buckminster Fuller 工程蓝图，方格纸拓扑、令牌桶模拟，可照着实现。} </td> <td width="33%" valign="top" align="center"> <a href="https://rearticle.mmh1.top/#/gallery/color-clash"> <img src="https://raw.githubusercontent.com/ConardLi/assets/main/imgs/article/theam-sottsass.webp" alt="Sottsass · 孟菲斯" width="260"> <br><b>Sottsass</b> · 孟菲斯 </a> <br>_{撞色不翻车 · 设计随笔} <br>^{Memphis 80s 撞色，黑描边、硬投影、轻微旋转的不正经语法。} </td> <td width="33%" valign="top" align="center"> &nbsp; </td> </tr> </table>

完整的 11 套主题样品（含主题切换、搜索与筛选）在线 gallery：<https://rearticle.mmh1.top/#/gallery>。

---

这个 Skill 干什么

beautiful-article 把原本枯燥、线性、难以消化的文字材料变成视觉体验更漂亮、阅读节奏更清晰、也更便于审阅和分享的文章。它不是网页应用生成器 —— 注意力永远在"文章"本身：更好的阅读、更好的节奏、更好的美学。最终交付物是一份自包含、可离线打开的文件（可选随附 PDF），但那是交付细节、不是目标。

适合的场景：

• 把一篇长 URL / PDF / DOCX / Markdown 编辑成一篇网页长文
• 决策摘要 briefing、概念解释 explainer、教学步骤 tutorial、复盘 review、方案分析
• 视觉随笔 visual essay、对话 / 访谈 / 播客转写、交互式学习解释器
• 任何时候你希望比 Markdown 更好的阅读载体 —— 表格、SVG、代码、公式、复制 / 导出按钮一条龙

Skill 本质上是一个方法论 + 协作 harness。它附带一个 Vite + React + TypeScript 脚手架，基于 `reacticle` 组件协议 —— Agent 不手写裸 HTML / CSS，而是用 prose-first 的语义组件 + 主题约束的 Raw 自由层来组合。

---

核心思想

• 首先是一篇文章，不是应用 —— 注意力永远在文章。Raw 自由层、SVG、小工具必须服务阅读 / 解释 / 节奏 / 审美，不能喧宾夺主。
• Source → Plan → Build → Review 小型 harness —— 每个项目走 6 个有编号的 phase，中间有 3 个硬 checkpoint。
• `reacticle` 组件协议 —— 语义化的 prose 组件（Hero / Lead / Section / Quote / Callout / Image / Formula / CodeBlock / Table …）+ 一个必须用主题 token（--ra-*）的 Raw 自由层。
• 主题驱动设计 —— 内置 11 套 authoring profile（tufte / press / bayer / bodoni / vignelli / sottsass / freddie / andy / fuller / knuth / shannon），每套是给 Agent 看的 Markdown 契约，不是 CSS 文件。
• 默认 100% 信息保留 —— 文章类型自带推荐保留比例（longform ~100% / briefing ~50% / visual-essay ~40% …），用户可一句话覆盖。
• 硬协作 checkpoint —— Plan、首屏样张、最终交付前 Agent 必须停下来；每个决策必须逐项独立确认，不允许打包一个"全部 OK 吗"。
• 默认带封面 —— 一个 3:4 书封式题图位于 TOC 之上，外壳锁死、只能用主题 token、不允许远程图片。
• PDF 导出可选 —— 主交付物是一份自包含的 HTML 文件；PDF 只在用户在 Checkpoint 3 主动选择时通过零依赖的 html-to-pdf.sh 生成。

---

工作流

Phase 0  Intake
   │
Phase 1  Source → Markdown      （URL / PDF / DOCX / MD / 文本 → source.md）
   │
Phase 2  Editorial Planning     （一份 plan.md：Brief / Outline / Theme / Assets）
   │
★ Checkpoint 1  Plan            （5 个独立决策逐项确认）
   │
Phase 4  First Spread           （封面 + Hero + 第一节 + 一个代表性视觉块）
   │
★ Checkpoint 2  First Spread    （验收 + 后续开发模式 A/B）
   │
Phase 5  Full Article Build     （单 Agent 顺序 / 多 Agent 并行）
   │
Phase 6  Final Review           （Editorial / Visual / Technical 三视角）
   │
Phase 7  Repair                 （只允许最小切片修复）
   │
★ Checkpoint 3  Delivery        （HTML，或 HTML + PDF，或暂停修订）
   │
Phase 8  Delivery               （article.html，可选 article.pdf）

每个项目都有自己的工作区目录，作为 Agent 的长期记忆：

<workspace>/
  source/   original.*   source.md   source.<lang>.md（需翻译时）   extraction-notes.md
  plan/     plan.md
  article/  Cover.tsx   Article.tsx   sections/   raw-blocks/   assets/   article.html（产物）
  review/   first-spread-review.md   final-review.md
            （source-review.md 仅复杂源；repair-log.md 仅有修复时）
  index.html  package.json  vite.config.ts  tsconfig*.json   （构建工装）

---

Skill 目录结构

skills/beautiful-article/
├── SKILL.md                            主 Skill 文件（frontmatter name: beautiful-article）
├── manifest.json                       发布清单
├── README.md  /  README.zh-CN.md       本文档
├── references/
│   ├── article-types.md                文章类型路由
│   ├── article-types/                  briefing / dialogue / essay / explainer / full-report
│   │                                    interactive-explainer / longform / review / tutorial / visual-essay
│   ├── information-density.md          保留比例与组件 / 视觉比例的关系
│   ├── plan-template.md                单一 plan.md 模板（Brief / Outline / Theme / Assets）
│   ├── theme-selection.md              主题选择，density 与 theme 解耦
│   ├── layout.md                       版式宽度、TOC 默认值
│   ├── cover.md                        3:4 书封封面指南（5 条自检 + 5 个构图模板）
│   ├── asset-policy.md                 配图策略（none / user-assets / placeholders / ai-generated）
│   ├── component-policy.md             Reacticle 组件契约、prose-first
│   ├── raw-policy.md                   Raw 允许 / 禁止表、token 驱动、自检
│   ├── section-build.md                一节一文件铁律、subagent prompt 模板
│   ├── source-to-markdown.md           各类输入抽取规则 + 5 条自检
│   ├── scaffold.md                     脚手架行为、工作区结构
│   ├── html-output.md                  dev / build / 单文件 HTML 命令
│   ├── pdf-output.md                   html-to-pdf.sh 用法 + print CSS 覆盖
│   ├── review-checklist.md             各阶段 reviewer 清单与 sub-agent prompt
│   ├── repair-policy.md                最小切片修复对照表
│   └── harness.md                      Skill-as-harness 视角
├── theme-profiles/
│   ├── index.json                      主题注册表
│   └── andy / bayer / bodoni / freddie / fuller / knuth / press / shannon / sottsass / tufte / vignelli
├── scripts/
│   ├── scaffold.sh                     一键创建工作区
│   ├── html-to-pdf.sh                  可选 HTML → PDF（headless 浏览器，零 npm 依赖）
│   ├── pdf-print-overrides.css         注入 HTML 的 @media print 覆盖
│   ├── source-to-markdown-markitdown.py  主路径抽取（PDF / DOCX / HTML）
│   └── source-to-markdown.py           轻量 fallback（Markdown / TXT / 简单 HTML）
└── assets/
    └── scaffold-template/              脚手架脚本拷贝的 Vite + React + TS 模板

---

它是怎么工作的（要点）

1. 各节点的质检协议

不同 phase 用不同的质检方式 —— 滥开 SubAgent、滥写 review 文件是首要性能问题，所以 Skill 把规则写明：

2. 禁止静默替用户选择

每个 Checkpoint 的每一项决策必须独立问 —— Agent 可以推荐，但不能"我已经替你定了 X，不对再说"。Plan Checkpoint 5 项独立决策：文章类型（含推荐保留比例）/ 主题 / 版式宽度 / 配图模式 / 封面开关。

3. 文章类型 → 保留比例打包

10 种文章类型都自带推荐保留比例：longform · ~100% / tutorial · ~90% / full-report · ~80% / explainer · ~80% / dialogue · ~80% / review · ~70% / essay · ~70% / briefing · ~50% / visual-essay · ~40% / interactive-explainer · ~25% 摘录 + 75% AI 重构。用户可一句话覆盖。

4. 一节一文件铁律

每个 Section 都是 article/sections/NN-*.tsx 单文件组件。Article.tsx 只是 assembler —— 由主 Agent 拥有，负责 import 与排序、跑 typecheck / build、解决主题漂移。这是后续多 Agent 并行的前提。

5. 全程主题 token

Raw 块必须只用 --ra-* 主题 token —— 不允许野生颜色 / 字体。换主题时所有 Raw 块一处生效。每个主题都有一份 Markdown authoring profile，告诉 Agent 在该主题下怎么写、怎么排版。

---

创建一个项目

Skill 不预先创建工作区 —— 每个项目自己开。来自 Phase 4 的命令：

# 默认开封面
bash <path-to-skill>/scripts/scaffold.sh ./my-article --theme=tufte

# 关闭封面
bash <path-to-skill>/scripts/scaffold.sh ./my-article --theme=press --no-cover

# 查看可用主题
bash <path-to-skill>/scripts/scaffold.sh --list-themes

脚手架会拉起 Vite + React + TS 工作区，从 npm 装最新 reacticle，并放好 source/ plan/ review/ 三个目录 + article/Article.tsx / article/Cover.tsx / article/sections/01-opening.tsx 三份起点文件。

Phase 5 完成后 Agent 跑构建产出单文件 HTML：

npm run build           # → article/article.html（CSS + JS 全内联）

可选 PDF 导出（仅当 Checkpoint 3 用户选了 HTML + PDF）：

bash <path-to-skill>/scripts/html-to-pdf.sh

---

最佳实践

推荐

1. 先定文章类型 —— 它的保留比例锚定整个 plan。 2. 信任 harness 的 phase —— 不要因为"答案显而易见"就跳过 Plan checkpoint。 3. Raw 块只用主题 token —— --ra-*，禁止裸颜色 / 字体名。 4. 一节一文件 —— 哪怕这一节很短，也要隔离。review 与修复阶段会回报这点投入。 5. 封面要呼应主题 + 文章主旨 —— 不是一个占位渐变。

避免

1. ❌ 把 Skill 当成"帮我做个 HTML 页面" —— 交付物是文章。 2. ❌ 把多个 Checkpoint 决策打包成一个 yes/no。 3. ❌ Raw 块自带颜色 / 字体（主题漂移）。 4. ❌ 把所有 Section 都写进 Article.tsx（杀死 sub-agent 并行）。 5. ❌ 删除 colophon / 封面外壳（这些是契约的一部分）。

---

常见问题

Q1：什么时候不应该用这个 Skill？ 当用户其实想要的是网页应用 / dashboard / 表单 / 原型 / 通用 landing page —— 这些去找 web-design-engineer，不是这里。不确定时 Skill 会停下来澄清，而不是默默生成错的产物。

Q2：是不是总是 100% 信息保留？ 不是 —— 那只是 longform 类型的默认值。文章类型决定推荐比例，用户可以在 Checkpoint 1 覆盖。

Q3：文章语言可以与源材料不同吗？ 可以。如果用户指定的目标语言与源不一致，Phase 1 会先产出地道翻译版 source/source.<lang>.md，Phase 2+ 据此编写。

Q4：如果 Agent 运行时没有 SubAgent / Task 工具怎么办？ Skill 显式照顾了这种情况：主 Agent 兜底承担 SubAgent 的工作，并在 review 文件首注明"无 SubAgent 环境，主 Agent 兜底"。

Q5：为什么用 React + Vite + reacticle 而不是裸 HTML？ 因为 Agent 需要一个稳定的、prose-first 的组件契约 —— 它要扛住多 Section 并行写作、主题切换、Raw 自由层这些场景。npm run build 时所有依赖会全部内联回单文件 HTML 交付。

---

工具要求

Skill 假设 Agent 运行时可以：

• 启动 shell 命令（用于 scaffold.sh / html-to-pdf.sh / npm 构建）
• 在工作区读写文件
• （可选）开启 sub-agent 来跑 First Spread / Section / Final review
• （可选）调用 MarkItDown（Python）做高保真 PDF / DOCX / HTML 抽取；不可用时由轻量 fallback 脚本处理 Markdown / TXT / 简单 HTML

---

许可证

MIT

文章类型路由

文章类型是结构决策，主题是审美决策（见 theme-selection.md）—— 两者完全解耦。

文章类型与信息保留比例的关系（重要）：理论上"内容保留是独立决策"，但实践中两者 绑定很紧。每个类型都自带一个标配保留比例（见下表"推荐信息保留"列）。longform + 20% / tutorial + 20% / briefing + 100% 这类组合是伪选项：要么类型变形（briefing+100%≈full-report）， 要么内容空洞（longform 写出 8 章每章 2 段）。所以 Plan Checkpoint 1 把"保留比例"打包进"文章 类型"的语义化选项里（见 SKILL.md Phase 3），只在用户明确想精修（如"longform 但只要 60%" = 一篇被深度编辑的长文）才作为非标配组合记入 plan.md。

Phase 2 选定类型后，读对应 article-types/<type>.md 拿结构 / 组件 / Raw 边界 / 配图倾向 / 自检。非标配组合要在 plan/plan.md Brief 段同时记下"标配 X% → 用户覆盖 Y%"，并让主 Agent 在写每节时手动调整正文/视觉比例（不能照搬 article-types/<type>.md 的默认建议）。

选型提示

• 源材料信息密度高、要完整归档 → longform。
• 源材料是消化后的报告 / 正式分析（执行摘要 + 数据 + 风险 + 建议四件套）→ full-report。
• 要把一个机制 / 概念讲清楚（正文为主）→ explainer。
• 要让读者"玩明白"一个概念（Raw 交互为主，正文为辅，每知识点配交互演示）→ interactive-explainer。
• 对话 / Q&A / 访谈 / 播客转录 / AMA → dialogue。
• 评审某个 工程 PR / 方案 / 事故 / 设计 → review。
• 给决策者快速判断 → briefing。
• 观点输出 / 评论 / 产品 / 书 / 论文评测 → essay。
• 教别人上手做事（步骤 + 跑通）→ tutorial。
• 传播 / 展示、图文主导 → visual-essay。

类型只定结构倾向，不锁死信息密度和主题；用户可在 Plan Checkpoint 覆盖。

Article Type · briefing

给忙人（决策者 / 同事 / 投资人）快速判断用。读者不会读完全文，所以每段都得帮决策。

• 推荐信息保留：40-60%（只留重点结论、关键证据、关键取舍、下一步；删一切铺垫 / 推导 /

背景 / 历史）。

• 典型结构：Hero（标题 = 一句话结论）→ Summary（结论先行 + 3-5 个关键事实，最重要

的一块）→ Section：关键证据 → 取舍 / 风险 → 下一步 / 行动项。短而紧凑，整体阅读时间 控制在 3-5 分钟。不必有 Conclusion（Summary 已经把结论说了）。

• 组件选择：仍 prose-first，正文短句直给（每段最好不超过 3 句）。Summary 是核心 ——

这是 briefing 的灵魂。其余按需：

• Table：确需 N 项并排对比时。
• Decision / Tradeoff：确有"X vs Y"取舍要展示时。
• ActionList：确有下一步要列时（谁做 / 何时做）。
• 不要因为是 briefing 就堆组件 —— briefing 贵在精简，组件多了反而显冗。
• Raw 边界：少量但有力 —— 一个关键对比图 / 趋势 / 选项矩阵 / 决策树；不堆视觉。

一篇 briefing 通常 0-2 块 Raw。

• 配图倾向：none 或单张关键图（数据图 / 关键截图）；偏 tufte 证据感或 press

简洁编辑感。

• 主题倾向：tufte（数据型 briefing）、vignelli（中性规格）、press（编辑节奏）。
• 自检：
• 30 秒内（只读 Hero + Summary）能抓到结论吗？
• 每段是否都在帮决策（这段删掉决策会受影响吗）？
• 有没有冗余展开 / 解释来由 / 历史背景 / "之所以这样"段落？
• 行动项是否可执行（谁做 / 何时做 / 怎么验收）？
• 整体阅读时间是否真的在 3-5 分钟？超过就不是 briefing 了。

何时不要用 briefing：

>

- 要让读者完整理解而非快速判断 → longform / full-report / explainer。

- 评审某个具体产物 → review。

- 给读者学懂一个概念 → explainer / interactive-explainer。

Article Type · dialogue

对话 / Q&A / 访谈 / 播客转录 / AMA / 圆桌。任何"多个声音轮流说话"的内容形式。

• 推荐信息保留：80%（删冗余口语 / 重复 / 寒暄，保留实质内容；不删观点也不改语气）。
• 典型结构：Hero（话题 + 嘉宾 + 主持 + 日期 / 来源）→ Lead（背景 / 为什么聊这个）→

多个 Section，每节一个话题或问题，正文用 发言者明示 + 大量 `Quote` 体现对话节奏 → 可选 Summary 放"关键观点摘要"在文章开头或结尾 → Conclusion（要点 / 延伸阅读）。

• 组件选择：
• 正文中每段开头明示发言者（如 **A**：… / **主持**：…），避免读者搞混；
• Quote 大量使用 —— 嘉宾的金句、原话、关键定义都用 Quote 抬出来；
• Aside tone="principle" 标定义 / 数据 / 概念解释；
• Summary 在开头放"3-5 个关键观点"，让快速读者也能拿到精华；
• 少用 Table / CodeBlock（对话很少有结构化技术内容；有时一律按嘉宾原话放代码段）；
• Detail 折叠可选的延伸 / 注释。
• Raw 边界：可用 Raw 做话题地图（章节导航 / 时间线）、关键概念可视化（嘉宾解释了

什么机制就配一张 Raw 图解）、金句卡片；不要装饰性弹幕 / 动画头像。

• 配图倾向：user-assets（嘉宾头像 / 现场照片 / 提到的截图）或 none（纯文本对话）；

少用 ai-generated 氛围图。

• 主题倾向：press（出版编辑感，适合长对话 / 访谈）、bodoni（杂志感专访）、freddie

（活泼播客感）。

• 自检：
• 发言者归属清晰，不会让读者搞错"是谁说的"？
• 对话节奏保留？没有把它压成"单声音综述"？
• 关键观点能在 30 秒内从 Summary 抓到？
• 删减后嘉宾原意没有被改写 / 误传？
• 移动端发言者标记仍然清晰？

未来扩展：若 reacticle 组件库新增 Dialogue / Speaker 等专用对话组件，本类型应优先使用。

当前实现用 Quote + 正文显式标注即可。

Article Type · essay

观点、评论、叙事、评测（产品 / 书 / 论文 / 电影）、随笔、专栏、宣言。观点驱动的非 虚构写作。

• 推荐信息保留：60-80%（保留论证链与最有力的例证；删旁枝、删冗长引用、删重复的换句话）。
• 典型结构：Hero（标题气质强）→ Lead（抛出张力 / 矛盾 / 反直觉问题，钩住读者）

→ Section：开场 → 论点 → 例证 → 转折 → 收束。结构服务叙事节奏，不必规整对称 —— 一篇好 essay 可以是 3 节也可以是 7 节，看节奏。

• 组件选择：正文是绝对主体；Quote 引名言 / 原话 / 反方观点；Aside tone="aside"

放旁注 / 个人评论 / 反方立场；少用 Table / RiskList 等数据组件（会破坏叙事感）； Summary 仅在长 essay 时用。

• Raw 边界：偶尔一个有表现力的视觉停顿（节奏图 / 概念对比 / 情绪曲线），服务叙事而非

解释机制；密度低 —— 一篇 essay 通常 1-3 块 Raw 就够了。

• 配图倾向：press 暖色编辑摄影 / 插图 / 手稿；服务气氛但不喧宾夺主。评测型 essay

可用 user-assets（产品 / 书 / 电影截图）。

• 主题倾向：press（出版编辑型）、bodoni（专栏 / feature）、andy（柔软叙事）、

sottsass（活泼文化评论）。

• 自检：
• 是否有一条清晰的论证 / 叙事线？读者能否一句话复述这篇的核心观点？
• 例证是否有力？是否最少 2 个具体例子（而不是空泛论断）？
• 语气是否一致、像人写的（不是 AI 味、不是套路化展开）？
• Lead 是否真的"抛出张力"，而不是温吞地铺垫背景？
• 收束是否给读者留下点什么（不一定结论，可以是新问题 / 新视角）？

何时不要用 essay：

>

- 评审工程产物（PR / 方案 / 事故）→ review。

- 给读者做决策 → briefing。

- 要把一个机制讲清楚 → explainer。

- 是对话 / 访谈整理 → dialogue。

Article Type · explainer

解释一个机制 / 系统 / 概念 / 算法 / 协议。读者读完真懂这个东西怎么回事、为什么这样、 何时用 / 不用。

• 推荐信息保留：80%（保留主要机制和关键细节，删重复 / 旁枝 / 历史背景；保留所有"关键

直觉"和"易错点"）。

• 典型结构：Hero → Lead（为什么要懂这个 / 不懂的代价）→ Section：问题 → 机制 →

图解 → 示例 → 常见误区 → 何时用 / 不用 → Conclusion。

• 组件选择：正文讲机制（正文仍是主体，不要拆成卡片堆）；Aside tone="principle"

点出"关键直觉 / 一句话本质 / 易错点"；CodeBlock 给具体示例；Table 对比方案 / 对比变种； Detail / Tabs 折叠次要细节和深入推导；Quote 引原论文 / 规范原文。

• Raw 边界：鼓励多用解释性视觉 —— 机制流程、状态变化、数据流向、概念关系可用 Raw

自由层（HTML 布局 / 轻交互 / 动效 / 按需 SVG），让抽象概念可视、可对照；每块服务一个 具体机制点。Raw 是辅助而非主体 —— 如果你发现 Raw 承载了主要信息、正文变成了图注，那应 该考虑 interactive-explainer。

• 配图倾向：解释性视觉优先（Raw —— 交互 / 布局 / 动效 / SVG 均可）；需要真实界面 / 系统

截图时用 user-assets；少用氛围图。

• 主题倾向：tufte（技术 / 数据型）、shannon（系统 / 工程型）、knuth（学术型）、

freddie / bayer（面向新手的活泼型）、fuller（系统设计 / 协议型）。

• 自检：
• 读者读完是否真懂这个机制（不只是"知道有这个东西"）？
• 图解是否服务理解还是装饰？删掉是否影响理解？
• 常见误区是否覆盖（最容易踩的 2-3 个坑）？
• "何时用 / 不用"是否清楚？这是 explainer 与 longform 的关键差别。
• 长技术文章如果可以删 20% 仍能讲清，优先用 explainer；要原文归档用 longform。

何时不要用 explainer：

>

- 要让读者操作着学懂（Raw 是主载体）→ interactive-explainer。

- 要让读者跟着做出来一个东西 → tutorial。

- 源材料是论文 / 报告级别的完整论证 → longform / full-report。

Article Type · full-report

研究报告、正式分析、技术评估、年度回顾、调研报告。源材料具备"执行摘要 + 关键发现 + 数据 + 风险 + 建议"骨架，或可以被重组成这个骨架。

• 推荐信息保留：80%（消化原始材料后的报告化呈现；删冗余推导、扩展阅读、附录细节，

保留执行摘要 / 关键发现 / 数据 / 风险 / 建议四件套不动）。若用户的源材料就是报告原文 且要 100% 归档，覆盖为 100% 并按"非标配组合"在 plan/plan.md Brief 段记下。

• 典型结构：Hero（标题 + 报告期 / 范围 / 作者 / 单位）→ Summary（**执行摘要 / 关键

结论先行，必备）→ `Section`：背景与方法 → 关键发现 → 数据与证据 → 风险与限制 → 建议与 下一步 → `Conclusion`（核心结论复述 + 决策建议）。TOC 必开**。

• 组件选择：Summary 放"关键结论 + 关键数据"（让快读者 30 秒能拿到核心）；Table 承载

数据 / 对比；RiskList / Decision / Tradeoff 承载风险与取舍；CodeBlock / Formula 承载技术证据；ActionList 承载建议清单；正文承载论证过程。

• Raw 边界：数据图、趋势、对比矩阵、风险热度图、依赖关系等用 Raw 自由层（HTML / CSS

图表与矩阵、轻交互、按需 SVG / canvas）；保持证据感、低装饰——避免动效抢戏，避免氛围 渐变色。

• 配图倾向：none 或真实数据图 / 报告截图（tufte 风）；避免氛围图 / 配图打断阅读。

如有产品截图，要服务一个具体结论。

• 主题倾向：tufte（数据型）、knuth（学术型）、vignelli（中性规格 / 标准化报告）、

fuller（系统设计 / RFC 风格）。

• 自检：
• 结论是否在文章开头 30 秒内能抓到？
• 数据 / 风险 / 建议是否齐全且有据可循（每条建议指向哪些发现）？
• 是否像一份正式报告而非营销页或长文随笔？
• Table / RiskList / Decision 等是因为内容是这样才用，还是为了"显得专业"硬塞？

何时不要用 full-report：

>

- 源材料是连贯论证 / 叙事长文 → longform。

- 用户要的是"给老板看"的决策摘要而非完整报告 → briefing。

- 评审某个具体 PR / 方案 / 事故 → review。

Article Type · interactive-explainer

把一篇长技术文章 / 论文 / 系统设计稿，重构为以交互动画为主载体的"会用了再走"式学习页。 参考路径：3blue1brown 视觉化、distill.pub 的可调参数式机器学习解释、Bartosz Ciechanowski （ciechanow.ski）的"硬件原理可玩页"。

与 explainer 的关键区别：

>

- explainer：正文是主体，Raw 是辅助插图。读者读完"知道了"。

- interactive-explainer：Raw 是主体，正文是简短引导和定义。读者操作完"会用了"。

• 推荐信息保留：~25%（**注意：这里的百分比不是"原文删了 75%"，而是"成品里直接来自

原文的句子 / 段落只占约 25%"。本类型的本质是内容重构 —— 从原文里只摘核心知识 点的关键定义、公式、数据、约束、易错点；其余 75% 由 AI 围绕这些知识点全新创作：引导 文字、直觉解释、交互演示、自己试、验证理解。原文的叙事铺垫、历史背景、案例展开、扩展 讨论全部舍弃，由交互替代。不要把它当"删 50% 的 explainer"做**，那样既学不透也失去 本类型存在的意义。

• 典型结构：
• Hero（一句话定位：这页让你学懂什么 / 玩什么）
• Lead（前置：1-2 句话提示你需要哪些基础，玩完能做到什么）
• 可选 Summary（列出 N 个核心知识点作为路线图）
• 多个 Concept Section，每个一个核心知识点，节内三段式：

1. 定义 / 直觉：1-3 段正文 + 一个 Aside tone="principle" 抬出一句话直觉。 2. 交互演示（Raw 主体）：动画 / 滑块 / 拖拽 / 状态切换 / 参数变化的实时可视化。 3. 自己试 / 验证理解（Raw 交互）：让读者动手试一个边界 / 反例 / 应用场景；可选一个 "答案揭晓"的折叠。

• Conclusion（知识点串联回顾 + 何时用 / 不用 + 延伸阅读）。
• 组件选择：
• 正文短：每节正文加起来通常不超过 200-400 字；
• Aside tone="principle" 标定义、关键直觉、易错点；
• Detail / Tabs 折叠次要细节、答案、推导；
• Quote 引原文 / 论文金句；
• 少用 Table / CodeBlock（如有，必须服务一个具体交互演示，不放整页代码）；
• Raw 是主角。
• Raw 边界（核心 · 必读）：
• 每个 Raw 必须服务一个具体知识点，不允许装饰性炫技。
• 操作性优先：滑块 / 拖拽 / 切换 / 输入框 / 步进按钮；让用户改变某个量并**实时看到

结果**。比"看一段动画"更深。

• 状态可见：当前参数、当前数值、当前阶段都要显式可见，不要藏在动画里。
• 可重置：每个交互配"reset"或"恢复初值"，鼓励反复试。
• 样式走 token：颜色 / 字体 / 间距用 --ra-*，不写野生 CSS。
• 错误示例同样有价值：让用户拖到"会出错"的位置，配一行说明"为什么这里崩"。
• 配图倾向：none 优先（交互比图片更有信息量）；少量 placeholders（理论图 / 截图）；

避免 ai-generated（氛围图打断学习节奏）。

• 主题倾向：tufte（克制 + 数据感，适合 ML / 算法可视化）、shannon（暗底工程感，

适合系统 / 硬件交互演示）、knuth（学术克制，适合论文重构）；避免 freddie / sottsass 这类活泼配色（会让交互显得像游戏而非学习）。

• 自检：
• 读者玩完是否真正会用这个概念，而不只是"听过 / 看过"？
• 每个交互是否服务一个具体知识点？有没有炫技但学不到东西的 Raw？
• 没有交互的章节，是真的不需要交互，还是偷懒了？（这是判断本类型是否走样的关键问题）
• 移动端能不能操作？很多滑块 / 拖拽 / 复杂 SVG 在 mobile 上不能用 —— 必须在 Plan 阶段就

决定"是否放弃 mobile 交互" 还是"提供 mobile 替代展示"。

• 删掉所有 Raw 后，剩下的正文是不是太薄？太薄说明 Raw 没把信息装进去 —— 应该在 Raw 内或

紧邻位置补足。

• 成品里"直接来自原文的句子 / 段落"比例确实在 ~25% 这个量级吗？太高（>40%）说明你

在"删 explainer"而不是重构；太低（<10%）说明核心知识点没说清。

• 核心知识点筛选有据：能否一句话说出"这页保留的 N 个知识点为什么是这 N 个"？随便挑

几个是这个类型走样的开端。

何时不要用 interactive-explainer：

>

- 源材料是叙事 / 观点 / 评论（→ essay）。

- 源材料是步骤型操作（→ tutorial，步骤之间有先后依赖，不是知识点的并列）。

- 源材料是数据报告（→ full-report，结论比交互重要）。

- 你不打算写真正可操作的 Raw（→ explainer 即可，别假装 interactive）。

Article Type · longform

完整长文、归档、深度阅读。这是默认类型。源材料是连贯论证 / 叙事 / 综述，且用户要原 文级保留。

• 推荐信息保留：100%（原文关键内容不丢；只允许删除明显的重复段落和无信息的过场句）。
• 典型结构：Hero → Lead（导语，框定主题）→ 可选 Summary（TL;DR / 结论先行）→

多个 Section（必要时 Subsection）→ 关键概念处 Raw 增强 → Conclusion。长文（>10 小节或预估阅读 >15 分钟）开启 TOC。

• 组件选择：正文段落为绝对主体，应占文章绝大部分篇幅；Aside 点出关键直觉 /

历史注 / 反方观点；Quote 引用名言或原话；Table 承载二维数据；技术内容用 CodeBlock / Formula。不要把连贯段落拆成卡片堆 —— 卡片堆是 longform 最常见的走样形态。

• Raw 边界：在关键概念、数据趋势、机制处插入 Raw 自由层（轻交互 / 自定义排版 / 动效 /

按需 SVG），给长文节奏与呼吸；每块服务具体段落，用 --ra-* token。Raw 是增强而非主体 —— 如果开始让 Raw 承载主要信息，说明你应该考虑 explainer 或 interactive-explainer。

• 配图倾向：none / placeholders 优先；技术 / 证据型可用真实数据图（tufte 风）；

叙事型可加少量 press 风氛围图。

• 主题倾向：tufte（技术 / 证据型）、knuth（学术 / 论文）、press（叙事 / 综述）、

bodoni（专栏 / feature）。

• 自检：
• 正文是否仍是绝对主体？没有把段落拆成卡片堆？
• 章节衔接是否自然？读者读完一节会自然想读下一节？
• Raw 是点亮关键概念还是打断阅读节奏？
• 100% 信息是否读起来像被精修过的长文（而非原文搬运）？
• 长文有没有 TOC + Summary 帮助读者定位？

何时不要用 longform：

>

- 源材料是消化后的报告（执行摘要 + 风险 + 建议四件套）→ full-report。

- 源材料是要解释一个机制 / 概念，可以删 20% → explainer。

- 源材料是论文 / 长文但你想做成交互学习页 → interactive-explainer。

- 给忙人看 / 要决策 → briefing。

Article Type · review

工程审阅：PR / 方案设计 / 事故复盘 / 架构 / API / 安全审计。起点是审阅一份具体产物 并产出意见与行动。

• 推荐信息保留：60-80%（保留关键发现 + 证据 + 行动；省略无关细节 / 上下文铺垫）。
• 典型结构：Hero（被评对象 + 评审范围 + 评审日期 / 评审人）→ Summary（**结论 /

评审意见先行**）→ Section：背景与目标 → 发现（逐条） → 影响评估 → 建议 → 行动项 → Conclusion（核心判断 + 通过 / 待修 / 否决）。

• 组件选择：仍 prose-first —— 结论与发现先用正文 + Summary 讲清楚。下面是**领域

特例组件，只在内容确实是该结构时**按需取用，不要因为是 review 就全堆上：

• RiskList：确有一组需要分级的风险时。
• DiffReview：确有代码改动要逐行评时；代码一律用 CodeBlock。
• Decision / Tradeoff：确有"X vs Y"的取舍要展示时。
• Incident：事故复盘时的时间线。
• ActionList / Checkpoint：行动项 / 验收点确需结构化时。
• Raw 边界：影响范围图、依赖关系、风险热度矩阵、调用链、监控曲线等用 Raw 自由层

（HTML / CSS 矩阵 + 热度、轻交互、按需 SVG）；克制、证据优先、不抢正文。

• 配图倾向：user-assets 真实截图 / diff / 监控图 / dashboard 截图（tufte 风）。
• 主题倾向：tufte（证据型 review）、shannon（暗底工程 / 事故复盘）、fuller（系统设计

/ RFC review）、vignelli（中性规格型）。

• 自检：
• 评审意见是否在文章开头先行清楚（通过 / 待修 / 否决）？
• 每条发现是否有证据支撑（代码片段 / 截图 / 数据 / 日志），不是凭感觉？
• 建议与行动项是否可执行（谁做 / 何时做 / 怎么验收）？
• 起点是审阅一份具体产物？如果起点是"读者要做决策"，应该用 briefing。

何时不要用 review：

>

- 评测产品 / 书 / 论文 / 电影（观点驱动，没有"通过 / 否决"二元判断）→ essay。

- 给老板做一份"该不该做 X"的决策摘要 → briefing。

- 完整的事后调研报告 → full-report。

Article Type · tutorial

教学、步骤、上手指南、安装配置、迁移手册。读者跟着做就能跑通的内容。

• 推荐信息保留：80-100%（步骤不能丢，否则跟不下来；可删的只有冗长背景、可选的深入

扩展、不影响跑通的"为什么"段落）。

• 典型结构：Hero → Lead（学完能做什么 / 前置条件 / 预计用时）→ 可选 Summary

（整体路径鸟瞰）→ Section：每个阶段一节，节内 = 目标 → 步骤（逐步）→ 示例 → 验收点 → 常见坑 → 可选 Section：练习 / 扩展 → Conclusion（总结 + 下一步学什么）。

• 组件选择：CodeBlock 给每一步代码（保真，可复制运行）；ActionList /

Checkpoint 列步骤与验收点；Aside tone="warning" 标坑 / 注意事项；Detail 折叠可选的 深入解释 / 替代方案；Table 列参数 / 选项 / 配置项；Tabs 给多平台 / 多语言并列示例。

• Raw 边界：流程图、状态变化（before / after）、UI 步骤示意、命令前后对照用 Raw 自由层

（HTML 步骤布局 / 轻交互 / 按需 SVG）；让步骤可视、可对照。不必为每步都加 Raw —— 代码 + 截图能讲清楚的就不加。

• 配图倾向：user-assets 优先（真实截图每个关键步骤）；纯命令行类教程可用 none。
• 主题倾向：vignelli（中性规格 / 文档感）、freddie（活泼上手）、fuller（系统配置 /

RFC 风格）、tufte（密度高的技术教程）。

• 自检：
• 照着做能否真的跑通？没有跳步 / 没有"省略号 …"假装代码？
• 步骤是否完整有序？每步都有验收点（怎么知道这步成了）？
• 代码是否可直接复制运行？不缺 import / 不缺环境说明？
• 常见坑是否标注（版本不匹配 / 权限不够 / 平台差异）？
• 移动端代码块能横滚不溢出？

何时不要用 tutorial：

>

- 源材料是讲机制不是讲操作 → explainer。

- 想让读者玩懂而不是做出来 → interactive-explainer。

- 源材料是 API 文档 / 完整规格 → 用 longform + 强 TOC，tutorial 不适合做参考手册。

Article Type · visual-essay

展示、传播、图文主导、品牌叙事、年终回顾、文化评论。视觉是主角，文字短而精，节奏强。

• 推荐信息保留：20-60%（只留核心观点和最有力量的材料；大量删减叙事 / 推导 / 数据细节，

把保留下来的内容用视觉重新组织）。

• 典型结构：Hero（强气质 / 满版视觉 / 大字标题）→ 短 Section 串联，每节 = 少文字 +

大视觉 + 一句金句 → 节与节之间有强节奏对比（疏 / 密 / 明 / 暗）→ Conclusion（留白 收束 / 一句话点题）。章节短 —— 每节阅读时间 30 秒到 1 分钟。

• 组件选择：正文用短句、断行；Quote 做金句停顿（不引名言，而是把文章里的"狠话"抬

出来当节标记）；Image / Raw 是主角；少用密集数据组件（Table / RiskList 会破 坏视觉节奏）。

• Raw 边界：视觉块占比最高 —— 大尺度版面、节奏图、概念可视化、动效、轻交互（HTML

/ CSS / React，按需用 SVG / canvas）；可以做满版背景、滚动触发动效、多列错位 排版等。但仍必须是文章形态 —— 不是 landing page、不是产品 dashboard。

• 配图倾向：ai-generated / user-assets 大图；构图 / 留白 / 排版本身就是表达；

避免 stock photo 和"商务握手"类俗图。

• 主题倾向：bodoni（黑白大刊）、press（暖色编辑）、sottsass（活泼彩色）、bayer

（现代主义 / 海报感）、andy（柔软叙事）。气质强的主题在这个类型里效果最好。

• 自检：
• 是否仍是一篇文章而非海报 / landing page / dashboard？（删掉所有视觉后，剩下的文字

能否串成一个观点？能 = 文章；不能 = landing page）

• 视觉是否服务核心观点而非纯装饰 / 炫技？
• 节奏是否有呼吸（疏密对比 / 明暗对比 / 大小对比）？
• 删减后是否仍像"被编辑过的文章"而非"缩水的摘要"？
• 移动端是否仍能传达核心观点（很多大版面在 mobile 上会塌）？

何时不要用 visual-essay：

>

- 给读者做决策 → briefing。

- 让读者完整理解 → longform / explainer。

- 让读者操作着学懂 → interactive-explainer（也是视觉主导，但读者要动手）。

- 要传达完整论证 / 数据 → essay / full-report。

配图与素材策略

配图必须服务文章，不是装饰。Phase 2 把配图策略与逐图计划写进 plan/plan.md 的 Assets 段（见 plan-template.md），不再产出独立的 `asset-plan.md` 文件。

与 Raw 正交：配图策略只管 Image，不管 Raw（铁律）

配图策略 = 是否使用外部 `Image`，以及用哪种来源。它与 `Raw` 完全正交，不是二选一：

• `Raw` 始终存在，是每篇文章默认的表现力层（任意 HTML / CSS / JS / React：交互、

自定义布局排版、动效、小工具，以及按需的 SVG / canvas 图解），不受配图策略影响，也永远 不需要用户"开启"。

• `Image` 是独立的可选叠加层，由配图策略决定是否使用、用哪种来源。
• 选 none 不等于"用 Raw 替代 Image" —— 它只表示"不使用外部图片"，Raw 照常使用。

别把它框成 "Image vs Raw"。正确心智是："Raw 一定有；Image 要不要、用哪种来源，由用户在

Plan Checkpoint 明确选定。"

四种来源模式（只针对 Image）

不主动生成 AI 图片：ai-generated 必须用户显式选择。但即便选 none，也不影响 Raw。

Asset Checkpoint 必问（Plan Checkpoint 内 · 必须让用户选，不能默认通过）

配图模式是必选项，不允许用一个默认值一笔带过。先一句话说明"Raw 照常使用"，再让用户 从四种 Image 来源里明确选一种：

配图模式（这一项只决定是否使用外部 Image；Raw 自由层 —— 交互 / 布局 / 动效 / 图解 —— 不受影响，照常使用）。
请从以下四种里选一种：
- none：不使用外部图片，靠正文 + Raw + 表格表达（推荐给技术 / 证据型文章）。
- user-assets：你提供素材目录或截图，我据此排版。
- placeholders：先放占位图，我在 plan.md 的 Assets 段标注每张图应替换成什么。
- ai-generated：我先生成配图提示词，等你确认后再生成图片。
我的推荐：<策略>，原因：<一句话>。你确认或改成别的？

ai-generated 提示词原则

选 ai-generated 时不直接随意生成图片，先在 plan/plan.md 的 Assets 段列出每张图： 位置 · 服务的段落 / 论点 · 目的 · 主题风格 · 构图 · 禁止项 · 提示词 · 备选提示词。

示例：

Image 01
位置：Hero 背景
目的：建立"技术出版物"气质，不解释具体机制
主题：press
风格：warm editorial still life, paper texture, low saturation
禁止：3D icon, neon gradient, SaaS stock photo, smiling office people
Prompt: Warm editorial photograph of a desk with annotated technical notes,
printed code snippets, a graphite pencil, soft morning light, low saturation,
refined book-publishing mood, no screens, no logos.

图片自检（每张图）

• 是否服务文章中的具体位置？是否符合选定主题 theme-profiles/<id>.md 的媒体风格？
• 是否不是纯装饰？是否不会抢正文？是否没有和 Raw 表达重复？
• 是否有 caption / source / alt 文本？

配图自查并入 Plan 自查（5 条之一："Raw / 图片有目的"）—— 由主 Agent 内联完成， 不再单独开 Asset Reviewer SubAgent。详见 review-checklist.md 的 Plan 自查段。

修复政策（最小切片）

按最小单位修复。有修复才写 review/repair-log.md（一次过 / 无修复则不写）。

禁止

• 用户只反馈一处问题就重写整篇。
• 为了修视觉而改动已确认的文章结构。
• 为了压缩信息而删除用户指定必须保留的内容。

最小切片对照

repair-log.md 格式

## <日期> <谁反馈 / 哪个 Reviewer>
- 问题：<一句话>
- 定位层：<节奏 / 视觉 / 内容 / 构建>
- 最小修复单位：<Section 03 / raw-blocks/02 / main.tsx 主题 ...>
- 改动：<改了什么>
- 验证：<dev 预览 / npm run html 通过 / 控制台无错>

先定位是哪一层（内容 / 结构 / 视觉 / 构建），再改最小切片，不要重做整篇。