mcp-shrimp-task-manager/docs/architecture.md

# 蝦米任務管理器系統架構

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

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

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