前四天把「為什麼要做這件事」「手冊要長什麼樣」「產品與工具的軟硬需求」「為什麼選 Playwright」都講完了。今天在正式動手寫程式之前，先把整條產線的全景圖攤開來看。

需求

接下來的實作會一天處理一小塊 (e.g. 定位元件、狀態注入、截圖、標註、遮蔽，剩下的我再想想XD)。我覺得還是需要先有一個整體的大架構的感覺，才能比較清楚知道現在自己當下在整個產線的哪個階段或步驟，以及對應的目的是什麼。

以前我是會畫一個 roadmap 啦 (有興趣的讀者可以去看我去年和前年的文章XD)，但這次準備時間比較不充裕，整體架構還在滾動式調整中，等最後一天再看看要不要補上 roadmap，順便做回顧。

五個角色

整條產線可以拆成五個角色，彼此是獨立的，各有各自的功能：

1. manifest/*.yaml

   記錄所有「由人決定的細節」的設定檔，包含整本使用手冊的章節、順序、要標註的元件等。結構稍微複雜一些，後面會展開討論。

2. runner

   純粹的執行者，它會根據 manifest 依序執行操作、節圖、標註、輸出檔案。原則上是不做任何判斷，完全照著 manifest 的安排走。

3. docs/*.md

   手冊裡「給人讀的文字」，也就是每一章的操作說明、注意事項這些正文，初稿由 AI 生成，人再進去修。

   這裡要跟 manifest 分清楚：manifest 描述的是「機器要做什麼」(操作哪個元件、拍哪張圖、標註哪裡)，docs/*.md 放的是「讀者要看什麼」。兩邊的變動原因不太一樣，UI 流程改了要動 manifest，某句話講不清楚則是要動 docs。而且正文是長篇文字，塞進 YAML 裡之後要查看 git diff 會很難讀。

   另外，正文不是整份都給 AI 寫，像警語、法規聲明這類內容會圈成人工保護區，重新生成時不會被覆蓋掉，這部分後面會單獨講。正文跟截圖之間則是靠檔名約定綁在一起，不需要另外維護一份「哪張圖配哪段文字」的對照表，避免對照表過期。

4. templates/reference.docx

   Word 模板，跟內容完全分離。可以根據需求設定多個模板。

5. config.json

   與執行環境相關的設定，例如：App 路徑、輸出目錄、圖片寬度。

   跟 manifest 的分界線是這樣判斷的：換一台電腦、換一個人跑就得改的東西放 config.json，手冊內容本身要變才改的東西放 manifest。 所以 App 執行檔的路徑 (每台機器、每個 OS 都不一樣) 進 config，章節順序、要標註哪個按鈕進 manifest。

   分開還有一個好處是版控：config 是一人一份，通常只把 config.example.json 進版控，實際的 config 各自留在本機，才不會 A 的路徑蓋掉 B 的路徑。

這五個角色裡，只有第一個是需要人類去維護內容的。第三、四個雖然看起來也需要人類處理，但本質上都是「產物」。正文是 AI 生成加人工審核過的產物，排版模板是設計者產出、之後很少變動的產物。

將整條產線串起來

manifest、fixtures、config 三樣東西一起餵給 runner，runner 跑出截圖(含標註)，截圖再跟 docs 底下的正文合流，一起交給 pandoc 搭配排版模板，最後產出 word 檔與 PDF。

這裡第一次出現 pandoc，先簡單說明一下：它是一個文件格式轉換器，負責把 Markdown 轉成 docx / pdf，而 reference.docx 是餵給它的「樣式來源」，決定字體、標題樣式這些排版細節，跟內容完全分離。

至於為什麼是 pandoc？其實 Day 03 就已經把答案固定好了：當「要有 Word 檔」跟「正文要用純文字管理」同時成立，能選的工具就非常少。真正的替代方案不是換一個轉換器，而是放棄用 Markdown 當來源，改用 python-docx 這類套件直接把 docx 組出來，只是，那就等於連 git diff 的可讀性一起放棄了。

完整的用法會在後面的文章中展開討論。

對照到實際的資料夾結構，大致長這樣(細節可能會再調整，但整體架構不會變)：

auto-manual/
├── manifest/
│   └── demo-zhHant.yaml       # 唯一的人為真相來源
├── fixtures/
│   └── demo-data.json         # 固定假資料，讓畫面每次都長一樣
├── config.json                # App 路徑、輸出目錄等環境設定
├── docs/
│   ├── 10-overview.md
│   ├── 20-setting.md
│   └── ...
├── screenshots/
│   ├── overview-01.png
│   └── ...
├── templates/
│   └── reference.docx
├── runner/                    # 執行邏輯
└── output/
    ├── manual.docx
    └── manual.pdf

這裡也可以看到前面提過的命名約定：manifest 的章節 id、docs/ 的檔名、screenshots/ 的檔名前綴，三者是對齊的，細節等到後面設計 manifest 的時候再展開。

實際跑起來的感覺大致上會是：

1. 準備好 config (App 路徑要正確、執行環境要裝好)
2. 下一道指令
3. 依序跑過每一章
4. 等數分鐘 (視章節數量而定)
5. output/ 底下會新增排好版的 docx 與 pdf

今天沒有寫到任何一行程式碼，但把整條產線的架構展示出來了：五個角色各自負責什麼、資料怎麼流動、產物最後會落在哪裡。後面每一天的實作，基本上都是在填這張架構圖上的其中一格。

不過在開始填之前，還缺一個最基本的東西：一個可以拿來練習的對象。明天會介紹這系列示範用的 Electron App，一個刻意設計得「剛好夠難拍」的目標，讓後面每一天的實作都有真實的東西可以練習。