{
  "markdown": "# Dotfiles\n\n個人設定檔案集合，透過 [chezmoi](https://www.chezmoi.io/) 跨平台管理（Windows 11、macOS、Linux/WSL）。\n\n---\n\n## Bootstrap：各平台前置安裝\n\n在使用 chezmoi 前，需先安裝 **git**、**chezmoi**，以及平台的套件管理器。\n\n### macOS\n\n```bash\n# 1. 安裝 Xcode Command Line Tools（提供 git 和編譯工具）\nxcode-select --install\n\n# 2. 安裝 Homebrew\n/bin/bash -c \"$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)\"\n\n# 3. 安裝 chezmoi\nbrew install chezmoi\n```\n\n### Windows（PowerShell）\n\n> **前提**：先裝好 **git**、**PowerShell 7（pwsh）** 與 **chezmoi**。\n> - chezmoi 的 `.sh` interpreter 會自動偵測 Git for Windows（依序找\n>   `~/.local/opt/git`、`C:\\Program Files\\Git`、scoop git），git 用 winget、官方安裝器\n>   或 scoop 皆可，**不再硬依賴 scoop**。\n> - chezmoi 對 `.ps1` run script 預設用 **pwsh** 執行（非 Windows 內建的 PowerShell 5.1），\n>   且**無 fallback**：缺了 pwsh，第一個 `.ps1` 安裝腳本就會 `exec: \"pwsh\": not found` 而中止。\n>   pwsh 之於 `.ps1` 等同 git 之於 `.sh`，故為手動前置條件。\n\n```powershell\n# 1. 安裝 git（winget 為 OS 內建，不需 scoop）\nwinget install Git.Git\n\n# 2. 安裝 PowerShell 7（chezmoi 用它執行 .ps1 安裝腳本）\nwinget install Microsoft.PowerShell\n\n# 3. 安裝 chezmoi\nwinget install twpayne.chezmoi\n```\n\n> **MSIX vs MSI**：`winget install Microsoft.PowerShell` 交付的是 **MSIX（Store）**版\n> —— 它落在版本化的 `WindowsApps`、靠 App Execution Alias 上 PATH，且提權安裝會\n> `0x80070005`。bootstrap 用它**完全堪用**（chezmoi 的 `.ps1` interpreter 靠 PATH 解析）。\n> 若你偏好乾淨的 **MSI** 版（落 `C:\\Program Files\\PowerShell\\7`、非 Store），winget 給不了，\n> 需改用 [GitHub release](https://github.com/PowerShell/PowerShell/releases) 的\n> `PowerShell-<ver>-win-x64.msi`（提權 `msiexec /i ... /qn`）。已是 MSIX 的機器可用部署到\n> `~/.local/bin/switch-pwsh-to-msi.ps1` 的 helper（提權執行）一鍵切換；apply 期間也會偵測並提醒。\n\n> scoop 為**選用**：僅在你要用它管理 GUI 應用程式時才需安裝\n> （GUI app 清單維護於 [gist](https://gist.github.com/idontwannarock/cef42b856b878e718a2e402eb8e5d7e1)，不在本 repo）。chezmoi 本身不需要 scoop。\n\n### Linux / WSL\n\n```bash\n# 1. 設定 passwordless sudo（chezmoi apply 的 install scripts 需要 sudo 安裝套件）\necho \"$USER ALL=(ALL) NOPASSWD: ALL\" | sudo tee /etc/sudoers.d/$USER\nsudo chmod 0440 /etc/sudoers.d/$USER\n\n# 2. 安裝 git 和編譯工具\nsudo apt update && sudo apt install -y git build-essential curl\n\n# 3. 安裝 Homebrew（版本管理工具如 JDK、Python、Go 透過 brew 安裝）\n/bin/bash -c \"$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)\"\n# 依照 brew 的提示將 brew 加入 PATH\n\n# 4. 安裝 chezmoi\nbrew install chezmoi\n# 或使用官方腳本\nsh -c \"$(curl -fsLS get.chezmoi.io)\"\n```\n\n---\n\n## 初始化\n\n依機器情況選擇以下其中一種方式：\n\n### 情境 A：機器上已有此 repo（最常見）\n\n```bash\n# 告訴 chezmoi 使用現有 repo，不克隆新的\nchezmoi init --source /path/to/your/dotfiles\n\n# 查看會有哪些變更\nchezmoi diff\n\n# 套用設定\nchezmoi apply\n```\n\n### 情境 B：全新機器，克隆到指定位置\n\n```bash\n# 克隆到你偏好的路徑，同時初始化\nmkdir -p ~/github\nchezmoi init --source ~/github/dotfiles git@github.com:idontwannarock/dotfiles.git\n\n# 查看會有哪些變更\nchezmoi diff\n\n# 套用設定\nchezmoi apply\n```\n\n### 情境 C：全新機器，使用 chezmoi 預設位置\n\n```bash\n# chezmoi 會克隆到 ~/.local/share/chezmoi（macOS/Linux）\n# 或 %USERPROFILE%/AppData/Local/chezmoi（Windows）\nchezmoi init --apply git@github.com:idontwannarock/dotfiles.git\n```\n\n> **首次 apply 前**：建議先執行 `chezmoi diff` 確認哪些現有設定會被覆蓋。\n\n---\n\n## 日常操作\n\n```bash\n# 拉取最新變更並套用（最常用，已預設 --init --force --refresh-externals）\nchezmoi update\n\n# 只看差異，不套用\nchezmoi diff\n\n# 套用全部\nchezmoi apply\n\n# 只套用特定檔案\nchezmoi apply ~/.config/starship/starship.toml\n\n# 進入 source 目錄（編輯設定、commit、push）\nchezmoi cd\ngit add .\ngit commit -m \"...\"\ngit push\nexit  # 回到原本的目錄\n```\n\n### 開機自動提示\n\n每天開啟第一個 shell（bash/zsh/PowerShell）時，若 dotfiles 有新版本會自動提示：\n\n```\ndotfiles: 3 new commit(s). Run 'chezmoi update' to apply.\n```\n\n不會自動套用，保留你決定何時更新的控制權。\n\n---\n\n## Troubleshooting\n\n### Windows：`chezmoi update` 報 `%1 is not a valid Win32 application`\n\n症狀：\n\n```\nchezmoi: .claude/settings.json.sh: fork/exec ...\\*.settings.json.sh: %1 is not a valid Win32 application.\n```\n\n原因：chezmoi 本機 config（`~/.config/chezmoi/chezmoi.toml`）缺少 `[interpreters.sh]`\n區塊，Windows 無法直接執行 `.sh` script。這個區塊定義在 `.chezmoi.toml.tmpl`，\n在本機 config 不存在或過舊時需要 `chezmoi init` 才會 render 進去。\n\n自動修復：`run_onchange_before_patch-chezmoi-config.ps1.tmpl` 會在 `chezmoi apply`\n早期偵測並補上 `[interpreters.sh]`，使用者只需要**再跑一次** `chezmoi update`\n即可（第一次 apply 會修好 config 但同一 run 的 `.sh` script 可能還在用\n舊快取，第二次就會乾淨跑完）。\n\n手動修復：直接執行 `chezmoi init`，這會重新 render `.chezmoi.toml.tmpl`\n成本機 config（不會動 source directory、也不會問問題）。\n\n### 任何平台：apply 中止會讓字典序在後的 target 靜默落空\n\nchezmoi 依 **target path 字典序**處理 target，而且**沒有 skip-on-error**。任何一項失敗，\n排在它之後的 target 全部不會部署 —— 而 apply 的輸出只有那一行錯誤，不會說「還有 N 項\n未處理」。曾因此讓 `Documents/_shared-profile.d/26-glab.ps1` 長期沒部署到 Windows，\n正向測試完全看不出來，最後靠跨機比對才發現。\n\n判斷方式：懷疑某個變更沒到某台機器時，先看它的 target path 排在失敗項之前還之後\n（`.claude` < `.codex` < `.local` < `Documents`）。`chezmoi status` 會列出所有待處理項目。\n\n防呆：`chezmoi apply` / `chezmoi update` 非零退出時，shell wrapper 會印出警告與待處理\n筆數（`Documents/_shared-profile.d/96-chezmoi-guard.ps1` 與\n`.chezmoitemplates/shell-common/base` 的 `chezmoi()`，兩邊訊息一致）。\n\n### Windows：`.local/opt/jdk-*/...: Access is denied.`\n\n症狀：`chezmoi apply` 在 JDK 升版時中止，例如\n\n```\nchezmoi: .local/opt/jdk-17/bin/server/classes.jsa: Access is denied.\n```\n\n原因**不是**檔案鎖，也不是 ACL：Temurin 的 zip 對少數 entry 帶唯讀權限位，chezmoi 解壓\nexternal archive 時把它映射成 Windows 的 `ReadOnly` 檔案屬性，下次升版就無法覆寫自己\n寫出來的檔案。chezmoi 不會為了自己的寫入而暫時解除唯讀（[twpayne/chezmoi#3441](https://github.com/twpayne/chezmoi/issues/3441)）。\n\n自動修復：`run_onchange_before_clear-readonly-externals.ps1.tmpl` 會在 apply 進入寫入\n階段之前清掉 `~/.local/opt/jdk-*` 底下的 `ReadOnly` 屬性。它以 `.chezmoiexternal.toml`\n裡的五個 JDK 版本 pin 為 onchange key，只有版本異動時才跑。\n\n---\n\n## 管理範圍\n\n### 由 chezmoi 管理（chezmoi apply 時自動部署）\n\n| 設定 | 部署目標 | 平台 |\n|------|----------|------|\n| Shell prompt（[Starship](docs/starship.md)） | `~/.config/starship/starship.toml` | 跨平台 |\n| [Vim](docs/vim.md) / IdeaVim | `~/.vimrc`, `~/.ideavimrc`, `~/.vim/` | 跨平台 |\n| Bash | `~/.bashrc`, `~/.shell_common` | Windows (Git Bash)、Linux/WSL |\n| Zsh | `~/.zshrc`, `~/.shell_common` | macOS |\n| PowerShell 7 | `~/Documents/PowerShell/` | Windows |\n| PowerShell 5 | `~/Documents/WindowsPowerShell/` | Windows |\n| PS shared fragments | `~/Documents/_shared-profile.d/` | Windows |\n| Claude Code 全域設定 | `~/.claude/CLAUDE.md` | 跨平台 |\n| Claude Code commands | `~/.claude/commands/` | 跨平台 |\n| Claude Code agents | `~/.claude/agents/` | 跨平台 |\n| Codex CLI 全域設定 | `~/.codex/config.toml` | 跨平台 |\n| Codex CLI skills | `~/.codex/skills/` | 跨平台 |\n| Statusline binary | `~/.local/bin/statusline` | 跨平台（自動下載） |\n\n### 自動安裝的工具\n\n`chezmoi apply` 時會自動安裝以下工具（若尚未安裝）。各平台的來源已不相同：\n\n| 平台 | 來源 |\n|------|------|\n| Windows | **`.chezmoiexternal.toml`**（GitHub Releases / 官方 CDN → `~/.local/bin`、`~/.local/opt`）。Scoop 已於 Wave 1–12 全面退場，安裝腳本不再呼叫它 |\n| macOS | brew；JVM 工具鏈用 sdkman、Python 用 uv |\n| Linux/WSL | 一般工具用 apt；JVM 工具鏈用 sdkman、Python 用 uv；Go 用官方 tarball 裝到 `~/.local/go`（apt 版太舊不支援 GOTOOLCHAIN） |\n\n> Scoop 在本 repo 只剩兩個角色：使用者手動執行的 `scoopupdate`，以及維護於外部 gist 的 GUI app 清單。**沒有任何安裝腳本依賴它**。\n\n**基礎設施（before phase）：**\n\n| 工具 | 說明 |\n|------|------|\n| jq | modify_ scripts 的 JSON 處理 |\n\n**開發語言 / Runtime（install-01-runtimes）：**\n\nWindows 端此腳本已是**指標對照表，不安裝任何東西**——Wave 10 之後整條 toolchain 都由 `.chezmoiexternal.toml` 提供。\n\n| 工具 | Unix 來源 | Windows 來源 |\n|------|-----------|--------------|\n| NVM + Node.js | 官方 curl installer | external（nvm-windows zip → `~/.local/opt/nvm`）+ Wave 9 migrate script |\n| Vim | apt / brew | external → `~/.local/opt/vim` + `dot_local/bin/*.cmd` wrappers |\n| Go | Linux 官方 tarball → `~/.local/go`；macOS brew | external（go.dev zip）→ `~/.local/opt/go` |\n| Python | uv（3.13） | uv（3.11 + 3.13），由 Wave 10 migrate script 觸發 |\n| uv | 官方 installer | external |\n| Rustup | 官方 rustup-init | 官方 rustup-init（Wave 10 migrate script） |\n| Maven 3 | sdkman | external → `~/.local/opt/maven` |\n| Temurin JDK 8, 11, 17, 21, 25 | sdkman | external → `~/.local/opt/jdk-N` + `java{8,11,17,21,25}.cmd` |\n| Starship | 官方 installer | external |\n\nGo 的 base version ≥ 1.24（支援 GOTOOLCHAIN 自動下載專案需求版本）。Rustup 安裝後，每次 `chezmoi apply` 由 `run_update-rust-toolchain` 自動 `rustup update stable` 追蹤最新版。\n\n**npm 全域工具（install-02-npm-tools）：**\n\n| 工具 | 說明 |\n|------|------|\n| Claude Code | AI CLI（`@anthropic-ai/claude-code`） |\n| Codex CLI | AI CLI（`@openai/codex`） |\n| OpenSpec | 結構化開發流程（`@fission-ai/openspec`） |\n\n**Claude Code 設定（install-03-claude-config）：**\n\n| 項目 | 說明 |\n|------|------|\n| slack plugin | Claude Code plugin |\n| 清理 marketplace | `obra/superpowers-marketplace` 的三個 plugin（superpowers、episodic-memory、elements-of-style）全數退役後，連同 cache 目錄一併移除註冊 |\n| atlassian MCP | 由此腳本註冊的 user-scope MCP server；http transport，本機不 spawn process，OAuth 需自行 `/mcp` 完成 |\n| 清理 | 取消安裝已退役的 plugin／MCP server／npm 工具並清掉殘留 cache，使移除在每台機器上收斂 |\n\n> jdtls（Java LSP）已於 Wave 11 移出此腳本，改由 `.chezmoiexternal.toml` 提供（`~/.local/opt/jdtls` + `~/.local/bin/jdtls`）。\n\n**容器 / 雲（install-containers）：**\n\nWindows 端為 no-op：docker / kubectl / kubelogin 皆由 external 提供，Lens 不納管。\n\n| 工具 | Unix 來源 |\n|------|-----------|\n| Docker, Docker Compose | apt / brew |\n| kubectl, kubelogin | apt / brew（Windows 走 external） |\n| Lens | 不納管（手動安裝） |\n\n**CLI 工具（install-cli-tools）：**\n\nWindows 端為 no-op：每個舊有套件現在不是來自 external、就是來自 OS 內建，或不再納管。\n\n| 工具 | Unix 來源 |\n|------|-----------|\n| 一般 CLI 工具 | brew（macOS）/ apt（Linux） |\n| libpq（psql） | brew，keg-only 故 force-link |\n| golangci-lint | 官方 installer → `~/.local/bin`（不在 apt） |\n| Hugo | apt，缺套件時退回官方安裝指引 |\n| nexttrace | 官方腳本（不在 apt） |\n| yt-dlp | apt，缺套件時退回 pip 指引 |\n\n**字型（install-fonts）：**\n\n| 字型 | 說明 |\n|------|------|\n| CaskaydiaCove Nerd Font Mono | Terminal 字型 |\n| JetBrains Mono | 程式字型 |\n\n來源依平台不同：macOS 走 brew cask；Windows 由 external 下載、`run_once_register-fonts` 註冊（install-fonts 本身為 no-op）；Linux/WSL 的字型由主機端終端機負責，不在此管理。\n\n### 不納入 chezmoi（手動管理）\n\n| 項目 | 原因 |\n|------|------|\n| [SSH keys 與 `~/.ssh/config`](docs/ssh.md) | 每台機器獨立，不應同步；config 含內網 IP 與主機別名。可共用的部分走 `~/.ssh/config.d/` drop-in |\n| [Git 憑證](docs/git-credentials.md) | 包含機器專屬 access token |\n| GUI 應用程式 | 各機器需求不同（清單維護於 [gist](https://gist.github.com/idontwannarock/cef42b856b878e718a2e402eb8e5d7e1)） |\n| NeoVim | 已棄用並自 repo 移除，改用 [Vim](docs/vim.md) 設定；舊設定可自 git history 取回 |\n\n---\n\n## 目錄結構\n\nchezmoi 的 source state 全部收在 `home/` 底下，由 repo root 的 `.chezmoiroot`\n（內容為 `home`）指向。repo root 只保留「不部署」的專案基礎建設（CI 原始碼、文件、\n測試、OpenSpec），讓根目錄保持精簡。兩者互不干擾：root 的檔案 chezmoi 根本看不到，\n因此不需要再用 `.chezmoiignore` 排除。\n\n```\ndotfiles/\n├── .chezmoiroot              # 內容為 \"home\"：chezmoi 從 home/ 讀取 source state\n├── home/                     # ← chezmoi source root（所有受管設定與安裝腳本）\n│   ├── .chezmoi.toml.tmpl    # chezmoi 環境偵測設定（WSL detection 等）\n│   ├── .chezmoiignore.tmpl   # 依 OS 排除不適用的檔案\n│   ├── .chezmoiexternal.toml # 外部資源（statusline / passgen binary）\n│   ├── .chezmoiremove        # 退役檔案清單（跨機器清除已部署的舊檔）\n│   ├── .chezmoitemplates/    # 平台專用 template 片段\n│   │   ├── bashrc/           #   bashrc/{windows,linux}\n│   │   ├── scripts/          #   scripts/{load-nvm}（安裝腳本共用片段）\n│   │   ├── shell-common/     #   shell-common/{base,windows,linux,darwin}\n│   │   └── zshrc/            #   zshrc/{darwin}\n│   ├── Documents/            # Windows PowerShell profiles（chezmoi 管理）\n│   │   ├── _shared-profile.d/ #   PS5 + PS7 共用 fragments\n│   │   ├── PowerShell/       #   PS7 專屬 profile\n│   │   └── WindowsPowerShell/ #   PS5 專屬 profile\n│   ├── dot_config/           # ~/.config/ 設定（starship 等）\n│   ├── dot_claude/           # ~/.claude/ 設定（commands / skills / output-styles / exact_agents）\n│   ├── dot_codex/            # ~/.codex/ 設定（skills）\n│   ├── dot_local/bin/        # ~/.local/bin/ 腳本（wrapper 與手動執行的輔助腳本）\n│   ├── dot_shell_common.tmpl # ~/.shell_common 入口（依 OS 載入 template 片段）\n│   ├── dot_bashrc.tmpl       # ~/.bashrc 入口（Windows Git Bash / Linux/WSL）\n│   ├── dot_zshrc.tmpl        # ~/.zshrc 入口（macOS）\n│   ├── dot_vimrc / dot_ideavimrc / dot_vim/  # Vim / IdeaVim\n│   ├── run_onchange_before_*.tmpl # 前置腳本（jq 安裝、chezmoi config 修復）\n│   ├── run_once_install-*.tmpl    # 工具安裝腳本（01-runtimes → 02-npm-tools → 03-claude-config, containers, cli-tools, fonts）\n│   ├── run_onchange_*.tmpl        # 設定更新腳本（變更時重跑）\n│   └── run_after_*.tmpl           # 後置腳本（Windows codex config 合併）\n│\n├── .github/workflows/        # GitHub Actions（工具編譯發佈、PR 階段建置檢查、Pester 測試、shell 測試、template render、externals 驗證）\n├── tools/                    # 自建工具原始碼（CI 編譯為 release，經 external 拉回，不部署）\n│   ├── statusline/           #   Go：Claude Code 狀態列\n│   └── passgen/              #   Rust：密碼產生器\n├── docs/                     # 工具設定說明文件\n├── context/                  # 專案 context（做需求分析時的長青背景，非自動載入）\n├── tests/                    # Pester 測試（CI 於 windows-latest 執行）\n└── openspec/                 # OpenSpec 變更追蹤\n```\n\n需求分析或架構判斷前，先讀 [`context/`](context/index.md)：專案解決什麼問題、domain 詞彙表、反覆適用的原則與約束。它不會自動載入，需要時主動查閱。\n\n---\n\n## 文件\n\n| 文件 | 說明 |\n|------|------|\n| [Bash](docs/bash.md) | Bash 設定、worklogs、Windows Terminal 整合 |\n| [Claude Code](docs/claude-code.md) | Claude Code 設定、statusline、plugins、現成可用的 MCP 清單 |\n| [claude-zai wrapper](docs/claude-zai-wrapper.md) | 切換 Claude Code 後端的 wrapper |\n| [Codex CLI](docs/codex-cli.md) | Codex CLI 設定、skills、Claude workflow 對齊 |\n| [Corp SSH（Linux/WSL）](docs/corp-ssh-setup.md) | 公司 SSH 密碼 + OTP 自動化 |\n| [Corp SSH（Windows）](docs/corp-ssh-setup-windows.md) | 同上的 Windows 版 |\n| [Corp GitLab（glab）](docs/gitlab-corp-access.md) | glab 的權杖與 host 解析、每台機器的一次性設定 |\n| [Git 憑證管理](docs/git-credentials.md) | Git 遠端認證（GCM、SSH、WSL） |\n| [herdr](docs/herdr.md) | Agent 多工器的實測行為與陷阱（Linux/macOS） |\n| [PowerShell](docs/powershell.md) | PowerShell profile 設定與依賴 |\n| [Renovate](docs/renovate.md) | external 工具版本自動追蹤與 auto-merge |\n| [SSH](docs/ssh.md) | SSH key 設定教學、`~/.ssh/config.d/` Include 慣例 |\n| [Starship](docs/starship.md) | Starship prompt 設定 |\n| [User Scripts](docs/user-scripts.md) | 手動執行的輔助腳本（scoop 更新、pwsh 換裝） |\n| [Vim](docs/vim.md) | Vim / IdeaVim 設定與快捷鍵 |\n",
  "bytes": 13418,
  "sha": "606c0f7cd2b765f52a7cd402c8328faf5532500f39cdd48b340876de01468ddb",
  "repo_slug": "idontwannarock/dotfiles",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/okf_idontwannarock_dotfiles_context_index_md_fcb93fe5/readme"
}