美麗文章（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 / 誤寫檔案是首要效能問題，按下表嚴格執行：

節點	品質檢驗方式	產物	為什麼
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`	交付物的一部分，留檔有價值

鐵律：

Plan Checkpoint（Phase 2 → Checkpoint 1）嚴禁開 SubAgent 做品質檢驗。主 Agent 寫完 plan.md 後就地對照 5 條清單（見 references/review-checklist.md 的 Plan 自查段）核查、按結論改完 plan/plan.md，不要寫任何 review 檔案，然後進入 Checkpoint 1。
First Spread / Final 必須用 SubAgent（這兩個節點 SubAgent 價值 > 開銷）；只有探測不到 SubAgent 環境才由主 Agent 兜底，並在檔案首註明「無 SubAgent 環境，主 Agent 兜底」。
Section Reviewer 用 SubAgent，但回傳值是訊息（pass / fail + 修復點）；fail 項主 Agent 收到後直接修，不要讓 SubAgent 寫 review/section-NN-review.md 檔案。
拿到任何品質檢驗結論 —— 先按 fail 項把產出改完，再回報「做完了 + 自檢結論 + 改了什麼」。直接拿原始結論回報但不修復 = 違規。
決策收集鐵律 · 禁止靜默替用戶選擇：在每個 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 開場訊息模板（在收集決策之前先發一條簡短說明）：

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（或編號列出兩個問題，停下等答覆）：

驗收結論 —— 選項：通過 · 進入完整產生 / 局部修改 · 我會另起一條說改哪裡 / 主題或版式不合適 · 回到 Checkpoint 1。
後續開發模式 —— 選項：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）：

Editorial Reviewer：文章性、資訊取捨、結構。
Visual Reviewer：主題、Raw、配圖、行動端。
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
```
腳本探測系統…

美丽文章（Beautiful Article）