zhongwei/gh-vivalalova-agent-ide-agent-ide
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Initial commit

Browse Source
This commit is contained in:
Zhongwei Li
2025-11-30 09:04:50 +08:00
commit 501144d8f2
13 changed files with 1077 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

22
skills/vivalalova__agent-ide/.claude-plugin/marketplace.json Normal file
View File

@@ -0,0 +1,22 @@
{
"name": "agent-ide-skills",
"owner": {
"name": "vivalalova",
"email": "vivalalova@gmail.com"
},
"metadata": {
"description": "AI code intelligence toolkit for refactoring, analysis, and quality assessment",
"version": "1.0.0"
},
"plugins": [
{
"name": "agent-ide",
"description": "Code refactoring and analysis toolkit using agent-ide CLI. Supports symbol renaming, file moving with import updates, dependency analysis, circular dependency detection, ShitScore quality scoring, and code snapshots. Works with TypeScript, JavaScript, and Swift projects.",
"source": "./plugins/skills/agent-ide",
"strict": false,
"skills": [
"./"
]
}
]
}

153
skills/vivalalova__agent-ide/plugins/skills/agent-ide/SKILL.md Normal file
View File

@@ -0,0 +1,153 @@
---
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 檔案）

99
skills/vivalalova__agent-ide/plugins/skills/agent-ide/references/analyze.md Normal file
View File

@@ -0,0 +1,99 @@
# 品質分析 (analyze)
> **執行方式**：以下 `agent-ide` 指 `node ${PLUGIN_ROOT}/bin/agent-ide.js`
> （PLUGIN_ROOT = 此 skill 所在 repo 根目錄，往上三層）
分析程式碼品質，支援多種分析類型。
## 分析類型
| 類型 | 說明 |
|------|------|
| `complexity` | 循環/認知複雜度（預設） |
| `dead-code` | 未使用的函式/變數 |
| `best-practices` | ES Module 等實踐檢查 |
| `patterns` | async/Promise/interface/enum 使用模式 |
| `quality` | 綜合評分（型別安全、錯誤處理、安全性、命名、測試覆蓋率） |
## 用法
```bash
# 複雜度分析（預設）
agent-ide analyze --path . --format json
# 指定分析類型
agent-ide analyze dead-code --path . --format json
agent-ide analyze quality --path . --format json
# 顯示所有結果（不只問題項目）
agent-ide analyze --path . --format json --all
```
## 參數
| 參數 | 說明 |
|------|------|
| `[type]` | 分析類型（可選） |
| `--path` | 專案路徑 |
| `--all` | 顯示所有結果 |
| `--format` | 輸出格式：`json`、`summary` |
## 輸出格式
### json（預設）
```json
{
"command": "analyze",
"success": true,
"analyzeType": "complexity",
"summary": {
"totalScanned": 25,
"issuesFound": 3,
"averageComplexity": 12.5,
"maxComplexity": 45
},
"issues": [
{
"type": "complexity",
"severity": "high",
"message": "複雜度 45，認知複雜度 32",
"filePath": "src/services/parser.ts",
"score": 45
}
]
}
```
### summary
```
🔍 分析程式碼品質...
分析類型: complexity
成功: 是
發現 16 個問題
🟡 複雜度 11，認知複雜度 9
src/api/middleware/validator.ts
🟡 複雜度 14，認知複雜度 7
src/controllers/order-controller.ts
🟠 複雜度 22，認知複雜度 7
src/models/order-model.ts
🟠 複雜度 32，認知複雜度 24
src/services/order-service.ts
... 還有 12 個問題
```
## 欄位說明
| 欄位 | 說明 |
|------|------|
| `analyzeType` | 分析類型 |
| `issues` | 問題列表 |
| `issues[].type` | 問題類型 |
| `issues[].severity` | 嚴重度：`critical`、`high`、`medium`、`low` |
| `issues[].message` | 問題描述 |
| `issues[].filePath` | 檔案路徑 |
| `issues[].score` | 分數（複雜度等） |
| `summary.averageComplexity` | 平均複雜度 |
| `summary.maxComplexity` | 最大複雜度 |

92
skills/vivalalova__agent-ide/plugins/skills/agent-ide/references/deps.md Normal file
View File

@@ -0,0 +1,92 @@
# 依賴分析 (deps)
> **執行方式**：以下 `agent-ide` 指 `node ${PLUGIN_ROOT}/bin/agent-ide.js`
> （PLUGIN_ROOT = 此 skill 所在 repo 根目錄，往上三層）
分析專案依賴關係，檢測循環依賴和孤立檔案。
## 子命令
| 子命令 | 說明 |
|--------|------|
| `graph` | 完整依賴圖 |
| `cycles` | 循環依賴分析 |
| `impact` | 影響分析 |
| `orphans` | 孤立檔案分析 |
## 用法
```bash
# 基本分析（預設顯示循環依賴和孤立檔案）
agent-ide deps --path . --format json
# 完整依賴圖
agent-ide deps --path . --format json --all
# 使用子命令
agent-ide deps graph --path . --format json
agent-ide deps cycles --path . --format json
agent-ide deps orphans --path . --format json
```
## 參數
| 參數 | 說明 |
|------|------|
| `--path` | 專案路徑 |
| `--all` | 顯示完整依賴圖 |
| `--format` | 輸出格式：`json`、`summary` |
## 輸出格式
### json（預設）
```json
{
"command": "deps",
"success": true,
"cycles": [
{ "cycle": ["a.ts", "b.ts", "c.ts"], "length": 3 }
],
"orphans": ["src/utils/unused.ts"],
"graph": {
"nodes": [{ "id": "src/index.ts", "label": "index" }],
"edges": [{ "from": "src/index.ts", "to": "src/app.ts" }]
},
"summary": {
"totalScanned": 50,
"totalFiles": 50,
"totalDependencies": 120,
"cyclesFound": 1,
"orphanedFiles": 3
}
}
```
### summary
```
🔍 分析依賴關係...
未發現循環依賴
孤立檔案: 12 個
- src/index.ts
- src/quality-test/error-handling-bad.ts
- src/quality-test/naming-violations.ts
- src/utils/array-utils.ts
- src/utils/date-utils.ts
... 還有 7 個
```
## 欄位說明
| 欄位 | 說明 |
|------|------|
| `cycles` | 循環依賴列表 |
| `cycles[].cycle` | 循環路徑 |
| `cycles[].length` | 循環長度 |
| `orphans` | 孤立檔案列表（無被引用） |
| `graph.nodes` | 依賴圖節點 |
| `graph.edges` | 依賴圖邊 |
| `summary.cyclesFound` | 發現的循環數 |
| `summary.orphanedFiles` | 孤立檔案數 |

82
skills/vivalalova__agent-ide/plugins/skills/agent-ide/references/move.md Normal file
View File

@@ -0,0 +1,82 @@
# 檔案移動 (move)
> **執行方式**：以下 `agent-ide` 指 `node ${PLUGIN_ROOT}/bin/agent-ide.js`
> （PLUGIN_ROOT = 此 skill 所在 repo 根目錄，往上三層）
移動檔案並自動更新所有 import。
## 用法
```bash
# 預覽影響
agent-ide move src/api/user.ts src/services/user.service.ts --path . --dry-run
# 執行移動
agent-ide move src/api/user.ts src/services/user.service.ts --path .
```
## 參數
| 參數 | 說明 |
|------|------|
| `<source>` | 來源檔案路徑 |
| `<target>` | 目標檔案路徑 |
| `--path` | 專案路徑 |
| `--dry-run` | 預覽模式，不實際執行 |
| `--format` | 輸出格式：`json`、`summary`、`diff` |
## 輸出格式
### diff（預設）
```diff
--- a/src/index.ts
+++ b/src/index.ts
@@ -1,5 +1,5 @@
-import { User } from './api/user';
+import { User } from './services/user.service';
Summary: 2 files, 3 changes, (+1 -1)
```
### summary
```
Moved 'user.ts' to 'user.service.ts'
Files: 2
Changes: 3 (+1 -1)
Files:
src/index.ts: import updated (+1 -1)
```
### json
```json
{
"command": "move",
"success": true,
"files": [
{
"filePath": "src/index.ts",
"hunks": [
{
"header": "@@ -1,5 +1,5 @@",
"lines": [
{ "type": "delete", "lineNumber": 1, "content": "import { User } from './api/user';" },
{ "type": "add", "lineNumber": 1, "content": "import { User } from './services/user.service';" }
]
}
]
}
],
"summary": { "totalFiles": 2, "totalChanges": 3 }
}
```
## 特性
- 自動更新所有引用該檔案的 import 路徑
- 支援相對路徑和絕對路徑
- 保留原始檔案的 import 語句

118
skills/vivalalova__agent-ide/plugins/skills/agent-ide/references/refactor.md Normal file
View File

@@ -0,0 +1,118 @@
# 重構 (refactor)
> **執行方式**：以下 `agent-ide` 指 `node ${PLUGIN_ROOT}/bin/agent-ide.js`
> （PLUGIN_ROOT = 此 skill 所在 repo 根目錄，往上三層）
提取函數、內聯函數等重構操作。
## 支援的動作
| 動作 | 說明 |
|------|------|
| `extract-function` | 提取程式碼為函數（TS/JS） |
| `extract-closure` | 提取程式碼為閉包（Swift） |
| `inline-function` | 內聯函數呼叫 |
## 用法
```bash
# 提取函數
agent-ide refactor extract-function --file src/file.ts --start-line 10 --end-line 20 --function-name newFn --dry-run
# 提取閉包（Swift）
agent-ide refactor extract-closure --file src/file.swift --start-line 10 --end-line 20 --function-name newClosure --dry-run
# 跨檔案提取（提取到新檔案並自動加入 import）
agent-ide refactor extract-function --file src/file.ts -s 10 -e 20 -n helper --target-file src/utils.ts --dry-run
# 內聯函數
agent-ide refactor inline-function --file src/file.ts --function-name helperFn --dry-run
```
## 參數
### extract-function / extract-closure
| 參數 | 說明 |
|------|------|
| `--file` | 來源檔案路徑 |
| `-s, --start-line` | 起始行號 |
| `-e, --end-line` | 結束行號 |
| `-n, --function-name` | 新函數名稱 |
| `-t, --target-file` | 目標檔案（跨檔案提取） |
| `--dry-run` | 預覽模式 |
| `--format` | 輸出格式 |
### inline-function
| 參數 | 說明 |
|------|------|
| `--file` | 檔案路徑 |
| `--function-name` | 要內聯的函數名稱 |
| `--dry-run` | 預覽模式 |
| `--format` | 輸出格式 |
## 輸出格式
### diff（預設）
```diff
--- a/src/services/order-service.ts
+++ b/src/services/order-service.ts
@@ -1,4 +1,4 @@
+function extractedFn(order: Order) {
+ // extracted code
+}
+
export class OrderService {
processOrder(order: Order) {
- // original code here
+ extractedFn(order);
}
}
Summary: 1 file, 4 changes, (+2 -2)
```
### summary
```
Extracted function 'extractedFn'
Files: 1
Changes: 4 (+2 -2)
Files:
src/services/order-service.ts: code refactored (+2 -2)
```
### json
```json
{
"command": "refactor",
"success": true,
"files": [
{
"filePath": "src/file.ts",
"hunks": [
{
"header": "@@ -10,15 +10,20 @@",
"lines": [
{ "type": "add", "lineNumber": 10, "content": "function newFn() {" },
{ "type": "add", "lineNumber": 11, "content": " // extracted code" },
{ "type": "add", "lineNumber": 12, "content": "}" }
]
}
]
}
],
"summary": { "totalFiles": 1, "totalChanges": 5 }
}
```
## 特性
- 自動分析變數依賴，生成正確的參數列表
- 跨檔案提取自動加入 import/export
- 內聯時自動處理參數替換

103
skills/vivalalova__agent-ide/plugins/skills/agent-ide/references/rename.md Normal file
View File

@@ -0,0 +1,103 @@
# 符號重命名 (rename)
> **執行方式**：以下 `agent-ide` 指 `node ${PLUGIN_ROOT}/bin/agent-ide.js`
> （PLUGIN_ROOT = 此 skill 所在 repo 根目錄，往上三層）
安全地跨專案重命名符號。
## 用法
```bash
# 預覽變更
agent-ide rename --path . --from getUserData --to fetchUserProfile --dry-run
# 執行重命名
agent-ide rename --path . --from getUserData --to fetchUserProfile
```
## 參數
| 參數 | 說明 |
|------|------|
| `--path` | 專案路徑 |
| `--from` | 原始符號名稱 |
| `--to` | 新符號名稱 |
| `--dry-run` | 預覽模式，不實際執行 |
| `--format` | 輸出格式：`json`、`summary`、`diff` |
## 輸出格式
### diff（預設）
```diff
--- a/src/models/user-model.ts
+++ b/src/models/user-model.ts
@@ -6,7 +6,7 @@
import { BaseModel } from './base-model';
-UserModel
+UserEntity
constructor(user: User) {
--- a/src/services/user-service.ts
+++ b/src/services/user-service.ts
@@ -5,10 +5,10 @@
-UserModel
+UserEntity
Summary: 2 files, 8 changes, (+4 -4)
```
### summary
```
Renamed 'UserModel' to 'UserEntity'
Files: 2
Changes: 8 (+4 -4)
Files:
src/models/user-model.ts: symbol renamed (+1 -1)
src/services/user-service.ts: symbol renamed (+3 -3)
```
### json
```json
{
"command": "rename",
"success": true,
"files": [
{
"filePath": "src/services/user.ts",
"hunks": [
{
"header": "@@ -10,7 +10,7 @@",
"oldStart": 10,
"oldCount": 7,
"newStart": 10,
"newCount": 7,
"lines": [
{ "type": "context", "lineNumber": 10, "content": "export class UserService {" },
{ "type": "delete", "lineNumber": 11, "content": " getUserData() {" },
{ "type": "add", "lineNumber": 11, "content": " fetchUserProfile() {" }
]
}
]
}
],
"summary": { "totalFiles": 3, "totalChanges": 5 }
}
```
## 欄位說明
| 欄位 | 說明 |
|------|------|
| `files` | 受影響的檔案列表 |
| `files[].filePath` | 檔案路徑 |
| `files[].hunks` | 變更區塊列表 |
| `hunks[].header` | diff header |
| `hunks[].lines` | 變更行（context/delete/add） |
| `summary.totalFiles` | 總受影響檔案數 |
| `summary.totalChanges` | 總變更數 |

111
skills/vivalalova__agent-ide/plugins/skills/agent-ide/references/search.md Normal file
View File

@@ -0,0 +1,111 @@
# 程式碼搜尋 (search)
> **執行方式**：以下 `agent-ide` 指 `node ${PLUGIN_ROOT}/bin/agent-ide.js`
> （PLUGIN_ROOT = 此 skill 所在 repo 根目錄，往上三層）
支援多種搜尋類型的強大搜尋功能。
## 搜尋類型
| 類型 | 說明 |
|------|------|
| `text` | 文字搜尋（預設） |
| `regex` | 正規表達式搜尋 |
| `fuzzy` | 模糊搜尋（容錯匹配） |
| `symbol` | 符號名稱搜尋 |
| `structural` | 結構化搜尋（按類型過濾） |
## 用法
```bash
# 文字搜尋
agent-ide search "UserService" --path . --format json
# 正規表達式搜尋
agent-ide search "function.*User" --path . -t regex --format json
# 模糊搜尋
agent-ide search "usrSvc" --path . -t fuzzy --format json
# 符號搜尋（支援萬用字元）
agent-ide search symbol --query "User*" --path . --format json
# 結構化搜尋（按類型過濾）
agent-ide search structural -t class --pattern "Service" --path . --format json
```
## 進階過濾選項
```bash
# 過濾帶有特定屬性的符號
agent-ide search structural -t class --with-attribute "@Observable" --path .
# 過濾實作特定協定的類別
agent-ide search structural -t class --implements "Codable" --path .
# 過濾繼承特定類別的子類別
agent-ide search structural -t class --extends "BaseService" --path .
```
## 參數
| 參數 | 說明 |
|------|------|
| `<query>` | 搜尋關鍵字 |
| `--path` | 專案路徑 |
| `-t, --type` | 搜尋類型 |
| `--query` | 符號搜尋的查詢字串 |
| `--pattern` | 結構化搜尋的模式 |
| `--format` | 輸出格式：`json`、`summary` |
## 輸出格式
### json（預設）
```json
{
"command": "search",
"success": true,
"results": [
{
"filePath": "src/services/user.ts",
"line": 15,
"column": 10,
"content": "UserService",
"context": ["import { Injectable } from '@nestjs/common';", ""]
}
],
"summary": { "totalScanned": 50, "issuesFound": 3 },
"truncated": false,
"searchTime": 45
}
```
### summary
```
🔍 搜尋: "function"
找到 50 個結果
搜尋耗時: 25ms
(結果已截斷)
src/quality-test/error-handling-bad.ts:8:1
function
src/quality-test/naming-violations.ts:29:1
function
src/services/user-service.ts:15:1
function
```
## 欄位說明
| 欄位 | 說明 |
|------|------|
| `results` | 搜尋結果列表 |
| `results[].filePath` | 檔案路徑 |
| `results[].line` | 行號 |
| `results[].column` | 欄位 |
| `results[].content` | 匹配內容 |
| `results[].context` | 上下文行 |
| `truncated` | 結果是否被截斷 |
| `searchTime` | 搜尋耗時（毫秒） |

95
skills/vivalalova__agent-ide/plugins/skills/agent-ide/references/shift.md Normal file
View File

@@ -0,0 +1,95 @@
# 程式碼移動 (shift)
> **執行方式**：以下 `agent-ide` 指 `node ${PLUGIN_ROOT}/bin/agent-ide.js`
> （PLUGIN_ROOT = 此 skill 所在 repo 根目錄，往上三層）
在檔案內或跨檔案移動程式碼行。
## 用法
```bash
# 同檔案內移動
agent-ide shift src/file.ts --from 2 --to 5 --position 10 --dry-run
# 移到新檔案
agent-ide shift src/old.ts --from 1 --to 3 --target src/new.ts --position 1
```
## 參數
| 參數 | 說明 |
|------|------|
| `<file>` | 來源檔案路徑 |
| `--from` | 起始行號 |
| `--to` | 結束行號 |
| `--position` | 目標位置行號 |
| `--target` | 目標檔案（跨檔案移動） |
| `--dry-run` | 預覽模式，不實際執行 |
| `--format` | 輸出格式：`json`、`summary`、`diff` |
## 輸出格式
### diff（預設）
```diff
--- a/src/utils/string-utils.ts
+++ b/src/utils/string-utils.ts
@@ -2,10 +2,12 @@
* String Utils
*/
-export function capitalize(str: string): string {
- if (!str) {
- return str;
- }
+export function capitalize(str: string): string {
+ if (!str) {
+ return str;
+ }
+ return str.charAt(0).toUpperCase() + str.slice(1).toLowerCase();
+}
Summary: 1 file, 10 changes, (+6 -4)
```
### summary
```
Moved 6 lines within file (5-10 → 15)
Files: 1
Changes: 10 (+6 -4)
Files:
src/utils/string-utils.ts: lines moved (+6 -4)
```
### json
```json
{
"command": "shift",
"success": true,
"files": [
{
"filePath": "src/file.ts",
"hunks": [
{
"header": "@@ -2,10 +2,10 @@",
"lines": [
{ "type": "delete", "lineNumber": 2, "content": " function oldPosition() {" },
{ "type": "add", "lineNumber": 10, "content": " function oldPosition() {" }
]
}
]
}
],
"summary": { "totalFiles": 1, "totalChanges": 2 }
}
```
## 使用場景
- 重新排列函數順序
- 將程式碼片段移到新檔案
- 整理程式碼結構

107
skills/vivalalova__agent-ide/plugins/skills/agent-ide/references/snapshot.md Normal file
View File

@@ -0,0 +1,107 @@
# 模組快照 (snapshot)
> **執行方式**：以下 `agent-ide` 指 `node ${PLUGIN_ROOT}/bin/agent-ide.js`
> （PLUGIN_ROOT = 此 skill 所在 repo 根目錄，往上三層）
產生模組/專案快照供 AI 快速理解程式碼結構，大幅減少 token 使用量（~91% 節省）。
## 用法
```bash
# 模組快照（指定模組目錄）
agent-ide snapshot --path src/core/indexing --format json
# 專案快照（自動偵測所有模組）
agent-ide snapshot --path . --format json
# 人類可讀摘要
agent-ide snapshot --path src/core/indexing --format summary
```
## 參數
| 參數 | 說明 |
|------|------|
| `--path` | 目標路徑 |
| `--format` | 輸出格式：`json`、`summary` |
## 自動偵測規則
| 條件 | 結果 |
|------|------|
| 有 `package.json` + `src/` 目錄 | 專案快照（掃描所有模組） |
| 有 `index.ts` | 模組快照 |
| 其他 | 視為模組 |
## 輸出結構
| 欄位 | 說明 |
|------|------|
| `command` | 命令類型（`snapshot`） |
| `success` | 執行是否成功 |
| `summary` | 統計摘要（掃描數量等） |
| `snapshotType` | 快照類型（`module` 或 `project`） |
| `snapshot.module` | 模組名稱（module 類型） |
| `snapshot.project` | 專案名稱（project 類型） |
| `snapshot.modules` | 各模組快照（project 類型） |
| `snapshot.api` | Class 的 public 方法及簽章 |
| `snapshot.factories` | `createXxx` 工廠函數及簽章 |
| `snapshot.types` | Interface 和 Type 定義 |
| `snapshot.private` | Class 私有欄位（供理解內部狀態） |
## 輸出格式
### json（預設）
```json
{
"command": "snapshot",
"success": true,
"summary": { "totalScanned": 1 },
"snapshotType": "module",
"snapshot": {
"module": "indexing",
"api": {
"IndexEngine": {
"findSymbol": "(name: string, options?: SearchOptions) → Promise<SymbolSearchResult[]>",
"indexProject": "() → Promise<void>"
}
},
"factories": {
"createIndexConfig": "(workspacePath: string, options?: Partial<IndexConfig>) → IndexConfig"
},
"types": {
"FileChangeType": "'add' | 'change' | 'unlink'"
},
"private": {
"IndexEngine": { "fields": ["config", "fileIndex"] }
}
}
}
```
### summary
```
📦 專案: sample-project
📁 模組數: 2
📂 src
API: 20 classes
Factories: 4
Types: 54
📂 src/types
API: 0 classes
Factories: 0
Types: 43
```
## 快照內容說明
| 區塊 | 內容 |
|------|------|
| `api` | Class 的 public 方法及其完整簽章 |
| `factories` | `createXxx` 開頭的工廠函數 |
| `types` | Interface 和 Type alias 定義 |
| `private` | Class 的私有欄位列表（供理解內部狀態） |