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

更新 README 文件以強調蝦米任務管理器的智能任務管理系統特性，重新整理功能特點與任務管理工作流程，並新增系統提示詞指導，提升用戶對系統的理解與使用體驗。同時，移除不再使用的 API 參考文檔與示例代碼，簡化文檔結構，增強可讀性與維護性。

Browse Source
This commit is contained in:
siage 2025-04-12 16:57:47 +08:00
parent 2e94c71c21
commit feac46d780
7 changed files with 638 additions and 2800 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

2
.cursor/modes.json
View File

@ -37,7 +37,7 @@
"description": "Execute tasks",
"comment": "Task Planner - Creates and maintains task files",
"model": "claude-3.7-sonnet",
"customPrompt": "你是一個專業的任務執行專家，當用戶有指定執行任務，則使用 mcp_shrimp_task_manager_execute_task 進行任務執行，沒有執行任務時則使用 mcp_shrimp_task_manager_list_tasks 尋找位執行的任務並執行，當執行完成後必須總結摘要告知用戶使用，你一次只能執行一個任務，單任務完成時除非用戶明確告知否則禁止進行下一則任務。",
"customPrompt": "你是一個專業的任務執行專家，當用戶有指定執行任務，則使用 mcp_shrimp_task_manager_execute_task 進行任務執行，沒有執行任務時則使用 mcp_shrimp_task_manager_list_tasks 尋找位執行的任務並執行，當執行完成後必須總結摘要告知用戶使用，你一次只能執行一個任務，單任務完成時除非用戶明確告知否則禁止進行下一則任務。用戶如果要求連續模式則按照順序連續執行所有任務",
"allowedCursorTools": [
"codebase_search",
"read_file",

360
README.md
View File

@ -1,237 +1,49 @@
# MCP 蝦米任務管理器
基於 Model Context Protocol (MCP)的任務管理系統，幫助 Agent 有效管理和執行任務。
> 🚀 基於 Model Context Protocol (MCP) 的智能任務管理系統，為 AI Agent 提供高效的程式開發工作流程框架。
## 功能特點
蝦米任務管理器透過結構化的工作流程引導，協助 Agent 系統性規劃程式開發步驟，強化任務記憶管理機制，有效避免冗餘與重複的編程工作。
1. **任務規劃與分析**：幫助 Agent 理解和分析複雜任務
2. **任務拆分**：將大型任務拆分為可管理的小任務
3. **依賴管理**：處理任務間的依賴關係，確保正確的執行順序
4. **執行追蹤**：監控任務執行進度和狀態
5. **任務驗證**：確保任務符合預期要求
6. **工作日誌**：記錄和查詢對話歷史，提供任務執行過程的完整紀錄
7. **刪除任務**：刪除未完成狀態的任務，維護任務列表整潔
8. **任務複雜度評估**：自動評估任務複雜度並提供處理建議
9. **任務摘要自動更新**：完成任務時自動更新摘要，優化記憶效能
## ✨ 功能特點
## 任務管理工作流程
- **任務規劃與分析**：深入理解與分析複雜任務需求
- **智能任務拆分**：將大型任務自動拆分為可管理的小型任務
- **依賴關係管理**：精確處理任務間的依賴關係，確保正確的執行順序
- **執行狀態追蹤**：即時監控任務執行進度和狀態
- **任務完整性驗證**：確保任務成果符合預期要求
- **完整工作日誌**：記錄和查詢對話歷史，提供任務執行過程的完整紀錄
- **任務複雜度評估**：自動評估任務複雜度並提供最佳處理建議
- **任務摘要自動更新**：完成任務時自動產生摘要，優化記憶效能
本系統提供了完整的任務工作流程：
## 🔄 任務管理工作流程
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)**：刪除未完成的任務（不能刪除已完成任務）
本系統提供完整的任務管理生命週期：
## 新增功能詳情
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`：管理未完成的任務（已完成任務將保留在系統中）
### 刪除任務功能
## 📚 文件資源
允許刪除未完成狀態的任務，但禁止刪除已完成的任務。系統會檢查任務狀態和依賴關係，確保安全刪除。
- [系統架構](docs/architecture.md)：詳細的系統設計與數據流說明
```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-任務摘要自動更新機制)。
## 工作日誌功能
### 功能概述
工作日誌系統記錄 MCP 與 LLM 之間的關鍵對話內容，主要目的是：
1. **保存執行脈絡**：記錄任務執行過程中的關鍵決策和事件
2. **提供可追溯性**：方便回溯查看歷史操作和決策理由
3. **知識累積**：積累經驗知識，避免重複解決相同問題
4. **效能分析**：提供數據支持，幫助分析系統效能和改進方向
系統會自動在以下關鍵時刻記錄日誌：
- 任務執行開始時
- 關鍵決策點
- 任務驗證過程中
- 任務完成時
### 如何使用日誌查詢工具
系統提供兩個主要的日誌管理工具：
#### 1. 查詢日誌 (list_conversation_log)
```javascript
const logResult = await mcp.mcp_shrimp_task_manager.list_conversation_log({
taskId: "任務ID", // 選填，按特定任務過濾
startDate: "2025-01-01T00:00:00Z", // 選填，開始日期（ISO格式）
endDate: "2025-12-31T23:59:59Z", // 選填，結束日期（ISO格式）
limit: 20, // 選填，每頁顯示數量，預設20，最大100
offset: 0, // 選填，分頁起始位置，預設0
});
```
參數說明：
- `taskId`：按任務 ID 過濾日誌
- `startDate`：查詢開始日期，ISO 格式字串
- `endDate`：查詢結束日期，ISO 格式字串
- `limit`：每頁顯示的記錄數量，預設 20，最大 100
- `offset`：分頁偏移量，用於實現分頁查詢
#### 2. 清除日誌 (clear_conversation_log)
```javascript
const clearResult = await mcp.mcp_shrimp_task_manager.clear_conversation_log({
confirm: true, // 必填，確認刪除操作
});
```
注意：清除操作不可逆，請謹慎使用。
### 日誌數據結構
工作日誌的核心數據結構為 `ConversationEntry`：
```typescript
interface ConversationEntry {
id: string; // 唯一識別符
timestamp: Date; // 記錄時間
participant: ConversationParticipant; // 對話參與者（MCP或LLM）
summary: string; // 消息摘要，僅記錄關鍵信息
relatedTaskId?: string; // 關聯的任務ID（選填）
context?: string; // 額外上下文信息（選填）
}
enum ConversationParticipant {
MCP = "MCP", // 系統方
LLM = "LLM", // 模型方
}
```
日誌以 JSON 格式存儲在 `data/conversation_log.json` 文件中，當記錄數量超過閾值時，系統會自動將舊日誌歸檔並創建新的日誌文件。
### 開發者指南：擴展或修改日誌功能
#### 關鍵文件
1. **類型定義**：`src/types/index.ts`
- 包含 `ConversationEntry` 和 `ConversationParticipant` 等核心類型定義
2. **模型層**：`src/models/conversationLogModel.ts`
- 包含所有日誌相關的數據操作函數
- 日誌文件的讀寫、查詢、歸檔等功能
3. **工具層**：`src/tools/logTools.ts`
- 提供給外部調用的日誌工具函數
- 實現格式化輸出和參數處理
4. **摘要提取**：`src/utils/summaryExtractor.ts`
- 從完整對話中提取關鍵信息的工具
- 使用關鍵詞匹配和重要性評分算法
#### 如何擴展
1. **添加新的日誌查詢方式**
- 在 `conversationLogModel.ts` 中添加新的查詢函數
- 在 `logTools.ts` 中創建相應的工具函數
- 在 `index.ts` 中註冊新工具
2. **修改日誌存儲方式**
- 日誌默認以 JSON 文件形式存儲，可修改 `conversationLogModel.ts` 改用數據庫存儲
- 同時更新相關的讀寫函數
3. **優化摘要提取算法**
- 可在 `summaryExtractor.ts` 中增強或替換摘要提取算法
- 考慮添加基於機器學習的摘要方法
4. **添加新的日誌觸發點**
- 在關鍵流程中調用 `addConversationEntry` 函數添加新的日誌記錄點
## 任務依賴關係
系統支持兩種方式指定任務依賴：
1. **通過任務名稱**（推薦）：使用任務名稱直接引用依賴任務，更直觀易讀
```json
{
"name": "實現前端表單",
"dependencies": ["設計UI界面", "定義API規格"]
}
```
2. **通過任務 ID**：使用任務的唯一標識符，適用於需要精確引用的場景
```json
{
"name": "部署應用",
"dependencies": ["a1b2c3d4-e5f6-g7h8-i9j0-k1l2m3n4o5p6"]
}
```
這種靈活的依賴指定方式讓您可以在同一批次創建的任務間建立依賴關係，無需預先知道任務 ID。
## 文檔資源
- [API 參考文檔](docs/api-reference.md)：詳細的 API 接口說明和參數列表
- [使用指南](docs/usage-guide.md)：功能使用場景和最佳實踐
- [示例代碼與案例](docs/examples.md)：具體使用案例和代碼示例
- [系統架構](docs/architecture.md)：系統架構設計和數據流
## 安裝與使用
## 🔧 安裝與使用
```bash
# 安裝依賴
# 安裝依賴套件
npm install
# 啟動服務
# 建置並啟動服務
npm run build
```
## 在支援 MCP 的客戶端中使用
## 🔌 在支援 MCP 的客戶端中使用
蝦米任務管理器可以與任何支援 Model Context Protocol 的客戶端一起使用，例如 Cursor IDE。
@ -241,8 +53,8 @@ npm run build
#### 全局配置
1. 打開 Cursor IDE 的全局設定檔案（通常位於 `~/.cursor/mcp.json`）
2. 在 `mcpServers` 部分添加蝦米任務管理器的配置
1. 開啟 Cursor IDE 的全局設定檔案（通常位於 `~/.cursor/mcp.json`）
2. 在 `mcpServers` 區段中添加以下配置：
```json
{
@ -258,11 +70,11 @@ npm run build
}
```
請將 `/mcp-shrimp-task-manager` 替換為實際的路徑。
> ⚠️ 請將 `/mcp-shrimp-task-manager` 替換為您的實際路徑。
#### 專案特定配置
您也可以在每個專案中設定專屬的配置，這樣能夠針對不同專案使用不同的數據目錄：
您也可以為每個專案設定專屬配置，以便針對不同專案使用獨立的數據目錄：
1. 在專案根目錄創建 `.cursor` 目錄
2. 在該目錄下創建 `mcp.json` 文件，內容如下：
@ -281,74 +93,72 @@ npm run build
}
```
**DATA_DIR 參數**是蝦米任務管理器存儲任務數據、對話記錄等信息的目錄，正確設置此參數對於系統的正常運行至關重要。此參數必須使用絕對路徑，使用相對路徑可能導致系統無法正確定位數據目錄，造成數據丟失或功能失效。
### ⚠️ 重要配置說明
> **警告**：DATA_DIR 參數僅支援絕對路徑設置。使用相對路徑可能導致以下問題：
**DATA_DIR 參數**是蝦米任務管理器存儲任務數據、對話記錄等信息的目錄，正確設置此參數對於系統的正常運行至關重要。此參數必須使用**絕對路徑**，使用相對路徑可能導致系統無法正確定位數據目錄，造成數據丟失或功能失效。
> **警告**：使用相對路徑可能導致以下問題：
>
> - 數據檔案找不到，導致系統初始化失敗
> - 任務狀態丟失或無法正確保存
> - 應用程式在不同環境下行為不一致
> - 系統崩潰或無法啟動
更多關於專案特定配置的詳細說明和最佳實踐，請參閱[使用指南：專案特定配置](docs/usage-guide.md#project-specific-configuration)。
## 💡 系統提示詞指導
### 可用的工具
### Cursor IDE 配置
在 Cursor IDE 中，配置完成後，您可以使用以下工具：
您可以啟用 Cursor Settings => Features => Custom modes 功能，並配置以下兩個模式：
- **開始規劃**：`plan_task`
- **分析問題**：`analyze_task`
- **反思構想**：`reflect_task`
- **拆分任務**：`split_tasks`
- **列出任務**：`list_tasks`
- **執行任務**：`execute_task`
- **檢驗任務**：`verify_task`
- **完成任務**：`complete_task`
- **刪除任務**：`delete_task`
- **查詢日誌**：`list_conversation_log`
- **清除日誌**：`clear_conversation_log`
#### TaskPlanner 模式
### 使用範例
在 Cursor IDE 中，您可以這樣使用蝦米任務管理器：
```javascript
// 開始規劃一個任務
const planResult = await mcp.mcp_shrimp_task_manager.plan_task({
description: "開發一個用戶註冊系統",
requirements: "需要支持電子郵件和社交媒體登入",
});
// 拆分任務
const splitResult = await mcp.mcp_shrimp_task_manager.split_tasks({
isOverwrite: false,
tasks: [
{
name: "設計用戶界面",
description: "創建用戶友好的註冊表單界面",
notes: "需要遵循品牌設計指南",
},
{
name: "實現後端API",
description: "開發用戶註冊和驗證API",
dependencies: ["設計用戶界面"], // 使用任務名稱引用依賴
},
],
});
// 執行任務
const executeResult = await mcp.mcp_shrimp_task_manager.execute_task({
taskId: "task-uuid-here", // 可從list_tasks獲取
});
```
你是一個專業的任務規劃專家，你必須與用戶進行交互，分析用戶的需求，並收集專案相關資訊，最終使用 mcp_shrimp_task_manager_plan_task 建立任務，當任務建立完成後必須總結摘要，並告知用戶使用 任務執行 Model 進行任務執行。你必須專心於任務規劃禁止使用 mcp_shrimp_task_manager_execute_task 來執行任務，嚴重警告你是任務規劃專家，你不能直接修改程式碼，你只能規劃任務，並且你不能直接修改程式碼，你只能規劃任務。
```
## 技術實現
#### TaskExecutor 模式
- **Node.js**：JavaScript 運行時環境
- **TypeScript**：提供類型安全
- **MCP SDK**：用於與大型語言模型互動
- **UUID**：生成唯一任務標識符
```
你是一個專業的任務執行專家，當用戶有指定執行任務，則使用 mcp_shrimp_task_manager_execute_task 進行任務執行，沒有執行任務時則使用 mcp_shrimp_task_manager_list_tasks 尋找位執行的任務並執行，當執行完成後必須總結摘要告知用戶使用，你一次只能執行一個任務，單任務完成時除非用戶明確告知否則禁止進行下一則任務。用戶如果要求"連續模式"則按照順序連續執行所有任務
```
## 許可協議
> 💡 根據您的需求場景選擇適當的模式：
>
> - 當需要規劃任務時使用 **TaskPlanner** 模式
> - 當需要執行任務時使用 **TaskExecutor** 模式
MIT
### 在其他工具中使用
如果您的工具不支援 Custom modes 功能，可以：
- 在不同階段手動貼上相應的提示詞
- 或直接使用簡單命令如 `請規劃以下任務：......` 或 `請開始執行任務...`
## 🛠️ 可用工具一覽
配置完成後，您可使用以下工具：
| 功能分類 | 工具名稱 | 功能描述 |
| ------------ | ------------------------ | ------------------ |
| **任務規劃** | `plan_task` | 開始規劃任務 |
| **任務分析** | `analyze_task` | 深入分析任務需求 |
| **方案評估** | `reflect_task` | 反思與改進方案構想 |
| **任務管理** | `split_tasks` | 將任務拆分為子任務 |
| | `list_tasks` | 顯示所有任務及狀態 |
| | `delete_task` | 刪除未完成的任務 |
| **任務執行** | `execute_task` | 執行特定任務 |
| | `verify_task` | 檢驗任務完成情況 |
| | `complete_task` | 標記任務為已完成 |
| **日誌管理** | `list_conversation_log` | 查詢對話歷史日誌 |
| | `clear_conversation_log` | 清除歷史對話記錄 |
## 🔧 技術實現
- **Node.js**：高效能的 JavaScript 運行時環境
- **TypeScript**：提供強型別安全的開發環境
- **MCP SDK**：與大型語言模型無縫互動的接口
- **UUID**：生成唯一且可靠的任務識別碼
## 📄 許可協議
本專案採用 MIT 許可協議發布 - 詳見 [LICENSE](LICENSE) 文件

545
docs/api-reference.md
View File

@ -1,545 +0,0 @@
# 蝦米任務管理器 API 參考文檔
本文檔提供蝦米任務管理器的 API 參考，包含所有可用工具的詳細說明和參數列表。
## 目錄
- [核心任務管理 API](#核心任務管理-api)
- [任務管理 API](#任務管理-api)
- [工作日誌功能](#工作日誌功能)
- [實用工具函數](#實用工具函數)
## 核心任務管理 API
### 1. 任務規劃
#### `plan_task`
初始化並詳細規劃任務流程，建立明確的目標與成功標準。
**參數：**
| 參數名 | 類型 | 必填 | 描述 |
| ------------ | ------ | ---- | ------------------------------------------------------ |
| description | string | 是 | 完整詳細的任務問題描述，應包含任務目標、背景及預期成果 |
| requirements | string | 否 | 任務的特定技術要求、業務約束條件或品質標準（選填） |
**返回：**
- 成功：返回結構化的任務規劃結果
- 失敗：返回錯誤訊息，說明失敗原因
**使用範例：**
```javascript
const planResult = await mcp.mcp_shrimp_task_manager.plan_task({
description:
"開發一個用戶註冊功能，包含表單驗證、數據存儲和電子郵件確認流程。",
requirements: "必須符合GDPR數據保護規定，支持多語言，並通過所有安全測試。",
});
```
### 2. 任務分析
#### `analyze_task`
深入分析任務需求並系統性檢查代碼庫，評估技術可行性與潛在風險。
**參數：**
| 參數名 | 類型 | 必填 | 描述 |
| ---------------- | ------ | ---- | ------------------------------------------------------------ |
| summary | string | 是 | 結構化的任務摘要，包含任務目標、範圍與關鍵技術挑戰 |
| initialConcept | string | 是 | 初步解答構想，包含技術方案、架構設計和實施策略 |
| previousAnalysis | string | 否 | 前次迭代的分析結果，用於持續改進方案（僅在重新分析時需提供） |
**返回：**
- 成功：返回詳細的任務分析結果
- 失敗：返回錯誤訊息，說明失敗原因
**使用範例：**
```javascript
const analysisResult = await mcp.mcp_shrimp_task_manager.analyze_task({
summary: "開發用戶身份驗證模塊，包含登入、註冊和密碼重設功能",
initialConcept: "計劃使用JWT進行身份驗證，實現無狀態API設計...",
});
```
### 3. 方案反思
#### `reflect_task`
批判性審查分析結果，評估方案完整性並識別優化機會，確保解決方案符合最佳實踐。
**參數：**
| 參數名 | 類型 | 必填 | 描述 |
| -------- | ------ | ---- | ------------------------------------------------------------ |
| summary | string | 是 | 結構化的任務摘要，保持與分析階段一致以確保連續性 |
| analysis | string | 是 | 完整詳盡的技術分析結果，包括所有技術細節、依賴組件和實施方案 |
**返回：**
- 成功：返回方案改進建議和優化機會
- 失敗：返回錯誤訊息，說明失敗原因
**使用範例：**
```javascript
const reflectionResult = await mcp.mcp_shrimp_task_manager.reflect_task({
summary: "開發用戶身份驗證模塊，包含登入、註冊和密碼重設功能",
analysis: "詳細的技術分析結果，包括JWT實現方式、安全考量等...",
});
```
### 4. 任務拆分
#### `split_tasks`
將複雜任務分解為獨立且可追蹤的子任務，建立明確的依賴關係和優先順序。
**參數：**
| 參數名 | 類型 | 必填 | 描述 |
| ----------- | ------- | ---- | --------------------------------------------------------------------------- |
| isOverwrite | boolean | 是 | 任務覆蓋模式選擇（true：清除並覆蓋所有現有任務；false：保留現有任務並新增） |
| tasks | array | 是 | 結構化的任務清單，每個任務應保持原子性且有明確的完成標準 |
**tasks 對象屬性：**
| 屬性名 | 類型 | 必填 | 描述 |
| ------------ | ------ | ---- | ------------------------------------------------ |
| name | string | 是 | 簡潔明確的任務名稱，應能清晰表達任務目的 |
| description | string | 是 | 詳細的任務描述，包含實施要點、技術細節和驗收標準 |
| notes | string | 否 | 補充說明、特殊處理要求或實施建議（選填） |
| dependencies | array | 否 | 此任務依賴的前置任務 ID 或任務名稱列表 |
**返回：**
- 成功：返回創建的任務列表
- 失敗：返回錯誤訊息，說明失敗原因
**使用範例：**
```javascript
const tasksResult = await mcp.mcp_shrimp_task_manager.split_tasks({
isOverwrite: false,
tasks: [
{
name: "設計用戶數據模型",
description: "定義用戶實體的數據結構和驗證規則...",
notes: "參考現有的權限模型",
dependencies: [],
},
{
name: "實現用戶註冊API",
description: "開發註冊端點，處理表單驗證和數據存儲...",
dependencies: ["設計用戶數據模型"],
},
],
});
```
### 5. 任務列表
#### `list_tasks`
生成結構化任務清單，包含完整狀態追蹤、優先級和依賴關係。
**參數：** 無
**返回：**
- 成功：返回系統中所有任務的結構化清單
- 失敗：返回錯誤訊息，說明失敗原因
**使用範例：**
```javascript
const tasksList = await mcp.mcp_shrimp_task_manager.list_tasks();
```
### 6. 任務執行
#### `execute_task`
按照預定義計劃執行特定任務，確保每個步驟的輸出符合質量標準。
**參數：**
| 參數名 | 類型 | 必填 | 描述 |
| ------ | ------ | ---- | ----------------------------------------------------- |
| taskId | string | 是 | 待執行任務的唯一標識符，必須是系統中存在的有效任務 ID |
**返回：**
- 成功：返回任務執行指南和上下文
- 失敗：返回錯誤訊息，說明失敗原因
**使用範例：**
```javascript
const executeResult = await mcp.mcp_shrimp_task_manager.execute_task({
taskId: "task-uuid-here",
});
```
### 7. 任務驗證
#### `verify_task`
全面驗證任務完成度，確保所有需求與技術標準都已滿足，並無遺漏細節。
**參數：**
| 參數名 | 類型 | 必填 | 描述 |
| ------ | ------ | ---- | ----------------------------------------------------- |
| taskId | string | 是 | 待驗證任務的唯一標識符，必須是系統中存在的有效任務 ID |
**返回：**
- 成功：返回任務驗證評估結果
- 失敗：返回錯誤訊息，說明失敗原因
**使用範例：**
```javascript
const verifyResult = await mcp.mcp_shrimp_task_manager.verify_task({
taskId: "task-uuid-here",
});
```
## 任務管理 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` 參數時，系統會根據任務名稱和描述自動生成摘要。
### 4. 清除所有任務功能
#### `clear_all_tasks`
清除系統中所有未完成的任務，提供簡化的系統重置功能。
**參數：**
| 參數名 | 類型 | 必填 | 描述 |
| ------- | ------- | ---- | ------------------------- |
| confirm | boolean | 是 | 確認刪除操作，必須為 true |
**返回：**
- 成功：返回清除操作的結果，包含被刪除的任務數量
- 失敗：返回錯誤訊息，說明失敗原因
**使用範例：**
```javascript
const clearResult = await mcp.mcp_shrimp_task_manager.clear_all_tasks({
confirm: true, // 必須明確確認
});
```
**安全機制：**
- 必須明確設置 `confirm` 參數為 `true` 才能執行操作
- 系統會自動在清除前創建數據備份，存放在 `data/backups` 目錄
- 所有清除操作都會記錄到系統日誌中
- 已完成的任務不會被刪除，確保歷史記錄完整性
### 5. 更新任務功能
#### `update_task`
更新未完成任務的內容，包括名稱、描述和注記。
**參數：**
| 參數名 | 類型 | 必填 | 描述 |
| ----------- | ------ | ---- | ------------------------------------------------- |
| taskId | string | 是 | 待更新任務的唯一標識符，必須是未完成的有效任務 ID |
| name | string | 否 | 任務的新名稱（選填） |
| description | string | 否 | 任務的新描述（選填） |
| notes | string | 否 | 任務的新補充說明（選填） |
**返回：**
- 成功：返回更新後的任務數據
- 失敗：返回錯誤訊息，說明失敗原因（如任務不存在、已完成等）
**使用範例：**
```javascript
const updateResult = await mcp.mcp_shrimp_task_manager.update_task({
taskId: "task-uuid-here",
name: "優化後的任務名稱",
description: "更詳細的任務描述...",
notes: "補充重要資訊",
});
```
**約束條件：**
- 不允許更新已完成的任務
- 至少需要提供 name、description 或 notes 中的一個參數
- 任務 ID 和完成狀態不可通過此功能更改
### 6. 任務相關文件位置記錄功能
#### `update_task_files`
為任務添加或更新相關文件記錄，提升任務執行時的上下文記憶能力。
**參數：**
| 參數名 | 類型 | 必填 | 描述 |
| ------------ | ------ | ---- | ------------------------------------ |
| taskId | string | 是 | 任務的唯一標識符 |
| relatedFiles | array | 是 | 相關文件列表，包含以下屬性的對象數組 |
**relatedFiles 對象屬性：**
| 屬性名 | 類型 | 必填 | 描述 |
| ----------- | ------ | ---- | ------------------------------------------------------------------------------------ |
| path | string | 是 | 文件路徑（相對於項目根目錄或絕對路徑） |
| type | string | 是 | 文件關聯類型，可選值：「待修改」、「參考資料」、「輸出結果」、「依賴文件」、「其他」 |
| description | string | 否 | 文件的補充描述（選填） |
| lineStart | number | 否 | 相關代碼區塊的起始行（選填） |
| lineEnd | number | 否 | 相關代碼區塊的結束行（選填） |
**返回：**
- 成功：返回更新後的任務數據，包含完整的相關文件列表
- 失敗：返回錯誤訊息
**使用範例：**
```javascript
const updateFilesResult = await mcp.mcp_shrimp_task_manager.update_task_files({
taskId: "task-uuid-here",
relatedFiles: [
{
path: "src/components/Button.tsx",
type: "待修改",
description: "需要修改按鈕組件以支持新狀態",
lineStart: 24,
lineEnd: 45,
},
{
path: "docs/design-spec.md",
type: "參考資料",
description: "包含按鈕設計規範",
},
],
});
```
## 工作日誌功能
### 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, // 必填，確認刪除操作
});
```
## 實用工具函數
### 1. 任務相關文件摘要生成
#### `loadTaskRelatedFiles`
生成任務相關文件的內容摘要，基於文件元數據創建格式化的摘要信息，而不實際讀取檔案內容。
**參數：**
| 參數名 | 類型 | 必填 | 描述 |
| -------------- | ------------- | ---- | ----------------------------------------------------------------------------------------- |
| relatedFiles | RelatedFile[] | 是 | 相關文件列表 - RelatedFile 物件數組，包含文件的路徑、類型、描述等資訊 |
| maxTotalLength | number | 否 | 摘要內容的最大總長度 - 控制生成摘要的總字符數，避免過大的返回內容，預設值為 15000（選填） |
**RelatedFile 物件屬性：**
| 屬性名 | 類型 | 必填 | 描述 |
| ----------- | --------------- | ---- | --------------------------------------------------------------------------------------------------------------------------- |
| path | string | 是 | 文件路徑（相對於項目根目錄或絕對路徑） |
| type | RelatedFileType | 是 | 文件關聯類型，可選值：TO_MODIFY（待修改）、REFERENCE（參考資料）、DEPENDENCY（依賴文件）、OUTPUT（輸出結果）、OTHER（其他） |
| description | string | 否 | 文件的補充描述（選填） |
| lineStart | number | 否 | 相關代碼區塊的起始行（選填） |
| lineEnd | number | 否 | 相關代碼區塊的結束行（選填） |
**返回：**
- 返回一個包含兩個屬性的物件：
- `content`: 詳細的文件資訊，包含每個檔案的基本資訊和提示訊息
- `summary`: 簡潔的檔案列表概覽，適合快速瀏覽
**使用範例：**
```typescript
import { loadTaskRelatedFiles } from "../utils/fileLoader.js";
import { RelatedFile, RelatedFileType } from "../types/index.js";
// 定義相關文件列表
const relatedFiles: RelatedFile[] = [
{
path: "src/components/Button.tsx",
type: RelatedFileType.TO_MODIFY,
description: "需要修改按鈕組件以支持新狀態",
lineStart: 24,
lineEnd: 45,
},
{
path: "docs/design-spec.md",
type: RelatedFileType.REFERENCE,
description: "包含按鈕設計規範",
},
];
// 生成文件摘要
const result = await loadTaskRelatedFiles(relatedFiles, 10000);
console.log(result.summary); // 顯示簡潔的摘要
console.log(result.content); // 顯示詳細的內容
```
**重要說明：**
- 此函數不會實際讀取檔案內容，僅基於提供的文件元數據生成摘要信息
- 返回的摘要按文件類型優先級排序，優先處理待修改的文件
- 當摘要總長度超過 maxTotalLength 參數時，會停止處理剩餘文件並添加說明
- 摘要內容包括文件路徑、類型、描述和行範圍等基本信息

387
docs/architecture.md
View File

@ -49,12 +49,22 @@
工具註冊層負責將各功能工具註冊到 MCP 系統中，使其能夠被 LLM 訪問和使用。
**新增功能**：
**主要功能**：
- 註冊 `delete_task` 工具函數，允許刪除未完成的任務
- 註冊 `clear_all_tasks` 工具函數，允許清除所有未完成的任務
- 註冊 `update_task` 工具函數，允許更新未完成任務的內容
- 註冊 `update_task_files` 工具函數，允許更新任務相關文件列表
- 註冊 `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)
@ -64,17 +74,24 @@
- `taskTools.ts`: 任務管理相關工具
- `logTools.ts`: 日誌管理相關工具
- `fileLoader.ts`: 任務相關文件的摘要生成工具（新增）
- `fileLoader.ts`: 任務相關文件的摘要生成工具
**新增功能**：
**主要功能**：
- 在 `taskTools.ts` 中新增 `deleteTask` 工具函數和 schema
- 在 `taskTools.ts` 中新增 `clearAllTasks` 工具函數和 schema，實現安全的任務清除
- 在 `taskTools.ts` 中新增 `updateTaskContent` 工具函數和 schema，支持任務內容更新
- 在 `taskTools.ts` 中新增 `updateTaskRelatedFiles` 工具函數和 schema，支持文件關聯管理
- 在 `executeTask` 中集成任務複雜度檢查邏輯
- 在 `executeTask` 中增強上下文記憶功能，自動加載相關文件
- 在 `completeTask` 中增強摘要處理功能
- 實現 `planTask` 工具函數，初始化並詳細規劃任務流程
- 實現 `analyzeTask` 工具函數，深入分析任務需求
- 實現 `reflectTask` 工具函數，批判性審查分析結果
- 實現 `splitTasks` 工具函數，將複雜任務分解為獨立且可追蹤的子任務
- 實現 `listTasks` 工具函數，生成結構化任務清單
- 實現 `executeTask` 工具函數，按照預定義計劃執行特定任務
- 實現 `verifyTask` 工具函數，全面驗證任務完成度
- 實現 `completeTask` 工具函數，正式標記任務為完成狀態
- 實現 `deleteTask` 工具函數，刪除未完成的任務
- 實現 `clearAllTasks` 工具函數，刪除所有未完成的任務
- 實現 `updateTask` 工具函數，更新任務內容
- 實現 `updateTaskRelatedFiles` 工具函數，更新任務相關文件列表
- 實現 `listConversationLog` 工具函數，查詢系統對話日誌
- 實現 `clearConversationLog` 工具函數，清除所有對話日誌記錄
### 2.3 模型邏輯層 (models/\*.ts)
@ -85,26 +102,34 @@
- `taskModel.ts`: 任務數據模型和操作
- `conversationLogModel.ts`: 對話日誌數據模型和操作
**新增功能**：
**主要功能**：
- 在 `taskModel.ts` 中實現 `deleteTask` 函數
- 在 `taskModel.ts` 中實現 `clearAllTasks` 函數，包含備份和安全檢查機制
- 在 `taskModel.ts` 中擴展 `updateTask` 函數，增加對已完成任務的檢查邏輯
- 在 `taskModel.ts` 中新增 `updateTaskContent` 和 `updateTaskRelatedFiles` 函數
- 增加 `assessTaskComplexity` 函數評估任務複雜度
- 實現 `updateTaskSummary` 函數更新任務摘要
- 在 `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)
定義系統中使用的所有數據類型和接口。
**新增類型**：
**主要類型**：
- `TaskComplexityLevel` 枚舉：定義任務複雜度級別
- `TaskStatus` 枚舉：定義任務狀態，包括待處理、進行中、已完成和被阻擋
- `TaskDependency` 接口：定義任務依賴關係
- `RelatedFileType` 枚舉：定義文件關聯類型，如待修改、參考資料、輸出結果、依賴文件和其他
- `RelatedFile` 接口：定義任務相關文件結構
- `Task` 接口：定義任務的完整數據結構
- `ConversationParticipant` 枚舉：定義對話參與者類型，如 MCP 和 LLM
- `ConversationEntry` 接口：定義對話日誌條目
- `TaskComplexityLevel` 枚舉：定義任務複雜度級別，如低複雜度、中等複雜度、高複雜度和極高複雜度
- `TaskComplexityThresholds` 常量：定義複雜度評估閾值
- `TaskComplexityAssessment` 接口：記錄複雜度評估結果
- `RelatedFile` 接口：定義任務相關文件結構
- `RelatedFileType` 枚舉：定義文件關聯類型（待修改、參考資料等）
### 2.5 工具函數 (utils/\*.ts)
@ -113,15 +138,16 @@
**核心文件**：
- `summaryExtractor.ts`: 實現摘要提取和生成功能
- `fileLoader.ts`: 實現任務相關文件的摘要生成功能（新增）
- `contextManager.ts`: 管理上下文記憶和優化（新增）
- `fileLoader.ts`: 實現任務相關文件的摘要生成功能
**新增功能**：
**主要功能**：
- 增強 `generateTaskSummary` 函數實現自動摘要生成
- 實現 `loadTaskRelatedFiles` 函數，生成任務相關文件的摘要
- 簡化 `extractRelevantCodeBlocks` 函數，生成代碼的位置和描述摘要
- 實現 `optimizeContext` 函數，優化上下文表示和壓縮
- 實現 `extractSummary` 函數，從文本中提取簡短摘要
- 實現 `generateTaskSummary` 函數，基於任務名稱和描述生成任務完成摘要
- 實現 `extractTitle` 函數，從內容中提取適合作為標題的文本
- 實現 `extractSummaryFromConversation` 函數，從對話記錄中提取摘要信息
- 實現 `loadTaskRelatedFiles` 函數，生成任務相關文件的內容摘要
- 實現 `generateFileInfo` 函數，生成文件基本資訊摘要
### 2.6 數據存儲層
@ -131,7 +157,7 @@
- `data/tasks.json`: 存儲所有任務數據
- `data/conversation_log.json`: 存儲對話日誌數據
- `data/backups/`: 存儲任務數據備份（新增）
- `data/backups/`: 存儲任務數據備份
## 3. 數據流
@ -176,6 +202,8 @@ LLM 調用 execute_task
| |
+------------> 計算注記長度
| |
+------------> 檢查是否有注記
| |
v v
確定複雜度級別 <----- 應用評估閾值
|
@ -189,7 +217,7 @@ LLM 調用 execute_task
返回增強後的任務執行提示給 LLM
```
### 3.3 任務摘要更新流程
### 3.3 任務完成流程
```
LLM 調用 complete_task
@ -280,7 +308,7 @@ LLM 調用 update_task
記錄操作到日誌
|
v
返回更新後的任務信息給 LLM
返回更新結果給 LLM
```
### 3.6 更新任務相關文件流程
@ -295,6 +323,9 @@ LLM 調用 update_task_files
檢查任務是否存在
|
v
檢查任務狀態（阻止更新已完成任務）
|
v
驗證文件列表格式
|
v
@ -313,40 +344,52 @@ LLM 調用 update_task_files
記錄操作到日誌
|
v
返回更新後的任務信息給 LLM
返回更新結果給 LLM
```
### 3.7 上下文記憶加載流程
### 3.7 文件處理流程
```
執行任務前預處理
處理任務相關文件
|
v
檢查任務相關文件列表
|
v
按優先級排序文件
根據文件類型進行優先級排序
| |
| +---> 待修改 > 參考資料 > 依賴文件 > 輸出結果 > 其他
|
v
生成文件摘要
| |
| +---> 對於指定行號範圍的文件，生成該範圍的摘要
| |
| +---> 對於大型文件，生成關鍵內容的摘要描述
| +---> 對於一般文件，生成整體內容摘要
|
v
返回文件摘要結果
```
### 3.8 對話日誌查詢流程
```
LLM 調用 list_conversation_log
|
v
處理過濾參數
| |
| +---> 對於文檔文件，生成整體內容摘要
| +---> 任務ID過濾（如有提供）
| |
| +---> 日期範圍過濾（如有提供）
| |
| +---> 應用分頁參數（limit和offset）
|
v
加載依賴任務的摘要
查詢符合條件的日誌條目
|
v
加載任務執行歷史記錄
格式化日誌條目列表
|
v
優化上下文表示
|
v
將增強的上下文注入任務執行環境
返回查詢結果給 LLM
```
## 4. 系統交互圖
@ -377,117 +420,147 @@ LLM 調用 update_task_files
+-------------+ 返回結果 +-------------+ 返回數據 +------------+
```
## 5. 新增功能架構圖
## 5. 核心功能架構圖
### 5.1 刪除任務功能
```
+----------------+ +----------------+ +---------------+
| | | | | |
| deleteTaskSchema|---->| deleteTask |---->| modelDeleteTask|
| | | (taskTools.ts) | | (taskModel.ts)|
+----------------+ +------+---------+ +-------+-------+
| |
v v
+------+------------------------+------+
| 檢查任務狀態和依賴關係 |
+------+------------------------+------+
|
v
+------+------------------------+------+
| 記錄操作到日誌 |
+------+------------------------+------+
```
### 5.2 任務複雜度自適應處理
### 5.1 任務規劃功能
```
+----------------+ +----------------+ +------------------+
| | | | | |
| executeTask |---->| 複雜度評估調用 |---->| assessTaskComplexity|
| (taskTools.ts) | | | | (taskModel.ts) |
+----------------+ +-------+--------+ +-------+----------+
| |
v v
+------+---------------------+------+
| 應用複雜度評估閾值和指標 |
+------+---------------------+------+
| 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.3 任務摘要自動更新機制
### 5.6 任務驗證功能
```
+-----------------+ +----------------+ +-------------------+
| | | | | |
| completeTask |---->| 摘要處理邏輯 |---->| updateTaskSummary |
| (taskTools.ts) | | | | (taskModel.ts) |
+-----------------+ +-------+--------+ +---------+---------+
| |
v |
+------+--------+ |
| summaryExtractor| |
| (utils) |<--------------+
+---------------+
+----------------+ +----------------+ +------------------+
| | | | | |
| verifyTaskSchema|---->| verifyTask |---->| 任務驗證評估 |
| | | (taskTools.ts) | | |
+----------------+ +-------+--------+ +------------------+
```
### 5.4 清除所有任務功能
### 5.7 完成任務功能
```
+------------------+ +----------------+ +-------------------+
| | | | | |
| clearAllTasksSchema |---->| clearAllTasks |---->| modelClearAllTasks |
| | | (taskTools.ts) | | (taskModel.ts) |
+------------------+ +-------+--------+ +---------+---------+
| |
v v
+----------------+ +----------------+ +------------------+
| | | | | |
| 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.5 更新任務功能
```
+------------------+ +----------------+ +-------------------+
| | | | | |
| updateTaskSchema |---->| updateTaskContent |---->| updateTask |
| | | (taskTools.ts) | | (taskModel.ts) |
+------------------+ +-------+--------+ +---------+---------+
| |
v v
+------+---------------------+------+
| 檢查任務狀態和更新參數有效性 |
+------+---------------------+------+
|
v
+------+---------------------+------+
| 應用更新和記錄操作 |
+------+---------------------+------+
```
### 5.6 任務相關文件位置記錄功能
### 5.11 更新任務相關文件功能
```
+----------------------+ +---------------------+ +---------------------+
| | | | | |
+----------------------+ +---------------------+ +----------------------+
| | | | | |
| updateTaskFilesSchema |---->| updateTaskRelatedFiles |---->| updateTaskRelatedFiles |
| | | (taskTools.ts) | | (taskModel.ts) |
+----------------------+ +-----------+---------+ +-----------+---------+
| | | (taskTools.ts) | | (taskModel.ts) |
+----------------------+ +-----------+---------+ +-----------+----------+
| |
v v
+-------+-------------------------+------+
@ -500,29 +573,34 @@ LLM 調用 update_task_files
+-------+-------------------------+------+
```
### 5.7 上下文記憶優化功能
### 5.12 日誌查詢功能
```
+---------------+ +-------------------+ +------------------+
| | | | | |
| executeTask |---->| loadTaskContext |---->| loadRelatedFiles |
| (taskTools.ts)| | (contextManager.ts) | | (fileLoader.ts) |
+---------------+ +--------+----------+ +--------+---------+
| |
v v
+-------+------------------------+-----+
| 文件優先級排序和摘要生成 |
+-------+------------------------+-----+
|
v
+-------+------------------------+-----+
| 上下文優化和大小控制 |
+-------+------------------------+-----+
|
v
+-------+------------------------+-----+
| 歷史記錄和依賴任務摘要整合 |
+-------+------------------------+-----+
+------------------------+ +-------------------+ +---------------------+
| | | | | |
| listConversationLogSchema|---->| listConversationLog|---->| getConversationLogs |
| | | (logTools.ts) | | (logModel.ts) |
+------------------------+ +---------+---------+ +---------+-----------+
| |
v v
+-------+------------------------+-----+
| 過濾參數處理和分頁控制 |
+-------+------------------------+-----+
```
### 5.13 清除日誌功能
```
+-------------------------+ +--------------------+ +------------------------+
| | | | | |
| clearConversationLogSchema|---->| clearConversationLog|---->| clearConversationLogs |
| | | (logTools.ts) | | (logModel.ts) |
+-------------------------+ +---------+----------+ +----------+-------------+
| |
v v
+-------+-------------------------+-----+
| 確認參數檢查和刪除操作 |
+-------+-------------------------+-----+
```
## 6. 擴展性考慮
@ -543,8 +621,8 @@ LLM 調用 update_task_files
- **任務處理流程擴展**：可通過修改 `executeTask`、`verifyTask` 等函數擴展任務處理流程
- **複雜度評估擴展**：可在 `assessTaskComplexity` 中添加更多評估指標
- **摘要生成擴展**：可增強 `summaryExtractor.ts` 中的算法
- **上下文管理擴展**：可在 `contextManager.ts` 中添加更多上下文優化策略
- **摘要生成擴展**：可在 `fileLoader.ts` 中支持更多文件類型的摘要格式化
- **文件處理擴展**：可在 `fileLoader.ts` 中支持更多文件類型的摘要格式化
- **過濾條件擴展**：可在日誌查詢中添加更多過濾條件選項
## 7. 系統限制與未來改進
@ -553,20 +631,23 @@ LLM 調用 update_task_files
- 使用文件存儲，不適合多用戶並發場景
- 缺乏用戶認證和權限控制
- 摘要生成使用簡單規則，可進一步改進
- 上下文大小有限，需要更智能的壓縮和優先級機制
- 文件處理不讀取實際文件內容，僅生成摘要信息
### 7.2 未來可能的改進
- 遷移到數據庫存儲，提高並發處理能力
- 添加用戶管理和訪問控制
- 使用機器學習模型優化摘要生成和上下文管理
- 使用更先進的算法優化摘要生成
- 添加任務優先級和時間規劃功能
- 實現任務執行進度追蹤
- 增強文件關聯系統，支持更複雜的關係類型
- 實現自動識別相關文件的能力
- 支持實際讀取文件內容，提供更詳細的上下文
## 8. 結論
蝦米任務管理器採用模塊化、分層設計，使系統具有良好的可維護性和擴展性。新增的清除所有任務功能、更新任務功能、任務相關文件位置記錄功能和上下文記憶優化功能進一步增強了系統的功能性和用戶體驗，使其能夠更有效地管理複雜項目的任務流程，特別是在需要長期上下文記憶的場景中表現出色。
蝦米任務管理器採用模塊化、分層設計，使系統具有良好的可維護性和擴展性。通過 14 個核心工具函數和完善的數據模型，系統能夠有效地管理複雜項目的任務流程，特別在需要長期上下文記憶的場景中表現出色。
系統的設計重點在於提供清晰的任務管理流程，同時增強 LLM 在執行任務時的上下文記憶能力，通過精確的文件關聯和智能上下文載入，有效解決了 LLM 在處理長期複雜任務時的記憶限制問題。
隨著系統的進一步發展，未來將著重改進數據存儲方式、優化摘要生成算法、增強文件處理能力和添加更多任務管理功能，使系統能夠應對更多複雜的任務管理場景。

792
docs/examples.md
View File

@ -1,792 +0,0 @@
# 蝦米任務管理器 - 示例代碼與使用案例
本文檔提供蝦米任務管理器各功能的詳細示例代碼和實際使用案例，幫助您更好地理解和應用這些功能。
## 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
// 1. 首先導出現有任務作為備份
const currentTasks = await mcp.mcp_shrimp_task_manager.list_tasks();
console.log("備份現有任務列表：", currentTasks);
// 2. 記錄已完成任務數量（這些任務不會被刪除）
const completedTasksMatch =
currentTasks.content[0].text.match(/已完成: (\d+) 個任務/);
const completedTasksCount = completedTasksMatch
? parseInt(completedTasksMatch[1])
: 0;
console.log(`已完成任務數量: ${completedTasksCount} (這些任務將被保留)`);
// 3. 執行清除操作（必須設置確認參數）
try {
const clearResult = await mcp.mcp_shrimp_task_manager.clear_all_tasks({
confirm: true, // 必須明確確認才能執行清除
});
console.log("清除結果:", clearResult);
// 4. 提取備份文件路徑信息
const backupPathMatch =
clearResult.content[0].text.match(/備份文件: (.*\.json)/);
const backupPath = backupPathMatch ? backupPathMatch[1] : "備份文件路徑未知";
console.log(`數據已備份到: ${backupPath}`);
} catch (error) {
console.error("清除操作失敗:", error);
}
// 5. 確認清除結果
const remainingTasks = await mcp.mcp_shrimp_task_manager.list_tasks();
console.log("清除後的任務列表:", remainingTasks);
// 6. 開始新的任務規劃
await mcp.mcp_shrimp_task_manager.plan_task({
description: "項目第二階段：優化用戶體驗並擴展功能",
requirements: "改進性能、美化界面、增加新功能模塊",
});
```
### 案例：測試環境重置
在進行系統測試後，需要將環境重置為初始狀態，同時保留已完成任務的歷史記錄。
#### 示例代碼：
```javascript
// 1. 查詢當前環境狀態
const beforeReset = await mcp.mcp_shrimp_task_manager.list_tasks();
console.log("重置前狀態:", beforeReset);
// 2. 記錄重要測試結果
const testResults = "測試發現3個UI問題，2個性能瓶頸，均已記錄到測試報告";
console.log(`測試結果摘要: ${testResults}`);
// 3. 執行環境重置
await mcp.mcp_shrimp_task_manager.clear_all_tasks({
confirm: true,
});
// 4. 確認重置結果
const afterReset = await mcp.mcp_shrimp_task_manager.list_tasks();
console.log("重置後狀態:", afterReset);
// 5. 記錄重置操作到系統日誌
await mcp.mcp_shrimp_task_manager.list_conversation_log({
limit: 1, // 只獲取最新的一條日誌
});
```
## 5. 更新任務功能案例
### 案例：調整任務範圍
在進行過程中發現任務需求有變化，需要調整任務描述和範圍。
#### 示例代碼：
```javascript
// 1. 獲取需要更新的任務ID
const taskList = await mcp.mcp_shrimp_task_manager.list_tasks();
const taskIdMatch = taskList.content[0].text.match(
/ID: `([^`]+)`.*名稱: "實現用戶註冊功能"/
);
const taskId = taskIdMatch ? taskIdMatch[1] : null;
if (!taskId) {
console.error("找不到目標任務");
return;
}
// 2. 更新任務內容
const updateResult = await mcp.mcp_shrimp_task_manager.update_task({
taskId,
name: "實現用戶註冊和驗證功能",
description:
"設計並實現用戶註冊流程，包括：\n1. 基本信息註冊\n2. 電子郵件驗證\n3. 手機號碼驗證\n4. 安全問題設置\n5. 初始偏好設定",
notes: "更新原因：產品團隊要求增加電子郵件和手機驗證步驟，提高帳戶安全性",
});
console.log("任務更新結果:", updateResult);
// 3. 通知團隊成員任務範圍變更
console.log("已通知團隊成員任務範圍已擴大，包含更多驗證步驟");
// 4. 記錄變更歷史
const changeLog = `
變更日期: ${new Date().toISOString()}
變更內容: 擴展任務範圍，增加郵件和手機驗證步驟
變更原因: 提高帳戶安全性
請求方: 產品團隊
`;
console.log("變更日誌:", changeLog);
```
### 案例：澄清任務描述
發現任務描述不夠清晰，開發人員需要更多細節以正確實現功能。
#### 示例代碼：
```javascript
// 1. 找到需要澄清的任務
const allTasks = await mcp.mcp_shrimp_task_manager.list_tasks();
const taskIdMatch = allTasks.content[0].text.match(
/ID: `([^`]+)`.*名稱: "優化數據庫查詢"/
);
const taskId = taskIdMatch ? taskIdMatch[1] : null;
if (!taskId) {
console.error("找不到目標任務");
return;
}
// 2. 添加更詳細的技術說明
await mcp.mcp_shrimp_task_manager.update_task({
taskId,
description:
"優化產品列表和用戶資料頁面的數據庫查詢性能，目標是將頁面載入時間從當前的2.5秒降低到1秒以內。技術要求：\n1. 分析並優化現有SQL查詢\n2. 添加適當的索引\n3. 實現查詢結果緩存\n4. 考慮使用數據庫讀寫分離\n5. 測量並報告性能改進",
notes:
"性能瓶頸主要出現在產品過濾和排序操作上，特別是當產品數量超過1000個時。可考慮使用Redis緩存熱門查詢結果。",
});
// 3. 複查更新後的任務描述
const updatedTask = await mcp.mcp_shrimp_task_manager.execute_task({
taskId,
});
console.log("已更新的任務詳情:", updatedTask);
```
## 6. 任務相關文件位置記錄功能案例
### 案例：記錄複雜重構任務的相關文件
在進行大型代碼重構時，需要記錄涉及的所有相關文件，以便更好地跟蹤和管理變更。
#### 示例代碼：
```javascript
// 1. 建立重構任務
await mcp.mcp_shrimp_task_manager.split_tasks({
isOverwrite: false,
tasks: [
{
name: "重構認證系統",
description:
"將現有的基於Session的認證系統重構為JWT令牌認證，提高系統擴展性和安全性",
notes: "重構過程中需確保向後兼容，不影響現有用戶",
},
],
});
// 2. 獲取新創建的任務ID
const taskList = await mcp.mcp_shrimp_task_manager.list_tasks();
const taskIdMatch = taskList.content[0].text.match(
/ID: `([^`]+)`.*名稱: "重構認證系統"/
);
const taskId = taskIdMatch ? taskIdMatch[1] : null;
if (!taskId) {
console.error("找不到重構任務");
return;
}
// 3. 記錄所有相關文件
await mcp.mcp_shrimp_task_manager.update_task_files({
taskId,
relatedFiles: [
// 需要修改的核心文件
{
path: "src/services/authService.js",
type: "待修改",
description: "認證服務核心邏輯，需將session邏輯替換為JWT",
lineStart: 24,
lineEnd: 156,
},
{
path: "src/middleware/auth.js",
type: "待修改",
description: "認證中間件，需更新驗證邏輯",
lineStart: 5,
lineEnd: 42,
},
{
path: "src/controllers/userController.js",
type: "待修改",
description: "用戶控制器，需更新登入和註銷邏輯",
lineStart: 78,
lineEnd: 142,
},
// 參考資料
{
path: "docs/auth-system-design.md",
type: "參考資料",
description: "認證系統設計文檔，包含JWT切換的要求和規範",
},
{
path: "package.json",
type: "參考資料",
description: "檢查已安裝的依賴，可能需要添加jsonwebtoken套件",
lineStart: 10,
lineEnd: 25,
},
// 依賴的組件
{
path: "src/utils/crypto.js",
type: "依賴文件",
description: "加密工具，JWT簽名將使用此模塊",
lineStart: 15,
lineEnd: 35,
},
// 需要創建的新文件
{
path: "src/config/jwt.js",
type: "輸出結果",
description: "新的JWT配置文件，需要創建",
},
{
path: "src/utils/tokenManager.js",
type: "輸出結果",
description: "新的令牌管理工具，處理JWT的創建、驗證和刷新",
},
],
});
// 4. 查看更新後的任務詳情
const taskWithFiles = await mcp.mcp_shrimp_task_manager.execute_task({
taskId,
});
console.log("帶有相關文件信息的任務:", taskWithFiles);
```
### 案例：記錄 Bug 修復相關的代碼文件
在處理複雜 Bug 時，記錄相關文件位置以便快速定位問題。
#### 示例代碼：
```javascript
// 1. 創建bug修復任務
await mcp.mcp_shrimp_task_manager.split_tasks({
isOverwrite: false,
tasks: [
{
name: "修復購物車計算錯誤",
description: "修復在添加多個相同產品到購物車時總價計算錯誤的問題",
notes:
"此問題只在特定情況下出現：當用戶添加同一產品超過10個且應用了折扣優惠",
},
],
});
// 2. 獲取新創建的任務ID
const taskList = await mcp.mcp_shrimp_task_manager.list_tasks();
const taskIdMatch = taskList.content[0].text.match(
/ID: `([^`]+)`.*名稱: "修復購物車計算錯誤"/
);
const taskId = taskIdMatch ? taskIdMatch[1] : null;
if (!taskId) {
console.error("找不到bug修復任務");
return;
}
// 3. 添加問題相關文件
await mcp.mcp_shrimp_task_manager.update_task_files({
taskId,
relatedFiles: [
// 包含錯誤代碼的文件
{
path: "src/services/cartService.js",
type: "待修改",
description: "購物車服務，計算總價的邏輯有誤",
lineStart: 87,
lineEnd: 104,
},
{
path: "src/utils/priceCalculator.js",
type: "待修改",
description: "價格計算工具，折扣邏輯實現有誤",
lineStart: 45,
lineEnd: 65,
},
// 測試用例
{
path: "tests/cart.test.js",
type: "參考資料",
description: "現有測試用例，需要擴展以覆蓋發現的錯誤場景",
lineStart: 120,
lineEnd: 150,
},
// 錯誤報告
{
path: "docs/bug-reports/cart-calculation-issue.md",
type: "參考資料",
description: "詳細的錯誤報告，包含用戶報告的具體場景和截圖",
},
],
});
// 4. 執行任務，自動加載相關文件
await mcp.mcp_shrimp_task_manager.execute_task({
taskId,
});
```
## 7. 優化任務執行時的上下文記憶功能案例
### 案例：處理跨多個文件的複雜任務
實現一個需要理解和修改多個相關文件的功能，利用增強的上下文記憶功能。
#### 示例代碼：
```javascript
// 1. 創建複雜任務
await mcp.mcp_shrimp_task_manager.split_tasks({
isOverwrite: false,
tasks: [
{
name: "實現多租戶數據隔離",
description:
"在現有系統中實現多租戶數據隔離功能，確保不同租戶的數據完全隔離，同時共享應用代碼和基礎設施",
notes: "這是一項複雜的架構變更，需要修改多個核心組件",
},
],
});
// 2. 獲取新創建的任務ID
const taskList = await mcp.mcp_shrimp_task_manager.list_tasks();
const taskIdMatch = taskList.content[0].text.match(
/ID: `([^`]+)`.*名稱: "實現多租戶數據隔離"/
);
const taskId = taskIdMatch ? taskIdMatch[1] : null;
if (!taskId) {
console.error("找不到多租戶任務");
return;
}
// 3. 關聯核心相關文件
await mcp.mcp_shrimp_task_manager.update_task_files({
taskId,
relatedFiles: [
// 數據庫連接和模型
{
path: "src/config/database.js",
type: "待修改",
description: "數據庫配置，需改為支持多租戶連接池",
lineStart: 10,
lineEnd: 45,
},
{
path: "src/models/baseModel.js",
type: "待修改",
description: "所有模型的基類，需添加租戶ID過濾",
lineStart: 5,
lineEnd: 50,
},
// 中間件和上下文
{
path: "src/middleware/tenantContext.js",
type: "輸出結果",
description: "需要創建的新租戶上下文中間件",
},
{
path: "src/utils/requestContext.js",
type: "待修改",
description: "請求上下文工具，需增加租戶信息傳遞",
lineStart: 15,
lineEnd: 40,
},
// 身份驗證相關
{
path: "src/services/authService.js",
type: "待修改",
description: "認證服務，需在令牌中包含租戶信息",
lineStart: 50,
lineEnd: 120,
},
],
});
// 4. 執行任務，系統會自動加載相關文件和上下文
const executionResult = await mcp.mcp_shrimp_task_manager.execute_task({
taskId,
});
// 5. 在任務執行過程中，發現需要更多相關文件，動態添加
await mcp.mcp_shrimp_task_manager.update_task_files({
taskId,
relatedFiles: [
// 新發現的相關文件
{
path: "src/services/userService.js",
type: "待修改",
description: "用戶服務也需更新以支持多租戶",
lineStart: 25,
lineEnd: 75,
},
{
path: "docs/architecture/multi-tenant-design.md",
type: "參考資料",
description: "多租戶架構設計文檔，提供實現指導",
},
],
});
// 6. 繼續執行任務，系統會結合新添加的文件和之前的上下文
await mcp.mcp_shrimp_task_manager.execute_task({
taskId,
});
// 7. 任務完成後，記錄完整的實現摘要
await mcp.mcp_shrimp_task_manager.complete_task({
taskId,
summary:
"成功實現多租戶數據隔離功能，採用了基於中間件的動態租戶識別和數據過濾方案。主要更改包括：(1)實現了租戶上下文中間件，自動從請求中提取租戶標識；(2)增強了數據庫連接池，支持租戶專用連接；(3)修改了基礎模型類，所有查詢自動應用租戶過濾；(4)更新了認證服務，在JWT令牌中包含租戶信息；(5)實現了請求間租戶上下文的傳遞機制。所有修改均經過單元測試和集成測試驗證，確保數據完全隔離且性能影響最小化。",
});
```
### 案例：長時間進行的開發任務
在需要多次中斷和恢復的長期開發任務中，利用上下文記憶功能保持連續性。
#### 示例代碼：
```javascript
// 假設我們有一個已經進行了一段時間的長期任務
const taskId = "existing-long-term-task-id";
// 1. 恢復到之前的工作狀態，系統會自動加載任務相關文件和執行歷史
const taskContext = await mcp.mcp_shrimp_task_manager.execute_task({
taskId,
});
console.log("恢復任務上下文:", taskContext);
// 2. 記錄新的發現和決策
const developmentLog = `
開發日誌 - ${new Date().toISOString()}
今天解決了用戶認證頁面的以下問題：
1. 修復了表單驗證錯誤信息不顯示的問題
2. 優化了密碼強度檢查算法
3. 決定使用漸進式登入延遲策略防止暴力破解
待解決問題：
- OAuth提供商回調處理邏輯複雜，需要重構
- 移動端視圖適配問題
`;
console.log(developmentLog);
// 3. 更新任務相關文件，記錄今天處理的內容
await mcp.mcp_shrimp_task_manager.update_task_files({
taskId,
relatedFiles: [
// 今天修改的文件
{
path: "src/components/LoginForm.jsx",
type: "待修改",
description: "登入表單組件，已修復驗證錯誤顯示問題",
lineStart: 45,
lineEnd: 95,
},
{
path: "src/utils/passwordStrength.js",
type: "待修改",
description: "密碼強度檢查工具，已優化算法",
lineStart: 10,
lineEnd: 50,
},
{
path: "src/middleware/rateLimit.js",
type: "待修改",
description: "添加了漸進式登入延遲功能",
lineStart: 25,
lineEnd: 65,
},
// 明天需要處理的文件
{
path: "src/services/oauthService.js",
type: "待修改",
description: "OAuth服務需要重構，明天處理",
lineStart: 80,
lineEnd: 180,
},
{
path: "src/styles/mobile.css",
type: "待修改",
description: "需要改進移動端樣式適配",
lineStart: 120,
lineEnd: 200,
},
],
});
// 4. 更新任務注記，記錄進度和計劃
await mcp.mcp_shrimp_task_manager.update_task({
taskId,
notes:
"已完成認證頁面的基本功能和安全增強。下一步將重構OAuth服務並改進移動端適配。預計還需3天完成所有計劃工作。",
});
```
## 結論
以上示例展示了蝦米任務管理器在不同場景下的使用方法。通過這些具體案例，您可以了解如何：
1. 使用刪除任務功能維護任務列表的整潔和準確性
2. 利用任務複雜度自適應處理功能合理規劃和分解複雜任務
3. 通過任務摘要自動更新機制記錄關鍵實施細節和決策
4. 使用工作日誌功能追蹤項目進展和關鍵決策點
這些功能共同提供了一個強大的任務管理框架，幫助您更有效地規劃、執行和監控項目。

318
docs/functionality-checklist.md Normal file
View File

@ -0,0 +1,318 @@
# 蝦米任務管理器 - 功能實現清單
本文檔列出蝦米任務管理器系統中所有實際實現的工具函數、參數結構和功能。此清單作為文檔審查的基準參考。
## 類型定義與枚舉
### 任務狀態枚舉 (TaskStatus)
- `PENDING = "待處理"` - 已創建但尚未開始執行的任務
- `IN_PROGRESS = "進行中"` - 當前正在執行的任務
- `COMPLETED = "已完成"` - 已成功完成並通過驗證的任務
- `BLOCKED = "被阻擋"` - 由於依賴關係而暫時無法執行的任務
### 任務依賴關係 (TaskDependency)
- `taskId: string` - 前置任務的唯一標識符，當前任務執行前必須完成此依賴任務
### 相關文件類型枚舉 (RelatedFileType)
- `TO_MODIFY = "待修改"` - 需要在任務中修改的文件
- `REFERENCE = "參考資料"` - 任務的參考資料或相關文檔
- `OUTPUT = "輸出結果"` - 任務產生的輸出文件
- `DEPENDENCY = "依賴文件"` - 任務依賴的組件或庫文件
- `OTHER = "其他"` - 其他類型的相關文件
### 相關文件 (RelatedFile)
- `path: string` - 文件路徑，可以是相對於項目根目錄的路徑或絕對路徑
- `type: RelatedFileType` - 文件與任務的關係類型
- `description?: string` - 文件的補充描述，說明其與任務的具體關係或用途
- `lineStart?: number` - 相關代碼區塊的起始行（選填）
- `lineEnd?: number` - 相關代碼區塊的結束行（選填）
### 任務介面 (Task)
- `id: string` - 任務的唯一標識符
- `name: string` - 簡潔明確的任務名稱
- `description: string` - 詳細的任務描述，包含實施要點和驗收標準
- `notes?: string` - 補充說明、特殊處理要求或實施建議（選填）
- `status: TaskStatus` - 任務當前的執行狀態
- `dependencies: TaskDependency[]` - 任務的前置依賴關係列表
- `createdAt: Date` - 任務創建的時間戳
- `updatedAt: Date` - 任務最後更新的時間戳
- `completedAt?: Date` - 任務完成的時間戳（僅適用於已完成的任務）
- `summary?: string` - 任務完成摘要，簡潔描述實施結果和重要決策（僅適用於已完成的任務）
- `relatedFiles?: RelatedFile[]` - 與任務相關的文件列表（選填）
### 對話參與者類型枚舉 (ConversationParticipant)
- `MCP = "MCP"` - 系統方（MCP）
- `LLM = "LLM"` - 模型方（LLM）
### 對話日誌條目 (ConversationEntry)
- `id: string` - 日誌條目的唯一標識符
- `timestamp: Date` - 記錄的時間戳
- `participant: ConversationParticipant` - 對話參與者（MCP 或 LLM）
- `summary: string` - 消息摘要，只記錄關鍵信息點而非完整對話
- `relatedTaskId?: string` - 關聯的任務 ID（選填），用於將對話與特定任務關聯
- `context?: string` - 額外的上下文信息（選填），提供對話發生的背景
### 任務複雜度級別枚舉 (TaskComplexityLevel)
- `LOW = "低複雜度"` - 簡單且直接的任務，通常不需要特殊處理
- `MEDIUM = "中等複雜度"` - 具有一定複雜性但仍可管理的任務
- `HIGH = "高複雜度"` - 複雜且耗時的任務，需要特別關注
- `VERY_HIGH = "極高複雜度"` - 極其複雜的任務，建議拆分處理
### 任務複雜度評估結果 (TaskComplexityAssessment)
- `level: TaskComplexityLevel` - 整體複雜度級別
- `metrics: object` - 各項評估指標的詳細數據
- `descriptionLength: number` - 描述長度
- `dependenciesCount: number` - 依賴數量
- `notesLength: number` - 注記長度
- `hasNotes: boolean` - 是否有注記
- `recommendations: string[]` - 處理建議列表
## 工具函數與參數
### 1. plan_task
**描述**：初始化並詳細規劃任務流程，建立明確的目標與成功標準
**參數**：
- `description: string` (必填) - 完整詳細的任務問題描述，應包含任務目標、背景及預期成果
- 必須至少 10 個字符
- `requirements?: string` (選填) - 任務的特定技術要求、業務約束條件或品質標準
**返回值**：
- 返回一個包含規劃提示的響應，用於引導用戶開始任務分析
### 2. analyze_task
**描述**：深入分析任務需求並系統性檢查代碼庫，評估技術可行性與潛在風險
**參數**：
- `summary: string` (必填) - 結構化的任務摘要，包含任務目標、範圍與關鍵技術挑戰
- 必須至少 20 個字符
- `initialConcept: string` (必填) - 初步解答構想，包含技術方案、架構設計和實施策略
- 必須至少 50 個字符
- `previousAnalysis?: string` (選填) - 前次迭代的分析結果，用於持續改進方案
**返回值**：
- 返回一個包含技術分析指引的響應，用於指導用戶進行深入分析
### 3. reflect_task
**描述**：批判性審查分析結果，評估方案完整性並識別優化機會，確保解決方案符合最佳實踐
**參數**：
- `summary: string` (必填) - 結構化的任務摘要，保持與分析階段一致以確保連續性
- 必須至少 20 個字符
- `analysis: string` (必填) - 完整詳盡的技術分析結果，包括所有技術細節、依賴組件和實施方案
- 必須至少 100 個字符
**返回值**：
- 返回一個包含反思提示與實施建議的響應
### 4. split_tasks
**描述**：將複雜任務分解為獨立且可追蹤的子任務，建立明確的依賴關係和優先順序
**參數**：
- `isOverwrite: boolean` (必填) - 任務覆蓋模式選擇（true：清除並覆蓋所有現有任務；false：保留現有任務並新增）
- `tasks: Array<object>` (必填) - 結構化的任務清單，每個任務應保持原子性且有明確的完成標準
- `name: string` (必填) - 簡潔明確的任務名稱，應能清晰表達任務目的
- 不超過 100 個字符
- `description: string` (必填) - 詳細的任務描述，包含實施要點、技術細節和驗收標準
- 必須至少 10 個字符
- `notes?: string` (選填) - 補充說明、特殊處理要求或實施建議
- `dependencies?: string[]` (選填) - 此任務依賴的前置任務 ID 或任務名稱列表
- `relatedFiles?: RelatedFile[]` (選填) - 與任務相關的文件列表
**返回值**：
- 返回一個包含任務拆分結果的響應，包括成功創建的任務數量和任務 ID 列表
### 5. list_tasks
**描述**：生成結構化任務清單，包含完整狀態追蹤、優先級和依賴關係
**參數**：無
**返回值**：
- 返回一個包含任務清單的響應，按狀態分組顯示所有任務
### 6. execute_task
**描述**：按照預定義計劃執行特定任務，確保每個步驟的輸出符合質量標準
**參數**：
- `taskId: string` (必填) - 待執行任務的唯一標識符，必須是系統中存在的有效任務 ID
**返回值**：
- 返回一個包含任務執行指南的響應，包括任務詳情、複雜度評估和執行步驟建議
### 7. verify_task
**描述**：全面驗證任務完成度，確保所有需求與技術標準都已滿足，並無遺漏細節
**參數**：
- `taskId: string` (必填) - 待驗證任務的唯一標識符，必須是系統中存在的有效任務 ID
**返回值**：
- 返回一個包含任務驗證結果的響應，包括完成標準檢查和具體驗證項
### 8. complete_task
**描述**：正式標記任務為完成狀態，生成詳細的完成報告，並更新關聯任務的依賴狀態
**參數**：
- `taskId: string` (必填) - 待完成任務的唯一標識符，必須是系統中存在的有效任務 ID
- `summary?: string` (選填) - 任務完成摘要，簡潔描述實施結果和重要決策
**返回值**：
- 返回一個包含任務完成確認的響應，包括完成時間和更新的依賴任務狀態
### 9. delete_task
**描述**：刪除未完成的任務，但不允許刪除已完成的任務，確保系統記錄的完整性
**參數**：
- `taskId: string` (必填) - 待刪除任務的唯一標識符，必須是系統中存在且未完成的任務 ID
**返回值**：
- 返回一個包含任務刪除結果的響應，包括成功或失敗的訊息
### 10. clear_all_tasks
**描述**：刪除系統中所有未完成的任務，該指令必須由用戶明確確認才能執行
**參數**：
- `confirm: boolean` (必填) - 確認刪除所有未完成的任務（此操作不可逆）
**返回值**：
- 返回一個包含清除操作結果的響應，包括成功或失敗的訊息
### 11. update_task
**描述**：更新任務內容，包括名稱、描述和注記，但不允許修改已完成的任務
**參數**：
- `taskId: string` (必填) - 待更新任務的唯一標識符，必須是系統中存在且未完成的任務 ID
- `name?: string` (選填) - 任務的新名稱
- `description?: string` (選填) - 任務的新描述內容
- `notes?: string` (選填) - 任務的新補充說明
**返回值**：
- 返回一個包含任務更新結果的響應，包括成功或失敗的訊息
### 12. update_task_files
**描述**：更新任務相關文件列表，用於記錄與任務相關的代碼文件、參考資料等
**參數**：
- `taskId: string` (必填) - 待更新任務的唯一標識符，必須是系統中存在且未完成的任務 ID
- `relatedFiles: Array<RelatedFile>` (必填) - 與任務相關的文件列表
- `path: string` (必填) - 文件路徑，可以是相對於項目根目錄的路徑或絕對路徑
- `type: RelatedFileType` (必填) - 文件與任務的關係類型
- `description?: string` (選填) - 文件的補充描述
- `lineStart?: number` (選填) - 相關代碼區塊的起始行
- `lineEnd?: number` (選填) - 相關代碼區塊的結束行
**返回值**：
- 返回一個包含文件更新結果的響應，包括成功或失敗的訊息
### 13. list_conversation_log
**描述**：查詢系統對話日誌，支持按任務 ID 或時間範圍過濾，提供分頁功能處理大量記錄
**參數**：
- `taskId?: string` (選填) - 按任務 ID 過濾對話記錄
- `startDate?: string` (選填) - 起始日期過濾，格式為 ISO 日期字串
- `endDate?: string` (選填) - 結束日期過濾，格式為 ISO 日期字串
- `limit?: number` (選填，預設 20) - 返回結果數量限制，最大 100
- `offset?: number` (選填，預設 0) - 分頁偏移量
**返回值**：
- 返回一個包含對話日誌查詢結果的響應，包括日誌條目列表及分頁信息
### 14. clear_conversation_log
**描述**：清除所有對話日誌記錄，需要明確確認以避免意外操作
**參數**：
- `confirm: boolean` (必填) - 確認刪除所有日誌記錄（此操作不可逆）
**返回值**：
- 返回一個包含清除操作結果的響應，包括成功或失敗的訊息
## 工具函數重要細節
### 依賴關係 (dependencies) 處理
- 在 `splitTasks` 和其他函數中，`dependencies` 參數允許接受任務名稱或任務 ID(UUID)
- 系統會在任務創建或更新時將字串陣列轉換為 `TaskDependency` 物件陣列
- 任務依賴關係形成有向無環圖(DAG)，用於確定任務執行順序和阻塞狀態
### 任務複雜度評估
- 系統使用 `assessTaskComplexity` 函數評估任務的複雜度
- 評估基於多個指標：描述長度、依賴數量、注記長度等
- 根據 `TaskComplexityThresholds` 定義的閾值來判定複雜度級別
- 複雜度評估結果用於生成適當的處理建議
### 文件處理功能
- `loadTaskRelatedFiles` 函數不實際讀取檔案內容，僅生成文件資訊摘要
- 文件按類型優先級排序：待修改 > 參考資料 > 依賴文件 > 輸出結果 > 其他
- 支持指定代碼區塊行號範圍，便於精確定位關鍵實現
### 日誌管理
- 系統會自動記錄重要操作到對話日誌
- 長文本會自動使用 `extractSummary` 函數提取摘要，避免日誌過於冗長
- 日誌條目數量超過閾值時會進行自動輪換和歸檔
- 日誌查詢支持多種過濾條件和分頁功能
## 實用工具函數
### 摘要提取 (summaryExtractor.ts)
- `extractSummary` - 從文本中提取簡短摘要，自動處理 Markdown 格式
- `generateTaskSummary` - 基於任務名稱和描述生成任務完成摘要
- `extractTitle` - 從內容中提取適合作為標題的文本
- `extractSummaryFromConversation` - 從對話記錄中提取摘要信息
### 文件加載 (fileLoader.ts)
- `loadTaskRelatedFiles` - 生成任務相關文件的內容摘要
- `generateFileInfo` - 生成文件基本資訊摘要

1034
docs/usage-guide.md
View File

File diff suppressed because it is too large Load Diff