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 訪問和使用。

**新增功能**：

- 註冊 `delete_task` 工具函數，允許刪除未完成的任務
- 註冊 `clear_all_tasks` 工具函數，允許清除所有未完成的任務
- 註冊 `update_task` 工具函數，允許更新未完成任務的內容
- 註冊 `update_task_files` 工具函數，允許更新任務相關文件列表

### 2.2 工具實現層 (tools/\*.ts)

工具實現層包含具體工具函數的實現，處理參數解析、驗證和結果格式化。

**核心文件**：

- `taskTools.ts`: 任務管理相關工具
- `logTools.ts`: 日誌管理相關工具
- `fileLoader.ts`: 文件加載和處理工具（新增）

**新增功能**：

- 在 `taskTools.ts` 中新增 `deleteTask` 工具函數和 schema
- 在 `taskTools.ts` 中新增 `clearAllTasks` 工具函數和 schema，實現安全的任務清除
- 在 `taskTools.ts` 中新增 `updateTaskContent` 工具函數和 schema，支持任務內容更新
- 在 `taskTools.ts` 中新增 `updateTaskRelatedFiles` 工具函數和 schema，支持文件關聯管理
- 在 `executeTask` 中集成任務複雜度檢查邏輯
- 在 `executeTask` 中增強上下文記憶功能，自動加載相關文件
- 在 `completeTask` 中增強摘要處理功能

### 2.3 模型邏輯層 (models/\*.ts)

模型邏輯層包含核心業務邏輯和數據處理函數，負責實現各種功能的邏輯處理。

**核心文件**：

- `taskModel.ts`: 任務數據模型和操作
- `conversationLogModel.ts`: 對話日誌數據模型和操作

**新增功能**：

- 在 `taskModel.ts` 中實現 `deleteTask` 函數
- 在 `taskModel.ts` 中實現 `clearAllTasks` 函數，包含備份和安全檢查機制
- 在 `taskModel.ts` 中擴展 `updateTask` 函數，增加對已完成任務的檢查邏輯
- 在 `taskModel.ts` 中新增 `updateTaskContent` 和 `updateTaskRelatedFiles` 函數
- 增加 `assessTaskComplexity` 函數評估任務複雜度
- 實現 `updateTaskSummary` 函數更新任務摘要

### 2.4 數據模型定義 (types/index.ts)

定義系統中使用的所有數據類型和接口。

**新增類型**：

- `TaskComplexityLevel` 枚舉：定義任務複雜度級別
- `TaskComplexityThresholds` 常量：定義複雜度評估閾值
- `TaskComplexityAssessment` 接口：記錄複雜度評估結果
- `RelatedFile` 接口：定義任務相關文件結構
- `RelatedFileType` 枚舉：定義文件關聯類型（待修改、參考資料等）

### 2.5 工具函數 (utils/\*.ts)

提供各種輔助功能的工具函數。

**核心文件**：

- `summaryExtractor.ts`: 實現摘要提取和生成功能
- `fileLoader.ts`: 實現智能文件加載和代碼區塊提取功能（新增）
- `contextManager.ts`: 管理上下文記憶和優化（新增）

**新增功能**：

- 增強 `generateTaskSummary` 函數實現自動摘要生成
- 實現 `loadTaskRelatedFiles` 函數，智能加載相關文件內容
- 實現 `extractRelevantCodeBlocks` 函數，從大型文件中提取關鍵代碼
- 實現 `optimizeContext` 函數，優化上下文表示和壓縮

### 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
返回更新後的任務信息給 LLM
```

### 3.7 上下文記憶加載流程

```
執行任務前預處理
      |
      v
檢查任務相關文件列表
      |
      v
按優先級排序文件
      |
      v
智能加載文件內容
      |      |
      |      +---> 對於指定行號範圍的文件，優先加載該範圍
      |      |
      |      +---> 對於大型文件，提取關鍵代碼區塊
      |      |
      |      +---> 對於文檔文件，生成摘要
      |
      v
加載依賴任務的摘要
      |
      v
加載任務執行歷史記錄
      |
      v
優化上下文表示
      |
      v
將增強的上下文注入任務執行環境
```

## 4. 系統交互圖

### 4.1 LLM 與任務管理器交互

```
+-------+    1.調用工具     +----------------+
|       |------------------>|                |
|  LLM  |                   | 蝦米任務管理器  |
|       |<------------------|                |
+-------+    4.返回結果     +-------+--------+
                                    |
                            +-------v--------+
                            |                |
                            |  JSON 數據存儲 |
                            |                |
                            +----------------+
```

### 4.2 工具層與模型層交互

```
+-------------+     調用     +-------------+     讀寫    +------------+
|             |------------->|             |------------>|            |
| 工具實現層   |             | 模型邏輯層   |            | 數據存儲層  |
|             |<-------------|             |<------------|            |
+-------------+    返回結果   +-------------+    返回數據 +------------+
```

## 5. 新增功能架構圖

### 5.1 刪除任務功能

```
+----------------+     +----------------+     +---------------+
|                |     |                |     |               |
| deleteTaskSchema|---->| deleteTask    |---->| modelDeleteTask|
|                |     | (taskTools.ts) |     | (taskModel.ts)|
+----------------+     +------+---------+     +-------+-------+
                              |                       |
                              v                       v
                       +------+------------------------+------+
                       |        檢查任務狀態和依賴關係       |
                       +------+------------------------+------+
                              |
                              v
                       +------+------------------------+------+
                       |          記錄操作到日誌           |
                       +------+------------------------+------+
```

### 5.2 任務複雜度自適應處理

```
+----------------+     +----------------+     +------------------+
|                |     |                |     |                  |
| executeTask    |---->| 複雜度評估調用 |---->| assessTaskComplexity|
| (taskTools.ts) |     |                |     | (taskModel.ts)   |
+----------------+     +-------+--------+     +-------+----------+
                               |                      |
                               v                      v
                        +------+---------------------+------+
                        |     應用複雜度評估閾值和指標      |
                        +------+---------------------+------+
                               |
                               v
                        +------+---------------------+------+
                        |      生成處理建議和提示增強      |
                        +------+---------------------+------+
```

### 5.3 任務摘要自動更新機制

```
+-----------------+     +----------------+     +-------------------+
|                 |     |                |     |                   |
| completeTask    |---->| 摘要處理邏輯   |---->| updateTaskSummary |
| (taskTools.ts)  |     |                |     | (taskModel.ts)    |
+-----------------+     +-------+--------+     +---------+---------+
                                |                        |
                                v                        |
                         +------+--------+               |
                         | summaryExtractor|              |
                         | (utils)       |<--------------+
                         +---------------+
```

### 5.4 清除所有任務功能

```
+------------------+     +----------------+     +-------------------+
|                  |     |                |     |                   |
| clearAllTasksSchema |---->| clearAllTasks  |---->| modelClearAllTasks |
|                  |     | (taskTools.ts) |     | (taskModel.ts)    |
+------------------+     +-------+--------+     +---------+---------+
                                 |                        |
                                 v                        v
                          +------+---------------------+------+
                          |     確認參數檢查和數據備份      |
                          +------+---------------------+------+
                                 |
                                 v
                          +------+---------------------+------+
                          |      篩選和批量刪除未完成任務    |
                          +------+---------------------+------+
                                 |
                                 v
                          +------+---------------------+------+
                          |        記錄操作到日誌          |
                          +------+---------------------+------+
```

### 5.5 更新任務功能

```
+------------------+     +----------------+     +-------------------+
|                  |     |                |     |                   |
| updateTaskSchema |---->| updateTaskContent |---->| updateTask     |
|                  |     | (taskTools.ts) |     | (taskModel.ts)    |
+------------------+     +-------+--------+     +---------+---------+
                                 |                        |
                                 v                        v
                          +------+---------------------+------+
                          |  檢查任務狀態和更新參數有效性    |
                          +------+---------------------+------+
                                 |
                                 v
                          +------+---------------------+------+
                          |        應用更新和記錄操作       |
                          +------+---------------------+------+
```

### 5.6 任務相關文件位置記錄功能

```
+----------------------+     +---------------------+     +---------------------+
|                      |     |                     |     |                     |
| updateTaskFilesSchema |---->| updateTaskRelatedFiles |---->| updateTaskRelatedFiles |
|                      |     | (taskTools.ts)      |     | (taskModel.ts)      |
+----------------------+     +-----------+---------+     +-----------+---------+
                                       |                           |
                                       v                           v
                               +-------+-------------------------+------+
                               |     驗證文件格式和路徑有效性        |
                               +-------+-------------------------+------+
                                       |
                                       v
                               +-------+-------------------------+------+
                               |     更新任務相關文件列表            |
                               +-------+-------------------------+------+
```

### 5.7 上下文記憶優化功能

```
+---------------+     +-------------------+     +------------------+
|               |     |                   |     |                  |
| executeTask   |---->| loadTaskContext  |---->| loadRelatedFiles |
| (taskTools.ts)|     | (contextManager.ts) |   | (fileLoader.ts) |
+---------------+     +--------+----------+     +--------+---------+
                               |                        |
                               v                        v
                       +-------+------------------------+-----+
                       |      文件優先級排序和智能載入      |
                       +-------+------------------------+-----+
                               |
                               v
                       +-------+------------------------+-----+
                       |      上下文優化和大小控制         |
                       +-------+------------------------+-----+
                               |
                               v
                       +-------+------------------------+-----+
                       |      歷史記錄和依賴任務摘要整合    |
                       +-------+------------------------+-----+
```

## 6. 擴展性考慮

### 6.1 新功能擴展方式

蝦米任務管理器的模塊化設計使其易於擴展。要添加新功能，通常需要：

1. 在 `types/index.ts` 中定義相關數據類型
2. 在相應的模型文件中實現核心邏輯
3. 在工具層創建對應的工具函數
4. 在 `index.ts` 中註冊新工具

### 6.2 目前的擴展點

系統當前提供以下擴展點：

- **任務處理流程擴展**：可通過修改 `executeTask`、`verifyTask` 等函數擴展任務處理流程
- **複雜度評估擴展**：可在 `assessTaskComplexity` 中添加更多評估指標
- **摘要生成擴展**：可增強 `summaryExtractor.ts` 中的算法
- **上下文管理擴展**：可在 `contextManager.ts` 中添加更多上下文優化策略
- **文件加載擴展**：可在 `fileLoader.ts` 中支持更多文件類型的智能加載

## 7. 系統限制與未來改進

### 7.1 當前限制

- 使用文件存儲，不適合多用戶並發場景
- 缺乏用戶認證和權限控制
- 摘要生成使用簡單規則，可進一步改進
- 上下文大小有限，需要更智能的壓縮和優先級機制

### 7.2 未來可能的改進

- 遷移到數據庫存儲，提高並發處理能力
- 添加用戶管理和訪問控制
- 使用機器學習模型優化摘要生成和上下文管理
- 添加任務優先級和時間規劃功能
- 實現任務執行進度追蹤
- 增強文件關聯系統，支持更複雜的關係類型
- 實現自動識別相關文件的能力

## 8. 結論

蝦米任務管理器採用模塊化、分層設計，使系統具有良好的可維護性和擴展性。新增的清除所有任務功能、更新任務功能、任務相關文件位置記錄功能和上下文記憶優化功能進一步增強了系統的功能性和用戶體驗，使其能夠更有效地管理複雜項目的任務流程，特別是在需要長期上下文記憶的場景中表現出色。

系統的設計重點在於提供清晰的任務管理流程，同時增強 LLM 在執行任務時的上下文記憶能力，通過精確的文件關聯和智能上下文載入，有效解決了 LLM 在處理長期複雜任務時的記憶限制問題。