Omarchy 3.x      → 舊架構，僅作歷史對照，請勿照做
Omarchy 4.x (Quattro) → 目前架構，本手冊的實作對象

# 這些在 macOS / Windows 上會有差異，在 Omarchy 上不會
sed -i 's/foo/bar/' file.txt      # macOS 需要 sed -i ''
readlink -f ./path                # macOS 沒有 -f
docker run --network host ...     # macOS / Windows 的 Docker Desktop 不支援
stat -c '%s' file                 # macOS 是 stat -f '%z'

接收任務
  ↓
執行工具（多數是 shell 指令）
  ↓
讀取輸出
  ↓
判斷下一步
  ↓
（循環）

背景
  20 人 Java/Vue 團隊，目前 Windows + WSL2 + IntelliJ
  痛點：WSL2 檔案 I/O 慢、Docker Desktop 授權費、環境不一致

評估後的決定
  ✅ 3 位資深工程師先導入 Omarchy（自願、有 Linux 經驗）
  ✅ 建立團隊的 bootstrap script 與標準設定（第 42 章）
  ⏸️ 觀察 3 個月：穩定性、AI Agent 產出品質、支援成本
  ❌ 暫不全面導入：EDR/DLP 政策未通過資安審查

3 個月後的實際發現
  ✅ Maven build 時間從 3m20s 降到 1m50s（WSL2 I/O 消失）
  ✅ AI Agent 逆向工程效率明顯提升（CLI 工具鏈完整）
  ⚠️ 一次 rolling update 導致 NVIDIA 驅動異常，靠 snapshot 還原（15 分鐘）
  ❌ 公司 VPN client 只有 Windows / macOS 版，需用替代方案

傳統 Linux 發行版的態度
  「這裡有 500 個選項，請自行組裝出你要的系統」
  → 自由度高，但決策成本極高，且每個人組出來的都不一樣

Omakase 的態度
  「我已經幫你組好了一套經過驗證的組合，先用用看」
  → 決策成本近乎零，團隊一致性高，但你必須接受別人的品味

第 1–3 天   效率降低 40–60%。你會一直忘記快捷鍵，一直想去摸滑鼠。
第 4–7 天   效率回到 80%。開始記住 Super+Return / Super+Space / Super+W。
第 2 週     效率回到 100%，開始感受到 tiling 的好處。
第 3–4 週   效率超過原本。手不再離開鍵盤，切換成本趨近於零。

Overlapping（Windows / macOS）
  「我有一堆視窗疊在一起，我要花力氣管理它們的位置與大小」

Tiling（Omarchy）
  「我不管視窗位置，系統自動排。我只管『我現在要看哪個』」

情境
  資深工程師 A 習慣 i3wm 的 vim 風格快捷鍵（hjkl），
  上手 Omarchy 第一天就把 bindings.lua 大改，
  同時換掉 bar 的排列、改了 shell.json 大半設定。

第 3 週遇到的問題
  omarchy update 之後：
  - 部分自訂 binding 與新版預設衝突，兩個功能搶同一組鍵
  - shell.json 的某個 key 在新版改名，bar 有個 widget 消失
  - 想找官方文件排查，但文件寫的是預設行為，跟他的環境對不上
  - 花了 3 小時才排除

事後檢討
  ❌ 錯誤：一次改太多，且沒有把設定納入版本控制
  ✅ 正確做法：
     1. 先用預設值兩週
     2. 用 git 管理 ~/.config（dotfiles，見第 43 章）
     3. 每次只改一項，改完 commit
     4. update 前先 git status 確認自己改了什麼

# 🔧 檢視最近的 coredump（一般 Linux 指令）
coredumpctl list

# 檢視特定一筆的詳細資訊
coredumpctl info <PID>

套件來源優先順序
  1. Arch core / extra / multilib   ← 官方，最可信
  2. Omarchy 自有套件庫              ← 官方策展，可信
  3. AUR                            ← ⚠️ 使用者上傳，需自行審查 PKGBUILD

Wayland（協定）
   ↓
Hyprland（Compositor / Window Manager）
   ├─ Tiling 演算法（dwindle / scrolling）
   ├─ Workspace 管理
   ├─ 按鍵綁定（bindings）
   ├─ 動畫與視覺效果
   └─ 多螢幕

Quickshell（Qt Quick / QML 框架）
   ↓
omarchy-shell（單一長駐程序）
   ↓
Plugins（bar / launcher / menu / notification / OSD / lock screen / background service）

Agent CLI（lazy-loaded launcher）
  claude   → Claude Code
  codex    → OpenAI Codex
  opencode → OpenCode
  agy      → Google Antigravity CLI
  copilot  → GitHub Copilot CLI
  crush    → Crush
  grok     → Grok CLI (xAI)
  pi       → Mario Zechner's Pi
  omp      → Oh My Pi
  ori      → Ori (OpenRouter harness)

整合機制
  omarchy default agent <name>      設定預設 agent
  omarchy agent prompt "task"       帶任務啟動
  Super + Shift + Ctrl + A          專屬終端機啟動預設 agent
  a / c / cx / cy                   inline 別名
  Bar 上的 agents panel             用量 / session / token 追蹤
  Omarchy Skill                     ⚠️ 實驗性：coredump 自動診斷

~/.config/                     ← 你的。改這裡。update 不會覆蓋
├── hypr/
│   ├── hyprland.lua           主設定
│   ├── bindings.lua           按鍵
│   ├── monitors.lua           螢幕
│   ├── input.lua              輸入裝置
│   ├── looknfeel.lua          外觀
│   └── autostart.lua          自動啟動
├── omarchy/
│   ├── shell.json             bar / widget 設定
│   └── plugins/               第三方 shell plugin
├── foot/foot.ini              終端機設定
└── ...

~/.bashrc                      ← 你的。可加 export / function / alias
~/.XCompose                    ← 你的。emoji 與自動補字

/usr/share/omarchy/            ← Omarchy 的。⚠️ 不要改，update 會覆蓋
$OMARCHY_PATH/shell/plugins/   ← 官方 shell plugin

症狀
  「頂端的 bar 不見了，但視窗還能正常操作」

用分層架構定位
  ⑤ Hyprland 層  → 正常（視窗能操作，代表 compositor 活著）
  ⑥ Shell 層     → 有問題（bar 屬於 omarchy-shell）

診斷指令
  $ systemctl --user status omarchy-shell     # 檢查 shell 程序狀態
  $ omarchy debug                             # 產生診斷資訊

可能原因（由高到低機率）
  1. 手動按了 Super + Shift + Space（隱藏 bar）→ 再按一次
  2. 第三方 plugin 崩潰拖垮 shell → omarchy plugin list 逐一 disable 測試
  3. shell.json 格式錯誤 → 檢查 JSON 語法
  4. 更新後的 migration 未完成 → 重跑 omarchy update

關鍵洞察
  因為 4.x 把 8 支程式合併成 1 個程序，
  「一個 plugin 崩潰可能拖垮整個 shell」是 4.x 特有的風險。
  3.x 時代 waybar 掛掉不會影響 mako。

$OMARCHY_PATH/shell/plugins/     ← 第一方（官方內建）
~/.config/omarchy/plugins/       ← 第三方（你安裝的）

兩者在啟動時都會被自動探索（auto-discovered）

# 列出所有 plugin（含啟用狀態）
omarchy plugin list

# 啟用 / 停用
omarchy plugin enable omarchy.tailscale
omarchy plugin disable omarchy.weather

# 從 git repository 安裝第三方 plugin
omarchy plugin add https://github.com/acme/omarchy-weather.git --enable

# 驗證自己寫的 plugin（發布前必做）
omarchy plugin validate ./my-plugin

my-plugin/
├── manifest.json        必要：宣告 plugin 名稱、kind、進入點
└── Main.qml             QML 實作

1. 開發 → omarchy plugin validate ./my-plugin
2. 推到公開 git repository
3. 到 https://omarchyplugins.com 註冊，供社群發現

# 設定檔位置
~/.config/omarchy/shell.json      # bar 設定在 "bar" key 底下

# CLI 控制
omarchy bar                        # bar 相關子指令

Super + Shift + Space    隱藏 / 顯示 bar

-- ~/.config/hypr/bindings.lua
-- Lua 讓你可以用迴圈產生綁定，而不是複製貼上 10 次

local workspaces = { 1, 2, 3, 4, 5, 6, 7, 8, 9 }

for _, ws in ipairs(workspaces) do
  bind("SUPER", tostring(ws), "workspace", tostring(ws))
  bind("SUPER SHIFT", tostring(ws), "movetoworkspace", tostring(ws))
end

# 💡 實務：升級前先看官方這一版做了哪些 migration
ls -1 "$OMARCHY_PATH/migrations/" | tail -20

# 讀某一支 migration 的實際內容（最可靠的變更說明）
cat "$OMARCHY_PATH/migrations/<timestamp>.sh"

情境
  工程師 B 在某部落格看到「Omarchy 自訂 waybar 教學」，
  照做後發現：
  - 找不到 ~/.config/waybar/ 目錄
  - pacman -Qi waybar 顯示套件不存在
  - 以為系統壞了，想重灌

真正的原因
  那篇文章寫的是 Omarchy 3.x。
  4.x 根本沒有 waybar，bar 是 omarchy-shell 的一個 plugin。

正確做法
  $ cat ~/.config/omarchy/shell.json | jq '.bar'    # 看目前 bar 設定
  $ omarchy plugin list                             # 看有哪些 plugin
  $ omarchy bar --help                              # 看 bar 的 CLI 用法
  # 或直接拖曳 widget，或用 Style → Menu Bar 選單

如何避免
  看到教學先確認版本。判斷關鍵字：
  - 出現 waybar / mako / walker / swayosd / hyprland.conf → 3.x，跳過
  - 出現 omarchy-shell / shell.json / *.lua / plugin      → 4.x，可參考

情境
  安裝了一個社群的「股價 bar widget」plugin，
  隔天開機後整條 bar 消失、通知也不會跳、鎖定畫面失效。

原因
  該 plugin 在網路異常時未處理例外，
  導致 QML 拋出未捕捉的錯誤 → 整個 omarchy-shell 程序崩潰。
  因為 4.x 所有元件都在同一程序，故障半徑 = 整個桌面 shell。

處理流程
  1. Ctrl + Alt + F2 切到 TTY（bar 沒了但 TTY 還在）
  2. omarchy plugin list                    # 找出可疑 plugin
  3. omarchy plugin disable <plugin-name>   # 停用
  4. systemctl --user restart omarchy-shell # 重啟 shell
  5. 確認恢復後，再決定要不要修 plugin 或永久移除

教訓
  企業環境應該建立 plugin 白名單，
  且新 plugin 應在測試機驗證一週後才推廣。

CPU     4–8 核
RAM     16 GB
儲存    256 GB NVMe
GPU     內顯

可以做
  ✅ 一般 Web 開發（Vue / React 前端）
  ✅ 單一 Spring Boot 服務 + 1 個資料庫容器
  ✅ AI Agent CLI（呼叫雲端 LLM，本機負擔小）
  ✅ VS Code

會很痛苦
  ⚠️ IntelliJ IDEA + 大型 Maven 專案（IntelliJ 索引很吃 RAM）
  ❌ 多個容器（PostgreSQL + Redis + Kafka + Zookeeper）同時跑
  ❌ 同時開多個 AI Agent session 處理大型 codebase

CPU     8–12 核
RAM     32 GB          ← 本手冊建議的企業標準
儲存    1 TB NVMe
GPU     內顯 或 中階獨顯

可以做
  ✅ IntelliJ + 大型 Spring Boot 專案
  ✅ 完整的本機開發堆疊（PostgreSQL + Redis + Kafka + 前後端）
  ✅ 2–3 個 AI Agent 平行處理不同 worktree
  ✅ 一邊跑整合測試一邊繼續開發

CPU     12–16 核以上
RAM     64 GB 以上
儲存    2 TB NVMe
GPU     視是否要跑 local LLM 而定

適用情境
  ✅ 多 Agent 平行工作（第 23 章的 Agent Team）
  ✅ 大型 monorepo 的逆向工程（同時索引數十萬行程式碼）
  ✅ Framework 升版：同時開 3 個 worktree（原版 / 升版中 / 對照）
  ✅ 完整的微服務堆疊本機開發（8+ 個容器）
  ✅ 若要跑 local LLM，另需 GPU VRAM（見 5.5）

一個 AI Agent 工作階段實際佔用的資源

Agent CLI 本體               ~200-500 MB    （輕）
  ↓ 它會做這些事
語言伺服器（LSP）            ~1-2 GB        （分析程式碼）
Maven / Gradle build         ~2-4 GB        （編譯驗證）
測試執行（含 Testcontainers） ~2-6 GB        （跑測試）
被開啟的容器                 ~2-8 GB        （驗證行為）
IntelliJ 索引                ~4-8 GB        （若同時開著）
─────────────────────────────────────────
單一 agent 工作階段峰值       ~10-20 GB

多開 3 個 agent 處理不同 worktree → 輕鬆超過 32 GB

# 用 pacman 或 AUR 安裝 Ollama（🔧 一般 Linux 做法）
# ⚠️ 注意：安裝前先閱讀 PKGBUILD
yay -G ollama-bin && bat ollama-bin/PKGBUILD   # 先讀再裝
yay -S ollama-bin

# 拉一個模型
ollama pull qwen2.5-coder:7b

# VRAM 需求粗估
#   7B  量化模型  ≈  5-8 GB VRAM
#   14B 量化模型  ≈ 10-14 GB VRAM
#   32B 量化模型  ≈ 20-28 GB VRAM
#   70B 量化模型  ≈ 40-48 GB VRAM

情境
  某公司採購 10 台開發機給團隊裝 Omarchy，規格：
  - Intel i7 / 16 GB RAM / 512 GB SSD
  - NVIDIA RTX 顯示卡（「以後可以跑 AI」）
  - 藍牙鍵盤滑鼠組（辦公室美觀考量）
  - 資安政策要求 Secure Boot 開啟

結果
  ❌ 藍牙鍵盤無法輸入開機解密密碼 → 全部退回換有線鍵盤
  ❌ Secure Boot 必須關閉 → 需要資安例外簽核，卡了 6 週
  ❌ 16 GB RAM 跑 IntelliJ + 5 個容器 + AI Agent 時嚴重 swap
  ⚠️ NVIDIA 驅動在第 3 次 rolling update 時異常 → 靠快照還原
  ❌ 「以後可以跑 AI」的 RTX 顯卡完全沒用到
     （團隊實際用的是 Claude Code，呼叫雲端，不吃 GPU）

正確的規格應該是
  ✅ AMD Ryzen / 32 GB RAM / 1 TB NVMe
  ✅ AMD 內顯（省事）或 Intel 內顯
  ✅ 有線鍵盤（或至少 2.4GHz 無線）
  ✅ 事前完成 Secure Boot 的資安例外簽核
  💰 同樣預算下，把錢從 GPU 移到 RAM 與 SSD，實際效益高得多

給 Omarchy 的未配置空間
  最低      150 GB    （能跑，但容器與快照會很快吃緊）
  建議      300 GB    （一般 Java + 前端開發）
  舒適      500 GB+   （多容器、多 worktree、AI Agent 重度使用）

https://iso.omarchy.org/omarchy-4.0.2.iso

# 計算下載檔案的 SHA256
Get-FileHash -Algorithm SHA256 ".\omarchy-4.0.2.iso" | Format-List

sha256sum omarchy-4.0.2.iso

# 📘 官方內建函式：互動式選擇目標磁碟後寫入
iso2sd omarchy-4.0.2.iso

操作
  1. 插上 USB
  2. 開機時按下開機選單鍵（各廠牌不同）
     Dell / Lenovo   → F12
     HP              → F9
     ASUS / Acer     → F12 或 Esc
     MSI / Gigabyte  → F11
  3. 選擇 USB 裝置（通常顯示為 UEFI: <USB 廠牌>）

常見錯誤
  ❌ 看不到 USB 選項    → Secure Boot 沒關 / Fast Boot 沒關 / USB 不是 UEFI 開機格式
  ❌ 開機後黑畫面        → 顯示卡問題，NVIDIA 使用者可嘗試 nomodeset 開機參數
  ❌ 選了 Legacy 開機項  → 務必選有 "UEFI:" 前綴的那一項

Installer 會列出偵測到的磁碟

選項 A：Full-disk install（整碟安裝）
  ⚠️ DANGER：抹掉該顆磁碟的所有資料，包含 Windows

選項 B：Free space install（未配置空間安裝）
  📘 官方：用於 Dual Boot，安裝到你先前壓縮出來的未配置空間

安裝程式會要求你設定加密密碼

⚠️ 三個絕對不能忘的事
  1. 這個密碼忘記 = 資料永久無法還原（沒有後門、沒有客服可以救）
  2. 這個密碼要用「有線/2.4GHz 鍵盤」在開機時輸入
  3. 這個密碼與「登入密碼」是兩個不同的密碼

📘 官方：只有在特定情況下可以跳過加密——
   在磁碟格式化確認畫面按 Ctrl + C
   ⚠️ 但強烈不建議。開發機上有原始碼、SSH 私鑰、雲端憑證。

需要填寫
  - 使用者名稱
  - 登入密碼（同時也是 sudo 密碼）
  - 主機名稱
  - 時區
  - 鍵盤配置
  - 網路（有線自動；Wi-Fi 需選 SSID 輸入密碼）

安裝執行（1–5 分鐘）
    ↓
重開機（記得拔掉 USB）
    ↓
Limine bootloader 出現
    ↓
輸入 LUKS 加密密碼   ← ⚠️ 用有線鍵盤
    ↓
輸入登入密碼
    ↓
桌面出現

# 📘 官方指令：掃描並把其他作業系統（如 Windows Boot Manager）加入開機選單
sudo limine-scan

準備一顆 volume label 為 cidata 的第二個磁碟／ISO
   ↓
Installer 偵測到它
   ↓
跳過設定精靈，套用設定檔內容
   ↓
自動重開機

# 📘 官方指定的方式
openssl passwd -6
# 輸入密碼後，會輸出 $6$... 開頭的雜湊字串

genisoimage -output cidata.iso -volid cidata -joliet -rock cidata/

D-3 天
  ✅ 確認資料已備份（外接碟 + OneDrive）
  ✅ 備份 ~/.ssh、瀏覽器書籤、1Password 已同步
  ✅ 記下 BitLocker 復原金鑰
  ✅ 在 Windows 關閉 BitLocker

D-2 天
  ⏳ BitLocker 解密中（1 TB NVMe 花了約 4 小時）
  ✅ manage-bde -status 顯示 Fully Decrypted

D-1 天
  ✅ 磁碟管理壓縮 C: 空出 400 GB
  ✅ BIOS：關閉 Secure Boot、TPM、Fast Boot；確認 UEFI 模式
  ✅ 下載 ISO、驗證、用 balenaEtcher 寫入 USB（含驗證）
  ✅ 準備有線 USB 鍵盤

D-Day
  09:00  從 USB 開機
  09:02  選擇 Free space install
  09:03  設定 LUKS 密碼（寫在密碼管理器裡）
  09:04  設定使用者、時區、鍵盤、Wi-Fi
  09:06  安裝完成，拔 USB 重開機
  09:08  輸入 LUKS 密碼 → 登入 → 桌面出現
  09:10  sudo limine-scan → 重開機 → Windows 回到開機選單
  ✅ 總計 10 分鐘（但前置作業花了 3 天）

Limine 開機選單
    ↓（可選擇快照版本，見第 32 章）
LUKS 解密密碼
    ↓
登入密碼
    ↓
桌面

┌──────────────────────────────────────────────────────────────┐
│ [logo] [1][2][3][4]      🕐 14:32  ☁️ 26°      🔊 🔵 📶 🔋 ⏻ │  ← 頂端 bar
├──────────────────────────────────────────────────────────────┤
│                                                              │
│                                                              │
│                     （空的桌面）                              │
│              沒有圖示、沒有工作列、沒有 Dock                    │
│                                                              │
│                                                              │
└──────────────────────────────────────────────────────────────┘

omarchy menu                    # 開啟根選單
omarchy menu <path>             # 直接跳到指定位置
omarchy menu close              # 關閉選單

# 📘 這些全部預裝好了，直接可用
rg "TODO"                    # ripgrep：搜內容
fd "Application.java"        # fd：找檔案
ff                           # fzf 模糊搜尋（含預覽）
lt                           # eza 樹狀列出
lsa                          # eza 顯示隱藏檔
bat pom.xml                  # 語法高亮檢視
cd oma                       # zoxide 智慧跳轉（會學習你的習慣）
tldr tar                     # 簡明版 man page
lazygit                      # Git TUI
btop                         # 系統監控

Super + 1/2/3/4         跳到工作區 1/2/3/4
Super + Shift + 1/2/3/4 把目前視窗「移動」到工作區 1/2/3/4
Super + Tab             下一個工作區

工作區 1    編輯器 / IDE
工作區 2    終端機 + AI Agent
工作區 3    瀏覽器（文件、測試頁面）
工作區 4    容器、日誌、監控

# 📘 官方 CLI 語法：omarchy reminder <分鐘> '<訊息>'
omarchy reminder 7 'Tea ready'

# 💡 啟動長任務時同時設一個 25 分鐘的提醒
omarchy reminder 25 'Agent: 檢查 upgrade/java-11 worktree 進度' && \
  tmux new -s upgrade -d 'claude'

# 或包成 shell 函式（放 ~/.bashrc）
agent-timed() {
  local mins="${1:?用法: agent-timed <分鐘> <任務描述>}"; shift
  omarchy reminder "$mins" "Agent 任務該檢查了：$*"
  echo "⏰ ${mins} 分鐘後會提醒你"
}

1. 熟悉四個核心鍵（Super+Space / Return / W / K）           10 分鐘
2. 開終端機，試玩 rg / fd / ff / bat / lt                    10 分鐘
3. 練習工作區切換（Super+1/2/3/4）與視窗移動                  15 分鐘
4. 挑一個喜歡的主題（Super+Ctrl+Shift+Space）                 5 分鐘
5. Menu → Update → Omarchy（做第一次更新）                    10 分鐘
6. Menu → Setup → Defaults → Editor（設定你要的編輯器）        5 分鐘
7. Menu → Install → Development（安裝 Java / Node，第 13 章）  20 分鐘
8. 設定 Git 與 SSH（第 16 章）                                20 分鐘
9. Menu → Setup → Defaults → Agent（設定 AI Agent，第 18 章）  10 分鐘

⚠️ 不要第一天就大改設定。先用預設兩週。

Day 1
  😖 一直找不到「開始按鈕」，反射性去摸滑鼠
  😖 開了視窗不知道怎麼關（一直找右上角的 X）
  ✅ 記住了 Super + Space 和 Super + Return
  效率：40%

Day 2-3
  😐 開始習慣 Super + W 關視窗
  😖 tiling 很不習慣，一直按 Super + T 切浮動
  ✅ 發現 Super + K 可以查快捷鍵
  效率：60%

Day 4-7
  🙂 工作區切換變成反射動作
  🙂 開始接受 tiling，不再手動排視窗
  ✅ 終端機工具鏈（rg / fd / ff）用得很順
  效率：85%

Week 2
  😀 手幾乎不離開鍵盤
  😀 發現「切換視窗不用思考」的爽感
  ✅ 開始用 tmux 版面函式（tdl）
  效率：100%+

Week 3-4
  🚀 開始覺得回去用 Windows 很卡
  🚀 AI Agent 工作流上手（第 18-23 章）
  效率：120%+

# 確認別名實際指向什麼
type a
type c
type cx
type cy

tmux ls              # 列出 session
tmux attach -t <n>   # 重新接上

Level 1 — 第 1 天（4 個）
  Super + Space     選單
  Super + Return    終端機
  Super + W         關視窗
  Super + K         查快捷鍵

Level 2 — 第 2–3 天（6 個）
  Super + 1/2/3/4          切工作區
  Super + Shift + 1/2/3/4  移動視窗
  Super + 方向鍵            切換焦點
  Super + F                全螢幕
  Super + Shift + Return   瀏覽器
  Super + Ctrl + V         剪貼簿歷史

Level 3 — 第 1 週（8 個）
  Super + Shift + Ctrl + A  ⭐ AI Agent
  Super + Alt + Return      tmux
  Print Screen              截圖
  Super + Ctrl + W/A/B      網路/音訊/藍牙面板
  Super + T                 浮動切換
  Super + S                 Scratchpad

Level 4 — 第 2 週以後
  Super + L                 scrolling layout
  Super + J / G / O         堆疊 / 群組 / 彈出
  Super + Ctrl + C          OCR
  Super + Ctrl + R          提醒
  tmux prefix 系列

一位團隊 lead 的實際做法：

第一週，他把 Level 1 + Level 2 的 10 個快捷鍵
用大字印在 A5 紙上貼在螢幕邊框。

第二週撕掉 Level 1（已經是反射動作），
換上 Level 3。

第三週撕掉整張紙。

結果：全團隊 5 人在 3 週內都完成過渡，
沒有人因為「記不住快捷鍵」而放棄。

關鍵：不要一開始就給人 60 個快捷鍵的表。
      給 4 個，用熟了再給 6 個。

Hyprland 負責                     omarchy-shell 負責
─────────────────────            ─────────────────────
視窗位置與大小（tiling）             頂端 bar
工作區切換                          應用啟動器
按鍵綁定                            通知
視窗動畫                            音量/亮度 OSD
多螢幕配置                          鎖定畫面
輸入裝置（鍵盤/滑鼠/觸控板）           桌布

# 步驟 1：先看官方預設長什麼樣
bat ~/.config/hypr/bindings.lua
bat ~/.config/hypr/monitors.lua
bat ~/.config/hypr/input.lua

# 步驟 2：備份（很重要）
cp ~/.config/hypr/bindings.lua ~/.config/hypr/bindings.lua.bak

# 步驟 3：或者更好的做法——先把 ~/.config 納入 Git（見第 43 章）
cd ~/.config && git init && git add . && git commit -m "初始設定"

# 步驟 4：修改
nvim ~/.config/hypr/bindings.lua

# 步驟 5：套用（Hyprland 通常會自動 reload；若無，重新載入設定）
hyprctl reload

症狀：App 顯示得非常大，像是被放大了

原因：GDK_SCALE 設為 2（適用於高 DPI 螢幕），
     但你用的是一般解析度螢幕

修改：~/.config/hypr/monitors.lua 中把 GDK_SCALE 從 2 改成 1

# 🔧 先確認 Hyprland 偵測到哪些螢幕
hyprctl monitors

# 輸出會包含：螢幕名稱（如 DP-1、HDMI-A-1）、解析度、更新率、位置

可以直接對 AI Agent 說：

「這是我的 hyprctl monitors 輸出：
 <貼上輸出>

 這是我目前的 ~/.config/hypr/monitors.lua：
 <貼上檔案內容>

 請幫我把 DP-1 設為主螢幕放在左邊，HDMI-A-1 放在右邊，
 兩個都用 1920x1080@60。
 請只輸出修改後的完整檔案，並說明你改了哪幾行。」

開第 1 個視窗           開第 2 個              開第 3 個
┌─────────────┐       ┌──────┬──────┐       ┌──────┬──────┐
│             │       │      │      │       │      │  B   │
│      A      │  →    │  A   │  B   │  →    │  A   ├──────┤
│             │       │      │      │       │      │  C   │
└─────────────┘       └──────┴──────┘       └──────┴──────┘

規則：新視窗會分割「目前有焦點的那個視窗」的空間，
     並交替橫向/縱向分割。

        ┌──────┬──────┬──────┬ ─ ─ ─ ┬ ─ ─ ─ ┐
        │  A   │  B   │  C   │   D   │   E   │
        │      │      │      │       │       │
        └──────┴──────┴──────┴ ─ ─ ─ ┴ ─ ─ ─ ┘
        ←─── 畫面可見範圍 ───→  ← 超出邊緣，可捲動 →

適合：需要同時開很多視窗（如比對 5 個檔案）

需求
  三螢幕：筆電內建 + 兩台外接 27" 4K

做法（利用 Lua 對 LLM 友善的特性）

  Step 1  收集現況
    $ hyprctl monitors > /tmp/monitors.txt
    $ cat ~/.config/hypr/monitors.lua

  Step 2  先備份（絕不能省）
    $ cd ~/.config && git add -A && git commit -m "改多螢幕設定前"

  Step 3  請 agent 產生設定
    $ omarchy agent prompt "讀取 /tmp/monitors.txt 與 \
      ~/.config/hypr/monitors.lua。請依照該檔案既有的 Lua 寫法， \
      把 eDP-1（筆電）放在中間下方，DP-1 放左上，DP-2 放右上， \
      外接螢幕用 3840x2160@60 並設 scale 1.5。 \
      先輸出你打算做的修改與理由，等我確認後再寫檔。"

  Step 4  ⭐ 自己 review agent 的修改
    $ git diff

  Step 5  套用並驗證
    $ hyprctl reload
    # 如果畫面爆掉：
    $ git checkout ~/.config/hypr/monitors.lua && hyprctl reload

  關鍵：因為有 Git，最壞情況是 10 秒還原，不是重灌。

# 🔧 查看 shell 程序狀態
systemctl --user status omarchy-shell

# 重啟 shell（bar 消失、通知失效時的第一招）
systemctl --user restart omarchy-shell

# 查看 shell 的日誌（排查 plugin 崩潰）
journalctl --user -u omarchy-shell -n 100 --no-pager

# 即時追蹤日誌
journalctl --user -u omarchy-shell -f

# 確認實際的 unit 名稱
systemctl --user list-units | grep -i omarchy

# 列出所有 plugin 與啟用狀態
omarchy plugin list

# 啟用 / 停用
omarchy plugin enable omarchy.tailscale
omarchy plugin disable omarchy.weather

# 安裝第三方 plugin
omarchy plugin add https://github.com/acme/omarchy-weather.git --enable

# 驗證 plugin（發布前必做）
omarchy plugin validate ./my-plugin

$OMARCHY_PATH/shell/plugins/     第一方（官方內建）
~/.config/omarchy/plugins/       第三方（你安裝的）

兩處在啟動時自動探索

# 看看 $OMARCHY_PATH 實際指向哪裡
echo $OMARCHY_PATH
ls -la $OMARCHY_PATH/shell/plugins/
ls -la ~/.config/omarchy/plugins/

# 審查用的實務指令（安裝前先手動 clone）
git clone https://github.com/acme/omarchy-weather.git /tmp/plugin-review
cd /tmp/plugin-review

# 檢查可疑呼叫
rg -n "Process|exec|spawn" --type qml
rg -n "XMLHttpRequest|fetch\(|http://|https://"
rg -n "\.ssh|\.aws|credentials|API_KEY|TOKEN|SECRET"
rg -n "FileView|readFile|writeFile"

# 看看整體規模（太大的 plugin 審查成本高）
tokei . 2>/dev/null || find . -name "*.qml" | xargs wc -l

# 檢視目前 bar 設定
jq '.bar' ~/.config/omarchy/shell.json

# 檢視完整 shell 設定
bat ~/.config/omarchy/shell.json

# ⚠️ 修改前先備份
cp ~/.config/omarchy/shell.json ~/.config/omarchy/shell.json.bak

# CLI 控制
omarchy bar --help

# 驗證 JSON 語法（沒有輸出錯誤 = 語法正確）
jq empty ~/.config/omarchy/shell.json && echo "✅ JSON 語法正確"

my-plugin/
├── manifest.json      宣告名稱、kind、進入點
└── Main.qml           QML 實作

# 1. 以官方 plugin 為範本（最可靠的學習方式）
ls $OMARCHY_PATH/shell/plugins/
cp -r $OMARCHY_PATH/shell/plugins/<某個簡單的 plugin> ~/my-plugin

# 2. 修改
cd ~/my-plugin && nvim manifest.json Main.qml

# 3. 驗證
omarchy plugin validate ~/my-plugin

# 4. 本機測試：放到第三方目錄
cp -r ~/my-plugin ~/.config/omarchy/plugins/
systemctl --user restart omarchy-shell

# 5. 看日誌確認有沒有錯誤
journalctl --user -u omarchy-shell -n 50 --no-pager

給 Agent 的 prompt 範本：

「請讀取 $OMARCHY_PATH/shell/plugins/ 底下的 2-3 個官方 plugin，
 分析它們的 manifest.json 結構與 QML 寫法。
 然後依照同樣的模式，幫我寫一個 bar-widget plugin，
 功能是顯示目前 Git repository 的分支名稱。
 請先說明你從官方 plugin 學到的結構，再寫程式碼。」

⚠️ 重點：讓 agent「先讀官方範例再寫」，
    而不是讓它憑記憶猜 API。

症狀
  開機後 bar 消失、通知不跳、鎖定畫面失效
  但視窗操作正常（Hyprland 活著）

排查步驟

  1. 確認是 shell 層問題
     $ systemctl --user status omarchy-shell
     → 顯示 failed 或 activating (auto-restart)

  2. 看日誌找根因
     $ journalctl --user -u omarchy-shell -n 200 --no-pager | grep -i error
     → 發現：TypeError: Cannot read property 'price' of undefined
        at file:///home/user/.config/omarchy/plugins/stock-widget/Main.qml:47

  3. 定位到 plugin
     → stock-widget，網路異常時未處理例外

  4. 停用
     $ omarchy plugin disable stock-widget
     $ systemctl --user restart omarchy-shell
     → ✅ bar 恢復

  5. 決策
     選項 A：移除該 plugin
     選項 B：自己修（加 null check）並發 PR 給作者

如果 bar 消失導致無法操作：
  Ctrl + Alt + F2 進 TTY，用上述指令處理，
  然後 Ctrl + Alt + F1 回到桌面。

# 探索用的第一組指令
omarchy --help          # 看所有指令群
omarchy <group> --help  # 看某一群的子指令

omarchy capture qr                  # 從截圖區域解析 QR code
omarchy capture text                # OCR 文字擷取
omarchy capture screenrecording     # 開始/停止螢幕錄影
omarchy capture webcam resize       # 調整 webcam 疊加視窗

# 截圖：[模式] [輸出方式]
omarchy capture screenshot smart copy
omarchy capture screenshot region save
omarchy capture screenshot windows copy
omarchy capture screenshot fullscreen save

omarchy menu                    # 開啟根選單
omarchy menu <path>             # 直接跳到指定位置
omarchy menu toggle <section>   # 切換選單區段
omarchy menu close              # 關閉選單

omarchy agent                       # AI coding agent 用量資料
omarchy default agent <name>        # 設定預設 agent
omarchy agent prompt "task"         # 帶著任務啟動 agent

# 📘 官方：列出所有指令群
omarchy commands

# 📘 官方：展開到每一個子指令
omarchy commands --all

# 📘 官方：⭐ JSON 輸出——這是給 agent / 腳本用的
omarchy commands --all --json

# 💡 實務：把官方指令清單轉成 agent 允許清單的素材
omarchy commands --all --json | jq -r '.. | .name? // empty' | sort -u

# 💡 比對這次升級新增／移除了哪些指令（升級後值得跑一次）
omarchy commands --all --json > ~/.cache/omarchy-cmds-new.json
diff <(jq -S . ~/.cache/omarchy-cmds-old.json) \
     <(jq -S . ~/.cache/omarchy-cmds-new.json)

# 完整探索一個指令群
omarchy plugin --help
omarchy channel --help
omarchy capture --help
omarchy bar --help
omarchy agent --help

# 任何層級都可以加 --help
omarchy capture screenshot --help

# 找出所有 omarchy-* 開頭的獨立指令
compgen -c | grep '^omarchy' | sort -u

# 看某個指令實際是什麼（script? 別名? 函式?）
type omarchy
type omarchy-snapshot
type omarchy-channel-set

# 如果是 script，直接讀它（最可靠的文件）
bat "$(which omarchy-snapshot)"

# 看 repo 裡的所有可執行檔（最完整的清單）
ls -1 "$OMARCHY_PATH/bin/" | sort

情境
  要讓 Claude Code 能自主處理系統相關任務，
  但不能做危險操作。

做法（以 Claude Code 的 settings 為例，概念可套用到其他 agent）

  ✅ 自動允許（Safe）
     omarchy debug
     omarchy plugin list
     omarchy theme list
     omarchy agent
     omarchy menu close
     systemctl --user status omarchy-shell
     journalctl --user -u omarchy-shell*

  ⚠️ 需要人工確認（Caution）
     omarchy update
     omarchy theme set *
     omarchy plugin enable *
     omarchy plugin disable *
     systemctl --user restart omarchy-shell

  ❌ 完全禁止（Destructive）
     omarchy-reinstall
     omarchy plugin add *
     omarchy-sudo-passwordless
     sudo *
     pacman *
     yay *

驗證方式
  請 agent 試著執行一個 Destructive 指令，
  確認它被擋下來，而不是靜默執行。

想裝 Node.js 20？
  ① pacman -S nodejs          → 只能裝一個版本，且會跟著系統更新
  ② yay -S nodejs-lts-iron    → AUR，同樣只能一個版本
  ③ mise use -g node@20       → ⭐ 可多版本共存，專案可各自指定
  ④ nvm install 20            → 又一套版本管理器，與 mise 打架
  ⑤ docker run node:20        → 完全隔離，但開發體驗差

❌ 主機安裝 PostgreSQL 的問題
   - 專案 A 要 PG 14，專案 B 要 PG 16 → 衝突
   - 系統更新可能自動升級 PG 大版本 → 資料格式不相容
   - 想重置測試資料要手動清 → 容易誤刪
   - 團隊每個人的 PG 設定都不一樣 → 「在我機器上可以」
   - Omarchy 是 rolling release → 這個風險特別高

✅ Container 安裝 PostgreSQL 的好處
   - 版本寫在 compose.yaml，跟著專案走
   - docker compose down -v 一秒重置
   - 團隊每個人跑的是同一個 image
   - 與 CI / production 一致
   - 不受系統更新影響

# 安裝（官方推薦的方式）
omarchy pkg add <package>
# 或 Menu → Install → Package（有模糊搜尋）

# 移除（會一併移除設定檔與相依）
omarchy pkg drop <package>
# 或 Menu → Remove → Package

pacman -Q                    # 列出已安裝套件
pacman -Qs java              # 搜尋已安裝的套件
pacman -Ss ripgrep           # 搜尋可安裝的套件
pacman -Qi git               # 看某個套件的詳細資訊
pacman -Ql git               # 列出某套件安裝了哪些檔案
pacman -Qo /usr/bin/rg       # 這個檔案屬於哪個套件？
pacman -Qdt                  # 列出孤兒套件（沒有東西依賴它們）

全域版本（machine-wide 預設）
    ↓ 被覆寫
專案版本（該目錄及子目錄）
    ↓ 被覆寫
Shell 版本（目前這個終端機 session）

# ── 查詢 ──
mise ls                      # 已安裝的版本
mise ls-remote java           # 可安裝的 Java 版本
mise current                  # 目前生效的版本
mise doctor                   # 診斷 mise 設定問題

# ── 全域安裝 ──
mise use -g java@temurin-25   # 全域預設 Java 25
mise use -g node@22           # 全域預設 Node 22

# ── 專案層級 ──
cd ~/projects/my-app
mise use java@temurin-21      # 只在這個專案用 Java 21
mise use node@20
# → 會產生 .mise.toml，應納入 Git

# ── 依既有設定檔安裝 ──
mise i                        # 📘 官方：讀 .ruby-version / .nvmrc / .mise.toml 等

# ── 一次性執行（不改變設定）──
mise x java@17 -- java -version
mise x node@18 -- npm test

# ~/projects/my-app/.mise.toml
# ⭐ 這個檔案應該進 Git —— 它讓團隊每個人的 runtime 版本一致

[tools]
java = "temurin-25"
node = "22"
python = "3.12"

[env]
# 專案專屬環境變數（⚠️ 不要放 secrets）
SPRING_PROFILES_ACTIVE = "local"
JAVA_TOOL_OPTIONS = "-Dfile.encoding=UTF-8"

症狀
  $ java -version   → 顯示 Java 17
  $ mvn -v          → 顯示 Java 21
  $ echo $JAVA_HOME → 指向一個不存在的路徑
  IntelliJ 用的又是第三個 Java

根因調查
  $ which -a java
    /home/user/.local/share/mise/installs/java/temurin-21/bin/java
    /usr/lib/jvm/java-17-openjdk/bin/java        ← pacman 裝的
    /home/user/.sdkman/candidates/java/current/bin/java  ← 還有 SDKMAN！

  $ pacman -Qs jdk
    jdk-openjdk 17...      ← 誰裝的？

  → 三套版本管理器並存：pacman + mise + SDKMAN

整理流程
  1. 決定唯一真相來源：mise
  2. 移除 SDKMAN
     ⚠️ DANGER：rm -rf 是永久刪除，沒有資源回收桶。
        執行前先確認路徑正確，並確認 SDKMAN 底下沒有你要保留的東西。
     $ ls ~/.sdkman/candidates/        # 先看裡面有什麼
     $ rm -rf ~/.sdkman                # 確認後才刪
     $ 從 ~/.bashrc 移除 SDKMAN 的初始化行
  3. 移除 pacman 的 JDK
     $ omarchy pkg drop jdk-openjdk
  4. 清空 JAVA_HOME 的手動設定，交給 mise
     $ 從 ~/.bashrc 移除 export JAVA_HOME=...
  5. 用 mise 統一
     $ mise use -g java@temurin-25
  6. 每個專案宣告自己的版本
     $ cd ~/projects/legacy-app && mise use java@temurin-8
     $ cd ~/projects/new-app && mise use java@temurin-25
  7. 驗證
     $ mise doctor
     $ mise current
     $ cd ~/projects/legacy-app && java -version   # 應顯示 8
     $ cd ~/projects/new-app && java -version      # 應顯示 25

結果
  ✅ 每個專案的 .mise.toml 進 Git，團隊版本一致
  ✅ 「在我機器上可以」的問題消失
  ✅ AI Agent 也能正確判斷專案用哪個版本（讀 .mise.toml）

# 貼上執行，看看有什麼還沒裝
for c in git gh rg fd fzf bat eza zoxide jq yq tmux mise docker lazygit ssh gpg; do
  if command -v "$c" >/dev/null 2>&1; then
    printf "✅ %-10s %s\n" "$c" "$(command -v "$c")"
  else
    printf "❌ %-10s 未安裝\n" "$c"
  fi
done

# 安裝前先確認套件名稱
pacman -Ss yq
pacman -Ss delta
pacman -Ss tokei

# 方式 A：JetBrains Toolbox（推薦——自動更新、多版本管理）
#   到 https://www.jetbrains.com/toolbox-app/ 下載 .tar.gz
#   解壓後執行 jetbrains-toolbox，之後由它管理所有 JetBrains IDE

# 方式 B：AUR
yay -G intellij-idea-community-edition   # ① 先下載
bat intellij-idea-community-edition/PKGBUILD  # ② 讀過再裝
yay -S intellij-idea-community-edition   # ③ 安裝

最低限度的 Neovim 求生技能（用於在 TTY 救援時改設定）

  i          進入插入模式（可以打字）
  Esc        回到一般模式
  :w         儲存
  :q         離開
  :wq        儲存並離開
  :q!        不儲存強制離開   ← 最重要的一個
  /關鍵字     搜尋
  dd         刪除一行
  u          復原

00:00  確認基礎工具（跑 13.2 的檢查腳本）
00:03  omarchy update（確保基準最新）
00:10  Menu → Setup → Defaults → Editor（設定 VS Code）
00:12  安裝 IntelliJ（JetBrains Toolbox）
00:20  設定 Git 與 SSH（第 16 章）
00:35  mise use -g java@temurin-25
       mise use -g node@22
00:40  Menu → Setup → Defaults → Agent（設定預設 AI Agent，第 18 章）
00:45  gh auth login
00:48  git clone 第一個專案
00:50  cd 專案 && mise i        # 讀 .mise.toml 裝對版本
00:52  docker compose up -d     # 起 DB / Redis
00:55  mvn test                 # 驗證
00:58  tdl                      # ⭐ 開出 編輯器 + agent + 終端機
01:00  ✅ 開始工作

⚠️ 這 60 分鐘裡完全沒有裝：
   PostgreSQL、Redis、Kafka（都在容器裡）
   多餘的 AUR 套件
   用不到的語言 runtime

# 看看有哪些 Java 版本可裝
mise ls-remote java | grep temurin | tail -30

# 全域預設（本手冊建議用最新 LTS 作為全域預設）
mise use -g java@temurin-25

# 驗證
java -version
echo $JAVA_HOME
mise current java

cd ~/projects/legacy-erp
mise use java@temurin-8        # 產生 .mise.toml
cat .mise.toml
# [tools]
# java = "temurin-8"

# ⭐ 把 .mise.toml 加入版控——這是團隊版本一致的關鍵
git add .mise.toml
git commit -m "chore: 宣告本專案使用 Java 8"

# 之後任何人 clone 下來
mise i        # 📘 官方：自動裝對版本

# 用 mise 安裝（可多版本）
mise use -g maven@3.9
mvn -v

# 或用 pacman（單一版本，較簡單）
omarchy pkg add maven

<?xml version="1.0" encoding="UTF-8"?>
<settings xmlns="http://maven.apache.org/SETTINGS/1.0.0">

  <!-- 內部 Nexus / Artifactory 作為所有請求的鏡像 -->
  <mirrors>
    <mirror>
      <id>corp-nexus</id>
      <name>公司內部 Maven Repository</name>
      <url>https://nexus.corp.example.com/repository/maven-public/</url>
      <mirrorOf>*</mirrorOf>
    </mirror>
  </mirrors>

  <servers>
    <server>
      <id>corp-nexus</id>
      <username>${env.NEXUS_USER}</username>
      <!-- ⚠️ 不要在這裡寫明文密碼。用環境變數，或 mvn --encrypt-password -->
      <password>${env.NEXUS_TOKEN}</password>
    </server>
  </servers>

</settings>

mvn clean install                       # 完整建置
mvn clean install -DskipTests           # 跳過測試（快速編譯驗證）
mvn test                                # 只跑測試
mvn test -Dtest=UserServiceTest         # 單一測試類別
mvn dependency:tree                     # ⭐ 相依樹（逆向工程必備）
mvn dependency:analyze                  # 找出宣告了但沒用到的相依
mvn versions:display-dependency-updates # ⭐ 可升級的相依（升版必備）
mvn versions:display-plugin-updates     # 可升級的 plugin
mvn help:effective-pom                  # 展開後的完整 POM
mvn -o clean install                    # 離線模式

mise use -g gradle@8
gradle -v

# 但實務上，專案通常自帶 wrapper——優先用它
./gradlew build
./gradlew test
./gradlew dependencies      # ⭐ 相依樹

# 方式 A：Spring Initializr（推薦，不需額外裝工具）
curl https://start.spring.io/starter.zip \
  -d type=maven-project \
  -d language=java \
  -d javaVersion=25 \
  -d bootVersion=4.0.0 \
  -d groupId=com.example \
  -d artifactId=demo \
  -d name=demo \
  -d packageName=com.example.demo \
  -d dependencies=web,data-jpa,postgresql,validation,actuator \
  -o demo.zip

unzip demo.zip -d demo && cd demo

# ⭐ 立刻宣告 runtime 版本
mise use java@temurin-25

# compose.yaml — 本機開發用的服務
# ⭐ 版本鎖定在這裡，跟著專案走，不是跟著機器走
services:
  postgres:
    image: postgres:16-alpine
    environment:
      POSTGRES_DB: demo
      POSTGRES_USER: demo
      POSTGRES_PASSWORD: demo_local_only   # ⚠️ 僅限本機開發，勿用於任何其他環境
    ports:
      - "127.0.0.1:5432:5432"              # ⭐ 只綁 localhost，不對外
    volumes:
      - pgdata:/var/lib/postgresql/data
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U demo -d demo"]
      interval: 5s
      timeout: 3s
      retries: 10

  redis:
    image: redis:7-alpine
    ports:
      - "127.0.0.1:6379:6379"
    healthcheck:
      test: ["CMD", "redis-cli", "ping"]
      interval: 5s
      timeout: 3s
      retries: 10

volumes:
  pgdata:

# 啟動
docker compose up -d

# 確認健康狀態
docker compose ps

# 看日誌
docker compose logs -f postgres

# ⚠️ DANGER：-v 會刪除 volume（資料全消失）
docker compose down -v     # 只在你確定要重置測試資料時用

# src/main/resources/application-local.yml
spring:
  datasource:
    url: jdbc:postgresql://localhost:5432/demo
    username: demo
    password: demo_local_only
  jpa:
    hibernate:
      ddl-auto: validate        # ⚠️ 絕不要用 create-drop 以外的破壞性設定於非本機
    properties:
      hibernate:
        format_sql: true
  data:
    redis:
      host: localhost
      port: 6379

logging:
  level:
    org.springframework.web: DEBUG
    org.hibernate.SQL: DEBUG

management:
  endpoints:
    web:
      exposure:
        include: health,info,metrics    # ⚠️ 不要在 production 開放全部 endpoint

# 啟動應用
./mvnw spring-boot:run -Dspring-boot.run.profiles=local

# 或用 mise 的環境變數
SPRING_PROFILES_ACTIVE=local ./mvnw spring-boot:run

File → Project Structure → SDKs → + → Add JDK
路徑：~/.local/share/mise/installs/java/<版本>/

例如：
  ~/.local/share/mise/installs/java/temurin-25/

# 找出實際路徑
mise where java@temurin-25
ls ~/.local/share/mise/installs/java/

// .vscode/settings.json（放在專案內，可進 Git）
{
  // ⭐ 指向 mise 管理的 JDK
  "java.configuration.runtimes": [
    {
      "name": "JavaSE-25",
      "path": "/home/YOUR_USER/.local/share/mise/installs/java/temurin-25",
      "default": true
    },
    {
      "name": "JavaSE-1.8",
      "path": "/home/YOUR_USER/.local/share/mise/installs/java/temurin-8"
    }
  ],
  "java.compile.nullAnalysis.mode": "automatic",
  "java.format.settings.url": "https://raw.githubusercontent.com/google/styleguide/gh-pages/eclipse-java-google-style.xml",
  "files.encoding": "utf8",
  "editor.formatOnSave": true
}

Extension Pack for Java       （Microsoft）
Spring Boot Extension Pack    （VMware）

# AGENTS.md

## 專案技術棧

- Java 25（由 `.mise.toml` 宣告，請勿改動）
- Spring Boot 4.0.x
- PostgreSQL 16（容器，見 `compose.yaml`）
- Maven（請一律使用 `./mvnw`，不要用系統的 `mvn`）

## 開發環境

```bash
docker compose up -d              # 先起相依服務
./mvnw spring-boot:run -Dspring-boot.run.profiles=local
```

## 你（Agent）必須遵守的規則

1. **不要修改 `.mise.toml`** — runtime 版本由團隊統一決定
2. **不要在程式碼中寫死任何密碼、token 或連線字串** — 一律走設定檔或環境變數
3. **修改程式碼後一律執行** `./mvnw test`，測試沒過就不算完成
4. **不要執行 `docker compose down -v`** — 那會刪掉本機測試資料
5. **不要 `git push`** — 由人類決定何時推送
6. **新增相依前先問** — 我們有內部 Nexus，不是所有套件都可用
7. 遵循既有的 package 結構：`controller` / `service` / `repository` / `domain`

## 常用指令

```bash
./mvnw dependency:tree                        # 相依樹
./mvnw versions:display-dependency-updates    # 可升級的相依
./mvnw test -Dtest=UserServiceTest            # 單一測試
```

情境
  一位工程師同時負責：
  - legacy-erp     Java 8  + Spring Boot 2.7
  - core-api       Java 21 + Spring Boot 3.3
  - new-portal     Java 25 + Spring Boot 4.0

傳統做法的痛苦
  ❌ 手動改 JAVA_HOME，常常忘記改回來
  ❌ IntelliJ 三個專案設定不同 SDK，切換時常出錯
  ❌ mvn 在錯的 Java 版本下跑，錯誤訊息看不懂

mise 的做法
  # 每個專案宣告自己的版本（各自的 .mise.toml，都進 Git）
  $ cd ~/projects/legacy-erp && mise use java@temurin-8
  $ cd ~/projects/core-api   && mise use java@temurin-21
  $ cd ~/projects/new-portal && mise use java@temurin-25

  # 之後只要 cd 進去，版本自動切換
  $ cd ~/projects/legacy-erp && java -version   # → 8
  $ cd ~/projects/core-api   && java -version   # → 21

搭配 Omarchy 的 tdl 與 git worktree
  # 用工作區分開三個專案
  Workspace 1  →  cd ~/projects/legacy-erp && tdl
  Workspace 2  →  cd ~/projects/core-api && tdl
  Workspace 3  →  cd ~/projects/new-portal && tdl

  每個 tdl 都是「編輯器 + AI Agent + 終端機」，
  且各自在正確的 Java 版本下。

  ⭐ AI Agent 也吃到正確的版本 ——
     它跑 ./mvnw test 時用的是該專案宣告的 Java。

# 安裝 Node（用 mise）
mise ls-remote node | tail -20
mise use -g node@22            # 全域用最新 LTS

# 驗證
node -v
npm -v

# 安裝 pnpm（推薦）
# 方式 A：mise
mise use -g pnpm@latest
# 方式 B：corepack（Node 內建）
corepack enable
corepack prepare pnpm@latest --activate

cd ~/projects
pnpm create vue@latest

✔ Project name              … my-portal
✔ TypeScript                … Yes      ⭐ 強烈建議
✔ JSX Support               … No
✔ Vue Router                … Yes
✔ Pinia (state management)  … Yes
✔ Vitest (unit testing)     … Yes      ⭐ 讓 AI Agent 有測試可跑
✔ End-to-End Testing        … Playwright
✔ ESLint                    … Yes
✔ Prettier                  … Yes

cd my-portal

# ⭐ 立刻宣告 Node 版本並進 Git
mise use node@22
git add .mise.toml

pnpm install
pnpm dev        # → http://localhost:5173

pnpm add -D tailwindcss @tailwindcss/vite

import { fileURLToPath, URL } from 'node:url'
import { defineConfig } from 'vite'
import vue from '@vitejs/plugin-vue'
import tailwindcss from '@tailwindcss/vite'

export default defineConfig({
  plugins: [vue(), tailwindcss()],
  resolve: {
    alias: {
      '@': fileURLToPath(new URL('./src', import.meta.url)),
    },
  },
  server: {
    port: 5173,
    // ⭐ 把 /api 轉發到本機的 Spring Boot，避免 CORS 問題
    proxy: {
      '/api': {
        target: 'http://localhost:8080',
        changeOrigin: true,
      },
    },
  },
})

@import "tailwindcss";

pnpm add primevue @primeuix/themes
pnpm add -D @primevue/auto-import-resolver unplugin-vue-components

import { createApp } from 'vue'
import { createPinia } from 'pinia'
import PrimeVue from 'primevue/config'
import Aura from '@primeuix/themes/aura'

import App from './App.vue'
import router from './router'
import './assets/main.css'

const app = createApp(App)

app.use(createPinia())
app.use(router)
app.use(PrimeVue, {
  theme: {
    preset: Aura,
    options: {
      // 讓 Tailwind 的 utility class 能覆蓋 PrimeVue 樣式
      cssLayer: {
        name: 'primevue',
        order: 'theme, base, primevue',
      },
    },
  },
})

app.mount('#app')

pnpm create vite@latest my-react-app -- --template react-ts
cd my-react-app && mise use node@22 && pnpm install && pnpm dev

# Angular CLI 建議裝在專案內或用 npx，避免全域版本衝突
pnpm dlx @angular/cli@latest new my-ng-app
cd my-ng-app && mise use node@22 && pnpm install && pnpm start

pnpm create next-app@latest my-next-app     # React SSR
pnpm create nuxt@latest my-nuxt-app         # Vue SSR

主力瀏覽器（日常）        →  一個
開發測試用（乾淨 profile） →  另一個，或用 --user-data-dir 另開 profile

理由：擴充套件（廣告阻擋、密碼管理）會干擾前端開發除錯

# 開一個乾淨的測試 profile（🔧 一般 Chromium 用法）
chromium --user-data-dir=/tmp/chrome-dev-profile http://localhost:5173

# AGENTS.md

## 技術棧

- Vue 3（Composition API + `<script setup>`）
- TypeScript（strict 模式）
- Vite
- Tailwind CSS
- PrimeVue
- Pinia（狀態管理）
- Vitest（單元測試）+ Playwright（E2E）
- **pnpm**（請勿使用 npm 或 yarn）

## 常用指令

```bash
pnpm install
pnpm dev            # 開發伺服器 :5173
pnpm build          # 正式建置
pnpm test:unit      # 單元測試
pnpm lint           # ESLint
pnpm type-check     # TypeScript 檢查
```

## 你（Agent）必須遵守的規則

1. **一律使用 `pnpm`**，不要用 `npm install` 或 `yarn`
2. **元件一律用 `<script setup lang="ts">`**，不要用 Options API
3. **不要使用 `any`** — 需要時用 `unknown` 加型別守衛
4. **樣式優先用 Tailwind utility class**，避免寫 scoped CSS
5. **新增元件後必須加對應的 Vitest 測試**
6. **改完程式碼一律執行**：`pnpm type-check && pnpm lint && pnpm test:unit`
7. **不要修改 `.mise.toml`**
8. **不要 `git push`**

## 目錄結構

```text
src/
├── components/     可複用元件
├── views/          路由頁面
├── stores/         Pinia stores
├── composables/    可複用邏輯
├── api/            API client
└── types/          TypeScript 型別定義
```

情境
  Vue 3 前端 + Spring Boot 後端，需要同時開發與除錯

Omarchy 上的配置

  Workspace 1 — 後端
    $ cd ~/projects/api && tdl
    ┌────────────┬────────────┐
    │  Neovim    │ AI Agent   │
    │  (程式碼)   │ (claude)   │
    ├────────────┴────────────┤
    │  ./mvnw spring-boot:run │
    └─────────────────────────┘

  Workspace 2 — 前端
    $ cd ~/projects/portal && tdl
    ┌────────────┬────────────┐
    │  VS Code   │ AI Agent   │
    │            │            │
    ├────────────┴────────────┤
    │  pnpm dev               │
    └─────────────────────────┘

  Workspace 3 — 瀏覽器
    Super + Shift + Return
    → http://localhost:5173（Vite 的 proxy 會把 /api 轉到 :8080）

  Workspace 4 — 容器與日誌
    $ docker compose logs -f
    Super + Shift + D  (lazydocker)

切換成本
  Super + 1/2/3/4，零延遲，手不離鍵盤。

⭐ 關鍵設定
  vite.config.ts 的 server.proxy 把 /api → localhost:8080
  → 前端不用處理 CORS，也不用改 API base URL

# 身分（⭐ 這會出現在每個 commit 上）
git config --global user.name "你的名字"
git config --global user.email "you@company.com"

# 預設分支名稱
git config --global init.defaultBranch main

# 換行處理（Linux 上）
git config --global core.autocrlf input

# ⭐ 中文檔名不要被轉義成八進位
git config --global core.quotepath false

# 有裝 delta 的話（更好看的 diff）
git config --global core.pager "delta"
git config --global interactive.diffFilter "delta --color-only"
git config --global delta.navigate true

# pull 時用 rebase 而非 merge（避免無意義的 merge commit）
git config --global pull.rebase true

# 記住衝突解法
git config --global rerere.enabled true

# 確認結果
git config --global --list

# ⭐ 用 ed25519（比 RSA 更短更安全）
ssh-keygen -t ed25519 -C "you@company.com" -f ~/.ssh/id_ed25519_company

# ⚠️ 一定要設 passphrase
#    有 passphrase + ssh-agent = 安全又方便

# 啟動 agent 並加入金鑰
eval "$(ssh-agent -s)"
ssh-add ~/.ssh/id_ed25519_company

# 列出已載入的金鑰
ssh-add -l

# ~/.bashrc 末端加入
if [ -z "$SSH_AUTH_SOCK" ]; then
  eval "$(ssh-agent -s)" > /dev/null
fi

ssh-keygen -t ed25519 -C "personal@gmail.com"     -f ~/.ssh/id_ed25519_personal
ssh-keygen -t ed25519 -C "you@company.com"        -f ~/.ssh/id_ed25519_ghe
ssh-keygen -t ed25519 -C "you@company.com"        -f ~/.ssh/id_ed25519_gitlab

chmod 600 ~/.ssh/id_ed25519_*
chmod 644 ~/.ssh/id_ed25519_*.pub

# ~/.ssh/config
# ⭐ 這是多帳號並存的核心

# ── 全域預設 ──
Host *
    AddKeysToAgent yes
    IdentitiesOnly yes            # ⭐ 只用指定的金鑰，不要把所有金鑰都試一遍
    ServerAliveInterval 60
    ServerAliveCountMax 3

# ── 個人 GitHub ──
Host github-personal
    HostName github.com
    User git
    IdentityFile ~/.ssh/id_ed25519_personal

# ── 公司 GitHub Enterprise ──
Host github-work
    HostName github.com
    User git
    IdentityFile ~/.ssh/id_ed25519_ghe

# ── 自架 GitHub Enterprise Server（若有）──
Host ghe.corp.example.com
    HostName ghe.corp.example.com
    User git
    IdentityFile ~/.ssh/id_ed25519_ghe

# ── 公司 GitLab ──
Host gitlab.corp.example.com
    HostName gitlab.corp.example.com
    User git
    IdentityFile ~/.ssh/id_ed25519_gitlab
    Port 22

# ── 需要跳板機的 GitLab（企業常見）──
# Host gitlab-internal
#     HostName gitlab.internal.corp
#     User git
#     IdentityFile ~/.ssh/id_ed25519_gitlab
#     ProxyJump bastion.corp.example.com

chmod 600 ~/.ssh/config

# 個人專案
git clone git@github-personal:myname/my-side-project.git

# 公司專案
git clone git@github-work:mycompany/backend-api.git

# GitLab
git clone git@gitlab.corp.example.com:team/internal-tool.git

ssh -T git@github-personal    # 應顯示 "Hi myname!"
ssh -T git@github-work        # 應顯示 "Hi work-username!"
ssh -T git@gitlab.corp.example.com

# 除錯用（看它實際用了哪把金鑰）
ssh -vT git@github-work 2>&1 | grep -i "offering\|identity"

[user]
    name = 你的名字
    email = personal@gmail.com      # 預設用個人身分

[init]
    defaultBranch = main

[core]
    quotepath = false
    autocrlf = input

[pull]
    rebase = true

# ⭐ 只要 repo 在 ~/work/ 底下，就套用公司身分
[includeIf "gitdir:~/work/"]
    path = ~/.gitconfig-work

# 公司 GitLab 專案
[includeIf "gitdir:~/gitlab/"]
    path = ~/.gitconfig-work

[user]
    name = 你的名字
    email = you@company.com

[commit]
    gpgsign = true                  # 公司要求簽章的話

[user]
    signingkey = YOUR_GPG_KEY_ID

cd ~/personal/side-project && git config user.email   # → personal@gmail.com
cd ~/work/backend-api && git config user.email        # → you@company.com

# 登入
gh auth login
#   選 GitHub.com 或 GitHub Enterprise Server
#   選 SSH 作為協定
#   選擇要使用的 SSH 公鑰

# 檢查狀態
gh auth status

# clone 私有 repo
gh repo clone myorg/private-repo

# 常用
gh repo view --web              # 在瀏覽器開啟
gh pr create                    # 建立 PR
gh pr list                      # 列出 PR
gh pr checkout 123              # 切到某個 PR 的分支
gh pr diff 123                  # 看 PR 的 diff
gh pr review 123 --approve
gh issue list
gh run list                     # GitHub Actions 執行紀錄
gh run watch                    # 即時看 CI 狀態

# 加入第二個帳號
gh auth login --hostname github.com

# 切換
gh auth switch

# 針對企業版
gh auth login --hostname ghe.corp.example.com

omarchy pkg add glab

# 認證（自架 GitLab）
glab auth login --hostname gitlab.corp.example.com

# 常用
glab mr create
glab mr list
glab ci status
glab ci view

# 產生金鑰
gpg --full-generate-key
#   選 (1) RSA and RSA 或 (9) ECC
#   金鑰長度 4096（RSA）
#   有效期建議設 2 年，到期再續

# 取得金鑰 ID
gpg --list-secret-keys --keyid-format=long
# sec   ed25519/ABCD1234EFGH5678 2026-09-05 [SC]

# 設定 Git
git config --global user.signingkey ABCD1234EFGH5678
git config --global commit.gpgsign true
git config --global tag.gpgsign true

# 匯出公鑰貼到 GitHub / GitLab
gpg --armor --export ABCD1234EFGH5678

# 建立新的 worktree 與分支，並切進去
ga feature/user-export

# 現在你在一個獨立的目錄裡，與主 repo 分開
pwd    # → ~/projects/backend-api-feature-user-export（或類似路徑）

# 完成後移除 worktree 與分支（會確認）
gd

❌ 不用 worktree
   Agent 在你的主工作目錄改東西
   → 你正在改的檔案被覆蓋
   → 想比對「改前 vs 改後」要一直 git stash
   → 兩個 agent 同時工作會互相衝突

✅ 用 worktree
   ~/projects/api              main 分支，你自己在用
   ~/projects/api-upgrade      Agent A 在做 Spring Boot 升版
   ~/projects/api-feature-x    Agent B 在做新功能

   → 完全隔離，互不影響
   → 可以同時開三個 tdl，各跑一個 agent
   → 隨時可以 diff 比對
   → 出事只要 gd 就乾淨移除

git worktree list
git worktree add ../api-upgrade -b feature/spring-boot-4
git worktree remove ../api-upgrade
git worktree prune                    # 清理已消失目錄的紀錄

# 開分支
git switch -c feature/user-export

# ⭐ 或用 worktree（AI Agent 場景）
ga feature/user-export

# 工作、commit
git add -p                    # ⭐ 逐塊確認要 commit 什麼
git commit -m "feat: 新增使用者匯出 API"

# 推送並建立 PR
git push -u origin feature/user-export
gh pr create --fill

# 看 CI
gh run watch

需求
  個人 GitHub（開源專案）
  公司 GitHub Enterprise（主要工作）
  公司 GitLab（內部工具）

完整設定

  ① 目錄規劃（讓 includeIf 能生效）
     ~/personal/     個人專案
     ~/work/         公司 GitHub 專案
     ~/gitlab/       公司 GitLab 專案

  ② 三把 SSH 金鑰（16.3）
  ③ ~/.ssh/config 用 Host 別名區分（16.3）
  ④ ~/.gitconfig + includeIf 依目錄切 email（16.4）
  ⑤ gh auth login 兩個帳號 + glab auth login

  驗證清單
  $ cd ~/personal/xxx && git config user.email   # personal@gmail.com
  $ cd ~/work/xxx && git config user.email       # you@company.com
  $ ssh -T git@github-personal                   # Hi myname!
  $ ssh -T git@github-work                       # Hi work-username!
  $ gh auth status                               # 兩個帳號都在
  $ cd ~/work/xxx && git log -1 --format='%an <%ae>'   # 確認最後一筆 commit 身分正確

  ⭐ 最後一項驗證最重要 ——
     設定看起來對，不代表 commit 真的用了對的身分。

# 🔧 檢查 SSH 服務狀態（作為 server）
systemctl status sshd

# 檢查防火牆
sudo ufw status verbose

# ~/.ssh/config

Host *
    AddKeysToAgent yes
    IdentitiesOnly yes
    ServerAliveInterval 60          # 每 60 秒送一次 keepalive
    ServerAliveCountMax 3           # 連續 3 次沒回應才斷線
    Compression yes
    HashKnownHosts yes

# ── 開發伺服器 ──
Host dev
    HostName dev.corp.example.com
    User myuser
    IdentityFile ~/.ssh/id_ed25519_corp
    # ⭐ 連線複用：第二次以後的連線秒開
    ControlMaster auto
    ControlPath ~/.ssh/sockets/%r@%h:%p
    ControlPersist 10m

# ── 跳板機模式（企業常見）──
Host prod-app-01
    HostName 10.0.1.10
    User myuser
    IdentityFile ~/.ssh/id_ed25519_corp
    ProxyJump bastion               # ⭐ 自動經由跳板機

Host bastion
    HostName bastion.corp.example.com
    User myuser
    IdentityFile ~/.ssh/id_ed25519_corp
    Port 2222

# ── 需要 SOCKS proxy 的環境 ──
# Host external-git
#     HostName github.com
#     User git
#     ProxyCommand nc -X 5 -x 127.0.0.1:1080 %h %p

# ControlPath 需要目錄先存在
mkdir -p ~/.ssh/sockets && chmod 700 ~/.ssh/sockets
chmod 600 ~/.ssh/config

# 把遠端主機的 port 轉發到 localhost
fip

# 列出所有作用中的轉發
lip

# 中斷轉發
dip

遠端資料庫在內網，本機的 IntelliJ / DBeaver 要連
  → fip 把 remote:5432 轉到 localhost:15432
  → IntelliJ 連 localhost:15432
  → 不需要開放資料庫對外，也不需要 VPN 全域路由

# 本地轉發：localhost:15432 → 透過 dev → db.internal:5432
ssh -L 15432:db.internal:5432 -N dev

# 動態轉發（SOCKS proxy）
ssh -D 1080 -N bastion

# 來源有變動就自動 rsync 到目的地
rsw ./src user@dev:/opt/app/src

lsw     # 列出所有 watcher
dsw     # 停止所有 watcher

Agent 跑在本機 Omarchy
   ↓ 透過 ssh 執行遠端指令
遠端伺服器

優點：Agent 的 context 在本機，程式碼在本機
缺點：每個指令都有網路延遲

# ① SSH 到遠端
ssh dev

# ② ⭐ 一定要在 tmux 裡跑，否則斷線任務就死了
tmux new -s agent-work

# ③ 在遠端啟動 agent
cd /opt/projects/legacy-app
claude          # 或該機器上安裝的 agent

# ④ 需要離開時 detach（任務繼續跑）
#    Ctrl + Space, 然後按 d

# ⑤ 之後重新接上
ssh dev
tmux attach -t agent-work

① 安裝擴充套件：Remote - SSH
② Ctrl + Shift + P → "Remote-SSH: Connect to Host"
③ 選擇 ~/.ssh/config 中定義的 Host
④ VS Code Server 會自動安裝到遠端

omarchy pkg add kubectl helm k9s

# kubeconfig 位置
ls -la ~/.kube/config
chmod 600 ~/.kube/config          # ⚠️ 這個檔案等同叢集憑證

# 多叢集切換
kubectl config get-contexts
kubectl config use-context dev-cluster

# k9s（TUI，強烈推薦）
k9s

環境
  本機 Omarchy
    ↓ SSH（需經跳板機）
  bastion.corp.example.com:2222
    ↓
  dev-01.internal（開發機，程式碼在這裡，無法外傳）

設定

  ① ~/.ssh/config
     Host bastion
         HostName bastion.corp.example.com
         User myuser
         Port 2222
         IdentityFile ~/.ssh/id_ed25519_corp

     Host dev-01
         HostName 10.0.2.11
         User myuser
         IdentityFile ~/.ssh/id_ed25519_corp
         ProxyJump bastion
         ControlMaster auto
         ControlPath ~/.ssh/sockets/%r@%h:%p
         ControlPersist 10m

  ② 一行連進去（ProxyJump 自動處理跳板）
     $ ssh dev-01

  ③ 在遠端用 tmux 跑 agent
     $ tmux new -s upgrade
     $ cd /opt/projects/legacy-erp
     $ claude
     > 請分析這個 repository 的架構，不要修改任何檔案。

  ④ 下班 detach，隔天接回來
     Ctrl+Space d
     （隔天）$ ssh dev-01 && tmux attach -t upgrade

  ⑤ 需要用本機 IntelliJ 連遠端資料庫
     $ fip                        # 互動式選擇要轉發的 port
     $ lip                        # 確認轉發中
     → IntelliJ 連 localhost:<轉發後的 port>

⚠️ 前提條件（必須先確認）
   - 公司資安政策允許在 dev-01 上執行 AI Agent
   - dev-01 上沒有 production 憑證
   - LLM 供應商的資料處理政策符合公司要求
   - 這台機器上的程式碼可以送到該 LLM 供應商
     ← ⭐ 這一點常被忽略，但它是合規的核心問題

# 方式 A：CLI
omarchy default agent <name>

# 方式 B：選單
# Super + Space → Setup → Defaults → Agent

開一個新的終端機視窗，在裡面啟動預設 agent。

適合：需要一個獨立的 agent 對話空間，不干擾你目前的終端機

# 在目前的終端機、目前的目錄啟動預設 agent
a

適合：你已經 cd 到專案目錄了，直接叫 agent 來看

omarchy agent prompt "分析這個 repository 的架構，不要修改任何檔案"

# 可以包成自己的 shell 函式（放在 ~/.bashrc）
review() {
  omarchy agent prompt "請 review 目前 git diff 中的變更。\
檢查：① 是否有安全問題（硬編碼密碼、SQL injection、未驗證輸入）\
② 是否有明顯的錯誤處理缺漏 ③ 是否符合專案的既有慣例。\
只回報問題，不要修改檔案。"
}

# 使用
git diff && review

# CLI 查詢
omarchy agent

# 常見位置（實際請以各 agent 官方文件為準）
ls -la ~/.claude/          # Claude Code
ls -la ~/.codex/           # Codex
ls -la ~/.config/opencode/ # OpenCode
ls -la ~/.copilot/         # Copilot CLI

# 專案層級的 agent 指示檔（第 21 章詳談）
ls -la ./AGENTS.md ./CLAUDE.md ./.github/copilot-instructions.md 2>/dev/null