From b8eff6f333cb0af5cdd5dfa80b5b4cb953f5148e Mon Sep 17 00:00:00 2001 From: Zhongwei Li Date: Sat, 29 Nov 2025 18:18:29 +0800 Subject: [PATCH] Initial commit --- .claude-plugin/plugin.json | 12 + README.md | 3 + commands/analyze-java-domain-flow.md | 374 +++++++++ commands/analyze-java-domain.md | 804 +++++++++++++++++++ commands/analyze-java.md | 1076 ++++++++++++++++++++++++++ plugin.lock.json | 53 ++ 6 files changed, 2322 insertions(+) create mode 100644 .claude-plugin/plugin.json create mode 100644 README.md create mode 100644 commands/analyze-java-domain-flow.md create mode 100644 commands/analyze-java-domain.md create mode 100644 commands/analyze-java.md create mode 100644 plugin.lock.json diff --git a/.claude-plugin/plugin.json b/.claude-plugin/plugin.json new file mode 100644 index 0000000..8d4c187 --- /dev/null +++ b/.claude-plugin/plugin.json @@ -0,0 +1,12 @@ +{ + "name": "legacy-analyzer", + "description": "使用多個專門代理配合基於置信度的評分系統，分析 Legacy Java Spring Boot 專案並產生高品質教學文件", + "version": "1.4.0", + "author": { + "name": "Dennis Liu (繁體中文版)", + "email": "nossi1970@hotmail.com" + }, + "commands": [ + "./commands" + ] +} \ No newline at end of file diff --git a/README.md b/README.md new file mode 100644 index 0000000..af7dced --- /dev/null +++ b/README.md @@ -0,0 +1,3 @@ +# legacy-analyzer + +使用多個專門代理配合基於置信度的評分系統，分析 Legacy Java Spring Boot 專案並產生高品質教學文件 diff --git a/commands/analyze-java-domain-flow.md b/commands/analyze-java-domain-flow.md new file mode 100644 index 0000000..4fc797a --- /dev/null +++ b/commands/analyze-java-domain-flow.md @@ -0,0 +1,374 @@ +--- +description: 高效分析 Java Spring Boot 專案的調用鏈與流程圖（單一檔案輸出） +allowed-tools: + - Task + - TodoWrite + - Read + - Write + - Glob + - Grep + - Bash +--- + +# Legacy Java Domain Flow Analyzer + +專注於**調用鏈追蹤與流程圖生成**的高效領域分析工具。 + +**使用方式**： +``` +/legacy-analyzer:analyze-java-domain-flow 商品建立 +/legacy-analyzer:analyze-java-domain-flow 訂單取消 +/legacy-analyzer:analyze-java-domain-flow 用戶登入 +``` + +**與 analyze-java-domain 的差異**： +| 比較項目 | analyze-java-domain | analyze-java-domain-flow | +|---------|---------------------|--------------------------| +| 輸出檔案 | 6 個 Markdown 檔案 (~850行) | 單一檔案 (~300行) | +| 執行時間 | 4-6 分鐘 | 2-3 分鐘 | +| 核心內容 | 完整領域文件 | 調用鏈 + 流程圖 | +| 資料模型 | 詳細 DTO/Entity 說明 | 僅列出涉及類別 | +| 業務規則 | 完整規則文件 | 不包含 | + +--- + +## 搜尋範圍 + +**只搜尋**：`.java`、`.xml`（MyBatis Mapper） +**排除**：`pom.xml`、`.yml`、`.properties` + +--- + +要執行此操作，請精確遵循以下步驟： + +## 階段 1: 入口點發現（Haiku，~30秒） + +1. **解析使用者輸入**，產生搜尋策略： + + ```json + { + "domain": "商品建立", + "keywords": { + "chinese": ["商品", "產品", "建立", "新增"], + "english": ["Product", "Item", "Create", "Add", "Save"], + "patterns": ["create.*Product", "add.*Product", "Product.*Controller"] + } + } + ``` + +2. 使用 **Haiku 代理**快速定位入口點： + + **搜尋策略**（必須限制檔案類型）： + ``` + Grep: pattern="@(Post|Put|Get|Delete)Mapping.*{keyword}" glob="*.java" + Grep: pattern="class.*{keyword}.*(Controller|Service)" glob="*.java" + ``` + + **輸出入口點 JSON**： + ```json + { + "entry_points": [ + { + "file": "ProductController.java", + "method": "createProduct", + "http": "POST /api/products", + "line": 67 + } + ], + "related_classes": ["ProductController", "ProductService", "ProductRepository"] + } + ``` + +3. **如果找不到入口點**，終止並建議： + ``` + 找不到與「{關鍵字}」相關的程式碼。 + 建議：使用英文關鍵字如 "Product" 或 "Order" + ``` + +--- + +## 階段 2: 調用鏈追蹤（Sonnet，~1-2分鐘） + +4. 對每個入口點（最多 3 個），啟動 **Sonnet 代理**並行追蹤。 + + **追蹤規則**： + - 從 Controller → Service → Repository → MyBatis XML + - 最大深度：5 層 + - 只追蹤專案內程式碼（遇到框架類別標記為「框架內建」停止） + + **追蹤步驟**： + + a. 讀取 Controller 方法，找出調用的 Service + b. 讀取 Service 實現類別，找出調用的 Repository/其他 Service + c. 讀取 Repository，識別 JPA 方法或 MyBatis Mapper + d. 如果是 MyBatis，讀取對應的 XML Mapper 檔案 + + **輸出調用鏈 JSON**： + ```json + { + "chain_id": "chain-1", + "entry": "POST /api/products → ProductController.createProduct", + "nodes": [ + { + "level": 0, + "layer": "Controller", + "class": "ProductController", + "method": "createProduct(ProductDTO)", + "file": "src/.../ProductController.java:67-85", + "calls": ["productService.create"] + }, + { + "level": 1, + "layer": "Service", + "class": "ProductServiceImpl", + "method": "create(ProductDTO)", + "file": "src/.../ProductServiceImpl.java:45-78", + "annotations": ["@Transactional"], + "logic": "檢查名稱重複 → 轉換 DTO → 保存", + "calls": ["productRepo.existsByName", "productRepo.save"] + }, + { + "level": 2, + "layer": "Repository", + "class": "ProductRepository", + "method": "save(Product)", + "file": "src/.../ProductRepository.java:12", + "type": "JPA 內建方法" + } + ], + "classes_involved": ["ProductController", "ProductServiceImpl", "ProductRepository", "Product", "ProductDTO"] + } + ``` + +5. 收集所有調用鏈結果 + +--- + +## 階段 3: 流程驗證與評分（Haiku，~20秒） + +6. 對每條調用鏈啟動 **Haiku 代理**進行驗證評分： + + **驗證維度**： + - **路徑完整性 (40%)**：調用鏈是否從入口到資料層完整 + - **證據準確性 (40%)**：檔案路徑和行號是否正確 + - **邏輯清晰度 (20%)**：流程描述是否清楚 + + **輸出評分 JSON**： + ```json + { + "chain_id": "chain-1", + "scores": { + "completeness": 95, + "accuracy": 90, + "clarity": 85 + }, + "total": 91, + "status": "verified" + } + ``` + + **狀態判定**： + - `total >= 80`：verified (已驗證) + - `total >= 60`：partial (部分驗證) + - `total < 60`：unverified (未驗證，標記警告) + +--- + +## 階段 4: 流程圖與文件生成（Sonnet，~1分鐘） + +7. 啟動 **Sonnet 代理**生成單一 Markdown 文件。 + + **文件結構**（目標 ~300 行）： + + ```markdown + # {領域名稱} 調用鏈分析 + + > 自動生成於 {timestamp} | 驗證狀態: {N} 條已驗證 + + ## 快速概覽 + + | 項目 | 數值 | + |------|------| + | 入口點 | {N} 個 | + | 調用鏈 | {M} 條 | + | 涉及類別 | {K} 個 | + | 平均深度 | {D} 層 | + + ## 入口點總覽 + + | HTTP 方法 | 路徑 | Controller.方法 | 驗證狀態 | + |-----------|------|-----------------|----------| + | POST | /api/products | ProductController.createProduct | verified | + + --- + + ## 調用鏈 1: {簡短描述} + + **入口**: `POST /api/products` → `ProductController.createProduct` + **狀態**: verified (91分) + + ### 流程圖 + + ```mermaid + sequenceDiagram + participant C as Controller + participant S as Service + participant R as Repository + participant DB as Database + + C->>S: productService.create(dto) + S->>S: 檢查名稱重複 + S->>R: productRepo.existsByName(name) + R->>DB: SELECT EXISTS + DB-->>R: boolean + R-->>S: false + S->>R: productRepo.save(product) + R->>DB: INSERT + DB-->>R: Product + R-->>S: Product + S-->>C: ProductDTO + ``` + + ### 調用層級 + + | 層級 | 類別.方法 | 檔案位置 | 說明 | + |------|----------|----------|------| + | 0 | ProductController.createProduct | ProductController.java:67 | 接收請求 | + | 1 | ProductServiceImpl.create | ProductServiceImpl.java:45 | 業務邏輯 | + | 2 | ProductRepository.save | ProductRepository.java:12 | 資料存取 | + + ### 關鍵邏輯 (`ProductServiceImpl.java:50-55`) + + ```java + if (productRepo.existsByName(dto.getName())) { + throw new ProductExistsException(); + } + Product product = mapper.toEntity(dto); + return productRepo.save(product); + ``` + + --- + + ## 整體架構圖 + + ```mermaid + flowchart TD + subgraph Controller Layer + A[ProductController] + end + subgraph Service Layer + B[ProductServiceImpl] + end + subgraph Repository Layer + C[ProductRepository] + end + subgraph Database + D[(products)] + end + + A -->|createProduct| B + B -->|existsByName| C + B -->|save| C + C --> D + ``` + + --- + + ## 涉及類別清單 + + | 類別 | 類型 | 檔案位置 | + |------|------|----------| + | ProductController | Controller | src/.../ProductController.java | + | ProductServiceImpl | Service | src/.../ProductServiceImpl.java | + | ProductRepository | Repository | src/.../ProductRepository.java | + | Product | Entity | src/.../Product.java | + | ProductDTO | DTO | src/.../ProductDTO.java | + + --- + + ## 驗證摘要 + + | 調用鏈 | 完整性 | 準確性 | 清晰度 | 總分 | 狀態 | + |--------|--------|--------|--------|------|------| + | chain-1: 建立商品 | 95 | 90 | 85 | 91 | verified | + ``` + + **文件撰寫規則**： + - 使用繁體中文 + - 每條調用鏈必須有 **Mermaid sequenceDiagram** + - 文件末尾必須有 **整體架構 flowchart** + - 程式碼片段限制 5-10 行 + - 所有檔案引用必須包含行號 + - **禁止**：改善建議、效能優化、測試策略 + +8. 將文件寫入：`.legacy-analysis/flow-{keyword}-{timestamp}/DOMAIN-FLOW.md` + +--- + +## 完成 + +9. 顯示完成摘要： + + ``` + ╔═══════════════════════════════════════════════════════════╗ + ║ Domain Flow Analyzer - 分析完成 ║ + ╚═══════════════════════════════════════════════════════════╝ + + 🎯 分析領域: {領域關鍵字} + + 📁 輸出位置: .legacy-analysis/flow-{keyword}-{timestamp}/DOMAIN-FLOW.md + + 📊 分析結果: + - 入口點: {N} 個 + - 調用鏈: {M} 條 (已驗證: {V} 條) + - 涉及類別: {K} 個 + - 平均驗證分數: {score} + + 📈 調用鏈概覽: + 1. POST /api/products → ProductController.createProduct [91分] + 2. ... + + 🔗 快速導覽: + - 整體架構圖: DOMAIN-FLOW.md#整體架構圖 + - 調用鏈詳解: DOMAIN-FLOW.md#調用鏈-1-{描述} + + 💡 特色: + - 單一檔案輸出（約 300 行） + - 包含 Mermaid 序列圖與架構圖 + - 所有調用鏈經過驗證評分 + ``` + +--- + +## 執行時間估算 + +| 階段 | 時間 | 模型 | +|------|------|------| +| 入口點發現 | ~30秒 | Haiku | +| 調用鏈追蹤 | ~1-2分鐘 | Sonnet (並行) | +| 流程驗證 | ~20秒 | Haiku (並行) | +| 文件生成 | ~1分鐘 | Sonnet | +| **總計** | **~2-3分鐘** | | + +--- + +## 與 analyze-java-domain 的配合使用 + +``` +場景 1: 快速了解流程 + → 使用 analyze-java-domain-flow（2-3分鐘） + → 獲得調用鏈圖表 + +場景 2: 深度了解領域 + → 先用 analyze-java-domain-flow 掌握流程 + → 再用 analyze-java-domain 獲得完整文件 +``` + +--- + +## 重要注意事項 + +- **核心輸出**：調用鏈 + Mermaid 流程圖（不包含資料模型、業務規則詳解） +- **單一檔案**：所有內容整合到一個 Markdown 檔案 +- **驗證機制**：每條調用鏈都有驗證評分，確保準確性 +- **效率優先**：比 analyze-java-domain 快約 50% diff --git a/commands/analyze-java-domain.md b/commands/analyze-java-domain.md new file mode 100644 index 0000000..04c15aa --- /dev/null +++ b/commands/analyze-java-domain.md @@ -0,0 +1,804 @@ +--- +description: 分析 Legacy Java Spring Boot 專案中的特定領域邏輯與業務流程 +allowed-tools: + - Task + - TodoWrite + - Read + - Write + - Glob + - Grep + - Bash +--- + +# Legacy Java Domain Analyzer + +針對使用者指定的領域/功能關鍵字，深度分析 Java Spring Boot 專案中的相關邏輯與完整調用鏈。 + +**使用方式**： +``` +/legacy-analyzer:analyze-java-domain 請分析商品建立的流程 +/legacy-analyzer:analyze-java-domain 分析訂單取消邏輯 +/legacy-analyzer:analyze-java-domain 整理用戶註冊流程 +``` + +**與 analyze-java 的差異**： +- `analyze-java`：掃描全專案，生成完整文件（7-9 分鐘） +- `analyze-java-domain`：定向搜尋特定領域，深度追蹤調用鏈（3-5 分鐘） + +--- + +## 搜尋範圍限制 + +**只搜尋以下檔案類型**： +- `.java` - Java 原始碼（Controller, Service, Repository, Entity 等） +- `.xml` - MyBatis Mapper 檔案（SQL 查詢邏輯） + +**排除的檔案**： +- `pom.xml` - Maven 依賴定義 +- `build.gradle` - Gradle 依賴定義 +- `.yml` / `.yaml` / `.properties` - 配置檔（與領域邏輯無關） + +**Grep 搜尋時必須使用 glob 參數限制範圍**： +``` +# 正確方式 +Grep: pattern="關鍵字" glob="*.java" +Grep: pattern="關鍵字" glob="*.xml" （排除 pom.xml 的結果） + +# 錯誤方式（不要這樣做） +Grep: pattern="關鍵字" （會搜尋所有檔案） +``` + +--- + +要執行此操作，請精確遵循以下步驟： + +## 準備工作 + +1. **解析使用者輸入**，識別： + - **領域關鍵字**（Domain Keywords）：如「商品建立」、「訂單取消」、「用戶註冊」 + - **搜尋關鍵字**（Search Keywords）：從領域關鍵字推導出可能的： + - 中文詞彙：商品、產品、建立、新增、創建 + - 英文詞彙：Product, Item, Goods, Create, Add, Insert + - 方法名：createProduct, addProduct, insertProduct, saveProduct + - 類別名：ProductController, ProductService, ProductRepository + - API 路徑：/product, /products, /api/product + + **輸出搜尋策略 JSON**： + ```json + { + "user_query": "商品建立的流程", + "domain": "商品建立", + "search_keywords": { + "chinese": ["商品", "產品", "建立", "新增", "創建"], + "english": ["Product", "Item", "Goods", "Create", "Add", "Save"], + "method_patterns": ["create.*Product", "add.*Product", "save.*Product", "insert.*Product"], + "class_patterns": ["Product.*Controller", "Product.*Service", "Product.*Repository"], + "api_patterns": ["/product", "/products", "POST.*product"] + } + } + ``` + +2. 使用 TodoWrite 建立待辦事項清單 + +3. 創建工作目錄：`.legacy-analysis/domain-{keyword}-{timestamp}/` + - keyword：領域關鍵字的英文簡寫（如 product-create） + +--- + +## 階段 1: 快速資格檢查與入口點發現 + +4. 使用 **Haiku 代理**快速檢查專案並找出入口點： + + **代理任務**： + - 確認是 Spring Boot 專案（檢查 pom.xml 或 build.gradle） + - 使用 Grep 搜尋所有搜尋關鍵字，統計匹配數量 + - 識別最可能的**入口點**（Entry Points）： + - Controller 類別中包含關鍵字的方法 + - API 端點（@RequestMapping, @PostMapping, @GetMapping） + + **搜尋策略**（必須限制檔案類型）： + ``` + # 搜尋 Controller 中的相關端點（只搜尋 .java） + Grep: pattern="@(Post|Put|Get|Delete)Mapping.*product" glob="*.java" + Grep: pattern="@RequestMapping.*product" glob="*.java" + + # 搜尋 Service 中的相關方法（只搜尋 .java） + Grep: pattern="(create|add|save|insert).*Product" glob="*.java" + + # 搜尋類別定義（只搜尋 .java） + Grep: pattern="class.*Product.*(Controller|Service|Repository)" glob="*.java" + + # 搜尋 MyBatis Mapper 中的相關 SQL（只搜尋 .xml，排除 pom.xml） + Grep: pattern="<(select|insert|update|delete).*product" glob="*.xml" + # 注意：過濾結果時排除 pom.xml + ``` + + **輸出入口點 JSON**： + ```json + { + "project_valid": true, + "total_matches": 45, + "entry_points": [ + { + "type": "controller", + "file": "src/main/java/com/example/controller/ProductController.java", + "method": "createProduct", + "http_method": "POST", + "path": "/api/products", + "line": 67 + }, + { + "type": "controller", + "file": "src/main/java/com/example/controller/ProductController.java", + "method": "addProduct", + "http_method": "POST", + "path": "/api/products/add", + "line": 112 + } + ], + "related_classes": [ + "ProductController", + "ProductService", + "ProductServiceImpl", + "ProductRepository", + "Product", + "ProductDTO" + ] + } + ``` + + **如果匹配數量 = 0**，輸出建議並終止： + ``` + ❌ 找不到與「{領域關鍵字}」相關的程式碼 + + 建議嘗試： + 1. 使用不同的關鍵字（如「商品」改為「Product」或「Item」） + 2. 確認專案中是否有此功能 + 3. 使用 /legacy-analyzer:analyze-java 進行全專案掃描 + ``` + +5. 將入口點資訊寫入：`.legacy-analysis/domain-{keyword}-{timestamp}/01-entry-points.json` + +--- + +## 階段 2: 深度調用鏈追蹤 + +6. 對於每個入口點，啟動一個 **Sonnet 代理**進行深度追蹤。 + + **如果入口點 <= 3 個**：全部並行啟動 + **如果入口點 > 3 個**：只追蹤最重要的 3 個（根據 HTTP 方法優先級：POST > PUT > DELETE > GET） + + **每個追蹤代理的任務**： + + 從入口點開始，遞歸追蹤完整的調用鏈： + + ``` + Controller.method() + ↓ 調用 + Service.method() + ↓ 調用 + Repository.method() + ↓ 操作 + Entity + ``` + + **追蹤步驟**： + + a. **讀取入口 Controller 方法**： + - 使用 Read 讀取 Controller 檔案（.java） + - 找到目標方法 + - 識別方法內調用的 Service + + b. **追蹤 Service 層**： + - 讀取 Service 介面和實現類別（.java） + - 分析業務邏輯 + - 識別調用的 Repository 和其他 Service + + c. **追蹤 Repository 層**： + - 讀取 Repository 介面（.java） + - 識別自定義查詢方法 + - **如果使用 MyBatis**：搜尋對應的 Mapper XML 檔案 + ``` + # 根據 Repository/Mapper 介面名稱搜尋對應的 XML + Glob: pattern="**/ProductMapper.xml" + # 或搜尋 XML 中的 namespace + Grep: pattern="namespace.*ProductMapper" glob="*.xml" + ``` + + d. **追蹤 MyBatis Mapper XML**（如果存在）： + - 讀取 Mapper XML 檔案 + - 分析 SQL 語句（select, insert, update, delete） + - 識別動態 SQL（if, choose, foreach） + - 記錄 resultMap 和參數映射 + + e. **分析相關 Entity**： + - 讀取涉及的 Entity 類別（.java） + - 分析欄位和關聯關係 + + f. **識別橫切關注點**： + - @Transactional 事務邊界 + - 異常處理 + - 驗證邏輯（@Valid） + - 日誌記錄 + + **輸出調用鏈 JSON**： + ```json + { + "entry_point": { + "file": "ProductController.java", + "method": "createProduct", + "line": 67 + }, + "call_chain": [ + { + "level": 0, + "type": "controller", + "class": "ProductController", + "method": "createProduct(ProductDTO)", + "file": "src/.../ProductController.java", + "lines": "67-85", + "annotations": ["@PostMapping", "@Valid"], + "description": "接收商品建立請求，驗證輸入", + "calls": ["productService.createProduct"] + }, + { + "level": 1, + "type": "service", + "class": "ProductServiceImpl", + "method": "createProduct(ProductDTO)", + "file": "src/.../ProductServiceImpl.java", + "lines": "45-78", + "annotations": ["@Transactional"], + "description": "核心業務邏輯：檢查商品名稱重複、設定預設值、保存商品", + "calls": ["productRepository.existsByName", "productRepository.save"], + "business_rules": [ + "商品名稱不可重複", + "價格必須大於 0", + "庫存預設為 0" + ] + }, + { + "level": 2, + "type": "repository", + "class": "ProductRepository", + "method": "save(Product)", + "file": "src/.../ProductRepository.java", + "lines": "12", + "description": "JPA 內建方法，保存 Entity 到資料庫", + "calls": [] + }, + { + "level": 2, + "type": "mybatis-mapper", + "class": "ProductMapper", + "method": "insertProduct", + "file": "src/main/resources/mapper/ProductMapper.xml", + "lines": "25-35", + "sql_type": "insert", + "description": "MyBatis INSERT 語句，將商品資料插入 products 表", + "sql_snippet": "INSERT INTO products (name, price, stock) VALUES (#{name}, #{price}, #{stock})", + "dynamic_sql": false, + "calls": [] + } + ], + "mybatis_mappers": [ + { + "interface": "ProductMapper.java", + "xml": "src/main/resources/mapper/ProductMapper.xml", + "statements": [ + {"id": "insertProduct", "type": "insert", "line": 25}, + {"id": "selectByName", "type": "select", "line": 40} + ] + } + ], + "entities_involved": [ + { + "class": "Product", + "file": "src/.../entity/Product.java", + "table": "products", + "key_fields": ["id", "name", "price", "stock", "categoryId"] + }, + { + "class": "ProductDTO", + "file": "src/.../dto/ProductDTO.java", + "purpose": "請求/響應資料傳輸物件" + } + ], + "cross_cutting": { + "transaction": "@Transactional on ProductServiceImpl.createProduct", + "validation": "@Valid on request body", + "exception_handling": "throws ProductAlreadyExistsException" + } + } + ``` + + **重要規則**： + - ❗ 每個方法引用必須有實際檔案路徑和行號 + - ❗ 使用 Read 驗證每個檔案內容 + - ❗ 如果追蹤到第三方庫（如 JpaRepository），標記為「框架內建」不再深入 + - ❗ 最大追蹤深度：5 層（防止無限遞歸） + - ❗ 只返回 JSON，不執行 Write 操作 + - ❗ **只讀取 .java 和 .xml 檔案**（排除 pom.xml） + - ❗ MyBatis Mapper XML 通常位於 `src/main/resources/mapper/` 或類似目錄 + +7. 等待所有追蹤代理完成，收集結果 + +8. 合併所有調用鏈並寫入：`.legacy-analysis/domain-{keyword}-{timestamp}/02-call-chains.json` + +--- + +## 階段 3: 發現提取與評分 + +9. 從調用鏈中提取**發現（Findings）**： + + 將調用鏈轉換為結構化發現，每個發現代表一個重要的知識點： + + **發現類型**： + - `entry-point`：API 入口點 + - `business-logic`：業務邏輯 + - `data-operation`：資料操作 + - `validation`：驗證規則 + - `transaction`：事務管理 + - `exception`：異常處理 + - `entity`：資料模型 + - `mybatis-sql`：MyBatis SQL 語句（來自 .xml mapper） + - `mybatis-dynamic`：MyBatis 動態 SQL（if, choose, foreach） + + **發現格式**（與 analyze-java 相容）： + ```json + { + "finding_id": "DOMAIN-001", + "type": "entry-point", + "title": "商品建立 API 端點", + "description": "POST /api/products 端點接收商品建立請求，使用 @Valid 驗證輸入的 ProductDTO", + "evidence": [ + { + "file": "src/main/java/com/example/controller/ProductController.java", + "lines": "67-85", + "snippet": "@PostMapping\npublic ResponseEntity createProduct(@Valid @RequestBody ProductDTO dto)" + } + ], + "importance": "high", + "call_chain_ref": "chain-1" + } + ``` + +10. 對每個發現啟動 **Haiku 代理**進行評分（與 analyze-java 相同的評分機制）： + + **評分維度**： + - 證據強度 (40%)：檔案路徑驗證、行號準確性 + - 重要性 (30%)：對理解領域邏輯的重要程度 + - 完整性 (15%)：描述是否清晰完整 + - 準確性 (15%)：技術描述是否正確 + + **輸出格式**： + ```json + { + "finding_id": "DOMAIN-001", + "scores": { + "evidence": 95, + "importance": 90, + "completeness": 85, + "accuracy": 95 + }, + "total_score": 92.25, + "confidence_level": "very_high" + } + ``` + +11. ⚠️ **MANDATORY**: 等待所有評分完成，不可跳過 + +12. 將評分結果寫入：`.legacy-analysis/domain-{keyword}-{timestamp}/03-scores.json` + +--- + +## 階段 4: 過濾與整理 + +13. 應用過濾規則（與 analyze-java 相同）： + - 保留 total_score >= 75 + - evidence < 60 強制丟棄 + - accuracy < 50 強制丟棄 + - importance >= 90 且 evidence >= 70 例外保留 + +14. 按調用鏈順序組織發現： + - 將發現按其在調用鏈中的位置排序 + - 標記發現之間的關聯關係 + +15. 寫入結構化資料：`.legacy-analysis/domain-{keyword}-{timestamp}/04-structured.json` + +--- + +## 階段 5: 領域文件生成（分檔策略） + +⚠️ **重要：為避免單一文件過大導致 token 限制問題，採用分檔策略** + +### 文件撰寫原則（核心守則） + +**文件目的**：幫助工程師/開發者/新人理解現有專案的 domain know-how 與 project design。 + +**必須刪除的內容類型**： +- ❌ 改善建議、優化建議（如「建議實作快取」、「未來可以加入 A/B Testing」） +- ❌ 效能優化策略（如「平行處理」、「批次查詢」建議） +- ❌ 測試代碼範例（測試應該在測試檔案本身查看） +- ❌ 假設性/範例性程式碼（只保留實際程式碼引用） +- ❌ 「應該」「建議」「優化」「未來」字眼的段落 +- ❌ 監控與告警建議（如「應該實作的監控指標」） + +**必須保留的內容類型**： +- ✅ 現有程式碼的結構與邏輯說明 +- ✅ 實際的業務規則（從程式碼中提取） +- ✅ 資料模型與關聯關係 +- ✅ 調用鏈與流程圖 +- ✅ 錯誤訊息對照表（現有的） +- ✅ 檔案位置速查 + +**程式碼引用原則**： +- 只保留 5-15 行的關鍵邏輯片段 +- 必須標註檔案路徑和行號（如 `ProductService.java:45-60`） +- 完整代碼應引導讀者查看原始檔案 +- 禁止假設性或簡化範例程式碼 + +**避免重複原則**： +- API 端點列表只在 00-INDEX.md +- DTO 欄位說明只在 03-data-model.md +- 業務規則只在 04-business-rules.md +- 錯誤碼對照只在 04-business-rules.md +- 常數定義只在 03-data-model.md + +--- + +16. **依章節分檔生成**，每個章節由獨立的 **Sonnet 代理**生成： + + **輸入**（所有代理共用）： + - 結構化發現 JSON（04-structured.json） + - 調用鏈 JSON（02-call-chains.json） + - 入口點 JSON（01-entry-points.json） + - 使用者原始查詢 + + --- + + ### 文件 1: 索引頁 (00-INDEX.md) - 目標 ~50 行 + + 由主 session 直接生成，內容： + - 領域名稱和簡介（2-3 句話） + - 文件清單與連結 + - API 端點總覽表格（唯一出現位置） + - 快速統計 + + ```markdown + # {領域名稱} 領域分析 + + > 本文件幫助你理解 {領域名稱} 的現有實作，不包含改善建議。 + + ## API 端點總覽 + + | HTTP 方法 | 路徑 | Controller 方法 | 用途 | + |-----------|------|----------------|------| + | POST | /api/products | createProduct | 建立商品 | + | GET | /api/products/{id} | getProduct | 查詢商品 | + + ## 文件索引 + + | 文件 | 說明 | 目標讀者 | + |------|------|----------| + | [01-概述](./01-overview.md) | 領域概念、架構全貌 | 新人、PM | + | [02-調用鏈](./02-call-chains.md) | 程式碼導覽、呼叫路徑 | 開發者 | + | [03-資料模型](./03-data-model.md) | DTO/Entity/Enum 參考 | 開發者 | + | [04-業務規則](./04-business-rules.md) | 業務邏輯、錯誤碼 | 開發者、QA | + | [05-檔案索引](./05-guide.md) | 檔案位置速查 | 開發者 | + + ## 快速統計 + + - 入口點: {N} 個 + - 調用鏈: {M} 條 + - 涉及類別: {K} 個 + ``` + + --- + + ### 文件 2: 概述 (01-overview.md) - 目標 ~150 行 + + **代理任務**：生成領域概述和架構圖 + + **保留內容**： + - 簡介（3-5 句話） + - 核心功能列表（bullet points） + - 技術特色（使用了什麼框架/模式） + - 系統架構圖（單一 Mermaid flowchart） + - 核心類別說明表格（類別名、檔案路徑、職責） + + **刪除內容**： + - ❌ 效能考量/優化策略 + - ❌ 未來擴展方向 + - ❌ 測試策略 + - ❌ 詳細 DTO 設計（移到 03-data-model.md） + - ❌ API 端點列表（已在 00-INDEX.md） + - ❌ 多個序列圖（只保留一個最重要的） + + **Mermaid 圖表限制**： + - 只使用一個整體架構 flowchart + - 只保留一個最重要 API 的序列圖 + - 序列圖不超過 15 行 + + --- + + ### 文件 3: 調用鏈詳解 (02-call-chains.md) - 目標 ~200 行 + + **代理任務**：說明程式碼呼叫路徑 + + **保留內容**： + - 調用鏈概覽表格（入口點、涉及類別、主要功能） + - 架構分層說明（Controller → Service → Repository） + - 每條調用鏈的層級結構（精簡版）： + - 類別和方法名稱 + - 檔案路徑:行號 + - 3-5 句功能說明 + - 重要註解（@Transactional, @Valid） + - 共用元件說明 + + **刪除內容**： + - ❌ 效能瓶頸分析 + - ❌ 優化策略建議 + - ❌ 冗長的程式碼區塊（每個不超過 10 行） + - ❌ 重複的 Kutt API 整合說明（整合至此文件一次） + + **程式碼片段限制**： + - 每個方法只保留關鍵 5-10 行 + - 必須標註 `檔案名:行號` + - 以 `// ... 完整實作請見原始檔案` 結尾 + + **調用鏈呈現格式**（精簡版）： + ```markdown + ### 調用鏈 1: 建立商品 + + | 層級 | 類別.方法 | 檔案位置 | 說明 | + |------|----------|----------|------| + | 0 | ProductController.createProduct | ProductController.java:67 | 接收請求 | + | 1 | ProductService.createProduct | ProductServiceImpl.java:45 | 業務邏輯 | + | 2 | ProductRepository.save | ProductRepository.java:12 | 資料存取 | + + **關鍵邏輯** (`ProductServiceImpl.java:50-55`): + ```java + if (productRepository.existsByName(dto.getName())) { + throw new ProductAlreadyExistsException(); + } + return productRepository.save(product); + // ... 完整實作請見原始檔案 + ``` + ``` + + --- + + ### 文件 4: 資料模型 (03-data-model.md) - 目標 ~200 行 + + **代理任務**：說明資料結構（唯一來源） + + **保留內容**： + - DTO/Entity 關係圖（Mermaid erDiagram） + - Entity 欄位說明表格（類別、欄位、型別、說明） + - DTO 欄位說明表格 + - Enum 定義表格 + - 常數定義表格（唯一位置） + - 資料流轉說明（簡短） + + **刪除內容**： + - ❌ 效能考量 + - ❌ 測試資料範例 + - ❌ 假設性的表結構 + - ❌ 簡化範例 DTO 程式碼 + + **表格格式範例**： + ```markdown + ## Entity: Product (`ProductEntity.java:15`) + + | 欄位 | 型別 | 對應資料表欄位 | 說明 | + |------|------|---------------|------| + | id | Long | product_id | 主鍵 | + | name | String | product_name | 商品名稱 | + ``` + + --- + + ### 文件 5: 業務規則與異常 (04-business-rules.md) - 目標 ~150 行 + + **代理任務**：整理現有業務規則（唯一來源） + + **保留內容**： + - 業務規則清單表格（規則、程式碼位置、說明） + - 錯誤碼/錯誤訊息對照表（唯一位置） + - 異常類別列表（類別名、觸發條件、HTTP 狀態碼） + - 驗證邏輯摘要（@Valid 欄位、自定義驗證） + + **刪除內容**： + - ❌ 測試覆蓋建議 + - ❌ 效能考量 + - ❌ 修改指南 + - ❌ 測試 SQL 範例 + + **表格格式範例**： + ```markdown + ## 業務規則 + + | 規則 | 程式碼位置 | 說明 | + |------|-----------|------| + | 商品名稱不可重複 | ProductServiceImpl.java:48 | 建立前檢查 | + | 價格必須大於 0 | ProductDTO.java:23 | @Min(1) 驗證 | + + ## 錯誤碼對照 + + | 錯誤碼 | HTTP 狀態 | 訊息 | 觸發條件 | + |--------|----------|------|----------| + | PRODUCT_001 | 409 | 商品名稱已存在 | 名稱重複 | + ``` + + --- + + ### 文件 6: 檔案索引 (05-guide.md) - 目標 ~100 行 + + **代理任務**：提供檔案位置速查（最有價值的參考） + + **保留內容**： + - 相關檔案清單（按類型分類） + - Controllers + - Services + - Repositories + - Entities + - DTOs + - Mappers (MyBatis XML) + - 測試檔案位置（僅列出路徑，不詳述） + - 常見問題列表（僅標題和 1 句說明，不詳述解法） + + **刪除內容**： + - ❌ 如何修改此流程（改善建議） + - ❌ 效能優化建議 + - ❌ 測試策略詳述 + - ❌ 部署與配置詳述 + - ❌ API 測試範例（curl/Postman） + - ❌ 除錯技巧詳述 + + **檔案清單格式**： + ```markdown + ## 相關檔案 + + ### Controllers + - `src/main/java/.../ProductController.java` - 商品 API 入口 + + ### Services + - `src/main/java/.../ProductService.java` - 介面 + - `src/main/java/.../ProductServiceImpl.java` - 實作 + + ### Tests + - `src/test/java/.../ProductServiceTest.java` + - `src/test/java/.../ProductControllerTest.java` + + ## 常見問題 + + | 問題 | 相關檔案 | + |------|----------| + | 商品建立失敗 | ProductServiceImpl.java:48 | + | 價格驗證錯誤 | ProductDTO.java:23 | + ``` + + --- + + **撰寫風格**（所有文件通用）： + - 使用繁體中文 + - 假設讀者不了解此專案 + - 優先使用表格呈現結構化資訊 + - 所有程式碼引用必須有 `檔案名:行號` + - 每個文件開頭包含返回索引的連結 + - 每個資訊只出現在一個文件中（避免重複） + - **禁止使用「建議」「應該」「優化」「未來」等字眼** + +17. **並行生成文件**： + + 啟動 **4 個 Sonnet 代理**並行生成文件 2-5： + - 代理 A: 生成 `01-overview.md`（目標 ~150 行） + - 代理 B: 生成 `02-call-chains.md`（目標 ~200 行） + - 代理 C: 生成 `03-data-model.md`（目標 ~200 行） + - 代理 D: 生成 `04-business-rules.md`（~150 行）+ `05-guide.md`（~100 行） + + 主 session 同時生成 `00-INDEX.md`（目標 ~50 行） + + **預期總行數**：約 850 行（相比原本 4000+ 行減少約 80%） + +18. 將所有文件寫入：`.legacy-analysis/domain-{keyword}-{timestamp}/docs/` + + ``` + docs/ + ├── 00-INDEX.md # 索引頁 (~50 行) + ├── 01-overview.md # 概述 (~150 行) + ├── 02-call-chains.md # 調用鏈 (~200 行) + ├── 03-data-model.md # 資料模型 (~200 行) + ├── 04-business-rules.md # 業務規則 (~150 行) + └── 05-guide.md # 檔案索引 (~100 行) + ``` + +--- + +## 完成 + +19. 顯示完成摘要： + + ``` + ╔═══════════════════════════════════════════════════════════╗ + ║ Legacy Domain Analyzer - 領域分析完成 ║ + ╚═══════════════════════════════════════════════════════════╝ + + 🎯 分析領域: {領域關鍵字} + + 📁 工作目錄: .legacy-analysis/domain-{keyword}-{timestamp}/ + + 📄 生成的文件: + ├─ 01-entry-points.json (入口點 {N} 個) + ├─ 02-call-chains.json (調用鏈 {M} 條) + ├─ 03-scores.json (評分結果) + ├─ 04-structured.json (結構化發現 {K} 個) + └─ docs/ (領域分析文件 - 精簡版) ⭐ + ├─ 00-INDEX.md (~50 行) 索引與 API 總覽 + ├─ 01-overview.md (~150 行) 概述與架構圖 + ├─ 02-call-chains.md (~200 行) 調用鏈詳解 + ├─ 03-data-model.md (~200 行) 資料模型 + ├─ 04-business-rules.md (~150 行) 業務規則 + └─ 05-guide.md (~100 行) 檔案索引 + + 📊 分析統計: + - 總執行時間: {X} 分 {Y} 秒 + - 追蹤的調用鏈: {M} 條 + - 文件總行數: ~850 行（精簡版） + - 平均置信度: {score} + + 🔗 主要入口點: + 1. POST /api/products → ProductController.createProduct + 2. ... + + 📖 閱讀指南: + - 新人/PM: 從 00-INDEX.md → 01-overview.md + - 開發者: 02-call-chains.md → 03-data-model.md + - QA: 04-business-rules.md + + 💡 文件特色: + - 專注於「理解現有專案」，不含改善建議 + - 每個資訊只出現一次，無重複內容 + - 所有程式碼引用包含檔案路徑和行號 + - 總計約 850 行（相比完整版減少 80%） + ``` + +--- + +## 重要注意事項 + +- **並行執行**： + - 階段 2 的追蹤代理（最多 3 個）並行啟動 + - 階段 3 的評分代理全部並行啟動 + - 階段 5 的文件生成代理（4 個）並行啟動 + +- **精簡文件策略**： + - 採用 6 個精簡文件（總計 ~850 行） + - 每個文件有明確的目標行數限制 + - 禁止「建議」「應該」「優化」「未來」字眼 + - 每個資訊只出現在一個文件中（避免重複） + - 程式碼片段限制 5-15 行，引導讀者看原始檔案 + +- **與 analyze-java 的互補性**： + - 先用 `analyze-java-domain` 理解特定功能 + - 如需全局視角，再用 `analyze-java` + - 兩者輸出格式相容，可以合併 + +- **搜尋策略優化**： + - 使用多種關鍵字變體（中英文、駝峰、下劃線） + - 使用正則表達式匹配方法名模式 + - 從 Controller 開始追蹤，確保找到完整流程 + +- **深度優先 vs 廣度優先**： + - 此命令採用深度優先策略 + - 完整追蹤一條調用鏈後再追蹤下一條 + - 最大深度 5 層，避免過度追蹤 + +- **時間估算**： + - 階段 1: 約 30 秒（Haiku 快速掃描） + - 階段 2: 約 2-3 分鐘（Sonnet 深度追蹤，最多 3 條鏈） + - 階段 3: 約 10-20 秒（Haiku 評分） + - 階段 4: 約 10 秒（主 session 處理） + - 階段 5: 約 1-2 分鐘（4 個 Sonnet 並行生成精簡文件） + - **總計: 約 4-6 分鐘** diff --git a/commands/analyze-java.md b/commands/analyze-java.md new file mode 100644 index 0000000..31eec8b --- /dev/null +++ b/commands/analyze-java.md @@ -0,0 +1,1076 @@ +--- +description: 分析 Legacy Java Spring Boot 專案並生成教學文件 +allowedTools: + - Task + - TodoWrite + - Read + - Write + - Glob + - Grep + - Bash +--- + +# Legacy Java Project Analyzer + +為給定的 Java Spring Boot 專案生成詳細的分析文件，using multiple specialized agents with confidence-based scoring。 + +要執行此操作，請精確遵循以下步驟： + +## 準備工作 + +1. 首先使用 TodoWrite 建立待辦事項清單，包含所有階段 + +2. 創建工作目錄：`.legacy-analysis/session-{timestamp}/` + +## 階段 1: 資格預檢與快速掃描 + +3. 使用 Haiku 代理檢查專案是否適合分析。代理應檢查： + - 專案根目錄是否存在 `pom.xml` 或 `build.gradle`？ + - 是否包含 Spring Boot 依賴？（檢查 spring-boot-starter） + - Java 檔案數量是否適中？（使用 Glob 統計 **/*.java，應 < 1000） + + 如果不符合任一條件，說明原因並終止。 + +4. 使用 Haiku 代理快速掃描專案結構。代理應： + - 使用 Glob 找出所有 .java 檔案並統計數量 + - 使用 Grep 搜尋以下註解並統計數量： + - `@RestController` 或 `@Controller` + - `@Service` + - `@Repository` + - `@Entity` + - 讀取 pom.xml 或 build.gradle 獲取： + - Spring Boot 版本 + - 前 10 個主要依賴 + - 使用 Glob 列出主要 package（src/main/java 下的第一層目錄） + + 返回專案摘要 JSON： + ```json + { + "projectType": "Spring Boot", + "springBootVersion": "2.7.12", + "buildTool": "Maven", + "totalJavaFiles": 245, + "componentCounts": { + "controllers": 15, + "services": 20, + "repositories": 12, + "entities": 10 + }, + "mainPackages": [ + "com.example.order.controller", + "com.example.order.service", + "com.example.order.repository" + ], + "keyDependencies": [ + "spring-boot-starter-web", + "spring-boot-starter-data-jpa", + "mysql-connector-java" + ] + } + ``` + +5. 將專案摘要寫入：`.legacy-analysis/session-{timestamp}/01-project-scan.json` + +## 階段 2: 多視角並行分析 + +6. 啟動 **6 個並行 Sonnet 代理**來獨立分析專案。 + + **所有代理的共同輸入**： + - 專案摘要 JSON（來自步驟 4） + - 專案根目錄路徑 + + **所有代理的共同輸出格式**（JSON）： + ```json + { + "analyst": "代理名稱", + "findings": [ + { + "finding_id": "分類前綴-編號", + "type": "發現類型", + "title": "簡短標題", + "description": "詳細描述（2-3 句話）", + "evidence": [ + { + "file": "檔案相對路徑", + "lines": "起始行-結束行", + "snippet": "關鍵程式碼片段（可選）" + } + ], + "importance": "high/medium/low", + "notes": "額外說明（可選）" + } + ], + "total_findings": 數量 + } + ``` + + **所有代理的重要規則**： + - ❗ 每個發現必須有實際的檔案路徑和行號作為證據 + - ❗ 使用 Read 工具驗證檔案內容，確保引用正確 + - ❗ 使用 Glob/Grep 輔助搜尋，不要猜測 + - ❗ 如果無法確認，不要包含該發現 + - ❗ 只返回 JSON，不執行 Write 操作 + - ❗ 專注於自己的分析領域，不要越界 + +--- + + **代理 #1：架構分析代理** + + 職責：分析專案的整體架構和分層設計 + + 應分析： + - Package 組織結構（使用 Glob 掃描目錄） + - 分層架構識別： + - Controller 層：處理 HTTP 請求 + - Service 層：業務邏輯 + - Repository 層：資料存取 + - Entity 層：資料模型 + - 識別架構模式（MVC、三層架構、DDD 等） + - 層與層之間的依賴關係（通過讀取代表性類別） + + 應使用工具： + - Glob: 掃描 package 結構 + - Grep: 搜尋 @RestController, @Service, @Repository, @Entity + - Read: 讀取 2-3 個代表性類別（每層一個） + + 發現類型前綴：`ARCH-` + + 發現類型：`architecture` + + 預期發現數量：8-15 個 + +--- + + **代理 #2：API 端點分析代理** + + 職責：分析所有 REST API 端點和請求處理流程 + + 應分析： + - 所有 @RestController 或 @Controller 類別（使用 Grep 找出） + - 主要 API 端點： + - HTTP 方法（GET/POST/PUT/DELETE） + - 路徑和路徑參數 + - 請求/響應格式 + - 主要業務流程： + - Controller → Service → Repository 的調用鏈 + - 事務管理（@Transactional） + - 認證授權機制（如果有 Spring Security） + - 異常處理（@ExceptionHandler, @ControllerAdvice） + + 應使用工具： + - Grep: 搜尋 @RestController, @RequestMapping, @GetMapping, @PostMapping + - Read: 讀取所有 Controller 類別（或前 10 個如果太多） + - Grep: 搜尋 @Transactional, @ExceptionHandler + + 發現類型前綴：`API-` + + 發現類型：`endpoint` + + 預期發現數量：15-25 個（視 Controller 數量） + +--- + + **代理 #3：資料流分析代理** + + 職責：分析資料模型和資料流轉 + + 應分析： + - 所有 JPA Entity 類別（使用 Grep 找出 @Entity） + - Entity 之間的關聯關係： + - @OneToOne, @OneToMany, @ManyToOne, @ManyToMany + - 關聯的方向和級聯設定 + - 資料流轉路徑： + - DTO → Entity（轉換邏輯） + - Entity → Database（Repository 操作） + - Repository 介面和自定義查詢 + - 資料驗證邏輯（@Valid, @NotNull 等） + + 應使用工具： + - Grep: 搜尋 @Entity, @OneToMany, @ManyToOne + - Read: 讀取所有 Entity 類別 + - Grep: 搜尋 @Repository, extends JpaRepository + - Read: 讀取主要 Repository 介面 + + 發現類型前綴：`DATA-` + + 發現類型：`entity` 或 `dataflow` + + 預期發現數量：10-20 個 + +--- + + **代理 #4：業務邏輯分析代理** + + 職責：分析核心業務邏輯和 Service 層 + + 應分析： + - 所有 @Service 類別（使用 Grep 找出） + - 主要業務方法： + - 方法簽名和參數 + - 業務規則和驗證 + - 複雜的業務邏輯 + - Service 之間的調用關係（依賴注入） + - 事務管理： + - @Transactional 的使用 + - 事務邊界 + - 業務異常處理 + + 應使用工具： + - Grep: 搜尋 @Service, @Transactional + - Read: 讀取所有 Service 類別（或主要的 5-10 個） + - 分析依賴注入（@Autowired, 建構子注入） + + 發現類型前綴：`BIZ-` + + 發現類型：`service` 或 `business-logic` + + 預期發現數量：15-25 個 + +--- + + **代理 #5：配置分析代理** + + 職責：分析專案配置和第三方整合 + + 應分析： + - application.yml 或 application.properties： + - 資料庫配置 + - Server 配置 + - 環境變數 + - Spring Boot 配置類別（@Configuration）： + - Bean 定義 + - 第三方服務整合 + - Spring Security 配置（如果有） + - 依賴管理（pom.xml 或 build.gradle）： + - 主要依賴及版本 + - 第三方庫的用途 + + 應使用工具： + - Read: 讀取 application.yml/properties + - Grep: 搜尋 @Configuration, @Bean + - Read: 讀取配置類別 + - Read: 讀取 pom.xml 或 build.gradle + + 發現類型前綴：`CONF-` + + 發現類型：`configuration` 或 `dependency` + + 預期發現數量：8-15 個 + +--- + + **代理 #6：模式識別代理** + + 職責：識別設計模式和編碼最佳實踐 + + 應分析： + - 設計模式的應用： + - Factory Pattern（工廠模式） + - Strategy Pattern（策略模式） + - Builder Pattern（建造者模式） + - Singleton Pattern（單例模式） + - Spring 特定模式： + - Dependency Injection（依賴注入） + - AOP（面向切面編程，如果有 @Aspect） + - 異常處理模式： + - 全域異常處理器（@ControllerAdvice） + - 自定義異常類別 + - 日誌記錄實踐（Logger 使用） + - DTO 模式的使用 + + 應使用工具： + - Grep: 搜尋常見模式關鍵字（Factory, Strategy, Builder, Singleton） + - Read: 讀取包含模式的類別 + - Grep: 搜尋 @ControllerAdvice, @Aspect, @Pointcut + - 分析代碼風格和命名慣例 + + 發現類型前綴：`PATTERN-` + + 發現類型：`pattern` 或 `practice` + + 預期發現數量：5-15 個 + +--- + +7. 等待所有 6 個代理完成，收集所有輸出 + +8. 合併所有發現清單為一個 JSON 陣列 + +9. 將合併的發現清單寫入：`.legacy-analysis/session-{timestamp}/02-findings-raw.json` + +10. 統計總發現數量並報告（例如："收集到 102 個發現"） + +## 階段 3: 獨立置信度評分 + +⚠️⚠️⚠️ **CRITICAL - THIS STAGE IS MANDATORY AND CANNOT BE SKIPPED** ⚠️⚠️⚠️ + +**為什麼這個階段是核心且不可跳過的：** + +1. **這是整個插件的靈魂** + - 置信度評分系統是本插件與其他分析工具的根本差異 + - 沒有評分 = 沒有質量保證 = 無法區分真實發現與幻覺 + - 跳過此階段違反了插件的核心設計原則 + +2. **防幻覺機制完全依賴此階段** + - 第二層防護：評分代理使用 Glob 驗證檔案存在 + - 第三層防護：閾值過濾（score >= 75, evidence >= 60） + - 沒有評分 = 防幻覺機制失效 = 可能產生錯誤文件 + +3. **成本和時間都非常合理** + - Haiku 模型速度極快（每個評分 < 1 秒） + - 100 個評分代理並行執行只需 10-20 秒 + - Haiku 成本極低（相比 Sonnet 便宜 50-100 倍） + - 即使 200 個發現，總時間也只增加 10-15 秒 + +4. **不評分的嚴重後果** + - 最終文件會包含所有未驗證的發現（包括幻覺、錯誤、瑣碎內容） + - 過濾率 0%（承諾是 40-60%） + - 無法信任檔案路徑和行號 + - 用戶體驗極差，失去插件價值 + +**明確的執行要求：** + +❌ **絕對禁止以下行為**： +- 以「發現數量太多」為理由跳過評分 +- 以「節省時間」為理由跳過評分 +- 以「成本考量」為理由跳過評分 +- 直接使用未評分的發現生成文件 +- 進入階段 4 而不先完成階段 3 + +✅ **你 MUST 執行以下操作**： +- 對 **每一個發現** 啟動一個獨立的 Haiku 評分代理 +- 等待 **所有** 評分代理完成 +- 將所有評分結果寫入 `03-scores.json` +- 只有在 `03-scores.json` 存在後才能繼續下一階段 + +11. **REQUIRED**: 對於步驟 8 中的 **每一個發現**，啟動一個並行 **Haiku 代理**進行評分。 + **DO NOT SKIP ANY FINDINGS**, regardless of the total count. + + **每個評分代理的輸入**： + - 單個發現 JSON（包含 finding_id, type, title, description, evidence, importance） + - 專案摘要 JSON（作為上下文） + + **評分任務**： + + 從四個維度對發現進行評分（0-100）： + + **a. 證據強度 (Evidence Strength)** - 權重 40% + + 評分標準： + - 90-100 分：完美證據 + - 有精確的檔案路徑和行號 + - 使用 Read 工具驗證檔案存在且內容匹配 + - 代碼片段準確無誤 + + - 70-89 分：良好證據 + - 有檔案路徑和行號 + - 使用 Glob 確認檔案存在 + - 描述與代碼基本匹配 + + - 50-69 分：基本證據 + - 有檔案路徑但行號範圍過大（> 50 行） + - 通過推理得出，未直接驗證 + - 可能需要額外確認 + + - 30-49 分：弱證據 + - 只有檔案路徑，沒有行號 + - 基於間接證據（如依賴推測） + - 不確定性較高 + + - 0-29 分：無效證據 + - 沒有檔案路徑或檔案不存在 + - 明顯的猜測或假設 + - 幻覺（fabrication） + + **評分方法**：使用 Glob 驗證檔案路徑是否存在。如果時間允許，使用 Read 讀取檔案驗證行號範圍和內容。 + + --- + + **b. 重要性 (Importance)** - 權重 30% + + 評分標準： + - 90-100 分：極其重要 + - 核心業務邏輯（如訂單處理、支付流程） + - 主要架構決策（如分層設計、依賴管理） + - 新手必須理解的概念 + - 影響整個系統的設計 + + - 70-89 分：很重要 + - 重要的業務流程 + - 關鍵的設計模式應用 + - 常見的 CRUD 操作 + - 第三方服務整合 + + - 50-69 分：中等重要 + - 輔助功能 + - 一般的配置項目 + - 可選的理解點 + - 工具方法 + + - 30-49 分：次要 + - 邊緣功能 + - 細節實現 + - 進階理解點 + + - 0-29 分：不重要 + - 瑣碎細節 + - 與業務無關的內容 + - 可以忽略的資訊 + + --- + + **c. 完整性 (Completeness)** - 權重 15% + + 評分標準： + - 90-100 分：非常完整 + - 描述清晰易懂 + - 包含完整的流程或調用鏈 + - 有充足的上下文 + - 提供了代碼範例 + + - 70-89 分：基本完整 + - 描述清晰 + - 主要流程完整 + - 上下文充足 + + - 50-69 分：部分完整 + - 描述較簡略 + - 流程不完整或片段化 + - 缺少部分上下文 + + - 30-49 分：不完整 + - 描述模糊 + - 只有流程片段 + - 上下文不足 + + - 0-29 分：非常不完整 + - 描述不清 + - 沒有流程資訊 + - 完全缺乏上下文 + + --- + + **d. 準確性 (Accuracy)** - 權重 15% + + 評分標準： + - 90-100 分：完全準確 + - 技術描述正確無誤 + - 沒有錯誤或幻覺 + - 可以直接使用 + + - 70-89 分：基本準確 + - 主要描述正確 + - 有小的不精確（如版本差異） + - 需要微調 + + - 50-69 分：部分準確 + - 有明顯錯誤 + - 需要修正才能使用 + - 部分資訊可能誤導 + + - 30-49 分：不準確 + - 多處錯誤 + - 包含幻覺或猜測 + - 不可信 + + - 0-29 分：完全錯誤 + - 完全不正確 + - 大量幻覺 + - 必須丟棄 + + --- + + **計算最終分數**： + + ``` + total_score = evidence * 0.4 + importance * 0.3 + completeness * 0.15 + accuracy * 0.15 + ``` + + **輸出格式**（JSON）： + ```json + { + "finding_id": "ARCH-001", + "scores": { + "evidence": 95, + "importance": 85, + "completeness": 90, + "accuracy": 95 + }, + "total_score": 91.25, + "confidence_level": "very_high", + "reasoning": "發現有明確的檔案路徑證據（已用 Glob 驗證存在），描述準確且清晰，對理解三層架構非常重要，新手必須知道。", + "verified_files": [ + "src/main/java/com/example/order/controller/OrderController.java (verified)" + ], + "issues": [] + } + ``` + + **confidence_level 對應**： + - very_high: total_score >= 85 + - high: 75 <= total_score < 85 + - medium: 60 <= total_score < 75 + - low: 45 <= total_score < 60 + - very_low: total_score < 45 + +12. **REQUIRED**: 等待 **所有** 評分代理完成，收集所有評分結果。 + 不要只收集部分結果，必須等待全部完成。 + +13. **REQUIRED**: 將評分結果寫入：`.legacy-analysis/session-{timestamp}/03-scores.json` + +14. 統計評分分佈（例如："58 個 >= 75, 44 個 < 75"） + +## 階段 4: 過濾與結構化整合 + +🔒 **VALIDATION CHECKPOINT - 在繼續之前必須驗證** 🔒 + +14.5. **MANDATORY PRE-CHECK**: 在執行任何過濾操作前，你 MUST 先驗證以下條件： + + **檢查 1: 確認評分文件存在** + ``` + 使用 Read 工具檢查文件是否存在： + .legacy-analysis/session-{timestamp}/03-scores.json + ``` + + **如果文件不存在**，你 MUST： + - 立即停止執行 + - 輸出錯誤訊息： + ``` + ❌❌❌ 致命錯誤：階段 3 評分被跳過 ❌❌❌ + + 檢測到缺少文件：03-scores.json + + 這表示階段 3（獨立置信度評分）沒有被執行。 + 沒有評分數據，無法進行質量過濾，無法保證最終文件質量。 + + 請檢查階段 3 的執行日誌，或重新執行完整流程。 + + 插件設計要求：所有階段必須依序完成，不可跳過。 + ``` + - **DO NOT PROCEED** 到步驟 15 + + **檢查 2: 驗證評分數量一致性** + + 使用 Read 工具讀取以下兩個文件： + - `02-findings-raw.json` (原始發現數量) + - `03-scores.json` (評分數量) + + 驗證：評分數量 == 原始發現數量 + + **如果數量不一致**，你 MUST： + - 輸出警告訊息： + ``` + ⚠️ 警告：評分數量與發現數量不一致 + + 原始發現: {N} 個 + 評分結果: {M} 個 + 差異: {N-M} 個發現未被評分 + + 可能原因：部分評分代理失敗 + + 將繼續執行，但請注意未評分的發現將被自動過濾。 + ``` + - 對於未評分的發現，自動賦予 total_score = 0（將被過濾） + + **只有在通過所有檢查後**，才能繼續執行步驟 15。 + +15. **REQUIRED**: 過濾發現，應用以下規則： + + **主要規則**： + - 保留 total_score >= 75 的發現 + + **額外規則**（強制）： + - 如果 evidence < 60：強制丟棄（即使總分 >= 75） + 理由：沒有足夠證據，可能是幻覺 + + - 如果 accuracy < 50：強制丟棄（即使總分 >= 75） + 理由：準確性太低，可能誤導讀者 + + **例外規則**（保留）： + - 如果 importance >= 90 且 evidence >= 70：保留（即使總分 < 75） + 理由：極其重要的發現，證據也足夠 + + 統計並報告過濾結果（例如："保留 58 個高質量發現，過濾掉 44 個低質量發現，過濾率 43.1%"） + +16. 將保留的發現按類別分組： + - architecture: 架構發現 + - endpoint: API 端點 + - entity: 資料模型 + - dataflow: 資料流轉 + - service: 業務邏輯 + - business-logic: 業務邏輯（同義詞） + - configuration: 配置 + - dependency: 依賴 + - pattern: 設計模式 + - practice: 編碼實踐 + +17. 每個類別內按 total_score 降序排序（最高質量在前） + +18. 識別發現之間的關聯關係（可選但推薦）： + - 例如：API-001（創建訂單端點）→ BIZ-005（OrderService.createOrder）→ DATA-003（Order Entity） + - 建立關聯圖以幫助理解完整流程 + +19. 生成結構化資料 JSON： + ```json + { + "summary": { + "total_findings_raw": 102, + "total_findings_filtered": 58, + "filter_rate": 0.431, + "by_category": { + "architecture": 8, + "endpoint": 15, + "entity": 7, + "dataflow": 3, + "service": 12, + "configuration": 7, + "pattern": 6 + }, + "average_score": 82.5 + }, + "findings_by_category": { + "architecture": [ /* 發現陣列 */ ], + "endpoint": [ /* 發現陣列 */ ], + ... + }, + "relationships": [ + { + "from": "API-001", + "to": ["BIZ-005", "DATA-003"], + "type": "invokes" + } + ] + } + ``` + +20. **REQUIRED**: 將結構化資料寫入：`.legacy-analysis/session-{timestamp}/04-findings-structured.json` + +## 階段 5: 教學文件生成 + +🔒 **FINAL VALIDATION CHECKPOINT - 文件生成前的最後檢查** 🔒 + +20.5. **MANDATORY FINAL CHECK**: 在啟動文件生成代理前，你 MUST 驗證所有必需文件已就緒： + + **檢查 1: 驗證所有階段的輸出文件存在** + + 使用 Read 工具確認以下文件全部存在： + - `01-project-scan.json` (階段 1 輸出) + - `02-findings-raw.json` (階段 2 輸出) + - `03-scores.json` (階段 3 輸出) ← **關鍵文件** + - `04-findings-structured.json` (階段 4 輸出) + + **如果任何文件缺失**，你 MUST： + - 立即停止執行 + - 輸出錯誤訊息： + ``` + ❌❌❌ 致命錯誤：無法生成教學文件 ❌❌❌ + + 缺少必需的文件：{缺失的文件名} + + 這表示前置階段沒有正確完成。 + 無法在沒有完整數據的情況下生成教學文件。 + + 請重新執行完整的分析流程，確保所有階段依序完成。 + ``` + - **DO NOT START** 文件生成代理 + + **檢查 2: 驗證結構化發現的質量** + + 使用 Read 工具讀取 `04-findings-structured.json`，確認： + - `summary.total_findings_filtered` > 0（至少有一些高質量發現） + - `summary.filter_rate` 在 0.2-0.8 之間（過濾率正常） + + **如果過濾後發現數量 = 0**，你 MUST： + - 輸出警告訊息： + ``` + ⚠️ 警告：沒有任何發現通過質量過濾 + + 原始發現: {N} 個 + 通過過濾: 0 個 + + 可能原因： + 1. 分析代理的發現質量極低（證據不足） + 2. 評分標準過於嚴格 + 3. 專案過於簡單，沒有足夠的內容可分析 + + 建議： + - 檢查 02-findings-raw.json 和 03-scores.json + - 考慮手動調整過濾閾值（從 75 降至 65） + - 或手動補充文件內容 + ``` + - 繼續生成文件，但文件內容會很少 + + **檢查 3: 禁止使用未評分的發現** + + 你 MUST 確認： + - 文件生成代理的輸入 **只能** 是 `04-findings-structured.json` + - **絕對禁止** 直接使用 `02-findings-raw.json` + - **絕對禁止** 添加任何未在結構化發現中的資訊 + + **只有在通過所有檢查後**，才能啟動文件生成代理。 + +21. **REQUIRED**: 使用 **Sonnet 代理**生成教學文件。 + + **輸入**： + - 結構化發現 JSON（來自步驟 20 的 `04-findings-structured.json`）← **唯一允許的輸入來源** + - 專案摘要 JSON（來自步驟 5 的 `01-project-scan.json`） + + **任務**： + + 生成完整的 Markdown 教學文件，假設讀者是完全不了解此專案的新進工程師。 + + **文件結構**（必須包含）： + + ### 1. 專案概述 + - 專案基本資訊（名稱、類型、Spring Boot 版本、建構工具） + - 專案規模（檔案數量、元件統計） + - 專案結構（主要 package） + - 核心模組列表 + + ### 2. 快速開始 + - 如何運行專案（從 git clone 到 spring-boot:run） + - 重要端點列表（健康檢查、API 文件） + - 開發環境要求（JDK、Maven/Gradle、資料庫） + + ### 3. 架構說明 + - 整體架構圖（使用 Mermaid flowchart） + - 分層設計說明（Controller/Service/Repository/Entity） + - Package 組織結構 + - 架構優點 + + 範例 Mermaid 圖： + ```mermaid + graph TB + Client[客戶端請求] + Controller[Controller 層
處理 HTTP 請求] + Service[Service 層
業務邏輯處理] + Repository[Repository 層
資料存取] + DB[(MySQL 資料庫)] + + Client --> Controller + Controller --> Service + Service --> Repository + Repository --> DB + ``` + + ### 4. API 端點清單 + + 對於每個重要的 API 端點（從 endpoint 類別的發現）： + - HTTP 方法和路徑 + - 描述和用途 + - 請求範例（JSON） + - 響應範例（JSON） + - 業務流程序列圖（使用 Mermaid sequenceDiagram） + - 關鍵程式碼片段（含檔案路徑連結） + - 重要提示（如事務管理、異常處理） + + 範例序列圖： + ```mermaid + sequenceDiagram + participant Client + participant Controller + participant Service + participant Repository + participant DB + + Client->>Controller: POST /api/orders + Controller->>Service: createOrder(OrderDTO) + Service->>Service: 驗證庫存 + Service->>Repository: save(Order) + Repository->>DB: INSERT + DB-->>Repository: 成功 + Repository-->>Service: Order Entity + Service-->>Controller: OrderResponseDTO + Controller-->>Client: 201 Created + ``` + + ### 5. 核心業務流程 + + 選擇 2-3 個最重要的業務流程（基於 importance 分數）： + - 流程整體說明 + - 詳細步驟分解 + - 完整序列圖 + - 涉及的類別和方法列表（含檔案路徑連結） + - 程式碼片段和註解 + - 新手提示 + + ### 6. 資料模型 + + - Entity 關係圖（使用 Mermaid erDiagram） + - 對於每個主要 Entity： + - 資料表名稱 + - 主要欄位說明 + - 關聯關係說明 + - JPA 註解解釋（@Entity, @Table, @OneToMany 等） + - 程式碼範例 + + 範例 ER 圖： + ```mermaid + erDiagram + Order ||--o{ OrderItem : contains + Order { + Long id PK + Long customerId + String status + Timestamp createdAt + } + OrderItem { + Long id PK + Long orderId FK + Long productId + int quantity + decimal price + } + + Customer ||--o{ Order : places + Customer { + Long id PK + String name + String email + } + ``` + + ### 7. 關鍵配置 + + - 資料庫配置（含 YAML/properties 範例） + - Spring Security 配置（如果有） + - 重要的 Bean 配置 + - 環境變數說明 + + ### 8. 設計模式與最佳實踐 + + 對於每個識別出的設計模式： + - 模式名稱和類型 + - 應用位置（檔案路徑） + - 程式碼範例 + - 使用此模式的優點 + - 相關的最佳實踐 + + ### 9. 新手入門指南 + + - **我該從哪裡開始？** + - 建議的學習順序（10 分鐘理解架構 → 30 分鐘追蹤一個流程 → ...） + - 推薦先看哪些類別 + + - **常見任務指南** + - 如何添加新的 API 端點 + - 如何修改業務邏輯 + - 如何添加新的 Entity + + - **開發環境設置** + - 所需工具清單 + - 資料庫設置步驟 + - 環境變數配置 + - 如何運行測試 + + - **推薦的學習資源** + - Spring Boot 官方文件連結 + - Spring Data JPA 文件連結 + - 相關教學資源 + + ### 10. 附錄 + + - **高質量發現清單** + - 按類別列出所有發現（含 finding_id 和 score） + + - **文件變更歷史** + - 初始版本生成時間 + - 後續手動更新記錄區 + + - **檔案路徑索引** + - 所有引用的檔案路徑清單（方便快速導航） + + --- + + **撰寫風格要求**： + + ✅ **假設讀者是新手** + - 不假設任何先備知識 + - 解釋所有技術術語（如 JPA、DTO、依賴注入） + - 提供充足的上下文 + + ✅ **使用繁體中文** + - 自然流暢的中文 + - 技術術語保留英文（如 Controller, Service, @Transactional） + - 適當加入英文原文（如「依賴注入 (Dependency Injection)」） + + ✅ **大量使用圖表** + - 每個複雜流程都應該有 Mermaid 圖 + - 圖表類型：flowchart（架構圖）、sequenceDiagram（序列圖）、erDiagram（ER 圖） + - 圖表要清晰、標註完整 + + ✅ **包含程式碼範例** + - 關鍵程式碼片段（使用 ```java 語法高亮） + - 適當的註解（特別是複雜邏輯） + - 檔案路徑和行號（格式：`src/.../OrderController.java:67-85`） + + ✅ **可點擊的連結** + - 所有檔案路徑都使用 Markdown 連結格式（如 `[OrderController.java](src/.../OrderController.java)`） + - 使用相對路徑 + + ✅ **結構清晰** + - 使用 Markdown 標題階層（#, ##, ###） + - 使用清單和表格組織資訊 + - 每個章節之間用 `---` 分隔 + + --- + + **重要規則**： + + ❗ **CRITICAL RULE: 只使用高質量發現** + - **MUST** 只能使用 total_score >= 75 的發現（來自 `04-findings-structured.json`） + - **MUST NOT** 添加任何未在發現清單中的資訊 + - **MUST NOT** 直接使用 `02-findings-raw.json` 中的未評分發現 + - 如果某個面向沒有足夠的發現，明確說明「此部分資訊不足，建議手動補充」 + + ❗ **CRITICAL RULE: 所有引用必須可驗證** + - **MUST**: 每個程式碼範例都必須有檔案路徑 + - **MUST**: 每個流程圖都必須基於實際的發現 + - **MUST NOT**: 編造任何檔案路徑或類別名稱 + - **MUST NOT**: 添加未經驗證的代碼片段 + + ❗ **保持客觀** + - 如實描述專案現況 + - 不過度美化或批評 + - 基於事實陳述 + + ❗ **Mermaid 語法正確** + - 確保所有 Mermaid 圖表語法正確 + - 測試常見的 Mermaid 語法錯誤（如缺少引號、箭頭錯誤） + + --- + + **輸出**： + + 返回完整的 Markdown 文件內容（純文本，不需要 JSON 包裝） + +22. **REQUIRED**: 將生成的文件寫入：`.legacy-analysis/session-{timestamp}/05-PROJECT-ANALYSIS.md` + +23. （可選）生成統計報告並寫入：`.legacy-analysis/session-{timestamp}/session-stats.json` + ```json + { + "session_id": "session-20250125-143022", + "start_time": "2025-01-25T14:30:22Z", + "end_time": "2025-01-25T14:36:45Z", + "duration_seconds": 383, + "project_info": { + "name": "Order Management System", + "type": "Spring Boot", + "total_java_files": 245 + }, + "analysis_stats": { + "total_findings_raw": 102, + "total_findings_filtered": 58, + "filter_rate": 0.431, + "average_score": 82.5, + "by_category": { ... } + }, + "agent_calls": { + "qualification_check": 1, + "quick_scan": 1, + "analysis_agents": 6, + "scoring_agents": 102, + "documentation_generator": 1, + "total": 111 + }, + "quality_metrics": { + "file_path_verified_rate": 1.0, + "average_evidence_score": 87.3, + "average_importance_score": 78.5 + } + } + ``` + +## 完成 + +24. 顯示完成摘要，包含： + + ``` + ╔═══════════════════════════════════════════════════════╗ + ║ Legacy Project Analyzer - 分析完成 ║ + ╚═══════════════════════════════════════════════════════╝ + + ✅ 所有階段已完成 + + 📁 工作目錄: .legacy-analysis/session-{timestamp}/ + + 📄 生成的文件: + ├─ 01-project-scan.json (專案掃描摘要) + ├─ 02-findings-raw.json (原始發現 102 個) + ├─ 03-scores.json (評分結果) + ├─ 04-findings-structured.json (結構化發現 58 個) + ├─ 05-PROJECT-ANALYSIS.md (最終教學文件) ⭐ + └─ session-stats.json (統計資訊) + + 📊 分析統計: + - 總執行時間: 6 分 23 秒 + - 代理調用: 111 次 (2 Haiku + 6 Sonnet + 102 Haiku + 1 Sonnet) + - 發現總數: 102 個 + - 高質量發現: 58 個 (56.9%) + - 檔案路徑驗證率: 100% + - 平均置信度分數: 82.5 + + 🎯 下一步建議: + 1. 閱讀最終文件: 05-PROJECT-ANALYSIS.md + 2. 根據文件理解專案架構和核心流程 + 3. 動手運行專案並對照文件調試 + 4. 如需深入特定模組，可補充手動分析 + + 💡 提示: + - 本文件由 AI 自動生成，基於 58 個高質量發現 + - 所有引用的檔案路徑都已驗證存在 + - 如發現任何錯誤或遺漏，歡迎手動補充 + + 祝學習順利！ 🚀 + ``` + +## 重要注意事項 + +- **使用 TodoWrite 追蹤進度**：在步驟 1 建立待辦清單，並在完成每個階段時更新狀態 + +- **並行執行代理**（CRITICAL for performance）： + - 階段 2 的 6 個分析代理 **MUST** 並行啟動（在單個回應中使用多個 Task 工具） + - 階段 3 的 N 個評分代理 **MUST** 並行啟動（全部一次性啟動） + - **DO NOT** 等待單個代理完成才啟動下一個 + - **DO NOT** 序列執行（會導致總時間從 7 分鐘變成 30+ 分鐘） + +- **錯誤處理**： + - 如果某個分析代理失敗，記錄錯誤但繼續其他代理 + - 如果某個評分代理失敗，該發現使用預設低分（0）並標記 + - 如果文件生成失敗，嘗試重試一次 + +- **檔案路徑格式**： + - 使用相對路徑（相對於專案根目錄） + - 格式：`src/main/java/com/example/order/controller/OrderController.java` + - 不要使用絕對路徑或 Windows 路徑格式 + +- **時間估算**（所有階段都是必須的）： + - 階段 1: 約 1 分鐘（Haiku） + - 階段 2: 約 3-4 分鐘（6 個 Sonnet 並行） + - 階段 3: 約 10-20 秒（N 個 Haiku 並行）← **不可跳過，時間極短** + - 階段 4: 約 30 秒（主 session 處理） + - 階段 5: 約 2-3 分鐘（1 個 Sonnet） + - **總計: 約 7-9 分鐘（中型專案，100 個發現）** + + **關鍵時間說明**： + - 階段 3 雖然處理 100+ 個發現，但因為 Haiku 極快且並行執行，只需 10-20 秒 + - 跳過階段 3 只能「節省」10-20 秒，但會失去整個插件的核心價值 + - 即使 200 個發現，階段 3 也只需 15-25 秒 + +- **成本優化**（設計已優化，無需手動調整）： + - 階段 1: Haiku（快速、便宜） + - 階段 2: Sonnet（推理能力強，用於深度分析） + - 階段 3: Haiku（任務簡單、數量多、成本極低）← **100 個 Haiku 調用成本 < 1 個 Sonnet** + - 階段 4: 無模型調用（主 session 處理） + - 階段 5: Sonnet（需要創造力和結構化能力） + + **總成本分析**： + - 中型專案（245 檔案）：約 2 Haiku + 6 Sonnet + 100 Haiku + 1 Sonnet + - 等價成本：約 10-12 個 Sonnet 調用 + - 相比全用 Sonnet 的簡單方案：節省 60-70% 成本 + +- **質量保證**： + - 所有發現都必須有檔案路徑證據 + - 評分代理會驗證檔案存在性 + - 閾值過濾確保只有高質量發現進入最終文件 + - 多層防護機制防止幻覺 diff --git a/plugin.lock.json b/plugin.lock.json new file mode 100644 index 0000000..af90528 --- /dev/null +++ b/plugin.lock.json @@ -0,0 +1,53 @@ +{ + "$schema": "internal://schemas/plugin.lock.v1.json", + "pluginId": "gh:DennisLiuCk/claude-plugin-marketplace:plugins/legacy-analyzer", + "normalized": { + "repo": null, + "ref": "refs/tags/v20251128.0", + "commit": "c5641aa3d58109234ce96ecaf100dadda3d4f22e", + "treeHash": "2f211c896e9640422ee00ff91a7a186db1a5a6d2862c4f273bbe06ffe1919340", + "generatedAt": "2025-11-28T10:10:14.874693Z", + "toolVersion": "publish_plugins.py@0.2.0" + }, + "origin": { + "remote": "git@github.com:zhongweili/42plugin-data.git", + "branch": "master", + "commit": "aa1497ed0949fd50e99e70d6324a29c5b34f9390", + "repoRoot": "/Users/zhongweili/projects/openmind/42plugin-data" + }, + "manifest": { + "name": "legacy-analyzer", + "description": "使用多個專門代理配合基於置信度的評分系統，分析 Legacy Java Spring Boot 專案並產生高品質教學文件", + "version": "1.4.0" + }, + "content": { + "files": [ + { + "path": "README.md", + "sha256": "0d66b66117b8393306d1e487d2dd223761f4041eddccdafc90844a323374ad50" + }, + { + "path": ".claude-plugin/plugin.json", + "sha256": "06ceed5e4be45ef67fd0946cf567c38630a615ea4ff354746c19535793e6519f" + }, + { + "path": "commands/analyze-java.md", + "sha256": "a3e80f21a6c1e71bc171fad32e337aebd5a5cc6ac7f5b26c11061c23faafa84e" + }, + { + "path": "commands/analyze-java-domain.md", + "sha256": "f3c4b3455a8c72b9af28c9fd44baa1d1317c6e4f9ce3a2ef12ef5cc823b9eb47" + }, + { + "path": "commands/analyze-java-domain-flow.md", + "sha256": "edeefac6c18d85445c91365db629b59349d048785c6c5d86bc0f1281566cf69f" + } + ], + "dirSha256": "2f211c896e9640422ee00ff91a7a186db1a5a6d2862c4f273bbe06ffe1919340" + }, + "security": { + "scannedAt": null, + "scannerVersion": null, + "flags": [] + } +} \ No newline at end of file