docx-engine 完整使用教學：用 Claude Code 把想法變 Word 報告

日期：2026-05-01 Repo：github.com/latteouka/docx-engine

TL;DR

docx-engine 是一個宣告式 Word 文件生成引擎，你用 TypeScript 描述「這章要這段話、這邊要表格、那邊要圖」，引擎幫你套好台灣政府公文格式、自動編章節號、做目錄、轉 PDF、產散發版小檔。搭配 Claude Code 後，完全不會寫程式也能用——你跟 AI 說人話，它寫 TypeScript、跑指令、檢查排版。本文涵蓋安裝（Mac/Windows）、所有功能、以及如何把它調教成寫論文／會議紀錄／任何文件類型的引擎。

它解決的痛點

寫服務建議書、技術規格書、結案報告、論文這類有固定格式要求的長文件時，最浪費時間的不是內容，是：

章節編號手動維護（加一節整章重排）
圖目錄、表目錄、目錄頁碼對不準
字型、間距、頁邊距改一處要全文同步
換客戶／換用途要重做整套版型
DOCX 轉 PDF、壓縮散發版的零碎流程

docx-engine 把這些全部自動化。你只管內容。

誰適合用

寫投標文件（服務建議書、規格書、附錄）的人
寫結案報告、驗收報告的維護案 PM
寫論文、研究報告、會議紀錄的研究員／秘書
任何「同一份格式要重複用、內容會變」的文件作業
不會寫程式但會用 Claude Code 的人

能做到的事（功能全清單）

文件元素

元素	用途	自動化能力
`title`	大標題（封面）	套用 theme 樣式
`heading` (level 1-6)	章節標題	自動編號、自動進目錄
`body`	內文段落	首行縮排、字型、間距自動
`rich`	混合粗體/斜體/底線/顏色的段落	runs 陣列定義
`table`	表格	跨頁重複表頭、儲存格合併、背景色、嵌套元素
`image`	圖片	自動縮放、加 caption、自動進圖目錄
`list`	條列（bullet/decimal/letter）	階層、續編
`toc`	手動目錄	條目列出（頁碼 Word 自動填）
`figureIndex`	圖目錄	自動收錄全文有 caption 的圖
`tableIndex`	表目錄	自動收錄全文有 caption 的表
`faqIndex`	常見問題索引	連到對應章節 bookmark
`pageBreak`	強制換頁	—
`sectionBreak`	分節（重設頁碼、隱藏頁首頁尾）	封面不算頁碼、正文從 1 開始

編號風格（`numberingStyle`）

風格	Level 1	Level 2	Level 3	Level 4	Level 5
`chapter`（預設）	第一章	1.1	1.1.1	1.1.1.1	1.1.1.1.1
`government`	壹、	一、	（一）	1、	(1)
`decimal`	1.	1.1	1.1.1	1.1.1.1	a.

視覺風格（`theme`）

引擎內建三種 preset，可以整套切換或局部覆寫：

government — 政府公文風（寬鬆間距、無標題底線）
clean-report — 短報告風（緊湊間距、標題底線）
kymo-acceptance — 驗收／結案變體

也支援「preset + 局部覆寫」混用：

theme: {
  preset: 'clean-report',
  title: { borderColor: '2E74B5' },
  body: { spaceBefore: 60 },
}

Pipeline（一鍵全流程）

pnpm generate <案名>                          # 只產 DOCX
pnpm pipeline <案名>                          # DOCX → PDF（列印母本）
pnpm pipeline <案名> --compress               # 加散發版小檔（典型 6-15 MB）
pnpm pipeline <案名> --verify                 # 加拆頁 PNG 截圖供逐頁檢查
pnpm pipeline <案名> --compress --verify      # 全套（定稿前）
pnpm reverse <舊版.docx> <案名>               # DOCX 逆向解析為 TypeScript

其他特色

跨平台：macOS + Windows 都可（Word → PDF 在 Mac 用 AppleScript、Win 用 PowerShell）
輸出檔名範本：outputFilename: '114FA004_v2_{{timestamp}}' 自動替換為時間戳
元素標準化：裸圖片自動包成有說明的表格、圖片過大自動縮放、跳級 heading 印 warning
內建單元測試：pnpm test 跑 validate.test.ts / punctuation.test.ts 等

安裝（Mac + Windows，給 Claude Code 看的版本）

使用者請直接打開 Claude Code，把下面整段貼進去。Claude 會看你的作業系統，自動跑對應指令、遇到問題自動處理。你不用記任何指令。

我要安裝 docx-engine。我的作業系統是 <Mac / Windows>，請你：

1. 檢查是否已裝 Node.js（>= 18）和 pnpm，沒有的話幫我裝
   - Mac：用 brew install node，再 npm install -g pnpm
   - Windows：到 nodejs.org 下載 LTS 安裝，再用 PowerShell 跑 npm install -g pnpm
2. 確認我有 Microsoft Word（不是 LibreOffice 或 WPS），沒有的話請我先裝
3. 用 git clone https://github.com/latteouka/docx-engine.git 拉到 ~/projects（或我指定的位置）
4. cd 進去跑 pnpm install
5. （可選但推薦）裝壓縮和拆頁工具：
   - Mac：brew install ghostscript poppler
   - Windows：到 ghostscript.com 和 github.com/oschwartz10612/poppler-windows 下載安裝包，把 bin/ 加入 PATH
6. 跑 pnpm test 確認所有測試通過
7. 跑 pnpm generate test-basic 產一份測試文件，確認 projects/test-basic/output/ 出現 .docx
8. 用 Word 打開那份 .docx 確認可以正常開啟

每步做完報告結果。遇到任何錯誤訊息直接貼出來分析根因，不要猜。

Claude Code 會逐步執行，遇到錯誤會自己處理（permission、PATH、版本不符等都常見）。整個過程約 5-15 分鐘。

第一次使用：四個情境

情境 A：有舊版 DOCX，要參考做新版

我要做一份新的 <文件類型>。手上有去年類似案子的 ~/Desktop/舊版.docx，
幫我參考它的結構做一份新的，案名 <new-name>，丟到 projects/<new-name>/。
新案的特殊需求是 <列出與舊版差異>。

Claude 會：

跑 pnpm reverse 舊版.docx <new-name>-legacy
讀完逆向結果，整理結構備忘錄
用引擎標準格式重寫（逆向結果不會直接搬入——這是引擎的設計哲學）
一邊寫一邊跑 pnpm generate 確認零警告

情境 B：完全從零

我要開新案件 <new-name>，是一份 <文件類型>。從零開始，先問我要講什麼。

Claude 會複製 projects/_template-rfp/（或你指定的範本）並逐章問你內容。

情境 C：改一段話／加一章

把 <name> 第二章第三節的「我們有豐富經驗」改成具體的「累計承接 12 案、服務 50+ 機關」。

或

在 <name> 第 5 章後面加一章「災害復原計畫」，至少 3 個 SLA 表格。

情境 D：檢查 PDF 排版

跑 pipeline --verify 後，逐頁讀 PNG 圖檢查 <name>，找出空白頁、斷頭標題、圖片溢出。

Claude 會用 Read 工具一頁一頁讀截圖，挑出問題並修正。

怎麼客製化成「適合自己」的引擎

引擎的核心被刻意設計成「不要動」（避免你和上游維護者的修改衝突），但你可以無限擴充三個地方來客製：

1. 寫一份你領域的 `writing-guide`

引擎內建 writing-guides/rfp.md（投標公文風）。你可以新增：

writing-guides/thesis.md（論文用）
writing-guides/meeting-minutes.md（會議紀錄用）
writing-guides/research-report.md（研究報告用）

每份指引應包含：用詞語氣、章節結構規則、表格／圖片／引用的標準寫法、量化敘述規則、特定領域慣例。

跟 Claude 說「參考 writing-guides/rfp.md 的密度與結構，幫我寫一份論文版」，它會用 RFP 那份的寫法當骨架，內容換成論文領域的規範。

2. 建一個你領域的 `_template-*`

每個範本是一個資料夾骨架，包含：

projects/_template-thesis/
├── config.ts       # 預設 numberingStyle / theme / 字型 / 頁邊距
├── content/        # 章節骨架（每章一支 .ts，含占位提示）
├── lifecycle.md    # 該文件類型的生命週期（如：選題→初稿→審查→修訂→定稿）
└── assets/         # 空目錄

例：論文範本可能用 numberingStyle: 'decimal'、加 figureIndex 和 tableIndex、章節骨架是「摘要／緒論／文獻探討／方法／結果／討論／結論／參考文獻／附錄」。

開新論文時跟 Claude 說「複製 _template-thesis 開新案 my-thesis」即可。

3. 在自己的案件 `projects/<name>/` 裡為所欲為

config.ts 改字型／字級／頁邊距／頁首頁尾
content/ 裡用任何引擎元素自由排版
theme 用 preset + 局部覆寫做出該案的視覺特色
元素加 style: { ... } 做單點覆寫（這個標題要紅色、這段內文要置中等）

範例 — 自訂 theme 局部覆寫：

// config.ts
export const config: DocConfig = {
  numberingStyle: 'decimal',
  theme: {
    preset: 'clean-report',
    body: { fontSize: 24, spaceBefore: 80 },     // 12pt + 段前 4pt
    title: { borderColor: '003366', borderSize: 12 },
  },
}

工作流推薦：把流程包進 lifecycle.md

引擎附的 _template-rfp/lifecycle.md 把投標案拆成 8 步：

① 逆向需求 → ② 差距分析 → ③ 撰寫 → ④ PDF 驗證 → ⑤ 簡報 → ⑥ 定稿 → ⑦ 回流 → ⑧ 歸檔

每步寫清楚「該做什麼、需要使用者提供什麼」。Claude 進入新案件時先讀 lifecycle.md，知道走到哪步、下一步要問什麼資訊。

你可以為自己的文件類型寫一份：

論文：選題 → 文獻盤點 → 初稿 → 指導教授審 → 口委審 → 修訂 → 定稿 → 送印
會議紀錄：會前議程 → 開會錄音 → 整理逐字稿 → 寫紀錄 → 主管核 → 發送 → 歸檔
結案報告：契約對照 → 證據盤點 → 撰寫 → 送審會議 → 修訂 → 撥款追蹤

這樣每次開新案，Claude 自動走流程、自動問你該補的素材。

不要碰的邊界（重要）

如果你會跟著上游 git pull 拿更新（拿 bug 修復、新功能），下面這些檔案不要動，否則 pull 時會爆衝突：

engine.ts / types.ts / punctuation.ts / validate.ts
themes/ / reverse/
scripts/generate.ts / reverse.ts / pipeline.ts / verify.ts / word2pdf.*
CLAUDE.md / README.md / writing-guides/rfp.md
package.json / tsconfig.json / .gitignore

例外：你完全 fork 自用、不再 pull 上游了——隨便改。但建議至少前半年保留 pull 通道，因為這個引擎還在快速迭代。

想加新功能怎麼辦？

直接跟 Claude 說「我要改引擎做 XX，幫我走 PR 流程」。它會：

切新 branch（feat/xxx）
先寫測試（TDD）
改實作讓測試過
跑 pnpm test 全綠
實地產 DOCX 驗證
用 conventional commits 寫訊息
gh pr create 並完整填 PR template

維護者合併後，你下次 git pull 就有了，所有用這個引擎的人也一起受益。

進階：raw OOXML 風格控制

如果引擎內建元素不夠用（例如要做特殊的浮水印、複雜的多欄排版），有兩個出路：

用既有元素拼：絕大多數需求可以用 table + noBorder + 嵌套元素硬刻
發 PR 加新元素：先在 types.ts 加型別、engine.ts 加渲染、寫測試，再開 PR

不要在 projects/<name>/content/ 自己用 docx 套件 raw 寫 — 你會失去引擎標準化層的保護（背景色、字型一致性、編號連續性）。

品質驗證 SOP

定稿前一律跑：

pnpm pipeline <案名> --compress --verify

然後跟 Claude 說：

逐頁讀 projects/<案名>/output/verify/page-*.png，檢查：
- 異常換行、孤行、寡婦行
- 章節標題斷在頁尾
- 圖片超出邊界、解析度過低
- 表格跨頁時表頭沒重複
- 目錄頁碼是否對應內文（最容易出錯的地方）
- 圖目錄／表目錄條目齊全

把問題列清單給我，我來決定哪些要修。

Claude 用 Read 工具一頁一頁讀 PNG，列出所有問題。這是取代人眼校對的關鍵步驟。

常見問題

我完全不會寫 TypeScript，真的能用嗎？

真的。整套設計給 AI 寫程式、人寫內容。你只需要：

提供素材（舊版文件、人員清單、數據、圖片）
確認內容（「這段太口語」「這個數字錯了」）
開成品檢查

Word 開檔時跳「是否更新欄位」？

點「是」。這是目錄／圖目錄／表目錄自動填頁碼的機制。

散發版壓縮後畫質不夠？

預設用 Ghostscript /ebook 150 DPI（典型壓 85-90%）。畫質不足時改 /printer（300 DPI、約 15-25 MB）。跟 Claude 說「散發版改用 printer 等級」即可。

Mac 第一次跑會問「允許控制 Microsoft Word」？

點「好」。AppleScript 必經授權，一次就好。

我改了內容想重產

跟 Claude 說「重新生成 <案名>」或手動 pnpm generate <案名>。

想完全脫離上游自己魔改？

git remote remove origin、移到自己的 GitHub repo、用自己的 fork。代價是上游修 bug、加新元素時你要手動 cherry-pick。

學到的事

宣告式 + AI = 解放排版時間：人寫內容、AI 寫格式、引擎跑細節，三層分工讓「不會寫程式」不再是用 TypeScript 工具的障礙
逆向是提取素材，不是生成最終 content：舊文件給結構與論述策略當參考，但格式必須用引擎標準重寫——否則整份文件會風格不一
客製化集中在三個邊界：writing-guide（風格）、template（骨架）、project config（單案調整），引擎核心保持不動才能跟上游同步
lifecycle.md 是 AI 工作流的 spec：把文件類型的流程寫清楚，Claude 就能自己走、自己問該問的問題、不會漏步驟
拆頁 PNG 逐頁檢查取代人眼校對：定稿前的最後一道關卡，AI 讀截圖比人快也比人細

前文

把 AI 當新員工：用 Claude Code 打造「可重複、品質一致」的工作流 — 這篇 docx-engine 教學是該文舉的具體案例，看完工具再回去讀那篇會更有體感。

參考資料

docx-engine GitHub Repo — 原始碼與 Releases
Claude Code 官網 — AI 助手安裝
docx 套件 — 引擎底層用的 OOXML 生成函式庫
Ghostscript Releases — PDF 壓縮工具
poppler-windows — Windows 拆頁工具