Initial commit
This commit is contained in:
Zhongwei Li
387
references/cli-reference.md
Normal file
387
references/cli-reference.md
Normal file
@@ -0,0 +1,387 @@
|
||||
# Agent IDE CLI 指令參考
|
||||
|
||||
## 安裝方式
|
||||
|
||||
### 方式一：Plugin（推薦）
|
||||
```bash
|
||||
/plugin marketplace add vivalalova/agent-ide
|
||||
```
|
||||
|
||||
### 方式二：CLI 安裝
|
||||
```bash
|
||||
npm install -g agent-ide
|
||||
# 或從源碼編譯
|
||||
git clone https://github.com/vivalalova/agent-ide.git
|
||||
cd agent-ide && pnpm install && pnpm build && npm link
|
||||
```
|
||||
|
||||
## 核心功能模組
|
||||
|
||||
| 功能 | 說明 |
|
||||
|------|------|
|
||||
| `snapshot` | 快速生成專案概覽 |
|
||||
| `index` | 建立程式碼索引 |
|
||||
| `search` | 搜尋符號、文字 |
|
||||
| `rename` | 重新命名符號 |
|
||||
| `move` | 移動檔案並更新 import |
|
||||
| `analyze` | 分析程式碼品質 |
|
||||
| `deps` | 依賴關係分析 |
|
||||
| `shit` | 垃圾度評分（分數越高越糟） |
|
||||
| `refactor` | 程式碼重構操作 |
|
||||
| `plugins` | 管理語言解析器 |
|
||||
|
||||
## CLI 指令詳細說明
|
||||
|
||||
### 1. 專案快照 (snapshot)
|
||||
|
||||
**基本快照**：
|
||||
```bash
|
||||
npx agent-ide snapshot --format json
|
||||
```
|
||||
|
||||
**壓縮級別**：
|
||||
```bash
|
||||
# Minimal - 最小資訊
|
||||
npx agent-ide snapshot --compression minimal
|
||||
|
||||
# Medium - 中等資訊
|
||||
npx agent-ide snapshot --compression medium
|
||||
|
||||
# Full - 完整資訊
|
||||
npx agent-ide snapshot --compression full
|
||||
```
|
||||
|
||||
**輸出到檔案**：
|
||||
```bash
|
||||
npx agent-ide snapshot --output project-snapshot.json
|
||||
```
|
||||
|
||||
**指定路徑**：
|
||||
```bash
|
||||
npx agent-ide snapshot --path /path/to/project
|
||||
```
|
||||
|
||||
**完整參數列表**：
|
||||
- `--path`: 專案路徑
|
||||
- `--compression`: 壓縮級別（minimal/medium/full）
|
||||
- `--output`: 輸出檔案路徑
|
||||
- `--format`: 輸出格式（json/table/summary）
|
||||
|
||||
### 2. 程式碼索引 (index)
|
||||
|
||||
**建立索引**：
|
||||
```bash
|
||||
npx agent-ide index --path /path/to/project
|
||||
```
|
||||
|
||||
**增量更新**：
|
||||
```bash
|
||||
npx agent-ide index --incremental
|
||||
```
|
||||
|
||||
**自訂檔案類型**：
|
||||
```bash
|
||||
npx agent-ide index --extensions .ts,.tsx,.js,.jsx
|
||||
```
|
||||
|
||||
**排除規則**：
|
||||
```bash
|
||||
npx agent-ide index --exclude "node_modules,dist,build"
|
||||
```
|
||||
|
||||
**完整參數列表**：
|
||||
- `--path`: 專案路徑
|
||||
- `--incremental`: 增量更新模式
|
||||
- `--extensions`: 指定檔案副檔名
|
||||
- `--exclude`: 排除的目錄或檔案模式
|
||||
- `--force`: 強制重建索引
|
||||
|
||||
### 3. 搜尋操作 (search)
|
||||
|
||||
**基本搜尋**：
|
||||
```bash
|
||||
npx agent-ide search "UserService" --format json
|
||||
```
|
||||
|
||||
**正則表達式搜尋**：
|
||||
```bash
|
||||
npx agent-ide search "function.*User" --type regex --format json
|
||||
```
|
||||
|
||||
**限制結果數量**：
|
||||
```bash
|
||||
npx agent-ide search "import" --limit 10 --format json
|
||||
```
|
||||
|
||||
**完整參數列表**：
|
||||
- `--type`: 搜尋類型（text/symbol/regex）
|
||||
- `--limit`: 限制結果數量
|
||||
- `--format`: 輸出格式（json/list/table）
|
||||
- `--case-sensitive`: 大小寫敏感
|
||||
- `--whole-word`: 完整單字匹配
|
||||
|
||||
### 4. 重命名操作 (rename)
|
||||
|
||||
⚠️ **必須使用 agent-ide 進行重命名**：確保所有引用都正確更新
|
||||
|
||||
**預覽重命名**：
|
||||
```bash
|
||||
npx agent-ide rename --from oldName --to newName --preview
|
||||
```
|
||||
|
||||
**執行重命名**：
|
||||
```bash
|
||||
npx agent-ide rename --from oldName --to newName
|
||||
```
|
||||
|
||||
**啟用備份**：
|
||||
```bash
|
||||
npx agent-ide rename --from oldName --to newName --backup
|
||||
```
|
||||
|
||||
**批量重命名**：
|
||||
```bash
|
||||
npx agent-ide rename --config rename-config.json
|
||||
```
|
||||
|
||||
**完整參數列表**：
|
||||
- `--from`: 原始名稱
|
||||
- `--to`: 目標名稱
|
||||
- `--preview`: 預覽模式
|
||||
- `--backup`: 自動備份
|
||||
- `--config`: 批量重命名設定檔
|
||||
- `--path`: 專案路徑
|
||||
|
||||
### 5. 檔案移動 (move)
|
||||
|
||||
⚠️ **必須使用 agent-ide 進行檔案移動**：自動更新所有 import 語句
|
||||
|
||||
**預覽移動**：
|
||||
```bash
|
||||
npx agent-ide move src/old.ts src/new.ts --preview
|
||||
```
|
||||
|
||||
**執行移動**：
|
||||
```bash
|
||||
npx agent-ide move src/old.ts src/new.ts
|
||||
```
|
||||
|
||||
**批量移動（遞迴）**：
|
||||
```bash
|
||||
npx agent-ide move src/old-module src/new-module --recursive
|
||||
```
|
||||
|
||||
**完整參數列表**：
|
||||
- `--preview`: 預覽模式
|
||||
- `--recursive`: 遞迴移動整個目錄
|
||||
- `--backup`: 自動備份
|
||||
- `--update-imports`: 自動更新 import（預設開啟）
|
||||
|
||||
### 6. 品質分析 (analyze)
|
||||
|
||||
**分析複雜度**：
|
||||
```bash
|
||||
npx agent-ide analyze complexity --format json --all
|
||||
```
|
||||
|
||||
**偵測死代碼**：
|
||||
```bash
|
||||
npx agent-ide analyze dead-code --format json --all
|
||||
```
|
||||
|
||||
**最佳實踐檢查**：
|
||||
```bash
|
||||
npx agent-ide analyze best-practices --format json
|
||||
```
|
||||
|
||||
**完整參數列表**：
|
||||
- `--all`: 分析所有檔案
|
||||
- `--file`: 分析特定檔案
|
||||
- `--format`: 輸出格式（json/table/summary）
|
||||
- `--threshold`: 複雜度閾值
|
||||
|
||||
### 7. 依賴分析 (deps)
|
||||
|
||||
**專案整體依賴**：
|
||||
```bash
|
||||
npx agent-ide deps --format json
|
||||
npx agent-ide deps --format json --all
|
||||
```
|
||||
|
||||
**特定檔案依賴**：
|
||||
```bash
|
||||
npx agent-ide deps --file src/service.ts --format json
|
||||
```
|
||||
|
||||
**偵測循環依賴**：
|
||||
```bash
|
||||
npx agent-ide deps --detect-circular
|
||||
```
|
||||
|
||||
**完整參數列表**：
|
||||
- `--file`: 分析特定檔案
|
||||
- `--all`: 分析所有檔案
|
||||
- `--format`: 輸出格式（json/graph/table）
|
||||
- `--detect-circular`: 偵測循環依賴
|
||||
- `--max-depth`: 最大依賴深度
|
||||
|
||||
### 8. 垃圾度評分 (shit)
|
||||
|
||||
**基本評分**：
|
||||
```bash
|
||||
npx agent-ide shit --format json
|
||||
```
|
||||
|
||||
**詳細報告**：
|
||||
```bash
|
||||
npx agent-ide shit --detailed --format json
|
||||
```
|
||||
|
||||
**前 N 個問題檔案**：
|
||||
```bash
|
||||
npx agent-ide shit --detailed --top=20 --format json
|
||||
```
|
||||
|
||||
**設定最大允許值（CI/CD 質量閘門）**：
|
||||
```bash
|
||||
npx agent-ide shit --max-allowed=70
|
||||
```
|
||||
|
||||
**完整參數列表**：
|
||||
- `--detailed`: 詳細報告
|
||||
- `--top`: 顯示前 N 個問題檔案
|
||||
- `--max-allowed`: CI/CD 質量閘門閾值
|
||||
- `--format`: 輸出格式（json/table/summary）
|
||||
- `--file`: 分析特定檔案
|
||||
|
||||
### 9. 程式碼重構 (refactor)
|
||||
|
||||
**提取函式**：
|
||||
```bash
|
||||
npx agent-ide refactor extract-function \
|
||||
--file src/app.ts \
|
||||
--start-line 10 \
|
||||
--end-line 20 \
|
||||
--function-name handleUser
|
||||
```
|
||||
|
||||
**內聯函式**：
|
||||
```bash
|
||||
npx agent-ide refactor inline-function \
|
||||
--file src/utils.ts \
|
||||
--function-name helperFunction
|
||||
```
|
||||
|
||||
**完整參數列表**：
|
||||
- `--file`: 目標檔案
|
||||
- `--start-line`: 起始行號（extract-function）
|
||||
- `--end-line`: 結束行號（extract-function）
|
||||
- `--function-name`: 函式名稱
|
||||
- `--preview`: 預覽模式
|
||||
|
||||
### 10. 語言解析器管理 (plugins)
|
||||
|
||||
**列出所有解析器**：
|
||||
```bash
|
||||
npx agent-ide plugins list
|
||||
```
|
||||
|
||||
**查看特定解析器資訊**：
|
||||
```bash
|
||||
npx agent-ide plugins info typescript
|
||||
```
|
||||
|
||||
**完整參數列表**：
|
||||
- `list`: 列出所有已安裝的解析器
|
||||
- `info <name>`: 顯示特定解析器的詳細資訊
|
||||
|
||||
## ShitScore 評分系統
|
||||
|
||||
### 評分維度
|
||||
- **複雜度 (30%)**：高圈複雜度、長函式、深層巢狀
|
||||
- **維護性 (30%)**：死代碼、超大檔案
|
||||
- **架構 (30%)**：循環依賴、高耦合
|
||||
- **QA (20%)**：測試覆蓋率、程式碼註解品質
|
||||
|
||||
### 評級標準
|
||||
- **A (0-29)**：優秀
|
||||
- **B (30-49)**：良好
|
||||
- **C (50-69)**：需重構
|
||||
- **D (70-84)**：強烈建議重構
|
||||
- **F (85-100)**：建議重寫
|
||||
|
||||
|
||||
## 效能指標
|
||||
|
||||
- **增量索引速度**：約 1000 檔案/秒
|
||||
- **查詢延遲**：<50ms（快取命中）
|
||||
- **記憶體佔用**：~100MB per 10k 檔案
|
||||
|
||||
## 使用建議
|
||||
|
||||
### ✅ 優先使用 agent-ide 的場景
|
||||
- 跨檔案重命名符號
|
||||
- 自動更新 import 路徑
|
||||
- 依賴關係分析
|
||||
- 程式碼品質掃描
|
||||
- 批量重構操作
|
||||
- 循環依賴檢測
|
||||
|
||||
### ❌ 保持原生工具的場景
|
||||
- 簡單檔案讀寫
|
||||
- 快速查看檔案內容
|
||||
- 單一檔案內的小改動
|
||||
|
||||
## 批量操作範例
|
||||
|
||||
### 批量重命名設定檔
|
||||
|
||||
建立 `rename-config.json`：
|
||||
```json
|
||||
{
|
||||
"renames": [
|
||||
{ "from": "oldName1", "to": "newName1" },
|
||||
{ "from": "oldName2", "to": "newName2" },
|
||||
{ "from": "oldName3", "to": "newName3" }
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
執行批量重命名：
|
||||
```bash
|
||||
npx agent-ide rename --config rename-config.json
|
||||
```
|
||||
|
||||
### 批量移動目錄
|
||||
|
||||
```bash
|
||||
# 移動整個模組
|
||||
npx agent-ide move src/legacy-module src/modules/legacy --recursive
|
||||
|
||||
# 重組專案結構
|
||||
npx agent-ide move src/utils src/shared/utils --recursive
|
||||
npx agent-ide move src/helpers src/shared/helpers --recursive
|
||||
```
|
||||
|
||||
### CI/CD 整合範例
|
||||
|
||||
```bash
|
||||
#!/bin/bash
|
||||
# quality-check.sh
|
||||
|
||||
echo "Running code quality checks..."
|
||||
|
||||
# 生成快照
|
||||
npx agent-ide snapshot --output reports/snapshot.json
|
||||
|
||||
# 檢查 ShitScore
|
||||
npx agent-ide shit --max-allowed=70 || exit 1
|
||||
|
||||
# 分析複雜度
|
||||
npx agent-ide analyze complexity --all --format json > reports/complexity.json
|
||||
|
||||
# 偵測循環依賴
|
||||
npx agent-ide deps --detect-circular || exit 1
|
||||
|
||||
echo "All quality checks passed!"
|
||||
```
|
||||
Reference in New Issue
Block a user