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

新增刪除任務功能，允許用戶刪除未完成的任務，並禁止刪除已完成的任務以維護系統記錄的完整性。同時，新增任務複雜度評估功能，系統在執行任務時自動評估複雜度並提供處理建議，並在任務完成時自動更新摘要。更新相關文檔以反映這些新功能，提升任務管理的靈活性與可操作性。

Browse Source
This commit is contained in:
siage 2025-04-11 17:31:48 +08:00
parent 7630185773
commit 3a003476e8
5 changed files with 1382 additions and 11 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

79
README.md
View File

@ -10,6 +10,9 @@
4. **執行追蹤**：監控任務執行進度和狀態 4. **執行追蹤**：監控任務執行進度和狀態
5. **任務驗證**：確保任務符合預期要求 5. **任務驗證**：確保任務符合預期要求
6. **工作日誌**：記錄和查詢對話歷史，提供任務執行過程的完整紀錄 6. **工作日誌**：記錄和查詢對話歷史，提供任務執行過程的完整紀錄
7. **刪除任務**：刪除未完成狀態的任務，維護任務列表整潔
8. **任務複雜度評估**：自動評估任務複雜度並提供處理建議
9. **任務摘要自動更新**：完成任務時自動更新摘要，優化記憶效能
## 任務管理工作流程 ## 任務管理工作流程
@ -20,9 +23,56 @@
3. **反思構想 (reflect_task)**：批判性審查分析結果，確保方案完善 3. **反思構想 (reflect_task)**：批判性審查分析結果，確保方案完善
4. **拆分任務 (split_tasks)**：將大任務拆分為小任務，建立依賴關係 4. **拆分任務 (split_tasks)**：將大任務拆分為小任務，建立依賴關係
5. **列出任務 (list_tasks)**：查看所有任務及其狀態 5. **列出任務 (list_tasks)**：查看所有任務及其狀態
6. **執行任務 (execute_task)**：執行特定任務 6. **執行任務 (execute_task)**：執行特定任務，同時評估任務複雜度
7. **檢驗任務 (verify_task)**：檢查任務完成情況 7. **檢驗任務 (verify_task)**：檢查任務完成情況
8. **完成任務 (complete_task)**：標記任務完成並提供報告 8. **完成任務 (complete_task)**：標記任務完成並提供報告，更新摘要
9. **刪除任務 (delete_task)**：刪除未完成的任務（不能刪除已完成任務）
## 新增功能詳情
### 刪除任務功能
允許刪除未完成狀態的任務，但禁止刪除已完成的任務。系統會檢查任務狀態和依賴關係，確保安全刪除。
```javascript
// 刪除特定任務
await mcp.mcp_shrimp_task_manager.delete_task({
taskId: "task-uuid-here",
});
```
更多詳情請參閱 [API 參考文檔](docs/api-reference.md#1-刪除任務功能) 和 [使用指南](docs/usage-guide.md#1-刪除任務功能)。
### 任務複雜度自適應處理
系統會在執行任務時自動評估任務複雜度，並根據複雜度提供適當的處理建議。支持四個複雜度級別：低複雜度、中等複雜度、高複雜度和極高複雜度。
複雜度評估基於多種指標：
- 任務描述長度
- 依賴任務數量
- 注記長度
更多詳情請參閱 [API 參考文檔](docs/api-reference.md#2-任務複雜度自適應處理) 和 [使用指南](docs/usage-guide.md#2-任務複雜度自適應處理)。
### 任務摘要自動更新機制
當任務完成時，系統會自動生成或使用提供的摘要信息，優化 LLM 的記憶效能。
```javascript
// 提供自定義摘要
await mcp.mcp_shrimp_task_manager.complete_task({
taskId: "task-uuid-here",
summary: "詳細的任務完成摘要...",
});
// 或使用自動生成的摘要
await mcp.mcp_shrimp_task_manager.complete_task({
taskId: "task-uuid-here",
});
```
更多詳情請參閱 [API 參考文檔](docs/api-reference.md#3-任務摘要自動更新機制) 和 [使用指南](docs/usage-guide.md#3-任務摘要自動更新機制)。
## 工作日誌功能 ## 工作日誌功能
@ -164,6 +214,13 @@ enum ConversationParticipant {
這種靈活的依賴指定方式讓您可以在同一批次創建的任務間建立依賴關係，無需預先知道任務 ID。 這種靈活的依賴指定方式讓您可以在同一批次創建的任務間建立依賴關係，無需預先知道任務 ID。
## 文檔資源
- [API 參考文檔](docs/api-reference.md)：詳細的 API 接口說明和參數列表
- [使用指南](docs/usage-guide.md)：功能使用場景和最佳實踐
- [示例代碼與案例](docs/examples.md)：具體使用案例和代碼示例
- [系統架構](docs/architecture.md)：系統架構設計和數據流
## 安裝與使用 ## 安裝與使用
```bash ```bash
@ -171,7 +228,7 @@ enum ConversationParticipant {
npm install npm install
# 啟動服務 # 啟動服務
npm start npm run build
``` ```
## 在支援 MCP 的客戶端中使用 ## 在支援 MCP 的客戶端中使用
@ -185,18 +242,15 @@ npm start
```json ```json
{ {
"mcpServers": [ "mcpServers": {
{ "shrimp-task-manager": {
"name": "蝦米任務管理器",
"id": "mcp-shrimp-task-manager",
"command": "node", "command": "node",
"args": ["path/to/mcp-shrimp-task-manager/dist/index.js"], "args": ["/mcp-shrimp-task-manager/dist/index.js"],
"description": "任務規劃、拆分、執行和管理工具",
"env": { "env": {
"NODE_ENV": "production" "DATA_DIR": "/mcp-shrimp-task-manager/data"
}
} }
} }
]
} }
``` ```
@ -214,6 +268,9 @@ npm start
- **執行任務**：`execute_task` - **執行任務**：`execute_task`
- **檢驗任務**：`verify_task` - **檢驗任務**：`verify_task`
- **完成任務**：`complete_task` - **完成任務**：`complete_task`
- **刪除任務**：`delete_task`
- **查詢日誌**：`list_conversation_log`
- **清除日誌**：`clear_conversation_log`
### 使用範例 ### 使用範例

167
docs/api-reference.md Normal file
View File

@ -0,0 +1,167 @@
# 蝦米任務管理器 API 參考文檔
本文檔提供蝦米任務管理器的 API 參考，包含所有可用工具的詳細說明和參數列表。
## 新增功能
### 1. 刪除任務功能
#### `delete_task`
允許刪除未完成狀態的任務，但禁止刪除已完成的任務。
**參數：**
| 參數名 | 類型 | 必填 | 描述 |
| ------ | ------ | ---- | --------------------------------------------------------- |
| taskId | string | 是 | 待刪除任務的唯一標識符，必須是系統中存在且未完成的任務 ID |
**返回：**
- 成功：返回操作成功的確認訊息
- 失敗：返回錯誤訊息，說明失敗原因（任務不存在、任務已完成、有依賴關係等）
**使用範例：**
```javascript
const deleteResult = await mcp.mcp_shrimp_task_manager.delete_task({
taskId: "task-uuid-here",
});
```
**約束條件：**
- 不允許刪除已完成的任務（狀態為 `COMPLETED`）
- 如果有其他任務依賴於此任務，也不允許刪除
- 刪除操作不可逆，請謹慎使用
### 2. 任務複雜度自適應處理
系統會在執行任務時自動評估任務複雜度，並提供相應的處理建議。此功能無需額外的 API 調用，在執行 `execute_task` 時自動應用。
**複雜度級別：**
- **低複雜度**：簡單且直接的任務，通常不需要特殊處理
- **中等複雜度**：具有一定複雜性但仍可管理的任務
- **高複雜度**：複雜且耗時的任務，需要特別關注
- **極高複雜度**：極其複雜的任務，建議拆分處理
**複雜度評估指標：**
- **描述長度**：任務描述的字符數
- **依賴數量**：任務依賴的前置任務數量
- **注記長度**：任務注記的字符數（如果有）
**複雜度閾值：**
| 指標 | 中等複雜度 | 高複雜度 | 極高複雜度 |
| -------- | ---------- | ---------- | ---------- |
| 描述長度 | >500 字符 | >1000 字符 | >2000 字符 |
| 依賴數量 | >2 個 | >5 個 | >10 個 |
| 注記長度 | >200 字符 | >500 字符 | >1000 字符 |
### 3. 任務摘要自動更新機制
當任務完成時，系統會自動生成或使用提供的摘要信息，以優化 LLM 的記憶效能。
#### `complete_task`
標記任務為已完成狀態，可提供自定義摘要或使用系統自動生成的摘要。
**參數：**
| 參數名 | 類型 | 必填 | 描述 |
| ------- | ------ | ---- | -------------------------------------------------------------------- |
| taskId | string | 是 | 待標記為完成的任務唯一標識符，必須是狀態為「進行中」的有效任務 ID |
| summary | string | 否 | 任務完成摘要，簡潔描述實施結果和重要決策（選填，如未提供將自動生成） |
**返回：**
- 成功：任務被標記為完成，並顯示任務報告要求
- 失敗：返回錯誤訊息，說明失敗原因
**使用範例：**
```javascript
// 提供自定義摘要
const completeResult = await mcp.mcp_shrimp_task_manager.complete_task({
taskId: "task-uuid-here",
summary:
"成功實現用戶驗證功能，包括登入、登出和密碼重設流程。採用了 JWT 令牌機制確保安全性，並添加了針對常見攻擊的防護措施。",
});
// 使用自動生成的摘要
const completeResult = await mcp.mcp_shrimp_task_manager.complete_task({
taskId: "task-uuid-here",
});
```
**自動摘要生成：**
當未提供 `summary` 參數時，系統會根據任務名稱和描述自動生成摘要。
## 工作日誌功能
### 1. 查詢日誌
#### `list_conversation_log`
查詢系統對話日誌，支持按任務 ID 或時間範圍過濾，提供分頁功能。
**參數：**
| 參數名 | 類型 | 必填 | 描述 |
| --------- | ------ | ---- | ------------------------------------------- |
| taskId | string | 否 | 按任務 ID 過濾（選填） |
| startDate | string | 否 | 起始日期過濾，ISO 格式字串（選填） |
| endDate | string | 否 | 結束日期過濾，ISO 格式字串（選填） |
| limit | number | 否 | 返回結果數量限制，預設 20，最大 100（選填） |
| offset | number | 否 | 分頁偏移量，預設 0（選填） |
**使用範例：**
```javascript
const logResult = await mcp.mcp_shrimp_task_manager.list_conversation_log({
taskId: "task-uuid-here", // 選填，按特定任務過濾
startDate: "2025-01-01T00:00:00Z", // 選填，開始日期
endDate: "2025-12-31T23:59:59Z", // 選填，結束日期
limit: 20, // 選填，每頁顯示數量
offset: 0, // 選填，分頁起始位置
});
```
### 2. 清除日誌
#### `clear_conversation_log`
清除所有對話日誌記錄，操作不可逆。
**參數：**
| 參數名 | 類型 | 必填 | 描述 |
| ------- | ------- | ---- | ------------------------- |
| confirm | boolean | 是 | 確認刪除操作，必須為 true |
**使用範例：**
```javascript
const clearResult = await mcp.mcp_shrimp_task_manager.clear_conversation_log({
confirm: true, // 必填，確認刪除操作
});
```
## 完整 API 列表
除了上述新增功能外，蝦米任務管理器還提供以下核心功能：
1. **開始規劃**：`plan_task`
2. **分析問題**：`analyze_task`
3. **反思構想**：`reflect_task`
4. **拆分任務**：`split_tasks`
5. **列出任務**：`list_tasks`
6. **執行任務**：`execute_task`
7. **檢驗任務**：`verify_task`
8. **完成任務**：`complete_task`
9. **刪除任務**：`delete_task`
10. **查詢日誌**：`list_conversation_log`
11. **清除日誌**：`clear_conversation_log`

329
docs/architecture.md Normal file
View File

@ -0,0 +1,329 @@
# 蝦米任務管理器系統架構
本文檔描述蝦米任務管理器的系統架構設計，包括各組件的功能、交互方式和數據流。
## 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. 結論
蝦米任務管理器採用模塊化、分層設計，使系統具有良好的可維護性和擴展性。新增的刪除任務功能、任務複雜度自適應處理和任務摘要自動更新機制進一步增強了系統的功能性和用戶體驗，使其能夠更有效地管理複雜項目的任務流程。

514
docs/examples.md Normal file
View File

@ -0,0 +1,514 @@
# 蝦米任務管理器 - 示例代碼與使用案例
本文檔提供蝦米任務管理器各功能的詳細示例代碼和實際使用案例，幫助您更好地理解和應用這些功能。
## 1. 刪除任務功能案例
### 案例：重新規劃項目架構
在一個開發週期中，您發現原本規劃的架構方案需要調整，部分任務不再適用。
#### 示例代碼：
```javascript
// 檢查當前的任務列表
const taskList = await mcp.mcp_shrimp_task_manager.list_tasks();
console.log(taskList);
// 識別需要刪除的任務
const tasksToDelete = [
"8a7b6c5d-4e3f-2g1h-0i9j-8k7l6m5n4o3p", // "設計舊版元件庫" 任務
"1a2b3c4d-5e6f-7g8h-9i0j-1k2l3m4n5o6p", // "實現舊版API介面" 任務
];
// 逐個刪除任務
for (const taskId of tasksToDelete) {
try {
const result = await mcp.mcp_shrimp_task_manager.delete_task({
taskId,
});
console.log(`任務 ${taskId} 刪除結果:`, result);
} catch (error) {
console.error(`刪除任務 ${taskId} 失敗:`, error);
// 檢查是否有依賴關係阻止刪除
if (error.message.includes("依賴")) {
console.log("檢測到依賴關係，需要先處理依賴任務");
// 這裡可以添加處理依賴關係的邏輯
}
}
}
// 確認任務已刪除
const updatedTaskList = await mcp.mcp_shrimp_task_manager.list_tasks();
console.log(updatedTaskList);
```
### 案例：修正錯誤創建的任務
在團隊協作過程中，由於溝通不當，創建了重複或不必要的任務。
#### 示例代碼：
```javascript
// 首先列出所有任務，識別重複項
const allTasks = await mcp.mcp_shrimp_task_manager.list_tasks();
// 假設我們發現兩個名稱相似的任務實際是同一個任務
const duplicateTasks = allTasks.content[0].text.match(
/ID: `([^`]+)`.*名稱: "用戶註冊功能"/g
);
if (duplicateTasks && duplicateTasks.length > 1) {
// 提取第二個重複任務的ID
const duplicateTaskId = duplicateTasks[1].match(/ID: `([^`]+)`/)[1];
// 刪除重複的任務
await mcp.mcp_shrimp_task_manager.delete_task({
taskId: duplicateTaskId,
});
console.log(`已刪除重複的任務: ${duplicateTaskId}`);
}
```
## 2. 任務複雜度自適應處理案例
### 案例：處理高複雜度的系統重構任務
您需要執行一個涉及多個子系統的大型重構任務，系統識別出這是一個高複雜度任務。
#### 示例代碼：
```javascript
// 執行複雜任務
const executeResult = await mcp.mcp_shrimp_task_manager.execute_task({
taskId: "complex-task-uuid-here",
});
// 解析複雜度評估結果
const complexityMatch = executeResult.content[0].text.match(/複雜度級別: (.*)/);
if (complexityMatch && complexityMatch[1].includes("高複雜度")) {
console.log("檢測到高複雜度任務，準備拆分...");
// 根據複雜度評估建議拆分任務
await mcp.mcp_shrimp_task_manager.split_tasks({
isOverwrite: false,
tasks: [
{
name: "重構階段1：數據模型更新",
description: "更新系統核心數據模型，確保向後兼容性",
notes: "需專注於資料遷移計劃",
},
{
name: "重構階段2：API改造",
description: "基於新數據模型更新API層",
dependencies: ["重構階段1：數據模型更新"],
},
{
name: "重構階段3：前端適配",
description: "更新前端代碼以兼容新API",
dependencies: ["重構階段2：API改造"],
},
],
});
// 列出拆分後的任務
await mcp.mcp_shrimp_task_manager.list_tasks();
}
```
### 案例：建立複雜任務的里程碑
對於複雜任務，設置明確的里程碑和檢查點可以幫助跟蹤進度。
#### 示例代碼：
```javascript
// 執行中等複雜度的任務
const taskResult = await mcp.mcp_shrimp_task_manager.execute_task({
taskId: "medium-complexity-task-uuid",
});
// 查看系統建議
console.log("系統複雜度評估建議:", taskResult);
// 根據建議設置里程碑
const today = new Date();
const milestones = [
{
name: "需求分析完成",
deadline: new Date(today.setDate(today.getDate() + 2))
.toISOString()
.split("T")[0],
},
{
name: "核心功能實現",
deadline: new Date(today.setDate(today.getDate() + 5))
.toISOString()
.split("T")[0],
},
{
name: "整合測試完成",
deadline: new Date(today.setDate(today.getDate() + 3))
.toISOString()
.split("T")[0],
},
{
name: "文檔編寫與部署",
deadline: new Date(today.setDate(today.getDate() + 2))
.toISOString()
.split("T")[0],
},
];
console.log("為複雜任務設置的里程碑:", milestones);
// 記錄里程碑到任務注記（假設我們有更新任務的API）
// 在實際場景中，您可能需要將這些里程碑記錄到專門的文檔或項目管理工具
```
## 3. 任務摘要自動更新機制案例
### 案例：完成關鍵功能並提供詳細摘要
您剛完成了一個重要的系統功能，需要記錄詳細的實施過程和決策理由。
#### 示例代碼：
```javascript
// 完成任務並提供詳細摘要
await mcp.mcp_shrimp_task_manager.complete_task({
taskId: "auth-system-task-uuid",
summary: `成功實現多因素認證系統，包括以下關鍵組件：
1. 核心認證流程：使用 JWT + 刷新令牌架構，支持多設備同時登入，令牌有效期為30分鐘，刷新令牌7天。
2. 因素實現：
- 知識因素：密碼採用 Argon2id 算法加鹽哈希存儲
- 設備因素：實現基於 FIDO2/WebAuthn 的無密碼認證
- 所有權因素：支持 TOTP 和 HOTP 兩種一次性密碼標準
3. 安全增強措施：
- 實現漸進式登入延遲，防止暴力破解
- IP變動時要求額外驗證
- 可疑活動檢測與自動鎖定
4. 性能優化：
- 認證流程平均響應時間降低40%
- 使用Redis作為令牌存儲，支持水平擴展
- 實現分層緩存策略，降低數據庫壓力
遇到並解決的主要挑戰：(1)跨域認證問題；(2)移動設備上的WebAuthn兼容性；(3)離線驗證機制。`,
});
// 列出任務，確認摘要已更新
const tasks = await mcp.mcp_shrimp_task_manager.list_tasks();
console.log(tasks);
```
### 案例：使用自動生成的摘要
對於較簡單的任務，可以讓系統自動生成摘要。
#### 示例代碼：
```javascript
// 完成任務，讓系統自動生成摘要
await mcp.mcp_shrimp_task_manager.complete_task({
taskId: "simple-logging-task-uuid",
});
// 檢查生成的摘要
const taskList = await mcp.mcp_shrimp_task_manager.list_tasks();
const completedTasks = taskList.content[0].text.match(/已完成.*?\n\n/gs);
if (completedTasks) {
const relevantTask = completedTasks.find((task) =>
task.includes("simple-logging-task-uuid")
);
const summaryMatch = relevantTask.match(/摘要: (.*?)(?:\n|$)/);
if (summaryMatch) {
console.log("系統自動生成的摘要:", summaryMatch[1]);
}
}
```
## 4. 工作日誌功能案例
### 案例：追蹤關鍵任務的執行歷程
在復盤專案時，需要了解某個關鍵任務的完整執行過程和決策點。
#### 示例代碼：
```javascript
// 查詢特定任務的日誌
const taskLogs = await mcp.mcp_shrimp_task_manager.list_conversation_log({
taskId: "key-feature-task-uuid",
limit: 50, // 獲取更多記錄
});
// 分析日誌中的關鍵決策點
const decisionPoints = taskLogs.entries.filter(
(entry) =>
entry.summary.includes("決定") ||
entry.summary.includes("選擇") ||
entry.summary.includes("決策")
);
console.log("任務執行過程中的關鍵決策點:", decisionPoints);
// 分析遇到的挑戰
const challenges = taskLogs.entries.filter(
(entry) =>
entry.summary.includes("問題") ||
entry.summary.includes("挑戰") ||
entry.summary.includes("困難") ||
entry.summary.includes("錯誤")
);
console.log("任務執行過程中遇到的挑戰:", challenges);
// 組織執行時間線
const timeline = taskLogs.entries
.map((entry) => ({
time: new Date(entry.timestamp),
action:
entry.summary.substring(0, 100) +
(entry.summary.length > 100 ? "..." : ""),
participant: entry.participant,
}))
.sort((a, b) => a.time - b.time);
console.log("任務執行時間線:", timeline);
```
### 案例：項目結束後清理不必要的日誌
在項目完成後，需要清理積累的大量日誌，但保留關鍵記錄。
#### 示例代碼：
```javascript
// 首先，提取重要日誌並保存
const allLogs = await mcp.mcp_shrimp_task_manager.list_conversation_log({
limit: 1000, // 嘗試獲取大量日誌
offset: 0,
});
// 識別關鍵日誌（例如重要決策、錯誤解決方案等）
const keyLogs = allLogs.entries.filter((entry) => {
// 過濾出重要性高的日誌
const isDecision =
entry.summary.includes("決策") || entry.summary.includes("選擇方案");
const isError =
entry.summary.includes("修復錯誤") || entry.summary.includes("解決問題");
const isMilestone =
entry.summary.includes("里程碑") || entry.summary.includes("階段完成");
return isDecision || isError || isMilestone;
});
// 將關鍵日誌保存到外部文件（示例）
console.log("保存的關鍵日誌數量:", keyLogs.length);
console.log("關鍵日誌示例:", keyLogs.slice(0, 3));
// 確認已保存重要日誌後，清除系統中的全部日誌
const confirmation = window.confirm(
"已保存關鍵日誌，是否清除系統中的所有日誌記錄？"
);
if (confirmation) {
await mcp.mcp_shrimp_task_manager.clear_conversation_log({
confirm: true,
});
console.log("所有日誌已清除");
}
```
## 5. 綜合案例：完整項目流程
以下是一個完整的項目工作流程示例，從規劃到完成，使用蝦米任務管理器的各項功能。
### 案例：開發一個用戶資料分析儀表板
#### 階段 1：項目規劃與任務拆分
```javascript
// 開始規劃
await mcp.mcp_shrimp_task_manager.plan_task({
description:
"開發一個用戶資料分析儀表板，用於可視化用戶行為數據，支持多維度分析和報表導出功能。",
requirements:
"技術棧要求使用React前端和Node.js後端，數據視覺化採用ECharts或D3.js，需支持千萬級用戶數據的實時分析。",
});
// 分析問題
await mcp.mcp_shrimp_task_manager.analyze_task({
summary: "用戶資料分析儀表板開發項目，集成多維數據可視化和報表導出功能",
initialConcept:
"採用模塊化設計，前端使用React+Redux+ECharts，後端使用Node.js+Express+MongoDB，實現數據流水線處理和快速響應的數據查詢API。",
});
// 反思構想
await mcp.mcp_shrimp_task_manager.reflect_task({
summary: "用戶資料分析儀表板開發項目，集成多維數據可視化和報表導出功能",
analysis:
"經過詳細分析，決定採用以下技術方案：\n1. 前端框架：React 18 + TypeScript\n2. 狀態管理：Redux Toolkit + RTK Query\n3. 視覺化庫：ECharts 5 (適合複雜數據視覺化)\n4. 後端API：Node.js + Express + MongoDB聚合查詢\n5. 數據處理：採用分層緩存策略，通過Redis緩存熱門查詢\n6. 報表導出：使用server-side生成PDF和CSV\n...",
});
// 拆分任務
await mcp.mcp_shrimp_task_manager.split_tasks({
isOverwrite: false,
tasks: [
{
name: "設計系統架構",
description:
"定義系統整體架構，包括前後端技術選型、數據流、API設計和部署架構",
notes: "需考慮系統擴展性和性能要求",
},
{
name: "開發資料處理後端",
description: "實現資料處理引擎，支持大數據量查詢和聚合分析",
dependencies: ["設計系統架構"],
},
{
name: "實現資料視覺化元件",
description: "開發可重用的視覺化圖表元件，支持多種數據展示形式",
dependencies: ["設計系統架構"],
},
{
name: "搭建儀表板界面",
description: "根據UI設計實現儀表板界面，包括布局、過濾器和用戶交互",
dependencies: ["設計系統架構"],
},
{
name: "整合資料和視覺化",
description: "連接後端API和前端視覺化元件，實現數據實時更新和交互",
dependencies: [
"開發資料處理後端",
"實現資料視覺化元件",
"搭建儀表板界面",
],
},
{
name: "開發報表導出功能",
description: "實現多格式報表導出功能，支持PDF、CSV等格式",
dependencies: ["整合資料和視覺化"],
},
{
name: "系統測試與優化",
description:
"進行系統整體測試，包括功能測試、性能測試和壓力測試，針對性優化",
dependencies: ["整合資料和視覺化", "開發報表導出功能"],
},
],
});
```
#### 階段 2：任務執行與複雜度處理
```javascript
// 列出所有任務
const tasks = await mcp.mcp_shrimp_task_manager.list_tasks();
console.log(tasks);
// 找出第一個待執行的任務
const pendingTasks = tasks.content[0].text.match(/待處理.*?ID: `([^`]+)`/gs);
const firstTaskId = pendingTasks[0].match(/ID: `([^`]+)`/)[1];
// 執行架構設計任務
const executeResult = await mcp.mcp_shrimp_task_manager.execute_task({
taskId: firstTaskId,
});
// 檢查複雜度評估
if (executeResult.content[0].text.includes("高複雜度")) {
console.log("架構設計是高複雜度任務，需要特別關注");
// 可以進一步拆分架構設計任務
await mcp.mcp_shrimp_task_manager.split_tasks({
isOverwrite: false,
tasks: [
{
name: "前端架構設計",
description: "設計前端架構，包括組件結構、狀態管理和路由設計",
dependencies: [],
},
{
name: "後端架構設計",
description: "設計後端架構，包括API結構、數據模型和緩存策略",
dependencies: [],
},
{
name: "整合前後端架構",
description: "確保前後端架構協同工作，定義數據交換格式和API契約",
dependencies: ["前端架構設計", "後端架構設計"],
},
],
});
}
```
#### 階段 3：完成任務與提供摘要
```javascript
// 驗證任務
await mcp.mcp_shrimp_task_manager.verify_task({
taskId: "architecture-task-uuid",
});
// 完成任務並提供詳細摘要
await mcp.mcp_shrimp_task_manager.complete_task({
taskId: "architecture-task-uuid",
summary: `成功設計完成系統整體架構，採用了以下關鍵技術決策：
1. 採用微服務架構，將資料處理和視覺化渲染分離，提高系統靈活性
2. 前端技術棧：React 18 + TypeScript + ECharts 5，組件採用原子設計模式
3. 後端技術棧：Node.js + Express + MongoDB，採用資料聚合管道處理複雜查詢
4. 快取策略：三層緩存（應用內存、Redis、持久化存儲），針對不同數據生命週期優化
5. 擴展性設計：水平擴展的API服務，事件驅動的資料處理管道
解決的主要挑戰：(1)大數據量分析性能瓶頸；(2)多維度數據實時更新一致性；(3)跨設備體驗一致性
測試結果顯示架構可支持超過1000萬用戶記錄的快速分析，查詢響應時間控制在200ms以內，比目標性能指標提升了35%。`,
});
```
#### 階段 4：查詢任務日誌和維護
```javascript
// 查詢任務執行日誌
const taskLogs = await mcp.mcp_shrimp_task_manager.list_conversation_log({
taskId: "architecture-task-uuid",
});
// 分析日誌，找出關鍵決策點
const decisions = taskLogs.entries.filter(
(entry) => entry.summary.includes("決定") || entry.summary.includes("選擇")
);
console.log("架構設計過程中的關鍵決策:", decisions);
// 清理不必要的任務（假設有些子任務變得不必要）
await mcp.mcp_shrimp_task_manager.delete_task({
taskId: "unnecessary-subtask-uuid",
});
// 最終檢查任務狀態
const finalTaskList = await mcp.mcp_shrimp_task_manager.list_tasks();
console.log("當前任務狀態:", finalTaskList);
```
## 結論
以上示例展示了蝦米任務管理器在不同場景下的使用方法。通過這些具體案例，您可以了解如何：
1. 使用刪除任務功能維護任務列表的整潔和準確性
2. 利用任務複雜度自適應處理功能合理規劃和分解複雜任務
3. 通過任務摘要自動更新機制記錄關鍵實施細節和決策
4. 使用工作日誌功能追蹤項目進展和關鍵決策點
這些功能共同提供了一個強大的任務管理框架，幫助您更有效地規劃、執行和監控項目。

304
docs/usage-guide.md Normal file
View File

@ -0,0 +1,304 @@
# 蝦米任務管理器使用指南
本指南提供蝦米任務管理器的詳細使用說明，包括各功能的使用場景、最佳實踐和實用建議。
## 新增功能使用指南
### 1. 刪除任務功能
#### 使用場景
- **任務規劃變更**：當項目規劃變更，需要刪除某些不再需要的任務時
- **錯誤創建的任務**：修正錯誤創建的任務，避免任務列表混亂
- **任務優先級調整**：刪除低優先級任務以聚焦於更重要的目標
#### 最佳實踐
1. **刪除前先檢查依賴關係**：使用 `list_tasks` 檢查是否有其他任務依賴於要刪除的任務
2. **先刪除子任務**：如果要刪除一個有多個子任務的父任務，建議先刪除所有子任務
3. **保留重要任務記錄**：對於重要但不再需要的任務，考慮將其標記為完成而非刪除，以保留歷史記錄
4. **刪除後驗證**：刪除操作後，使用 `list_tasks` 確認任務已被正確刪除且依賴關係未受影響
#### 範例使用流程
```javascript
// 1. 先查看任務列表，確認要刪除的任務 ID
await mcp.mcp_shrimp_task_manager.list_tasks();
// 2. 刪除特定任務
await mcp.mcp_shrimp_task_manager.delete_task({
taskId: "task-uuid-here",
});
// 3. 再次查看任務列表，確認刪除結果
await mcp.mcp_shrimp_task_manager.list_tasks();
```
#### 注意事項
- 已完成的任務（狀態為 `COMPLETED`）無法刪除，這是為了保持系統記錄的完整性
- 如果任務有依賴關係，系統會阻止刪除操作並提供詳細的錯誤信息
- 刪除操作是永久性的，請在操作前確認
### 2. 任務複雜度自適應處理
#### 使用場景
- **大型項目初始評估**：快速評估任務複雜度，幫助合理規劃
- **任務執行前準備**：了解任務複雜度，提前做好資源分配
- **拆分複雜任務**：識別高複雜度任務，考慮拆分為小任務
#### 最佳實踐
1. **關注複雜度警告**：當系統顯示「高複雜度」或「極高複雜度」警告時，應特別重視
2. **遵循處理建議**：系統會根據複雜度提供針對性建議，應認真考慮這些建議
3. **複雜任務拆分**：對於極高複雜度的任務，最好使用 `split_tasks` 拆分成多個子任務
4. **設置里程碑**：對於高複雜度任務，定期檢查進度並記錄關鍵決策點
#### 複雜度級別處理指南
| 複雜度級別 | 處理建議 |
| ---------- | ------------------------------------------------------------ |
| 低複雜度 | 直接執行，設定明確的完成標準 |
| 中等複雜度 | 詳細規劃執行步驟，分階段執行並定期檢查進度 |
| 高複雜度 | 進行充分的分析和規劃，考慮拆分為子任務，建立清晰的里程碑 |
| 極高複雜度 | 強烈建議拆分為多個獨立任務，進行風險評估，建立具體的測試標準 |
#### 範例使用流程
```javascript
// 執行任務時，系統會自動評估複雜度並提供建議
const result = await mcp.mcp_shrimp_task_manager.execute_task({
taskId: "task-uuid-here",
});
// 對於高複雜度任務，考慮拆分
if (
result.content.includes("高複雜度") ||
result.content.includes("極高複雜度")
) {
await mcp.mcp_shrimp_task_manager.split_tasks({
isOverwrite: false,
tasks: [
// 拆分後的子任務...
],
});
}
```
### 3. 任務摘要自動更新機制
#### 使用場景
- **任務完成記錄**：記錄任務完成的關鍵成果與決策
- **知識傳遞**：為團隊成員提供簡明的任務完成報告
- **進度回顧**：在項目中期或結束時回顧已完成的工作成果
#### 最佳實踐
1. **提供詳細摘要**：儘可能提供詳細但簡潔的自定義摘要，而非依賴自動生成
2. **突出關鍵點**：在摘要中強調最重要的實現細節、技術選擇和解決方案
3. **包含量化成果**：如適用，包括性能改進、資源節省等量化結果
4. **記錄挑戰與解決方案**：記錄遇到的主要挑戰及其解決方法
#### 編寫高品質摘要的指南
優質的任務摘要應該包含以下要素：
1. **成就說明**：清晰說明實現了什麼功能或解決了什麼問題
2. **實施方法**：簡述實現的主要步驟或採用的技術方案
3. **技術決策**：解釋為何選擇特定的實現方法
4. **成果評估**：描述實現結果如何滿足或超出預期
5. **限制與展望**：提及現有實現的限制以及未來可能的改進方向
#### 範例使用流程
```javascript
// 完成任務時提供詳細摘要
await mcp.mcp_shrimp_task_manager.complete_task({
taskId: "task-uuid-here",
summary:
"成功實現任務複雜度自適應處理功能，包括：(1)在 types/index.ts 中定義了 TaskComplexityLevel 枚舉、TaskComplexityThresholds 閾值常量和 TaskComplexityAssessment 介面；(2)在 taskModel.ts 中新增 assessTaskComplexity 函數，根據任務描述長度、依賴數量和注記長度等指標評估任務複雜度；(3)修改 executeTask 函數整合複雜度檢查邏輯，並根據複雜度級別提供適當的提示和處理建議。實現結果可準確識別不同複雜度的任務，並提供針對性的處理策略，有效提升複雜任務的管理效率。",
});
// 或者讓系統自動生成摘要
await mcp.mcp_shrimp_task_manager.complete_task({
taskId: "task-uuid-here",
});
```
#### 自動摘要生成的工作原理
當未提供自定義摘要時，系統會：
1. 基於任務名稱和描述自動生成摘要
2. 使用智能算法提取關鍵信息
3. 確保摘要長度適中（約 250 字符以內）
4. 保留任務最核心的功能描述和目標
## 工作日誌功能使用指南
### 查詢日誌 (`list_conversation_log`)
#### 使用場景
- **追蹤任務執行過程**：了解特定任務的執行歷程
- **回顧關鍵決策**：查找過去做出的重要決策和理由
- **診斷問題**：當遇到問題時，檢查歷史記錄以找出原因
- **提取經驗教訓**：從過去的項目中學習，避免重複錯誤
#### 最佳實踐
1. **使用特定過濾條件**：針對具體任務或時間段查詢，避免獲取過多不相關日誌
2. **利用分頁功能**：對於大量日誌，使用分頁功能逐步檢視
3. **定期審查日誌**：定期查看日誌，及時發現問題並總結經驗
4. **將關鍵發現記錄到文檔**：將日誌中的重要發現整理到專門的文檔中，方便團隊分享
#### 範例使用流程
```javascript
// 查詢特定任務的日誌
const taskLogs = await mcp.mcp_shrimp_task_manager.list_conversation_log({
taskId: "task-uuid-here",
});
// 查詢特定時間段的日誌
const dateLogs = await mcp.mcp_shrimp_task_manager.list_conversation_log({
startDate: "2025-01-01T00:00:00Z",
endDate: "2025-01-31T23:59:59Z",
});
// 使用分頁功能查看大量日誌
let allLogs = [];
let offset = 0;
const limit = 20;
let hasMore = true;
while (hasMore) {
const logs = await mcp.mcp_shrimp_task_manager.list_conversation_log({
limit,
offset,
});
allLogs = allLogs.concat(logs.entries);
offset += limit;
hasMore = logs.entries.length === limit;
}
```
### 清除日誌 (`clear_conversation_log`)
#### 使用場景
- **釋放存儲空間**：當日誌佔用過多空間時
- **保護隱私**：清除包含敏感信息的日誌
- **重新開始**：在項目新階段開始前清理舊日誌
#### 最佳實踐
1. **備份重要日誌**：清除前考慮導出或備份重要日誌
2. **定期維護**：建立定期日誌清理計劃，維持系統整潔
3. **選擇性清理**：考慮只保留最近或最關鍵的日誌
4. **確認清理操作**：清除是不可逆的，操作前確保團隊成員都已了解
#### 範例使用流程
```javascript
// 清除所有日誌（需慎重操作）
await mcp.mcp_shrimp_task_manager.clear_conversation_log({
confirm: true,
});
```
## 整合使用流程
以下是一個完整的任務管理工作流程，整合了所有功能的使用：
1. **規劃與分析**
```javascript
// 開始規劃
await mcp.mcp_shrimp_task_manager.plan_task({
description: "項目描述...",
requirements: "技術要求...",
});
// 分析問題
await mcp.mcp_shrimp_task_manager.analyze_task({
summary: "任務摘要...",
initialConcept: "初步構想...",
});
// 反思構想
await mcp.mcp_shrimp_task_manager.reflect_task({
summary: "任務摘要...",
analysis: "分析結果...",
});
```
2. **任務拆分與執行**
```javascript
// 拆分任務
await mcp.mcp_shrimp_task_manager.split_tasks({
isOverwrite: false,
tasks: [
/* 任務列表 */
],
});
// 查看任務列表
await mcp.mcp_shrimp_task_manager.list_tasks();
// 執行任務（系統會自動評估複雜度）
await mcp.mcp_shrimp_task_manager.execute_task({
taskId: "task-uuid-here",
});
```
3. **驗證與完成**
```javascript
// 驗證任務
await mcp.mcp_shrimp_task_manager.verify_task({
taskId: "task-uuid-here",
});
// 完成任務（提供詳細摘要）
await mcp.mcp_shrimp_task_manager.complete_task({
taskId: "task-uuid-here",
summary: "詳細摘要...",
});
```
4. **維護與整理**
```javascript
// 刪除不需要的任務
await mcp.mcp_shrimp_task_manager.delete_task({
taskId: "task-uuid-here",
});
// 查詢任務日誌
await mcp.mcp_shrimp_task_manager.list_conversation_log({
taskId: "task-uuid-here",
});
```
## 常見問題與解決方案
### Q: 如何處理極高複雜度的任務？
**A:** 建議將極高複雜度的任務拆分為多個小任務。使用 `split_tasks` 工具，確保每個子任務都有明確的範圍和可驗證的成功標準。
### Q: 自動生成的摘要不夠詳細怎麼辦？
**A:** 建議總是提供自定義摘要。自定義摘要應包含實施過程中的關鍵決策、主要挑戰及其解決方案、使用的核心技術和達成的成果。
### Q: 為什麼無法刪除已完成的任務？
**A:** 這是為了保持系統記錄的完整性。已完成的任務通常包含寶貴的實施記錄和經驗，保留這些信息有助於未來的參考和學習。
### Q: 日誌記錄佔用了太多空間怎麼辦？
**A:** 定期使用 `list_conversation_log` 工具檢查日誌，提取關鍵信息並記錄到專門的文檔中，然後使用 `clear_conversation_log` 工具清理舊日誌。