Kami — AI 文件設計系統完整教學

Kami (紙, かみ) 在日文裡就是「紙」的意思。它是一套以約束為核心的設計系統 (constraint-based design system)，能把 AI 生成的內容轉成專業排版的文件。這份教學涵蓋上游開源專案本身，以及在上面打造的企業級客製化延伸。

1. 什麼是 Kami？(What is Kami)

問題在哪

Claude、GPT 這類 AI 模型寫出來的內容品質，其實已經跟專業寫手不相上下了。但每次你叫 AI「幫我做一份 PDF」，出來的版面、字型、色調都不一樣。成品看起來堪用，但絕對不是你會直接寄給投資人、面試委員、或者拿去研討會報告的東西——不手動整理一番根本拿不出手。

瓶頸不在寫作能力，而在設計一致性 (design consistency)。

解法：一套約束語言

Kami 不是一包模板、也不是 CSS 框架。它是一套約束語言 (constraint language)——一組精簡且有主見的規則，任何 AI agent 都能遵循，產出你真的會拿去用的文件。你可以把它想成「給機器人的 style guide」：一組配色、一套字型層級、一種編輯節奏，統一套用到所有文件類型。

核心哲學很簡單：好的內容，值得好的紙。

tw93 三部曲

Kami 是 tw93 的 AI 工具三部曲中的第三部：

三者形成一個完整迴圈：Kaku 打造工具、Waza 讓你更會用工具、Kami 交付最終產物。

Kami 在 AI 文件工作流中的位置

flowchart LR
    A[User Request] --> B[AI Agent]
    B --> C{Content Ready?}
    C -->|No| B
    C -->|Yes| D[Kami Constraint Language]
    D --> E[Template Selection]
    E --> F[HTML Generation]
    F --> G{Output Path}
    G -->|Default| H[WeasyPrint PDF]
    G -->|Editable| I[python-pptx PPTX]
    G -->|Markdown| J[Marp Slides]
    G -->|Web| K[Static HTML Site]
    
    style D fill:#1B365D,color:#fff
    style H fill:#f5f4ed,stroke:#1B365D
    style I fill:#f5f4ed,stroke:#1B365D
    style J fill:#f5f4ed,stroke:#1B365D
    style K fill:#f5f4ed,stroke:#1B365D

關鍵數據 (Key Stats)

2. 安裝指南 (Installation Guide)

Kami 支援四種安裝路徑，取決於你用的 AI 工具。四種路徑裝的是同一套設計系統，差別只在 agent 怎麼找到和載入 skill。

2.1 Claude Code（推薦）

需要 Claude Code v2.1.142 或更新版本。

1# 從 plugin marketplace 安裝
2/plugin marketplace add tw93/kami
3/plugin install kami@kami
4
5# 之後更新
6claude plugin update kami

2.2 Codex

1# 從 repo marketplace 安裝
2codex plugin marketplace add tw93/kami
3codex plugin add kami@kami
4
5# 之後更新
6codex plugin marketplace upgrade kami
7codex plugin add kami@kami    # 重新整理已安裝的 snapshot

2.3 通用 Agent（OpenCode、Pi 等）

如果你的工具從 ~/.agents/ 讀取 skills：

1npx skills add tw93/kami/plugins/kami/skills/kami -a '*' -g -y

子路徑 plugins/kami/skills/kami 指向自包含的 skill 套件。如果只裝 tw93/kami 的 repo 根目錄，只會拿到 SKILL.md，因為 repo 根目錄同時也是網站原始碼。

更新的話就重跑同一個 npx skills add 指令。目前先別用 npx skills update（它會把 repo-root skills 折疊成單一檔案）。

2.4 Claude Desktop

1. 從最新 release 下載 kami.zip
2. 打開 Customize > Skills > “+” > Create skill
3. 直接上傳 ZIP（不需要解壓縮）

更新方法：下載最新 ZIP，點 skill 卡片上的 “…"，選 Replace，上傳。

2.5 Brand Profile 設定 (Brand Profile Setup)

Brand profile (品牌設定檔) 是選用的，但建議設定。它會在跨 session 之間保存你的身份、品牌色、預設值和寫作習慣。

建立檔案：

1mkdir -p ~/.config/kami
2# 複製範例模板並自訂
3cp references/brand.example.md ~/.config/kami/brand.md

檔案用 YAML frontmatter 放結構化欄位，Markdown body 放自由格式的備忘：

 1---
 2name: Jane Doe
 3role: Founder & CEO
 4email: jane@example.com
 5brand_color: "#1B365D"
 6language: en
 7page_size: A4
 8tone: professional
 9---
10
11# Writing Habits
12- Prefer active voice
13- Keep sentences under 25 words
14- Use Oxford comma

優先順序： 明確 prompt 指令 > 編輯判斷 > 習慣備忘 > frontmatter 預設值 > 內建預設值。Brand profile 只會靜默補缺，不會覆蓋你在當前對話中指定的東西。

2.6 字型處理 (Font Handling)

每種語言使用一套 serif 字型 (襯線字型) 涵蓋整個頁面：

大型 CJK 字型沒有打包進 skill 套件，為了保持 ZIP 輕量。當字型缺失時，scripts/ensure-fonts.sh 會自動恢復到使用者字型目錄：

1bash scripts/ensure-fonts.sh

在完整 repo checkout 的情況下，字型會先嘗試從本地檔案載入，再 fallback 到 jsDelivr CDN。

安裝決策樹 (Installation Decision Tree)

flowchart TD
    A[Which AI tool?] --> B{Claude Code?}
    B -->|Yes| C["/plugin marketplace add tw93/kami"]
    B -->|No| D{Codex?}
    D -->|Yes| E["codex plugin marketplace add tw93/kami"]
    D -->|No| F{Claude Desktop?}
    F -->|Yes| G["Download kami.zip, upload via Skills UI"]
    F -->|No| H["npx skills add tw93/kami/..."]
    
    C --> I[Run: bash scripts/ensure-fonts.sh]
    E --> I
    G --> I
    H --> I
    I --> J{Brand profile?}
    J -->|Yes| K["Create ~/.config/kami/brand.md"]
    J -->|No| L[Ready to use]
    K --> L

3. 核心架構 (Core Architecture)

六步驟工作流 (The 6-Step Workflow)

不管你是做一頁紙 (one-pager) 還是 15 頁白皮書 (white paper)，每份 Kami 文件都走同樣六個步驟：

1. 載入 brand profile — 如果 ~/.config/kami/brand.md 存在就讀取。套用為最低優先度的預設值。
2. 判斷語言 — 配合使用者語言。中文用 *.html，英文用 *-en.html，韓文用 *-ko.html，日文走中文路徑搭配 YuMincho (best-effort)。
3. 選擇文件類型 — 透過決策樹，把使用者意圖對應到 10 種文件類型之一。
4. 填充模板 — Agent 把 HTML 模板的 placeholder 換成實際內容，遵循 design.md 和 writing.md 的規範。
5. 建置 — 渲染到目標格式 (WeasyPrint PDF、python-pptx PPTX 或 Marp MD)。
6. 驗證 — 視覺 QA 檢查，特別注意 CJK 渲染和版面完整性。

10 種文件類型 (The 10 Document Types)

三條渲染路徑 (Three Rendering Paths)

完整 Pipeline 架構 (Full Pipeline Architecture)

flowchart TB
    subgraph Input
        U[User Prompt]
        B[Brand Profile]
        M[Mermaid Source .mmd]
    end

    subgraph KamiCore["Kami Core Engine"]
        S1[Step 1: Load Brand]
        S2[Step 2: Language Detection]
        S3[Step 3: Doc Type Selection]
        S4[Step 4: Fill Template]
        S5[Step 5: Build]
        S6[Step 6: Verify]
        S1 --> S2 --> S3 --> S4 --> S5 --> S6
    end

    subgraph Templates["10 Templates"]
        T1[one-pager]
        T2[long-doc]
        T3[letter]
        T4[portfolio]
        T5[resume]
        T6[slides-weasy]
        T7[equity-report]
        T8[changelog]
        T9[landing-page]
    end

    subgraph MermaidPipeline["Mermaid Pipeline"]
        BM[beautiful-mermaid SVG]
        MC[mermaid-cli PNG]
        MN[mermaid_normalize.py]
        CI[codex-image Editorial PNG]
        BM --> MN --> SVG[Clean SVG]
        MC --> PNG[High-res PNG]
        M --> CI
    end

    subgraph Output
        PDF[WeasyPrint PDF]
        PPTX[python-pptx PPTX]
        MARP[Marp MD Slides]
        HTML[Static HTML Site]
    end

    U --> S1
    B --> S1
    S3 --> Templates
    Templates --> S4
    MermaidPipeline --> S4
    S5 --> PDF
    S5 --> PPTX
    S5 --> MARP
    S5 --> HTML

    style KamiCore fill:#f5f4ed,stroke:#1B365D
    style T10 fill:#00A896,color:#fff

4. 設計系統深度解析 (Design System Deep Dive)

Kami 調色盤 (The Kami Palette)

整套設計系統建構在一個刻意限縮的調色盤上。這個約束就是重點：顏色越少，一致性越高。

黃金守則：墨藍 (Ink Blue) 是唯一的強調色。其他全部是暖灰色的深淺變化。沒有其他顏色、沒有漸層、沒有陰影、沒有 3D 效果。

字型排版 (Typography)

Kami 每種語言只用一套 serif 字型。這是刻意的選擇：serif 字型天生就能透過粗細和大小變化傳達層級，而 sans-serif 需要額外的視覺線索。

字級系統很簡潔：

• 標題 (Title)：大號、粗體、墨藍色
• 副標 (Subtitle)：中號、正常字重、暖深灰
• 內文 (Body)：舒適的閱讀大小、近黑色
• 圖說 (Caption)：小號、石灰色

版面原則 (Layout Principles)

1. 不用陰影 — Drop shadow 是偷懶。用留白和邊框取代。
2. 不用漸層 — 只用純色。這也確保 WeasyPrint 相容性。
3. Serif 層級 — 靠字型大小和粗細傳達結構，不靠顏色種類。
4. 充裕的留白 — 讓內容呼吸。擠得密密麻麻的頁面是不會有人想讀的。
5. 溫暖畫布 — #f5f4ed 羊皮紙色背景比純白更溫暖，降低視覺疲勞，讓文件有一種沉穩、編輯感的質地。
6. 列印變體 — 選用的白紙模式 (white-paper mode) 會把背景換成白色，適合辦公室印表機，但卡片和表格保留溫暖色調，層級感依然清晰。

17 種內嵌 SVG 圖表 (17 Inline SVG Diagram Types)

Kami 內建 17 種手繪風圖表原件，以內嵌 SVG (inline SVG) 的方式提供。這些不是獨立的文件類型——它們是你嵌入任何文件裡的元件。

每張圖表都用 Kami 調色盤（羊皮紙背景、墨藍強調色、暖灰中性色），而且是完全靜態的——不需要 JavaScript。

5. 文件類型與範例 (Document Types & Examples)

5.1 One-Pager (一頁紙)

使用場景：高層摘要、產品簡介、投資人一頁紙。必須塞在一頁以內。

關鍵特色：高密度版面、指標方塊 (metric tiles)、清晰的區塊層級，專為快速掃讀設計。

範例 prompt：

• EN: "Make a one-pager for my SaaS startup that summarizes our Q2 metrics"
• CN: "幫我做一份一頁紙，總結我們的 Q2 營運數據"

5.2 Long Doc (長文)

使用場景：白皮書 (white paper)、技術報告、年度摘要。6-15 頁的持續論述。

關鍵特色：目錄 (TOC)、編號章節、腳注、圖說、邊注。

範例 prompt：

• EN: "Turn this research into a 10-page white paper on federated learning"
• CN: "幫我把這份研究排版成一份關於聯邦學習的白皮書"

5.3 Letter (信件)

使用場景：推薦信、正式書信、辭職信、備忘錄 (memo)。

關鍵特色：信頭 (letterhead)、日期、收件人、正式結尾、簽名欄。

範例 prompt：

• EN: "Write a formal recommendation letter for my colleague"
• CN: "幫我寫一封正式推薦信"

5.4 Portfolio (作品集)

使用場景：專案展示、case study、設計作品集。3-6 頁，以視覺為主。

關鍵特色：Hero 圖片、專案卡片、前後對比、推薦語。

範例 prompt：

• EN: "Make a portfolio of my top 5 open source projects"
• CN: "幫我做一份我的開源專案作品集"

5.5 Resume (簡歷)

使用場景：專業簡歷、學術 CV。1-2 頁。

關鍵特色：含聯絡資訊的 header、經歷時間軸、技能標籤、學歷區塊。

範例 prompt：

• EN: "Build me a resume highlighting my ML engineering experience"
• CN: "幫我做一份強調機器學習工程經驗的簡歷"

5.6 Slides - Weasy (學術風格簡報)

使用場景：研討會演講、研究報告、學術研討。預設的簡報風格。

關鍵特色：羊皮紙背景、Charter serif 字型、眉標區塊標籤 (eyebrow section labels)、SVG 圖表、講者備忘。

範例 prompt：

• EN: "Design a slide deck for my talk on agent architectures"
• CN: "幫我做一套關於 Agent 架構的演講簡報"

5.7 Equity Report (個股研報)

使用場景：投資備忘錄、個股分析、季度報告。

關鍵特色：指標儀表板、價格圖表（K 線圖/瀑布圖）、估值表、風險矩陣。

範例 prompt：

• EN: "Write a Tesla Q1 2026 equity report with my analysis notes"
• CN: "幫我寫一份 Tesla Q1 2026 的個股研報"

5.8 Changelog (更新日誌)

使用場景：Release notes、版本歷史、產品更新日誌。

關鍵特色：版本標題、日期戳記、分類變更（Added / Changed / Fixed / Removed）。

範例 prompt：

• EN: "Make a changelog for our v1.7.1 release"
• CN: "幫我做一份 v1.7.1 的更新日誌"

5.9 Landing Page (落地頁)

使用場景：產品首頁、行銷網站。以螢幕優先，不產出 PDF。

關鍵特色：含入場動畫的 Hero 區塊、自動輪播的圖片走廊 (gallery carousel)、響應式斷點 (880px / 480px)、prefers-reduced-motion 支援、多語系附加檔案（sitemap, robots.txt, llms.txt）。

範例 prompt：

• EN: "Build a landing page for my Mac utility app"
• CN: "幫我做一個產品落地頁"

使用場景：企業 BD (Business Development; 商務開發) pitch、投資人簡報、藥廠 pipeline deck。完整說明見第 7 節。

關鍵特色：Teal + navy 配色、sans-serif (Inter/Lato/Outfit)、pipeline 導航列、8 種投影片類型、卡片式版面。

範例 prompt：

|——–|————-|—————| | 背景 (Background) | Parchment #f5f4ed | White #ffffff | | 強調色 (Accent) | Ink Blue #1B365D | Teal #00A896 | | 字型 (Typography) | Charter (serif) | Outfit/Inter/Lato (sans-serif) | | 風格 (Style) | 學術、編輯感、安靜 | 企業 BD、pitch-ready | | 版面 (Layout) | 學術密排節奏 | 卡片式、圖示豐富、寬鬆間距 | | 圖示 (Icons) | 無 | 圓形輪廓線圖示 (outline icons) | | 導航 (Navigation) | 眉標區塊標籤 | Pipeline 進度列 (5 階段) | | 目標受眾 (Audience) | 研究者、學者 | 投資人、BD 夥伴、高階主管 |

6. Mermaid 圖表管線 (Mermaid Diagram Pipeline)

為什麼 Mermaid 重要

Mermaid 是一種文字化的圖表語言 (text-based diagram language)。你不用在 PowerPoint 裡拖方塊，而是用程式碼描述結構，渲染器幫你畫出來。這讓圖表能版控、能讓 AI 寫、能重現。

Kami 透過兩條不同的渲染路徑整合 Mermaid，各自適用不同環境。

路徑 1：beautiful-mermaid（瀏覽器 SVG）

beautiful-mermaid 是一個瀏覽器端渲染器，產出的 SVG 用原生 <text> 元素（而不是 <foreignObject>; 外部物件元素）。這是 PDF 輸出的首選路徑。

工作流程：

1. 在 .mmd 檔案中寫你的 Mermaid 程式碼
2. 在任何跑 beautiful-mermaid 的瀏覽器中渲染成 SVG（比如 https://agents.craft.do/mermaid）
3. 跑 normalizer 把主題轉成 Kami 調色盤：

   1python3 scripts/mermaid_normalize.py raw.svg -o clean.svg
   

4. 把乾淨的 SVG 嵌入你的文件模板

路徑 2：mermaid-cli（無頭 PNG 渲染）

當 beautiful-mermaid 用不了的時候（比如無頭 Docker 環境），mermaid-cli (Mermaid 命令列渲染工具) 可以直接渲染 .mmd 檔案。但是，它的 SVG 輸出對文字標籤使用 <foreignObject> (外部物件元素; SVG 內嵌 HTML 的機制)，而 WeasyPrint 無法渲染 <foreignObject>——你的 PDF 會有方塊和線條，但裡面的文字是隱形的。

解法：渲染成 PNG，不是 SVG。

1# 建立給 Docker/container 用的 puppeteer 設定
2echo '{"args":["--no-sandbox","--disable-setuid-sandbox"]}' > puppeteer-config.json
3
4# 以高解析度渲染成 PNG
5npx --yes @mermaid-js/mermaid-cli \
6  -i diagram.mmd -o diagram.png \
7  -b white -w 1600 \
8  -p puppeteer-config.json \
9  -c theme.json --quiet

mermaid_normalize.py 腳本

這是一個純 Python 腳本（不依賴 Node），把任何 beautiful-mermaid SVG 轉換成 Kami 風格的圖表：

--check 旗標會跑一次 lint 檢查，抓出任何 color-mix(、<foreignObject>、或外部字型 import，這些都會搞壞 PDF 渲染。

WeasyPrint SVG 陷阱 (The WeasyPrint SVG Trap)

這是 Kami mermaid pipeline 裡最常遇到的坑：

mermaid-cli SVG 用 <foreignObject> 做文字標籤。WeasyPrint 會忽略 <foreignObject>。你的 PDF 會有方塊和線條，但裡面的文字全部消失。

解法很簡單：如果你用 mermaid-cli，一律渲染成 PNG，不是 SVG。如果你用 beautiful-mermaid，它的 <text> 元素在 normalize 之後就沒問題。

Kami 主題檔 (mermaid-theme.json)

references/mermaid-theme.json 把 beautiful-mermaid 的七個色彩角色對應到 Kami 調色盤：

兩條路徑比較 (The Two Paths Compared)

flowchart LR
    subgraph Input
        MMD[".mmd Source File"]
    end

    subgraph PathA["Path A: beautiful-mermaid"]
        BM["Browser Render (SVG)"]
        NM["mermaid_normalize.py"]
        CSVG["Clean SVG"]
        BM --> NM --> CSVG
    end

    subgraph PathB["Path B: mermaid-cli"]
        MCLI["npx mermaid-cli (PNG)"]
        HPNG["High-res PNG"]
        MCLI --> HPNG
    end

    MMD --> BM
    MMD --> MCLI
    CSVG --> DOC["Embed in Document"]
    HPNG --> DOC

    style PathA fill:#f5f4ed,stroke:#1B365D
    style PathB fill:#f5f4ed,stroke:#504e49

mermaid-cli PNG 尺寸指南 (Sizing Guide)

一律加上 object-fit: contain; display: block; margin: 0 auto; 做置中。

為什麼要做這個

上游 Kami 的 slides-weasy 模板是為學術和編輯風格的簡報設計的：溫暖的羊皮紙背景、Charter serif、安靜的節奏。拿來做研究報告很完美，但拿來做企業 BD (Business Development; 商務開發) 的 pitch deck 就不對了——那種場景的觀眾期待的是現代、乾淨、sans-serif 的美感加上企業品牌識別。

CSS 變數 (WeasyPrint 安全)：

 1:root {
 2  /* Primary */
 3  --vz-teal: #00A896;        /* 主品牌強調色 */
 4  --vz-teal-dark: #007A6E;   /* 較深 teal，用於強調 */
 5  --vz-teal-deepest: #1A5E59;/* 最深 teal — 封面投影片背景 */
 6  
 7  /* Text */
 8  --vz-navy: #0F172A;        /* 主要文字（近黑） */
 9  --vz-slate: #475569;       /* 次要文字 */
10  --vz-muted: #6F7A88;       /* 低調文字 */
11  
12  /* Surface */
13  --vz-white: #ffffff;       /* 主背景 */
14  --vz-gray-light: #f8fafc;  /* 卡片背景 */
15  --vz-border: #e2e8f0;      /* 邊框和分隔線 */
16  
17  /* Semantic */
18  --vz-red: #C00000;         /* 風險、警告 */
19  --vz-green: #70AD47;       /* 成功、已驗證 */
20  --vz-orange: #ED7D31;      /* 注意 */
21  --vz-yellow: #FFC000;      /* 留意 */
22}

8 種投影片類型 (The 8 Slide Types)

所有投影片共享一個統一的 HTML 結構：

 1<section class="slide slide-{type}">
 2  <div class="slide-header">
 3    <span class="eyebrow">SECTION LABEL</span>
 4    <h2>Page Title</h2>
 5    <p class="lead">Subtitle</p>
 6  </div>
 7  <div class="slide-body">
 8    <!-- Type-specific content -->
 9  </div>
10  <div class="slide-footer">
11    <span class="confidential">Confidential. ...</span>
12    <span class="page-num"></span>
13  </div>
14</section>

觸發方式 (How to Trigger)

字型排版 (Typography)

CJK fallback：Microsoft JhengHei (TC)、Malgun Gothic (KR)、Noto Sans CJK。

WeasyPrint 適配 (WeasyPrint Adaptations)

因為 WeasyPrint 不是瀏覽器，某些 CSS 功能必須做適配：

封面投影片背景使用 --vz-teal-deepest (#1A5E59) 純色，而不是漸層。

8. 客製化延伸：codex-image Skill (Custom Extension: codex-image)

問題是什麼

beautiful-mermaid 和 mermaid-cli 畫出來的圖表都很精確，但看起來就像工具輸出——功能性夠、精準、但很素。如果你要做投資人 pitch deck 或研討會簡報，你會希望圖表看起來像設計師畫的：有個性、有視覺吸引力的 editorial illustration (編輯風格插圖)。

解法

codex-image skill 把 mermaid 程式碼（或自然語言描述）轉換成 editorial 風格的 16:9 PNG 圖片，使用 Codex CLI。底層是 Codex agent (gpt-5.4) 內部呼叫 imagegen/gpt-image-2 模型來渲染漂亮的插圖。

關鍵發現 (The Key Discovery)

讓這個東西跑起來的路徑其實不太直覺：

1. 直接用 -m gpt-image-2 會失敗 — gpt-image-2 模型在用 ChatGPT 帳號跑 Codex 時不支援。
2. 直接 API 呼叫會失敗 — 環境裡沒有 OPENAI_API_KEY（Codex 用 ChatGPT OAuth）。
3. 能用的方法：用預設模型的 codex exec，讓 Codex agent 內部自己呼叫 imagegen。這繞過了 350 字元的 API 限制，允許完整的 mermaid 程式碼（測試過最長 1,863 字元）作為輸入。

1# 這個會失敗：
2codex exec -m gpt-image-2 "draw a diagram"
3
4# 這個可以：
5codex exec "Redraw this Mermaid diagram as a clean 16:9 landscape diagram..."

6 種風格預設集 (The 6 Style Presets)

所有預設集共享一個公共前綴："Redraw this Mermaid diagram as a clean 16:9 landscape diagram (1536x1024)."

scripts/codex-image.sh

這支 546 行的 shell 腳本是執行引擎。主要功能：

1# 批次模式：處理目錄下所有 .mmd 檔案
2bash scripts/codex-image.sh mermaid_assets/deck-a/
3
4
5# 自訂風格 prompt
6bash scripts/codex-image.sh diagrams/ --style "neon cyberpunk, dark bg" --timeout 180
7
8# 加入額外上下文
9bash scripts/codex-image.sh flow.mmd --context "emphasise the JAK2 pathway"

內部運作方式：

1. 讀取 .mmd 檔案內容
2. 組合 prompt：style_prompt + mermaid_code + context
3. 呼叫 codex exec "$PROMPT" 並擷取 log
4. 用 UUID regex 從 log 中提取 session ID
5. 從 ~/.codex/generated_images/{sid}/ig_*.png 複製生成的圖片到輸出目錄

輸出： gpt-image-2 高品質 1536x1024 PNG，存到 {input_dir}/codex_generated/。

路由規則：codex-image vs. Kami Mermaid

兩者都處理 mermaid，但服務不同目的：

原則：codex-image 產出的是 AI 生成的概念插圖（editorial 風格）。Kami 產出的是程式化渲染的精確圖表。兩者互補，不是競爭。

9. 客製化延伸：kami_to_pptx 腳本 (Custom Extension: kami_to_pptx Scripts)

為什麼要獨立腳本

WeasyPrint (WP; 網頁轉 PDF 引擎) HTML-to-PDF 是 Kami 的預設輸出路徑。但有時候使用者就是需要一份可編輯的 PPTX 檔——要交給用 PowerPoint 的同事、要在會議前做最後調整、或者要符合公司的簡報模板要求。

python-pptx (PPT 生成套件) 可以用程式生成 PPTX 檔案，但原生 python-pptx 的輸出看起來就像空白投影片上自動生成的文字框。kami_to_pptx 腳本把完整的 Kami 設計系統帶進 PPTX 的世界。

kami_to_pptx.py（Kami 學術風格）

檔案大小： 1,534 行

這支腳本用 Kami 羊皮紙美學生成 PPTX 檔案：

設計常數：

1PARCHMENT  = RGBColor(0xf5, 0xf4, 0xed)  # 畫布背景
2IVORY      = RGBColor(0xfa, 0xf9, 0xf5)  # 卡片背景
3BRAND      = RGBColor(0x1B, 0x5F, 0xAA)  # 強調色（為螢幕調整過）
4NEAR_BLACK = RGBColor(0x14, 0x14, 0x13)  # 主要文字
5OLIVE      = RGBColor(0x50, 0x4e, 0x49)  # 第三層文字
6BORDER     = RGBColor(0xe8, 0xe6, 0xdc)  # 邊框
7SERIF      = "Charter"                     # 主字型

關鍵輔助函式：

檔案大小： 814 行

1WHITE       = RGBColor(0xff, 0xff, 0xff)  # 畫布背景
2VZ_TEAL     = RGBColor(0x00, 0xA8, 0x96)  # 主強調色
3VZ_NAVY     = RGBColor(0x0F, 0x17, 0x2A)  # 主要文字
4VZ_SLATE    = RGBColor(0x47, 0x55, 0x69)  # 次要文字
5VZ_TEAL_DEEP = RGBColor(0x1A, 0x5E, 0x59) # 深 teal，用於封面投影片
6SERIF       = "Inter"                       # 主字型（sans-serif）

使用時機 (When to Use)

10. 兩階段工作流 (Two-Stage Workflow)

Kami 生態系裡最強大的模式是兩階段工作流 (two-stage workflow)，結合快速結構迭代與高保真的視覺打磨。

階段 1：快速結構審查 (Stage 1: Quick Structure Review)

 1Markdown（含 mermaid 程式碼）
 2    |
 3    v
 4從 fenced code blocks 提取 .mmd 檔案
 5    |
 6    v
 7mermaid-cli 渲染每個 .mmd 為 PNG（快、精確）
 8    |
 9    v
10    |
11    v
12WeasyPrint 渲染成 PDF v1
13    |
14    v
15使用者審查結構和內容

目的： 在投入視覺打磨之前，先把內容和版面搞定。mermaid-cli PNG 功能上夠用但很素——拿來做結構審查完全足夠。

階段 2：漂亮的 Editorial 版本 (Stage 2: Beautiful Editorial Version)

 1    |
 2    v
 3Codex agent 生成 editorial PNG（每張 1536x1024）
 4    |
 5    v
 6用 codex editorial PNG 替換 mermaid-cli PNG
 7    |
 8    v
 9WeasyPrint 渲染成 PDF v2（另存新檔）
10    |
11    v
12使用者審查最終成品

目的： 把已驗證的結構轉化成簡報 ready 的文件，搭配 AI 生成的 editorial illustration (編輯風格插圖)。

完整流程圖 (The Full Sequence)

sequenceDiagram
    participant U as User
    participant C as Claude Agent
    participant MC as mermaid-cli
    participant WP as WeasyPrint
    participant CX as Codex (codex-image)

    U->>C: Markdown with mermaid code
    C->>C: Extract .mmd files
    
    rect rgb(245, 244, 237)
    Note over C,WP: Stage 1 - Structure Review
    C->>MC: Render .mmd to PNG
    MC-->>C: diagram PNGs
    C->>WP: Build HTML to PDF
    WP-->>C: pdf-v1.pdf
    C->>U: Review structure
    end

    U->>C: Structure approved

    rect rgb(0, 168, 150)
    Note over C,CX: Stage 2 - Editorial Polish
    CX-->>C: editorial PNGs (1536x1024)
    C->>C: Replace PNGs in template
    C->>WP: Build HTML to PDF
    WP-->>C: pdf-v2.pdf (saved separately)
    C->>U: Final output
    end

關鍵規則 (Key Rules)

1. v1 和 v2 共存 — 絕不用 v2 覆蓋 v1。兩者服務不同目的（審查 vs. 交付）。
2. .mmd 中間檔保留 — mermaid 原始碼檔案保留下來，確保可重現。
3. 階段 2 是選用的 — 如果 mermaid-cli PNG 已經夠用，就完全跳過 codex-image。
4. codex-image 輸出到獨立目錄 — {mmd_dir}/codex_generated/ 把 editorial PNG 和 mermaid-cli 輸出隔離。

兩階段完成後的檔案結構 (File Structure After Both Stages)

 1project/
 2├── content.md                    # 原始 markdown
 3├── mmd/                          # 提取出的 mermaid 原始碼
 4│   ├── slide-01.mmd
 5│   ├── slide-02.mmd
 6│   ├── slide-01.png              # mermaid-cli 輸出（階段 1）
 7│   ├── slide-02.png
 8│   └── codex_generated/          # codex-image 輸出（階段 2）
 9│       ├── slide-01.png
10│       └── slide-02.png
11├── output-v1.pdf                 # 階段 1（結構審查）
12└── output-v2.pdf                 # 階段 2（editorial 打磨）

11. 常見問題與疑難排解 (FAQ & Troubleshooting)

Q1: 我的 PDF 圖表有方塊和線條，但文字消失了

原因： 你直接嵌了 mermaid-cli 的 SVG。mermaid-cli 用 <foreignObject> (外部物件元素) 做文字，WeasyPrint 會忽略它。

解法： 渲染成 PNG 而不是 SVG：

1npx --yes @mermaid-js/mermaid-cli -i diagram.mmd -o diagram.png -b white -w 1600

或者改用 beautiful-mermaid SVG + mermaid_normalize.py。

Q2: 中文/韓文渲染成方塊或豆腐字

原因： CJK 字型沒有安裝。

解法：

1bash scripts/ensure-fonts.sh

中文的話，確認 TsangerJinKai02 在你的使用者字型目錄裡。韓文的話，確認 Source Han Serif K 已安裝。安裝字型後可能需要清除字型快取：

1fc-cache -fv

Q3: codex exec 逾時或沒有產出圖片

原因： 網路問題、Codex 驗證過期、或 prompt 太複雜。

解法：

1. 確認 Codex 正常運作：codex doctor
2. 檢查驗證：確認 ~/.codex/auth.json 有有效的 credentials
3. 先試一個簡單的 prompt 來隔離問題
4. 增加逾時時間：--timeout 300（預設是 300 秒）
5. 用 --retry 1 在失敗時自動重試

Q4: codex-image 無法提取 session ID

原因： Codex log 格式可能已經改變，或者圖片沒有生成。

解法： 腳本用 UUID regex 從 codex exec 的輸出中找 session ID。如果失敗了：

1. 手動檢查 ~/.codex/generated_images/ 裡最近的資料夾
2. 直接跑 codex exec 觀察輸出
3. 把 Codex CLI 更新到最新版本

Q5: WeasyPrint CSS 渲染結果跟瀏覽器預覽不一樣

原因： WeasyPrint 的 CSS 支援比瀏覽器受限。

常見陷阱和解法：

Q6: PPTX 投影片看起來像普通文字框

原因： 你用了基本的 python-pptx，沒有搭配設計系統輔助函式。

Q7: Mermaid SVG 文字在 kami PDF 裡隱形，但在瀏覽器裡看得到

原因： SVG 沒有經過 normalize。原始的 beautiful-mermaid SVG 可能包含 color-mix()、CSS 變數、或 Google Fonts import，WeasyPrint 處理不了這些。

解法：

1python3 scripts/mermaid_normalize.py raw.svg -o clean.svg
2# 驗證：
3python3 scripts/mermaid_normalize.py clean.svg --check

Q8: 我該用哪個簡報模板？

Q9: .pageformat 指令在 PDF 第一頁造成錯誤

原因： 語法不對。.pageformat {A4} 是錯的。

解法： 用具名參數語法：

1.pageformat size:{A4}

Q10: 怎麼使用列印（白紙）變體？

建置時加上 print variant 旗標。這會把背景從羊皮紙色翻轉成純白，適合辦公室或家用印表機。卡片和表格保留溫暖色調，所以層級感依然清晰。

12. 速查清單 (Quick Reference Checklist)

安裝清單 (Installation Checklist)

• 透過你的工具的 plugin 系統安裝 Kami（Claude Code / Codex / Claude Desktop / 通用）
• 跑 bash scripts/ensure-fonts.sh 安裝 CJK 字型
• （選用）建立 ~/.config/kami/brand.md，填入你的身份和預設值
• （選用）安裝 WeasyPrint：pip install weasyprint（或 uv pip install weasyprint）
• （選用）安裝 python-pptx：pip install python-pptx Pillow（for PPTX 輸出）
• （選用）安裝 mermaid-cli：npm install -g @mermaid-js/mermaid-cli（for 圖表渲染）
• （選用）驗證 Codex CLI：codex doctor（for codex-image skill）

文件類型選擇指南 (Document Type Selection Guide)

風格預設集選擇指南 (Style Preset Selection Guide - codex-image)

關鍵檔案位置 (Key File Locations)

建置指令 (Build Commands)

 1# 建置所有目標
 2python3 scripts/build.py
 3
 4# 快速驗證檢查
 5python3 scripts/build.py --check
 6
 7# 完整驗證
 8python3 scripts/build.py --verify
 9
10# Normalize mermaid SVG 以便嵌入 PDF
11python3 scripts/mermaid_normalize.py raw.svg -o clean.svg
12
13# 檢查 SVG 的 WeasyPrint 相容性
14python3 scripts/mermaid_normalize.py diagram.svg --check
15
16# 從 mermaid 生成 editorial 圖表
17bash scripts/codex-image.sh mermaid_assets/ --style editorial
18
19
20# 恢復缺失的字型
21bash scripts/ensure-fonts.sh
22
23# 跑測試
24python3 scripts/tests/test_build.py