From feac46d780f538421ed5d6ed604ab0818d984029 Mon Sep 17 00:00:00 2001 From: siage Date: Sat, 12 Apr 2025 16:57:47 +0800 Subject: [PATCH] =?UTF-8?q?=E6=9B=B4=E6=96=B0=20README=20=E6=96=87?= =?UTF-8?q?=E4=BB=B6=E4=BB=A5=E5=BC=B7=E8=AA=BF=E8=9D=A6=E7=B1=B3=E4=BB=BB?= =?UTF-8?q?=E5=8B=99=E7=AE=A1=E7=90=86=E5=99=A8=E7=9A=84=E6=99=BA=E8=83=BD?= =?UTF-8?q?=E4=BB=BB=E5=8B=99=E7=AE=A1=E7=90=86=E7=B3=BB=E7=B5=B1=E7=89=B9?= =?UTF-8?q?=E6=80=A7=EF=BC=8C=E9=87=8D=E6=96=B0=E6=95=B4=E7=90=86=E5=8A=9F?= =?UTF-8?q?=E8=83=BD=E7=89=B9=E9=BB=9E=E8=88=87=E4=BB=BB=E5=8B=99=E7=AE=A1?= =?UTF-8?q?=E7=90=86=E5=B7=A5=E4=BD=9C=E6=B5=81=E7=A8=8B=EF=BC=8C=E4=B8=A6?= =?UTF-8?q?=E6=96=B0=E5=A2=9E=E7=B3=BB=E7=B5=B1=E6=8F=90=E7=A4=BA=E8=A9=9E?= =?UTF-8?q?=E6=8C=87=E5=B0=8E=EF=BC=8C=E6=8F=90=E5=8D=87=E7=94=A8=E6=88=B6?= =?UTF-8?q?=E5=B0=8D=E7=B3=BB=E7=B5=B1=E7=9A=84=E7=90=86=E8=A7=A3=E8=88=87?= =?UTF-8?q?=E4=BD=BF=E7=94=A8=E9=AB=94=E9=A9=97=E3=80=82=E5=90=8C=E6=99=82?= =?UTF-8?q?=EF=BC=8C=E7=A7=BB=E9=99=A4=E4=B8=8D=E5=86=8D=E4=BD=BF=E7=94=A8?= =?UTF-8?q?=E7=9A=84=20API=20=E5=8F=83=E8=80=83=E6=96=87=E6=AA=94=E8=88=87?= =?UTF-8?q?=E7=A4=BA=E4=BE=8B=E4=BB=A3=E7=A2=BC=EF=BC=8C=E7=B0=A1=E5=8C=96?= =?UTF-8?q?=E6=96=87=E6=AA=94=E7=B5=90=E6=A7=8B=EF=BC=8C=E5=A2=9E=E5=BC=B7?= =?UTF-8?q?=E5=8F=AF=E8=AE=80=E6=80=A7=E8=88=87=E7=B6=AD=E8=AD=B7=E6=80=A7?= =?UTF-8?q?=E3=80=82?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- .cursor/modes.json | 2 +- README.md | 360 +++-------- docs/api-reference.md | 545 ---------------- docs/architecture.md | 387 +++++++----- docs/examples.md | 792 ----------------------- docs/functionality-checklist.md | 318 ++++++++++ docs/usage-guide.md | 1034 ------------------------------- 7 files changed, 638 insertions(+), 2800 deletions(-) delete mode 100644 docs/api-reference.md delete mode 100644 docs/examples.md create mode 100644 docs/functionality-checklist.md delete mode 100644 docs/usage-guide.md diff --git a/.cursor/modes.json b/.cursor/modes.json index dc53665..de29162 100644 --- a/.cursor/modes.json +++ b/.cursor/modes.json @@ -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", diff --git a/README.md b/README.md index af1b8c4..b7c01da 100644 --- a/README.md +++ b/README.md @@ -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) 文件 diff --git a/docs/api-reference.md b/docs/api-reference.md deleted file mode 100644 index 5b6fe05..0000000 --- a/docs/api-reference.md +++ /dev/null @@ -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 參數時，會停止處理剩餘文件並添加說明 -- 摘要內容包括文件路徑、類型、描述和行範圍等基本信息 diff --git a/docs/architecture.md b/docs/architecture.md index 7329c33..c789e7e 100644 --- a/docs/architecture.md +++ b/docs/architecture.md @@ -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 在處理長期複雜任務時的記憶限制問題。 + +隨著系統的進一步發展，未來將著重改進數據存儲方式、優化摘要生成算法、增強文件處理能力和添加更多任務管理功能，使系統能夠應對更多複雜的任務管理場景。 diff --git a/docs/examples.md b/docs/examples.md deleted file mode 100644 index e8ceb28..0000000 --- a/docs/examples.md +++ /dev/null @@ -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. 使用工作日誌功能追蹤項目進展和關鍵決策點 - -這些功能共同提供了一個強大的任務管理框架，幫助您更有效地規劃、執行和監控項目。 diff --git a/docs/functionality-checklist.md b/docs/functionality-checklist.md new file mode 100644 index 0000000..465d6d6 --- /dev/null +++ b/docs/functionality-checklist.md @@ -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` (必填) - 結構化的任務清單，每個任務應保持原子性且有明確的完成標準 + - `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` (必填) - 與任務相關的文件列表 + - `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` - 生成文件基本資訊摘要 diff --git a/docs/usage-guide.md b/docs/usage-guide.md deleted file mode 100644 index e2cfa93..0000000 --- a/docs/usage-guide.md +++ /dev/null @@ -1,1034 +0,0 @@ -# 蝦米任務管理器使用指南 - -本指南提供蝦米任務管理器的詳細使用說明，包括各功能的使用場景、最佳實踐和實用建議。 - -## 新增功能使用指南 - -### 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. 保留任務最核心的功能描述和目標 - -### 4. 清除所有任務功能 - -#### 使用場景 - -- **項目重啟**：當項目需要重新規劃和組織時 -- **測試清理**：在測試系統後恢復到初始狀態 -- **系統重置**：在出現數據混亂或錯誤狀態時進行系統重置 - -#### 最佳實踐 - -1. **數據備份**：系統會自動在執行清除前創建數據備份，但建議在執行前手動備份重要數據 -2. **謹慎使用**：清除操作不可逆，請確保真的需要刪除所有未完成任務 -3. **團隊溝通**：在團隊環境中使用前，先與團隊成員溝通確認 -4. **清除後檢查**：清除後使用 `list_tasks` 確認結果 - -#### 範例使用流程 - -```javascript -// 1. 先查看當前任務列表，確認哪些任務將被刪除 -await mcp.mcp_shrimp_task_manager.list_tasks(); - -// 2. 執行清除操作（必須明確確認） -const clearResult = await mcp.mcp_shrimp_task_manager.clear_all_tasks({ - confirm: true, // 必須設為 true -}); - -// 3. 檢查清除結果 -console.log(clearResult); - -// 4. 確認剩餘任務狀態 -await mcp.mcp_shrimp_task_manager.list_tasks(); -``` - -#### 安全注意事項 - -- **明確確認**：必須設置 `confirm: true` 參數，以防止意外操作 -- **備份保留**：系統會自動創建備份，格式為 `tasks-backup-YYYYMMDD-HHMMSS.json` -- **日誌記錄**：所有清除操作都會記錄在日誌中，包括操作時間、被刪除的任務數量 -- **保留完成任務**：已完成的任務不會被刪除，確保項目歷史記錄完整性 - -#### 潛在風險 - -- **無法撤銷**：一旦執行，操作無法撤銷（除通過手動還原備份） -- **依賴關係丟失**：清除後，任務間的依賴關係將無法恢復 -- **上下文丟失**：與任務相關的上下文記憶可能會丟失 - -### 5. 更新任務功能 - -#### 使用場景 - -- **任務細節變更**：當任務要求或細節發生變化時 -- **補充任務資訊**：添加更多細節或說明以澄清任務目標 -- **調整任務範圍**：擴大或縮小任務範圍時修改描述 - -#### 最佳實踐 - -1. **保持簡潔明確**：更新時確保任務描述清晰，焦點明確 -2. **記錄變更原因**：在注記中添加變更的理由，便於後續追蹤 -3. **通知相關人員**：任務有重大變更時，確保相關人員了解 -4. **維護一致性**：確保更新後的任務與整體項目目標一致 - -#### 範例使用流程 - -```javascript -// 1. 查看任務當前狀態 -await mcp.mcp_shrimp_task_manager.list_tasks(); - -// 2. 更新任務內容 -const updateResult = await mcp.mcp_shrimp_task_manager.update_task({ - taskId: "task-uuid-here", - name: "更新後的任務名稱", - description: "更詳細的任務描述，包含新要求...", - notes: "更新原因：需求變更，添加了新的功能要求", -}); - -// 3. 確認更新結果 -console.log(updateResult); -``` - -#### 注意事項 - -- **已完成任務限制**：已完成的任務不能被更新，這確保了任務歷史記錄的穩定性 -- **至少一個參數**：更新時至少需要提供 name、description 或 notes 中的一個參數 -- **不改變核心屬性**：任務 ID 和完成狀態不能通過此功能更改 -- **歷史記錄**：系統會自動記錄所有更新操作，便於追蹤任務變更歷史 - -### 6. 任務相關文件位置記錄功能 - -#### 使用場景 - -- **代碼關聯跟蹤**：記錄任務涉及的代碼文件和位置 -- **文檔參考關聯**：將相關設計文檔、API 規範等與任務關聯 -- **提升上下文記憶**：幫助 LLM 在任務執行時快速加載相關上下文 -- **資源整理**：系統性整理與任務相關的所有資源 - -#### 最佳實踐 - -1. **分類關聯文件**：使用不同的關聯類型（待修改、參考資料等）清晰分類 -2. **精確定位代碼**：對代碼文件指定具體行號範圍，聚焦關鍵代碼區域 -3. **添加描述說明**：為每個文件添加簡明的描述，說明其與任務的關係 -4. **及時更新關聯**：當發現新的相關文件時，及時更新關聯關係 - -#### 文件關聯類型使用指南 - -| 類型 | 適用場景 | 建議 | -| -------- | -------------------------------- | ------------------------------------ | -| 待修改 | 需要在任務中修改的文件 | 指定具體行號範圍，描述需要修改的內容 | -| 參考資料 | 提供背景或指導的文檔 | 添加說明，指出需要關注的文檔關鍵部分 | -| 輸出結果 | 任務將創建或修改的目標文件 | 描述預期的輸出結果和質量標準 | -| 依賴文件 | 任務實現依賴的組件或庫 | 說明依賴關係和注意事項 | -| 其他 | 不屬於上述類別但與任務相關的文件 | 清楚說明關聯原因 | - -#### 範例使用流程 - -```javascript -// 添加或更新任務相關文件 -const filesResult = await mcp.mcp_shrimp_task_manager.update_task_files({ - taskId: "task-uuid-here", - relatedFiles: [ - // 待修改的代碼文件，包含具體行號 - { - path: "src/services/authService.ts", - type: "待修改", - description: "需要增加多因素認證支持", - lineStart: 45, - lineEnd: 78, - }, - // 參考的設計文檔 - { - path: "docs/auth-design.md", - type: "參考資料", - description: "包含認證流程設計和安全要求", - }, - // 任務將要創建的新文件 - { - path: "src/components/TwoFactorAuth.tsx", - type: "輸出結果", - description: "需要創建的多因素認證組件", - }, - // 依賴的現有組件 - { - path: "src/components/InputCode.tsx", - type: "依賴文件", - description: "將複用的驗證碼輸入組件", - }, - ], -}); -``` - -#### 上下文記憶增強效果 - -通過關聯文件功能，系統可以： - -1. **自動生成文件摘要**：執行任務時基於文件元數據生成摘要信息 -2. **提供精確定位信息**：保留文件路徑和行號範圍，方便後續查找 -3. **建立知識網絡**：將分散的相關資源連接成有機整體 -4. **提高執行效率**：提供結構化的文件相關信息，減少任務執行時間 - -### 7. 優化任務執行時的上下文記憶功能 - -#### 使用場景 - -- **執行複雜任務**：當任務涉及多個文件和組件時 -- **延續之前工作**：在中斷後重新開始任務時恢復上下文 -- **團隊協作**：不同成員接手任務時快速了解相關上下文 -- **長期項目**：在跨越長時間的項目中保持上下文連貫性 - -#### 最佳實踐 - -1. **優先關聯核心文件**：識別並優先關聯最重要的文件 -2. **保持關聯更新**：隨著任務進展，及時更新相關文件列表 -3. **添加精確注釋**：在相關文件描述中提供具體指引 -4. **利用代碼區塊定位**：使用行號範圍準確定位相關代碼 -5. **建立樹狀依賴**：明確文件間的依賴關係，形成知識樹 - -#### 智能上下文加載功能說明 - -系統在執行任務時會智能處理文件相關信息，主要特點包括： - -1. **自動優先級排序**：根據文件類型和關聯程度排序 - - - "待修改"文件優先級最高 - - 直接依賴的文件次之 - - 參考資料根據相關性排序 - -2. **文件摘要生成**：對於關聯文件，系統會： - - - 基於文件元數據創建格式化的摘要信息 - - 優先處理指定的行號範圍信息 - - 根據文件類型提供適當的上下文提示 - -3. **上下文壓縮**：在上下文過大時，系統會： - - - 控制摘要內容的總長度 - - 對文件生成簡潔的描述 - - 優化格式，減少上下文標記使用 - -4. **執行歷史記憶**：自動包含： - - 之前執行的關鍵步驟 - - 重要決策點和選擇原因 - - 遇到的問題和解決方案 - -#### 使用範例 - -執行任務時，系統會自動應用上下文記憶功能： - -```javascript -// 執行任務（系統會自動生成相關文件摘要） -const executeResult = await mcp.mcp_shrimp_task_manager.execute_task({ - taskId: "task-uuid-here", -}); - -// 隨著任務進展，更新相關文件以增強上下文記憶 -await mcp.mcp_shrimp_task_manager.update_task_files({ - taskId: "task-uuid-here", - relatedFiles: [ - // 添加新發現的相關文件 - { - path: "src/utils/validation.ts", - type: "依賴文件", - description: "包含表單驗證函數，用於實施表單驗證邏輯", - lineStart: 25, - lineEnd: 48, - }, - ], -}); - -// 繼續執行任務，利用更新後的上下文 -// 系統會根據更新的相關文件信息生成新的摘要 -``` - -#### 上下文記憶限制與解決方案 - -面對 LLM 上下文窗口限制，系統採用以下策略： - -1. **分層資訊呈現**： - - - 關鍵文件位置和描述信息優先呈現 - - 次要內容以簡要摘要形式提供 - - 背景知識以參考鏈接形式提供 - -2. **動態上下文調整**： - - - 根據任務階段調整重點內容 - - 在複雜決策點呈現更多背景資訊 - - 在實施階段聚焦於實現細節 - -3. **記憶外部化**： - - 使用相關文件系統存儲上下文 - - 提供檢索機制以按需加載資訊 - - 定期總結並存儲重要進展 - -## 工作日誌功能使用指南 - -### 查詢日誌 (`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.update_task_files({ - taskId: "task-uuid-here", - relatedFiles: [ - { - path: "src/components/Auth.tsx", - type: "待修改", - description: "需要更新的認證組件", - lineStart: 35, - lineEnd: 67, - }, - ], - }); - - // 執行任務（系統會自動評估複雜度並加載相關文件） - 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.update_task({ - taskId: "task-uuid-here", - description: "更新後的任務描述...", - }); - - // 刪除不需要的任務 - await mcp.mcp_shrimp_task_manager.delete_task({ - taskId: "task-uuid-here", - }); - - // 清除所有未完成任務（謹慎使用） - await mcp.mcp_shrimp_task_manager.clear_all_tasks({ - confirm: true, - }); - - // 查詢任務日誌 - 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` 工具清理舊日誌。 - -### Q: 如何管理大型項目中的上下文記憶？ - -**A:** 利用相關文件功能建立完整的文件關聯網絡，為每個任務標記最關鍵的相關文件，並使用精確的行號範圍定位核心代碼。定期更新文件關聯，反映項目的最新狀態。 - -### Q: 清除所有任務後，如何恢復誤刪的數據？ - -**A:** 系統在清除操作前會自動創建備份文件，存放在 `data/backups` 目錄下。可以通過手動恢復這些備份文件來還原數據。建議定期檢查並整理備份目錄，確保重要數據安全。 - - - -## 專案特定配置指南 - -蝦米任務管理器支持兩種配置方式：全局配置和專案特定配置。本章節將詳細介紹如何使用專案特定配置，幫助您更有效地管理多個專案的任務數據。 - -### DATA_DIR 參數的作用及重要性 - -`DATA_DIR` 是蝦米任務管理器中最關鍵的配置參數之一，它決定了系統存儲數據的位置。具體來說，`DATA_DIR` 參數指定的目錄用於存儲： - -1. **任務數據**：所有任務的詳細信息、狀態和依賴關係（`tasks.json`） -2. **對話日誌**：系統與 LLM 之間的交互記錄（`conversation_log.json`） -3. **數據備份**：任務數據的定期備份（`backups/` 目錄） -4. **臨時文件**：系統操作過程中的臨時數據 - -`DATA_DIR` 參數的正確設置對系統穩定性和數據安全至關重要，因為： - -- **數據持久化**：確保任務信息在系統重啟後不會丟失 -- **數據完整性**：維護任務間的依賴關係和執行歷史 -- **上下文記憶**：保存 LLM 在執行任務時需要的上下文信息 -- **備份與恢復**：支持數據備份和災難恢復機制 - -**重要說明：`DATA_DIR` 參數僅支援絕對路徑設置**。這是一項技術限制，主要基於以下原因： - -1. **路徑解析一致性**：絕對路徑提供確定的檔案位置，無論程式從何處啟動，都能準確定位數據目錄 -2. **跨環境穩定性**：在不同執行環境（如開發、測試、生產）中，相對路徑可能產生不同解析結果 -3. **程序啟動位置獨立性**：蝦米任務管理器可能從不同的工作目錄啟動，相對路徑會導致數據目錄位置不一致 -4. **多進程安全**：當系統在多個進程間運行時，絕對路徑確保所有進程訪問相同的數據目錄 - -> **警告**：使用相對路徑設置 DATA_DIR 會導致以下嚴重問題： -> -> - **系統初始化失敗**：無法找到或創建必要的數據文件，導致系統啟動失敗 -> - **數據不一致**：相同代碼在不同環境執行時可能使用不同的數據目錄，造成數據分散 -> - **任務狀態丟失**：任務狀態和歷史記錄可能找不到或丟失，導致任務執行中斷 -> - **系統不穩定**：路徑解析錯誤可能導致系統在某些情況下工作，在其他情況下失敗 -> - **備份失敗**：備份機制無法正確定位或存儲備份文件，增加數據丟失風險 - -為確保系統穩定性和數據安全，在配置 `DATA_DIR` 參數時，請始終使用絕對路徑，例如： - -```json -"DATA_DIR": "/Users/username/projects/my-project/data" -``` - -而不是相對路徑： - -```json -"DATA_DIR": "./data" // 請勿使用此方式設定！ -``` - -### 專案特定配置的優勢 - -相比全局配置，在專案目錄中使用專案特定的 `.cursor/mcp.json` 配置有以下明顯優勢： - -#### 1. 數據隔離 - -- **獨立數據存儲**：每個專案使用獨立的數據目錄，避免任務數據混淆 -- **專案內聚性**：任務數據與專案代碼一起管理，增強內聚性 -- **錯誤防護**：防止跨專案操作錯誤，如誤刪除他專案的任務 - -#### 2. 專案可移植性 - -- **整體遷移**：專案代碼和任務數據可一起移動或分享 -- **環境一致性**：確保在不同環境中使用相同的配置 -- **團隊協作**：團隊成員可以共享完整的專案上下文，包括任務狀態 - -#### 3. 多專案管理 - -- **同時處理**：可以同時處理多個專案而不互相影響 -- **上下文切換**：在不同專案間切換時，自動使用相應的任務數據 -- **專案特化**：可以為不同類型的專案設置不同的配置參數 - -#### 4. 版本控制友好 - -- **配置跟踪**：`.cursor/mcp.json` 可以納入版本控制系統 -- **配置共享**：團隊成員自動獲取一致的配置設置 -- **變更記錄**：配置變更可以通過版本控制系統追蹤和審查 - -### mcp.json 配置參數完整說明 - -專案特定的 `mcp.json` 文件應放置在專案根目錄的 `.cursor` 目錄下，其完整結構如下： - -```json -{ - "mcpServers": { - "shrimp-task-manager": { - "command": "node", - "args": ["/path/to/mcp-shrimp-task-manager/dist/index.js"], - "env": { - "DATA_DIR": "/absolute/path/to/data", - "LOG_LEVEL": "info", - "MAX_BACKUP_FILES": "5" - } - } - } -} -``` - -#### 必要參數 - -| 參數名 | 說明 | 示例值 | -| -------------- | ----------------------------------- | ---------------------------------------------------- | -| `command` | 執行命令，通常為 node | `"node"` | -| `args` | 命令參數，指向 dist/index.js 的路徑 | `["/path/to/mcp-shrimp-task-manager/dist/index.js"]` | -| `env.DATA_DIR` | 數據目錄路徑，必須使用絕對路徑 | `"/absolute/path/to/data"` | - -#### 可選環境變數 - -| 環境變數名 | 說明 | 默認值 | 示例值 | -| ------------------ | ------------------------- | -------- | ---------------------- | -| `LOG_LEVEL` | 日誌記錄級別 | `"info"` | `"debug"`, `"warning"` | -| `MAX_BACKUP_FILES` | 保留的最大備份文件數量 | `"5"` | `"10"` | -| `BACKUP_INTERVAL` | 自動備份間隔（小時） | `"24"` | `"12"` | -| `PORT` | HTTP 服務器端口（如啟用） | `"3000"` | `"8080"` | - -### 注意事項和建議 - -1. **路徑設置**： - - - 絕對路徑提供明確的位置指向，但降低了可移植性 - - 相對路徑（如 `"./data"`）增強可移植性，建議在團隊協作環境中使用 - -2. **數據目錄**： - - - 建議創建專用的數據目錄（例如 `data/`） - - 確保該目錄已納入 `.gitignore`，避免將任務數據提交到版本控制系統（除非有意共享） - -3. **權限考慮**： - - - 確保運行蝦米任務管理器的用戶對 DATA_DIR 目錄有讀寫權限 - - 在團隊環境中，可能需要考慮目錄的共享權限設置 - -4. **備份策略**： - - 設置適當的 `MAX_BACKUP_FILES` 值，平衡數據安全和磁盤使用 - - 考慮定期將備份複製到外部存儲以增強數據安全 - -### 專案特定配置的逐步設置指南 - -以下是配置專案特定 mcp.json 的詳細步驟指南，幫助您快速設置適合專案需求的配置。 - -#### 步驟 1：在專案根目錄創建 .cursor 目錄 - -首先，在您的專案根目錄中創建一個名為 `.cursor` 的目錄： - -```bash -# 在專案根目錄執行 -mkdir -p .cursor -``` - -> **注意**：在某些操作系統中，以點（.）開頭的目錄可能默認隱藏。如果您在檔案管理器中看不到該目錄，請檢查顯示隱藏文件的選項。 - -#### 步驟 2：創建 mcp.json 配置文件 - -在 `.cursor` 目錄中創建 `mcp.json` 文件： - -```bash -touch .cursor/mcp.json -``` - -#### 步驟 3：編輯 mcp.json 文件 - -使用您喜歡的文本編輯器打開 `mcp.json` 文件，添加以下基本配置： - -```bash -{ - "mcpServers": { - "shrimp-task-manager": { - "command": "node", - "args": ["/absolute/path/to/mcp-shrimp-task-manager/dist/index.js"], - "env": { - "DATA_DIR": "/absolute/path/to/data" - } - } - } -} -``` - -請將 `/absolute/path/to/mcp-shrimp-task-manager` 替換為蝦米任務管理器的實際安裝路徑。 - -#### 步驟 4：設定 DATA_DIR 參數 - -`DATA_DIR` 參數必須使用絕對路徑，這是系統正常運行的必要條件。絕對路徑提供了明確的位置指向，確保系統在任何情況下都能正確找到數據目錄。 - -```json -"DATA_DIR": "/Users/username/projects/my-project/data" -``` - -在設定 DATA_DIR 時，請遵循以下建議： - -1. **使用完整的絕對路徑**：從根目錄開始的完整路徑，確保無歧義 -2. **避免使用環境變量**：直接使用硬編碼的路徑，而非依賴環境變量解析 -3. **確保路徑存在**：提前創建該路徑，或在啟動前確認路徑存在 -4. **設置適當權限**：確保運行程序的用戶對該路徑有讀寫權限 - -> **警告**：系統不支持使用相對路徑設置 DATA_DIR。使用相對路徑會導致數據存取錯誤，可能造成任務狀態丟失、系統不穩定和數據不一致等嚴重問題。 - -#### 步驟 5：創建數據目錄 - -確保 `DATA_DIR` 指向的目錄存在： - -```bash -# 創建絕對路徑指定的數據目錄 -mkdir -p /Users/username/projects/my-project/data -``` - -#### 步驟 6：更新 .gitignore（可選但推薦） - -如果您的專案使用 Git 進行版本控制，建議將數據目錄添加到 `.gitignore` 文件中（除非您打算共享任務數據）： - -```bash -# 添加到 .gitignore -echo "data/" >> .gitignore -``` - -#### 完整配置範例 - -以下是一個更完整的配置範例，包含常用的可選參數： - -```json -{ - "mcpServers": { - "shrimp-task-manager": { - "command": "node", - "args": ["/path/to/mcp-shrimp-task-manager/dist/index.js"], - "env": { - "DATA_DIR": "/absolute/path/to/data", - "LOG_LEVEL": "info", - "MAX_BACKUP_FILES": "10", - "BACKUP_INTERVAL": "12" - } - } - } -} -``` - -#### 測試配置 - -完成配置後，打開 Cursor IDE 並嘗試使用蝦米任務管理器的任何功能（如 `list_tasks`）來測試配置是否生效。系統應該會在您指定的 `DATA_DIR` 路徑創建必要的數據文件。 - -#### 常見問題與解決方案 - -1. **找不到蝦米任務管理器** - - - 檢查 `args` 中的路徑是否正確指向 dist/index.js - - 確保已正確安裝蝦米任務管理器及其依賴 - -2. **無法創建或訪問數據目錄** - - - 檢查用戶對指定目錄的讀寫權限 - - 如果使用相對路徑，確認相對於專案根目錄的位置是否正確 - -3. **配置未生效** - - 確保 `.cursor/mcp.json` 文件格式正確（有效的 JSON） - - 重新啟動 Cursor IDE 以載入新配置 - - 檢查 Cursor IDE 的日誌是否有錯誤信息 - -### 多種配置場景範例 - -蝦米任務管理器可以適應多種不同的工作場景，以下提供幾種常見使用場景的配置示例和最佳實踐。 - -#### 1. 單一開發者多專案環境 - -對於同時處理多個專案的獨立開發者，專案特定配置可以幫助您維護清晰的任務隔離。 - -**示例配置**： - -```json -// 專案A: .cursor/mcp.json -{ - "mcpServers": { - "shrimp-task-manager": { - "command": "node", - "args": ["/Users/developer/tools/mcp-shrimp-task-manager/dist/index.js"], - "env": { - "DATA_DIR": "/Users/developer/projects/projectA/data", - "LOG_LEVEL": "info" - } - } - } -} -``` - -```json -// 專案B: .cursor/mcp.json -{ - "mcpServers": { - "shrimp-task-manager": { - "command": "node", - "args": ["/Users/developer/tools/mcp-shrimp-task-manager/dist/index.js"], - "env": { - "DATA_DIR": "/Users/developer/projects/projectB/data", - "LOG_LEVEL": "debug" // 不同的日誌級別 - } - } - } -} -``` - -**最佳實踐**： - -- 為每個專案指定唯一的絕對路徑作為 DATA_DIR，確保數據隔離 -- 根據專案需求調整日誌級別和備份策略 -- 使用腳本或別名簡化在多個專案間切換的操作 -- 使用有意義的目錄命名，如包含專案名稱的路徑 - -#### 2. 團隊協作環境 - -在團隊協作的環境中，專案特定配置可以確保團隊成員使用一致的設置。 - -**示例配置**： - -```json -// 團隊專案: .cursor/mcp.json (納入版本控制) -{ - "mcpServers": { - "shrimp-task-manager": { - "command": "node", - "args": ["/opt/shared/mcp-shrimp-task-manager/dist/index.js"], - "env": { - "DATA_DIR": "/opt/shared/project-data/team-project/data", - "LOG_LEVEL": "info", - "MAX_BACKUP_FILES": "10" - } - } - } -} -``` - -**最佳實踐**： - -- 使用絕對路徑指定數據目錄，確保所有團隊成員能訪問相同的位置 -- 將 `.cursor/mcp.json` 文件納入版本控制，但將數據目錄添加到 `.gitignore` -- 考慮為共享知識庫專案配置共享的數據目錄（如雲端存儲或版本控制） -- 明確記錄配置要求，確保新團隊成員能夠快速設置環境 -- 設置統一的團隊路徑標準，確保所有成員使用相同的路徑結構 - -#### 3. 臨時/測試專案設置 - -對於臨時專案或測試環境，您可能需要更靈活的配置。 - -**示例配置**： - -```json -// 臨時測試專案: .cursor/mcp.json -{ - "mcpServers": { - "shrimp-task-manager": { - "command": "node", - "args": ["/path/to/mcp-shrimp-task-manager/dist/index.js"], - "env": { - "DATA_DIR": "/tmp/test-project-data", // 使用臨時目錄的絕對路徑 - "LOG_LEVEL": "debug", - "MAX_BACKUP_FILES": "2" // 減少備份量 - } - } - } -} -``` - -**最佳實踐**： - -- 對於臨時測試，可以使用系統臨時目錄的絕對路徑存儲數據 -- 設置更高的日誌級別（如 `"debug"`）以便更詳細地診斷問題 -- 減少備份文件數量，避免不必要的磁盤使用 -- 測試完成後記得清理臨時數據 -- 為臨時數據目錄設置容易識別的命名前綴，方便日後清理 - -#### 4. 跨平台開發環境 - -在需要跨不同操作系統進行開發的場景中，配置需要特別注意。 - -**示例配置**： - -```json -// Windows開發環境: .cursor/mcp.json -{ - "mcpServers": { - "shrimp-task-manager": { - "command": "node", - "args": ["C:\\Program Files\\mcp-shrimp-task-manager\\dist\\index.js"], - "env": { - "DATA_DIR": "C:\\Users\\Developer\\AppData\\Local\\shrimp-task-manager\\data", - "LOG_LEVEL": "info" - } - } - } -} -``` - -```json -// macOS開發環境: .cursor/mcp.json -{ - "mcpServers": { - "shrimp-task-manager": { - "command": "node", - "args": ["/Applications/mcp-shrimp-task-manager/dist/index.js"], - "env": { - "DATA_DIR": "/Users/developer/Library/Application Support/shrimp-task-manager/data", - "LOG_LEVEL": "info" - } - } - } -} -``` - -**最佳實踐**： - -- 在每個平台上使用符合該平台標準的絕對路徑 -- 為不同操作系統創建單獨的配置檔案模板 -- 記錄每個平台的標準安裝路徑和數據目錄 -- 考慮使用平台特定的配置生成腳本 -- 確保 Windows 上的路徑使用雙反斜線或單正斜線 - -#### 5. 持續集成/持續部署環境 - -在 CI/CD 系統中，配置需要高度自動化和可重現性。 - -**示例配置**： - -```json -// CI/CD環境: .cursor/mcp.json -{ - "mcpServers": { - "shrimp-task-manager": { - "command": "node", - "args": ["/opt/ci/mcp-shrimp-task-manager/dist/index.js"], - "env": { - "DATA_DIR": "/opt/ci/build-data/job-${BUILD_ID}/data", - "LOG_LEVEL": "warning", - "MAX_BACKUP_FILES": "1" - } - } - } -} -``` - -**最佳實踐**： - -- 使用絕對路徑並可能結合 CI 系統的環境變量 -- 為每個構建作業使用獨立的數據目錄 -- 設置較低的備份頻率，專注於當前構建 -- 配置定期清理舊的構建數據 -- 使用 CI 系統的緩存機制提高效率 - -請注意，所有配置場景都統一使用絕對路徑設置 DATA_DIR 參數，這確保了系統的穩定性和數據的一致性。