Initial commit

references/snapshot.md

@@ -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 的私有欄位列表（供理解內部狀態） |