# 蝦米任務管理器系統架構 本文檔描述蝦米任務管理器的系統架構設計，包括各組件的功能、交互方式和數據流。 ## 1. 系統整體架構 蝦米任務管理器採用模塊化設計，基於 MCP (Model Context Protocol) 協議實現與 LLM 的互動。系統由以下核心組件構成： ``` +------------------+ | | | MCP 客戶端 | | (如 Cursor IDE) | | | +---------+--------+ | | MCP 協議 | +---------v--------+ | | | 工具註冊層 | <-- 新增 delete_task 工具 | (index.ts) | 新增 clear_all_tasks 工具 | | 新增 update_task 工具 | | 新增 update_task_files 工具 +---------+--------+ | | +------------------+------------------+ | | | +---------v--------+ +-------v---------+ +------v-----------+ | | | | | | | 工具實現層 | | 模型邏輯層 | | 工具實現層 | | (taskTools.ts) | | (taskModel.ts) | | (logTools.ts) | | | | | | | +------------------+ +-------+---------+ +------------------+ | | +---------v--------+ | | | 數據存儲層 | | (JSON 文件) | | | +------------------+ ``` ## 2. 主要組件說明 ### 2.1 工具註冊層 (index.ts) 工具註冊層負責將各功能工具註冊到 MCP 系統中，使其能夠被 LLM 訪問和使用。 **主要功能**： - 註冊 `plan_task` 工具函數，用於任務規劃 - 註冊 `analyze_task` 工具函數，用於任務分析 - 註冊 `reflect_task` 工具函數，用於批判性審查分析結果 - 註冊 `split_tasks` 工具函數，用於將複雜任務分解為子任務 - 註冊 `list_tasks` 工具函數，用於生成任務清單 - 註冊 `execute_task` 工具函數，用於執行特定任務 - 註冊 `verify_task` 工具函數，用於驗證任務完成度 - 註冊 `complete_task` 工具函數，用於標記任務為完成狀態 - 註冊 `delete_task` 工具函數，用於刪除未完成的任務 - 註冊 `clear_all_tasks` 工具函數，用於清除所有未完成的任務 - 註冊 `update_task` 工具函數，用於更新任務內容 - 註冊 `update_task_files` 工具函數，用於更新任務相關文件列表 - 註冊 `list_conversation_log` 工具函數，用於查詢系統對話日誌 - 註冊 `clear_conversation_log` 工具函數，用於清除所有對話日誌記錄 ### 2.2 工具實現層 (tools/\*.ts) 工具實現層包含具體工具函數的實現，處理參數解析、驗證和結果格式化。 **核心文件**： - `taskTools.ts`: 任務管理相關工具 - `logTools.ts`: 日誌管理相關工具 - `fileLoader.ts`: 任務相關文件的摘要生成工具 **主要功能**： - 實現 `planTask` 工具函數，初始化並詳細規劃任務流程 - 實現 `analyzeTask` 工具函數，深入分析任務需求 - 實現 `reflectTask` 工具函數，批判性審查分析結果 - 實現 `splitTasks` 工具函數，將複雜任務分解為獨立且可追蹤的子任務 - 實現 `listTasks` 工具函數，生成結構化任務清單 - 實現 `executeTask` 工具函數，按照預定義計劃執行特定任務 - 實現 `verifyTask` 工具函數，全面驗證任務完成度 - 實現 `completeTask` 工具函數，正式標記任務為完成狀態 - 實現 `deleteTask` 工具函數，刪除未完成的任務 - 實現 `clearAllTasks` 工具函數，刪除所有未完成的任務 - 實現 `updateTask` 工具函數，更新任務內容 - 實現 `updateTaskRelatedFiles` 工具函數，更新任務相關文件列表 - 實現 `listConversationLog` 工具函數，查詢系統對話日誌 - 實現 `clearConversationLog` 工具函數，清除所有對話日誌記錄 ### 2.3 模型邏輯層 (models/\*.ts) 模型邏輯層包含核心業務邏輯和數據處理函數，負責實現各種功能的邏輯處理。 **核心文件**： - `taskModel.ts`: 任務數據模型和操作 - `conversationLogModel.ts`: 對話日誌數據模型和操作 **主要功能**： - 在 `taskModel.ts` 中實現創建、讀取、更新和刪除任務的功能 - 在 `taskModel.ts` 中實現 `deleteTask` 函數，刪除未完成的任務 - 在 `taskModel.ts` 中實現 `clearAllTasks` 函數，刪除所有未完成的任務 - 在 `taskModel.ts` 中實現 `updateTask` 函數，更新任務內容 - 在 `taskModel.ts` 中實現 `updateTaskRelatedFiles` 函數，更新任務相關文件列表 - 在 `taskModel.ts` 中實現 `assessTaskComplexity` 函數，評估任務複雜度 - 在 `taskModel.ts` 中實現 `loadTaskById` 函數，載入特定任務 - 在 `taskModel.ts` 中實現 `completeTask` 函數，標記任務為完成狀態 - 在 `conversationLogModel.ts` 中實現對話日誌的記錄、查詢和清除功能 ### 2.4 數據模型定義 (types/index.ts) 定義系統中使用的所有數據類型和接口。 **主要類型**： - `TaskStatus` 枚舉：定義任務狀態，包括待處理、進行中、已完成和被阻擋 - `TaskDependency` 接口：定義任務依賴關係 - `RelatedFileType` 枚舉：定義文件關聯類型，如待修改、參考資料、輸出結果、依賴文件和其他 - `RelatedFile` 接口：定義任務相關文件結構 - `Task` 接口：定義任務的完整數據結構 - `ConversationParticipant` 枚舉：定義對話參與者類型，如 MCP 和 LLM - `ConversationEntry` 接口：定義對話日誌條目 - `TaskComplexityLevel` 枚舉：定義任務複雜度級別，如低複雜度、中等複雜度、高複雜度和極高複雜度 - `TaskComplexityThresholds` 常量：定義複雜度評估閾值 - `TaskComplexityAssessment` 接口：記錄複雜度評估結果 ### 2.5 工具函數 (utils/\*.ts) 提供各種輔助功能的工具函數。 **核心文件**： - `summaryExtractor.ts`: 實現摘要提取和生成功能 - `fileLoader.ts`: 實現任務相關文件的摘要生成功能 **主要功能**： - 實現 `extractSummary` 函數，從文本中提取簡短摘要 - 實現 `generateTaskSummary` 函數，基於任務名稱和描述生成任務完成摘要 - 實現 `extractTitle` 函數，從內容中提取適合作為標題的文本 - 實現 `extractSummaryFromConversation` 函數，從對話記錄中提取摘要信息 - 實現 `loadTaskRelatedFiles` 函數，生成任務相關文件的內容摘要 - 實現 `generateFileInfo` 函數，生成文件基本資訊摘要 ### 2.6 數據存儲層 使用 JSON 文件作為數據存儲，保存任務信息和對話日誌。 **核心文件**： - `data/tasks.json`: 存儲所有任務數據 - `data/conversation_log.json`: 存儲對話日誌數據 - `data/backups/`: 存儲任務數據備份 ## 3. 數據流 ### 3.1 任務刪除流程 ``` LLM 調用 delete_task | v 識別任務是否存在 | v 檢查任務狀態(拒絕刪除已完成任務) | v 檢查依賴關係(拒絕刪除有依賴的任務) | v 執行刪除操作 | v 記錄操作到日誌 | v 返回結果給 LLM ``` ### 3.2 任務複雜度評估流程 ``` LLM 調用 execute_task | v 載入任務信息 | v 評估任務複雜度 | +------------> 計算描述長度 | | +------------> 計算依賴數量 | | +------------> 計算注記長度 | | +------------> 檢查是否有注記 | | v v 確定複雜度級別 <----- 應用評估閾值 | v 生成處理建議 | v 更新任務提示，包含複雜度信息 | v 返回增強後的任務執行提示給 LLM ``` ### 3.3 任務完成流程 ``` LLM 調用 complete_task | v 載入任務信息 | v 檢查是否提供摘要 | +---- 有 ----> 使用提供的摘要 | +---- 無 ----> 自動生成摘要 | +---> 基於任務名稱和描述 | +---> 提取關鍵信息 | +---> 格式化摘要文本 | v 更新任務狀態為已完成 | v 保存摘要到任務記錄 | v 記錄操作到日誌 | v 返回結果給 LLM ``` ### 3.4 清除所有任務流程 ``` LLM 調用 clear_all_tasks | v 檢查確認參數（必須為 true） | v 創建數據備份 | v 載入當前任務列表 | v 篩選出未完成的任務 | v 記錄操作開始到日誌 | v 執行批量刪除 | v 更新數據文件 | v 記錄操作結果到日誌 | v 返回清除結果給 LLM ``` ### 3.5 更新任務內容流程 ``` LLM 調用 update_task | v 載入任務信息 | v 檢查任務是否存在 | v 檢查任務狀態（阻止更新已完成任務） | v 驗證更新參數（至少提供一個更新字段） | v 執行更新操作 | v 記錄操作到日誌 | v 返回更新結果給 LLM ``` ### 3.6 更新任務相關文件流程 ``` LLM 調用 update_task_files | v 載入任務信息 | v 檢查任務是否存在 | v 檢查任務狀態（阻止更新已完成任務） | v 驗證文件列表格式 | v 處理每個相關文件 | | | +---> 驗證文件路徑 | | | +---> 檢查行號範圍（如有提供） | | | +---> 驗證文件類型 | v 更新任務的相關文件列表 | v 記錄操作到日誌 | v 返回更新結果給 LLM ``` ### 3.7 文件處理流程 ``` 處理任務相關文件 | v 根據文件類型進行優先級排序 | | | +---> 待修改 > 參考資料 > 依賴文件 > 輸出結果 > 其他 | v 生成文件摘要 | | | +---> 對於指定行號範圍的文件，生成該範圍的摘要 | | | +---> 對於一般文件，生成整體內容摘要 | v 返回文件摘要結果 ``` ### 3.8 對話日誌查詢流程 ``` LLM 調用 list_conversation_log | v 處理過濾參數 | | | +---> 任務ID過濾（如有提供） | | | +---> 日期範圍過濾（如有提供） | | | +---> 應用分頁參數（limit和offset） | v 查詢符合條件的日誌條目 | v 格式化日誌條目列表 | v 返回查詢結果給 LLM ``` ## 4. 系統交互圖 ### 4.1 LLM 與任務管理器交互 ``` +-------+ 1.調用工具 +----------------+ | |------------------>| | | LLM | | 蝦米任務管理器 | | |<------------------| | +-------+ 4.返回結果 +-------+--------+ | +-------v--------+ | | | JSON 數據存儲 | | | +----------------+ ``` ### 4.2 工具層與模型層交互 ``` +-------------+ 調用 +-------------+ 讀寫 +------------+ | |------------->| |------------>| | | 工具實現層 | | 模型邏輯層 | | 數據存儲層 | | |<-------------| |<------------| | +-------------+ 返回結果 +-------------+ 返回數據 +------------+ ``` ## 5. 核心功能架構圖 ### 5.1 任務規劃功能 ``` +----------------+ +----------------+ +------------------+ | | | | | | | planTaskSchema |---->| planTask |---->| 任務規劃響應生成 | | | | (taskTools.ts) | | | +----------------+ +-------+--------+ +------------------+ ``` ### 5.2 任務分析功能 ``` +----------------+ +----------------+ +------------------+ | | | | | | | analyzeTaskSchema|---->| analyzeTask |---->| 技術分析指引生成 | | | | (taskTools.ts) | | | +----------------+ +-------+--------+ +------------------+ ``` ### 5.3 任務反思功能 ``` +----------------+ +----------------+ +------------------+ | | | | | | | reflectTaskSchema|---->| reflectTask |---->| 反思提示與建議生成| | | | (taskTools.ts) | | | +----------------+ +-------+--------+ +------------------+ ``` ### 5.4 任務拆分功能 ``` +----------------+ +----------------+ +------------------+ | | | | | | | splitTasksSchema|---->| splitTasks |---->| createTasks | | | | (taskTools.ts) | | (taskModel.ts) | +----------------+ +-------+--------+ +------------------+ ``` ### 5.5 任務執行功能 ``` +----------------+ +----------------+ +------------------+ | | | | | | | executeTaskSchema|---->| executeTask |---->| assessTaskComplexity| | | | (taskTools.ts) | | (taskModel.ts) | +----------------+ +-------+--------+ +------------------+ | v +------+---------------------+------+ | 任務執行指南和上下文生成 | +------+---------------------+------+ ``` ### 5.6 任務驗證功能 ``` +----------------+ +----------------+ +------------------+ | | | | | | | verifyTaskSchema|---->| verifyTask |---->| 任務驗證評估 | | | | (taskTools.ts) | | | +----------------+ +-------+--------+ +------------------+ ``` ### 5.7 完成任務功能 ``` +----------------+ +----------------+ +------------------+ | | | | | | | completeTaskSchema|---->| completeTask |---->| updateTaskSummary| | | | (taskTools.ts) | | (taskModel.ts) | +----------------+ +-------+--------+ +------------------+ | v +------+--------+ | summaryExtractor| | (utils) | +---------------+ ``` ### 5.8 任務刪除功能 ``` +----------------+ +----------------+ +------------------+ | | | | | | | deleteTaskSchema|---->| deleteTask |---->| modelDeleteTask | | | | (taskTools.ts) | | (taskModel.ts) | +----------------+ +-------+--------+ +------------------+ | v +------+---------------------+------+ | 檢查任務狀態和依賴關係 | +------+---------------------+------+ ``` ### 5.9 清除所有任務功能 ``` +------------------+ +----------------+ +------------------+ | | | | | | | clearAllTasksSchema|---->| clearAllTasks |---->| modelClearAllTasks| | | | (taskTools.ts) | | (taskModel.ts) | +------------------+ +-------+--------+ +------------------+ | v +------+---------------------+------+ | 確認參數檢查和數據備份 | +------+---------------------+------+ | v +------+---------------------+------+ | 篩選和批量刪除未完成任務 | +------+---------------------+------+ ``` ### 5.10 更新任務功能 ``` +------------------+ +----------------+ +------------------+ | | | | | | | updateTaskSchema |---->| updateTask |---->| updateTask | | | | (taskTools.ts) | | (taskModel.ts) | +------------------+ +-------+--------+ +------------------+ | v +------+---------------------+------+ | 檢查任務狀態和更新參數有效性 | +------+---------------------+------+ ``` ### 5.11 更新任務相關文件功能 ``` +----------------------+ +---------------------+ +----------------------+ | | | | | | | updateTaskFilesSchema |---->| updateTaskRelatedFiles |---->| updateTaskRelatedFiles | | | | (taskTools.ts) | | (taskModel.ts) | +----------------------+ +-----------+---------+ +-----------+----------+ | | v v +-------+-------------------------+------+ | 驗證文件格式和路徑有效性 | +-------+-------------------------+------+ | v +-------+-------------------------+------+ | 更新任務相關文件列表 | +-------+-------------------------+------+ ``` ### 5.12 日誌查詢功能 ``` +------------------------+ +-------------------+ +---------------------+ | | | | | | | listConversationLogSchema|---->| listConversationLog|---->| getConversationLogs | | | | (logTools.ts) | | (logModel.ts) | +------------------------+ +---------+---------+ +---------+-----------+ | | v v +-------+------------------------+-----+ | 過濾參數處理和分頁控制 | +-------+------------------------+-----+ ``` ### 5.13 清除日誌功能 ``` +-------------------------+ +--------------------+ +------------------------+ | | | | | | | clearConversationLogSchema|---->| clearConversationLog|---->| clearConversationLogs | | | | (logTools.ts) | | (logModel.ts) | +-------------------------+ +---------+----------+ +----------+-------------+ | | v v +-------+-------------------------+-----+ | 確認參數檢查和刪除操作 | +-------+-------------------------+-----+ ``` ## 6. 擴展性考慮 ### 6.1 新功能擴展方式 蝦米任務管理器的模塊化設計使其易於擴展。要添加新功能，通常需要： 1. 在 `types/index.ts` 中定義相關數據類型 2. 在相應的模型文件中實現核心邏輯 3. 在工具層創建對應的工具函數 4. 在 `index.ts` 中註冊新工具 ### 6.2 目前的擴展點 系統當前提供以下擴展點： - **任務處理流程擴展**：可通過修改 `executeTask`、`verifyTask` 等函數擴展任務處理流程 - **複雜度評估擴展**：可在 `assessTaskComplexity` 中添加更多評估指標 - **摘要生成擴展**：可增強 `summaryExtractor.ts` 中的算法 - **文件處理擴展**：可在 `fileLoader.ts` 中支持更多文件類型的摘要格式化 - **過濾條件擴展**：可在日誌查詢中添加更多過濾條件選項 ## 7. 系統限制與未來改進 ### 7.1 當前限制 - 使用文件存儲，不適合多用戶並發場景 - 缺乏用戶認證和權限控制 - 摘要生成使用簡單規則，可進一步改進 - 文件處理不讀取實際文件內容，僅生成摘要信息 ### 7.2 未來可能的改進 - 遷移到數據庫存儲，提高並發處理能力 - 添加用戶管理和訪問控制 - 使用更先進的算法優化摘要生成 - 添加任務優先級和時間規劃功能 - 實現任務執行進度追蹤 - 增強文件關聯系統，支持更複雜的關係類型 - 實現自動識別相關文件的能力 - 支持實際讀取文件內容，提供更詳細的上下文 ## 8. 結論 蝦米任務管理器採用模塊化、分層設計，使系統具有良好的可維護性和擴展性。通過 14 個核心工具函數和完善的數據模型，系統能夠有效地管理複雜項目的任務流程，特別在需要長期上下文記憶的場景中表現出色。 系統的設計重點在於提供清晰的任務管理流程，同時增強 LLM 在執行任務時的上下文記憶能力，通過精確的文件關聯和智能上下文載入，有效解決了 LLM 在處理長期複雜任務時的記憶限制問題。 隨著系統的進一步發展，未來將著重改進數據存儲方式、優化摘要生成算法、增強文件處理能力和添加更多任務管理功能，使系統能夠應對更多複雜的任務管理場景。