1077 lines
33 KiB
Markdown
1077 lines
33 KiB
Markdown
---
|
||
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 層<br/>處理 HTTP 請求]
|
||
Service[Service 層<br/>業務邏輯處理]
|
||
Repository[Repository 層<br/>資料存取]
|
||
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% 成本
|
||
|
||
- **質量保證**：
|
||
- 所有發現都必須有檔案路徑證據
|
||
- 評分代理會驗證檔案存在性
|
||
- 閾值過濾確保只有高質量發現進入最終文件
|
||
- 多層防護機制防止幻覺
|