MCP/mcp-shrimp-task-manager
1
0
Fork 0
mirror of https://github.com/cjo4m06/mcp-shrimp-task-manager.git synced 2025-07-27 00:12:26 +08:00
Code Issues Packages Projects Releases Wiki Activity
mcp-shrimp-task-manager/docs/architecture.md

22 KiB
Raw Blame History

蝦米任務管理器系統架構

本文檔描述蝦米任務管理器的系統架構設計，包括各組件的功能、交互方式和數據流。

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 在處理長期複雜任務時的記憶限制問題。

隨著系統的進一步發展，未來將著重改進數據存儲方式、優化摘要生成算法、增強文件處理能力和添加更多任務管理功能，使系統能夠應對更多複雜的任務管理場景。