beautiful-article
把用户提供的素材（网页 URL / PDF / DOCX / Markdown / 纯文本 / 截图 / 粘贴材料）编辑、设计成一篇美丽的、可离线打开和分享的**单文件 HTML 网页文章**。基于 reacticle 组件协议：不手写裸 HTML/CSS，而用语义组件 + 受主题约束的 Raw 自由层；按 source→规划→双确认→生成→终审→修复的小型 harness 流程推进，默认 100% 信息保留的长文。触发场景：把 URL/PDF/DOCX/文章做成网页文章 / 长文 / briefing / 解释文 / 视觉文章 / 教程 / 审阅复盘 / 方案分析，'render this
By conardli · 2,660 installs
npx skills add conardli/garden-skills --skill beautiful-article
Source repository · Upstream listing
Beautiful Article
背景原则
AI 生成内容越复杂，输出媒介越重要。HTML 的价值在于同时提升信息密度、视觉清晰度、分享便利性和交互能力：表格、SVG、CSS、代码片段、可调控件、复制与导出按钮，可以让读者不只是“看完”，而是能比较、定位、调整、复查和继续使用。Beautiful Article 的目的，是把原本枯燥、线性、难以消化的文字材料，转换成视觉体验更漂亮、阅读节奏更清晰、也更容易审阅和分享的单文件网页文章。
边界（先判断要不要进这个 Skill）
最终主产物是 single HTML 文章 ，不是网页应用。
文章可以有 Raw 自由层（任意 HTML / CSS / JS / React：交互、布局排版、动效、小工具、
按需的 SVG / canvas 图解），但 必须服务阅读、解释、论证、节奏或审美 。
不 生成：后台、表单、拖拽工作台、完整 dashboard、产品原型、通用 Web App。
信息密度由用户确认； 默认保留 100% 信息 ，生成长文式网页文章。
如果用户要的是应用而不是文章，停下来澄清，不要进入本 Skill。
工作流总览
工作区结构（脚手架创建；这些文件是 Skill 的长期记忆， 不要只依赖聊天上下文记决策 ）：
硬性质检协议（贯穿整个 Skill）
质检方式按节点区分 —— 不是所有质检都要开 SubAgent，也不是所有质检都要写文件。
误开 SubAgent / 误写文件是首要性能问题，按下表严格执行：
节点 质检方式 产物 为什么
Phase 1 Source（默认） 主 Agent 内联 5 条 checklist 无文件 主 Agent 反正要通读 source.md
Phase 1 Source（仅复杂/低置信源） Source Reviewer SubAgent（对照 original. diff） review/source review.md 静默丢失只能 diff 抓到
Phase 2 Plan / Checkpoint 1 前 主 Agent 内联自查（禁止开 SubAgent） 无文件 plan 是文字决策且 200 400 行，上下文是热的，SubAgent 冷启反而更慢
Phase 4 First Spread / Checkpoint 2 前 First Spread Reviewer SubAgent review/first spread review.md 首屏定调，多一道独立眼睛更稳
Phase 5 每个 Section Section Reviewer SubAgent 以消息返回 pass/fail + 修复点（不写文件） 一篇可能 5 15 节，N 份 review 文件无人再读
Phase 6 终审 / Checkpoint 3 前 Editorial + Visual + Technical Reviewer SubAgent review/final review.md 交付物的一部分，留档有价值
铁律：
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 。
各阶段文件读取指南（渐进加载，别一次全读）
阶段 必读 按需查
Phase 0 Intake references/harness.md ——
Phase 1 Source→MD references/source to markdown.md scripts/source to markdown markitdown.py · scripts/source to markdown.py
Phase 2 Planning references/article types.md · references/information density.md · references/plan template.md · references/theme selection.md · references/layout.md · references/asset policy.md · references/cover.md （封面构图想法） references/article types/<type .md · theme profiles/ .md
Phase 4 First Spread / Phase 5 Build（每节回看） references/section build.md · references/component policy.md · references/raw policy.md · 选定主题 theme profiles/<id .md · 封面： references/cover.md references/scaffold.md （建项目时一次）· references/html output.md
Phase 6/7 Review & Repair references/review checklist.md · references/repair policy.md ——
Phase 8 Delivery references/html output.md references/pdf output.md （仅当用户选 PDF 导出）
长会话里 agent 容易遗忘原则 —— Phase 5 会重复实现 N 个 Section， 每次开工
前回看 component policy.md + raw policy.md + 当前主题 theme profiles/<id .md 。
Phase 0 —— Intake
判断是否进入本 Skill，给出初步文章类型与输出模式（默认 single HTML）。
用户给的东西 该做的
一个或多个素材（URL/PDF/DOCX/MD/文本/截图） 进入 Phase 1
只说"帮我做篇 X 文章"但没素材 反问 ：先要素材或大纲。Skill 不替用户凭空构思内容
明显要的是应用 / 工具 / dashboard 停下来澄清，不进入本 Skill
捕获目标语言 ：开场就记录用户 期望的最终文章语言 （如用户提到"用中文/做成英文版"等）。
用户指定了语言 → 记进 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 项 （缺一不可）：
决策项 选项（语义化标签 · 含标配信息保留比例） 备注
1 文章类型 （信息保留比例打包在内） 完整长文 / 归档 longform · ~100% ／ 研究报告 / 正式分析 full report · ~80% ／ 教学步骤 / 上手指南 tutorial · ~90% ／ 概念 / 系统解释 explainer · ~80% ／ 对话 / 访谈 / 播客 dialogue · ~80% ／ PR / 方案 / 事故审阅 review · ~70% ／ 观点 / 评论 / 叙事 essay · ~70% ／ 交互式学习 / 玩明白一个概念 interactive explainer · ~25% 原文摘录 + 75% AI 重构 ／ 决策摘要 / 给忙人看 briefing · ~50% ／ 图文为主 / 传播展示 visual essay · ~40% AI 推荐一个并写一句理由。 比例已绑进类型选项 ，不再单独成题（否则会出现 longform + 20% 这种伪组合）。用户想偏离标配，用自由文本一句话覆盖（"我要 longform + 60%"），见下方"如何偏离标配"
2 主题 tufte / press / 其它已注册主题（读 theme profiles/index.json ） AI 推荐一个并写一句理由
3 版式宽度 narrow / regular / wide / full AI 推荐一个；默认 regular
4 配图模式 （必选 · 不允许"默认通过"） none / user assets / placeholders / ai generated 一句话"只决定是否使用外部 Image ； Raw 不受影响"
5 封面 （3:4 书封式题图，位于 TOC + 正文之上） 开（默认） / 关 AI 推荐"开"，并给一句构图想法（哪种主视觉 + 选哪个封面模板 A/B/C/D/E）。 briefing / dialogue 可推荐"关"。详见 references/cover.md
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"
时才生成。命令：
脚本探测系统已装的 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、无文件）