浮動式（floating） 是多數人熟悉的模式。視窗可以重疊、可以任意拖拉調整大小、可以最小化藏起來。macOS、Windows、GNOME、KDE 預設都是浮動式。操作直覺是「每個視窗是一張紙，自己決定放哪裡」。

平鋪式（tiling） 的規則不同：視窗自動排列填滿螢幕、不重疊，由 WM 的規則決定版面怎麼切割。開一個新視窗時，WM 自動把現有空間分一半給它；關掉一個視窗時，相鄰視窗自動擴展填補。操作直覺是「螢幕是一塊蛋糕，WM 負責切」。

多數平鋪式 WM 支援混合模式：特定視窗可以設為浮動，脫離平鋪規則。設定面板、密碼輸入框、小工具這類不適合塞進格子的視窗，通常會設成浮動例外。平鋪是預設，浮動是按需啟用的例外。

手動貼齊 vs 自動平鋪

在進入平鋪式 WM 之前，macOS 和 Windows 都提供了「手動貼齊」功能——用快捷鍵或拖拉把視窗貼到螢幕的半邊、角落、三分之一。macOS 原生的 window snapping、Windows 的 Snap Layout、以及 Rectangle 和 Magnet 這類第三方工具都屬於這個範疇。

手動貼齊跟自動平鋪的差距，在視窗數量少的時候幾乎感覺不到。開兩個視窗、左右各半，手動按一下快捷鍵就到位，完全夠用。

差距在視窗數量多的時候才出現。每開一個新視窗都要決定它放哪、按對應的快捷鍵；關掉一個視窗就留下空洞，要手動拖拉其他視窗去填——當這種版面管理的決策負擔開始分散你對工作本身的注意力時，就是自動平鋪開始有價值的時機。這個斷點因螢幕大小和工作類型而異：23 吋單螢幕上同時開終端機、編輯器、瀏覽器、文件，版面很快就不夠分；雙螢幕寬螢幕上同樣的視窗數量可能還很從容。

自動平鋪在這個情境下的優勢有三層。

第一層是自動回填。開視窗、關視窗，WM 自動重新分配空間，版面永遠是滿的、整齊的。你不用做任何版面決策。

第二層是操作對象的轉換。手動貼齊的操作對象是「某個視窗」——把 A 視窗貼到左邊、把 B 視窗貼到右上。平鋪式 WM 的操作對象是「版面結構」——把焦點往右移、把當前視窗跟隔壁交換、把這一格再水平切一半。你操作的是位置關係，不是絕對座標。

第三層是工作區整合。平鋪式工作流通常搭配多個工作區（workspace），每個工作區是一套獨立的平鋪佈局。「編輯器和終端機在工作區 1、瀏覽器在工作區 2、通訊軟體在工作區 4」——用快捷鍵瞬間切換整套上下文，而不是在一堆重疊視窗裡找。手動貼齊工具通常不帶工作區管理。

適用判讀

平鋪式視窗管理的投資報酬率取決於你的工作型態。

高回報情境：經常同時操作多個視窗且版面管理開始分散注意力、多數是「方方正正、可平鋪」的 app（終端機、編輯器、瀏覽器、文件閱讀器）、鍵盤操作為主、多螢幕、工作需要頻繁切換上下文（多個專案、不同任務區）。

低回報情境：大量使用需要特定比例或自由拖拉的 app（設計工具、影片剪輯、簡報製作）、很少同時開多個視窗、已經習慣且滿意目前的工作流、不想花時間學新鍵位。

折衷方案：所有平鋪式工具都支援 per-app 的浮動例外。不適合平鋪的 app（設定面板、計算機、某些對話框）設成浮動，其餘維持平鋪。這不是全有全無的選擇。

一個常見的踩坑模式是：看到 Hyprland 的截圖很漂亮，衝動裝了，發現日常有一半 app 不適合平鋪、鍵位記不住、每次更新都要修配置，兩週後放棄。務實的進入路徑是先在目前的系統上試手動貼齊工具（macOS 的 Rectangle 或 AeroSpace），確認自己真的享受鍵盤操作視窗的節奏，再往 Linux tiling WM 推進。或者用 VM 跑 Hyprland 體驗看看——體驗打折（VM 沒有 GPU 加速，動畫會卡），但能確認自己是否喜歡這種操作邏輯，再決定要不要花時間在實體機上搭建。

什麼是 Dotfile

Unix 系統用檔名開頭的 . 標記隱藏檔。shell 配置（.bashrc、.zshrc）、Git 設定（.gitconfig）、SSH 設定（.ssh/config）、以及 ~/.config/ 底下各種工具的配置目錄，都屬於這個範疇。這些檔案決定了你的工作環境怎麼運作：shell 的 prompt 長什麼樣、alias 有哪些、editor 用什麼 keymap、terminal 的配色方案、視窗管理器怎麼排列畫面。

「dotfile 管理」指的是把這些散落在家目錄各處的配置檔集中到一個 Git repo，建立版本歷史、可以跨機器同步、可以在新環境一鍵部署。跟手動備份的差異在於：備份是搬檔案，dotfile 管理是建立一套可重複執行的環境建構流程。

為什麼要管理 Dotfile

開發環境是累積出來的。今天加一個 alias、明天改一個 Git 設定、下週裝了一個 terminal 外掛調了字型。這些微調加起來就是「你順手的工作環境」，但因為都是零碎的小改動，很少有人會主動記錄。

問題在累積到一定程度後、環境需要重建的那一刻才會浮出來：

換機器。拿到新筆電，開始從零設定。裝完 shell、editor、terminal，發現少了一堆 alias 和 function，但想不起來之前到底加了哪些。花兩天勉強恢復到七八成，剩下的在未來幾週慢慢「撞到才發現少了」。

設備故障或遺失。公司配的筆電硬碟壞了。如果配置沒有外部副本，那台機器上所有的自訂設定（有些可能花了半年慢慢調出來的）全部歸零。復原速度直接取決於「你有沒有把配置存在機器以外的地方」。

在 VM 或容器裡重現環境。想在虛擬機裡測試一套 Linux 桌面（例如 Hyprland），或在 Docker 容器裡重現自己的 shell 環境做 CI 除錯。沒有版控的配置，就得手動複製貼上，還要記住哪些檔案在哪個路徑。

跨機器一致性。同時用筆電、桌機、遠端伺服器，希望每台機器的 shell 行為、Git 設定、editor 快捷鍵都一致。手動同步的成本隨機器數量線性增長，而且很容易漏改某一台，導致操作習慣在不同機器間不一致。

這些場景的共通點是：配置的價值在累積，但累積的前提是有記錄。沒有記錄的累積，只是暫存在某一台機器上的隱性知識，機器一換就歸零。

哪些東西應該建立 Dotfile

依配置的普遍性和適用場景，分成三層來判斷：

核心層：幾乎所有開發者都該管的

• Shell 配置（.zshrc / .bashrc）：alias、function、PATH、prompt、completion 設定。這是最高頻修改、也最容易累積隱性知識的地方。
• Git 配置（.gitconfig）：使用者名稱、email、預設 editor、alias（git lg = git log --oneline --graph）、diff/merge tool。
• SSH 配置（.ssh/config）：Host 別名、ProxyJump 跳板設定、每台主機的 IdentityFile 指定。注意：config 檔進 repo，私鑰不進 repo。
• Editor 配置：.vimrc（Vim）、~/.config/nvim/（Neovim）、VS Code 的 settings.json / keybindings.json。

工具層：依個人工具鏈而定

• Terminal multiplexer：tmux（.tmux.conf）、zellij（~/.config/zellij/）的面板配置、快捷鍵、狀態列。
• Terminal emulator：Alacritty、WezTerm、Kitty 的字型、配色、快捷鍵設定。
• 套件清單：macOS 的 Brewfile（brew bundle dump）、Arch 的 pacman -Qqe > pkglist.txt。這份清單讓新機器知道該裝哪些軟體。
• 開發工具的全域配置：.npmrc、.cargo/config.toml、.pypirc 等。但要注意區分：.eslintrc / .prettierrc 這類通常跟著專案 repo 走（每個專案可能規則不同），不跟著人走。

桌面層：Linux 桌面環境才需要

• Window manager：Hyprland（~/.config/hypr/）、i3（~/.config/i3/）、sway 的配置。
• 桌面元件：狀態列（waybar）、應用程式啟動器（rofi / wofi）、通知服務（mako / dunst）、鎖屏（swaylock / hyprlock）。
• 主題與配色：GTK / Qt 主題設定、游標主題、字型配置。

判讀準則

區分一個配置該不該進 dotfile repo，核心問題是：這個設定是跟著人走，還是跟著專案走？

跟著人走的（不管開哪個專案都要用的）→ 進 dotfile repo。跟著專案走的（專案 A 用 ESLint、專案 B 用 Biome）→ 留在專案 repo。

不該進 Dotfile Repo 的

• 私鑰、API key、token、密碼。用 .gitignore 排除，敏感資訊放 secret manager 或加密管理（具體做法見同步與 Secret 管理）。
• 暫存檔、cache、log。.zsh_history 很大且含敏感指令；各種工具的 cache 目錄是 generated 檔案，重建時自動產生。
• OS 層級的二進位設定。macOS 的 plist 可以選擇性管理（defaults write 指令可以版控），但整個 ~/Library/Preferences/ 不適合直接丟進 Git——檔案格式不穩定、diff 不可讀、很多是應用程式自動產生的。

概念位置

Reflection 三步：

1[Generate]    模型生成 v1
2   ↓
3[Critique]    模型（或 critic LLM）對 v1 給回饋
4   ↓
5[Refine]      模型按回饋生成 v2
6   ↓
7(可選 loop)

跟其他模式對照：

設計責任

讀 prompt engineering / agent paper 看到「reflection」「self-critique」「self-refine」「critic」就是這個機制。實作判讀：

1. 適用模型有能力辨識「自己寫的不夠好」、critique 跟 generator 不會共用同樣 blind spot。
2. 失敗在 systematic error：critique 跟 generator 是同個模型、訓練分佈中的盲點不會因為「再想一次」消失。判讀訊號：critique 每次給很像的建議、或修完還是同一類錯——換 critic 用不同 base model、或加外部驗證（test、lint、schema）取代 LLM critique。
3. 失敗在低能力模型：critic 能力不足、產不出有用建議、徒增 cost / latency。
4. 失敗在無限循環：沒有客觀停止訊號、reflection 一直跑、cost 爆掉。緩解：step cap + 外部 metric（test pass、schema valid）。
5. 失敗在過度修正：每次 reflection 都改一點、累積結果變糟（過度 fitting critic 意見）。緩解：保留 baseline、reflection 結果要跟 baseline 比、不一定採用。

Agent loop 是 reflection 的延伸特例、進階失敗模式見 4.4 Agent 架構。完整 workflow pattern 比較見 4.7 Workflow patterns。

失敗後先看什麼

失敗後第一步是定位 workflow 與 job。CI/CD 系統會把一次 push、pull request、tag 或 release 拆成多個 workflow，每個 workflow 下面又有多個 job；真正的下一步取決於是哪一層失敗。

Lint / format 失敗代表靜態契約沒有通過。常見情境是程式格式、文件格式、型別檢查、schema 或設定規則不符合規範。這類失敗的修復路徑通常很短：讀錯誤訊息、修正來源、必要時跑 formatter，再提交修正。

Test 失敗代表某個行為或契約沒有符合預期。這類失敗要先看 report、screenshot、trace、device log 或 error context，確認是功能真的回歸、測試假設過期，還是測試環境缺少 production-like artifact。直接改測試前，要先確認測試原本守的是哪個使用者或系統行為。

Build 失敗代表 pipeline 尚未產生可部署產物。這類失敗通常來自編譯錯誤、bundle 設定、依賴版本、環境變數、template 或資源路徑。修復時以專案定義的 production build 命令作為最小重現入口。

Deploy 失敗代表發布動作沒有完成。這類失敗需要先區分 artifact 是否存在、發布通道權限是否正確、環境保護是否放行。若測試與 build 已成功，deploy 失敗多半是發布通道問題；若 artifact 沒有產生，應回到 build 或 package 階段。

本機重現流程

本機重現的責任是讓修復建立在同一個驗證條件上。CI 是用乾淨環境執行的一組命令；只要能在本機跑出同樣的失敗，修復就能被快速驗證。

1make build
2make test
3make deploy-dry-run

Build 命令驗證 production artifact 是否能產生。這一步應該接近 CI 使用的 build 入口，避免開發模式遮蔽 production 問題。

Test 命令驗證產物或程式行為。前端可能是 browser test，後端可能是 integration / contract test，App 可能是 device test，Docker 可能是 image scan 或 smoke test。

Deploy dry-run 命令驗證發布前條件。高風險部署至少要能檢查 artifact、權限、環境與版本資訊；沒有 dry-run 的專案，也應保留對等的 preflight check。

修復與重新觸發

修復流程的核心是用新 commit 讓 CI 重新驗證。一般流程不需要刪掉失敗 commit，也不需要 force push；失敗 commit 留在歷史裡，後續 fix commit 會形成清楚的修復脈絡。

1. 讀失敗 job 的 log 或 artifact。
2. 在本機跑對應命令重現。
3. 修改最小必要範圍。
4. 跑同一條本機命令確認修復。
5. commit 並 push。
6. 等 GitHub Actions 重新跑。

這個流程的好處是保留可追溯性。日後再看到同類失敗，可以從 commit history 與 CI log 找到當時的判讀方式。

發布 gate 路由

發布 gate 的責任是把「是否進入下一階段」變成明確條件。這一頁只處理失敗後的操作路由；required checks、job needs、environment protection 與 artifact handoff 的設計原理，獨立放在 CI gate 與 workflow 邊界。

常見處理情境

CI 失敗但本機通過時，優先檢查環境差異。常見差異包括語言版本、套件管理器版本、缺少子模組、缺少 build artifact、測試依賴未安裝、時區或檔案大小寫差異。這類問題要把版本與建置前置條件寫進 workflow、Makefile 或 script，讓重現條件成為專案的一部分。

測試不穩定時，優先把 Flaky Test 狀態標出來並建立 owner。短期可以隔離或重跑，長期要找到不穩定來源，例如等待條件錯誤、外部網路依賴、時間假設、測試資料不穩或動畫 transition 尚未完成。測試不穩定會降低 gate 信任度，因此它本身就是需要治理的 CI 問題。

Deploy 失敗但測試通過時，優先看 artifact 與權限。若 build output 存在且可下載，問題通常在部署通道、token permission 或 environment protection；若 artifact 缺失，就回到 build job。

反模式與替代做法

反模式的共同問題是讓 CI 失去判讀價值。CI 的目標是讓綠燈代表「這次變更在定義好的條件下可發布」。

最小可用流程

最小可用流程是讓每次變更都有同一條路徑。對小型靜態網站或個人 blog，先做到以下四件事，就能形成穩定發布節奏。

1. push 或 PR 觸發 lint / test / build。
2. production build 有單一入口。
3. 測試失敗時保留 artifact 或 report。
4. deploy 只接受測試與 build 通過後的產物。

這套流程建立後，CI 紅燈就會成為清楚的路由訊號：哪一層壞、用哪個命令重現、修完後用哪個 gate 放行。

若變更涉及後端服務，可再對照 backend 知識卡的 Runbook、Rollback Strategy 與 Release Gate 進一步細化故障處理順序與放行條件。

下一步路由

• 需要理解 CI 在可靠性模組的位置：讀 6.1 CI pipeline。
• 需要看靜態站部署案例：讀 本 blog 專案部署。
• 需要理解 CI gate 設計：讀 CI gate 與 workflow 邊界。
• 需要理解發布阻擋策略：讀 6.8 Release Gate 與變更節奏。

Workflow 總覽

本專案目前有五條 workflow。三條屬於 CI / CD 主流程，兩條屬於 Claude 協作輔助流程。

這張表的責任是提供入口。看到 GitHub Actions 紅燈時，先對照 workflow 名稱，把失敗歸到內容檢查、瀏覽器測試、部署或協作流程。

md-check

md-check 的責任是讓 content/ 裡的 Markdown 維持同一套結構契約。它會先用 Go build 出 scripts/mdtools，再依序執行 formatter 檢查、lint 與卡片連結檢查。

1name: md-check
2on:
3  push:
4    branches: [main]
5  pull_request:
6    branches: [main]

這條 workflow 的核心步驟是：

1. actions/checkout@v6
2. actions/setup-go@v6
3. go build -o ../../bin/mdtools
4. ./bin/mdtools fmt --check content/
5. ./bin/mdtools lint content/
6. ./bin/mdtools cards content/

md-check 失敗時，下一步是回本機跑同一組命令。fmt --check 失敗代表格式可由 fmt --fix 修正；lint 失敗代表標題、front matter、URL、code block 等結構契約不符；cards 失敗代表卡片連結、orphan 或 K4 規則需要修。

1./bin/mdtools fmt --check content/
2./bin/mdtools lint content/
3./bin/mdtools cards content/

維護這條 workflow 時，規則來源要和 Blog Markdown 寫作規範與 mdtools 檢查 對齊。改 scripts/mdtools/internal/rules/ 時，也要同步更新規範文章，避免 CI 行為和文件描述分叉。

Playwright tests

Playwright tests 的責任是驗證使用者可見行為。它會先建出完整 Hugo site 與 Pagefind index，再用 Chromium 驗證搜尋、版面與互動。

1name: Playwright tests
2on:
3  push:
4    branches: [main]
5  pull_request:
6    branches: [main]

這條 workflow 的核心步驟是：

1. checkout，並包含 submodules
2. 安裝 Hugo 0.148.2 extended
3. 安裝 Node 24
4. npm ci
5. npx playwright install --with-deps chromium
6. make site
7. npx playwright test
8. 失敗時上傳 playwright-report/

make site 是這條 workflow 的關鍵前置條件。它會產生 Hugo 靜態檔與三份 Pagefind index：pagefind、pagefind-title、pagefind-content。如果只跑 hugo --minify 就跑 Playwright，搜尋測試會因為缺少 index 而失敗。

Playwright 失敗時，下一步是下載 playwright-report 或讀 error context。若失敗發生在搜尋頁，先確認 make site 是否完整成功；若失敗發生在版面，先看 screenshot、bounding box 或 computed style；若失敗發生在互動，先看 selector 是否仍對準真實 DOM。

1make site
2npm test

維護這條 workflow 時，測試要守使用者行為，不應只守 implementation detail。像 TOC RWD 這類版面行為，可以用 viewport 測試固定桌面、筆電與手機三種狀態。

Deploy Hugo site to Pages

Deploy Hugo site to Pages 的責任是把 main 上的內容建置成 GitHub Pages artifact 並部署。它只在 push 到 main 時觸發，不在 pull request 上部署。

1name: Deploy Hugo site to Pages
2on:
3  push:
4    branches:
5      - main

這條 workflow 有兩個 job：

build job 會先跑 hugo --minify，並把輸出寫到 hugo-build-output.txt。目前它設了 continue-on-error: true，所以 Hugo build 失敗時會進入 Claude Debug 步驟，嘗試讓 Claude 分析錯誤並 commit 修復。

Fail if build was not fixed 是第二道保護。若原本 Hugo build 失敗，workflow 會重新跑一次 hugo --minify；如果 Claude 沒修好，這一步會讓 workflow 停止。

Pagefind index 會在 Hugo build 後產生：

1npx -y pagefind --site public --root-selector main
2npx -y pagefind --site public --root-selector "article.article-content > h1" --output-subdir pagefind-title
3npx -y pagefind --site public --root-selector ".article-body" --output-subdir pagefind-content

Deploy 失敗時，下一步先分層判讀。若 build job 失敗，回到 Hugo 或 Pagefind；若 Upload artifact 成功但 deploy job 失敗，檢查 Pages environment、permission、artifact 與 GitHub Pages 設定。

這條 workflow 目前的注意事項是：deploy workflow 自己沒有直接 needs md-check 或 Playwright tests，因為它們是獨立 workflow。這是本專案目前的實際邊界；gate 設計原理見 CI gate 與 workflow 邊界。

Claude Code

Claude Code 的責任是提供互動式 Claude 協作入口。它不會在每次 push 自動修程式，而是在 issue、comment 或 review 內容包含 @claude 時觸發。

1on:
2  issue_comment:
3    types: [created]
4  pull_request_review_comment:
5    types: [created]
6  issues:
7    types: [opened, assigned]
8  pull_request_review:
9    types: [submitted]

這條 workflow 的 gate 寫在 job if。只有以下情境會真正執行：

• issue comment 包含 @claude
• pull request review comment 包含 @claude
• pull request review body 包含 @claude
• issue title 或 body 包含 @claude

這條 workflow 給 Claude actions: read 權限，讓它能讀 PR 上的 CI 結果。這對「請 Claude 看 CI 為什麼失敗」很重要，因為 Claude 需要讀 workflow run、job log 或 check 結果才能判斷。

維護這條 workflow 時，重點是權限最小化。它目前給的是 contents: read、pull-requests: read、issues: read、id-token: write、actions: read，適合互動分析；若未來要讓 Claude 直接 commit，才需要重新評估寫入權限與保護條件。

Claude Code Review

Claude Code Review 的責任是在 PR 事件發生時跑 Claude code review。它和 Claude Code 不同，前者是 PR review automation，後者是被 @claude 叫起來的互動入口。

1on:
2  pull_request:
3    types: [opened, synchronize, ready_for_review, reopened]

這條 workflow 使用 code-review@claude-code-plugins，prompt 是：

1/code-review:code-review ${{ github.repository }}/pull/${{ github.event.pull_request.number }}

它的責任是提供 review 視角。Claude review 可以指出風險、邏輯問題或測試缺口；真正阻擋合併與發布的責任仍在 Required Checks、測試 workflow 與 deploy gate。

維護這條 workflow 時，可以依 PR 類型決定是否加 path filter。若未來只想在程式碼或 workflow 變更時觸發，可打開 paths 設定；若希望文章內容也被 review，就維持目前全 PR 觸發。

本專案的發布阻擋邊界

本 blog 的發布阻擋邊界需要同時看 YAML 與 GitHub repository 設定。這一節只記錄本專案目前能從 YAML 判讀出的事實；required checks、environment protection 與 artifact handoff 的原理不在本頁展開。

目前從 YAML 可直接確認的阻擋關係是：

若日後發現測試紅燈但 Pages 仍發布，本頁只負責指出目前 workflow 邊界；具體改法回到 CI gate 與 workflow 邊界 判斷，並對照 Required Checks 與 Environment Protection。

失敗時的維護路由

失敗時的維護路由要先定位 workflow，再定位 job，再回到本機重現。這能避免在錯誤層修錯問題。

這份路由也可以當維護 checklist。新增 workflow 時，至少要補三件事：觸發條件、失敗時看哪個 artifact 或 log、本機要用哪條命令重現。

本專案維護注意事項

本專案維護注意事項的責任是記錄和目前 YAML 直接相關的操作提醒。這些提醒隨 workflow 實作改變而更新，不承擔通用 CI 設計原理。

• Playwright tests 依賴 make site 產生 Pagefind index；搜尋測試失敗時先確認 production build 是否完整。
• deploy.yml 的 Hugo build 使用 continue-on-error: true，後面用 Claude Debug 與 retry build 接住失敗。
• Claude Code 目前是 read-oriented 互動入口；若未來要寫入 repo，需要重新審核 permission。
• .github/workflows/*.yml 有實作變更時，要同步更新本頁，讓維護入口維持可信。

下一步路由

• CI 紅燈處理流程：讀 CI 失敗到修復發布流程。
• CI gate 設計原理：讀 CI gate 與 workflow 邊界。
• CI 在可靠性模組的位置：讀 6.1 CI pipeline。
• 發布 gate 設計：讀 6.8 Release Gate 與變更節奏。
• Markdown 檢查規則：讀 Blog Markdown 寫作規範與 mdtools 檢查。

共用的核心原則

• 宣告式：描述「環境應該長什麼樣」，而非「操作了哪些步驟」。Terraform 宣告「要有一個 VPC、CIDR 是 10.0.0.0/16」；dotfile 宣告「zsh 的 prompt 格式是這樣、alias ll 對應 ls -la」。
• 版控下的變更歷史：誰改了什麼、什麼時候改的、為什麼改，都在 Git log 裡。環境出問題時可以回溯到「上一次正常的狀態」是哪個 commit。
• 可 review：改了一個 shell function，diff 清楚可讀。跟在 terminal 裡直接 export 一個變數、下次重開就忘了相比，版控下的改動有跡可循。

差異

這個平行不只是比喻。從個人到團隊會教怎麼把 dotfile 的思想正式擴展到團隊環境——devcontainer 把「開發環境應該長什麼樣」寫成宣告式配置，讓新人 clone repo 就能拿到一致的開發環境，這正是 IaC 思想從組織 infra 往個人工作桌面延伸的具體產物。

Dotfile 是重建指令，不是備份

這是最重要的心智模型區分。Dotfile repo 的目標不是「把舊電腦的所有檔案搬到新電腦」（那是備份工具的工作），而是「一份能在空白機器上重建工作環境的指令集」。

這個思維跟 Docker 的哲學一致：Docker image 透過 Dockerfile「描述如何重建」環境，而不是「對一台跑著的伺服器拍快照」。Dotfile repo 也是——它記錄的是「你的環境應該長什麼樣」的宣告，不是「你的機器上現在有什麼」的快照。

這個區分決定了 repo 裡該放什麼：

• 放進去的：宣告式的配置檔（shell config、editor config、WM config）、套件清單（Brewfile、pacman list）、安裝腳本（install.sh，用來在新機器上自動化部署流程）。
• 不放的：暫存狀態（shell history、undo file、session file）、generated 產物（plugin 的 compiled cache）、大型二進位檔（字型檔案可以用套件管理器裝，不用放 repo）。

維持「重建指令」的純度，repo 才能保持輕量、diff 可讀、跨機器部署不會帶進不必要的狀態。

SSH key 是典型例子：管理工具和 shell 配置的知識在模組一和模組二，但實際操作時 SSH key 比這兩者都早——因為 git clone git@github.com:... 本身就需要 SSH key。如果照模組順序走，到模組二才發現 dotfile repo clone 不下來。

這篇是路線圖，告訴你每一步做什麼、為什麼這個順序、以及去哪個模組看具體操作。

階段一：基礎設施（後續所有步驟的前提）

這些步驟在任何配置之前完成，因為它們是 Git、遠端存取、dotfile clone 的前提。

1. 安裝作業系統 + 建立使用者帳號

macOS：開箱即用。Linux：選發行版（Arch 如果要用 Hyprland）、完成安裝、建立非 root 使用者。安裝程式每個選項該怎麼判讀、裝完最小系統缺哪些必要工具（連 sudo 都可能沒有），見 Linux 安裝選項判讀 與 最小安裝後的工具驗證與補足——這一步是整個系列展開最深、卻最常被一句帶過的地基。

2. 生成 SSH key pair

1ssh-keygen -t ed25519 -C "your-email@example.com"

為什麼這麼早做：

• Git 操作：GitHub / GitLab 的 SSH 認證需要 public key。dotfile repo 通常用 SSH URL（git@github.com:...），clone 前要先把 key 部署到 GitHub。用 HTTPS URL 可以繞過 SSH key，但長期來看 SSH key 是更省事的認證方式。還沒有 key、或想用 HTTPS / PAT 把 dotfile 弄進一台新機器的幾種路徑，見 外部連入、SSH key 與無 key 的 bootstrap 路徑。
• 遠端救援：模組七的場景三（GPU hang）依賴 SSH 作為桌面凍結時的救生通道。key 提前設好，出問題時才有路可走。
• 跨機器操作：筆電連桌機、桌機連 VM、VS Code Remote SSH——都靠這把 key。

3. 部署 public key

把 ~/.ssh/id_ed25519.pub 加到需要的服務：

1# 加到 GitHub
2cat ~/.ssh/id_ed25519.pub
3# 複製輸出，貼到 GitHub → Settings → SSH and GPG keys → New SSH key
4
5# 加到另一台機器（可選，用於跨機器 SSH）
6ssh-copy-id user@target-machine

4. Package manager + Git

macOS：先裝 Homebrew（macOS 的套件管理器，後續安裝 stow、tmux 等工具都靠它），再裝 Git：

1# 安裝 Homebrew
2/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
3
4# 安裝 Git（或用 xcode-select --install，會一併裝 Apple 的 Git）
5brew install git

Arch：pacman 隨 OS 安裝已可用，直接裝 Git：pacman -S git。

5. Clone dotfile repo

1git clone git@github.com:yourname/dotfiles.git ~/dotfiles

如果是第一次建 dotfile repo（還沒有 repo），先建一個空的再開始往裡面加配置。具體做法見模組一：管理工具與目錄結構。

階段二：Shell 與終端機（日常操作的基礎）

Shell 是所有操作的介面，終端機是 shell 的容器。這兩層配置好，後續的安裝、設定、除錯效率會高很多。

6. 安裝管理工具（stow / chezmoi）

把 dotfile repo 裡的配置 symlink 到正確位置。具體選型和操作見模組一。

7. Shell 配置（.zshrc / .bashrc）

模組化拆分、PATH 設定、alias、prompt。做完這一步，終端機操作才順手。見模組二：Shell 配置。

8. 終端機 + 編輯器

Terminal emulator 選型、tmux/zellij、neovim 基礎配置。見模組三：終端機與編輯器。

macOS 用戶到階段二完成後就有一個完整的工作環境。下一步依序讀模組一（管理工具選型）、模組二（shell 配置）、模組三（終端機），然後跳到階段四的 bootstrap script。階段三是 Linux 桌面環境的設定，macOS 用戶跳過。

階段三：桌面環境（Linux 限定）

macOS 用戶到階段二就有一個完整的工作環境了。以下步驟是 Linux 桌面環境的設定，macOS 用戶可以跳到階段四。

9. 視窗管理器

平鋪式 vs 浮動式的選型，Hyprland 安裝和核心配置。見模組四和模組五。

10. 桌面配套工具 + Rice

waybar、wofi、mako、配色系統。見模組六：桌面 Rice 設計。

11. 啟用 SSH server + 預防措施

桌面環境可用之後，設定遠端救援通道和預防性配置：

 1# SSH server（出問題時可以從另一台機器救援）
 2sudo systemctl enable sshd
 3sudo systemctl start sshd
 4
 5# 停用密碼登入（確保 SSH key 已設好）
 6# 編輯 /etc/ssh/sshd_config：PasswordAuthentication no
 7
 8# swap（OOM 緩衝）
 9sudo fallocate -l 4G /swapfile
10sudo chmod 600 /swapfile && sudo mkswap /swapfile && sudo swapon /swapfile
11
12# systemd-oomd
13sudo systemctl enable systemd-oomd

為什麼放在桌面設定之後：SSH server 和 swap 是預防措施，桌面能用了才有東西要保護。但 SSH key pair（階段一步驟 2-3）要提前做——key pair 是認證基礎設施，server 只是把門打開。

詳細的故障場景和預防措施見模組七：桌面環境維護與故障排除。

階段四：同步與可攜性

環境建好之後，確保這份配置能搬到下一台機器。

12. Bootstrap script

把階段一到三的操作自動化成 script，下次換機器跑一次就好。見模組八：同步、Bootstrap 與環境重建。

13. Secret 管理

哪些東西該進 repo、哪些要排除（SSH private key、API token、密碼）。同樣見模組八。

依賴關係速查

 1OS 安裝
 2  └─ SSH key pair ← 後續所有 Git / SSH 操作的前提
 3       └─ Git 安裝
 4            └─ dotfile repo clone
 5                 └─ 管理工具（stow link）
 6                      ├─ Shell 配置
 7                      ├─ 終端機 + 編輯器
 8                      └─ 桌面環境（Linux，macOS 到此為止 → 直接跳階段四）
 9                           └─ SSH server + 預防措施
10                                └─ Bootstrap script 自動化

可以亂序的步驟

依賴圖裡同一層級的步驟可以調換順序。具體來說：

• Shell 配置、終端機配置、編輯器配置三者互不依賴，先做哪個都行
• 視窗管理器和桌面配套工具可以交替設定（先裝 Hyprland 再裝 waybar，或反過來）
• swap 和 SSH server 互不依賴，先做哪個都行

跨層級的依賴必須按順序：SSH key 是 clone repo 的前提，repo 是 stow link 的前提，stow link 是 shell 配置生效的前提。

Gate 形式

Gate 形式要依控制範圍選擇。PR 合併、job 執行順序、production 發布與 artifact 傳遞是四種不同責任，混在一起會讓紅燈的意義變模糊。

Required checks 適合保護主線。它讓測試結果成為合併條件，避免紅燈變更進入 main 或 release branch（backend 延伸見 CI Pipeline）。

Job needs 適合同一條 workflow 內的發布管線。它讓 deploy 必須等 test、build 或 package 成功後才執行，避免 deploy job 先於驗證結果流動（platform 延伸見 Deployment Contract）。

Environment protection 適合正式環境。即使 build 與測試通過，production 或其他目標環境仍可要求人工審核、特定分支或特定 reviewer 才能部署（治理延伸見 Release Gate）。

Artifact handoff 適合避免「測試一份、發布另一份」的漂移。較嚴謹的流程會讓 build job 產生 artifact，test job 驗證這份 artifact，deploy job 發布同一份 artifact（供應鏈延伸見 Artifact Provenance）。

Workflow 邊界

Workflow 邊界的責任是決定哪些步驟共享同一條執行圖。放在同一條 workflow 裡的 job 可以用 needs 建立顯式依賴；分散在不同 workflow 裡的流程，通常要靠 branch protection 或 environment protection 建立跨 workflow gate。

多 workflow 的關鍵風險是順序假設。GitHub Actions 的 workflow 彼此獨立；跨 workflow 順序需要靠 repository 設定或 API 顯式串接。

發布阻擋判讀

發布阻擋要同時看 YAML 與 GitHub repository 設定。YAML 說明 workflow 或 job 如何執行；跨 workflow 的「測試通過才發布」通常要靠 Branch Protection、required status checks 或 environment protection。

這個判讀順序能避免錯修。若測試紅燈但目標環境仍發布，問題通常在 deploy gate 尚未把測試狀態納入發布條件。

常見反模式

反模式的共同問題是讓 CI 綠燈與發布安全之間失去因果關係。CI 的目標是讓綠燈代表「這次變更在定義好的條件下可進下一階段」。

Tripwire

Tripwire 的責任是提示什麼時候 workflow 結構需要重切，讓團隊從局部 patch 回到 gate 設計。

• 測試紅燈仍發布：把 deploy gate 顯式化，使用 required checks 或同 workflow needs。
• 本機常常重現不出 CI：把命令收斂到 Makefile 或 npm scripts，減少 workflow 專屬命令。
• 測試常因 artifact 缺失失敗：建立 artifact handoff，讓測試與發布使用同一份產物。
• workflow 說明與實作分叉：同步更新 workflow 文件與 YAML，讓維護入口保持可信。

下一步路由

• CI 紅燈處理流程：讀 CI 失敗到修復發布流程。
• 靜態站部署案例：讀 本 blog 專案部署。
• 可靠性層的 release gate：讀 6.8 Release Gate 與變更節奏。

dotfile 管理解決的核心問題是環境可重現性。一台新機器、一次重灌、一個 VM，都應該能用一份 Git repo 還原成你熟悉的工作環境。不做管理的代價是：每次換機器都在重新手動設定，每次都少記一兩個東西，每次都花一兩天才回到順手的狀態。

和其他系列的關係

Infra 教「組織的地基怎麼用 code 管理」，Dotfile 教「個人的工作桌面怎麼用 code 管理」。模組九把兩者接起來——當個人 dotfile 的思想擴展到團隊，就是 devcontainer 和標準化開發環境。

地基：機器初始化

編號模組都假設你已經有一台裝好 Linux、工具齊全、能從外部連入的機器。Linux 安裝與機器初始化 補的是那段被預設跳過的地基——OS 安裝選項怎麼判讀、最小系統缺哪些必要工具、怎麼連進去跑 bootstrap（含還沒有 SSH key 的情況），以及怎麼讓安裝腳本在失敗時可診斷。只要你換到全新環境（開 VM、租雲端主機、拿到空機器），就會先撞上這層。內容來自一次完整的 VM 實測，蒸餾成不綁特定發行版的判讀與決策。

教學模組

模組編號反映學習路徑：先理解為什麼、再學怎麼管理、然後逐層處理 shell/終端機/視窗管理/視覺客製化，最後談維護排錯、同步可攜性和團隊化。模組四到七是 Linux 桌面環境的深度實作，之後會搭配 VM 專案做 hands-on 實測。

VM 實測專案

模組四到七的 Linux 桌面配置會搭配一個獨立的 VM 專案做 hands-on 實測（類似 Monitoring 系列搭配 monitor 專案的關係）。教材負責概念與配置邏輯的說明，VM 專案負責實際安裝、調教、截圖驗證。VM 專案會在教材完成後另外建立。

章節文章

macOS 讀者的主線是前兩篇（浮動 vs 平鋪、macOS 工具鏈）。Linux Tiling WM 生態和 Wayland 顯示協議是想在 VM 或實機上體驗 Linux 桌面的選讀——macOS 上用 AeroSpace 或 yabai 的讀者可以直接跳到同步與 Bootstrap。

跨分類引用

• → 模組五：Hyprland 配置：Hyprland 的完整配置實務
• → 模組六：桌面 Rice 設計：compositor 之上的狀態列、啟動器、通知、配色系統
• → 模組一：管理工具與目錄結構：WM 配置怎麼進 dotfile repo
• → 模組八：同步、Bootstrap 與環境重建：跨機器搬移時硬體相關設定怎麼處理

本章寫的是這四種模式的本質、它們的失敗模式、彼此組合的方式、何時退化成 single call 更好。具體 framework 的 DAG syntax / workflow API 不在本章——這些跨 framework 差異大、半年一變、原理層級更穩。

本章目標

讀完本章後你能：

1. 區分四種基本 workflow 模式。
2. 看到一個 LLM application 時、能畫出它的 workflow 結構圖。
3. 判斷一個 workflow 是否該退化成 single call。
4. 識別 workflow 設計常見的反模式。

LLM 應用的本質是多 Call 組合

單一 LLM call 解的問題有上限：

• Context 限制：再大的 context window 也有上限、長文件得切。
• 推理深度：複雜推理拆步驟通常比一次推完更穩。
• Tool 範圍：multi-step tool use 需要多次 call 串起來。
• 多面向評估：同時要管邏輯、風格、合規時、單次 call 容易偏其中一面。

Multi-call 組合擴展能力範圍、代價是每多一個 call 多一份成本：

• Latency：N 個 call sequential 跑是 N 倍 latency；parallel 跑也至少要 max(call latency)。
• Cost：每個 call 的 token 成本累加、N 個 call 是 N 倍 cost。
• 失敗點：每個 call 都可能失敗、N 個 call 串起來成功率是個別成功率連乘。
• 複雜度：error handling、retry、partial success 處理複雜度爆炸。

「設計 workflow」的核心問題不是「能不能拆成多 call」、是「拆成多 call 的收益值不值得這份成本」。Workflow 設計常見的失敗是過早優化（software engineering idiom：「premature optimization is the root of all evil」、在沒有 profiling 證據前就拆結構、複雜度爆炸但無實質改進）、把簡單問題切成複雜 DAG（directed acyclic graph、有向無環圖、描述步驟依賴關係的資料結構）、最終比 single call 慢、貴、難維護、品質卻沒提升。Single call 在「context 塞得下 + 任務不需要外部 tool + 失敗代價低」的情境下仍是最高 ROI 選項。

四種基本模式各自解不同的「為什麼需要多 call」、下面逐個展開。

Pipeline：線性串接

結構：call_1 → call_2 → call_3 → ...、後一個 call 用前一個的 output 當 input。

適合場景：

• 任務有清楚的線性子步驟（萃取 → 摘要 → 翻譯、或 plan → execute → review）。
• 每個子步驟用同個模型最划算（一個 call 撐不下、拆成幾個 call 接力）。
• 子步驟輸出需要中間驗證 / 處理（前一步先過 schema 解析、再餵下一步）。

典型例子：

• Code review pipeline：先 LLM 找問題列表 → 再 LLM 對每個問題寫修改建議 → 最後 LLM 合成 summary。
• 文件處理：原文 → 萃取結構化資訊 → 套用 template → 輸出最終格式。

失敗模式：

• 中間步驟誤差累積：第一步小錯、第二步基於錯誤輸出、第三步累積到完全跑偏。整體錯誤率是個別錯誤率連乘的補集（任一步錯整個 pipeline 錯）。
• 無法檢測前段錯誤：後段沒辦法回頭修正前段、即使發現結果不對。
• 過度拆解：本來 single call 能處理的事拆成 3 步、latency 跟 cost 都暴增。

緩解策略：

• 中間步驟加 validation（schema 解析、簡單 sanity check）、catch 早期錯誤。
• 關鍵 pipeline 加 logging、出問題時能定位是哪一步壞。
• 定期重新評估「這個 pipeline 真的需要拆嗎」、不需要就合併回 single call。

Router：依輸入分流

結構：input → classifier → path A / B / C → output、依分類結果走不同處理路徑。

適合場景：

• 輸入類型多樣、不同類型需要不同處理（簡單 query 用小模型、複雜 query 用大模型）。
• Cost 優化（多數簡單請求走便宜 path、少數複雜請求走貴 path）。
• 功能分流（query 是 search、summarization、還是 code edit）。

典型例子：

• 客服分流：先判斷使用者意圖（查訂單 / 退貨 / 一般諮詢）、再分到對應 specialized agent。
• 模型分流：先 1B classifier 判斷複雜度、簡單問題給本地 14B、複雜問題給雲端旗艦。

失敗模式：

• Classifier 錯判：分流錯了、整個 query 跑進最差 path、結果完全不對。
• Classifier 比下游還複雜：本來 router 是 cost saver、結果 classifier 本身就要強模型、變成多花錢的繞路。
• Path 設計不完整：有些 query 不符合任何 path、router 強塞到某個 path、結果差。

Classifier 設計常用 structured output 強制輸出 enum、避免 free-form 解析；複雜應用可能把 classifier 本身做成 tool use 的特例。

緩解策略：

• Classifier 用較弱模型但加 confidence 判讀、低 confidence 走 fallback path。
• 簡化 path 數量（3-5 個內、保留必要切分即可）。
• 設計「unknown / catch-all」path、不假設所有 input 都能歸類。

Parallel：多 Call 並行、結果合併

結構：input → [call A, call B, call C 並行跑] → 合併 → output、多次 LLM call 同時跑、結果合起來。

適合場景：

• 任務有獨立面向（評估一份 PR 的程式碼品質 / 安全性 / 可讀性、各自一個 call）。
• Ensemble（同個任務跑多次、用 majority vote 提高可靠度）。
• Multi-source retrieval（從不同來源平行拉資料、合起來餵下游）。

典型例子：

• 多面向審查：同份 code 同時跑「邏輯」「風格」「安全」三個 review、合併成總評。
• Ensemble decoding：同個 prompt 用不同 seed / temperature 跑 5 次、majority vote 拿最穩答案。

失敗模式：

• 合併邏輯難設計：parallel 容易、合併難。三個 reviewer 意見不一致時怎麼裁判？多數決還是加權？
• Cost 是 sequential 數倍：parallel 跑 N call 的 cost 是 sequential single 的 N 倍、latency 才有節省。
• 不需要並行：本來 sequential single call 能解的事、parallel 變浪費。
• 不獨立的「平行」：兩個 call 其實依賴彼此、強制 parallel 反而漏訊號。

緩解策略：

• Parallel 前先問：這些 call 真的獨立嗎？依賴的應該 sequential。
• 合併邏輯先設計、再開始 parallel；想清楚怎麼合再進 parallel。
• Cost 監控：parallel 是 cost amplifier、生產環境注意。

Reflection：產出 → 評估 → 修正

結構：產出 → critic 評估 → 依評估修正 → 再評估 → ...、self-improvement loop。

適合場景：

• 任務有客觀評估訊號（test 跑通、規範符合、structured output 合法）。
• 一次產出品質不夠、可以迭代改善。
• 創意任務的「初稿 → 修稿」流程。

典型例子：

• Code 生成 + test 驅動：產出 code → 跑 test → 失敗的話讀 error 修正 → 再跑 test → 直到通過。
• 文章寫作：生成草稿 → critic 模型評論 → 依評論修改 → 再評論 → 直到滿意。

失敗模式：

• Critic 跟 generator 共用 blind spot：兩個都同個模型、有同樣的盲點、reflection 收斂到同樣錯誤位置（如兩個都不認識某個 framework 的 API、再 reflect 也不對）。
• 無限循環：沒有客觀停止訊號、reflection 一直跑、cost 爆掉。
• 過度修正：每次 reflection 都改一點、累積結果變糟（過度 fitting critic 意見）。
• Critic 失職：critic 太寬鬆、什麼都說 OK；或太嚴格、什麼都挑、永遠停不下來。

Systematic vs random error 的關鍵分層：reflection 對 random error 有效（同 prompt 重跑因 sampling 抖動產生的錯誤、多輪重 sample 會收斂）、但對 systematic error 無效（generator 跟 critic 共用 base model、訓練分佈中的盲點不會因重跑消失、loop 收斂到同樣錯誤）。判讀訊號：若 critic 每次給的修正建議都很像、或修完還是同一類錯、就是 systematic error、加 reflection steps 無收益。修法：換不同 base model 當 critic、或加外部驗證（test、lint、schema check）取代 LLM critic。Agent loop 是 reflection 的特例、進階失敗模式分析見 4.4 Agent 架構 的三類失敗段。

緩解策略：

• Critic 用不同模型、或不同 prompt 角度、減少 blind spot。
• Reflection 設 step 上限、即使沒達標也強制停。
• 客觀驗證訊號（test pass、schema 合法、外部 metric）優先於 LLM critic 主觀評估。
• Reflection 對有客觀訊號的任務 ROI 高、對純主觀偏好任務收益有限（critic 的「主觀好壞」跟 generator 同 base 時是同樣 distribution、無法 calibrate）。

四種模式的組合

實際應用通常混用、不是純單一模式：

• Pipeline of routers：第一步先 router 分類、每個 path 內部又是 pipeline。
• Parallel of pipelines：多個 pipeline 平行跑、最後合併。
• Reflection inside pipeline：pipeline 中某幾步用 reflection loop 改進、其他步驟 single call。
• Router into reflection：依輸入複雜度分流、簡單走 single call、複雜走 reflection loop。

複雜應用通常是這四種模式的多層組合。看 LLM application 結構時、能識別出基本模式組合、就能判斷它的複雜度合不合理。

組合的判讀訊號：

• 三層以上嵌套通常 over-engineered、考慮簡化。
• 同個模式重複用很多次（如 5 個 pipeline 串）可能拆得太細。
• 看不出基本模式的 ad-hoc 流程、通常維護困難。

何時退化成 Single Call 更好

判讀「該不該設計 workflow」的反射：先問「single call 能不能解」、不行再考慮拆。

Single call 更適合的訊號：

• 上下文短（< 8K token、塞得進現代 LLM）。
• 推理單純、不需要 multi-step。
• 不需要 tool 或只需一兩個簡單 tool。
• 沒有客觀驗證訊號可用、reflection 沒意義。
• Latency 敏感、不能接受多次 round trip。

「我先寫個 pipeline」常是過早優化：

• 簡單問題切成 5 步、累積誤差大過拆分收益。
• 為了「靈活性」抽象太多、最終比 single prompt 還難改。
• 寫 workflow framework 的成本超過用 raw API 的成本。

實務做法：先 single call baseline、跑半週看品質、不夠用再分解；workflow 設計留到 baseline 不足之後。

Workflow 設計常見的反模式

幾種特別容易踩的反模式：

過度切碎 pipeline

把任務切成 10 步、每步一個 LLM call、累積誤差大、latency 拖長、cost 爆。問題通常是「我以為拆細了品質會好」、實際相反。

訊號：pipeline 步驟超過 5 個、每步輸入輸出量級接近、看不出為什麼需要分。

緩解：能合併的合併、保留必要切點（中間有外部 tool 介入、或需要驗證的步驟）。

Parallel 跑根本不需要並行的事

兩個 call 其實依賴彼此、或本質是同個任務、硬要 parallel。Cost 是 sequential 的 N 倍、品質沒提升。

訊號：parallel 出來的結果合併邏輯複雜、或合併結果跟「直接 sequential 跑」差不多。

緩解：parallel 前問「這幾個 call 真的獨立、結果真的可合併嗎」、不獨立就 sequential。

Reflection 沒有客觀停止條件

Reflection loop 純靠模型自己判斷「夠好了沒」、容易過度修正或無限循環。

訊號：reflection loop 沒有 step cap、沒有外部 metric、純依模型自評。

緩解：每個 reflection loop 都設 step 上限 + 客觀停止訊號（test pass、external check）。

Router classifier 過於複雜

Classifier 本身就需要強模型、變成 router「省 cost」反而花更多。

訊號：classifier 用的模型跟下游 path 同等級或更強。

緩解：classifier 用最便宜的小模型；最便宜小模型若 confidence 不夠、改成「沒有 router、全部走主 path」。

看不出基本模式的 ad-hoc 流程

完全自訂的 control flow、不能對應到任何標準模式、維護困難。

訊號：流程圖畫不出來、新人接手要花一週搞懂、改一個 bug 影響不知道擴散到哪。

緩解：重新設計、強制套用基本模式組合。不能套用通常代表設計過度複雜。

何時過時 / 何時不過時

不會過時的部分：

• 四種基本模式（pipeline / router / parallel / reflection）的結構跟失敗模式分類。
• Multi-call 成本（latency / cost / 失敗點累乘）的本質。
• 「先 single call baseline、不夠再分解」的設計順序。
• 五個常見反模式的識別。

會變的部分：

• 具體 workflow framework（LangGraph、LlamaIndex Workflow、各家 DAG runner）的 API。
• 「最佳化」的具體技巧（caching、batching、streaming 整合）。
• 哪些 framework 對哪種模式支援好（會持續演化）。

看到新 workflow framework 時、回到本章四模式 framing、看它支援哪些模式、有沒有解決常見反模式、能不能跟你的應用場景對齊。Framework 換代不影響這四個模式的本質結構。

下一章

下一章：4.8 Multi-Agent 拓樸、當 single-thread 多 call 不夠用、需要平行專業化角色 / 跨產品 agent 重用時、進入 multi-agent 系統的拓樸設計。

設計完 workflow 後、進 production 還要評估資源、latency / throughput 取捨、observability 三層、降級設計、見 4.9 Production 資源規劃。

CI/CD 的責任是提供一致的判讀入口。當 workflow 顯示失敗時，團隊需要能快速判斷是 lint、test、build、package、Artifact Handoff、deploy 還是 Rollback Strategy 階段出問題，並知道下一步該回到本機重現、修正、重新提交，還是暫停發布。

前置知識卡片

用原子化卡片整理 Artifact、Required Checks、Artifact Handoff、Environment Protection、Preview Environment、Rollout Strategy、Rollback Strategy、Migration、Backfill、Image Digest、Release Channel、Infrastructure Drift、Function Alias 與 Flaky Test 等核心術語。流程文章專注情境判讀與決策順序，術語背景交由卡片維持一致。

學習路線

學習路線先從失敗處理與 gate 邊界開始，因為 CI/CD 的價值會在紅燈時最清楚。當讀者能判讀失敗位置與下一步路由，再依部署場域進入前端、後端、App、Docker 或本 blog 專案案例。

與其他教學的分工

CI/CD 教學負責日常工作流程與部署場域差異，Backend 可靠性模組負責系統層可靠性判斷。讀者想知道 workflow 失敗後怎麼修、發布 gate 怎麼切、前端與後端部署流程差在哪裡，讀本系列；想知道 CI 在 release gate、SLO、load test 與可靠性治理中的位置，回到 模組六：可靠性驗證流程。

Go、Python 或其他語言教材只需要保留測試寫法與本機命令。當內容開始涉及 workflow event、required checks、preview deployment、container registry、mobile signing、artifact、cache 或 branch protection，就應該移到本系列，讓不同語言共用同一套 CI/CD 操作語意。

判讀訊號

• GitHub Actions 紅燈後，不知道該看哪個 job。
• 本機測試通過，但 CI 失敗。
• 測試失敗後仍有部署 workflow 啟動。
• deploy 失敗時，團隊分不清 build artifact、部署權限與測試 gate 的責任。
• 前端、後端、App 與 Docker 使用同一套發布說明，導致場域細節混在一起。
• workflow 只有命令清單，沒有說明失敗後的處理路由與部署場域邊界。

下一步路由

• 想處理 GitHub Actions 紅燈：讀 CI 失敗到修復發布流程。
• 想理解 CI gate 原理：讀 CI gate 與 workflow 邊界。
• 想理解前端部署：讀 前端部署 CI/CD。
• 想理解後端部署：讀 後端部署 CI/CD。
• 想理解 App 發布：讀 App 部署 CI/CD。
• 想理解 Docker / image 流程：讀 Docker / Image 部署 CI/CD。
• 想理解 Serverless 發布：讀 Serverless 部署 CI/CD。
• 想理解資料處理任務發布：讀 Data Pipeline 部署 CI/CD。
• 想理解 IaC / 平台變更發布：讀 IaC / Platform 部署 CI/CD。
• 想理解 Flutter/Electron/Tauri 類客戶端發布：讀 Desktop Client 部署 CI/CD。
• 想理解 SDK / NPM / PyPI 發版：讀 Package / Library Release CI/CD。
• 想維護本 blog 的 workflow：讀 本 blog 專案部署。
• 想讓測試與發布共用同一份產物：讀 Artifact 與可重播性。
• 想治理不穩定測試：讀 Flaky test 治理。
• 想理解可靠性層的 CI 分層：讀 6.1 CI pipeline。
• 想理解發布 gate：讀 6.8 Release Gate 與變更節奏。
• 想理解 infra 變更的 plan / apply 流程怎麼走 CI：讀 Infra 走 PR 流程與自動化護欄。

Unix 系統用檔名開頭的 . 標記隱藏檔。shell 配置（.bashrc、.zshrc）、Git 設定（.gitconfig）、SSH 設定（.ssh/config）、以及 ~/.config/ 底下各種工具的配置目錄，都屬於這個範疇。「dotfile 管理」指的是把這些散落在家目錄各處的配置檔集中到一個 Git repo，建立版本歷史、可以跨機器同步、可以在新環境一鍵部署。

章節文章

跨分類引用

• → 模組一：管理工具與目錄結構：怎麼把散落的配置檔收進 Git repo
• → 模組八：同步、Bootstrap 與環境重建：環境重建的完整流程
• → 模組九：從個人到團隊：dotfile 思想往團隊環境延伸
• → Infra 基礎設施建置指南：組織層級的環境 as code