From 8cb3a3228d65b46f14b8999f1343570421bec8d1 Mon Sep 17 00:00:00 2001 From: siage Date: Sat, 12 Apr 2025 02:01:28 +0800 Subject: [PATCH] =?UTF-8?q?=E6=96=B0=E5=A2=9E=E5=AF=A6=E7=94=A8=E5=B7=A5?= =?UTF-8?q?=E5=85=B7=E5=87=BD=E6=95=B8=E4=BB=A5=E7=94=9F=E6=88=90=E4=BB=BB?= =?UTF-8?q?=E5=8B=99=E7=9B=B8=E9=97=9C=E6=96=87=E4=BB=B6=E7=9A=84=E6=91=98?= =?UTF-8?q?=E8=A6=81=EF=BC=8C=E6=9B=B4=E6=96=B0=20API=20=E5=8F=83=E8=80=83?= =?UTF-8?q?=E6=96=87=E6=AA=94=E4=BB=A5=E5=8C=85=E5=90=AB=E6=96=B0=E5=8A=9F?= =?UTF-8?q?=E8=83=BD=E8=AA=AA=E6=98=8E=EF=BC=8C=E4=B8=A6=E8=AA=BF=E6=95=B4?= =?UTF-8?q?=E6=9E=B6=E6=A7=8B=E6=96=87=E6=AA=94=E4=BB=A5=E5=8F=8D=E6=98=A0?= =?UTF-8?q?=E6=96=87=E4=BB=B6=E6=91=98=E8=A6=81=E7=94=9F=E6=88=90=E7=9A=84?= =?UTF-8?q?=E9=82=8F=E8=BC=AF=E8=88=87=E6=B5=81=E7=A8=8B=EF=BC=8C=E6=8F=90?= =?UTF-8?q?=E5=8D=87=E4=BB=BB=E5=8B=99=E7=AE=A1=E7=90=86=E7=9A=84=E9=9D=88?= =?UTF-8?q?=E6=B4=BB=E6=80=A7=E8=88=87=E6=96=87=E4=BB=B6=E8=99=95=E7=90=86?= =?UTF-8?q?=E8=83=BD=E5=8A=9B=E3=80=82?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- docs/api-reference.md | 65 ++++++++++++++++++++++++++++++++++++++++++ docs/architecture.md | 20 ++++++------- docs/usage-guide.md | 30 +++++++++---------- src/index.ts | 26 +++++++++++++++-- src/tools/taskTools.ts | 26 +++++++++-------- 5 files changed, 127 insertions(+), 40 deletions(-) diff --git a/docs/api-reference.md b/docs/api-reference.md index 06a77ed..5b6fe05 100644 --- a/docs/api-reference.md +++ b/docs/api-reference.md @@ -7,6 +7,7 @@ - [核心任務管理 API](#核心任務管理-api) - [任務管理 API](#任務管理-api) - [工作日誌功能](#工作日誌功能) +- [實用工具函數](#實用工具函數) ## 核心任務管理 API @@ -478,3 +479,67 @@ const clearResult = await mcp.mcp_shrimp_task_manager.clear_conversation_log({ ``` ## 實用工具函數 + +### 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 ce922f4..7329c33 100644 --- a/docs/architecture.md +++ b/docs/architecture.md @@ -64,7 +64,7 @@ - `taskTools.ts`: 任務管理相關工具 - `logTools.ts`: 日誌管理相關工具 -- `fileLoader.ts`: 文件加載和處理工具（新增） +- `fileLoader.ts`: 任務相關文件的摘要生成工具（新增） **新增功能**： @@ -113,14 +113,14 @@ **核心文件**： - `summaryExtractor.ts`: 實現摘要提取和生成功能 -- `fileLoader.ts`: 實現智能文件加載和代碼區塊提取功能（新增） +- `fileLoader.ts`: 實現任務相關文件的摘要生成功能（新增） - `contextManager.ts`: 管理上下文記憶和優化（新增） **新增功能**： - 增強 `generateTaskSummary` 函數實現自動摘要生成 -- 實現 `loadTaskRelatedFiles` 函數，智能加載相關文件內容 -- 實現 `extractRelevantCodeBlocks` 函數，從大型文件中提取關鍵代碼 +- 實現 `loadTaskRelatedFiles` 函數，生成任務相關文件的摘要 +- 簡化 `extractRelevantCodeBlocks` 函數，生成代碼的位置和描述摘要 - 實現 `optimizeContext` 函數，優化上下文表示和壓縮 ### 2.6 數據存儲層 @@ -328,13 +328,13 @@ LLM 調用 update_task_files 按優先級排序文件 | v -智能加載文件內容 +生成文件摘要 | | - | +---> 對於指定行號範圍的文件，優先加載該範圍 + | +---> 對於指定行號範圍的文件，生成該範圍的摘要 | | - | +---> 對於大型文件，提取關鍵代碼區塊 + | +---> 對於大型文件，生成關鍵內容的摘要描述 | | - | +---> 對於文檔文件，生成摘要 + | +---> 對於文檔文件，生成整體內容摘要 | v 加載依賴任務的摘要 @@ -511,7 +511,7 @@ LLM 調用 update_task_files | | v v +-------+------------------------+-----+ - | 文件優先級排序和智能載入 | + | 文件優先級排序和摘要生成 | +-------+------------------------+-----+ | v @@ -544,7 +544,7 @@ LLM 調用 update_task_files - **複雜度評估擴展**：可在 `assessTaskComplexity` 中添加更多評估指標 - **摘要生成擴展**：可增強 `summaryExtractor.ts` 中的算法 - **上下文管理擴展**：可在 `contextManager.ts` 中添加更多上下文優化策略 -- **文件加載擴展**：可在 `fileLoader.ts` 中支持更多文件類型的智能加載 +- **摘要生成擴展**：可在 `fileLoader.ts` 中支持更多文件類型的摘要格式化 ## 7. 系統限制與未來改進 diff --git a/docs/usage-guide.md b/docs/usage-guide.md index 4968bac..e2cfa93 100644 --- a/docs/usage-guide.md +++ b/docs/usage-guide.md @@ -289,10 +289,10 @@ const filesResult = await mcp.mcp_shrimp_task_manager.update_task_files({ 通過關聯文件功能，系統可以： -1. **自動載入關鍵上下文**：執行任務時自動加載相關文件內容 -2. **提供精確代碼定位**：直接定位到相關代碼，減少搜索時間 +1. **自動生成文件摘要**：執行任務時基於文件元數據生成摘要信息 +2. **提供精確定位信息**：保留文件路徑和行號範圍，方便後續查找 3. **建立知識網絡**：將分散的相關資源連接成有機整體 -4. **提高執行效率**：減少上下文切換，提高任務連貫性 +4. **提高執行效率**：提供結構化的文件相關信息，減少任務執行時間 ### 7. 優化任務執行時的上下文記憶功能 @@ -313,7 +313,7 @@ const filesResult = await mcp.mcp_shrimp_task_manager.update_task_files({ #### 智能上下文加載功能說明 -系統在執行任務時會智能處理文件內容，主要特點包括： +系統在執行任務時會智能處理文件相關信息，主要特點包括： 1. **自動優先級排序**：根據文件類型和關聯程度排序 @@ -321,16 +321,16 @@ const filesResult = await mcp.mcp_shrimp_task_manager.update_task_files({ - 直接依賴的文件次之 - 參考資料根據相關性排序 -2. **智能代碼提取**：對於大型文件，系統會： +2. **文件摘要生成**：對於關聯文件，系統會： - - 優先加載指定的行號範圍 - - 識別關鍵代碼區塊（如函數定義、類定義） - - 提取重要的註釋和文檔字符串 + - 基於文件元數據創建格式化的摘要信息 + - 優先處理指定的行號範圍信息 + - 根據文件類型提供適當的上下文提示 3. **上下文壓縮**：在上下文過大時，系統會： - - 保留核心代碼，刪減非關鍵部分 - - 對大型文檔生成摘要 + - 控制摘要內容的總長度 + - 對文件生成簡潔的描述 - 優化格式，減少上下文標記使用 4. **執行歷史記憶**：自動包含： @@ -343,7 +343,7 @@ const filesResult = await mcp.mcp_shrimp_task_manager.update_task_files({ 執行任務時，系統會自動應用上下文記憶功能： ```javascript -// 執行任務（系統會自動加載相關文件和上下文） +// 執行任務（系統會自動生成相關文件摘要） const executeResult = await mcp.mcp_shrimp_task_manager.execute_task({ taskId: "task-uuid-here", }); @@ -356,7 +356,7 @@ await mcp.mcp_shrimp_task_manager.update_task_files({ { path: "src/utils/validation.ts", type: "依賴文件", - description: "包含需要使用的表單驗證函數", + description: "包含表單驗證函數，用於實施表單驗證邏輯", lineStart: 25, lineEnd: 48, }, @@ -364,7 +364,7 @@ await mcp.mcp_shrimp_task_manager.update_task_files({ }); // 繼續執行任務，利用更新後的上下文 -// 系統會結合新文件和之前的執行上下文 +// 系統會根據更新的相關文件信息生成新的摘要 ``` #### 上下文記憶限制與解決方案 @@ -373,8 +373,8 @@ await mcp.mcp_shrimp_task_manager.update_task_files({ 1. **分層資訊呈現**： - - 核心代碼完整呈現 - - 次要內容以摘要形式提供 + - 關鍵文件位置和描述信息優先呈現 + - 次要內容以簡要摘要形式提供 - 背景知識以參考鏈接形式提供 2. **動態上下文調整**： diff --git a/src/index.ts b/src/index.ts index a8f3b7b..fc4083c 100644 --- a/src/index.ts +++ b/src/index.ts @@ -138,7 +138,7 @@ async function main() { server.tool( "split_tasks", - "將複雜任務分解為獨立且可追蹤的子任務，建立明確的依賴關係和優先順序", + "將複雜任務分解為獨立且可追蹤的子任務，建立明確的依賴關係和優先順序，dependencies 是一個字串陣列，支援任務名稱或任務ID(UUID)", { isOverwrite: z .boolean() @@ -166,11 +166,31 @@ async function main() { .optional() .describe("補充說明、特殊處理要求或實施建議（選填）"), dependencies: z - .array(z.string()) + .array(z.string(), { + message: "必須是字串陣列，支援任務名稱或任務ID(UUID)", + }) .optional() .describe( - "此任務依賴的前置任務ID或任務名稱列表，支持兩種引用方式，名稱引用更直觀" + "此任務依賴的前置任務ID或任務名稱列表，支持兩種引用方式，名稱引用更直觀，是一個字串陣列" ), + relatedFiles: z + .array( + z.object({ + path: z + .string() + .min(1, { message: "檔案路徑不能為空" }) + .describe("檔案路徑，相對於專案根目錄"), + type: z + .nativeEnum(RelatedFileType) + .describe("檔案類型，用於區分不同類型的檔案"), + description: z + .string() + .min(1, { message: "檔案描述不能為空" }) + .describe("檔案描述，用於說明檔案的用途和內容"), + }) + ) + .optional() + .describe("與任務相關的檔案列表，包含檔案路徑、類型和描述"), }) ) .describe("結構化的任務清單，每個任務應保持原子性且有明確的完成標準"), diff --git a/src/tools/taskTools.ts b/src/tools/taskTools.ts index 4b7b8e5..eb6b204 100644 --- a/src/tools/taskTools.ts +++ b/src/tools/taskTools.ts @@ -253,7 +253,9 @@ export const splitTasksSchema = z .optional() .describe("補充說明、特殊處理要求或實施建議（選填）"), dependencies: z - .array(z.string()) + .array(z.string(), { + message: "必須是字串陣列，支援任務名稱或任務ID(UUID)", + }) .optional() .describe( "此任務依賴的前置任務ID或任務名稱列表，支持兩種引用方式，名稱引用更直觀" @@ -672,38 +674,38 @@ export async function executeTask({ // 記錄加載文件操作 await addConversationEntry( ConversationParticipant.MCP, - `正在加載任務相關文件，共 ${task.relatedFiles.length} 個文件`, + `正在生成任務相關文件摘要，共 ${task.relatedFiles.length} 個文件`, task.id, - "加載相關文件" + "生成相關文件摘要" ); - // 加載相關文件內容，使用增強的智能提取功能 + // 生成任務相關文件的摘要資訊 const loadResult = await loadTaskRelatedFiles(task.relatedFiles); relatedFilesContent = loadResult.content; relatedFilesSummary = loadResult.summary; - // 記錄加載完成 + // 記錄摘要生成完成 await addConversationEntry( ConversationParticipant.MCP, - `任務相關文件加載完成，成功加載 ${task.relatedFiles.length} 個文件，提取了最相關的代碼片段`, + `任務相關文件摘要生成完成，已為 ${task.relatedFiles.length} 個文件生成摘要資訊`, task.id, - "相關文件加載完成" + "相關文件摘要生成完成" ); } catch (error) { - console.error("加載任務相關文件時發生錯誤:", error); + console.error("生成任務相關文件摘要時發生錯誤:", error); // 記錄錯誤 await addConversationEntry( ConversationParticipant.MCP, - `加載任務相關文件時發生錯誤: ${ + `生成任務相關文件摘要時發生錯誤: ${ error instanceof Error ? error.message : String(error) }`, task.id, - "相關文件加載錯誤" + "相關文件摘要生成錯誤" ); relatedFilesSummary = - "## 相關文件內容加載失敗\n\n加載文件時發生錯誤，請手動查看相關文件。"; + "## 相關文件摘要生成失敗\n\n生成文件摘要時發生錯誤，請手動查看相關文件。"; } } else { // 沒有相關文件的情況 @@ -837,7 +839,7 @@ export async function executeTask({ }); }); - prompt += `\n使用這些相關文件作為上下文，幫助您理解任務需求和實現細節。文件內容已經過智能提取，保留最相關的部分。\n`; + prompt += `\n使用這些相關文件作為上下文，幫助您理解任務需求和實現細節。系統已為文件生成摘要資訊，無需讀取實際檔案內容。\n`; } // 添加上下文信息