@ai-zen/agents-sdk 0.7.0 → 0.7.1

package/CHANGELOG.md

@@ -1,5 +1,15 @@
 # Changelog
 
+## [0.7.1] - 2026-08-25
+
+### 🚀 New Features
+
+- **`FindTextTool` (findText) gains three-layer output protection** — prevents search results from blowing up the context window:
+  - **`maxMatches`** (default 200) — caps the total number of matches; once reached, scanning stops and the result is marked `truncated`
+  - **`maxFileSize`** (default 300KB, aligned with `ReadFileTool`) — files larger than this are **skipped** rather than rejected, so an oversized file doesn't block the whole search
+  - **`maxLineLength`** (default 200) — each matched line's `content` and the regex `match` substring are truncated (with a trailing `…`)
+  - All three are optional parameters that can be overridden by the caller; when truncated the result returns `{ truncated: true, totalMatches, results }`, while non-truncated results keep the original JSON array shape (backward compatible)
+
 ## [0.7.0] - 2026-08-14
 
 ### ⚠️ Breaking

package/dist/capabilities/implements/builtin/FindTextTool.d.ts

@@ -10,5 +10,8 @@ export declare class FindTextTool extends SdkCallbackTool {
         text?: string;
         regex?: string;
         exclude?: string[];
+        maxMatches?: number;
+        maxFileSize?: number;
+        maxLineLength?: number;
     }, ctx?: ToolCallContext): Promise<string>;
 }

package/dist/capabilities/implements/builtin/FindTextTool.js

@@ -1,10 +1,16 @@
 import * as fsp from "fs/promises";
 import * as path from "path";
 import { SdkCallbackTool } from "../../../runtime/SdkCallbackTool.js";
+/** 默认总匹配数上限 */
+const DEFAULT_MAX_MATCHES = 200;
+/** 默认文件大小上限（字节，与 ReadFileTool 的 300KB 口径一致） */
+const DEFAULT_MAX_FILE_SIZE = 300 * 1024;
+/** 默认行内容/匹配子串截断长度 */
+const DEFAULT_MAX_LINE_LENGTH = 200;
 export class FindTextTool extends SdkCallbackTool {
     function = {
         name: "findText",
-        description: "查找文本出现的位置，支持普通文本或正则匹配，返回文件名及具体行号、行内容",
+        description: "查找文本出现的位置，支持普通文本或正则匹配，返回文件名及具体行号、行内容。为避免结果撑爆上下文，默认限制总匹配数、单文件大小与行内容长度，超限会截断并标记 truncated。",
         parameters: {
             type: "object",
             properties: {
@@ -31,6 +37,18 @@ export class FindTextTool extends SdkCallbackTool {
                         type: "string",
                     },
                 },
+                maxMatches: {
+                    type: "number",
+                    description: "总匹配数上限，默认 200",
+                },
+                maxFileSize: {
+                    type: "number",
+                    description: "单文件大小上限（字节），超过则跳过该文件，默认 307200（300KB）",
+                },
+                maxLineLength: {
+                    type: "number",
+                    description: "行内容与匹配子串的截断长度，默认 200",
+                },
             },
             required: ["path", "pattern"],
         },
@@ -49,48 +67,70 @@ export class FindTextTool extends SdkCallbackTool {
                 return "请提供 text 或 regex 参数";
             }
             const regex = regexStr ? new RegExp(regexStr) : null;
+            const maxMatches = input.maxMatches ?? DEFAULT_MAX_MATCHES;
+            const maxFileSize = input.maxFileSize ?? DEFAULT_MAX_FILE_SIZE;
+            const maxLineLength = input.maxLineLength ?? DEFAULT_MAX_LINE_LENGTH;
+            let totalMatches = 0;
+            let truncated = false;
             for await (const file of fsp.glob(input.pattern, {
                 cwd,
                 exclude: input.exclude || ["**/node_modules/**"],
             })) {
                 if (signal?.aborted)
                     break; // 中断：停止继续遍历/消费
+                if (totalMatches >= maxMatches) {
+                    truncated = true;
+                    break;
+                }
                 const fullPath = path.join(cwd, file);
                 const stats = await fsp.stat(fullPath);
                 if (signal?.aborted)
                     break; // 中断：stat 后再次检查
-                if (stats.isFile()) {
-                    const content = await fsp.readFile(fullPath, "utf-8");
-                    if (signal?.aborted)
-                        break; // 中断：readFile 后再次检查
-                    const lines = content.split("\n");
-                    const matches = [];
-                    lines.forEach((lineContent, index) => {
-                        if (regex) {
-                            const matchResult = lineContent.match(regex);
-                            if (matchResult) {
-                                matches.push({
-                                    line: index + 1,
-                                    content: lineContent,
-                                    match: matchResult[0],
-                                });
-                            }
-                        }
-                        else if (lineContent.includes(text)) {
+                if (!stats.isFile())
+                    continue;
+                // 文件过大则跳过（避免撑爆上下文；与 ReadFileTool 300KB 口径一致，但此处为跳过而非报错）
+                if (stats.size > maxFileSize)
+                    continue;
+                const content = await fsp.readFile(fullPath, "utf-8");
+                if (signal?.aborted)
+                    break; // 中断：readFile 后再次检查
+                const lines = content.split("\n");
+                const matches = [];
+                for (let index = 0; index < lines.length; index++) {
+                    if (totalMatches >= maxMatches) {
+                        truncated = true;
+                        break;
+                    }
+                    const lineContent = lines[index];
+                    if (regex) {
+                        const matchResult = lineContent.match(regex);
+                        if (matchResult) {
                             matches.push({
                                 line: index + 1,
-                                content: lineContent,
+                                content: truncate(lineContent, maxLineLength),
+                                match: truncate(matchResult[0], maxLineLength),
                             });
+                            totalMatches++;
                         }
-                    });
-                    if (matches.length > 0) {
-                        result.push({ file, matches });
                     }
+                    else if (lineContent.includes(text)) {
+                        matches.push({
+                            line: index + 1,
+                            content: truncate(lineContent, maxLineLength),
+                        });
+                        totalMatches++;
+                    }
+                }
+                if (matches.length > 0) {
+                    result.push({ file, matches });
                 }
             }
             if (signal?.aborted) {
                 return JSON.stringify({ aborted: true, results: result });
             }
+            if (truncated) {
+                return JSON.stringify({ truncated: true, totalMatches, results: result });
+            }
             return JSON.stringify(result);
         }
         catch (error) {
@@ -98,3 +138,9 @@ export class FindTextTool extends SdkCallbackTool {
         }
     }
 }
+/** 截断字符串到指定长度，超出部分以 "…" 结尾标记 */
+function truncate(s, max) {
+    if (s.length <= max)
+        return s;
+    return s.slice(0, max) + "…";
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ai-zen/agents-sdk",
-  "version": "0.7.0",
+  "version": "0.7.1",
   "description": "AI-Zen Agents SDK — shared business logic for CLI and Desktop",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",