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

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

@@ -0,0 +1,150 @@
+import * as fsp from "fs/promises";
+import { createReadStream } from "fs";
+import { StringDecoder } from "string_decoder";
+import { SdkCallbackTool } from "./SdkCallbackTool.js";
+import { DEFAULT_MAX_TOOL_OUTPUT } from "./outputGuard.js";
+/**
+ * 勘察文件结构概况（行数、每行列数等），不做内容读取。
+ *
+ * 定位与 readFile 的 range 配套：大文件先看结构（有多少行、每行多长），
+ * 再决定 readFile 的读取范围。流式扫描，故不受 readFile 的 300KB 读取阈值限制。
+ */
+export class InspectFileTool extends SdkCallbackTool {
+    function = {
+        name: "inspectFile",
+        description: "勘察文件的结构概况：总行数、总字符数、最长行的列数及其行索引、平均列数、行尾类型（LF/CRLF）。可选返回每行的列数映射。适用于在 readFile 之前先了解文件规模，再决定用 range 读取哪一段。仅做流式扫描，不受 readFile 的 300KB 读取阈值限制。",
+        parameters: {
+            type: "object",
+            properties: {
+                path: {
+                    type: "string",
+                    description: "文件路径",
+                },
+                withColCountMap: {
+                    type: "boolean",
+                    description: "是否返回每行列数映射（对象：行索引 → 列数，行索引从 0 开始）。默认 false。行数很多时该映射可能过大，此时将只返回概况字段。",
+                    default: false,
+                },
+            },
+            required: ["path"],
+            additionalProperties: false,
+        },
+    };
+    constructor(env) {
+        super({ env });
+    }
+    async call(input) {
+        try {
+            const filePath = this.resolve(input.path);
+            const stats = await fsp.stat(filePath);
+            if (!stats.isFile()) {
+                return `"${filePath}" 不是文件`;
+            }
+            const withColCountMap = input.withColCountMap ?? false;
+            const result = await scan(filePath, withColCountMap);
+            const summary = {
+                path: filePath,
+                bytes: stats.size,
+                lines: result.lines,
+                chars: result.chars,
+                maxCol: result.maxCol,
+                lineIndexOfMaxCol: result.lineIndexOfMaxCol,
+                avgCol: result.lines === 0 ? 0 : Math.round(result.chars / result.lines),
+                lineEnding: result.lineEnding,
+            };
+            if (!withColCountMap)
+                return JSON.stringify(summary);
+            // 明细超限时只返回概况 + 提示（不落盘）：文件规模已超出可处理范围
+            const limit = this.env.config.maxToolOutput ?? DEFAULT_MAX_TOOL_OUTPUT;
+            const payload = JSON.stringify({ ...summary, colCountMap: result.colCountMap });
+            if (payload.length > limit) {
+                return JSON.stringify({
+                    ...summary,
+                    colCountMapOmitted: true,
+                    warning: `行长度明细过大：概况与 colCountMap 合计 ${payload.length} 字符，` +
+                        `超过上限 ${limit} 字符，未落盘返回。文件规模超出可处理范围，` +
+                        `建议改用 findText 定位后再按 range 分段读取。`,
+                });
+            }
+            return payload;
+        }
+        catch (error) {
+            return error?.message;
+        }
+    }
+}
+/**
+ * 流式扫描文件，统计行数、字符数与每行列数。
+ *
+ * 口径：行索引 0-based；列数按字符数（UTF-16 长度）计、不含行尾换行符（CRLF 的 \r 不计）。
+ */
+async function scan(filePath, withColCountMap) {
+    const decoder = new StringDecoder("utf8");
+    const colCountMap = {};
+    let lines = 0;
+    let chars = 0;
+    let col = 0;
+    let maxCol = 0;
+    let lineIndexOfMaxCol = 0;
+    let sawLf = false;
+    let sawCrlf = false;
+    let lastWasNewline = false;
+    let sawAnyChar = false;
+    /** 上一个字符是 \r，等待判定它是否属于 CRLF */
+    let pendingCr = false;
+    const endLine = () => {
+        if (withColCountMap)
+            colCountMap[String(lines)] = col;
+        if (col > maxCol) {
+            maxCol = col;
+            lineIndexOfMaxCol = lines;
+        }
+        chars += col;
+        lines++;
+        col = 0;
+        lastWasNewline = true;
+    };
+    const processText = (text) => {
+        // 按 code unit 遍历，与 String.length 口径一致
+        for (let index = 0; index < text.length; index++) {
+            const char = text[index];
+            sawAnyChar = true;
+            if (char === "\n") {
+                if (pendingCr) {
+                    sawCrlf = true;
+                    pendingCr = false;
+                }
+                else {
+                    sawLf = true;
+                }
+                endLine();
+                continue;
+            }
+            // 前一个字符是 \r 且其后不是 \n：属孤立的 \r，作为行内字符计入
+            if (pendingCr) {
+                col++;
+                pendingCr = false;
+            }
+            if (char === "\r") {
+                pendingCr = true;
+                lastWasNewline = false;
+                continue;
+            }
+            col++;
+            lastWasNewline = false;
+        }
+    };
+    const stream = createReadStream(filePath);
+    for await (const chunk of stream) {
+        processText(decoder.write(chunk));
+    }
+    processText(decoder.end());
+    // 文件末尾残留的孤立 \r
+    if (pendingCr)
+        col++;
+    // 末行未以换行结束（空文件不计行）
+    if (sawAnyChar && !lastWasNewline)
+        endLine();
+    const lineEnding = sawCrlf && sawLf ? "mixed" : sawCrlf ? "CRLF" : "LF";
+    return { lines, chars, maxCol, lineIndexOfMaxCol, lineEnding, colCountMap };
+}

package/dist/{capabilities/implements → scope/plugins}/builtin/LsTool.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 LsTool extends SdkCallbackTool {

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

@@ -0,0 +1,52 @@
+import * as fsp from "fs/promises";
+import { SdkCallbackTool } from "./SdkCallbackTool.js";
+import { DEFAULT_MAX_TOOL_OUTPUT, guardOutput, headPreview } from "./outputGuard.js";
+export class LsTool extends SdkCallbackTool {
+    function = {
+        name: "ls",
+        description: "列出目录",
+        parameters: {
+            type: "object",
+            properties: {
+                path: {
+                    type: "string",
+                    description: "目录路径",
+                },
+            },
+            required: ["path"],
+            additionalProperties: false,
+        },
+    };
+    constructor(env) {
+        super({ env });
+    }
+    async call(input) {
+        try {
+            const entries = await fsp.readdir(this.resolve(input.path));
+            const json = JSON.stringify(entries);
+            // 输出保护：结果超过 maxToolOutput 时落盘为 result.json，返回警告 + 头部预览
+            const limit = this.env.config.maxToolOutput ?? DEFAULT_MAX_TOOL_OUTPUT;
+            return await guardOutput({
+                tool: "ls",
+                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: `输出过大：目录条目共 ${entries.length} 项、${json.length} 字符，超过上限 ${limit} 字符。` +
+                            `完整列表已落盘（result.json），可用 readFile 分批读取；` +
+                            `也可改用 glob 按模式筛选。`,
+                        files: ctx.files,
+                        chars: json.length,
+                        ...preview,
+                    });
+                },
+            });
+        }
+        catch (error) {
+            return error?.message;
+        }
+    }
+}

package/dist/{capabilities/implements → scope/plugins}/builtin/MkdirTool.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 MkdirTool extends SdkCallbackTool {

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

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

package/dist/{capabilities/implements → scope/plugins}/builtin/ReadFileTool.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 ReadFileTool extends SdkCallbackTool {
@@ -6,5 +6,6 @@ export declare class ReadFileTool extends SdkCallbackTool {
     constructor(env: ToolEnv);
     call(input: {
         path: string;
+        range?: number[];
     }): Promise<string>;
 }

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

@@ -0,0 +1,94 @@
+import * as fsp from "fs/promises";
+import { SdkCallbackTool } from "./SdkCallbackTool.js";
+import { DEFAULT_MAX_TOOL_OUTPUT, guardOutput } from "./outputGuard.js";
+export class ReadFileTool extends SdkCallbackTool {
+    function = {
+        name: "readFile",
+        description: "读取文件",
+        parameters: {
+            type: "object",
+            properties: {
+                path: {
+                    type: "string",
+                    description: "文件路径",
+                },
+                range: {
+                    type: "array",
+                    description: "读取范围 [起始行, 起始列, 结束行, 结束列]，行列均从 0 开始，-1 表示末位；" +
+                        "例如 [0, 0, 100, -1] 表示从第 0 行第 0 列读到第 100 行最后一列。省略则读取整个文件。",
+                    items: {
+                        type: "number",
+                    },
+                },
+            },
+            required: ["path"],
+            additionalProperties: false,
+        },
+    };
+    constructor(env) {
+        super({ env });
+    }
+    async call(input) {
+        try {
+            const filePath = this.resolve(input.path);
+            const stats = await fsp.stat(filePath);
+            // 读取阈值：文件过大时拒绝读取（与输出阈值 maxToolOutput 无关）
+            if (stats.size > 300 * 1024) {
+                throw new Error(`文件过大，无法读取，当前文件大小 ${stats.size} 字节`);
+            }
+            const content = await fsp.readFile(filePath, "utf-8");
+            const output = input.range ? sliceByRange(content, input.range) : content;
+            // 输出保护：本次返回内容超过上限时只警告、不落盘，并提示用 range 分批读取
+            const limit = this.env.config.maxToolOutput ?? DEFAULT_MAX_TOOL_OUTPUT;
+            return await guardOutput({
+                tool: "readFile",
+                content: output,
+                isOverLimit: (text) => text.length > limit,
+                buildWarning: () => `读取内容过大：本次输出 ${output.length} 字符，超过上限 ${limit} 字符，未落盘。` +
+                    `文件共 ${countLines(content)} 行、${content.length} 字符，` +
+                    `请用 range 参数分范围读取（形如 [起始行, 起始列, 结束行, 结束列]，行列从 0 开始，-1 表示末位）。`,
+            });
+        }
+        catch (error) {
+            return error?.message;
+        }
+    }
+}
+/**
+ * 按 [起始行, 起始列, 结束行, 结束列] 切片（0-based，-1 表末位）。
+ *
+ * - 起始行至结束行逐行取出；起始行从起始列起截取，结束行截取到结束列（含）；
+ * - 结束列为 -1 时取到行末，故 [0, 0, 100, -1] 即"第 0 行第 0 列到第 100 行末"；
+ * - 越界索引自动夹取到有效范围。
+ */
+function sliceByRange(content, range) {
+    const lines = content.split("\n");
+    const [rawStartLine = 0, rawStartCol = 0, rawEndLine = -1, rawEndCol = -1] = range;
+    const startLine = resolveIndex(rawStartLine, lines.length);
+    const endLine = resolveIndex(rawEndLine, lines.length);
+    if (endLine < startLine)
+        return "";
+    const selected = [];
+    for (let index = startLine; index <= endLine; index++) {
+        const line = lines[index] ?? "";
+        const from = index === startLine ? resolveIndex(rawStartCol, line.length) : 0;
+        const to = index === endLine ? resolveIndex(rawEndCol, line.length) : line.length - 1;
+        selected.push(line.slice(from, to + 1));
+    }
+    return selected.join("\n");
+}
+/** 解析行列索引：-1 表末位，其余负值自末尾倒数，越界夹取到有效范围 */
+function resolveIndex(index, length) {
+    if (!Number.isFinite(index) || length === 0)
+        return 0;
+    const normalized = index < 0 ? length + index : index;
+    if (normalized < 0)
+        return 0;
+    if (normalized > length - 1)
+        return length - 1;
+    return normalized;
+}
+/** 统计文本行数（空文本记 0 行） */
+function countLines(text) {
+    return text.length === 0 ? 0 : text.split("\n").length;
+}

package/dist/{capabilities/implements → scope/plugins}/builtin/RenameTool.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 RenameTool extends SdkCallbackTool {

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

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

package/dist/{capabilities/implements → scope/plugins}/builtin/RmTool.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 RmTool extends SdkCallbackTool {

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

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

package/dist/{runtime → scope/plugins/builtin}/SdkCallbackTool.d.ts

@@ -1,6 +1,6 @@
 import { Tool, ToolCallContext } from "@ai-zen/agents-core";
 import type { AgentNS } from "@ai-zen/agents-core";
-import type { AgentDefinition, AppConfig, ToolEnv } from "../types/index.js";
+import type { AgentDefinition, AppConfig, ToolEnv } from "../../../types/index.js";
 /** SdkCallbackTool 构造选项。env 为核心字段，未来可在此扩展可选项。 */
 export interface SdkCallbackToolOptions {
     /** 注入的工具环境 */

package/dist/{capabilities/implements → scope/plugins}/builtin/SleepTool.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 SleepTool extends SdkCallbackTool {

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

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

package/dist/{capabilities/implements → scope/plugins}/builtin/ViewImageTool.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";
 /**
  * 查看图片工具 — 让 Agent 主动查看/分析一张图片。**仅对视觉模型可用**：

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

@@ -1,7 +1,7 @@
 import OpenAI, { toFile } from "openai";
 import { promises as fs } from "node:fs";
 import path from "node:path";
-import { SdkCallbackTool } from "../../../runtime/SdkCallbackTool.js";
+import { SdkCallbackTool } from "./SdkCallbackTool.js";
 const SUPPORTED_EXT = [".jpg", ".jpeg", ".png", ".gif", ".webp"];
 /**
  * 是否为"本地 URL"——指向本地/回环地址，API 服务商无法下载访问。

package/dist/{capabilities/implements → scope/plugins}/builtin/WriteFileTool.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 WriteFileTool extends SdkCallbackTool {

package/dist/{capabilities/implements → scope/plugins}/builtin/WriteFileTool.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 WriteFileTool extends SdkCallbackTool {
     function = {
         name: "writeFile",

package/dist/{capabilities/discovery/builtin.d.ts → scope/plugins/builtin/discover.d.ts}

@@ -1,5 +1,5 @@
 import type { Tool } from "@ai-zen/agents-core";
-import type { ToolEnv } from "../../types/index.js";
+import type { ToolEnv } from "../../../types/index.js";
 /**
  * 发现内置工具：按静态注册表实例化全部内置工具（无任何过滤）。
  *

package/dist/{capabilities/discovery/builtin.js → scope/plugins/builtin/discover.js}

@@ -1,4 +1,4 @@
-import { BUILTIN_TOOL_CLASSES } from "../implements/builtin/index.js";
+import { BUILTIN_TOOL_CLASSES } from "./index.js";
 /**
  * 发现内置工具：按静态注册表实例化全部内置工具（无任何过滤）。
  *

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

@@ -1,7 +1,8 @@
-import type { SdkCallbackTool } from "../../../runtime/SdkCallbackTool.js";
+import type { SdkCallbackTool } from "./SdkCallbackTool.js";
 import type { ToolEnv } from "../../../types/index.js";
 import { CwdTool } from "./CwdTool.js";
 import { ReadFileTool } from "./ReadFileTool.js";
+import { InspectFileTool } from "./InspectFileTool.js";
 import { WriteFileTool } from "./WriteFileTool.js";
 import { ExecTool } from "./ExecTool.js";
 import { MkdirTool } from "./MkdirTool.js";
@@ -20,12 +21,12 @@ import { SleepTool } from "./SleepTool.js";
 import { ViewImageTool } from "./ViewImageTool.js";
 import { GenerateImageTool } from "./GenerateImageTool.js";
 /**
- * 全部内置工具类（19 个）。
- * 工具类由 Provider 用 ToolEnv 实例化（每个 Provider 一套实例，注入其 cwd）。
+ * 全部内置工具类（20 个）。
+ * 工具类由 Scope 的内置工具插件（BuiltinToolsScopePlugin）用 ToolEnv 实例化（每个 Scope 一套实例，注入其 cwd）。
  *
  * 发现层不做任何过滤——工具的可用性由各工具自行声明（SdkCallbackTool.isAvailable，
  * 入参含完整 config + 模型信息），在 buildTools/filter 阶段按声明过滤。
  * 如 GenerateImageTool 依赖 defaultImageModel、ViewImageTool 仅视觉模型可用。
  */
 export declare const BUILTIN_TOOL_CLASSES: Array<new (env: ToolEnv) => SdkCallbackTool>;
-export { CwdTool, ReadFileTool, WriteFileTool, ExecTool, MkdirTool, RmTool, GlobTool, LsTool, ExistTool, FindTextTool, DownloadFileTool, RenameTool, CopyTool, BatchEditTool, EditTool, ExecAsyncTool, SleepTool, ViewImageTool, GenerateImageTool, };
+export { CwdTool, ReadFileTool, InspectFileTool, WriteFileTool, ExecTool, MkdirTool, RmTool, GlobTool, LsTool, ExistTool, FindTextTool, DownloadFileTool, RenameTool, CopyTool, BatchEditTool, EditTool, ExecAsyncTool, SleepTool, ViewImageTool, GenerateImageTool, };

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

@@ -1,5 +1,6 @@
 import { CwdTool } from "./CwdTool.js";
 import { ReadFileTool } from "./ReadFileTool.js";
+import { InspectFileTool } from "./InspectFileTool.js";
 import { WriteFileTool } from "./WriteFileTool.js";
 import { ExecTool } from "./ExecTool.js";
 import { MkdirTool } from "./MkdirTool.js";
@@ -18,8 +19,8 @@ import { SleepTool } from "./SleepTool.js";
 import { ViewImageTool } from "./ViewImageTool.js";
 import { GenerateImageTool } from "./GenerateImageTool.js";
 /**
- * 全部内置工具类（19 个）。
- * 工具类由 Provider 用 ToolEnv 实例化（每个 Provider 一套实例，注入其 cwd）。
+ * 全部内置工具类（20 个）。
+ * 工具类由 Scope 的内置工具插件（BuiltinToolsScopePlugin）用 ToolEnv 实例化（每个 Scope 一套实例，注入其 cwd）。
  *
  * 发现层不做任何过滤——工具的可用性由各工具自行声明（SdkCallbackTool.isAvailable，
  * 入参含完整 config + 模型信息），在 buildTools/filter 阶段按声明过滤。
@@ -28,6 +29,7 @@ import { GenerateImageTool } from "./GenerateImageTool.js";
 export const BUILTIN_TOOL_CLASSES = [
     CwdTool,
     ReadFileTool,
+    InspectFileTool,
     WriteFileTool,
     ExecTool,
     MkdirTool,
@@ -46,4 +48,4 @@ export const BUILTIN_TOOL_CLASSES = [
     ViewImageTool,
     GenerateImageTool,
 ];
-export { CwdTool, ReadFileTool, WriteFileTool, ExecTool, MkdirTool, RmTool, GlobTool, LsTool, ExistTool, FindTextTool, DownloadFileTool, RenameTool, CopyTool, BatchEditTool, EditTool, ExecAsyncTool, SleepTool, ViewImageTool, GenerateImageTool, };
+export { CwdTool, ReadFileTool, InspectFileTool, WriteFileTool, ExecTool, MkdirTool, RmTool, GlobTool, LsTool, ExistTool, FindTextTool, DownloadFileTool, RenameTool, CopyTool, BatchEditTool, EditTool, ExecAsyncTool, SleepTool, ViewImageTool, GenerateImageTool, };

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

@@ -0,0 +1,81 @@
+/**
+ * 工具输出上限的缺省值（字符数）。
+ *
+ * 可由 AppConfig.maxToolOutput 覆盖；上限由各工具自行读取并判定，
+ * 骨架不感知配置，以便不同工具按自身口径（如 stdout/stderr 合计）判断。
+ */
+export declare const DEFAULT_MAX_TOOL_OUTPUT = 32768;
+/** 待落盘的文件：文件名（不含目录）+ 内容 */
+export interface GuardDumpFile {
+    /** 文件名，如 "stdout.log" */
+    name: string;
+    /** 文件内容 */
+    content: string;
+}
+/** buildWarning 回调收到的落盘结果 */
+export interface GuardWarningContext {
+    /** 本次落盘目录；未落盘（工具未提供 dump）时为 null */
+    dir: string | null;
+    /** 已落盘文件：文件名 → 绝对路径；未落盘时为空对象 */
+    files: Record<string, string>;
+}
+/** guardOutput 入参：骨架所需的一切（判定、落盘、警告）均由工具以回调提供 */
+export interface OutputGuardOptions<T> {
+    /** 工具名，用于落盘目录命名（如 "exec"） */
+    tool: string;
+    /** 工具本应返回的完整内容 */
+    content: T;
+    /** 超限判定：上限由工具自行从 config 读取，骨架不传参 */
+    isOverLimit: (content: T) => boolean;
+    /**
+     * 落盘内容组织（可选）。缺省表示"只警告、不落盘"（如 readFile）。
+     * 返回的文件按顺序写入本次调用专属的目录。
+     */
+    dump?: (dir: string, content: T) => GuardDumpFile[] | Promise<GuardDumpFile[]>;
+    /** 生成超限时的返回体（各工具自定义，可含头尾预览、统计、原有字段等） */
+    buildWarning: (ctx: GuardWarningContext) => string;
+}
+/**
+ * 标准输出保护骨架。
+ *
+ * 各工具在 call() 出口调用，只需提供三个回调：
+ *   1) isOverLimit  —— 是否超过上限（工具自读 config 判定，未被超限即原样返回 content）；
+ *   2) dump         —— 超限时落盘哪些文件（可省略 = 只警告不落盘）；
+ *   3) buildWarning —— 超限时返回给模型的内容。
+ *
+ * 骨架职责：判定 → 未超限原样返回 / 超限时创建独立目录并写文件 → 交给 buildWarning。
+ *
+ * 落盘目录：<os.tmpdir()>/ai-zen/tool-output/<tool>-<时间戳>-<随机串>/，
+ * 每次调用独立目录，互不覆盖；不做自清理，依赖系统对临时目录的清理策略。
+ *
+ * 落盘失败（磁盘满、权限不足等）不吞异常，直接向上抛出。
+ */
+export declare function guardOutput<T>(options: OutputGuardOptions<T>): Promise<T | string>;
+/** 头部预览 */
+export interface HeadPreview {
+    /** 头部内容（最多 size 字符） */
+    head: string;
+    /** 被省略的字符数；为 0 表示无省略（此时 head 为全文） */
+    omitted: number;
+}
+/**
+ * 生成头部预览：最多 size 字符。
+ *
+ * 适用于结果按出现顺序排列、尾部参考价值低的工具（如 findText）。
+ */
+export declare function headPreview(text: string, size?: number): HeadPreview;
+/** 头尾预览 */
+export interface HeadTailPreview {
+    /** 头部内容（最多 size 字符） */
+    head: string;
+    /** 尾部内容（最多 size 字符）；无省略时为空串 */
+    tail: string;
+    /** 被省略的字符数；为 0 表示无省略（此时 head 为全文） */
+    omitted: number;
+}
+/**
+ * 生成头尾预览：头部最多 size 字符 + 尾部最多 size 字符。
+ *
+ * 供各工具的 buildWarning 按需取用（也可自行组织预览，骨架不做限制）。
+ */
+export declare function headTailPreview(text: string, size?: number): HeadTailPreview;

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

@@ -0,0 +1,73 @@
+import * as fsp from "fs/promises";
+import * as os from "os";
+import * as path from "path";
+/**
+ * 工具输出上限的缺省值（字符数）。
+ *
+ * 可由 AppConfig.maxToolOutput 覆盖；上限由各工具自行读取并判定，
+ * 骨架不感知配置，以便不同工具按自身口径（如 stdout/stderr 合计）判断。
+ */
+export const DEFAULT_MAX_TOOL_OUTPUT = 32_768;
+/**
+ * 标准输出保护骨架。
+ *
+ * 各工具在 call() 出口调用，只需提供三个回调：
+ *   1) isOverLimit  —— 是否超过上限（工具自读 config 判定，未被超限即原样返回 content）；
+ *   2) dump         —— 超限时落盘哪些文件（可省略 = 只警告不落盘）；
+ *   3) buildWarning —— 超限时返回给模型的内容。
+ *
+ * 骨架职责：判定 → 未超限原样返回 / 超限时创建独立目录并写文件 → 交给 buildWarning。
+ *
+ * 落盘目录：<os.tmpdir()>/ai-zen/tool-output/<tool>-<时间戳>-<随机串>/，
+ * 每次调用独立目录，互不覆盖；不做自清理，依赖系统对临时目录的清理策略。
+ *
+ * 落盘失败（磁盘满、权限不足等）不吞异常，直接向上抛出。
+ */
+export async function guardOutput(options) {
+    const { tool, content, isOverLimit, dump, buildWarning } = options;
+    if (!isOverLimit(content))
+        return content;
+    if (!dump)
+        return buildWarning({ dir: null, files: {} });
+    const dir = await createDumpDir(tool);
+    const files = await dump(dir, content);
+    const paths = {};
+    for (const file of files) {
+        const target = path.join(dir, file.name);
+        await fsp.writeFile(target, file.content, "utf-8");
+        paths[file.name] = target;
+    }
+    return buildWarning({ dir, files: paths });
+}
+/**
+ * 生成头部预览：最多 size 字符。
+ *
+ * 适用于结果按出现顺序排列、尾部参考价值低的工具（如 findText）。
+ */
+export function headPreview(text, size = 1000) {
+    if (text.length <= size)
+        return { head: text, omitted: 0 };
+    return { head: text.slice(0, size), omitted: text.length - size };
+}
+/**
+ * 生成头尾预览：头部最多 size 字符 + 尾部最多 size 字符。
+ *
+ * 供各工具的 buildWarning 按需取用（也可自行组织预览，骨架不做限制）。
+ */
+export function headTailPreview(text, size = 1000) {
+    if (text.length <= size * 2)
+        return { head: text, tail: "", omitted: 0 };
+    return {
+        head: text.slice(0, size),
+        tail: text.slice(-size),
+        omitted: text.length - size * 2,
+    };
+}
+/** 创建本次调用专属的落盘目录 */
+async function createDumpDir(tool) {
+    const stamp = new Date().toISOString().replace(/[:.]/g, "-");
+    const rand = Math.random().toString(36).slice(2, 8);
+    const dir = path.join(os.tmpdir(), "ai-zen", "tool-output", `${tool}-${stamp}-${rand}`);
+    await fsp.mkdir(dir, { recursive: true });
+    return dir;
+}