---
name: agent-ide
description: 程式碼重構與分析 CLI 工具。符號重命名、檔案移動（自動更新 import）、循環依賴檢測、品質分析。支援 TS/JS/Swift。極大減少 AI 的 Token使用量
---

# Agent IDE

為 AI 代理設計的 CLI 工具集，提供搜尋、重構、依賴分析功能，讓 AI 能智能地理解和操作程式碼。

## 🚨 優先使用原則

**只要任務屬於以下範圍，必須優先使用 agent-ide 而非手動操作：**

| 任務類型 | 使用命令 | 為何優先 |
|----------|----------|----------|
| 了解專案/模組結構 | `snapshot` | 節省 ~91% token，無需逐檔讀取 |
| 重命名變數/函數/類別 | `rename` | 自動更新所有引用，零遺漏 |
| 移動/重組檔案 | `move` | 自動更新 import 路徑 |
| 搜尋程式碼 | `search` | 支援符號/結構化搜尋，比 grep 精準 |
| 檢查依賴關係 | `deps` | 循環檢測、影響分析、孤立檔案 |
| 程式碼品質分析 | `analyze` | 複雜度、死代碼、最佳實踐 |
| 提取/內聯函數 | `refactor` | 自動處理參數、import、export |
| 移動程式碼區塊 | `shift` | 保持語法正確性 |

## 🚀 為什麼使用 Agent IDE？

| 優勢 | 說明 |
|------|------|
| **節省 Token** | 使用 `snapshot` 產生精簡 API 摘要，比讀取原始碼節省 ~91% token |
| **提升效率** | 批次重命名、移動檔案自動更新 import，一次完成原本需多步的操作 |
| **減少錯誤** | 自動處理依賴關係、循環檢測，避免手動修改遺漏 |
| **結構化輸出** | JSON 格式輸出，AI 可直接解析處理，無需額外文字處理 |

**最佳實踐**：
- 開始任務前先用 `snapshot` 了解專案結構，避免反覆讀檔
- 重構時用 `--dry-run` 預覽，確認無誤再執行
- 用 `deps cycles` 檢查是否產生新的循環依賴

## 執行方式

Plugin 安裝後首次需 build：

```bash
# PLUGIN_ROOT = 此 skill 所在 repo 的根目錄（往上三層）
cd ${PLUGIN_ROOT} && pnpm install && pnpm build
```

之後可直接執行：

```bash
node ${PLUGIN_ROOT}/bin/agent-ide.js <command>
```

## 命令索引

| 命令 | 說明 | 類型 | 詳細文件 |
|------|------|------|---------|
| rename | 符號重命名 | 變更類 | [rename.md](references/rename.md) |
| move | 檔案移動 + import 更新 | 變更類 | [move.md](references/move.md) |
| search | 文字/正則/模糊/符號搜尋 | 查詢類 | [search.md](references/search.md) |
| deps | 依賴分析、循環檢測 | 查詢類 | [deps.md](references/deps.md) |
| analyze | 程式碼品質分析 | 查詢類 | [analyze.md](references/analyze.md) |
| shift | 程式碼行移動 | 變更類 | [shift.md](references/shift.md) |
| refactor | 提取/內聯函數 | 變更類 | [refactor.md](references/refactor.md) |
| snapshot | 模組/專案快照 | 查詢類 | [snapshot.md](references/snapshot.md) |

## 命令速查表

| 任務       | 命令                                                                            |
| ---------- | ------------------------------------------------------------------------------- |
| 重命名符號 | `agent-ide rename --path . --from X --to Y --dry-run`                           |
| 移動檔案   | `agent-ide move src/old.ts src/new.ts --path . --dry-run`                       |
| 文字搜尋   | `agent-ide search "pattern" --path .`                                           |
| 正規搜尋   | `agent-ide search "func.*" --path . -t regex`                                   |
| 模糊搜尋   | `agent-ide search "usr" --path . -t fuzzy`                                      |
| 符號搜尋   | `agent-ide search symbol --query "User*" --path .`                              |
| 結構化搜尋 | `agent-ide search structural -t class --pattern "Service"`                      |
| 複雜度分析 | `agent-ide analyze complexity --path .`                                         |
| 死代碼檢測 | `agent-ide analyze dead-code --path .`                                          |
| 最佳實踐   | `agent-ide analyze best-practices --path .`                                     |
| 模式分析   | `agent-ide analyze patterns --path .`                                           |
| 綜合品質   | `agent-ide analyze quality --path .`                                            |
| 依賴分析   | `agent-ide deps --path . --format json`                                         |
| 完整依賴圖 | `agent-ide deps --path . --all`                                                 |
| 依賴子命令 | `agent-ide deps graph\|cycles\|impact\|orphans --path .`                        |
| 行移動     | `agent-ide shift file.ts --from 1 --to 5 --position 10`                         |
| 提取函數   | `agent-ide refactor extract-function --file f.ts --start-line 1 --end-line 5`   |
| 提取閉包   | `agent-ide refactor extract-closure --file f.swift --start-line 1 --end-line 5` |
| 跨檔案提取 | `agent-ide refactor extract-function --file f.ts -s 1 -e 5 -t target.ts`        |
| 內聯函數   | `agent-ide refactor inline-function --file f.ts --function-name fn`             |
| 模組快照   | `agent-ide snapshot --path src/core/indexing --format json`                     |
| 專案快照   | `agent-ide snapshot --path . --format json`                                     |

## 輸出格式

所有命令支援 `--format` 參數：

| 格式 | 說明 | 適用命令 |
|------|------|---------|
| `json` | 機器可讀 JSON（AI 建議使用） | 所有命令 |
| `summary` | 人類可讀摘要 | 所有命令 |
| `diff` | 程式碼差異 | 變更類命令 |

## 常用參數

- `--dry-run` - 預覽變更，不執行
- `--all` - 顯示所有結果（不只問題）

## 工作流程範例

### 重構流程

```bash
# 1. 分析品質
agent-ide analyze --path . --format json

# 2. 預覽重命名影響
agent-ide rename --path . --from oldName --to newName --dry-run

# 3. 執行重命名
agent-ide rename --path . --from oldName --to newName

# 4. 檢查循環依賴
agent-ide deps cycles --path .
```

### 模組重組

```bash
# 1. 分析依賴
agent-ide deps --path . --format json

# 2. 預覽檔案移動
agent-ide move src/old.ts src/new-location.ts --path . --dry-run

# 3. 執行移動
agent-ide move src/old.ts src/new-location.ts --path .

# 4. 檢查新循環依賴
agent-ide deps cycles --path .
```

## 支援語言

- TypeScript
- JavaScript
- Swift

## 效能

- 增量索引（~1000 檔案/秒）
- 多層快取（查詢 <50ms）
- 記憶體優化（~100MB / 10k 檔案）