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, skills 等)。
檢查 Bun 是否已安裝，若已安裝則自動安裝 Codex CLI。
Clone 必要的設定儲存庫到 ~/.config/（Stage 1，包含 ~/.config/custom-skills 本機 repo）。
Clone 已設定的自訂 repo（若有）。
依 upstream/npx-skills.yaml 安裝或更新第一方與第三方 global Skills。
從 ~/.config/custom-skills 分發 commands、agents、workflows、plugins，以及保留 clone ownership 的 custom repo／ECC resources。
顯示已安裝的 Skills 清單與重複名稱警告。
顯示 npx skills 可用指令提示。

注意：Claude Code 需要使用 native 安裝方式，不再透過 NPM 安裝。

ai-dev install 預設 phase 為 tools,repos,npx-skills,targets。

可選參數

參數	說明
`--only`	只執行指定 phase：`tools,repos,npx-skills,targets`
`--skip`	從預設 phase 中跳過指定 phase
`--target`	僅分發指定目標：`claude`, `codex`, `agy`, `opencode`, `antigravity`
`--dry-run`	只顯示執行計畫，不實際寫入

範例：

# 只建立 repo，不分發到工具目錄
ai-dev install --only repos

# 僅分發到 Claude Code
ai-dev install --only targets --target claude

每日更新 (Update)

建議每天開始工作前執行，以保持環境最新：

ai-dev update

這會自動：

更新 Claude Code（若已安裝）。
更新全域 NPM 工具。
更新 manifest 管理的第一方與第三方 Skills（npx skills update）。
更新 Codex CLI（若 Bun 已安裝）。
拉取所有設定儲存庫的最新變更 (git fetch + git reset)。
更新已設定的自訂 repo。

注意：此指令不會自動分發 clone-owned resources。如需更新 commands、agents、workflows、plugins、custom repos 或 ECC，請執行 ai-dev clone。

ai-dev update 預設 phase 為 tools,repos,npx-skills。

可選參數

參數	說明
`--only`	只執行指定 phase：`tools,repos,npx-skills`
`--skip`	從預設 phase 中跳過指定 phase
`--dry-run`	只顯示執行計畫，不實際寫入

範例：

# 只更新 repo，不更新工具
ai-dev update --only repos

# 只更新工具
ai-dev update --only tools

# 更新後分發 clone-owned resources
ai-dev update && ai-dev clone

分發保留資源 (Clone)

分發仍由 framework ownership 管理的 commands、agents、workflows、plugins、custom repos 與 ECC 白名單 resources：

ai-dev clone

第一方 global skills 由 ValorVie/ai-dev-skills 維護，透過 npx-skills phase 安裝。ai-dev clone 不再從本 repository 的 skills/ 複製第一方 skills，也不會替它們建立新的 ManifestTracker ownership。

Codex 的使用者層 Skills 會寫入共用的 ~/.agents/skills。專案內的 Codex Skills 也統一放在 .agents/skills；.codex/config.toml、agents、hooks、prompts、認證與 session 等 Codex 專用資料仍留在 .codex。共用路徑可讓 Codex、Prime Agent 與其他支援 Agent Skills 慣例的 harness agent tool 讀取同一份一般 Skills，降低工具綁定。

ai-dev install、ai-dev update 與 ai-dev clone 會先檢查舊版 ~/.codex/skills：

目標沒有同名 skill 時，整個目錄搬到 ~/.agents/skills。
內容相同時，備份後移除舊副本。
內容不同時保留兩份並列出名稱，不會覆蓋；此次指令會在其他 phase 前停止並留下衝突 audit。
已退役的 auto-skill 不參與路徑遷移，交由後述確認式清理處理。
.system 等隱藏項目由 Codex 管理，不會搬移。
--dry-run 只列出預計搬移與去重的數量，不建立目錄或備份。

實際搬移前會先備份到 ~/.config/ai-dev/backups/codex-skills-migration/<timestamp>/，同一目錄的 audit.json 會記錄來源、目標、動作與結果。需要回復時，先停止後續分發，並逐項確認共用目錄的內容仍與備份相同：migrate 項目才把共用目錄中的項目移回舊路徑；deduplicate 項目保留共用副本，只從備份還原舊副本。若內容已變更就停止，不得整包覆蓋。ai-dev toggle --target codex --type skills 也會操作這個共用目錄，因此會同時影響讀取同一 skill 的其他工具。

auto-skill 已退役，不再參與安裝或分發。ai-dev clone 會在分發前檢查既有的來源副本、canonical state、shadow、各工具 projection、舊啟動規則與 Claude Plugin。只有在互動式終端明確確認後，才會先備份至 ~/.config/ai-dev/backups/auto-skill-removal/<timestamp>/ 再清理；拒絕、非互動模式與 --dry-run 都不會刪除。退役原因與原始內容見 archive/auto-skill/。

ai-dev clone 預設 phase 為 targets。

可選參數

參數	說明
`--only`	只執行指定 phase：`targets`
`--skip`	從預設 phase 中跳過指定 phase
`--target`	僅分發指定目標：`claude`, `codex`, `agy`, `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

ai-dev maintain template 會讀取 repo 根目錄的 project-template.manifest.yaml，只同步 allowlist 內的檔案與資料夾到 project-template/。這份 manifest 是模板內容的單一權威來源，用來取代過去 project init --force 隱式反向同步的耦合行為。

專案級操作 (Project)

在專案目錄下初始化 tracked scaffold，並以投影方式生成 AI 檔：

# 初始化專案（複製 tracked scaffold + hydrate AI 檔）
ai-dev project init

# 同名檔案會提示覆蓋 / 增量 / 差異 / 跳過
# 同名目錄會遞迴到檔案層級處理，目標額外檔案保留

# 初始化指定目錄
ai-dev project init /path/to/dir

# 強制重新初始化（只覆蓋同名檔案，不刪既有目錄）
ai-dev project init --force

# 重新生成 AI 檔（預設跳過衝突）
ai-dev project hydrate

# 收斂意圖檔、projection manifest 與實際檔案
ai-dev project reconcile

# 檢查 projection 狀態
ai-dev project doctor

# 更新專案配置（整合 openspec update + uds update）
ai-dev project update

# 只更新特定工具
ai-dev project update --only openspec

AI 文件本地排除：project init 若偵測到 .git/，會詢問是否將 AI 生成檔加入 .git/info/exclude。

退役資源清理：project init 與 project update 會檢查專案內的 auto-skill 副本及舊啟動規則。只有互動確認後才先備份再移除；--force 不會略過這項確認。若目前尚未 git init，指令只會提示你稍後手動啟用；project hydrate / project reconcile 只會在已啟用時同步排除規則。詳見下方 AI 文件本地排除章節。

初始化衝突規則：

ai-dev project init：遇到同名檔案時會進行內容級別分析，提供覆蓋、增量、查看差異、跳過選項。

ai-dev project init --force：只會無條件覆蓋同名檔案。

若目標已存在同名目錄，兩種模式都會遞迴到檔案層級處理；模板沒有的目標額外檔案會保留。

ai-dev project init 會放入 .standards/ scaffold，但不會替外部 uds CLI 執行 uds init。

可選參數

init:

參數	說明
`target` (位置參數)	目標目錄（預設為當前目錄）
`--force`, `-f`	強制重新初始化（即使已存在）

update:

參數	說明
`--only`, `-o`	只更新特定工具：`openspec`, `uds`

hydrate / reconcile:

參數	說明
`target` (位置參數)	目標目錄（預設為當前目錄）
`--force`, `-f`	強制覆蓋衝突項目
`--backup`	備份衝突項目後覆蓋

AI 文件本地排除 (Project Exclude)

管理 AI 生成檔（.claude/、.codex/、.gemini/、.github/skills/、AGENTS.md、CLAUDE.md 等）的本地 git 排除。

問題背景：AI 設定檔混在專案中會汙染 PR（例如 453 files changed，其中只有 5 個是程式碼）。但 AI 工具（Claude Code、Codex、OpenCode 等）需要在專案目錄中讀取這些檔案。

解決方案：使用 .git/info/exclude（本地 git 排除）取代 .gitignore。AI 工具不會讀取 .git/info/exclude，因此不受影響，但 git 會忽略這些檔案。

# 檢視目前排除清單
ai-dev project exclude --list

# 啟用本地排除
ai-dev project exclude --enable

# 停用本地排除（還原 git 追蹤）
ai-dev project exclude --disable

運作方式

project init 與 init-from 在 git repo 內都會詢問是否啟用本地排除
若 .ai-dev-project.yaml 的 git_exclude.enabled 為 true，project hydrate / project reconcile 會同步 .git/info/exclude
若專案尚未 git init，project init 只會提示稍後手動執行 ai-dev project exclude --enable
排除清單只涵蓋 AI 生成物，保留 .standards/、.editorconfig、.gitattributes、.gitignore 等 tracked scaffold
排除規則寫入 .git/info/exclude 的管理區塊（有標記，不影響手動項目）
init-from update 時自動同步排除清單（新增/移除項目）
clone 和 install 不會修改當前專案的 .git/info/exclude
設定記錄於 .ai-dev-project.yaml 的 git_exclude 區段

AI 工具相容性

工具	設定載入	直接讀取	搜尋/Grep	結論
Claude Code	OK	OK	Glob OK, Grep 跳過	可行
Codex CLI	OK	OK	搜尋跳過	可行
OpenCode	OK	OK	搜尋跳過	可行
Antigravity CLI (agy)	待驗證	待驗證	待驗證	待驗證（接替已退役的 Gemini CLI）
Antigravity	OK	OK	OK	可行

關鍵差異：.git/info/exclude 與 .gitignore 效果相同，但不被 AI 工具的 gitignore parser 讀取。詳細調查報告見 docs/report/2026-03-07-ai-files-gitignore-compatibility.md。

自訂 Repo 管理

新增或更新自訂 repo（用於納入公司/團隊的專屬 Skills、Commands、Agents 等資源）：

# 新增自訂 repo
ai-dev add-custom-repo owner/repo

# 指定名稱與分支
ai-dev add-custom-repo owner/repo --name my-custom-name --branch develop

# 自動補齊缺少的目錄結構
ai-dev add-custom-repo owner/repo --fix

# 更新所有自訂 repo
ai-dev update-custom-repo

自訂 repo 會記錄於 ~/.config/ai-dev/repos.yaml。

上游 Repo 管理 (Add Repo)

新增上游 repo 並開始追蹤（用於 upstream sources registry）：

# 新增上游 repo
ai-dev add-repo owner/repo

# 指定名稱與分支
ai-dev add-repo owner/repo --name my-custom-name --branch develop

# 跳過 clone（僅加入 sources.yaml）
ai-dev add-repo owner/repo --skip-clone

# 加入後立即執行分析
ai-dev add-repo owner/repo --analyze

可選參數

參數	說明
`remote_path` (位置參數，必填)	遠端 repo 路徑（例如: `owner/repo` 或完整 URL）
`--name`, `-n`	自訂名稱（預設使用 repo 名稱）
`--branch`, `-b`	追蹤的分支（預設：main）
`--skip-clone`	跳過 clone（僅加入 sources.yaml）
`--analyze`, `-a`	加入後立即執行分析

狀態檢查 (Status)

隨時檢查環境配置狀態：

ai-dev status

這會顯示：

核心工具版本 (Node.js, Git)
NPM 套件安裝狀態（含 skills 套件）
設定儲存庫狀態

列出已安裝資源 (List)

列出各工具已安裝的 Skills、Commands、Agents（預設包含停用的資源）：

# 列出 Claude Code 的 Skills
ai-dev list --target claude --type skills

# 列出 Antigravity 的 Workflows
ai-dev list --target antigravity --type workflows

# 列出 OpenCode 的 Agents
ai-dev list --target opencode --type agents

# 列出 Codex 的 Skills
ai-dev list --target codex --type skills

# 列出 Antigravity CLI (agy) 的 Skills
ai-dev list --target agy --type skills

# 隱藏已停用的資源
ai-dev list --hide-disabled

可選參數

參數	說明
`--target`, `-t`	目標工具：`claude`, `antigravity`, `opencode`, `codex`, `agy`
`--type`, `-T`	資源類型：`skills`, `commands`, `agents`, `workflows`
`--hide-disabled`, `-H`	隱藏已停用的資源（預設顯示全部）

啟用/停用資源 (Toggle)

啟用或停用特定工具的特定資源。停用時會將檔案移動到 ~/.config/custom-skills/disabled/ 目錄，啟用時會移回原位置。

# 停用特定 skill
ai-dev toggle --target claude --type skills --name skill-creator --disable

# 重新啟用
ai-dev toggle --target claude --type skills --name skill-creator --enable

# 查看目前狀態
ai-dev toggle --list

可選參數

參數	說明
`--target`, `-t`	目標工具：`claude`, `antigravity`, `opencode`, `codex`, `agy`
`--type`, `-T`	資源類型：`skills`, `commands`, `agents`, `workflows`
`--name`, `-n`	資源名稱
`--enable`, `-e`	啟用資源
`--disable`, `-d`	停用資源
`--list`, `-l`	列出目前的開關狀態

停用機制

停用資源時，檔案會被移動到 ~/.config/custom-skills/disabled/<target>/<type>/ 目錄：

~/.config/custom-skills/disabled/
├── claude/
│   ├── skills/
│   │   └── some-disabled-skill/
│   └── commands/
│       └── some-disabled-command.md
├── antigravity/
│   └── ...
├── opencode/
│   └── ...
├── codex/
│   └── skills/
│       └── ...
└── agy/
    └── skills/
        └── ...

注意：停用/啟用後需要重啟對應的 AI 工具才會生效。

配置檔

Toggle 狀態儲存於 ~/.config/custom-skills/toggle-config.yaml：

claude:
  skills:
    enabled: true
    disabled:
      - "some-skill-to-disable"
  commands:
    enabled: true
    disabled: []

antigravity:
  skills:
    enabled: true
    disabled: []
  workflows:
    enabled: true
    disabled: []

opencode:
  agents:
    enabled: true
    disabled: []

codex:
  skills:
    enabled: true
    disabled: []

agy:
  skills:
    enabled: true
    disabled: []

互動式 TUI 介面 (TUI)

啟動視覺化管理介面：

ai-dev tui

功能：

頂部按鈕列：Install / Update / Status / Add Skills / Quit
Target 下拉選單：切換目標工具（Claude Code / Antigravity / OpenCode / Codex / Antigravity CLI (agy)）
Type 下拉選單：切換資源類型（Skills / Commands / Agents / Workflows）
資源列表：Checkbox 勾選啟用/停用
Add Skills 對話框：輸入套件名稱並執行 npx skills add
MCP Config 區塊：檢視並快速開啟各工具的 MCP 設定檔

MCP Config 區塊：

TUI 底部顯示目前選擇的工具的 MCP 設定檔資訊：

工具	設定檔路徑
Claude Code	`~/.claude.json`
Antigravity	`~/.gemini/antigravity/mcp_config.json`
OpenCode	`~/.config/opencode/opencode.json`
Codex	`~/.codex/config.json`
Antigravity CLI (agy)	`~/.gemini/config/mcp_config.json`

點擊「Open in Editor」可在 VS Code 中開啟設定檔，點擊「Open Folder」可在檔案管理器中開啟。

ECC Hooks Plugin 區塊：

TUI 會顯示 ECC Hooks Plugin 的安裝方式參考。

詳細安裝說明請參考：@plugins/ecc-hooks/README.md

快速安裝：

claude --plugin-dir "/path/to/custom-skills/plugins/ecc-hooks"

快捷鍵：

按鍵	功能
`q`	退出
`Space`	切換選中項目
`a`	全選
`n`	全取消
`s`	儲存並同步
`p`	開啟 Add Skills 對話框
`e`	在編輯器中開啟 MCP 設定檔
`f`	在檔案管理器中開啟 MCP 設定檔所在目錄
`t`	切換 Standards Profile

Skills 管理

ai-dev baseline 的第一方與第三方 Skills 定義於 upstream/npx-skills.yaml。global phase 只指定 claude-code、codex、gemini-cli、opencode、antigravity；Eve 與 PromptScript 需在各自專案內手動安裝。需要手動安裝其他 skill 時，直接使用 npx skills：

ai-dev-first-party 使用 npx base 加本機 overlay。ai-dev install 與 ai-dev update 會逐檔比較上次接受的 upstream base、目前 upstream、持久 overlay 與 installed local，分類為 clean、local-only、both-changed 或 no-base。第一次出現 local-only、both-changed 或內容不同的 no-base 時，互動終端會要求選擇 keep-local、use-upstream 或 abort。ai-dev 會逐檔記住當時的 upstream hash、本機有效內容 hash 與選擇；兩邊都沒變時直接沿用，任一邊改變且仍有本機差異時才重新詢問。單純的 upstream 更新仍自動套用。非互動模式不會猜測新的選擇，會略過該 skill、繼續安全項目，最後回傳 exit 1。其他 npx packages 不經過這層處理。

互動選單會先以中文說明每個 diff 與處理選項。K 會保存本機覆寫；O 會先備份再採用上游；A 會在尚未寫入時中止。no-base 沒有共同基準，只提供 Dc 比較上游與本機，不會把不可用的 Ds／Dl 留給使用者猜測。

若同一 skill 的舊 target copies 含有不同本機版本，互動終端會先列出每個版本的 hash、變更檔案與來源路徑，要求選出一份 canonical local intent。選版後仍逐檔詢問 K／O／A；未選版本會保留在 transaction backup。非互動模式不會自動選版。已有 schema v2 state 的同名 already-migrated stale copies 不再參與 local intent 判斷，驗證成功後會在同一 transaction 內備份並清理。

要重新檢查先前選擇 keep-local 的 overlay，執行：

ai-dev install-npx-skills --review-first-party-overlays

這個選項會再次顯示互動選單，可改選 use-upstream。若目前不是互動終端，需重審的 skill 會依 fail-closed 規則略過，不會自行清除 overlay。

完成 decision resolution 後，ai-dev 會把同一 repository 的安全第一方 skills 合併成一次 npx add，並以多個明確 --skill 傳入清單。這是 non-interactive 模式的 Select All 等價操作，但不使用 wildcard，因此未列入 baseline 的新 skill 不會被自動安裝。

每個第一方 skill 在 npx 寫入前都有完整 transaction backup。npx 寫入、base 驗證、overlay 套用、effective tree 驗證或 state 寫入失敗時，會還原 installed roots、舊 manifest 與舊 overlay。直接執行原生 npx 若蓋掉 materialized overlay，下一次 ai-dev reconcile 會從持久 overlay 恢復，且相同 hash 組合不會再次詢問；若 upstream 或 overlay 之後改變且仍有本機差異，才重新要求決定。相關狀態位於：

~/.config/ai-dev/manifests/npx-first-party.yaml
~/.config/ai-dev/overlays/npx-first-party/
~/.config/ai-dev/backups/npx-first-party/
~/.config/ai-dev/transactions/npx-first-party/

use-upstream 覆蓋本機內容時會保留 timestamped backup。rollback 失敗或發現未完成 journal 時，不會開始下一個 npx transaction，請依命令輸出的 backup 路徑檢查後再重試。

# 可用指令
npx skills add <package>      # 安裝 skill 套件
npx skills a <package>        # 同上（別名）
npx skills install <package>  # 同上（別名）
npx skills i <package>        # 同上（別名）

# 計畫中
npx skills find <query>       # 搜尋 skills
npx skills update             # 更新已安裝的 skills

# 範例
npx skills add vercel-labs/agent-skills

# ai-dev 第一方 collection
npx skills add ValorVie/ai-dev-skills --list

# Matt Pocock 工程工作流（全域手動安裝）
npx skills@latest add mattpocock/skills -g -y

mattpocock/skills 不由 ai-dev 自動分發。技能成熟度、使用邏輯與更新方式請看 mattpocock/skills 使用指南。

測試 (Test)

執行測試並輸出原始結果（自動偵測專案測試框架）：

# 執行所有測試
ai-dev test

# 執行指定目錄
ai-dev test tests/

# 詳細輸出
ai-dev test -v

# 失敗即停
ai-dev test -x

# 過濾測試名稱
ai-dev test -k "test_name"

可選參數

參數	說明
`path` (位置參數)	測試路徑（檔案或目錄）
`--verbose`, `-v`	顯示詳細輸出
`--fail-fast`, `-x`	失敗時立即停止
`-k`	過濾測試名稱

注意：目前支援 Python (pytest)。

覆蓋率 (Coverage)

執行覆蓋率分析並輸出原始結果：

# 分析整個專案
ai-dev coverage

# 僅分析指定目錄
ai-dev coverage --source script/

# 僅分析指定模組
ai-dev coverage --source script.commands

可選參數

參數	說明
`path` (位置參數)	測試路徑（檔案或目錄）
`--source`, `-s`	模組名稱或目錄

注意：目前僅支援 Python，需要 pytest-cov 已安裝。若傳入單一 .py 檔案，CLI 會自動改用其父目錄，避免 pytest-cov 對單檔案來源產生警告。

Hooks 管理

管理 Claude Code ECC Hooks Plugin 的安裝與狀態：

# 安裝或更新 ECC Hooks Plugin
ai-dev hooks install --target claude

# 移除 ECC Hooks Plugin
ai-dev hooks uninstall --target claude

# 檢查安裝狀態
ai-dev hooks status --target claude

指令總覽

指令	說明
`ai-dev install`	首次安裝 AI 開發環境
`ai-dev update`	每日更新：更新工具與儲存庫
`ai-dev clone`	分發 commands、agents、workflows、plugins、custom repos 與 ECC resources
`ai-dev maintain clone`	整合外部來源回 custom-skills 開發目錄
`ai-dev maintain template`	依 manifest 同步 `project-template/`
`ai-dev project init`	初始化專案 tracked scaffold 並投影 AI 檔
`ai-dev project hydrate`	依專案意圖重新生成 AI 檔
`ai-dev project reconcile`	收斂 project intent、manifest 與實際生成檔
`ai-dev project doctor`	檢查 project projection 與 exclude 狀態
`ai-dev project update`	更新專案配置
`ai-dev project exclude`	管理 AI 文件的本地排除設定
`ai-dev status`	檢查環境狀態與工具版本
`ai-dev list`	列出已安裝的 Skills、Commands、Agents
`ai-dev toggle`	啟用/停用特定資源
`ai-dev tui`	啟動互動式終端介面
`ai-dev standards`	管理標準體系 profiles
`ai-dev derive-tests`	讀取 OpenSpec specs 供 AI 生成測試
`ai-dev test`	執行測試並輸出原始結果
`ai-dev coverage`	執行覆蓋率分析
`ai-dev hooks`	管理 ECC Hooks Plugin（install/uninstall/status）
`ai-dev add-repo`	新增上游 repo 並追蹤
`ai-dev add-custom-repo`	新增自訂 repo
`ai-dev update-custom-repo`	更新自訂 repo

長期維護參考：目前 CLI 命令面、核心副作用、狀態檔與資料流，請參閱 ai-dev 指令與資料流參考。

開發

本專案使用 uv 管理依賴，設定檔位於 pyproject.toml。

# 新增依賴
uv add <package>

# 同步依賴
uv sync

# 本地安裝測試
uv tool install . --force

# 建置套件
uv build

更新套件版本

安全更新 uv.lock 中的套件：

# 查看可更新的套件（不實際更新）
uv lock --dry-run --upgrade

# 更新所有套件到最新相容版本（依照 pyproject.toml 的限制）
uv lock --upgrade

# 只更新特定套件
uv lock --upgrade-package textual

# 同步安裝（確保環境與 lock 檔一致）
uv sync

# 測試是否正常運作
uv run ai-dev tui

還原方式：如果更新後有問題，可以用 git checkout uv.lock && uv sync 還原。

清除快取

如果遇到版本不一致或奇怪的快取問題：

# 清除 uv 快取
uv cache clean

# 重新同步（強制重新安裝）
uv sync --reinstall

資源來源

本專案整合多個上游資源：

來源	說明	目錄
universal-dev-standards	開發標準規範	`.standards/`
everything-claude-code	Hooks, Skills, Agents, Commands	`sources/ecc/`
anthropics/skills	官方 Skills	`sources/anthropic-skills/`
obra/superpowers	Superpowers Skills	`sources/superpowers/`
kepano/obsidian-skills	Obsidian Skills	`sources/obsidian-skills/`

ECC (Everything Claude Code) 資源

ECC 提供進階的 Claude Code 工作流程工具：

Hooks: Python 跨平台 hooks（memory-persistence, strategic-compact）
Skills: continuous-learning, eval-harness, security-review, tdd-workflow
Agents: build-error-resolver, e2e-runner, doc-updater, security-reviewer
Commands: /checkpoint, /build-fix, /e2e, /learn, /coverage, /eval

詳見 sources/ecc/README.md。

標準體系 (Standards Profiles)

支援多種標準體系切換，基於重疊檢測自動管理功能等效的資源：

# 查看目前狀態
ai-dev standards status

# 列出可用 profiles
ai-dev standards list

# 切換 profile（會自動停用重疊資源）
ai-dev standards switch ecc

# 預覽切換影響
ai-dev standards switch ecc --dry-run

# 顯示 profile 內容
ai-dev standards show ecc

# 顯示重疊定義
ai-dev standards overlaps

# 同步檔案狀態（停用/啟用資源）
ai-dev standards sync --target claude

可用 profiles：

uds - Universal Dev Standards 完整版（預設）
ecc - Everything Claude Code 工作流程
minimal - 最小化配置

Profile 系統特性：

重疊檢測：定義於 profiles/overlaps.yaml，標記功能等效的資源（如 UDS 的 tdd-workflow 與 ECC 的 tdd-workflow）
自動停用：切換 profile 時，自動停用重疊組中非偏好來源的資源
手動保護：手動停用的項目不會被 profile 切換覆蓋
同步機制：sync 指令會實際移動檔案到 .disabled/ 目錄或還原

上游追蹤系統

所有第三方 repo 的同步狀態記錄在 upstream/ 目錄：

# 使用 Skills 進行上游審核
/custom-skills-upstream-ops              # 預設 audit mode：commit 差異 + 同步建議
/custom-skills-upstream-ops uds-check    # UDS .standards/ 檔案級漂移
/custom-skills-upstream-ops overlap <repo>  # 任一 repo vs 本專案重疊偵測

詳見 upstream/README.md。

第三方資源目錄

除了已整合的上游資源,本專案也提供第三方資源目錄 (third-party/),收錄值得關注但尚未整合的外部專案資訊:

# 瀏覽第三方資源
cat third-party/README.md

# 查看特定專案資訊(如 wshobson/agents)
cat third-party/catalog/wshobson-agents.md

第三方資源目錄特色:

📋 參考資訊庫: 提供專案概述、功能清單、適用場景
🔌 原生安裝方式: 依照各專案的建議方式安裝(如 Plugin 市場、NPM 套件等)
✅ 評估檢查清單: 幫助判斷專案是否適合您的需求
🔄 漸進式採用: 從探索 → 評估 → 整合的清晰路徑

安裝方式範例:

# wshobson/agents - 使用其 Plugin 市場機制
/plugin marketplace add wshobson/agents
/plugin install python-development

# 其他專案 - 依各專案文件的建議方式
npx skills add <package>          # 若專案支援 skills 套件

與 upstream/ 的差異:

third-party/ - 待評估資源,依原生方式安裝,使用者自行管理
upstream/ - 已整合資源,透過 ai-dev clone 自動同步到本專案

詳見 third-party/README.md。

Claude Code Plugin

本專案包含 ECC Hooks Plugin，提供進階的 Claude Code 工作流程：

ECC Hooks Plugin 安裝

方式 1：本地開發測試

claude --plugin-dir "/path/to/custom-skills/plugins/ecc-hooks"

方式 2：從 Git URL 安裝

# 添加 marketplace
claude plugin marketplace add https://github.com/ValorVie/custom-skills.git

# 安裝 plugin
claude plugin install ecc-hooks@custom-skills

方式 3：在會話中使用 slash command

/plugin install ecc-hooks@custom-skills

詳見 plugins/ecc-hooks/README.md。

OpenCode Plugin (ecc-hooks-opencode)

OpenCode 平台的 ECC Hooks Plugin，提供：

Code Quality Hooks：JS/TS、PHP、Python 的格式化與靜態分析
Memory Persistence：Session 記憶持久化
Strategic Compact：智慧壓縮建議
OpenCode 獨有事件：file.edited、session.idle、file.watcher.updated、permission.asked、todo.updated
Custom Tools：run-tests、check-coverage、security-audit

透過 ai-dev clone 自動分發至 ~/.config/opencode/plugins/。

未來計畫

Hooks 細粒度控制

ai-dev hooks 已支援 install/uninstall/status。未來計畫加入更細粒度的控制：

個別 Hook 開關：在 TUI 中啟用/停用個別 hook
事件類型篩選：按 SessionStart、PreToolUse 等事件分組管理
配置持久化：更新時保留使用者的開關設定
CLI 支援：ai-dev hooks enable/disable/list

FilesExpand file tree

README.md

Latest commit

History

README.md

File metadata and controls

AI 開發環境設定工具 (ai-dev)

安裝

前置需求

安裝 CLI 工具

使用方式

首次安裝 (Install)

可選參數

每日更新 (Update)

可選參數

分發保留資源 (Clone)

可選參數

維護 custom-skills 專案 (Maintain)

專案級操作 (Project)

可選參數

AI 文件本地排除 (Project Exclude)

運作方式

AI 工具相容性

自訂 Repo 管理

上游 Repo 管理 (Add Repo)

可選參數

狀態檢查 (Status)

列出已安裝資源 (List)

可選參數

啟用/停用資源 (Toggle)

可選參數

停用機制

配置檔

互動式 TUI 介面 (TUI)

Skills 管理

測試 (Test)

可選參數

覆蓋率 (Coverage)

可選參數

Hooks 管理

指令總覽

開發

更新套件版本

清除快取

資源來源

ECC (Everything Claude Code) 資源

標準體系 (Standards Profiles)

上游追蹤系統

第三方資源目錄

Claude Code Plugin

ECC Hooks Plugin 安裝

OpenCode Plugin (ecc-hooks-opencode)

未來計畫

Hooks 細粒度控制