mcp-shrimp-task-manager/docs/usage-guide.md

蝦米任務管理器使用指南

本指南提供蝦米任務管理器的詳細使用說明，包括各功能的使用場景、最佳實踐和實用建議。

新增功能使用指南

1. 刪除任務功能

使用場景

• 任務規劃變更：當項目規劃變更，需要刪除某些不再需要的任務時
• 錯誤創建的任務：修正錯誤創建的任務，避免任務列表混亂
• 任務優先級調整：刪除低優先級任務以聚焦於更重要的目標

最佳實踐

1. 刪除前先檢查依賴關係：使用 list_tasks 檢查是否有其他任務依賴於要刪除的任務
2. 先刪除子任務：如果要刪除一個有多個子任務的父任務，建議先刪除所有子任務
3. 保留重要任務記錄：對於重要但不再需要的任務，考慮將其標記為完成而非刪除，以保留歷史記錄
4. 刪除後驗證：刪除操作後，使用 list_tasks 確認任務已被正確刪除且依賴關係未受影響

範例使用流程

// 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. 設置里程碑：對於高複雜度任務，定期檢查進度並記錄關鍵決策點

複雜度級別處理指南

複雜度級別	處理建議
低複雜度	直接執行，設定明確的完成標準
中等複雜度	詳細規劃執行步驟，分階段執行並定期檢查進度
高複雜度	進行充分的分析和規劃，考慮拆分為子任務，建立清晰的里程碑
極高複雜度	強烈建議拆分為多個獨立任務，進行風險評估，建立具體的測試標準

範例使用流程

// 執行任務時，系統會自動評估複雜度並提供建議
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. 限制與展望：提及現有實現的限制以及未來可能的改進方向

範例使用流程

// 完成任務時提供詳細摘要
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 確認結果

範例使用流程

// 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. 維護一致性：確保更新後的任務與整體項目目標一致

範例使用流程

// 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. 及時更新關聯：當發現新的相關文件時，及時更新關聯關係

文件關聯類型使用指南

類型	適用場景	建議
待修改	需要在任務中修改的文件	指定具體行號範圍，描述需要修改的內容
參考資料	提供背景或指導的文檔	添加說明，指出需要關注的文檔關鍵部分
輸出結果	任務將創建或修改的目標文件	描述預期的輸出結果和質量標準
依賴文件	任務實現依賴的組件或庫	說明依賴關係和注意事項
其他	不屬於上述類別但與任務相關的文件	清楚說明關聯原因

範例使用流程

// 添加或更新任務相關文件
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. 執行歷史記憶：自動包含：

   • 之前執行的關鍵步驟
   • 重要決策點和選擇原因
   • 遇到的問題和解決方案

使用範例

執行任務時，系統會自動應用上下文記憶功能：

// 執行任務（系統會自動加載相關文件和上下文）
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. 將關鍵發現記錄到文檔：將日誌中的重要發現整理到專門的文檔中，方便團隊分享

範例使用流程

// 查詢特定任務的日誌
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. 確認清理操作：清除是不可逆的，操作前確保團隊成員都已了解

範例使用流程

// 清除所有日誌（需慎重操作）
await mcp.mcp_shrimp_task_manager.clear_conversation_log({
  confirm: true,
});

整合使用流程

以下是一個完整的任務管理工作流程，整合了所有功能的使用：

1. 規劃與分析

   // 開始規劃
   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. 任務拆分與執行

   // 拆分任務
   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. 驗證與完成

   // 驗證任務
   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. 維護與整理

   // 更新任務內容
   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 目錄下。可以通過手動恢復這些備份文件來還原數據。建議定期檢查並整理備份目錄，確保重要數據安全。