mirror of
https://github.com/cjo4m06/mcp-shrimp-task-manager.git
synced 2025-07-27 16:42:30 +08:00
312 lines
12 KiB
Markdown
312 lines
12 KiB
Markdown
# 蝦米任務管理器 - 功能實現清單
|
||
|
||
本文檔列出蝦米任務管理器系統中所有實際實現的工具函數、參數結構和功能。此清單作為文檔審查的基準參考。
|
||
|
||
## 類型定義與枚舉
|
||
|
||
### 任務狀態枚舉 (TaskStatus)
|
||
|
||
- `PENDING = "待處理"` - 已創建但尚未開始執行的任務
|
||
- `IN_PROGRESS = "進行中"` - 當前正在執行的任務
|
||
- `COMPLETED = "已完成"` - 已成功完成並通過驗證的任務
|
||
- `BLOCKED = "被阻擋"` - 由於依賴關係而暫時無法執行的任務
|
||
|
||
### 任務依賴關係 (TaskDependency)
|
||
|
||
- `taskId: string` - 前置任務的唯一標識符，當前任務執行前必須完成此依賴任務
|
||
|
||
### 相關文件類型枚舉 (RelatedFileType)
|
||
|
||
- `TO_MODIFY = "待修改"` - 需要在任務中修改的文件
|
||
- `REFERENCE = "參考資料"` - 任務的參考資料或相關文檔
|
||
- `OUTPUT = "輸出結果"` - 任務產生的輸出文件
|
||
- `DEPENDENCY = "依賴文件"` - 任務依賴的組件或庫文件
|
||
- `OTHER = "其他"` - 其他類型的相關文件
|
||
|
||
### 相關文件 (RelatedFile)
|
||
|
||
- `path: string` - 文件路徑，可以是相對於項目根目錄的路徑或絕對路徑
|
||
- `type: RelatedFileType` - 文件與任務的關係類型
|
||
- `description?: string` - 文件的補充描述，說明其與任務的具體關係或用途
|
||
- `lineStart?: number` - 相關代碼區塊的起始行（選填）
|
||
- `lineEnd?: number` - 相關代碼區塊的結束行（選填）
|
||
|
||
### 任務介面 (Task)
|
||
|
||
- `id: string` - 任務的唯一標識符
|
||
- `name: string` - 簡潔明確的任務名稱
|
||
- `description: string` - 詳細的任務描述，包含實施要點和驗收標準
|
||
- `notes?: string` - 補充說明、特殊處理要求或實施建議（選填）
|
||
- `status: TaskStatus` - 任務當前的執行狀態
|
||
- `dependencies: TaskDependency[]` - 任務的前置依賴關係列表
|
||
- `createdAt: Date` - 任務創建的時間戳
|
||
- `updatedAt: Date` - 任務最後更新的時間戳
|
||
- `completedAt?: Date` - 任務完成的時間戳（僅適用於已完成的任務）
|
||
- `summary?: string` - 任務完成摘要，簡潔描述實施結果和重要決策（僅適用於已完成的任務）
|
||
- `relatedFiles?: RelatedFile[]` - 與任務相關的文件列表（選填）
|
||
|
||
### 任務複雜度級別枚舉 (TaskComplexityLevel)
|
||
|
||
- `LOW = "低複雜度"` - 簡單且直接的任務，通常不需要特殊處理
|
||
- `MEDIUM = "中等複雜度"` - 具有一定複雜性但仍可管理的任務
|
||
- `HIGH = "高複雜度"` - 複雜且耗時的任務，需要特別關注
|
||
- `VERY_HIGH = "極高複雜度"` - 極其複雜的任務，建議拆分處理
|
||
|
||
### 任務複雜度評估結果 (TaskComplexityAssessment)
|
||
|
||
- `level: TaskComplexityLevel` - 整體複雜度級別
|
||
- `metrics: object` - 各項評估指標的詳細數據
|
||
- `descriptionLength: number` - 描述長度
|
||
- `dependenciesCount: number` - 依賴數量
|
||
- `notesLength: number` - 注記長度
|
||
- `hasNotes: boolean` - 是否有注記
|
||
- `recommendations: string[]` - 處理建議列表
|
||
|
||
## 工具函數與參數
|
||
|
||
### 1. plan_task
|
||
|
||
**描述**：初始化並詳細規劃任務流程，建立明確的目標與成功標準
|
||
|
||
**參數**：
|
||
|
||
- `description: string` (必填) - 完整詳細的任務問題描述，應包含任務目標、背景及預期成果
|
||
- 必須至少 10 個字符
|
||
- `requirements?: string` (選填) - 任務的特定技術要求、業務約束條件或品質標準
|
||
|
||
**返回值**：
|
||
|
||
- 返回一個包含規劃提示的響應，用於引導用戶開始任務分析
|
||
|
||
### 2. analyze_task
|
||
|
||
**描述**：深入分析任務需求並系統性檢查代碼庫，評估技術可行性與潛在風險
|
||
|
||
**參數**：
|
||
|
||
- `summary: string` (必填) - 結構化的任務摘要，包含任務目標、範圍與關鍵技術挑戰
|
||
- 必須至少 20 個字符
|
||
- `initialConcept: string` (必填) - 初步解答構想，包含技術方案、架構設計和實施策略
|
||
- 必須至少 50 個字符
|
||
- `previousAnalysis?: string` (選填) - 前次迭代的分析結果，用於持續改進方案
|
||
|
||
**返回值**：
|
||
|
||
- 返回一個包含技術分析指引的響應，用於指導用戶進行深入分析
|
||
|
||
### 3. reflect_task
|
||
|
||
**描述**：批判性審查分析結果，評估方案完整性並識別優化機會，確保解決方案符合最佳實踐
|
||
|
||
**參數**：
|
||
|
||
- `summary: string` (必填) - 結構化的任務摘要，保持與分析階段一致以確保連續性
|
||
- 必須至少 20 個字符
|
||
- `analysis: string` (必填) - 完整詳盡的技術分析結果，包括所有技術細節、依賴組件和實施方案
|
||
- 必須至少 100 個字符
|
||
|
||
**返回值**：
|
||
|
||
- 返回一個包含反思提示與實施建議的響應
|
||
|
||
### 4. split_tasks
|
||
|
||
**描述**：將複雜任務分解為獨立且可追蹤的子任務，建立明確的依賴關係和優先順序
|
||
|
||
**參數**：
|
||
|
||
- `updateMode: "append" | "overwrite" | "selective" | "clearAllTasks"` (必填) - 任務更新模式選擇：
|
||
- `append`：保留所有現有任務並添加新任務
|
||
- `overwrite`：清除所有未完成任務並完全替換
|
||
- `selective`：根據任務名稱匹配更新現有任務，保留不在列表中的任務
|
||
- `clearAllTasks`：清除所有任務並創建備份
|
||
- `tasks: Array<object>` (必填) - 結構化的任務清單，每個任務應保持原子性且有明確的完成標準
|
||
- `name: string` (必填) - 簡潔明確的任務名稱，應能清晰表達任務目的
|
||
- 不超過 100 個字符
|
||
- `description: string` (必填) - 詳細的任務描述，包含實施要點、技術細節和驗收標準
|
||
- 必須至少 10 個字符
|
||
- `notes?: string` (選填) - 補充說明、特殊處理要求或實施建議
|
||
- `dependencies?: string[]` (選填) - 此任務依賴的前置任務 ID 或任務名稱列表
|
||
- `relatedFiles?: RelatedFile[]` (選填) - 與任務相關的文件列表
|
||
|
||
**返回值**：
|
||
|
||
- 返回一個包含任務拆分結果的響應，包括成功創建的任務數量和任務 ID 列表
|
||
|
||
### 5. list_tasks
|
||
|
||
**描述**：生成結構化任務清單，包含完整狀態追蹤、優先級和依賴關係
|
||
|
||
**參數**：無
|
||
|
||
**返回值**：
|
||
|
||
- 返回一個包含任務清單的響應，按狀態分組顯示所有任務
|
||
|
||
### 6. execute_task
|
||
|
||
**描述**：按照預定義計劃執行特定任務，確保每個步驟的輸出符合質量標準
|
||
|
||
**參數**：
|
||
|
||
- `taskId: string` (必填) - 待執行任務的唯一標識符，必須是系統中存在的有效任務 ID
|
||
|
||
**返回值**：
|
||
|
||
- 返回一個包含任務執行指南的響應，包括任務詳情、複雜度評估和執行步驟建議
|
||
|
||
### 7. verify_task
|
||
|
||
**描述**：全面驗證任務完成度，確保所有需求與技術標準都已滿足，並無遺漏細節
|
||
|
||
**參數**：
|
||
|
||
- `taskId: string` (必填) - 待驗證任務的唯一標識符，必須是系統中存在的有效任務 ID
|
||
|
||
**返回值**：
|
||
|
||
- 返回一個包含任務驗證結果的響應，包括完成標準檢查和具體驗證項
|
||
|
||
### 8. complete_task
|
||
|
||
**描述**：正式標記任務為完成狀態，生成詳細的完成報告，並更新關聯任務的依賴狀態
|
||
|
||
**參數**：
|
||
|
||
- `taskId: string` (必填) - 待完成任務的唯一標識符，必須是系統中存在的有效任務 ID
|
||
- `summary?: string` (選填) - 任務完成摘要，簡潔描述實施結果和重要決策
|
||
|
||
**返回值**：
|
||
|
||
- 返回一個包含任務完成確認的響應，包括完成時間和更新的依賴任務狀態
|
||
|
||
### 9. delete_task
|
||
|
||
**描述**：刪除未完成的任務，但不允許刪除已完成的任務，確保系統記錄的完整性
|
||
|
||
**參數**：
|
||
|
||
- `taskId: string` (必填) - 待刪除任務的唯一標識符，必須是系統中存在且未完成的任務 ID
|
||
|
||
**返回值**：
|
||
|
||
- 返回一個包含任務刪除結果的響應，包括成功或失敗的訊息
|
||
|
||
### 10. clear_all_tasks
|
||
|
||
**描述**：刪除系統中所有未完成的任務，該指令必須由用戶明確確認才能執行。同時將任務備份到 memory 子目錄，保存任務歷史記錄以供未來參考。
|
||
|
||
**參數**：
|
||
|
||
- `confirm: boolean` (必填) - 確認刪除所有未完成的任務（此操作不可逆）
|
||
|
||
**返回值**：
|
||
|
||
- 返回一個包含清除操作結果的響應，包括成功或失敗的訊息、備份文件名和備份位置
|
||
|
||
**重要細節**：
|
||
|
||
- 在刪除任務前，會自動將當前任務列表備份到 data/memory 子目錄
|
||
- 備份文件使用時間戳命名，格式為 tasks_memory_YYYY-MM-DDThh-mm-ss.json
|
||
- memory 子目錄作為長期記憶庫，用於存儲任務歷史記錄，供未來任務規劃參考
|
||
|
||
### 11. update_task
|
||
|
||
**描述**：更新任務內容，包括名稱、描述和注記，但不允許修改已完成的任務
|
||
|
||
**參數**：
|
||
|
||
- `taskId: string` (必填) - 待更新任務的唯一標識符，必須是系統中存在且未完成的任務 ID
|
||
- `name?: string` (選填) - 任務的新名稱
|
||
- `description?: string` (選填) - 任務的新描述內容
|
||
- `notes?: string` (選填) - 任務的新補充說明
|
||
|
||
**返回值**：
|
||
|
||
- 返回一個包含任務更新結果的響應，包括成功或失敗的訊息
|
||
|
||
### 12. update_task_files
|
||
|
||
**描述**：更新任務相關文件列表，用於記錄與任務相關的代碼文件、參考資料等
|
||
|
||
**參數**：
|
||
|
||
- `taskId: string` (必填) - 待更新任務的唯一標識符，必須是系統中存在且未完成的任務 ID
|
||
- `relatedFiles: Array<RelatedFile>` (必填) - 與任務相關的文件列表
|
||
- `path: string` (必填) - 文件路徑，可以是相對於項目根目錄的路徑或絕對路徑
|
||
- `type: RelatedFileType` (必填) - 文件與任務的關係類型
|
||
- `description?: string` (選填) - 文件的補充描述
|
||
- `lineStart?: number` (選填) - 相關代碼區塊的起始行
|
||
- `lineEnd?: number` (選填) - 相關代碼區塊的結束行
|
||
|
||
**返回值**：
|
||
|
||
- 返回一個包含文件更新結果的響應，包括成功或失敗的訊息
|
||
|
||
## 工具函數重要細節
|
||
|
||
### 依賴關係 (dependencies) 處理
|
||
|
||
- 在 `splitTasks` 和其他函數中，`dependencies` 參數允許接受任務名稱或任務 ID(UUID)
|
||
- 系統會在任務創建或更新時將字串陣列轉換為 `TaskDependency` 物件陣列
|
||
- 任務依賴關係形成有向無環圖(DAG)，用於確定任務執行順序和阻塞狀態
|
||
|
||
### 任務複雜度評估
|
||
|
||
- 系統使用 `assessTaskComplexity` 函數評估任務的複雜度
|
||
- 評估基於多個指標：描述長度、依賴數量、注記長度等
|
||
- 根據 `TaskComplexityThresholds` 定義的閾值來判定複雜度級別
|
||
- 複雜度評估結果用於生成適當的處理建議
|
||
|
||
### 文件處理功能
|
||
|
||
- `loadTaskRelatedFiles` 函數不實際讀取檔案內容，僅生成文件資訊摘要
|
||
- 文件按類型優先級排序：待修改 > 參考資料 > 依賴文件 > 輸出結果 > 其他
|
||
- 支持指定代碼區塊行號範圍，便於精確定位關鍵實現
|
||
|
||
## 實用工具函數
|
||
|
||
### 摘要提取 (summaryExtractor.ts)
|
||
|
||
- `extractSummary` - 從文本中提取簡短摘要，自動處理 Markdown 格式
|
||
- `generateTaskSummary` - 基於任務名稱和描述生成任務完成摘要
|
||
- `extractTitle` - 從內容中提取適合作為標題的文本
|
||
|
||
### 文件加載 (fileLoader.ts)
|
||
|
||
- `loadTaskRelatedFiles` - 生成任務相關文件的內容摘要
|
||
- `generateFileInfo` - 生成文件基本資訊摘要
|
||
|
||
## 任務記憶功能
|
||
|
||
任務記憶功能是蝦米任務管理器的重要特性，它使系統具備長期記憶能力，能夠保存、查詢和利用過去的任務執行經驗。
|
||
|
||
### 核心實現
|
||
|
||
1. **自動備份機制**：
|
||
|
||
- 在 `clearAllTasks` 函數中實現雙重備份功能
|
||
- 將任務備份同時保存在 data 目錄和 data/memory 子目錄
|
||
- 使用時間戳命名備份文件，格式為 tasks_memory_YYYY-MM-DDThh-mm-ss.json
|
||
|
||
2. **智能提示指導**：
|
||
- 在 `planTask` 函數的提示詞中添加任務記憶檢索指南
|
||
- 指導 Agent 如何查找、分析和應用歷史任務記錄
|
||
- 提供智能參考建議，促進知識重用
|
||
|
||
### 使用場景
|
||
|
||
- **任務規劃時**：參考類似任務的實施方案和最佳實踐
|
||
- **問題解決時**：查閱過去遇到的類似問題及其解決方法
|
||
- **代碼重用時**：識別過去實現的可重用組件或模式
|
||
- **經驗學習時**：分析過去成功和失敗案例，持續優化工作方式
|
||
|
||
### 技術要點
|
||
|
||
- 使用相對路徑引用 memory 目錄，保持代碼的一致性和可維護性
|
||
- 確保 memory 目錄存在，如不存在則自動創建
|
||
- 保持原有的錯誤處理模式，確保系統穩定性
|
||
- 備份過程透明無感，不影響用戶正常操作流程
|
||
|
||
此功能無需額外工具或配置，系統會自動在任務清除時保存歷史記錄，並在任務規劃時提供智能指導，使 Agent 能夠充分利用過去的經驗和知識。
|