微信公眾號內容工廠
把「寫完之後」那些折磨人的手工活自動化：排版、配圖、合規、交付。
寫作本身交給模型，本 skill 負責讓一篇稿子真正能發出去、發得好看、不踩雷。
能力範圍
| 層級 | 能力 | 說明 | 依賴 |
|---|---|---|---|
| L0 素材級 | ingest.py 素材攝入 | PDF/docx/pptx/網頁/長文 → 可引用的結構化素材 | pypdf、python-docx、python-pptx |
| L1 粘貼級 | md2wx.py Markdown → 內聯樣式 HTML | 4 套主題，輸出可直接粘貼進編輯器 | 純標準庫 |
| L2 成稿級 | cover.py 封面圖、lint.py 寫作閘門、check.py 合規體檢、preview.py 排版確認 | 900×383 / 1080×1080 / 200×200；寫作環節可校驗 | Pillow、Chrome |
| L3 直發級 | 草稿箱 API 直發 | 未實現，接口契約見 references/api.md | AppID + AppSecret + 認證帳號 |
完整創作默認按 L1 + L2 交付；局部任務按請求範圍交付，不強制生成整套產物。L3 需要帳號已認證並拿到 AppSecret——未認證的訂閱號沒有開發者接口， 拿不到就只能停在 L2（手動粘貼），這一點先跟用戶確認，不要假設有。
快速開始
順序很重要：先出預覽、再體檢、最後生成工作台。工作台是快照，提前生成會在改稿後變成舊版本。
完整創作按本 skill 的三檔封面標準驗收。 明確要求發布就緒的排版也需檢查封面；
lint --out out --publish將缺失或尺寸不符判為必須修。普通「僅排版」「僅體檢」「純預覽」 不強制補齊封面。三檔尺寸是本項目交付規格，不代替微信後台當前要求或實際圖片檢查。
# 0. 有素材文件時，先攝入（PDF/docx/pptx/網頁）
python3 scripts/ingest.py 素材.pdf -o out/ingest
# 1. 完整創作按項目規格生成封面：900×383 頭條 + 1080×1080 方形 + 200×200 次條
python3 scripts/cover.py --md article.md --all -o out/cover
# 2. 先出預覽頁（這一步不生成工作台）；輸出目錄不存在會自動創建
python3 scripts/md2wx.py article.md -o out/article.html
# 3. 排版確認（瀏覽器不可用時如實說明）
python3 scripts/preview.py out/article.html -o out/preview.png --height 4000
# 4. 雙重體檢（先跑一輪；發現問題先改稿，改完重來）
python3 scripts/lint.py article.md --cards out/素材卡.md --outline out/大綱.md --strict
python3 scripts/check.py article.md --html out/article.body.html --strict
# 5. 全部通過後，最後生成工作台並打快照（構建指紋寫進產物與 build.json）
python3 scripts/md2wx.py article.md --sheet --snapshot -o out/article.html
# 6. 交付前終檢：產物必須等於當前源稿，且封面齊全（--publish）
python3 scripts/lint.py article.md --out out --publish --strict
python3 scripts/check.py article.md --html out/article.body.html --strict
所有命令在 skill 根目錄下執行。python3 需為 3.9+；cover.py 需要 Pillow。按步驟執行並檢查退出碼，不忽略失敗繼續後續步驟；批量執行先啟用 set -e。沒有素材卡或大綱時省略對應參數，並記錄未核驗範圍；明確傳入但解析失敗不能當成未提供而放行。完整快照要求本地圖片已放在輸出目錄內；僅排版不強制快照或封面。
寫文章前：先把 frontmatter 寫好
標題、摘要、作者、主題這些元信息只寫一次，放在 Markdown 文件開頭，三個腳本共用：
---
title: 我寫廢了 150 份週報才明白：領導要的不是「你做了什麼」
title_short: 週報別再寫成流水帳了
summary: 週報要經過三層轉述，每過一手都在丟信息。如果領導不能從裡面抄走一句話，你這週的產出就等於零。
author: 雲光迷途
tag: 職場進階
theme: growth
---
# 正文標題
正文從這裡開始……
| 字段 | 必填 | 說明 |
|---|---|---|
title | 是 | 長標題，≤64 字；後台填的就是它 |
title_short | 是 | 短標題，≤20 字；只用來檢查信息流顯示，後台不填 |
summary | 是 | 摘要，≤120 字 |
author | 否 | 後台作者字段 + 封面署名；不寫則默認「雲光迷途」 |
tag | 建議 | 封面左上角標籤，2~4 字 |
theme | 建議 | tech / growth / minimal / elegant |
cover_title | 否 | 想在封面上另寫一句時用；省略則用 title |
寫好後，後面的渲染、封面、體檢都不需要再傳參數。
署名規則：默認「雲光迷途」，用戶指定就按指定的走。
| 場景 | 怎麼做 |
|---|---|
| 用戶沒說署名 | 什麼都不用寫，自動用默認「雲光迷途」，工作台會標註「來自默認署名」 |
| 用戶指定了署名 | 寫進 frontmatter 的 author——工作台、封面、後台作者字段都讀它 |
| 只想臨時試封面文字 | 用 md2wx.py --author / cover.py --author 覆蓋，不落盤 |
優先級：--author 命令行 > frontmatter 的 author > 默認「雲光迷途」。
不要只給 cover.py --author 而不改 frontmatter——那會讓封面署名和工作台裡的作者字段不一致。
工作流
先選任務分支，再執行對應步驟。 只有「完整創作」需要順序走完整鏈路，局部任務不套用全部創作提問。
| 任務 | 典型請求 | 只需確認 | 執行路線 |
|---|---|---|---|
| 完整創作 | 寫一篇文章；把素材改成文章 | 垂類、讀者、素材、主題 | Step 0 → 0.5（有素材時）→ 1~7 |
| 僅排版 | 已定稿，只排版；轉成公眾號 HTML | 定稿源文件、主題或現有 frontmatter；擬發布時才補缺失元信息 | Step 4 → Step 6.2（檢查提示，不自行改稿）→ Step 7（局部交付） |
| 僅封面 | 只做公眾號封面 | 封面文字、主題/樣式、所需尺寸、可選標籤與署名 | Step 5 → 人工復核封面文字 → Step 7（局部交付） |
| 僅體檢 | 只查合規、排版或引用 | 待檢文件；有 HTML、素材卡、大綱時才使用對應參數 | Step 6 的相關檢查 → Step 7（只交付報告） |
判斷不了分支時（例如「幫我處理一下這篇」「看看這個能不能發」）：先按完整創作走 Step 0， 但只問一個最關鍵的問題，不要一口氣拋出四問。寧可多問一句，也不要猜錯分支硬走七步。
局部任務只補當前任務必要信息，已有信息直接沿用；不得重寫已定稿正文或已有標題，不重新確認讀者、選題、大綱，也不強制再給五個標題候選。用戶明確要求改稿時，才另行進入對應創作步驟。
- 僅排版不調用
cover.py，除非用戶同時要求封面。已有主題優先沿用；沒有偏好時用tech並說明，不因此阻塞。 - 僅封面不要求補摘要、正文、素材卡或大綱，也不為了運行整篇檢查而偽造文章；按
references/compliance.md只復核實際封面文字，並說明復核範圍。 - 僅體檢不修改被檢文件。只有 Markdown 時不傳
--html；只有 HTML 且無 Markdown 源稿時只做 HTML 兼容人工檢查並說明範圍，不湊假正文。缺素材卡時說明引用與數字無法完整核驗。 - Pillow 或瀏覽器缺失時不自行安裝、不冒充該步驟已完成；交付已完成部分並列明缺失項。局部完成不等於整篇可以發布。
Step 0 · 確認輸入（僅完整創作）
完整創作先確認四件事，已有答案直接沿用；必要信息缺失時再提問，不自行編造：
- 垂類：技術/產品，還是職場/成長（決定主題與文風）
- 讀者：他們是誰、卡在哪、讀完能做什麼
- 素材：有沒有真實案例、數據、代碼、截圖
- 主題偏好：默認按垂類選（見「主題選擇」）
同時判斷這次的起點是哪一種，後面走不同的路：
| 起點 | 典型說法 | 走哪條路 |
|---|---|---|
| 給素材 | 「把這個 PDF / 週報 / 網頁改成公眾號文章」 | Step 0.5 → Step 1 |
| 給話題 | 「寫一篇關於 X 的文章」 | 跳過 0.5，直接 Step 1 |
| 兩者都有 | 「按這份報告，寫一篇講 Y 的」 | Step 0.5 → Step 1 |
Step 0.5 · 攝入素材（用戶給了文件或鏈接才走這一步）
讀 references/ingest.md，按它執行。不要跳過這一步直接開始寫——直接讀原文會跳讀、漏結論、把數字記錯。
python3 scripts/ingest.py 素材.pdf 會議紀要.docx -o out/ingest
產出三層文件（清洗正文 / 結構骨架 / 候選可引用句），然後按 ingest.md §2 抽素材卡：
| 前綴 | 類型 |
|---|---|
F | 事實（客觀陳述） |
D | 數據（數字 + 單位 + 口徑） |
O | 觀點（原作者主張，不是事實） |
? | 存疑（矛盾 / 無出處 / 需核實） |
這一步的交付物是素材卡表格 + 缺口清單，先給用戶確認，再往下走。
三條紅線（ingest.md §3）：不改數字、不改口徑、不把推測寫成事實。
發現同一指標多個數值時，進 ? 卡去問，不許默默擇一。
Step 1 · 話題擴展與大綱
- 用戶給了素材：從素材卡反推能寫什麼角度（
references/topic-expand.md§3） - 用戶只給話題：走
topic-expand.md§1–§3，把一句話擴成論點樹
再結合 references/writing-playbook.md 的 §1（垂類基線）和 §4（5 套結構模板）選定骨架，
產出帶字數配比的大綱給用戶確認。
大綱裡每個論點必須掛上素材卡編號（[F1] [D2]），掛不上的論點直接刪，
不許為了結構完整硬湊（topic-expand.md §4）。
Step 2 · 寫標題與摘要
讀 references/writing-playbook.md §2 與 §6：
- 出 長標題（≤64 字，用於後台字段）+ 短標題（≤20 字，用於信息流展示）
- 一次給 5 個候選，標註各自用了哪種公式，讓用戶挑
- 摘要 ≤120 字，給 1~2 個版本
Step 3 · 寫正文
按大綱寫 Markdown，注意：
- 開頭按 §3 的鉤子寫法，前 3 行就要抓住人
- 每段一件事，單段 ≤5 行（約 260 字）
- 收尾按 §5，用「提問收尾 / 系列預告 / 價值總結」，不要寫誘導分享
- 寫完用 §7 的 24 條清單過一遍「AI 味」，刪掉所有刪了不影響理解的過渡詞
Step 4 · 排版渲染
沿用 frontmatter 的 theme 或用戶明確指定的主題渲染；沒有偏好時按垂類選，局部排版默認 tech：
python3 scripts/md2wx.py article.md -o out/article.html
輸出父目錄會自動創建，產出兩個文件：
out/article.html— 預覽頁（帶白底容器，像手機閱讀頁）→ 用來看out/article.body.html— 純正文片段 → 備用粘貼方案
本步不生成工作台；最終 out/sheet.html 在 Step 7 生成，避免在封面和定稿完成前保存過早的文件快照。
渲染後用 preview.py 截圖，自己先看一眼再交給用戶（標題是否換行難看、表格是否過寬、代碼塊是否被截斷）。瀏覽器不可用時打開 HTML 人工檢查並如實說明未截圖，不因此要求重寫文章。
Step 5 · 生成封面（發布必做）
公眾號沒有封面就發不出去，這一步在「完整創作」和「要發布的排版」裡不是可選項。
python3 scripts/cover.py --md article.md --all -o out/cover
三檔一次出：cover.png 900×383（頭條 2.35:1）、cover-square.png 1080×1080（方形）、
cover-thumb.png 200×200（次條）。尺寸不對會被平台裁切，lint --publish 會校驗。
參數默認從 frontmatter 讀（標題、標籤、作者、主題），一般不用再傳：
--style：gradient（默認，深色底）/minimal（白底，觀點文）/band（色帶，品牌稿）--all出三檔：頭條 900×383、方形 1080×1080、次條 200×200- 封面標題默認用
title（長標題鉤子更足）；想換文字就在 frontmatter 加cover_title
Step 6 · 雙重體檢（兩個閘門，各管一段）
完整創作執行兩個閘門；僅排版、僅體檢按入口表選擇對應檢查，不強制補造缺失材料，也不自行改動原稿。缺少元信息、素材卡或截圖時記錄限制，局部交付不標為整篇可發布驗收。
6.1 寫作閘門 —— 查「觀點有沒有依據、數字從哪來」
python3 scripts/lint.py article.md --cards out/素材卡.md --outline out/大綱.md
這一步是硬閘門，不是在寫建議：
| 檢查 | 規則 | 不過會怎樣 |
|---|---|---|
| 空引用 | 正文 [F1] 必須在素材卡裡存在 | 報「必須修」 |
| 存疑卡 | [?N] 不得出現在正文 | 報「必須修」——核實或刪 |
| 數字無出處 | 正文每個「數字+單位」必須能在 F/D 卡找到 | 報「必須修」 |
| 論點無支撐 | 大綱每條支撐必須掛 ≥1 個 [F]/[D] | 報「必須修」 |
| 主論點質量 | 不能是短語（「緩存很重要」這類） | 報「必須修」 |
| 觀點卡 | [O] 被引用時提示不得當主論據 | 「應確認」 |
| 缺口清單 | 大綱必須有 P0/P1/P2 缺口 | 「提示」 |
沒有素材卡時自動降級：只提示「數字無法校驗」，並列出所有帶單位的數字供人工過目。
產物版本校驗：加 --out <產物目錄> 後，還會比對交付物裡的構建指紋與當前源稿算出的指紋。
python3 scripts/lint.py article.md --out out --publish --strict
--publish 表示按發布就緒範圍驗收，必須配合 --out 指定產物目錄；缺少目錄參數會報錯。它按本項目三檔規格檢查文件存在與 PNG 頭中的寬高，不完整解碼圖片，也不驗證封面文字、上傳或微信後台要求。
| 情況 | 判定 |
|---|---|
| 產物指紋 == 當前源稿指紋 | 通過 |
| 改過稿但沒重新渲染 | 「必須修」：預覽頁/工作台是舊版本 |
build.json 記錄的源稿摘要對不上 | 「必須修」：源稿在生成後被改過 |
article.body.html 被替換或手工編輯 | 「必須修」：靠 build.json 的正文摘要旁路校驗 |
| 產物沒有指紋 | 「應確認」：舊腳本生成或被手工改過 |
缺封面 / 尺寸不對（--publish） | 「必須修」：未達到本項目的發布就緒封面規格 |
這一步是防「改完稿忘了重跑，把上一版發出去」的唯一機械保障，交付前必跑。
6.2 發布體檢 —— 查「能不能發」
python3 scripts/check.py article.md --html out/article.body.html --strict
標題長度、摘要長度自動從 frontmatter 取，不用重複傳。
硬性通過標準：
| 指標 | 要求 |
|---|---|
| lint「必須修」 | 必須為 0 |
| 高風險項 | 0 個未解決高風險，人工確認誤報需留下證據與復核記錄 |
| 元信息 | title、title_short、summary 必填且非空；只支持 key: value 單行字段 |
| 標題字數 | 長標題 ≤64，短標題 ≤20；實際發布標題的關鍵開頭信息仍需人工檢查 |
| 摘要字數 | ≤120 |
| 外域圖片 | 發布前上傳或替換為微信可用圖片，並在編輯器預覽確認 |
| 專業或涉密內容 | 必須人工/法務終審，刪關鍵詞、改寫或脫敏不能替代審核和授權 |
兩個 --strict 都可以進 CI：有「必須修」或高風險時退出碼為 1。check.py 會將缺失/超長元信息、不支持的多行字段值、顯式指定但不存在的 HTML 作為高風險；未加 --strict 仍報告問題，但退出碼為 0。
發布體檢逐字段掃描 title、title_short、summary、cover_title、author、tag 與正文；正文代碼仍屏蔽，元信息中的反引號不能繞過檢查。JSON finding 的 field 標明來源，正文 line 仍相對正文。標題/摘要的命令行覆蓋值是最終檢查對象。
掃描通過不等於允許發布。高風險按 references/compliance.md §0 記錄「待復核 / 確認誤報 / 完成修訂 / 拒絕發布」；腳本不能讀取或代替人工復核記錄，確認誤報不使 --strict 自動通過。專業、授權與保密問題未解決時暫停，不交付為可發布稿。中低風險保留項、人工確認項及依據一併說明。
素材使用權限或出處不明時先補授權/來源或排除；不改成量級，也不把外部觀點改成作者親歷。素材攝入後單獨保留 許可與限制.md，記錄來源、署名、使用範圍、適用邊界及授權狀態。
Step 7 · 交付
需要 HTML/工作台的任務，交付前統一重新生成最終工作台。 確認定稿、元信息、主題及請求的封面已經完成，再使用同一份源稿與相同主題/輸出參數運行：
python3 scripts/md2wx.py article.md --sheet -o out/article.html
這會同步更新預覽頁、正文片段和 sheet.html，工作台從同目錄讀取最終 cover.png、cover-square.png、cover-thumb.png。它是靜態文件快照，刷新瀏覽器不會重新生成工作台。若之後又修改正文、元信息、主題或圖片，重新生成相關產物並復查對應檢查與預覽；不得交付舊快照。
構建指紋與回退：
- 指紋包含渲染代碼、源稿、合併後的主題、實際標題/署名/主題覆蓋及輸出選項、本地圖片和封面內容；元信息和本地資產變化都會使舊構建失效。
build.json使用 schema 2，聲明實際請求的文件，並逐項記錄完整 SHA256；檢查器按實際渲染參數校驗，因此顯式-t覆蓋主題不應誤報。文件丟失、內容替換或結構損壞會阻斷。article.body.html保持純淨、不帶任何標記；它與預覽/工作台分別靠清單摘要校驗，不只信任 HTML 中的指紋標籤。舊清單無法完整驗證時提示重新渲染。- 完整創作在最後一次渲染加
--snapshot，保存源稿、請求的 HTML、本地圖片和封面到out/.builds/<指紋>/。同一指紋的快照不可覆蓋；缺少本地圖片不能冒充完整快照。圖片須為輸出目錄內相對路徑，快照不獲取遠程圖片。 md2wx.py --list-builds --out-dir out查看歷史；md2wx.py --rollback <指紋> --out-dir out會恢復源稿原路徑、產物、本地圖片和封面，並清理上一版清單聲明而本版不需要的輸出。操作前先確認回退意圖，因為它會覆蓋當前源稿和已聲明資產；僅使用可信的本地快照。- 回退先驗證全部文件及摘要，損壞或危險路徑不會先恢復一半。快照不恢復渲染腳本或全局主題配置；這些變更後仍須重新渲染和復查。stdin 快照的源稿恢復為輸出目錄的
article.md。 - 僅排版沿用上面的不帶
--snapshot命令；完整創作使用：
python3 scripts/md2wx.py article.md --sheet --snapshot -o out/article.html
交付前自檢清單（逐條確認，不要用「命令跑過了」代替「文件看過了」）：
- 完整創作運行
lint.py article.md --out out --publish --strict通過——產物就是當前源稿且封面滿足項目規格 -
check.py article.md --html out/article.body.html --strict通過——沒有高風險項 - 親眼看過
article.html或preview.png（標題換行、表格寬度、代碼塊截斷） -
sheet.html裡的標題/短標題/摘要/作者與要填進後台的一致 - 三檔封面存在且頭部尺寸正確（
--publish已檢查）；另行打開圖片確認可解碼、文字沒被截斷 - 正文裡的本地圖片已列明「需要手動上傳」
- 交付說明寫清：保留了哪些中低風險項、哪些沒做完
逐項檢查實際輸出文件，封面或截圖缺失項要列明，不能以執行過命令代替文件確認；需要完整成稿時缺失項未解決不標為完整交付。源 Markdown 按實際路徑一併提供，不要求移動或覆蓋用戶原稿。
按任務範圍自檢（自檢項跟著請求走，不要一律按完整創作驗收）：
- 完整創作：全部清單逐項過
- 僅排版：源稿、HTML、正文片段、工作台可用即可，僅排版不要求三檔封面
- 僅封面：只復核封面文字與尺寸，不要求正文與體檢
- 僅體檢：只交報告，不要求改稿
局部任務只交付請求的產物：僅排版交付源稿、HTML、正文片段和工作台；僅封面交付請求尺寸的圖片及文字復核結論；僅體檢交付檢查報告。不要求補齊封面、素材卡或大綱，不能把局部檢查當成完整發布驗收。
下列清單僅適用於完整創作，源稿文件的位置以實際路徑為準：
out/
├── article.md 定稿 Markdown（源文件，含 frontmatter）
├── article.html 預覽頁（給人看）
├── article.body.html 純正文片段（備用）
├── sheet.html 發布工作台（用來發）
├── cover.png 頭條封面 900×383
├── cover-square.png 方形 1080×1080
├── cover-thumb.png 次條 200×200
└── preview.png 排版截圖
完整創作同時給出：長標題 / 短標題 / 摘要 / 體檢結論（保留了哪些中低風險項）。局部任務只列已有元信息、所請求產物、實際檢查範圍及未完成項，不為了補齊清單另寫標題、摘要或正文。
發佈到公眾號（關鍵步驟）
打開 out/sheet.html，一個頁面搞定所有複製操作：
- ① 標題 → 點「複製」→ 粘進後台標題框
- ③ 摘要 → 點「複製」→ 粘進後台摘要框
- ④ 作者 → 點「複製」→ 粘進作者框
- 正文 → 點右上角「複製正文」→ 粘進編輯區
- 正文圖片 → 左側「正文圖片」卡片裡逐張處理（見下）
- 封面圖 → 上傳
cover.png - 照「發布前清單」逐項勾選
為什麼圖片會丟
微信編輯器的粘貼只接收文字和樣式，不會幫你上傳本地圖片。 正文裡的
<img src="fig.png"> 是本地相對路徑，粘進編輯器後圖片位置是空的——這不是排版沒做好，
是宿主環境的限制：圖片必須先進入微信服務器（mmbiz.qpic.cn）才能顯示。
沒有 API 權限時，這一步只能手動。工作台把它壓縮成兩條路徑：
| 方式 | 操作 |
|---|---|
| 複製圖片 | 點「複製圖片」→ 到編輯器對應位置 Cmd+V，微信會自動上傳 |
| 右鍵複製 | 「複製圖片」失敗時點「打開原圖」→ 右鍵「複製圖片」→ 編輯器粘貼 |
| 兜底 | 右鍵「圖片另存為」→ 編輯器「圖片」按鈕上傳 |
順序按正文出現次序（第 1 張、第 2 張……），粘貼時對照正文找位置。
不要複製
.md源文：md 是純文本，切過去只剩一堆#和**，圖片和排版都不會有。 必須複製工作台的富文本，或article.body.html的渲染結果。
檢查是否漏圖：發布前在手機預覽裡從頭劃一遍，看每張圖是否都在位。
備用方案：瀏覽器打開 article.body.html → Cmd+A → 複製 → 粘貼。
（不要用 article.html，那是預覽頁，會帶進外層容器。）
主題選擇
| 主題 | 適用 | 視覺 |
|---|---|---|
tech 科技藍 | 技術拆解、產品分析、工程實踐 | 藍色強調、H2 豎條、深色代碼塊 |
growth 成長橙 | 職場經驗、成長復盤、方法論 | 暖橙強調、H2 色塊、行距更鬆 |
minimal 極簡黑白 | 觀點評論、深度思考 | 黑白、H2 底線 |
elegant 商務藏青 | 品牌稿、正式發布、行業分析 | 襯線字體、藏青強調、H1 居中 |
原則：內容越硬，主題越素。拿不準就用 tech。
新增主題只需在 scripts/themes/ 加一個 JSON，字段說明見 references/layout-spec.md §13。
命令速查
| 命令 | 作用 | 關鍵參數 |
|---|---|---|
ingest.py <文件...> | 素材 → 結構化文本 + 候選可引用句 | -o 輸出目錄、--json |
md2wx.py <md> | Markdown → 公眾號 HTML | --sheet 出工作台、--snapshot 打快照、-t 主題、-o 輸出、--no-body、--check |
md2wx.py --list-builds | 查看歷史構建 | --out-dir |
md2wx.py --rollback <指紋> | 恢復某版產物 | --out-dir |
cover.py | 封面圖 | --md 自動讀 frontmatter、--style、--all；--title/--tag/--author/--theme 可覆蓋 |
lint.py <md> | 寫作閘門 + 產物版本校驗 | --cards、--outline、--out、--json、--strict |
check.py <md> | 發布前體檢 | --html、--json、--strict；--title/--summary 可覆蓋 frontmatter |
preview.py <html> | 截圖確認排版 | -o、--width、--height |
標題、摘要、作者、主題默認都從 frontmatter 讀；命令行參數只用於臨時覆蓋。
--strict 用於 CI/自動化：存在高風險時退出碼為 1。
常見坑（必須知道）
| 坑 | 現象 | 處理 |
|---|---|---|
| 外鍊不可點 | 正文裡的 https://... 點了沒反應 | 改成文字描述，或放「閱讀原文」 |
| 圖片空白 | 外域圖片顯示為佔位/灰塊 | 手動在編輯器上傳，或走 L3 素材接口 |
| 空行不穩定 | 用空行做段落間距，客戶端表現不一致 | 用 margin 做間距，md2wx.py 已處理 |
| 代碼折行 | 長代碼被自動折行，不能讀 | 單塊 ≤30 行，超長拆片段 |
| 表格撐爆 | 5 列以上表格橫向滾動 | 列數 ≤4，超了就拆成兩張 |
| 標題被截斷 | 信息流只顯示約 20 字 | 必須有短標題版本 |
| 沒封面發不出去 | 後台頭條封面是必填項，跳過封面等於交不了稿 | 完整創作必跑 cover.py --all，交付前用 lint --out --publish 驗 |
| 交付了舊版本 | 改了稿但沒重新渲染，發出去是上一版 | 交付前跑 lint --out out --strict，指紋不一致會攔住 |
參考文檔（按需加載，不要一次性全讀）
| 文檔 | 什麼時候讀 |
|---|---|
references/ingest.md | Step 0.5：素材攝入、抽素材卡、保真規則、口徑衝突、缺口清單 |
references/topic-expand.md | Step 1：話題擴展、論點樹、防注水紀律 |
references/writing-playbook.md | Step 2~3：標題公式、開頭鉤子、結構模板、去 AI 味 |
references/compliance.md | Step 6：合規詞表、違規類型、替代表述 |
references/layout-spec.md | 需要調排版、加主題、判斷視覺問題時 |
references/api.md | 用戶要做 L3 自動發布時 |
依賴
| 依賴 | 用於 | 缺失時 |
|---|---|---|
| Python 3.9+ | 全部腳本 | 必須 |
| Pillow | cover.py | 封面圖這一步會失敗，其餘可用 |
| pypdf | ingest.py 解析 PDF | 已 vendored 到 scripts/vendor，無需另裝 |