beautiful-article

Beautiful Article

背景原則

AI 生成コンテンツが複雑になるほど、出力媒体が重要になります。HTML の価値は、情報密度、視覚的な明瞭さ、共有のしやすさ、インタラクティブ性を同時に高められることにあります。表、SVG、CSS、コードスニペット、調整可能なコントロール、コピーやエクスポートのボタンがあれば、読者はただ「読み終える」だけでなく、比較、位置の特定、調整、再確認、継続利用ができます。Beautiful Article の目的は、もともと退屈で、直線的で、消化しにくいテキスト資料を、視覚的に美しく、読み進めるリズムが明快で、レビューや共有もしやすい単一ファイルのウェブ記事に変換することです。

境界（まず、この Skill を使うべきか判断する）

• 最終的な主成果物は single HTML の記事であり、ウェブアプリではありません。
• 記事には Raw の自由レイヤー（任意の HTML / CSS / JS / React：インタラクション、レイアウト、アニメーション、小ツール、必要に応じた SVG / canvas の図解）を含められますが、読解、説明、論証、リズム、または美しさに役立つものに限ります。
• 生成しないもの：バックエンド、フォーム、ドラッグ＆ドロップの作業台、完全なダッシュボード、製品プロトタイプ、汎用 Web アプリ。
• 情報密度はユーザーに確認します。デフォルトでは情報を 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 の誤起動やファイルへの誤書き込みは、最も重大なパフォーマンス上の問題です。以下の表に厳密に従ってください。

工程	品質チェック方法	成果物	理由
Phase 1 Source（デフォルト）	メイン Agent がインラインで 5 項目のチェックリストを実施	ファイルなし	メイン Agent はいずれにせよ source.md を通読するため
Phase 1 Source（複雑なソース／信頼性が低いソースのみ）	Source Reviewer SubAgent（original.* との差分を確認）	review/source-review.md	気づかれない欠落は差分でしか検出できないため
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 と修正点を返す（ファイルには書き込まない）	1 本の記事に 5-15 個のセクションがある場合、N 個のレビュー用ファイルを作っても誰も再読しないため
Phase 6 最終レビュー / Checkpoint 3 の前	Editorial + Visual + Technical Reviewer SubAgent	review/final-review.md	成果物の一部として記録に残す価値があるため

厳守事項：

1. Plan Checkpoint（Phase 2 → Checkpoint 1）では、品質チェックに SubAgent を起動することを厳禁とします。メイン Agent は plan.md を書き終えたら、その場で references/review-checklist.md の Plan 自己確認セクションにある 5 項目のチェックリストと照合し、結論に基づいて plan/plan.md を修正します。レビュー用ファイルは一切書かず、その後 Checkpoint 1 に進みます。
2. First Spread と Final では必ず SubAgent を使用します（この 2 つの工程では SubAgent の価値がコストを上回ります）。SubAgent を利用できる環境が見つからない場合に限り、メイン Agent が代行し、ファイルの先頭に「SubAgent 環境がないため、メイン Agent が代行」と明記します。
3. Section Reviewer には SubAgent を使いますが、戻り値はメッセージ（pass / fail と修正点）です。メイン Agent は fail 項目を受け取ったら直接修正し、SubAgent に review/section-NN-review.md ファイルを書かせないでください。
4. 品質チェックの結果を受け取ったら、まず fail 項目に基づいて成果物を修正してから、「完了したこと＋自己確認の結果＋変更した内容」を報告します。元の結果をそのまま報告して修正しないのは違反です。
5. 判断事項の収集に関する厳守事項・ユーザーに黙って選択しない：各 Checkpoint（1 / 2 / 3）では、ユーザーの確認が必要な判断事項を一つずつ個別に列挙し、回答を待つ必要があります。Agent は推奨（「X をおすすめします。理由は……」）できますが、「X に決めておきました。違っていたら教えてください」などと言ってはいけません。これは選択の機会を奪うことになります。
   • 優先：環境に AskQuestion ツールがある場合、各判断事項を個別の question として扱います（1 回の呼び出しで複数の question を渡せます）。ユーザーは選択カードを使って、項目ごとに確認できます。
   • そうでない場合：いったん止まり、メッセージ内にすべての質問を番号付きで列挙します（質問ごとに段落を分け、推奨案＋理由＋代替案を明記します）。「項目ごとの回答をお待ちしてから続行します」と明確に伝え、その後の作業は一切続けないでください。
   • 絶対にしないこと：複数の判断事項を「おすすめをすべて選択／すべて OK ですか？」という yes/no の質問にまとめないでください。また、「おすすめはこれです」という一言の後、確認を待たずに次の工程へ進むことも禁止です。

各工程のチェックリストと SubAgent 用プロンプトのテンプレートについては、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（プロジェクト作成時に 1 回）· 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 —— プランのチェックポイント（★必須チェックポイント · Checkpoint 1、必ず停止）

鉄則：ユーザーに確認せずに選択してはいけません。各決定項目を個別に提示し、それぞれユーザーの回答を待ってください。

推奨することはできます（「Xをおすすめします。理由は…です」）。ただし、「Xに決めておきました。違っていたら教えてください」と言ってはいけません。後者はデフォルト値をこっそり押しつけ、選択の機会を奪うことになります。

確認方法（環境に応じてどちらかを選択）：

• 優先：AskQuestion ツール：各項目を独立した question として渡します（1回の呼び出しで複数の question を渡せます）。ユーザーは選択カードで各項目を確認します。
• AskQuestion ツールがない場合：メッセージ内で各質問を番号付きで列挙し、それぞれ独立した段落に分け、推奨項目・理由・代替案を明記して停止します。「各項目への回答を待ってから続行します」と明言し、その後の作業は一切続けないでください。

どちらの場合も、独立した決定ごとに独立した質問を1つ設けてください。「すべてOKですか？」のような yes/no の質問にまとめてはいけません。

必ず個別に確認する5項目（1つも欠かさないこと）：

#	決定項目	選択肢（意味の分かるラベル · 標準の情報保持率を含む）	備考
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 が1つ推奨し、理由を一言添えます。保持率は種類の選択肢に含まれているため、別の質問にしません（そうしないと longform + 20% のような不適切な組み合わせが生じます）。ユーザーが標準から外れたい場合は、自由記述で一言上書きします（「longform + 60% にしたい」）。下記の「標準から外れる方法」を参照してください
2	テーマ	tufte / press / その他の登録済みテーマ（theme-profiles/index.json を読む）	AI が1つ推奨し、理由を一言添えます
3	レイアウト幅	narrow / regular / wide / full	AI が1つ推奨します。デフォルトは regular です
4	画像モード（必須 · 「デフォルトで承認」は不可）	none / user-assets / placeholders / ai-generated	「外部の Image を使うかどうかだけを決定します。Raw には影響しません」と一言説明します
5	表紙（目次 + 本文より上に配置する3:4の書籍風カバー画像）	オン（デフォルト） / オフ	AI は「オン」を推奨し、構図のアイデア（どのようなメインビジュアルにするか + どの表紙テンプレート A/B/C/D/E を選ぶか）を一言添えます。briefing / dialogue では「オフ」を推奨してもかまいません。詳しくは references/cover.md を参照してください

TOC はデフォルトでオン：切り替えが1つだけで、ほとんどの記事でオンにするべきだからです。Plan Checkpoint の冒頭の説明で「TOC はデフォルトでオンです。オフにしたい場合はお知らせください」と一言伝えればよく、独立した質問にする必要はありません。

デフォルト値で進めるため、個別に質問する必要はない項目（ただし冒頭の説明で「変更したい場合はお知らせください」と明記し、ユーザーが後から変更できるようにしてください。完全に隠してはいけません）：

• 最終的な記事の言語：原文の言語に従います（ユーザーがそれ以前に指定している場合、またはすでに翻訳が完了している場合を除きます）。
• 編集による削除・短縮、再構成、語調の変更を許可するかどうか：デフォルトでは許可します（上記の情報保持率に従います）。
• 最初の画面のサンプルを先に確認するかどうか：デフォルトでは先に作成します（これが Phase 4 です）。
• TOC：デフォルトでオンです。

テーマについてユーザーが「任せます」と言った場合は、AI が推奨する最初のテーマを選びます。ただし、選択肢には他の候補と並べて記載し、「デフォルト · 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 に進んでください。自由記述で「標準外の保持率」が指定された場合は、Phase 4 に進む前に AI が plan/plan.md に記録したことを確認してください。

---

Phase 4 —— First Spread（記事版「第1章の確認」）

まず「表紙（オンの場合） + 最初の画面 + 第1節 + 代表的なビジュアルブロック」を作成します。この段階でスキャフォールドが作業領域を作成します：

# 默认开封面
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 コンポーネント（--no-cover が指定されていない場合は、デフォルトの article/Cover.tsx も）が作成されます。詳しくは 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（★必須チェックポイント、必ず停止）

最初の画面と第1 Section をユーザーに確認してもらい、後続の開発モードを選んでもらいます。Checkpoint 1 の決定事項確認の鉄則が同様に適用されます。2項目を個別に確認し、まとめてはいけません。AskQuestion を優先し、ツールがない場合は番号付きで列挙して回答を待ちます。

まず、簡潔なメッセージを送信します：

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

次に、AskQuestion で独立した2つの question を渡します（または2つの質問を番号付きで列挙し、回答を待って停止します）：

1. 確認結果 —— 選択肢：承認 · 全体の生成に進む / 一部修正 · 修正箇所は別途伝えます / テーマまたはレイアウトが適切でない · Checkpoint 1 に戻る。
2. 後続の開発モード —— 選択肢：A · 単一 Agent による順次作業（デフォルト · 最も安定 · スタイルの統一性が最も高い） / B · 複数 Agent による並行作業（最速 · スタイルにわずかな差異あり）。

この2つを「承認 + A でよいですか？」のようにまとめてはいけません。ユーザーは「確認を承認するが、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% 信息时像被精修过的长文， 而非原文搬运。

---

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

文件	何时读	内容
references/harness.md	Phase 0	Skill 的 harness 视角、六问、状态文件约定
references/source-to-markdown.md	Phase 1	各类输入 → source.md 规则、抽取自检、脚本用法
references/article-types.md	Phase 2	文章类型路由总览（含逐类型链接）
references/article-types/<type>.md	Phase 2 选定类型后	单类型结构 / 组件 / Raw 边界 / 配图倾向 / 自检
references/information-density.md	Phase 2	信息密度等级、与组件 / 视觉比例的关系
references/plan-template.md	Phase 2	单一 plan/plan.md 模板（Brief / Outline / Theme / Assets 四段）与写法
references/theme-selection.md	Phase 2	主题选择、density 与 theme 解耦、新增主题约束
references/layout.md	Phase 2 / Checkpoint	版式：宽度模式（与主题解耦）+ TOC，确认与用法
references/asset-policy.md	Phase 2	配图四种来源、AI 配图提示词原则、图片自检
references/cover.md	Phase 2 / Phase 4 写封面时	书封式封面设计指南（屏幕 3:4 / PDF 独占首页）：硬约束、视觉技术全开放、构图模板、各主题封面起手、5 条自检
references/section-build.md	Phase 4/5	一节一文件铁律、单/多 Agent 模式、并行 subagent prompt、主 Agent 合并
references/component-policy.md	Phase 4/5 每节	reacticle 组件协议、prose-first、信息密度与组件比例
references/raw-policy.md	Phase 4/5 每节	Raw 允许 / 禁止、token 驱动、Raw 自检
references/html-output.md	构建 / 交付时	dev / build / 单文件 HTML 命令与产物
references/pdf-output.md	Phase 8 Delivery 当用户选 PDF 导出时	html-to-pdf.sh 用法、TOC 排版原理、Raw 在 PDF 的表现、故障排除
references/review-checklist.md	Phase 6	各阶段 Reviewer 清单与 prompt 模板
references/repair-policy.md	Phase 7	最小切片修复对照表
references/scaffold.md	Phase 4 建项目时	脚手架做什么、用法、工作区结构、切主题
theme-profiles/index.json + *.md	Phase 2 选主题 / Phase 5 写作	主题 authoring profile（给 AI 读，非 CSS）
scripts/scaffold.sh	Phase 4 跑一次	一键创建文章工作区
scripts/html-to-pdf.sh	Phase 8 Delivery 仅当用户选 PDF	HTML → PDF（headless 浏览器 + 注入 print CSS，零 npm 依赖）
scripts/pdf-print-overrides.css	改 PDF 样式时	html-to-pdf.sh 注入到 <head> 的 @media print 覆盖：A) TOC 塌成上下排布；B) 分页行为（撤销 .ra-section 原子化、标题不孤儿、寡行控制等）；C) 封面独占首页
scripts/source-to-markdown-markitdown.py	Phase 1	MarkItDown 主路径，适合复杂 PDF / DOCX / HTML
scripts/source-to-markdown.py	Phase 1	轻量 fallback，适合 Markdown / TXT / 简单 HTML 或 MarkItDown 不可用时