wisp-writer：用 Wisp 主題寫出風格一致的文章
Wisp 的取向是安靜、準確、克制。文章寫在 src/content/posts/<slug>/index.mdx（或 index.md），frontmatter 以 src/content.config.ts 為準。本 skill 提供：
SKILL.md
reference/ frontmatter.md style-guide.md elements.md templates/
scripts/ new_post.py check_post.py tests/ （Python + uv，PEP 723 內聯依賴，無需安裝）
命令約定
所有命令在站台根目錄執行，寫成 uv run skills/wisp-writer/scripts/<腳本>.py ...。把本 skill 複製到其他 Wisp 站台時：
- 放在
<站台>/skills/wisp-writer/：命令不變。 - 放在
<站台>/.claude/skills/wisp-writer/或~/.claude/skills/wisp-writer/：把路徑換成實際位置；腳本會從目前目錄向上尋找astro.config.*或src/content，也可以用--root <站台根目錄>指定。 - 找不到站台時腳本會提示並以退出碼 2 結束，不會寫入任何檔案。
- 沒有 uv 時：
python3 <路徑>/new_post.py ...同樣可以執行（只用標準庫，需要 Python 3.10+）。
工作流程
- 明確讀者和重點。 動筆前寫下三件事：讀者是誰（會用什麼、不會什麼），讀完能帶走什麼（一句話結論），文章類型。資料不足時先問使用者，不要編造事實、資料或引用。
- 建立文章。 按類型選模板：
tutorial教學、deep-dive原理深挖、algorithm演算法講解（含互動元件）、note短筆記、paper-reading論文解讀。uv run skills/wisp-writer/scripts/new_post.py attention-explained \ --title "自注意力機制講解" --template deep-dive \ --tags "LLM,Transformer" --category 機器學習 \ --description "從直覺到公式，講清楚自注意力的計算過程。"--draft、--md/--mdx、--date、--list-templates。 - 寫作。 遵循 style-guide，元素寫法見 elements，欄位見 frontmatter。替換模板裡的全部
TODO。 - 配圖與互動。 需要圖時，使用 wisp-diagram skill 產出原始檔案和
.wisp.svg，再用圖表引用語法放進文章；簡單流程直接用 Mermaid。需要互動展示時使用現有的 explainer 元件（目前是MatMul）；其他演算法需要新增元件，方法見docs/guide/explainers.md，那屬於程式碼變更，應單獨說明並徵得同意，不要在寫文章時順手改。 - 檢查並修復。
輸出格式uv run skills/wisp-writer/scripts/check_post.py attention-explained --strict檔案:行號 層級 規則 說明。error 必須修；warning 逐條判斷，能修就修；info 只是提示。--json供程式讀取，--all檢查全部文章。 - 預覽。
pnpm build必須通過（會校驗 frontmatter 和 Mermaid）；想看效果用pnpm dev。可選：用 Playwright 對文章頁分別在 light 和 dark 主題截圖各一張，檢查公式、圖表和程式碼區塊是否溢出、深色下是否看得清。
硬規則
- 正文從 h2 開始，不寫 h1，層級不跳階；h2 用名詞短語。
title≤ 80、description≤ 200 個字元；description寫清文章解決什麼問題。- 標籤和分類重用已有寫法，大小寫一致（不要同時有
llm和LLM）。 - 中文段落用全形標點符號；中英文之間不需手動加空格；中文強調用
**粗體**，不用斜體。 - 術語首次出現時標註英文，如「自注意力（self-attention）」。
- 每個程式碼區塊都有語言標識；長程式碼區塊的摺疊是可選項，預設不用管。
- 每張圖都有 alt，描述圖要表達的結論；圖註用
"圖 N：說明"。 - 不硬編碼顏色，不寫
style=，不用 Tailwind 色階；顏色只能來自主題變數。 - 用到元件的文章必須是
.mdx並import；互動元件加client:visible。 - 不編造事實、資料、引用和連結；沒有把握的內容明確標註或刪除。
- 不改動現有文章，除非使用者要求；只在
src/content/posts/<slug>/內工作。
範例片段
下面是符合語氣的一段（講清一件事，不鋪墊，不誇張）：
## 為什麼要除以 √d
假設 $q$ 和 $k$ 的每個分量都是變異數為 1 的獨立隨機變數，那麼點積 $q \cdot k$ 的變異數是 $d_k$。維度越大，點積越大，softmax 就越接近 one-hot，梯度會變得很小。
除以 $\sqrt{d_k}$ 之後，變異數回到 1 左右，softmax 的輸出保持在溫和的範圍內。沒有這一步，深層網路很難訓練。
對比：「眾所周知，這個超級簡單但非常重要的小技巧能夠極大地提升效果！」——空洞、過度強調、沒有資訊。
常見錯誤
- 開頭寫「本文將介紹……」「隨著……的發展」，應直接給出結論或問題。
- 在正文中寫
# 標題；或 h2 之後直接寫 h4。 - 標題用句子（「我們來看看怎麼實現」），應為名詞短語（「實現」）。
- 中文裡混用半形逗號、括號；用斜體強調中文。
.md檔案裡寫元件，或.mdx裡忘了import；互動元件忘了client:visible。- 圖片沒有 alt；引用了尚未生成的
.excalidraw（先畫圖，再引用）；引用.wisp.svg而不是原始檔案。 - 同一概念用了新標籤（
Llm、大模型與已有LLM並存）。 - Mermaid 節點文字過長，渲染後重疊；應縮短到大約 12 個中文字以內。
- 留下
TODO佔位就交付；check_post.py --strict能發現。 - 只寫程式碼不解釋：程式碼前說明目的，程式碼後說明關鍵點或預期輸出。