@lmcc-dev/mult-fetch-mcp-server 1.2.1 → 1.3.1

package/dist/src/lib/server/tools.js

@@ -7,6 +7,8 @@ import { CallToolRequestSchema, ListToolsRequestSchema } from '@modelcontextprot
 import { log, COMPONENTS } from '../logger.js';
 import { fetchWithAutoDetect } from './fetcher.js';
 import { closeBrowserInstance } from './browser.js';
+import { BaseFetcher } from '../fetchers/common/BaseFetcher.js';
+import { TemplateUtils } from '../utils/TemplateUtils.js';
 /**
  * 获取HTML获取工具定义 (Get HTML fetch tool definition)
  * @returns HTML获取工具定义 (HTML fetch tool definition)
@@ -14,7 +16,7 @@ import { closeBrowserInstance } from './browser.js';
 function getHtmlFetchToolDefinition() {
     return {
         name: "fetch_html",
-        description: "Fetch a website and return the content as HTML",
+        description: "Fetch a website and return the content as HTML. Best practices: 1) Always set startCursor=0 for initial requests, and use the fetchedBytes value from previous response for subsequent requests to ensure content continuity. 2) Set contentSizeLimit between 20000-50000 for large pages. 3) When handling large content, use the chunking system by following the startCursor instructions in the system notes rather than increasing contentSizeLimit. 4) If content retrieval fails, you can retry using the same chunkId and startCursor, or adjust startCursor as needed but you must handle any resulting data duplication or gaps yourself. 5) Always explain to users when content is chunked and ask if they want to continue retrieving subsequent parts.",
         inputSchema: {
             type: "object",
             properties: {
@@ -22,6 +24,10 @@ function getHtmlFetchToolDefinition() {
                     type: "string",
                     description: "URL of the website to fetch",
                 },
+                startCursor: {
+                    type: "number",
+                    description: "Starting cursor position in bytes. Set to 0 for initial requests, and use the value from previous responses for subsequent requests to resume content retrieval.",
+                },
                 headers: {
                     type: "object",
                     description: "Optional headers to include in the request",
@@ -56,7 +62,7 @@ function getHtmlFetchToolDefinition() {
                 },
                 autoDetectMode: {
                     type: "boolean",
-                    description: "Optional flag to automatically switch to browser mode if standard fetch fails (default: true)",
+                    description: "Optional flag to automatically switch to browser mode if standard fetch fails (default: true). Set to false to strictly use the specified mode without automatic switching.",
                 },
                 waitForSelector: {
                     type: "string",
@@ -78,8 +84,20 @@ function getHtmlFetchToolDefinition() {
                     type: "boolean",
                     description: "Optional flag to close the browser after fetching (default: false)",
                 },
+                contentSizeLimit: {
+                    type: "number",
+                    description: "Optional maximum content size in bytes before splitting into chunks (default: 50KB). Set between 20KB-50KB for optimal results. For large content, prefer smaller values (20KB-30KB) to avoid truncation.",
+                },
+                enableContentSplitting: {
+                    type: "boolean",
+                    description: "Optional flag to enable content splitting for large responses (default: true)",
+                },
+                chunkId: {
+                    type: "string",
+                    description: `Optional chunk ID for retrieving a specific chunk of content from a previous request. The system adds prompts in the format ${TemplateUtils.SYSTEM_NOTE.START} ... ${TemplateUtils.SYSTEM_NOTE.END} which AI models should ignore when processing the content.`,
+                },
             },
-            required: ["url"],
+            required: ["url", "startCursor"],
         },
     };
 }
@@ -90,7 +108,7 @@ function getHtmlFetchToolDefinition() {
 function getJsonFetchToolDefinition() {
     return {
         name: "fetch_json",
-        description: "Fetch a JSON file from a URL",
+        description: "Fetch a JSON file from a URL. Best practices: 1) Always set startCursor=0 for initial requests, and use the fetchedBytes value from previous response for subsequent requests to ensure content continuity. 2) Set contentSizeLimit between 20000-50000 for large files. 3) When handling large content, use the chunking system by following the startCursor instructions in the system notes rather than increasing contentSizeLimit. 4) If content retrieval fails, you can retry using the same chunkId and startCursor, or adjust startCursor as needed but you must handle any resulting data duplication or gaps yourself. 5) Always explain to users when content is chunked and ask if they want to continue retrieving subsequent parts.",
         inputSchema: {
             type: "object",
             properties: {
@@ -98,6 +116,10 @@ function getJsonFetchToolDefinition() {
                     type: "string",
                     description: "URL of the JSON to fetch",
                 },
+                startCursor: {
+                    type: "number",
+                    description: "Starting cursor position in bytes. Set to 0 for initial requests, and use the value from previous responses for subsequent requests to resume content retrieval.",
+                },
                 headers: {
                     type: "object",
                     description: "Optional headers to include in the request",
@@ -142,8 +164,20 @@ function getJsonFetchToolDefinition() {
                     type: "boolean",
                     description: "Optional flag to close the browser after fetching (default: false)",
                 },
+                contentSizeLimit: {
+                    type: "number",
+                    description: "Optional maximum content size in bytes before splitting into chunks (default: 50KB). Set between 20KB-50KB for optimal results. For large content, prefer smaller values (20KB-30KB) to avoid truncation.",
+                },
+                enableContentSplitting: {
+                    type: "boolean",
+                    description: "Optional flag to enable content splitting for large responses (default: true)",
+                },
+                chunkId: {
+                    type: "string",
+                    description: `Optional chunk ID for retrieving a specific chunk of content from a previous request. The system adds prompts in the format ${TemplateUtils.SYSTEM_NOTE.START} ... ${TemplateUtils.SYSTEM_NOTE.END} which AI models should ignore when processing the content.`,
+                },
             },
-            required: ["url"],
+            required: ["url", "startCursor"],
         },
     };
 }
@@ -154,7 +188,7 @@ function getJsonFetchToolDefinition() {
 function getTextFetchToolDefinition() {
     return {
         name: "fetch_txt",
-        description: "Fetch a website, return the content as plain text (no HTML)",
+        description: "Fetch a website, return the content as plain text (no HTML). Best practices: 1) Always set startCursor=0 for initial requests, and use the fetchedBytes value from previous response for subsequent requests to ensure content continuity. 2) Set contentSizeLimit between 20000-50000 for large pages. 3) When handling large content, use the chunking system by following the startCursor instructions in the system notes rather than increasing contentSizeLimit. 4) If content retrieval fails, you can retry using the same chunkId and startCursor, or adjust startCursor as needed but you must handle any resulting data duplication or gaps yourself. 5) Always explain to users when content is chunked and ask if they want to continue retrieving subsequent parts.",
         inputSchema: {
             type: "object",
             properties: {
@@ -162,6 +196,10 @@ function getTextFetchToolDefinition() {
                     type: "string",
                     description: "URL of the website to fetch",
                 },
+                startCursor: {
+                    type: "number",
+                    description: "Starting cursor position in bytes. Set to 0 for initial requests, and use the value from previous responses for subsequent requests to resume content retrieval.",
+                },
                 headers: {
                     type: "object",
                     description: "Optional headers to include in the request",
@@ -206,8 +244,20 @@ function getTextFetchToolDefinition() {
                     type: "boolean",
                     description: "Optional flag to scroll to bottom of page in browser mode (default: false)",
                 },
+                contentSizeLimit: {
+                    type: "number",
+                    description: "Optional maximum content size in bytes before splitting into chunks (default: 50KB). Set between 20KB-50KB for optimal results. For large content, prefer smaller values (20KB-30KB) to avoid truncation.",
+                },
+                enableContentSplitting: {
+                    type: "boolean",
+                    description: "Optional flag to enable content splitting for large responses (default: true)",
+                },
+                chunkId: {
+                    type: "string",
+                    description: `Optional chunk ID for retrieving a specific chunk of content from a previous request. The system adds prompts in the format ${TemplateUtils.SYSTEM_NOTE.START} ... ${TemplateUtils.SYSTEM_NOTE.END} which AI models should ignore when processing the content.`,
+                },
             },
-            required: ["url"],
+            required: ["url", "startCursor"],
         },
     };
 }
@@ -218,7 +268,7 @@ function getTextFetchToolDefinition() {
 function getMarkdownFetchToolDefinition() {
     return {
         name: "fetch_markdown",
-        description: "Fetch a website and return the content as Markdown",
+        description: "Fetch a website and return the content as Markdown. Best practices: 1) Always set startCursor=0 for initial requests, and use the fetchedBytes value from previous response for subsequent requests to ensure content continuity. 2) Set contentSizeLimit between 20000-50000 for large pages. 3) When handling large content, use the chunking system by following the startCursor instructions in the system notes rather than increasing contentSizeLimit. 4) If content retrieval fails, you can retry using the same chunkId and startCursor, or adjust startCursor as needed but you must handle any resulting data duplication or gaps yourself. 5) Always explain to users when content is chunked and ask if they want to continue retrieving subsequent parts.",
         inputSchema: {
             type: "object",
             properties: {
@@ -226,6 +276,10 @@ function getMarkdownFetchToolDefinition() {
                     type: "string",
                     description: "URL of the website to fetch",
                 },
+                startCursor: {
+                    type: "number",
+                    description: "Starting cursor position in bytes. Set to 0 for initial requests, and use the value from previous responses for subsequent requests to resume content retrieval.",
+                },
                 headers: {
                     type: "object",
                     description: "Optional headers to include in the request",
@@ -270,8 +324,112 @@ function getMarkdownFetchToolDefinition() {
                     type: "boolean",
                     description: "Optional flag to scroll to bottom of page in browser mode (default: false)",
                 },
+                contentSizeLimit: {
+                    type: "number",
+                    description: "Optional maximum content size in bytes before splitting into chunks (default: 50KB). Set between 20KB-50KB for optimal results. For large content, prefer smaller values (20KB-30KB) to avoid truncation.",
+                },
+                enableContentSplitting: {
+                    type: "boolean",
+                    description: "Optional flag to enable content splitting for large responses (default: true)",
+                },
+                chunkId: {
+                    type: "string",
+                    description: `Optional chunk ID for retrieving a specific chunk of content from a previous request. The system adds prompts in the format ${TemplateUtils.SYSTEM_NOTE.START} ... ${TemplateUtils.SYSTEM_NOTE.END} which AI models should ignore when processing the content.`,
+                },
+            },
+            required: ["url", "startCursor"],
+        },
+    };
+}
+/**
+ * 获取纯文本获取工具定义 (Get plain text fetch tool definition)
+ * @returns 纯文本获取工具定义 (Plain text fetch tool definition)
+ */
+function getPlainTextFetchToolDefinition() {
+    return {
+        name: "fetch_plaintext",
+        description: "Fetch a website and return the content as plain text with HTML tags removed. Best practices: 1) Always set startCursor=0 for initial requests, and use the fetchedBytes value from previous response for subsequent requests to ensure content continuity. 2) Set contentSizeLimit between 20000-50000 for large pages. 3) When handling large content, use the chunking system by following the startCursor instructions in the system notes rather than increasing contentSizeLimit. 4) If content retrieval fails, you can retry using the same chunkId and startCursor, or adjust startCursor as needed but you must handle any resulting data duplication or gaps yourself. 5) Always explain to users when content is chunked and ask if they want to continue retrieving subsequent parts.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                url: {
+                    type: "string",
+                    description: "URL of the website to fetch",
+                },
+                startCursor: {
+                    type: "number",
+                    description: "Starting cursor position in bytes. Set to 0 for initial requests, and use the value from previous responses for subsequent requests to resume content retrieval.",
+                },
+                headers: {
+                    type: "object",
+                    description: "Optional headers to include in the request",
+                },
+                proxy: {
+                    type: "string",
+                    description: "Optional proxy server to use (format: http://host:port or https://host:port)",
+                },
+                noDelay: {
+                    type: "boolean",
+                    description: "Optional flag to disable random delay between requests (default: false)",
+                },
+                timeout: {
+                    type: "number",
+                    description: "Optional timeout in milliseconds (default: 30000)",
+                },
+                maxRedirects: {
+                    type: "number",
+                    description: "Optional maximum number of redirects to follow (default: 10)",
+                },
+                useSystemProxy: {
+                    type: "boolean",
+                    description: "Optional flag to use system proxy environment variables (default: true)",
+                },
+                debug: {
+                    type: "boolean",
+                    description: "Optional flag to enable detailed debug logging (default: false)",
+                },
+                useBrowser: {
+                    type: "boolean",
+                    description: "Optional flag to use headless browser for fetching (default: false)",
+                },
+                autoDetectMode: {
+                    type: "boolean",
+                    description: "Optional flag to automatically switch to browser mode if standard fetch fails (default: true). Set to false to strictly use the specified mode without automatic switching.",
+                },
+                waitForSelector: {
+                    type: "string",
+                    description: "Optional CSS selector to wait for when using browser mode",
+                },
+                waitForTimeout: {
+                    type: "number",
+                    description: "Optional timeout to wait after page load in browser mode (default: 5000)",
+                },
+                scrollToBottom: {
+                    type: "boolean",
+                    description: "Optional flag to scroll to bottom of page in browser mode (default: false)",
+                },
+                saveCookies: {
+                    type: "boolean",
+                    description: "Optional flag to save cookies for future requests to the same domain (default: true)",
+                },
+                closeBrowser: {
+                    type: "boolean",
+                    description: "Optional flag to close the browser after fetching (default: false)",
+                },
+                contentSizeLimit: {
+                    type: "number",
+                    description: "Optional maximum content size in bytes before splitting into chunks (default: 50KB). Set between 20KB-50KB for optimal results. For large content, prefer smaller values (20KB-30KB) to avoid truncation.",
+                },
+                enableContentSplitting: {
+                    type: "boolean",
+                    description: "Optional flag to enable content splitting for large responses (default: true)",
+                },
+                chunkId: {
+                    type: "string",
+                    description: `Optional chunk ID for retrieving a specific chunk of content from a previous request. The system adds prompts in the format ${TemplateUtils.SYSTEM_NOTE.START} ... ${TemplateUtils.SYSTEM_NOTE.END} which AI models should ignore when processing the content.`,
+                },
             },
-            required: ["url"],
+            required: ["url", "startCursor"],
         },
     };
 }
@@ -284,7 +442,8 @@ function getAllToolDefinitions() {
         getHtmlFetchToolDefinition(),
         getJsonFetchToolDefinition(),
         getTextFetchToolDefinition(),
-        getMarkdownFetchToolDefinition()
+        getMarkdownFetchToolDefinition(),
+        getPlainTextFetchToolDefinition()
     ];
 }
 /**
@@ -310,7 +469,7 @@ function registerToolCallHandler(server) {
         log('tools.callReceived', debug, { name, args: JSON.stringify(args) }, COMPONENTS.SERVER);
         try {
             // 处理不同类型的获取请求 (Handle different types of fetch requests)
-            if (name === 'fetch_html' || name === 'fetch_json' || name === 'fetch_txt' || name === 'fetch_markdown') {
+            if (name === 'fetch_html' || name === 'fetch_json' || name === 'fetch_txt' || name === 'fetch_markdown' || name === 'fetch_plaintext') {
                 const result = await handleFetchRequest(name, args, debug);
                 // 直接返回符合 MCP SDK 要求的格式
                 return result;
@@ -318,29 +477,13 @@ function registerToolCallHandler(server) {
             else {
                 // 未知工具 (Unknown tool)
                 log('tools.unknownTool', debug, { name }, COMPONENTS.SERVER);
-                return {
-                    content: [
-                        {
-                            type: "text",
-                            text: `Unknown tool: ${name}`
-                        }
-                    ],
-                    isError: true
-                };
+                return BaseFetcher.createErrorResponse(`Unknown tool: ${name}`);
             }
         }
         catch (error) {
             // 处理错误 (Handle error)
             log('tools.callError', debug, { name, error: error.message }, COMPONENTS.SERVER);
-            return {
-                content: [
-                    {
-                        type: "text",
-                        text: error.message
-                    }
-                ],
-                isError: true
-            };
+            return BaseFetcher.createErrorResponse(`Error fetching ${args.url || `chunk ${args.chunkId}`}: ${error.message}`);
         }
         finally {
             // 如果请求参数中指定了关闭浏览器，则关闭浏览器 (If request parameters specify to close browser, close browser)
@@ -359,20 +502,22 @@ function registerToolCallHandler(server) {
  */
 async function handleFetchRequest(name, args, debug) {
     // 验证URL参数 (Validate URL parameter)
-    if (!args.url) {
-        log('tools.missingUrl', debug, {}, COMPONENTS.SERVER);
-        return {
-            content: [
-                {
-                    type: "text",
-                    text: "URL parameter is required"
-                }
-            ],
-            isError: true
-        };
+    if (!args.url && !args.chunkId) {
+        log('tools.missingUrlOrChunkId', debug, {}, COMPONENTS.SERVER);
+        return BaseFetcher.createErrorResponse("Either URL or chunkId parameter is required");
+    }
+    // 验证startCursor参数 (Validate startCursor parameter)
+    if (args.startCursor === undefined) {
+        log('tools.missingStartCursor', debug, {}, COMPONENTS.SERVER);
+        return BaseFetcher.createErrorResponse("startCursor parameter is required. Use 0 for initial requests.");
     }
     // 记录请求 (Log request)
-    log('tools.fetchRequest', debug, { url: args.url, type: name }, COMPONENTS.SERVER);
+    if (args.chunkId) {
+        log('tools.fetchChunkRequest', debug, { chunkId: args.chunkId, startCursor: args.startCursor, type: name }, COMPONENTS.SERVER);
+    }
+    else {
+        log('tools.fetchRequest', debug, { url: args.url, startCursor: args.startCursor, type: name }, COMPONENTS.SERVER);
+    }
     // 执行获取请求 (Execute fetch request)
     try {
         const params = {
@@ -381,7 +526,7 @@ async function handleFetchRequest(name, args, debug) {
         };
         // 根据工具名称确定内容类型 (Determine content type based on tool name)
         const type = name.replace('fetch_', '');
-        const result = await fetchWithAutoDetect(params, type);
+        let result = await fetchWithAutoDetect(params, type);
         // 确保返回标准结构体 (Ensure returning standard structure)
         if (result.isError) {
             // 确保错误内容有正确的类型 (Ensure error content has correct type)
@@ -407,6 +552,19 @@ async function handleFetchRequest(name, args, debug) {
             if (!result.content[0].type) {
                 result.content[0].type = "text";
             }
+            // 如果内容是分段的，添加提示词 (If content is chunked, add prompt)
+            if (result.isChunked && result.hasMoreChunks) {
+                // 检查内容中是否已经包含系统提示，避免重复添加
+                // Check if content already contains system note to avoid duplicate
+                if (!TemplateUtils.hasSystemPrompt(result.content[0].text || '')) {
+                    // 使用BaseFetcher的addChunkPrompt方法添加提示词 (Use BaseFetcher's addChunkPrompt method to add prompt)
+                    result = BaseFetcher.addChunkPrompt(result);
+                }
+            }
+        }
+        // 如果没有匹配的类型，返回错误
+        if (!result.content[0].type) {
+            return BaseFetcher.createErrorResponse(`Unsupported content type: ${type}`);
         }
         // 将FetchResponse转换为符合MCP SDK要求的格式
         return {
@@ -417,16 +575,8 @@ async function handleFetchRequest(name, args, debug) {
     catch (error) {
         // 处理错误 (Handle error)
         log('tools.fetchError', debug, { url: args.url, error: error.message }, COMPONENTS.SERVER);
-        // 确保返回标准结构体 (Ensure returning standard structure)
-        return {
-            content: [
-                {
-                    type: "text",
-                    text: `Error fetching ${args.url}: ${error.message}`
-                }
-            ],
-            isError: true
-        };
+        // 返回错误信息 (Return error message)
+        return BaseFetcher.createErrorResponse(`Error fetching ${args.url || `chunk ${args.chunkId}`}: ${error.message}`);
     }
 }
 /**

package/dist/src/lib/types.js

@@ -32,4 +32,9 @@ export const RequestPayloadSchema = z.object({
     waitForTimeout: z.number().optional(),
     scrollToBottom: z.boolean().optional(),
     closeBrowser: z.boolean().optional(),
+    chunkId: z.string().optional(),
+    chunkIndex: z.number().optional(),
+    contentSizeLimit: z.number().optional(),
+    startCursor: z.number().optional(),
+    enableContentSplitting: z.boolean().optional(),
 }).merge(BrowserParamsSchema);

package/dist/src/lib/utils/ChunkManager.js

@@ -0,0 +1,177 @@
+/**
+ * Author: Martin <lmccc.dev@gmail.com>
+ * Co-Author: AI Assistant (Claude)
+ * Description: This code was collaboratively developed by Martin and AI Assistant.
+ */
+import { log, COMPONENTS } from '../logger.js';
+import { v4 as uuidv4 } from 'uuid';
+/**
+ * 分段内容管理器 (Chunk content manager)
+ * 用于存储和管理分段内容 (Used to store and manage chunked content)
+ */
+export class ChunkManager {
+    /**
+     * 存储分段内容的Map (Map to store chunked content)
+     * 键为分段ID，值为分段内容数组 (Key is chunk ID, value is array of chunk content)
+     */
+    static chunks = new Map();
+    /**
+     * 存储分段内容大小信息的Map (Map to store chunk size information)
+     * 键为分段ID，值为{totalBytes, fetchedBytes}对象 (Key is chunk ID, value is {totalBytes, fetchedBytes} object)
+     */
+    static sizeInfo = new Map();
+    /**
+     * 分段内容的过期时间（毫秒） (Expiration time for chunked content in milliseconds)
+     * 默认为10分钟 (Default is 10 minutes)
+     */
+    static EXPIRATION_TIME = 10 * 60 * 1000; // 10分钟
+    /**
+     * 分段内容的过期时间Map (Map to store expiration time for chunked content)
+     * 键为分段ID，值为过期时间戳 (Key is chunk ID, value is expiration timestamp)
+     */
+    static expirations = new Map();
+    /**
+     * 存储分段内容 (Store chunked content)
+     * @param chunks 分段内容数组 (Array of chunk content)
+     * @param totalBytes 原始内容总字节数 (Total bytes of original content)
+     * @param debug 是否启用调试模式 (Whether debug mode is enabled)
+     * @returns 分段ID (Chunk ID)
+     */
+    static storeChunks(chunks, totalBytes, debug = false) {
+        // 清理过期的分段内容 (Clean up expired chunks)
+        this.cleanupExpiredChunks(debug);
+        // 生成唯一的分段ID (Generate unique chunk ID)
+        const chunkId = uuidv4();
+        // 计算每个分块的字节大小 (Calculate byte size of each chunk)
+        const chunkSizes = chunks.map(chunk => Buffer.byteLength(chunk, 'utf8'));
+        // 存储分段内容 (Store chunked content)
+        this.chunks.set(chunkId, chunks);
+        // 存储分段大小信息 (Store chunk size information)
+        this.sizeInfo.set(chunkId, {
+            totalBytes,
+            fetchedBytes: chunkSizes
+        });
+        // 设置过期时间 (Set expiration time)
+        const expirationTime = Date.now() + this.EXPIRATION_TIME;
+        this.expirations.set(chunkId, expirationTime);
+        log('chunkManager.storedChunks', debug, {
+            chunkId,
+            count: chunks.length,
+            totalChunks: chunks.length,
+            totalBytes,
+            expiresAt: new Date(expirationTime).toISOString()
+        }, COMPONENTS.CHUNK_MANAGER);
+        return chunkId;
+    }
+    /**
+     * 获取分段内容 (Get chunked content)
+     * @param chunkId 分段ID (Chunk ID)
+     * @param startCursor 开始游标位置，指示从哪个字节开始获取 (Start cursor position, indicating from which byte to start fetching)
+     * @param sizeLimit 本次获取的最大字节数 (Maximum bytes to fetch in this request)
+     * @param debug 是否启用调试模式 (Whether debug mode is enabled)
+     * @returns 分段内容，包含获取信息 (Chunk content with fetch information)
+     */
+    static getChunkBySize(chunkId, startCursor = 0, sizeLimit = 50 * 1024, debug = false) {
+        // 检查分段ID是否存在 (Check if chunk ID exists)
+        if (!this.chunks.has(chunkId) || !this.sizeInfo.has(chunkId)) {
+            log('chunkManager.chunkIdNotFound', debug, { chunkId }, COMPONENTS.CHUNK_MANAGER);
+            return null;
+        }
+        // 获取分段内容数组和大小信息 (Get chunked content array and size information)
+        const chunks = this.chunks.get(chunkId);
+        const { totalBytes, fetchedBytes } = this.sizeInfo.get(chunkId);
+        // 验证startCursor是否有效 (Validate if startCursor is valid)
+        if (startCursor < 0 || startCursor >= totalBytes) {
+            log('chunkManager.invalidStartCursor', debug, {
+                chunkId,
+                startCursor,
+                totalBytes
+            }, COMPONENTS.CHUNK_MANAGER);
+            return null;
+        }
+        // 计算当前位置和每个分块的起始位置 (Calculate current position and start position of each chunk)
+        let currentPosition = 0;
+        let chunkIndex = 0;
+        let fetchedSoFar = 0;
+        let resultContent = '';
+        // 找到开始位置对应的分块 (Find the chunk corresponding to the start position)
+        for (let i = 0; i < fetchedBytes.length; i++) {
+            if (currentPosition + fetchedBytes[i] > startCursor) {
+                chunkIndex = i;
+                break;
+            }
+            fetchedSoFar += fetchedBytes[i];
+            currentPosition += fetchedBytes[i];
+        }
+        // 从找到的分块开始，读取指定大小的内容 (Start reading from the found chunk, up to the specified size)
+        let bytesToFetch = sizeLimit;
+        let bytesActuallyFetched = 0;
+        while (chunkIndex < chunks.length && bytesToFetch > 0) {
+            resultContent += chunks[chunkIndex];
+            bytesActuallyFetched += fetchedBytes[chunkIndex];
+            bytesToFetch -= fetchedBytes[chunkIndex];
+            chunkIndex++;
+        }
+        // 计算总获取字节数和剩余字节数 (Calculate total fetched bytes and remaining bytes)
+        const totalFetchedBytes = startCursor + bytesActuallyFetched;
+        const remainingBytes = totalBytes - totalFetchedBytes;
+        const isLastChunk = (remainingBytes <= 0);
+        log('chunkManager.retrievedChunkBySize', debug, {
+            chunkId,
+            startCursor,
+            size: sizeLimit,
+            bytesRequested: sizeLimit,
+            bytesRetrieved: bytesActuallyFetched,
+            totalFetchedBytes,
+            remainingBytes,
+            isLastChunk
+        }, COMPONENTS.CHUNK_MANAGER);
+        // 返回内容和获取信息 (Return content and fetch information)
+        return {
+            content: resultContent,
+            fetchedBytes: totalFetchedBytes,
+            remainingBytes,
+            isLastChunk,
+            totalBytes
+        };
+    }
+    /**
+     * 获取分段大小信息 (Get chunk size information)
+     * @param chunkId 分段ID (Chunk ID)
+     * @param debug 是否启用调试模式 (Whether debug mode is enabled)
+     * @returns 分段大小信息 (Chunk size information)
+     */
+    static getSizeInfo(chunkId, debug = false) {
+        // 检查分段ID是否存在 (Check if chunk ID exists)
+        if (!this.sizeInfo.has(chunkId)) {
+            log('chunkManager.sizeInfoNotFound', debug, { chunkId }, COMPONENTS.CHUNK_MANAGER);
+            return null;
+        }
+        // 返回分段大小信息 (Return chunk size information)
+        return this.sizeInfo.get(chunkId);
+    }
+    /**
+     * 清理过期的分段内容 (Clean up expired chunks)
+     * @param debug 是否启用调试模式 (Whether debug mode is enabled)
+     */
+    static cleanupExpiredChunks(debug = false) {
+        const now = Date.now();
+        let expiredCount = 0;
+        // 遍历所有分段ID (Iterate through all chunk IDs)
+        for (const [chunkId, expirationTime] of this.expirations.entries()) {
+            // 如果分段内容已过期，则删除 (If chunk content has expired, delete it)
+            if (expirationTime < now) {
+                this.chunks.delete(chunkId);
+                this.sizeInfo.delete(chunkId);
+                this.expirations.delete(chunkId);
+                expiredCount++;
+            }
+        }
+        if (expiredCount > 0) {
+            log('chunkManager.cleanedUpExpiredChunks', debug, {
+                expiredCount,
+                remainingChunks: this.chunks.size
+            }, COMPONENTS.CHUNK_MANAGER);
+        }
+    }
+}