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

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

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

## 1. 系統整體架構

蝦米任務管理器採用模塊化設計，基於 MCP (Model Context Protocol) 協議實現與 LLM 的互動。系統由以下核心組件構成：

```
                    +------------------+
                    |                  |
                    |   MCP 客戶端     |
                    | (如 Cursor IDE)  |
                    |                  |
                    +---------+--------+
                              |
                              | MCP 協議
                              |
                    +---------v--------+
                    |                  |
                    |   工具註冊層     |  <-- 新增 delete_task 工具
                    |   (index.ts)     |
                    |                  |
                    +---------+--------+
                              |
                              |
          +------------------+------------------+
          |                  |                  |
+---------v--------+ +-------v---------+ +------v-----------+
|                  | |                 | |                  |
|    工具實現層    | |   模型邏輯層    | |    工具實現層    |
|  (taskTools.ts)  | | (taskModel.ts)  | |  (logTools.ts)   |
|                  | |                 | |                  |
+------------------+ +-------+---------+ +------------------+
                              |
                              |
                    +---------v--------+
                    |                  |
                    |   數據存儲層     |
                    |   (JSON 文件)    |
                    |                  |
                    +------------------+
```

## 2. 主要組件說明

### 2.1 工具註冊層 (index.ts)

工具註冊層負責將各功能工具註冊到 MCP 系統中，使其能夠被 LLM 訪問和使用。

**新增功能**：

- 註冊 `delete_task` 工具函數，允許刪除未完成的任務

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

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

**核心文件**：

- `taskTools.ts`: 任務管理相關工具
- `logTools.ts`: 日誌管理相關工具

**新增功能**：

- 在 `taskTools.ts` 中新增 `deleteTask` 工具函數和 schema
- 在 `executeTask` 中集成任務複雜度檢查邏輯
- 在 `completeTask` 中增強摘要處理功能

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

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

**核心文件**：

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

**新增功能**：

- 在 `taskModel.ts` 中實現 `deleteTask` 函數
- 增加 `assessTaskComplexity` 函數評估任務複雜度
- 實現 `updateTaskSummary` 函數更新任務摘要

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

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

**新增類型**：

- `TaskComplexityLevel` 枚舉：定義任務複雜度級別
- `TaskComplexityThresholds` 常量：定義複雜度評估閾值
- `TaskComplexityAssessment` 接口：記錄複雜度評估結果

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

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

**核心文件**：

- `summaryExtractor.ts`: 實現摘要提取和生成功能

**新增功能**：

- 增強 `generateTaskSummary` 函數實現自動摘要生成

### 2.6 數據存儲層

使用 JSON 文件作為數據存儲，保存任務信息和對話日誌。

**核心文件**：

- `data/tasks.json`: 存儲所有任務數據
- `data/conversation_log.json`: 存儲對話日誌數據

## 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
```

## 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)       |<--------------+
                         +---------------+
```

## 6. 擴展性考慮

### 6.1 新功能擴展方式

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

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

### 6.2 目前的擴展點

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

- **任務處理流程擴展**：可通過修改 `executeTask`、`verifyTask` 等函數擴展任務處理流程
- **複雜度評估擴展**：可在 `assessTaskComplexity` 中添加更多評估指標
- **摘要生成擴展**：可增強 `summaryExtractor.ts` 中的算法

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

### 7.1 當前限制

- 使用文件存儲，不適合多用戶並發場景
- 缺乏用戶認證和權限控制
- 摘要生成使用簡單規則，可進一步改進

### 7.2 未來可能的改進

- 遷移到數據庫存儲，提高並發處理能力
- 添加用戶管理和訪問控制
- 使用機器學習模型優化摘要生成
- 添加任務優先級和時間規劃功能
- 實現任務執行進度追蹤

## 8. 結論

蝦米任務管理器採用模塊化、分層設計，使系統具有良好的可維護性和擴展性。新增的刪除任務功能、任務複雜度自適應處理和任務摘要自動更新機制進一步增強了系統的功能性和用戶體驗，使其能夠更有效地管理複雜項目的任務流程。