@ai-zen/agents-sdk 0.11.0 → 1.0.0-alpha.0

package/dist/scope/ScopePlugin.d.ts

@@ -0,0 +1,51 @@
+import type { Tool } from "@ai-zen/agents-core";
+import type { AgentDefinition } from "../types/index.js";
+import type { Scope, FilterOutput } from "./Scope.js";
+/**
+ * 插件向四维权限体系贡献的候选名称（任意子集）。
+ */
+export interface ScopeCandidates {
+    tools?: string[];
+    skills?: string[];
+    mcps?: string[];
+    subagents?: string[];
+}
+/**
+ * ScopePlugin — 能力插件契约（v1 核心扩展点）。
+ *
+ * 一个插件**自持一类能力**的完整生命周期：自己发现、自己持有发现结果、
+ * 自己声明候选名、自己按过滤结果实例化工具、自己负责释放。
+ * `Scope` 只做编排，不感知任何具体能力的发现状态。
+ *
+ * 与 `AgentPlugin`（core，挂在 Agent 运行时 send/loop/toolcall）不同，
+ * `ScopePlugin` 挂在**能力装配管线**（discover/filter/instantiate）。二者互不相关。
+ *
+ * 生命周期与三阶段管线的对应：
+ *   discover     —— 阶段 1 · 发现
+ *   candidates   —— 阶段 2 · 候选（供权限过滤）
+ *   instantiate  —— 阶段 3 · 实例化
+ *   dispose      —— 释放
+ */
+export interface ScopePlugin {
+    /** 唯一标识，如 "builtin" / "user-tools" / "skills" / "mcp" / "subagents" */
+    readonly id: string;
+    /**
+     * 阶段 1 · 发现：扫描来源、刷新自身状态（每次内部重新扫描，不跨 refresh 累积）。
+     * 相对路径应在此基于 `scope.cwd` 解析。
+     */
+    discover?(scope: Scope, options: {
+        silent?: boolean;
+    }): Promise<void> | void;
+    /**
+     * 阶段 2 · 候选：返回本插件向四维贡献的候选名。
+     * 可结合 `definition` 做可用性判断（如内置工具的 isAvailable）。同步返回。
+     */
+    candidates(scope: Scope, definition: AgentDefinition): ScopeCandidates;
+    /**
+     * 阶段 3 · 实例化：按过滤后的允许名产出 Tool 实例。
+     * `filtered` 为 `Scope.filter()` 的产物（四维允许名）。
+     */
+    instantiate(scope: Scope, filtered: FilterOutput): Tool[];
+    /** 可选 · 释放：逆序于注册顺序调用。如 MCP 断开所有连接。 */
+    dispose?(): Promise<void> | void;
+}

package/dist/scope/ScopePlugin.js

@@ -0,0 +1 @@
+export {};

package/dist/scope/plugins/allInOne.d.ts

@@ -0,0 +1,18 @@
+import type { ScopePlugin } from "../ScopePlugin.js";
+/** allInOne 的装配选项：各类能力来源的路径（绝对或相对 scope.cwd） */
+export interface AllInOneOptions {
+    skillsPaths?: string[];
+    toolsPaths?: string[];
+    subAgentsPaths?: string[];
+    mcpPaths?: string[];
+}
+/**
+ * 标准能力插件工厂 —— 恒返回 5 个标准插件（"全家桶"）。
+ *
+ * 顺序即优先级（去重时后注册覆盖先注册）：
+ *   builtin → user-tools → skills → mcp → subagents
+ * 因此用户工具可覆盖同名内置工具（与 v0 一致）。
+ *
+ * 想裁剪/替换某一类，改用手工逐个 `new XxxScopePlugin(...)` 后 `.use()`。
+ */
+export declare function allInOne(options?: AllInOneOptions): ScopePlugin[];

package/dist/scope/plugins/allInOne.js

@@ -0,0 +1,23 @@
+import { BuiltinToolsScopePlugin } from "./builtin/BuiltinToolsScopePlugin.js";
+import { UserToolsScopePlugin } from "./usertools/UserToolsScopePlugin.js";
+import { SkillsScopePlugin } from "./skills/SkillsScopePlugin.js";
+import { McpScopePlugin } from "./mcp/McpScopePlugin.js";
+import { SubAgentsScopePlugin } from "./subagents/SubAgentsScopePlugin.js";
+/**
+ * 标准能力插件工厂 —— 恒返回 5 个标准插件（"全家桶"）。
+ *
+ * 顺序即优先级（去重时后注册覆盖先注册）：
+ *   builtin → user-tools → skills → mcp → subagents
+ * 因此用户工具可覆盖同名内置工具（与 v0 一致）。
+ *
+ * 想裁剪/替换某一类，改用手工逐个 `new XxxScopePlugin(...)` 后 `.use()`。
+ */
+export function allInOne(options) {
+    return [
+        new BuiltinToolsScopePlugin(),
+        new UserToolsScopePlugin({ paths: options?.toolsPaths }),
+        new SkillsScopePlugin({ paths: options?.skillsPaths }),
+        new McpScopePlugin({ paths: options?.mcpPaths }),
+        new SubAgentsScopePlugin({ paths: options?.subAgentsPaths }),
+    ];
+}

package/dist/{capabilities/implements → scope/plugins}/builtin/BatchEditTool.d.ts

@@ -1,4 +1,4 @@
-import { SdkCallbackTool } from "../../../runtime/SdkCallbackTool.js";
+import { SdkCallbackTool } from "./SdkCallbackTool.js";
 import type { ToolEnv } from "../../../types/index.js";
 import type { AgentNS } from "@ai-zen/agents-core";
 interface Replacement {

package/dist/{capabilities/implements → scope/plugins}/builtin/BatchEditTool.js

@@ -1,5 +1,5 @@
 import * as fsp from "fs/promises";
-import { SdkCallbackTool } from "../../../runtime/SdkCallbackTool.js";
+import { SdkCallbackTool } from "./SdkCallbackTool.js";
 export class BatchEditTool extends SdkCallbackTool {
     function = {
         name: "batchEdit",
@@ -48,13 +48,16 @@ export class BatchEditTool extends SdkCallbackTool {
             const filePath = this.resolve(input.path);
             const content = await fsp.readFile(filePath, "utf-8");
             let newContent = content;
-            const results = [];
+            let replacedCount = 0;
+            // 仅回显"有问题"的替换项（未匹配到），便于模型据此修正；
+            // 成功项不回显原文与新文，仅计入成功数，避免大段文本回显撑大输出
+            const failed = [];
             for (const replacement of input.replacements) {
                 if (!newContent.includes(replacement.oldText)) {
-                    results.push({
+                    failed.push({
                         oldText: replacement.oldText,
                         newText: replacement.newText,
-                        result: "文件中未精确匹配到要替换的文本",
+                        reason: "文件中未精确匹配到要替换的文本",
                     });
                     continue;
                 }
@@ -64,14 +67,13 @@ export class BatchEditTool extends SdkCallbackTool {
                 else {
                     newContent = newContent.replace(replacement.oldText, replacement.newText);
                 }
-                results.push({
-                    oldText: replacement.oldText,
-                    newText: replacement.newText,
-                    result: "success",
-                });
+                replacedCount++;
             }
             await fsp.writeFile(filePath, newContent);
-            return JSON.stringify(results);
+            if (failed.length === 0) {
+                return JSON.stringify({ result: "success", replacedCount });
+            }
+            return JSON.stringify({ result: "partial", replacedCount, failed });
         }
         catch (error) {
             return error?.message;

package/dist/scope/plugins/builtin/BuiltinToolsScopePlugin.d.ts

@@ -0,0 +1,20 @@
+import type { Tool } from "@ai-zen/agents-core";
+import type { AgentDefinition } from "../../../types/index.js";
+import type { Scope, FilterOutput } from "../../Scope.js";
+import type { ScopeCandidates, ScopePlugin } from "../../ScopePlugin.js";
+/**
+ * 内置工具插件 —— 20 个内置工具类（BUILTIN_TOOL_CLASSES）。
+ *
+ * 发现层零过滤；可用性由各工具 `isAvailable(config, definition)` 自陈，
+ * 在本插件 `candidates()` 阶段按声明剔除（如 GenerateImageTool 依赖 defaultImageModel、
+ * ViewImageTool 仅视觉模型可用）。
+ */
+export declare class BuiltinToolsScopePlugin implements ScopePlugin {
+    static readonly ID = "builtin";
+    readonly id = "builtin";
+    /** 发现结果自持（每次 discover 重新实例化） */
+    private tools;
+    discover(scope: Scope): void;
+    candidates(scope: Scope, definition: AgentDefinition): ScopeCandidates;
+    instantiate(_scope: Scope, filtered: FilterOutput): Tool[];
+}

package/dist/scope/plugins/builtin/BuiltinToolsScopePlugin.js

@@ -0,0 +1,30 @@
+import { discoverBuiltinTools } from "./discover.js";
+/**
+ * 内置工具插件 —— 20 个内置工具类（BUILTIN_TOOL_CLASSES）。
+ *
+ * 发现层零过滤；可用性由各工具 `isAvailable(config, definition)` 自陈，
+ * 在本插件 `candidates()` 阶段按声明剔除（如 GenerateImageTool 依赖 defaultImageModel、
+ * ViewImageTool 仅视觉模型可用）。
+ */
+export class BuiltinToolsScopePlugin {
+    static ID = "builtin";
+    id = BuiltinToolsScopePlugin.ID;
+    /** 发现结果自持（每次 discover 重新实例化） */
+    tools = [];
+    discover(scope) {
+        this.tools = discoverBuiltinTools(scope.env);
+    }
+    candidates(scope, definition) {
+        const tools = this.tools
+            .filter((t) => {
+            const isAvailable = t?.isAvailable;
+            return isAvailable ? isAvailable(scope.config, definition) : true;
+        })
+            .map((t) => t.function.name);
+        return { tools };
+    }
+    instantiate(_scope, filtered) {
+        const allow = new Set(filtered.tools);
+        return this.tools.filter((t) => allow.has(t.function.name));
+    }
+}

package/dist/{capabilities/implements → scope/plugins}/builtin/CopyTool.d.ts

@@ -1,4 +1,4 @@
-import { SdkCallbackTool } from "../../../runtime/SdkCallbackTool.js";
+import { SdkCallbackTool } from "./SdkCallbackTool.js";
 import type { ToolEnv } from "../../../types/index.js";
 import type { AgentNS } from "@ai-zen/agents-core";
 export declare class CopyTool extends SdkCallbackTool {

package/dist/{capabilities/implements → scope/plugins}/builtin/CopyTool.js

@@ -1,5 +1,5 @@
 import * as fsp from "fs/promises";
-import { SdkCallbackTool } from "../../../runtime/SdkCallbackTool.js";
+import { SdkCallbackTool } from "./SdkCallbackTool.js";
 export class CopyTool extends SdkCallbackTool {
     function = {
         name: "copy",

package/dist/{capabilities/implements → scope/plugins}/builtin/CwdTool.d.ts

@@ -1,4 +1,4 @@
-import { SdkCallbackTool } from "../../../runtime/SdkCallbackTool.js";
+import { SdkCallbackTool } from "./SdkCallbackTool.js";
 import type { ToolEnv } from "../../../types/index.js";
 import type { AgentNS } from "@ai-zen/agents-core";
 export declare class CwdTool extends SdkCallbackTool {

package/dist/{capabilities/implements → scope/plugins}/builtin/CwdTool.js

@@ -1,4 +1,4 @@
-import { SdkCallbackTool } from "../../../runtime/SdkCallbackTool.js";
+import { SdkCallbackTool } from "./SdkCallbackTool.js";
 export class CwdTool extends SdkCallbackTool {
     function = {
         name: "cwd",

package/dist/{capabilities/implements → scope/plugins}/builtin/DownloadFileTool.d.ts

@@ -1,4 +1,4 @@
-import { SdkCallbackTool } from "../../../runtime/SdkCallbackTool.js";
+import { SdkCallbackTool } from "./SdkCallbackTool.js";
 import type { ToolEnv } from "../../../types/index.js";
 import type { AgentNS, ToolCallContext } from "@ai-zen/agents-core";
 export declare class DownloadFileTool extends SdkCallbackTool {

package/dist/{capabilities/implements → scope/plugins}/builtin/DownloadFileTool.js

@@ -1,6 +1,6 @@
 import * as fsp from "fs/promises";
 import * as path from "path";
-import { SdkCallbackTool } from "../../../runtime/SdkCallbackTool.js";
+import { SdkCallbackTool } from "./SdkCallbackTool.js";
 export class DownloadFileTool extends SdkCallbackTool {
     function = {
         name: "downloadFile",

package/dist/{capabilities/implements → scope/plugins}/builtin/EditTool.d.ts

@@ -1,4 +1,4 @@
-import { SdkCallbackTool } from "../../../runtime/SdkCallbackTool.js";
+import { SdkCallbackTool } from "./SdkCallbackTool.js";
 import type { ToolEnv } from "../../../types/index.js";
 import type { AgentNS } from "@ai-zen/agents-core";
 export declare class EditTool extends SdkCallbackTool {

package/dist/{capabilities/implements → scope/plugins}/builtin/EditTool.js

@@ -1,5 +1,5 @@
 import * as fsp from "fs/promises";
-import { SdkCallbackTool } from "../../../runtime/SdkCallbackTool.js";
+import { SdkCallbackTool } from "./SdkCallbackTool.js";
 function countOccurrences(content, text) {
     let count = 0;
     let pos = 0;

package/dist/{capabilities/implements → scope/plugins}/builtin/ExecAsyncTool.d.ts

@@ -1,4 +1,4 @@
-import { SdkCallbackTool } from "../../../runtime/SdkCallbackTool.js";
+import { SdkCallbackTool } from "./SdkCallbackTool.js";
 import type { ToolEnv } from "../../../types/index.js";
 import type { AgentNS } from "@ai-zen/agents-core";
 export declare class ExecAsyncTool extends SdkCallbackTool {

package/dist/{capabilities/implements → scope/plugins}/builtin/ExecAsyncTool.js

@@ -1,5 +1,5 @@
 import { spawn } from "child_process";
-import { SdkCallbackTool } from "../../../runtime/SdkCallbackTool.js";
+import { SdkCallbackTool } from "./SdkCallbackTool.js";
 export class ExecAsyncTool extends SdkCallbackTool {
     function = {
         name: "exec_async",

package/dist/{capabilities/implements → scope/plugins}/builtin/ExecTool.d.ts

@@ -1,4 +1,4 @@
-import { SdkCallbackTool } from "../../../runtime/SdkCallbackTool.js";
+import { SdkCallbackTool } from "./SdkCallbackTool.js";
 import type { ToolEnv } from "../../../types/index.js";
 import type { AgentNS, ToolCallContext } from "@ai-zen/agents-core";
 export declare class ExecTool extends SdkCallbackTool {

package/dist/{capabilities/implements → scope/plugins}/builtin/ExecTool.js

@@ -1,5 +1,6 @@
 import { exec } from "child_process";
-import { SdkCallbackTool } from "../../../runtime/SdkCallbackTool.js";
+import { SdkCallbackTool } from "./SdkCallbackTool.js";
+import { DEFAULT_MAX_TOOL_OUTPUT, guardOutput, headTailPreview } from "./outputGuard.js";
 export class ExecTool extends SdkCallbackTool {
     function = {
         name: "exec",
@@ -81,6 +82,37 @@ export class ExecTool extends SdkCallbackTool {
                 signal.addEventListener("abort", onAbort, { once: true });
             }
         });
-        return JSON.stringify(result);
+        // 输出保护：stdout + stderr 合计超过 maxToolOutput 时，分文件落盘并返回警告 + 头尾预览
+        const limit = this.env.config.maxToolOutput ?? DEFAULT_MAX_TOOL_OUTPUT;
+        const guarded = await guardOutput({
+            tool: "exec",
+            content: result,
+            isOverLimit: (output) => output.stdout.length + output.stderr.length > limit,
+            dump: (_dir, output) => [
+                { name: "stdout.log", content: output.stdout },
+                { name: "stderr.log", content: output.stderr },
+            ],
+            buildWarning: (ctx) => {
+                const stdout = headTailPreview(result.stdout);
+                const stderr = headTailPreview(result.stderr);
+                return JSON.stringify({
+                    outputTooLarge: true,
+                    warning: `输出过大：stdout + stderr 合计 ${result.stdout.length + result.stderr.length} 字符，` +
+                        `超过上限 ${limit} 字符。完整内容已分文件落盘（stdout.log / stderr.log），可用 readFile 分批读取。`,
+                    files: ctx.files,
+                    stdout: { chars: result.stdout.length, lines: countLines(result.stdout), ...stdout },
+                    stderr: { chars: result.stderr.length, lines: countLines(result.stderr), ...stderr },
+                    exitCode: result.exitCode,
+                    killed: result.killed,
+                    terminated: result.terminated,
+                });
+            },
+        });
+        // 未超限：content 为原始结果对象，按原有结构序列化；超限：buildWarning 已生成返回字符串
+        return typeof guarded === "string" ? guarded : JSON.stringify(guarded);
     }
 }
+/** 统计文本行数（空文本记 0 行） */
+function countLines(text) {
+    return text.length === 0 ? 0 : text.split("\n").length;
+}

package/dist/{capabilities/implements → scope/plugins}/builtin/ExistTool.d.ts

@@ -1,4 +1,4 @@
-import { SdkCallbackTool } from "../../../runtime/SdkCallbackTool.js";
+import { SdkCallbackTool } from "./SdkCallbackTool.js";
 import type { ToolEnv } from "../../../types/index.js";
 import type { AgentNS } from "@ai-zen/agents-core";
 export declare class ExistTool extends SdkCallbackTool {

package/dist/{capabilities/implements → scope/plugins}/builtin/ExistTool.js

@@ -1,5 +1,5 @@
 import * as fsp from "fs/promises";
-import { SdkCallbackTool } from "../../../runtime/SdkCallbackTool.js";
+import { SdkCallbackTool } from "./SdkCallbackTool.js";
 export class ExistTool extends SdkCallbackTool {
     function = {
         name: "exist",

package/dist/{capabilities/implements → scope/plugins}/builtin/FindTextTool.d.ts

@@ -1,4 +1,4 @@
-import { SdkCallbackTool } from "../../../runtime/SdkCallbackTool.js";
+import { SdkCallbackTool } from "./SdkCallbackTool.js";
 import type { ToolEnv } from "../../../types/index.js";
 import type { AgentNS, ToolCallContext } from "@ai-zen/agents-core";
 export declare class FindTextTool extends SdkCallbackTool {
@@ -14,4 +14,9 @@ export declare class FindTextTool extends SdkCallbackTool {
         maxFileSize?: number;
         maxLineLength?: number;
     }, ctx?: ToolCallContext): Promise<string>;
+    /**
+     * 输出保护：结果 JSON 超过 maxToolOutput 时落盘为 result.json，
+     * 返回警告 + 头尾预览；未超限则原样返回。
+     */
+    private protect;
 }

package/dist/{capabilities/implements → scope/plugins}/builtin/FindTextTool.js

@@ -1,6 +1,7 @@
 import * as fsp from "fs/promises";
 import * as path from "path";
-import { SdkCallbackTool } from "../../../runtime/SdkCallbackTool.js";
+import { SdkCallbackTool } from "./SdkCallbackTool.js";
+import { DEFAULT_MAX_TOOL_OUTPUT, guardOutput, headPreview } from "./outputGuard.js";
 /** 默认总匹配数上限 */
 const DEFAULT_MAX_MATCHES = 200;
 /** 默认文件大小上限（字节，与 ReadFileTool 的 300KB 口径一致） */
@@ -126,17 +127,41 @@ export class FindTextTool extends SdkCallbackTool {
                 }
             }
             if (signal?.aborted) {
-                return JSON.stringify({ aborted: true, results: result });
+                return await this.protect(JSON.stringify({ aborted: true, results: result }));
             }
             if (truncated) {
-                return JSON.stringify({ truncated: true, totalMatches, results: result });
+                return await this.protect(JSON.stringify({ truncated: true, totalMatches, results: result }));
             }
-            return JSON.stringify(result);
+            return await this.protect(JSON.stringify(result));
         }
         catch (error) {
             return error?.message;
         }
     }
+    /**
+     * 输出保护：结果 JSON 超过 maxToolOutput 时落盘为 result.json，
+     * 返回警告 + 头尾预览；未超限则原样返回。
+     */
+    async protect(json) {
+        const limit = this.env.config.maxToolOutput ?? DEFAULT_MAX_TOOL_OUTPUT;
+        return await guardOutput({
+            tool: "findText",
+            content: json,
+            isOverLimit: (text) => text.length > limit,
+            dump: (_dir, text) => [{ name: "result.json", content: text }],
+            buildWarning: (ctx) => {
+                const preview = headPreview(json);
+                return JSON.stringify({
+                    outputTooLarge: true,
+                    warning: `输出过大：结果共 ${json.length} 字符，超过上限 ${limit} 字符。` +
+                        `完整结果已落盘（result.json），可用 readFile 分批读取。`,
+                    files: ctx.files,
+                    chars: json.length,
+                    ...preview,
+                });
+            },
+        });
+    }
 }
 /** 截断字符串到指定长度，超出部分以 "…" 结尾标记 */
 function truncate(s, max) {

package/dist/{capabilities/implements → scope/plugins}/builtin/GenerateImageTool.d.ts

@@ -1,5 +1,5 @@
 import type { AgentNS, ToolCallContext } from "@ai-zen/agents-core";
-import { SdkCallbackTool } from "../../../runtime/SdkCallbackTool.js";
+import { SdkCallbackTool } from "./SdkCallbackTool.js";
 import type { AgentDefinition, AppConfig, ToolEnv } from "../../../types/index.js";
 /**
  * 根据文字描述生成图片。**统一返回字符串**（JSON，含图片 URL 列表）：

package/dist/{capabilities/implements → scope/plugins}/builtin/GenerateImageTool.js

@@ -1,5 +1,5 @@
 import OpenAI from "openai";
-import { SdkCallbackTool } from "../../../runtime/SdkCallbackTool.js";
+import { SdkCallbackTool } from "./SdkCallbackTool.js";
 /**
  * 根据文字描述生成图片。**统一返回字符串**（JSON，含图片 URL 列表）：
  * 生成结果如何处理（查看/下载/转发）由模型与上层自由决定——

package/dist/{capabilities/implements → scope/plugins}/builtin/GlobTool.d.ts

@@ -1,4 +1,4 @@
-import { SdkCallbackTool } from "../../../runtime/SdkCallbackTool.js";
+import { SdkCallbackTool } from "./SdkCallbackTool.js";
 import type { ToolEnv } from "../../../types/index.js";
 import type { AgentNS, ToolCallContext } from "@ai-zen/agents-core";
 export declare class GlobTool extends SdkCallbackTool {
@@ -9,4 +9,9 @@ export declare class GlobTool extends SdkCallbackTool {
         pattern: string;
         exclude?: string[];
     }, ctx?: ToolCallContext): Promise<string>;
+    /**
+     * 输出保护：结果 JSON 超过 maxToolOutput 时落盘为 result.json，
+     * 返回警告 + 头部预览；未超限则原样返回。
+     */
+    private protect;
 }

package/dist/{capabilities/implements → scope/plugins}/builtin/GlobTool.js

@@ -1,5 +1,6 @@
 import * as fsp from "fs/promises";
-import { SdkCallbackTool } from "../../../runtime/SdkCallbackTool.js";
+import { SdkCallbackTool } from "./SdkCallbackTool.js";
+import { DEFAULT_MAX_TOOL_OUTPUT, guardOutput, headPreview } from "./outputGuard.js";
 export class GlobTool extends SdkCallbackTool {
     function = {
         name: "glob",
@@ -44,12 +45,37 @@ export class GlobTool extends SdkCallbackTool {
                 result.push(file);
             }
             if (signal?.aborted) {
-                return JSON.stringify({ aborted: true, files: result });
+                return await this.protect(JSON.stringify({ aborted: true, files: result }));
             }
-            return JSON.stringify(result);
+            return await this.protect(JSON.stringify(result));
         }
         catch (error) {
             return error?.message;
         }
     }
+    /**
+     * 输出保护：结果 JSON 超过 maxToolOutput 时落盘为 result.json，
+     * 返回警告 + 头部预览；未超限则原样返回。
+     */
+    async protect(json) {
+        const limit = this.env.config.maxToolOutput ?? DEFAULT_MAX_TOOL_OUTPUT;
+        return await guardOutput({
+            tool: "glob",
+            content: json,
+            isOverLimit: (text) => text.length > limit,
+            dump: (_dir, text) => [{ name: "result.json", content: text }],
+            buildWarning: (ctx) => {
+                const preview = headPreview(json);
+                return JSON.stringify({
+                    outputTooLarge: true,
+                    warning: `输出过大：匹配结果共 ${json.length} 字符，超过上限 ${limit} 字符。` +
+                        `完整结果已落盘（result.json），可用 readFile 分批读取；` +
+                        `也可用更精确的 pattern 或 exclude 缩小范围后重新查找。`,
+                    files: ctx.files,
+                    chars: json.length,
+                    ...preview,
+                });
+            },
+        });
+    }
 }

package/dist/scope/plugins/builtin/InspectFileTool.d.ts

@@ -0,0 +1,17 @@
+import { SdkCallbackTool } from "./SdkCallbackTool.js";
+import type { ToolEnv } from "../../../types/index.js";
+import type { AgentNS } from "@ai-zen/agents-core";
+/**
+ * 勘察文件结构概况（行数、每行列数等），不做内容读取。
+ *
+ * 定位与 readFile 的 range 配套：大文件先看结构（有多少行、每行多长），
+ * 再决定 readFile 的读取范围。流式扫描，故不受 readFile 的 300KB 读取阈值限制。
+ */
+export declare class InspectFileTool extends SdkCallbackTool {
+    function: AgentNS.FunctionDefine;
+    constructor(env: ToolEnv);
+    call(input: {
+        path: string;
+        withColCountMap?: boolean;
+    }): Promise<string>;
+}