AI 開發環境設定工具 (ai-dev)
統一的自動化設定與維護 CLI 工具，支援 macOS, Linux 與 Windows。
安裝
完整環境設定指南：如果你是第一次設定 AI 開發環境（包含 Claude Code、MCP Server、Plugin 等），請參閱 AI 開發環境設定指南。
以下僅說明 ai-dev CLI 工具本身的安裝方式。
前置需求
請先安裝 uv (Python 專案管理工具)：
macOS / Linux:
curl -LsSf https://astral.sh/uv/install.sh | sh
Windows (PowerShell):
powershell -c "irm https://astral.sh/uv/install.ps1 | iex"
安裝 CLI 工具
從 GitHub 安裝（推薦）：
# 使用 uv
uv tool install git+https://github.com/ValorVie/custom-skills.git
# 使用 pipx
pipx install git+https://github.com/ValorVie/custom-skills.git
# 私有倉庫需要 token
uv tool install git+https://<GITHUB_TOKEN>@github.com/ValorVie/custom-skills.git
更新 CLI 工具：
uv tool upgrade ai-dev
本地開發安裝：
git clone https://github.com/ValorVie/custom-skills.git
cd custom-skills
# 一般安裝（需要更新 pyproject.toml 的 version 欄位後重新安裝才能套用程式碼變更）
uv tool install . --force
# Editable 安裝（推薦開發使用，程式碼變更立即生效）
uv tool install -e . --force
關於 -e (editable) 模式：
- 一般安裝：把源碼複製到安裝目錄，修改源碼後需要重新安裝才會生效
- Editable 安裝：建立指向專案目錄的連結，修改源碼後立即生效，不需重新安裝
開發期間建議使用 -e 模式，或直接用 uv run ai-dev <command> 從專案目錄執行。
使用方式
安裝後，可在任意目錄使用 ai-dev 指令。
# 顯示版本
ai-dev --version
ai-dev -v
# 顯示說明
ai-dev --help
首次安裝 (Install)
執行以下指令進行全新環境設定：
ai-dev install
這會自動：
- 檢查 Node.js 與 Git。
- 檢查 Claude Code CLI 是否已安裝（若無則顯示安裝指引）。
- 安裝全域 NPM 工具 (
openspec, gemini-cli, skills 等)。
- 檢查 Bun 是否已安裝，若已安裝則自動安裝 Codex CLI。
- Clone 必要的設定儲存庫到
~/.config/（Stage 1，包含 ~/.config/custom-skills 本機 repo）。
- Clone 已設定的自訂 repo（若有）。
- 同步
auto-skill canonical state 到 ~/.config/ai-dev/skills/auto-skill。
- 從
~/.config/custom-skills 分發 Skills 與設定到各個 AI 工具的目錄；auto-skill 會先為各 target 重建 ~/.config/ai-dev/projections/<target>/auto-skill shadow，再將工具目錄投影到該 shadow，優先使用 symlink/junction，失敗才 fallback copy。
- 顯示已安裝的 Skills 清單與重複名稱警告。
- 顯示
npx skills 可用指令提示。
注意：Claude Code 需要使用 native 安裝方式，不再透過 NPM 安裝。
ai-dev install 預設 phase 為 tools,repos,state,targets。
可選參數
| 參數 | 說明 |
|---|
--only | 只執行指定 phase：tools,repos,state,targets |
--skip | 從預設 phase 中跳過指定 phase |
--target | 僅分發指定目標：claude, codex, gemini, opencode, antigravity |
--dry-run | 只顯示執行計畫，不實際寫入 |
範例：
# 只建立 repo 與 canonical state，不分發到工具目錄
ai-dev install --only repos,state
# 僅分發到 Claude Code
ai-dev install --only state,targets --target claude
每日更新 (Update)
建議每天開始工作前執行，以保持環境最新：
ai-dev update
這會自動：
- 更新 Claude Code（若已安裝）。
- 更新全域 NPM 工具。
- 更新已安裝的第三方 Skills（
npx skills update）。
- 更新 Codex CLI（若 Bun 已安裝）。
- 拉取所有設定儲存庫的最新變更 (
git fetch + git reset)。
- 更新已設定的自訂 repo。
- 同步
auto-skill canonical state（不直接變更各工具目錄的 shadow/投影）。
注意：此指令不會自動分發 Skills 到各工具目錄。如需分發，請執行 ai-dev clone。
ai-dev update 預設 phase 為 tools,repos,state。
可選參數
| 參數 | 說明 |
|---|
--only | 只執行指定 phase：tools,repos,state |
--skip | 從預設 phase 中跳過指定 phase |
--dry-run | 只顯示執行計畫，不實際寫入 |
範例：
# 只更新 repo 與 canonical state，不更新工具
ai-dev update --only repos,state
# 只更新工具
ai-dev update --only tools
# 更新後分發 Skills
ai-dev update && ai-dev clone
分發 Skills (Clone)
將統一管理目錄的 Skills 分發到各 AI 工具目錄：
ai-dev clone
auto-skill 為特殊資源，採三層模型：
- canonical state：
~/.config/ai-dev/skills/auto-skill
- per-target shadow：
~/.config/ai-dev/projections/<target>/auto-skill
- tool projection：
~/.claude/skills/auto-skill、~/.codex/skills/auto-skill 等
ai-dev update 只刷新 canonical state。
ai-dev clone 會依 .clonepolicy.json 重建各 target 的 shadow，然後將工具目錄優先以 symlink（Windows 優先 junction）投影到 shadow；若平台或權限不支援才 fallback 為複製。
canonical state 與 shadow 會保留有效的 .clonepolicy.json；當 upstream auto-skill 缺少 policy 時，canonical refresh 會 fallback 使用 template policy，並以 temp rebuild 方式避免舊 state 反覆產生衝突訊息。
ai-dev clone 預設 phase 為 state,targets。
可選參數
| 參數 | 說明 |
|---|
--only | 只執行指定 phase：state,targets |
--skip | 從預設 phase 中跳過指定 phase |
--target | 僅分發指定目標：claude, codex, gemini, opencode, antigravity |
--dry-run | 只顯示執行計畫，不實際寫入 |
--force, -f | 強制覆蓋所有衝突檔案（不提示） |
--skip-conflicts, -s | 跳過有衝突的檔案，僅分發無衝突的檔案 |
--backup, -b | 備份衝突檔案後再覆蓋 |
範例：
# 只刷新 canonical state，不做分發
ai-dev clone --only state
# 只分發到 Claude 與 Codex
ai-dev clone --target claude,codex
# 強制覆蓋所有檔案
ai-dev clone --force
# 跳過衝突檔案
ai-dev clone --skip-conflicts
# 備份後覆蓋
ai-dev clone --backup
維護 custom-skills 專案 (Maintain)
maintain 子命令專門處理 custom-skills repo 自維護流程，避免和一般使用者的 install / clone / project init 混在一起。
# 整合外部來源回開發目錄
ai-dev maintain clone
# 依 allowlist manifest 同步 project-template
ai-dev maintain template
# 只檢查 project-template 是否需要更新
ai-dev maintain template --check
