Dnnecessary/skills

公眾號文章排版 Skill

把一篇 Markdown 文章轉換為可直接複製貼上進微信公眾號編輯器、且貼上後樣式不遺失的 HTML。

核心資產是 references/ 下的主題組件庫（每套一個主題：設計變數 + 各組件完整 HTML + 模板骨架 + 映射規則）外加 1 套通用增量庫（程式碼區塊 / 圖片·GIF / 小標籤標題，所有主題共用）。主題清單以 references/theme-index.md 為單一來源。本 SKILL.md 只負責流程與決策，具體 HTML 程式碼一律從組件庫取，不要憑記憶手寫。

工作流

0. 輸入與格式統一化

使用者可能給：Markdown 文字或 .md 路徑（直接進第 1 步）、.docx、.pdf、.txt/無標記純文字、網頁富文字。非 Markdown 輸入必須先讀 references/format-normalize.md 按其規則轉成 Markdown 草稿並做結構確認（docx 用 scripts/extract_docx.py，PDF 用 Read 分頁讀取+清噪，純文字按標題啟發式推斷結構）。什麼都沒給時，向使用者索要。

使用者說「直接排 / 自動排 / 一鍵 / 不用問」時進全自動模式：跳過結構確認與選主題提問，自動推斷結構、按題材自選主題、排版驗證，交付時附決策說明（章節結構、自擬標題、選題理由）。

1. 選主題（自動推薦制）

讀 references/theme-index.md（主題資訊的單一來源）。據文章題材主動推薦最契合的主題，再讓使用者一步確認——推薦但不擅自定死：

• 使用者已在請求裡指定主題 → 直接用，不問。
• 題材有明確契合 → 單問確認：「建議用 XX（理由），確認還是換一套？」選項給推薦項 + 1~2 個備選 + "看全部"。題材→主題契合參考 theme-index"適用場景"列：
  • 教學 / 評測 / 清單 / 工具盤點 / 知識整理 / 方法論拆解（資訊密度高）→ 摸魚綠
  • 深度分析 / 觀點 / 力量感話題 → 紅白色系
  • 設計 / 科技評論 / 專業觀點 / 高端品牌 → 石墨極簡風
  • 禪意 / 極簡生活 / 深度隨筆 → 留白禪意風
  • 工具對比 / 創意評測（票據視覺隱喻）→ 摸魚票據風
  • 內刊手記 / 深度評測 / 案例回顧 → 橄欖手記
• 無明顯傾向 → 預設首選 theme-index 第一行（摸魚綠）作為推薦項放第一位，用 AskUserQuestion 讓使用者在幾套裡選（主題多於 4 套時先按氣質分組問，再問該組下主題）。
• 全自動模式（使用者明說「直接排 / 一鍵 / 不用問」）→ 不提問，自動選題材最契合主題或預設第一行，交付時說明選擇理由。
• 使用者對現有主題都不滿意 / 想要新風格 → 走「自訂主題生成」流程（見下節），生成並登記後再回到本步選用。
• theme-index 為空 → 停止排版，告知使用者需要先添加主題風格（可走「自訂主題生成」）。

使用者定下主題後，才進入該主題內部的組件匹配（第 3、4 步：判定文章類型 → 按該主題的配方表選組件組合）。

2. 讀組件庫（兩份）

(1) 據 theme-index 中該主題的"組件庫檔案"列，Read 該主題專屬組件庫 references/theme-{標識}.md（含引言卡、章節標題、正文標記、簽名等主題專屬組件）。 (2) 同時 Read 通用增量庫 references/common-components.md——程式碼區塊、圖片/GIF、小標籤標題這三類所有主題共用，套用目前主題主色即可。

後續生成完全依據這兩份組件庫，HTML 一律從中取、不要手寫。

3. 解析 Markdown 結構

元素	識別規則
文章標題	# 標題 或 frontmatter title
開頭引言	文章最開頭的 > 引用 區塊
章節標題	## 標題
子章節	### 標題
加粗 / 高亮 / 底線	**文字** / ==文字== / <u>文字</u> 或 ++文字++
引用段落	非開頭的 > 文字
圖片 / GIF	、（GIF 與圖片同樣處理）
程式碼 / 命令 / Prompt	``` 圍欄程式碼區塊 ```、行內 `code`
分隔線 / 列表	---、*** / - 項 或 1. 項
表格	| 分隔的 Markdown 表格（常來自 docx 轉換）→ 優先用主題庫的表格/卡片組件（主題庫映射規則為準）

解析完結構後，判定文章類型（取主導類型，可複合）：教學/操作指南、盤點/工具清單、觀點/深度分析、訪談/人物特稿、數據回顧/報告、生活/情感隨筆、案例實戰。判定依據：步驟和命令多→教學；並列條目多→盤點；引語和人物敘事多→訪談；數字和對比多→數據；論證推演多→觀點。

4. 按配方選組件組合 → 組裝 HTML

先查所選主題庫的「文章類型 → 組件組合配方」表，按文章類型確定本篇的核心組件組合與點綴組件——不要拿到組件庫就逐段隨機選組件，配方保證同類文章的排版氣質穩定。配方之外的元素再按主題庫映射規則表補充。

然後依主題庫的**"完整文章模板骨架"章節**組裝，把每個 Markdown 元素替換為對應組件：

• 骨架順序以主題庫為準，不同主題骨架可能不同，不要套用其它主題的骨架。
• 行內標記按語義到所選組件庫裡找對應組件（組件編號各庫不統一，一律以語義為準、不要套固定編號）：**加粗**→主色加粗；==高亮==→純色淺底高亮；<u>文字</u> 或 ++文字++→底線；~~文字~~→螢光筆（純色淺底）；>引用→引用高亮區塊。
• 來自通用增量庫的組件：``` 程式碼區塊 ```→ 1a 深色 / 1b 淺色程式碼區塊，行內 `code`→ 1c；![說明](url)→ 2a 圖片（有說明才加說明組件）、.gif→ 2b GIF；需要突出的小標題/強調→ 3a 左豎條小標題或 3b 藥丸標籤，金句→ 3d、提示旁註→ 3e。優先級：先查主題庫映射規則表——該主題有等價語義組件（如自己的金句/提示區塊）就用主題庫版本保持氣質一致；主題庫沒有對應組件時才用通用庫 3x 並按其換色規則換成主題色。
• 一篇文章只用所選主題的那一套組件，不跨主題混用。
• 強調與小標題用"小標籤/左豎條"，不要用虛線框：要突出一個小標題或一段內容時，用左豎條小標題（3a）、藥丸標籤（3b）、左豎條金句/提示區塊（3d/3e）；不要用四周虛線框（dashed border）套一個標題，那樣笨重搶戲。

5. 驗證合規（強制）

把生成的 HTML 寫入目標檔案後，必須執行驗證腳本，ERROR 歸零才算完成：

# 用腳本所在 skill 的絕對路徑呼叫，HTML 參數也用其實際路徑（兩者目錄通常不同）
<SKILL_ROOT>/scripts/validate_gzh_html.py <生成的.html 的實際路徑>

它確定性地檢查平台禁用項和 <span leaf> 包裹。報 ERROR 就回到第 4 步修；半形標點 WARNING 同樣要修復到 0 再交付（這是實際使用中最高頻的返工點）。

漸變背景 WARNING 要逐項處理：文字高亮、引用/數據/引導卡背景預設改為主題內純色或 rgba 純色；使用者明確要求保留時，交付註明可能觸發 darkmode-no-gradient 彈窗。純裝飾漸變也會提示，尚未確認其不會觸發彈窗，保留時同樣說明風險。

6. 輸出

產物格式：純 <section>…</section> 正文片段，從全域容器開始，不要包 <!DOCTYPE>/<html>/<head>/<body>——公眾號編輯器只接受正文片段，多餘的文件外殼會被丟棄或干擾貼上。

1. 乾淨正文檔案：HTML 儲存到目前工作目錄，檔案名 {原檔案名}_排版_{主題中文名}({英文標識}).html（英文標識 = theme-index 組件庫檔案名去掉 theme- 前綴與 .md 後綴）。這份用於驗證和手動貼上兜底。
2. 帶「複製」按鈕的預覽頁（讓使用者一鍵複製，免去手動全選）：

   <SKILL_ROOT>/scripts/wrap_preview.py <上面的乾淨正文.html>
   

   產出 {...}_預覽.html——瀏覽器打開後右上角有「複製到公眾號」按鈕，點一下即把渲染後的富文字複製到剪貼簿（等價 Ctrl+A/Ctrl+C），再到公眾號編輯器 Ctrl/⌘+V 貼上。按鈕和腳本只在預覽外殼裡、不在被複製的 section 內，所以粘到公眾號的仍是乾淨合規正文。
3. 告知使用者：打開 {...}_預覽.html → 點右上角「複製」→ 公眾號編輯器貼上；並給出乾淨正文檔案路徑作為兜底。附驗證腳本結論（已通過 / 剩餘 warning）。

生成時的智慧處理（這些是本 skill 的特色，必須做）

1. 章節自動編號：按 ## 出現順序分配 01/02/03…；末章若為結語/總結類，用主題庫指定的結語編號變體（如 ∞），主題庫未指定時沿用數字編號。
2. 英文標籤：據中文章節標題生成英文標籤（實測→TEST、教學→TUTORIAL、總結→SUMMARY、思考→THOUGHTS…），主題庫有對應槽位時使用。
3. 正文關鍵詞底線（核心特色）：對每個正文段落主動找出 1–3 個最重要的短語，用該主題的底線 CSS（見 theme-index）標記。優先標核心觀點、結論、關鍵數據、專有名詞；短語 4–15 字；整段無要點可不標。即使原文沒有任何加粗也要主動加底線——它是出現頻率最高的基礎標記。
4. 引言關鍵詞高亮：識別開頭金句裡的核心詞，用高亮組件標記。
5. 目錄提取：從所有 ## 取前 3 個作為導讀/目錄要點（主題庫有目錄組件時）。
6. 開頭引言卡署名：按文章的作者或主題而定——文章有署名就寫"—— 作者名"，沒有明確作者就用與主題相關的簡短落款或直接省略。不要固定寫"甲木"（尾部簽名區同樣用 {{作者名}} 佔位，見第 7 條）。
7. 尾部作者簽名區（作者自填，僅末尾一處）：預設不寫死任何人名，用佔位署名讓使用者替換成自己的。
   • 第一句（作者介紹）：我是 {{作者名}}，{{一句話簡介，如：熱衷於分享 AI 觀察與乾貨}}——使用者在請求/偏好裡給了署名或簡介就直接填入；沒給就保留 {{作者名}} / {{簡介}} 佔位，並在交付時提示使用者替換成自己的署名。
   • 第二句（互動引導，通用可保留原樣）：如果你覺得今天這篇有收穫，歡迎**按讚、在看、轉發**三連，我們下篇見
   • 原文末尾已有作者簽名段（如"我是 XXX…"）→ 直接沿用原文的署名，不替換成佔位。
8. 列表轉換：按主題庫映射規則處理；無專屬列表組件時轉為帶縮排的正文段落。
9. 中文全形標點：正文標點一律用全形（，。！？：；""''（）—— …），不要用半形 , . ! ? : 和英文直引號 " '。生成 HTML 時就直接寫彎引號""''，不要先寫直引號再事後替換——原文裡的直引號在轉寫時當場轉換。例外：程式碼區塊、行內程式碼、英文專名/URL/程式碼識別碼內部保持原樣。

視覺層級（3 層遞進，所有主題通用）

層級	作用	頻率	手段
錨點層	最強錨點：產品名/步驟/CTA/核心金句	全文 ≤ 5 處	主色加粗、深色底白字引用
標記層	正文關鍵詞，每段 1–3 處	高頻	底線標記
容器層	引用區塊、概念標籤、長句強調	按需	淺底引用、螢光筆、徽章

平台紅線（核心，完整檢查交給驗證腳本）

• 禁止：<style>/<script>/<div>、class/id 屬性、position:fixed/absolute/sticky、float、@media/@keyframes、display:grid、CSS 變數、外部字型/CSS。
• 必須：樣式全部內聯 style；所有文字節點用 <span leaf="">文字</span> 包裹（否則貼上後樣式遺失）。
• 可用：display:flex（有限）、border-radius、box-shadow、<section>/<p>/<span>/<strong>/<img>/<h3>。
• 漸變背景相容性：漸變可渲染，但可能觸發公眾號 darkmode-no-gradient 內容結構檢測；文字和卡片背景預設用純色，不額外添加漸變。舊組件/自訂主題遇到此項也按第 5 步處理。

Gotchas（真實排版踩過的坑）

• 漏 <span leaf> 包裹是最常見致命錯——貼上到公眾號後樣式整片遺失。靠第 5 步驗證腳本兜底，別跳過。
• 底線：逐段落實、每段 1–3 個短語。不要整段劃線（失去焦點），也不要有的段標有的段漏；列表項裡的關鍵描述同樣要標。
• 章節編號錯亂：嚴格按 ## 順序，不要跳號；結語編號變體只用於末章，中間章節不能用。
• 簽名區有且僅有末尾一個：用固定文案，不在中間或多處出現；原文末尾若已有作者簽名/"按讚在看轉發三連"類段落，識別並併入這唯一的簽名區/CTA 卡片，不要保留原文段又再生成一個。
• 圖片說明硬造：只有 ![說明](url) 裡真有說明文字才生成說明組件；![](url) 空 alt 不要編造說明。
• 圖片自適應、不鋪滿：<img> 一律 max-width:100%;height:auto;display:block;margin:0 auto——按圖片自身尺寸顯示、居中，大圖縮到容器寬、小圖保持原尺寸。不用 width:100%（會把小圖也拉伸變糊）；只有表格 / 封面卡 / 流程圖這類佈局元素才用 width:100%。
• 跨主題混用組件：一篇文章只用所選主題 + 通用庫的組件，不從其它主題借組件。
• 錨點層濫用：最強強調全文 ≤ 5 處，到處加粗等於沒有重點。
• 原文內容遺漏：每個段落、每張圖都要轉換，不得漏；不要自行增刪原文實質內容。
• 佔位圖殘留：簽名區/CTA 組件裡若帶名片圖佔位（如 <img src="...名片或引導圖URL">），沒有真實圖片 URL 時整行刪掉，不要把佔位符留在產物裡。
• 目錄是精選不是全量：前言導讀/目錄組件展示精選的 3 個核心看點，不是完整章節列表；章節多於 3 個時挑最重要的 3 個，不要硬塞或誤導讀者以為只有 3 章。
• 不用虛線框：突出標題/強調用小標籤或左豎條（通用庫 3a–3e），不要用 border:…dashed 四周虛線框包標題。例外：主題庫明確定義的虛線組件（如摸魚綠的 quote-box 引用框、oneliner-card 亮點卡）是該主題的風格特徵，按主題庫用法正常使用。
• 標點別混半形：正文出現半形逗號句號、英文直引號 " ' 都要改成全形；但程式碼區塊/行內程式碼內的半形符號保持原樣，不要"全形化"程式碼。
• 程式碼/Prompt 必須用程式碼區塊：文章裡的程式碼、命令、提示詞用通用庫程式碼區塊組件（1a/1b），不要塞進普通段落或引用區塊，否則縮排和等寬會遺失。
• 程式碼區塊要緊湊、忌大空白：用通用庫 1a/1b 的"每行一個 <p style="margin:0">"寫法，絕不用 white-space:pre——它會把 HTML 原始碼裡 span 前的縮排和行間換行原樣渲染成大左縮排 + 空行；縮排只用全形空格 　，行距靠 line-height:1.6。
• 待補素材居中：【插入…】、待錄影 / GIF / 影片 / 成果圖等佔位，用通用庫 2c 居中素材佔位板塊（淺底柔虛線框 + 居中圖示與說明），不要用左對齊的提示區塊。

自訂主題生成（第二條工作流）

使用者想要內置主題之外的新風格（說「生成一套新主題 / 自訂風格 / 按這張參考圖做一套組件庫」，或對現有主題都不滿意）時，讀 references/theme-generator.md 並嚴格按其流程執行：

1. 收集偏好：主題描述必填（或參考圖），名稱/ID/五色/字型/三類 TAG/圓角/陰影可空則自動補全；一次問全，不逐欄位追問。
2. 生成區塊庫 HTML：用 theme-generator.md 末尾的【生成提示詞】原樣執行，產出 45~75 個 Block 的完整區塊庫，儲存到 assets/theme-previews/{theme-id}.html——全部區塊在同一頁面連續排布，使用者瀏覽器打開整頁一次瀏覽確認風格，不逐區塊展示確認。
3. 轉換 + 登記：使用者確認風格後，轉換為標準 references/theme-{標識}.md（必須補 <span leaf=""> 包裹、去掉預覽用 id、補齊五章節，規則詳見 theme-generator.md 第三步），登記 theme-index.md，跑 component_lint.py 到 0 ERROR。
4. 交付後該主題即成為常駐可選主題，後續排版與內置主題完全同權。

生成階段以提示詞規則為準；轉換進主題庫階段以本檔案「平台紅線」和「添加新主題的規範」為準（兩者衝突時後者優先，因為主題庫直接決定排版產物）。

添加新主題的規範

新主題以 references/theme-{英文標識}.md 命名，內容必須包含：

1. 設計變數速查表（主色/淺底/深字/標題色/正文色/分隔線色等）
2. 各組件完整 HTML（內聯樣式 + <span leaf=""> 包裹，遵守上面"平台紅線"）
3. 完整文章模板骨架（組件裝配順序；若有目錄/導航組件，明確其相對封面/引言的位置）
4. 文章類型 → 組件組合配方表（每種文章類型的核心組件組合 + 點綴組件，配方是排版氣質穩定的關鍵）
5. Markdown → 組件映射規則表

添加後在 references/theme-index.md 登記一行（主題名 / 主色 / 適用場景 / 組件庫檔案 / 正文底線 CSS），並跑 python3 scripts/component_lint.py . 確認組件庫無反模式（0 ERROR）。

觸發與主題選擇的回歸用例見 references/eval-cases.md（維護時用於回歸核對，不影響單次生成）。