@ai-zen/agents-sdk 0.10.0 → 0.12.0

package/CHANGELOG.md

@@ -1,5 +1,45 @@
 # Changelog
 
+## [0.12.0] - 2026-09-29
+
+### 🚀 New Features
+
+- **统一工具输出保护（`maxToolOutput`）** — `AppConfig` 新增 `maxToolOutput?: number`（字符数，缺省 32768；出厂 `DEFAULT_APP_CONFIG` 已写入该值）。新增输出保护骨架 `guardOutput()`（`capabilities/implements/builtin/outputGuard.ts`）：工具以三个回调自陈策略——`isOverLimit(content)`（工具自读 config 判定，含合计口径）、`dump(dir, content)`（落盘文件清单，缺省即"只警告不落盘"）、`buildWarning(ctx)`（返回体，含预览与统计）；骨架只负责"判定 → 未超限原样返回 / 超限时落盘"两件事。落盘目录为 `<os.tmpdir()>/ai-zen/tool-output/<工具名>-<时间戳>-<随机串>/`，每次调用独立互不覆盖，不做自清理（依赖系统对临时目录的策略）。已接入：
+  - **`exec`** — `stdout + stderr` 合计超限即分文件落盘 `stdout.log` / `stderr.log`，返回警告 + 各流头尾预览（各 1000 字符）+ 字符数/行数统计，原 `exitCode` / `killed` / `terminated` 字段保留；
+  - **`findText`** — 落盘 `result.json`，返回警告 + 头部预览（1000 字符）；既有 `maxMatches` / `maxFileSize` / `maxLineLength` 参数保持不变；
+  - **`glob` / `ls`** — 落盘 `result.json`，返回警告 + 头部预览，并提示缩小范围的方式（更精确的 `pattern` / `exclude`，或改用 `glob`）；
+  - **`readFile`** — 超限**不落盘**，仅返回警告并提示使用 `range` 分批读取。
+  - 另导出 `headPreview()` / `headTailPreview()` 供各工具按需组织预览（预览文本由工具自行生成）。
+- **`readFile` 新增 `range` 参数（可选）** — `range: [起始行, 起始列, 结束行, 结束列]`，行列均 0-based、`-1` 表示末位；如 `[0, 0, 100, -1]` 表示"第 0 行第 0 列读到第 100 行最后一列"。300KB 读取阈值保持不变——读取阈值（能否读）与输出阈值（是否落盘）互相独立。
+- **新增 `inspectFile` 工具（`InspectFileTool`）** — 勘察文件结构概况，不做内容读取，与 `readFile` 的 `range` 配套（先看结构，再决定读取范围）。返回 `path` / `bytes` / `lines` / `chars` / `maxCol` / `lineIndexOfMaxCol`（0-based）/ `avgCol` / `lineEnding`（`LF` / `CRLF` / `mixed`）；可选 `withColCountMap: true` 返回"行索引 → 列数"对象映射。流式扫描，**不受 300KB 读取阈值限制**；列数按字符数计、不含行尾换行符；明细超限时不落盘，仅返回概况 + 提示"文件规模超出可处理范围"。内置工具类由 19 个增至 20 个。
+- **`batchEdit` 输出精简** — 成功项不再回显原文与新文，全部成功时返回 `{ result: "success", replacedCount }`；存在未匹配项时返回 `{ result: "partial", replacedCount, failed: [{ oldText, newText, reason }] }`，仅回显有问题的原文与新文，避免大段文本回显撑大输出。
+- **`AgentDefinition` 新增 `custom` 字段** — 为 `true` 时 SDK 初始化不触碰该 Agent 的内置内容（如默认提示词）。出厂 `DEFAULT_AGENT_DEFINITION` 携带 `custom: false`：`ensureDefaultAgent()` 在 `custom !== true` 时**仅同步出厂提示词**（`name` / `permissions` / `modelId` 等用户改动保留），提示词一致时不写盘、不动 `updatedAt`（比较时忽略随机生成的 message `id`，避免时间戳漂移）。
+- **默认 Agent 提示词调整** — 去掉原有法则，改为两条：① 需要用户决策时，一次只问一个问题；② 当前对话基于 Node.js 驱动，可编写 Node.js 脚本执行复杂任务并通过 `exec` 工具运行。
+
+### ✅ Tests
+
+- 新增 `outputGuard.test.ts`（骨架：未超限原样返回 / 超限落盘并返回警告 / 无 `dump` 时只警告 / 目录隔离 / `headPreview` 与 `headTailPreview`）、`InspectFileTool.test.ts`（概况字段、`colCountMap` 映射、CRLF 与 mixed、末行无换行、空文件、300KB 以上文件、明细超限降级、目录与不存在路径）及各工具的超限/范围读取用例；`ConfigManager.bootstrap.test.ts` 覆盖 `custom: true` 跳过、仅同步提示词、一致时不写盘。SDK 全量 **499 passed / 6 skipped**
+
+## [0.11.0] - 2026-09-28
+
+### 💥 Breaking Changes
+
+- **`createCallSkillSubAgentTool` 移除第三参 `provider`** — Skill 子 Agent 不再经 `provider.buildTools(parent.definition, …)` 重新解析工具集，改为**直接沿用父 Agent 的工具集**（`ctx.agent.tools`），仅剔除 `call_skill_sub_agent` 自身：Skill 子 Agent 作为一次性对话分身，沿用调用者的能力而不再走第二遍权限过滤，同时避免 skill 链式自递归。传入 `Provider` 的调用方需删除该实参
+
+### 🚀 New Features
+
+- **Skill 子 Agent 纳入统一委派边界** — `call_skill_sub_agent` 由 `AgentToolLazy` 承载（原为就地实现的 `CallbackTool`），因此与常规 SubAgent 工具共享同一套 `onSubAgentStart` / `onSubAgentEnd` 插件钩子与 `sub-agent-start` / `sub-agent-end` 事件。将护栏装配到 `ctx.subAgent` 的消费方（如上下文护栏）与渲染子 Agent 流式输出的消费方（如 CLI），自此均覆盖该路径
+
+### 🛠 Optimized
+
+- **Skill 子 Agent 的构建收敛到 `buildAgent`** — 子 Agent 的初始消息（`System(SKILL.md 内容)` + `User(task)`）改由 `buildAgent` 决定（依托 core 4.3.0 的 `messages` 可选），原先手写的 abort 联动与返回值处理一并删除，交由工具基类统一实现
+- **校验失败改为抛错** — `skill_id` 不存在、或 Skill 未声明 `sub-agent: true` 时抛出错误（原为返回提示文本）；正常路径由 `skill_id` 枚举限定，不触发
+- **依赖 `@ai-zen/agents-core` 升至 `^4.3.0`** — 依赖声明保持 `workspace:^`，由 pnpm 在发布时展开为 `^4.3.0`。core 4.3.0 使 `AgentToolLazy.messages` 变为可选
+
+### ✅ Tests
+
+- `skillTools.test.ts` 中 `createCallSkillSubAgentTool` 用例重写为围绕 `AgentToolLazy`：工具契约不变、未知 Skill 抛错、非子 Agent Skill 抛错、委派边界（`onSubAgentStart` 与 `sub-agent-start` 分发、子 Agent 沿用父工具集且剔除自身、初始消息取自 SKILL.md 与 `task`）；SDK 全量 **463 passed / 6 skipped**
+
 ## [0.10.0] - 2026-09-28
 
 ### 🚀 New Features

package/README.md

@@ -89,20 +89,21 @@ All built-in tools are classes (extending `SdkCallbackTool`), instantiated by th
 | Tool | Description |
 |------|-------------|
 | `cwd` | Get the current working directory |
-| `readFile` | Read a file |
+| `readFile` | Read a file (optional `range` for line/column slicing; oversized output warns and suggests batched reads) |
+| `inspectFile` | Inspect a file's structural overview (line count, column distribution, etc.); streamed scan, not limited by the 300KB read threshold |
 | `writeFile` | Write a file |
-| `exec` | Execute a command (supports `timeout`) |
+| `exec` | Execute a command (supports `timeout`; oversized stdout+stderr is dumped to `stdout.log` / `stderr.log`) |
 | `exec_async` | Execute a command asynchronously, returns immediately without waiting |
 | `mkdir` | Create a directory |
 | `rm` | Delete a file or directory |
-| `glob` | Scan and find files using glob patterns |
-| `ls` | List directory contents |
+| `glob` | Scan and find files using glob patterns (oversized output dumped to `result.json`) |
+| `ls` | List directory contents (oversized output dumped to `result.json`) |
 | `exist` | Check whether a file or directory exists |
-| `findText` | Search for text or regex in files |
+| `findText` | Search for text or regex in files (oversized output dumped to `result.json`) |
 | `downloadFile` | Download a file from a URL and save it locally |
 | `rename` | Rename or move a file/directory |
 | `copy` | Copy a file or directory |
-| `batchEdit` | Batch-edit file text |
+| `batchEdit` | Batch-edit file text (only unmatched items are echoed back; successful ones are counted) |
 | `edit` | Edit text in a file |
 | `sleep` | Wait for a specified number of milliseconds |
 
@@ -113,6 +114,8 @@ Conditionally injected based on the active model / config:
 | `generateImage` | Only when `defaultImageModel` is configured | Generate an image from a text description |
 | `viewImage` | Only for vision models (the agent's `modelId` resolves to a model with `vision: true`) | View / analyze an image: local images are auto-uploaded via the Files API, network URLs are referenced directly |
 
+Tool output protection: `AppConfig.maxToolOutput` (in characters, default 32768) is the unified ceiling for tool output. Each tool handles overflow itself — `exec` dumps `stdout.log` / `stderr.log` separately (returning head/tail previews per stream), `findText` / `glob` / `ls` dump `result.json` (returning a head preview), and `readFile` only warns and suggests batched reads via `range`. Dumps go to `<tmpdir>/ai-zen/tool-output/<tool>-<timestamp>-<random>/`, one directory per call, with no self-cleanup. See [`docs/sdk-design.md` §7](docs/sdk-design.md).
+
 ## Built-in Plugins
 
 | Plugin | Description |

package/README.zh.md

@@ -88,20 +88,21 @@ await agent.send("你好");
 | 工具 | 说明 |
 |------|------|
 | `cwd` | 获取当前工作目录 |
-| `readFile` | 读取文件 |
+| `readFile` | 读取文件（可选 `range` 按行列范围读取；输出超限仅警告并提示用 `range` 分批） |
+| `inspectFile` | 勘察文件结构概况（行数、列数分布等），流式扫描不受 300KB 限制 |
 | `writeFile` | 写入文件 |
-| `exec` | 执行命令（支持 `timeout` 超时参数） |
+| `exec` | 执行命令（支持 `timeout` 超时参数；stdout+stderr 超限时分文件落盘 `stdout.log` / `stderr.log`） |
 | `exec_async` | 异步执行命令，启动后立即返回，不等待结果 |
 | `mkdir` | 创建目录 |
 | `rm` | 删除文件或目录 |
-| `glob` | 使用 glob 模式扫描查找文件 |
-| `ls` | 列出目录内容 |
+| `glob` | 使用 glob 模式扫描查找文件（输出超限落盘 `result.json`） |
+| `ls` | 列出目录内容（输出超限落盘 `result.json`） |
 | `exist` | 检查文件或目录是否存在 |
-| `findText` | 在文件中搜索文本或正则 |
+| `findText` | 在文件中搜索文本或正则（输出超限落盘 `result.json`） |
 | `downloadFile` | 从 URL 下载文件并保存到本地 |
 | `rename` | 重命名或移动文件/目录 |
 | `copy` | 复制文件或目录 |
-| `batchEdit` | 批量编辑文件文本 |
+| `batchEdit` | 批量编辑文件文本（仅回显未匹配项，成功项只计数） |
 | `edit` | 编辑文件中的文本 |
 | `sleep` | 等待指定毫秒数后继续 |
 
@@ -112,6 +113,8 @@ await agent.send("你好");
 | `generateImage` | 配置了 `defaultImageModel` 才注册 | 根据文字描述生成图片 |
 | `viewImage` | 仅视觉模型可用（Agent 的 `modelId` 解析为 `vision: true` 的模型） | 查看/分析图片：本地图片自动经 Files API 上传，网络 URL 直接引用 |
 
+工具输出保护：`AppConfig.maxToolOutput`（字符数，缺省 32768）是工具输出的统一上限，超限时由各工具自行处置——`exec` 分文件落盘 `stdout.log` / `stderr.log`（返回各流头尾预览），`findText` / `glob` / `ls` 落盘 `result.json`（返回头部预览），`readFile` 仅警告并提示用 `range` 分批读取。落盘目录为 `<tmpdir>/ai-zen/tool-output/<工具名>-<时间戳>-<随机串>/`，每次调用独立、不自清理。详见 [`docs/sdk-design.md` §7](docs/sdk-design.md)。
+
 ## 内置插件
 
 | 插件 | 说明 |

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

@@ -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/capabilities/implements/builtin/ExecTool.js

@@ -1,5 +1,6 @@
 import { exec } from "child_process";
 import { SdkCallbackTool } from "../../../runtime/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/builtin/FindTextTool.d.ts

@@ -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/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 { 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/builtin/GlobTool.d.ts

@@ -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/builtin/GlobTool.js

@@ -1,5 +1,6 @@
 import * as fsp from "fs/promises";
 import { SdkCallbackTool } from "../../../runtime/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/capabilities/implements/builtin/InspectFileTool.d.ts

@@ -0,0 +1,17 @@
+import { SdkCallbackTool } from "../../../runtime/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>;
+}

package/dist/capabilities/implements/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 "../../../runtime/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/builtin/LsTool.js

@@ -1,5 +1,6 @@
 import * as fsp from "fs/promises";
 import { SdkCallbackTool } from "../../../runtime/SdkCallbackTool.js";
+import { DEFAULT_MAX_TOOL_OUTPUT, guardOutput, headPreview } from "./outputGuard.js";
 export class LsTool extends SdkCallbackTool {
     function = {
         name: "ls",
@@ -21,8 +22,28 @@ export class LsTool extends SdkCallbackTool {
     }
     async call(input) {
         try {
-            const result = await fsp.readdir(this.resolve(input.path));
-            return JSON.stringify(result);
+            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/builtin/ReadFileTool.d.ts

@@ -6,5 +6,6 @@ export declare class ReadFileTool extends SdkCallbackTool {
     constructor(env: ToolEnv);
     call(input: {
         path: string;
+        range?: number[];
     }): Promise<string>;
 }

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

@@ -1,5 +1,6 @@
 import * as fsp from "fs/promises";
 import { SdkCallbackTool } from "../../../runtime/SdkCallbackTool.js";
+import { DEFAULT_MAX_TOOL_OUTPUT, guardOutput } from "./outputGuard.js";
 export class ReadFileTool extends SdkCallbackTool {
     function = {
         name: "readFile",
@@ -11,6 +12,14 @@ export class ReadFileTool extends SdkCallbackTool {
                     type: "string",
                     description: "文件路径",
                 },
+                range: {
+                    type: "array",
+                    description: "读取范围 [起始行, 起始列, 结束行, 结束列]，行列均从 0 开始，-1 表示末位；" +
+                        "例如 [0, 0, 100, -1] 表示从第 0 行第 0 列读到第 100 行最后一列。省略则读取整个文件。",
+                    items: {
+                        type: "number",
+                    },
+                },
             },
             required: ["path"],
             additionalProperties: false,
@@ -23,13 +32,63 @@ export class ReadFileTool extends SdkCallbackTool {
         try {
             const filePath = this.resolve(input.path);
             const stats = await fsp.stat(filePath);
+            // 读取阈值：文件过大时拒绝读取（与输出阈值 maxToolOutput 无关）
             if (stats.size > 300 * 1024) {
                 throw new Error(`文件过大，无法读取，当前文件大小 ${stats.size} 字节`);
             }
-            return await fsp.readFile(filePath, "utf-8");
+            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/builtin/index.d.ts

@@ -2,6 +2,7 @@ import type { SdkCallbackTool } from "../../../runtime/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,7 +21,7 @@ import { SleepTool } from "./SleepTool.js";
 import { ViewImageTool } from "./ViewImageTool.js";
 import { GenerateImageTool } from "./GenerateImageTool.js";
 /**
- * 全部内置工具类（19 个）。
+ * 全部内置工具类（20 个）。
  * 工具类由 Provider 用 ToolEnv 实例化（每个 Provider 一套实例，注入其 cwd）。
  *
  * 发现层不做任何过滤——工具的可用性由各工具自行声明（SdkCallbackTool.isAvailable，
@@ -28,4 +29,4 @@ import { GenerateImageTool } from "./GenerateImageTool.js";
  * 如 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/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,7 +19,7 @@ import { SleepTool } from "./SleepTool.js";
 import { ViewImageTool } from "./ViewImageTool.js";
 import { GenerateImageTool } from "./GenerateImageTool.js";
 /**
- * 全部内置工具类（19 个）。
+ * 全部内置工具类（20 个）。
  * 工具类由 Provider 用 ToolEnv 实例化（每个 Provider 一套实例，注入其 cwd）。
  *
  * 发现层不做任何过滤——工具的可用性由各工具自行声明（SdkCallbackTool.isAvailable，
@@ -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/capabilities/implements/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/capabilities/implements/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;
+}

package/dist/capabilities/implements/skillTools.d.ts

@@ -1,6 +1,5 @@
-import { CallbackTool } from "@ai-zen/agents-core";
+import { CallbackTool, AgentToolLazy } from "@ai-zen/agents-core";
 import type { SkillInfo } from "../discovery/skills.js";
-import type { Provider } from "../../runtime/Provider.js";
 /**
  * 创建 load_skill 工具。
  * 枚举所有允许的 skill（不限是否支持子 Agent），由 filteredSkills 提供完整信息。
@@ -10,6 +9,9 @@ export declare function createLoadSkillTool(skillDirs: string[], filteredSkills:
  * 创建 call_skill_sub_agent 工具。
  * 只展示 subAgent: true 的 Skill，枚举中自动排除不支持子 Agent 模式的 skill。
  *
- * 回调中创建独立的 Skill 子 Agent，通过 caps 按父 Agent 权限独立解析工具集。
+ * 工具由 AgentToolLazy 承载：子 Agent 在 exec 时构建，从而复用统一的委派边界
+ * （onSubAgentStart / onSubAgentEnd 钩子与 sub-agent-start / sub-agent-end 事件）。
+ * 子 Agent 沿用父 Agent 的工具能力（不做权限过滤），但剔除 call_skill_sub_agent 自身，
+ * 避免 skill 链式自递归。
  */
-export declare function createCallSkillSubAgentTool(skillDirs: string[], filteredSkills: SkillInfo[], provider?: Provider): CallbackTool;
+export declare function createCallSkillSubAgentTool(skillDirs: string[], filteredSkills: SkillInfo[]): AgentToolLazy;

package/dist/capabilities/implements/skillTools.js

@@ -1,5 +1,4 @@
-import { CallbackTool, Agent, Message } from "@ai-zen/agents-core";
-import { SdkAgent } from "../../runtime/SdkAgent.js";
+import { CallbackTool, Agent, AgentToolLazy, Message } from "@ai-zen/agents-core";
 import { createDisclosureParam } from "../disclosure.js";
 import { readSkill } from "../discovery/skills.js";
 import { getLogger } from "../../shared/logger.js";
@@ -70,9 +69,12 @@ export function createLoadSkillTool(skillDirs, filteredSkills) {
  * 创建 call_skill_sub_agent 工具。
  * 只展示 subAgent: true 的 Skill，枚举中自动排除不支持子 Agent 模式的 skill。
  *
- * 回调中创建独立的 Skill 子 Agent，通过 caps 按父 Agent 权限独立解析工具集。
+ * 工具由 AgentToolLazy 承载：子 Agent 在 exec 时构建，从而复用统一的委派边界
+ * （onSubAgentStart / onSubAgentEnd 钩子与 sub-agent-start / sub-agent-end 事件）。
+ * 子 Agent 沿用父 Agent 的工具能力（不做权限过滤），但剔除 call_skill_sub_agent 自身，
+ * 避免 skill 链式自递归。
  */
-export function createCallSkillSubAgentTool(skillDirs, filteredSkills, provider) {
+export function createCallSkillSubAgentTool(skillDirs, filteredSkills) {
     // 只保留支持子 Agent 模式的 skill
     const subAgentSkills = filteredSkills.filter((s) => s.subAgent);
     const ids = subAgentSkills.map((s) => s.id);
@@ -82,7 +84,7 @@ export function createCallSkillSubAgentTool(skillDirs, filteredSkills, provider)
         .map((s) => `  - ${s.id}: ${s.description || "无描述"}`)
         .join("\n");
     const skillIdDescription = `${param.description}\n\n各 Skill 说明：\n${skillDescriptions || "  无可用 Skill"}`;
-    return new CallbackTool({
+    return new AgentToolLazy({
         function: {
             name: "call_skill_sub_agent",
             description: "将任务委派给指定的 Skill 子 Agent，由其独立完成并返回结果。",
@@ -103,46 +105,28 @@ export function createCallSkillSubAgentTool(skillDirs, filteredSkills, provider)
                 additionalProperties: false,
             },
         },
-        async callback(input, ctx) {
-            const skillId = input.skill_id;
-            const task = input.task;
+        // 初始消息依赖运行时参数（skill_id → SKILL.md 内容），故不传 messages 模板，
+        // 由 buildAgent 读取 SKILL.md 后自行决定；abort 联动与委派边界由 AgentToolLazy 统一处理
+        buildAgent: async (parsedArgs, ctx) => {
+            const skillId = parsedArgs.skill_id;
+            const task = parsedArgs.task;
             const skill = await readSkill(skillDirs, skillId);
             if (!skill) {
-                return `❌ Skill "${skillId}" 不存在，请确认名称是否正确`;
+                throw new Error(`❌ Skill "${skillId}" 不存在，请确认名称是否正确`);
             }
             if (!skill.subAgent) {
-                return `Skill "${skillId}" 不支持子 Agent 模式，请使用 load_skill 加载指导后自行处理`;
+                throw new Error(`Skill "${skillId}" 不支持子 Agent 模式，请使用 load_skill 加载指导后自行处理`);
             }
-            // 临时 Skill 子 Agent 复用父 Agent 定义（权限 + 模型），排除当前 Skill 防自调用
+            // 沿用父 Agent 的工具能力（不做权限过滤），剔除自身以防自递归
             const parentAgent = ctx.agent;
-            const skillTools = provider && parentAgent instanceof SdkAgent
-                ? provider.buildTools(parentAgent.definition, {
-                    exclude: { skills: [skillId] },
-                })
-                : [];
-            const subAgent = new Agent({
+            const tools = parentAgent.tools.filter((t) => t.function.name !== "call_skill_sub_agent");
+            return new Agent({
                 client: parentAgent.client,
                 model: parentAgent.model,
                 modelConfig: parentAgent.modelConfig,
-                messages: [
-                    Message.System(skill.content),
-                    Message.User(task),
-                ],
-                tools: skillTools,
+                messages: [Message.System(skill.content), Message.User(task)],
+                tools,
             });
-            // 子 Agent 中断联动：外层 abort → subAgent.abort()
-            const onAbort = () => subAgent.abort();
-            if (ctx.signal) {
-                ctx.signal.addEventListener("abort", onAbort, { once: true });
-            }
-            try {
-                await subAgent.run();
-            }
-            finally {
-                ctx.signal?.removeEventListener("abort", onAbort);
-            }
-            const lastMsg = subAgent.messages.at(-1);
-            return typeof lastMsg?.content === "string" ? lastMsg.content : "";
         },
     });
 }

package/dist/config/ConfigManager.d.ts

@@ -23,7 +23,9 @@ export declare class ConfigManager {
     /**
      * 确保 basePath/agents/default.json 存在。
      *
-     * - default.json 已存在 → 返回已有定义，不覆盖
+     * - default.json 已存在且 custom === true → 用户声明为自定义，原样返回，不做任何改动
+     * - default.json 已存在且 custom !== true → 仅同步出厂提示词（messages），
+     *   其余字段（name/permissions/modelId 等）保留；提示词一致时不写盘
      * - agents/ 为空 → 写入默认 Agent
      * - 已有其他 Agent → 返回 null
      */

package/dist/config/ConfigManager.js

@@ -69,7 +69,9 @@ export class ConfigManager {
     /**
      * 确保 basePath/agents/default.json 存在。
      *
-     * - default.json 已存在 → 返回已有定义，不覆盖
+     * - default.json 已存在且 custom === true → 用户声明为自定义，原样返回，不做任何改动
+     * - default.json 已存在且 custom !== true → 仅同步出厂提示词（messages），
+     *   其余字段（name/permissions/modelId 等）保留；提示词一致时不写盘
      * - agents/ 为空 → 写入默认 Agent
      * - 已有其他 Agent → 返回 null
      */
@@ -77,11 +79,24 @@ export class ConfigManager {
         const agentsDir = join(this.basePath, "agents");
         const defaultPath = join(agentsDir, `${DEFAULT_AGENT_ID}.json`);
         try {
-            await fs.access(defaultPath);
-            return JSON.parse(await fs.readFile(defaultPath, "utf-8"));
+            const existing = JSON.parse(await fs.readFile(defaultPath, "utf-8"));
+            // 用户声明为自定义 → 完全跳过替换
+            if (existing.custom === true)
+                return existing;
+            // 仅同步提示词；内容一致则不写盘、不动时间戳
+            const messages = DEFAULT_AGENT_DEFINITION.messages;
+            if (sameMessages(existing.messages ?? [], messages))
+                return existing;
+            const updated = {
+                ...existing,
+                messages,
+                updatedAt: new Date().toISOString(),
+            };
+            await fs.writeFile(defaultPath, JSON.stringify(updated, null, 2), "utf-8");
+            return updated;
         }
         catch {
-            // default.json 不存在，继续
+            // 文件不存在或不可解析，继续走初始化流程
         }
         await fs.mkdir(agentsDir, { recursive: true });
         let existing;
@@ -219,4 +234,16 @@ export class ConfigManager {
         await fs.rename(tmpPath, path);
     }
 }
+/**
+ * 比较两段消息列表的提示词内容是否一致。
+ *
+ * 只比较 role 与 content，忽略 id 等每次生成都可能变化的字段，
+ * 避免因 id 差异导致无意义的重复写盘与时间戳漂移。
+ */
+function sameMessages(a, b) {
+    if (a.length !== b.length)
+        return false;
+    return a.every((message, index) => message.role === b[index].role &&
+        JSON.stringify(message.content) === JSON.stringify(b[index].content));
+}
 export { DEFAULT_AGENT_ID, DEFAULT_AGENT_DEFINITION, DEFAULT_SUBAGENT_ID, DEFAULT_SUBAGENT_DEFINITION, DEFAULT_APP_CONFIG, DEFAULT_MCP_CONFIG, CONFIG_SUB_DIRS, } from "./constants.js";

package/dist/config/constants.js

@@ -12,8 +12,11 @@ export const DEFAULT_AGENT_DEFINITION = {
     messages: [
         Message.System(`你是一个幽默风趣、严谨可靠的智能助手，请用中文回复。当前操作系统：${process.platform}。
 
-惜字如金：只交代结果和必要说明，执行过程（工具调用、读写、搜索等）用户均已可见，不必再复述。遇到任何不明确、不确定、有矛盾或可能影响结果的状况，立即停下并直接询问用户，而不是自行脑补、猜测或硬干。除此之外，主动调用工具、如实汇报，并只在你被指定的工作范围内行事。`),
+一、需要用户决策时，一次只问一个问题。
+二、当前对话基于 Node.js 驱动，你可以编写 Node.js 脚本执行复杂任务，并通过 exec 工具运行。`),
     ],
+    // 出厂默认 Agent：custom 为 false，SDK 初始化时会同步出厂提示词（用户设为 true 则跳过）
+    custom: false,
     permissions: {
         tools: { allow: ["*"] },
         skills: { allow: ["*"] },
@@ -177,6 +180,8 @@ export const DEFAULT_APP_CONFIG = {
     defaultImageModel: "cogview-4",
     defaultAgent: "default",
     defaultMigrationModel: "deepseek-v4-flash",
+    // 工具输出上限（字符数），与 DEFAULT_MAX_TOOL_OUTPUT 保持一致
+    maxToolOutput: 32_768,
 };
 // ---------------------------------------------------------------------------
 // 默认 MCP 配置（socket-pty 终端 MCP）

package/dist/index.d.ts

@@ -31,7 +31,7 @@ export { ContextGuardPlugin } from "./plugin/ContextGuardPlugin.js";
 export type { ContextGuardOptions } from "./plugin/ContextGuardPlugin.js";
 export { UnknownToolHintPlugin } from "./plugin/UnknownToolHintPlugin.js";
 export { BUILTIN_TOOL_CLASSES } from "./capabilities/implements/builtin/index.js";
-export { CwdTool, ReadFileTool, WriteFileTool, ExecTool, MkdirTool, RmTool, GlobTool, LsTool, ExistTool, FindTextTool, DownloadFileTool, RenameTool, CopyTool, BatchEditTool, EditTool, ExecAsyncTool, SleepTool, } from "./capabilities/implements/builtin/index.js";
+export { CwdTool, ReadFileTool, InspectFileTool, WriteFileTool, ExecTool, MkdirTool, RmTool, GlobTool, LsTool, ExistTool, FindTextTool, DownloadFileTool, RenameTool, CopyTool, BatchEditTool, EditTool, ExecAsyncTool, SleepTool, } from "./capabilities/implements/builtin/index.js";
 export { GenerateImageTool } from "./capabilities/implements/builtin/GenerateImageTool.js";
 export { ViewImageTool } from "./capabilities/implements/builtin/ViewImageTool.js";
 export { createLoadSkillTool, createCallSkillSubAgentTool } from "./capabilities/implements/skillTools.js";

package/dist/index.js

@@ -27,7 +27,7 @@ export { ContextGuardPlugin } from "./plugin/ContextGuardPlugin.js";
 export { UnknownToolHintPlugin } from "./plugin/UnknownToolHintPlugin.js";
 // 工具 — 内置工具类 + 动态工具工厂
 export { BUILTIN_TOOL_CLASSES } from "./capabilities/implements/builtin/index.js";
-export { CwdTool, ReadFileTool, WriteFileTool, ExecTool, MkdirTool, RmTool, GlobTool, LsTool, ExistTool, FindTextTool, DownloadFileTool, RenameTool, CopyTool, BatchEditTool, EditTool, ExecAsyncTool, SleepTool, } from "./capabilities/implements/builtin/index.js";
+export { CwdTool, ReadFileTool, InspectFileTool, WriteFileTool, ExecTool, MkdirTool, RmTool, GlobTool, LsTool, ExistTool, FindTextTool, DownloadFileTool, RenameTool, CopyTool, BatchEditTool, EditTool, ExecAsyncTool, SleepTool, } from "./capabilities/implements/builtin/index.js";
 export { GenerateImageTool } from "./capabilities/implements/builtin/GenerateImageTool.js";
 export { ViewImageTool } from "./capabilities/implements/builtin/ViewImageTool.js";
 export { createLoadSkillTool, createCallSkillSubAgentTool } from "./capabilities/implements/skillTools.js";

package/dist/runtime/Provider.js

@@ -170,7 +170,7 @@ export class Provider {
         // call_skill_sub_agent：只要有支持子 Agent 的 skill 就注册
         const hasSubAgentSkills = filteredSkills.some((s) => s.subAgent);
         if (allowedToolNames.has("call_skill_sub_agent") && hasSubAgentSkills) {
-            result.push(createCallSkillSubAgentTool(this.skillsPaths, filteredSkills, this));
+            result.push(createCallSkillSubAgentTool(this.skillsPaths, filteredSkills));
         }
         const mcpManager = this.mcpManager;
         if (allowedToolNames.has("load_mcp") && mcpManager && filteredMcps.length > 0) {

package/dist/types/index.d.ts

@@ -46,6 +46,13 @@ export interface AgentDefinition {
     createdAt: string;
     updatedAt: string;
     version?: number;
+    /**
+     * 是否用户自定义。
+     *
+     * 为 true 时 SDK 初始化不会同步/替换该 Agent 的内置内容（如默认提示词）；
+     * 缺省（或为 false）时，初始化会以出厂定义同步其提示词，其余字段保留。
+     */
+    custom?: boolean;
 }
 /** 图片生成模型配置 */
 export interface ImageModel {
@@ -71,6 +78,14 @@ export interface AppConfig {
     defaultAgent?: string;
     /** 默认迁移模型 ID */
     defaultMigrationModel?: string;
+    /**
+     * 工具输出上限（字符数），缺省取 32768。
+     *
+     * 工具本次输出超过该值时，由工具自身的保护策略处置（落盘或仅警告），
+     * 避免超长输出撑爆上下文。仅作用于"输出"，与工具的读取阈值无关
+     * （如 readFile/findText 对 300KB 文件的读取上限）。
+     */
+    maxToolOutput?: number;
 }
 /**
  * 工具环境 — Provider 在实例化内置工具时注入的环境信息。

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ai-zen/agents-sdk",
-  "version": "0.10.0",
+  "version": "0.12.0",
   "description": "AI-Zen Agents SDK — shared business logic for CLI and Desktop",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -16,7 +16,7 @@
   "author": "LZQCN",
   "license": "MIT",
   "dependencies": {
-    "@ai-zen/agents-core": "^4.2.0",
+    "@ai-zen/agents-core": "^4.3.0",
     "@modelcontextprotocol/sdk": "^1.29.0",
     "dayjs": "^1.11.21",
     "openai": "^7.5.0"