先裝 Homebrew，它是後面一切的基礎

macOS 本身沒有內建的第三方套件管理工具，而後面幾乎每一項補強（命令列工具、開發語言、甚至部分 GUI App）都靠它安裝。沒有 Homebrew，這份清單的其他項目全部無從裝起，所以它排第一。

安裝過程會要求輸入登入密碼（sudo），並自動下載 Xcode Command Line Tools，畫面可能停住數分鐘屬正常。

1/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

裝完還要把 Homebrew 的執行檔目錄加進 PATH，shell 才找得到 brew 與之後用它裝的工具。Homebrew 的安裝前綴依晶片而異：Apple Silicon 機器裝在 /opt/homebrew、Intel 機器裝在 /usr/local。安裝腳本結尾會印出對應這台機器的設定指令，照它印的路徑寫進 ~/.zprofile 讓每次開 shell 都生效。以下以 Apple Silicon 為例，Intel 機器把前綴換成 /usr/local 即可：

1echo 'eval "$(/opt/homebrew/bin/brew shellenv)"' >> ~/.zprofile
2eval "$(/opt/homebrew/bin/brew shellenv)"

這一步做完，驗證安裝成功：

1brew --version   # 應印出 Homebrew 4.x.x

版本號印出來，Homebrew 就能當後面所有項目的安裝來源。

把 bash 更新到 5.x

bash 是裝完 Homebrew 後最值得優先換掉的內建工具。macOS 的 /bin/bash 長年凍結在 3.2 系列（2006 年釋出，目前是 patchlevel 57），Apple 不再更新它，原因是 bash 4 改用 GPLv3 授權、Apple 不願隨系統散布。對寫腳本的人來說，這代表 associative array、${var,,} 大小寫轉換、mapfile 等近二十年的語法都用不了。

正確做法是用 Homebrew 另外裝一份新版並排存在，而不是覆寫系統版。/bin/bash 在唯讀的系統卷上、受 SIP（System Integrity Protection）保護，覆寫會被擋下：

1brew install bash

這會把 bash 5.x 裝到 /opt/homebrew/bin/bash，完全不碰 /bin/bash。因為前一步已經把 /opt/homebrew/bin 排在 PATH 前面，用 #!/usr/bin/env bash 起手的腳本就會自動改用新版。裝完驗證一下版本確實切過去：

1env bash --version   # 應顯示 5.x
2/bin/bash --version  # 系統版仍是 3.2.57，沒被動

要留意的是互動 shell 在現代 macOS 預設是 zsh，這一步不影響它。更新 bash 的目的是給 #!/usr/bin/env bash 腳本一個現代執行環境，不是換登入 shell。真要把新版 bash 當登入 shell，才需要額外把它加進 /etc/shells 再 chsh。

把 ~/.local/bin 加進 PATH，放個人腳本

跟專案無關的小工具（例如 disk-report 與 app-report 這類系統診斷腳本）需要一個能在任何地方直接呼叫、又不污染專案 repo 的家。慣例是個人的 ~/.local/bin，把它建好並掛上 PATH。

1mkdir -p ~/.local/bin
2echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.zprofile
3export PATH="$HOME/.local/bin:$PATH"

目錄建好、PATH 掛上後，確認它確實生效：

1echo "$PATH" | tr ':' '\n' | grep "$HOME/.local/bin"

之後把腳本 symlink 進這個目錄就能直接當指令用。

後續項目

基礎建設到位後，第一個掛上去的實用腳本就是系統診斷：磁碟空間診斷的 disk-report 與 按 App 聚合佔用的 app-report，兩支都 symlink 進 ~/.local/bin 直接當指令用。

這份清單會隨著之後遇到的需求往下增補，新項目接在這裡。原則維持不變：基礎建設排前面，依賴它的補強排後面，每一項都寫清楚「為什麼要做」而不只是貼指令。

每篇 hands-on 文章 focus 在「為什麼這樣設計」、本篇 focus 在「按順序跑通」。讀完想懂原理再進對應章節讀。

驗證日期：2026-05-12 環境：macOS 14+、Apple Silicon、Ollama 0.23.2、Python 3.11+ 總時間：~15 分鐘（含 model 下載） 磁碟需求：Step 1 ~ 4 約 ~5 GB（Ollama 200 MB + nomic-embed-text 274 MB + gemma3:1b 815 MB + room for index）；Step 5 ComfyUI 可選加 ~10 GB（SDXL base 模型）。 適用平台：本快速路徑只在 Apple Silicon Mac 驗證過；Intel Mac / Linux 上 Ollama 仍可裝、但 GPU 加速跟 model tag 行為可能不同、實際以官方 release notes 為準。

適合誰讀

為什麼不是「pre-built、clone 就能跑」

衍生產物（index.pkl、__pycache__/、Ollama model weights、即「跑出來的 cache / index / weight」、跟 source code 區別）刻意不進 git、原因見 4.10 衍生產物管理原理。所以 clone repo 後需要：

1. 裝 Ollama daemon + 拉 model（一次性）
2. 跑 ingest.py 建 RAG index（corpus 變動時重跑）
3. 之後 demo 就能用

本篇是這個流程的 step-by-step。

Step 1：裝 Ollama daemon（brew install ollama + brew services start）

daemon = 常駐 background process、開機自動啟動、見 launchd service 卡。

1brew install ollama
2brew services start ollama

驗證：

1curl -s http://localhost:11434/api/version
2# {"version":"0.x.x"}

詳細安裝跟 troubleshooting 見 Ollama setup 章節。

Step 2：拉 model（embed + chat 兩種角色）

為什麼要拉兩個 model：RAG 需要 embedding model 把文字壓成向量做語意比對、chat model 負責根據 retrieval 結果生成回答、兩者訓練目標不同、不能互通（見 3.1 embedding 空間）。

1# Embedding model（RAG / MCP 都要、274 MB）
2ollama pull nomic-embed-text
3
4# Chat model（推薦從 1B 開始驗證、之後可換大）
5ollama pull gemma3:1b

驗證：

1ollama list
2# NAME                       SIZE      MODIFIED
3# gemma3:1b                  815 MB    ...
4# nomic-embed-text:latest    274 MB    ...

選 chat model 大小的取捨見 1.4 模型選型優先順序。本 quickstart 用 1B 主要驗證流程跑通；長段 daily use（需要 follow 多段格式指令、複雜推理）建議 4B / 8B 起跳（見 instruction-following-test）、極短句驗證 / 簡單問答 1B 也可。本系列預設用 instruction-tuned model 變體（tag 含 :Xb 不含 -base）、適合對話 / 寫 code。

Step 3：建 RAG index（跑 ingest.py）

1cd /path/to/blog
2python3 scripts/rag-demo/ingest.py

預期輸出：

1Found 71 markdown files under content/llm
2  [10/71] 86 chunks in 4.5s
3  ...
4Wrote 463 records to scripts/rag-demo/index.pkl (22.3s)

實際數字看你的 blog content 量。Index file 在 scripts/rag-demo/index.pkl、3-50 MB 不等。

詳細的 chunking 策略、embedding 設計、為什麼 pickle、見 RAG demo 章節。

Step 4：跑 RAG / MCP / permission demo

完成 step 1-3 後、四個 demo 都能跑了：

RAG demo（語意搜尋 + LLM 回答）

1python3 scripts/rag-demo/query.py --show-retrieved "你的問題"

例：

1python3 scripts/rag-demo/query.py --show-retrieved "什麼是 MCP？"

預期看到 retrieved chunks（含相似度跟來源 path）+ LLM 用這些 context 生的答案。

MCP demo（stdio JSON-RPC server）

1python3 scripts/mcp-demo/test_client.py

預期看到 5 個階段的 JSON-RPC 對話：initialize / tools/list / tools/call (search_blog) / tools/call (read_chunk) / error。

Permission boundary demo（LLM-mediated file edit）

 1# 備份要試的檔案
 2cp content/llm/knowledge-cards/token.md /tmp/token-orig.md
 3
 4# Dry-run（預設、不寫檔、印 diff）
 5python3 scripts/permission-demo/edit_with_llm.py \
 6  content/llm/knowledge-cards/token.md \
 7  "加一句說明"
 8
 9# 還原（如果剛剛沒用 dry-run）
10cp /tmp/token-orig.md content/llm/knowledge-cards/token.md

詳細的 --dry-run / --confirm / --auto 三種 mode 取捨見 Permission boundary 章節。

Step 5（可選）：ComfyUI text-to-image demo

需要額外裝 ComfyUI + 拉 SDXL model（~10 GB 磁碟）、流程獨立：

1# 跟 step 1 平行的軌道、見 ComfyUI setup 章節
2cd ~/Projects
3git clone --depth 1 https://github.com/comfyanonymous/ComfyUI.git
4cd ComfyUI
5python3 -m venv venv
6source venv/bin/activate
7pip install -r requirements.txt
8# 下載 SDXL base：~/Projects/ComfyUI/models/checkpoints/
9# 見 ComfyUI setup 章節指令

啟動 + 跑 generation：

1cd ~/Projects/ComfyUI && source venv/bin/activate && nohup python main.py > /tmp/comfyui.log 2>&1 &
2# 等 server ready
3until curl -s -o /dev/null -w "%{http_code}" http://127.0.0.1:8188/ | grep -q 200; do sleep 2; done
4
5# 跑 generation（用 repo 內的 script）
6cd /path/to/blog
7python3 scripts/comfyui-test/generate.py --steps 15

詳細裝法 + workflow JSON 解讀見 ComfyUI setup 章節。

Cleanup（完事釋放資源）

1# 停 Ollama daemon
2brew services stop ollama
3
4# kill ComfyUI（如果有跑）
5pkill -9 -f "ComfyUI/main.py"
6
7# 清 build artifact（可選、可重建）
8rm -f scripts/rag-demo/index.pkl
9find scripts -name __pycache__ -type d -exec rm -rf {} +

詳細的 resource lifecycle 跟 cleanup idiom 見 Resource management 章節。

跑通後該往哪讀

跑不過時

何時這篇會過時

會變的部分：

• brew install ollama 流程（macOS 跟 brew 演化）
• ollama pull 的具體 model tag（model 會新陳代謝）
• Python 版本相容性（3.11 → 3.14 各有 quirk）

不會過時的部分：

• 4 步驟的順序（裝 daemon → 拉 model → 建 index → 跑 demo）是 RAG / MCP / 任何 LLM 應用的通用 setup pattern
• 衍生產物（index、cache）不進 git 的設計取捨
• Cleanup 步驟跟釋放邏輯

跑指令時報錯先看 step 對應章節的 troubleshooting section、再 Google 或開 issue。