@ai-zen/agents-sdk 1.0.0-alpha.1 → 1.0.0-alpha.11

package/dist/runtime/HandoffService.js

@@ -0,0 +1,372 @@
+import { promises as fs } from "node:fs";
+import { dirname, join, resolve as resolvePath } from "node:path";
+import { Message } from "@ai-zen/agents-core";
+import { getLogger } from "../shared/logger.js";
+import { readSkill } from "../scope/plugins/skills/discover.js";
+import { FALLBACK_HANDOFF_TEMPLATE, HANDOFF_SKILL_ID } from "../config/factory-skills.js";
+import { HandoffGuardPlugin } from "./HandoffGuardPlugin.js";
+/**
+ * 任务交接服务。
+ *
+ * 职责分层（这是本模块唯一的设计主线）：
+ *   - `handoff()`：**只产出交接文档**（停工 → 写文档 → 校验 → 失败降级），不动会话；
+ *   - `migrate()`：`handoff()` 之后清历史并开新会话（原「任务迁移」语义）。
+ *
+ * 模板的唯一真相源是 `handoff` Skill（`SKILL.md`）；代码只负责
+ * 「读正文 → 注入 → 校验文件 → 读不到时用兜底模板」，不持有第二份章节清单。
+ *
+ * 重入：`handoff()` 与 `migrate()` 共用 `busy` 标志。交接回合本身也是一次 `send()`，
+ * 若不在 busy 期间让 `AutoMigratePlugin` / `ContextGuardPlugin` 让行，就会「交接触发迁移、
+ * 迁移再触发交接」无限递归，或在最满的时刻被护栏直接击杀。
+ */
+export class HandoffService {
+    /** 交接文档兜底模板（仅在读不到 Skill 时使用） */
+    static FALLBACK_TEMPLATE = FALLBACK_HANDOFF_TEMPLATE;
+    handoffDirPath;
+    defaultMode;
+    defaultStrategy;
+    skillDirs;
+    client;
+    model;
+    modelConfig;
+    minHandoffBytes;
+    onBeforeHandoff;
+    onHandoff;
+    onMigrated;
+    logger;
+    /** 交接/迁移进行中标志（插件据此让行） */
+    _busy = false;
+    /** 交接回合的工具守卫（同一实例复用 + arm/disarm，避免插件数组无限增长） */
+    guard;
+    /** 已注册过守卫的 agent（每个 agent 只 use 一次） */
+    guardedAgents = new WeakSet();
+    constructor(options = {}) {
+        const { handoffDir, mode, strategy, skillDirs, client, model, modelConfig, minHandoffBytes, onBeforeHandoff, onHandoff, onMigrated, logger, } = options;
+        this.handoffDirPath = resolvePath(handoffDir ?? join(process.cwd(), ".ai-zen", "handoffs"));
+        this.defaultMode = mode ?? "self";
+        this.defaultStrategy = strategy ?? "omit";
+        this.skillDirs = skillDirs ?? [];
+        this.client = client;
+        this.model = model;
+        this.modelConfig = modelConfig;
+        this.minHandoffBytes = minHandoffBytes ?? 400;
+        this.onBeforeHandoff = onBeforeHandoff;
+        this.onHandoff = onHandoff;
+        this.onMigrated = onMigrated;
+        this.logger = logger ?? getLogger();
+    }
+    /** 是否正在交接/迁移（`AutoMigratePlugin` / `ContextGuardPlugin` 据此让行） */
+    get busy() {
+        return this._busy;
+    }
+    /** 交接文档目录 */
+    get handoffDir() {
+        return this.handoffDirPath;
+    }
+    // ==================================================================
+    // 静态纯工具（供上层复用 / 单测）
+    // ==================================================================
+    /**
+     * 交接文件名：`<YYYYMMDD-HHmmss>-<会话id前8位>.md`（本地时间，便于人眼归档）。
+     */
+    static createHandoffFileName(date = new Date(), conversationId) {
+        const p = (n) => String(n).padStart(2, "0");
+        const stamp = `${date.getFullYear()}${p(date.getMonth() + 1)}${p(date.getDate())}` +
+            `-${p(date.getHours())}${p(date.getMinutes())}${p(date.getSeconds())}`;
+        const suffix = conversationId ? `-${conversationId.slice(0, 8)}` : "";
+        return `${stamp}${suffix}.md`;
+    }
+    /**
+     * 拼装「本轮交接」指令：`[Skill 正文] + [本次交接参数]`。
+     *
+     * 不在 Skill 正文里发明占位符（本体系没有模板变量引擎），参数一律由代码拼在后面，
+     * 这样 Skill 只讲「怎么写」、代码只讲「写到哪、有什么能力」。
+     */
+    static createHandoffInstruction(params) {
+        const { skillContent, handoffPath, toolsAvailable } = params;
+        const tail = toolsAvailable
+            ? [
+                "请立即开始撰写，并用 write 工具把完整文档写入上面给出的路径（路径原样使用，不要改名、不要换目录）。",
+                "写完后用 read 回读一次确认完整，然后只回一句不超过 40 字的确认，**不要复述文档内容**。",
+            ]
+            : [
+                "请直接输出完整文档正文：不要任何解释、不要用代码块包裹，调用方会自行落盘。",
+            ];
+        return [
+            "你现在要为本轮对话编写一份任务交接文档。以下是必须遵守的交接规范。",
+            "",
+            "---",
+            "",
+            skillContent.trim(),
+            "",
+            "---",
+            "",
+            "## 本次交接参数",
+            `- 交接文档绝对路径：${handoffPath}`,
+            `- 工具能力：${toolsAvailable
+                ? "可用（read / exec 等，请据此核实真实状态）"
+                : "不可用（你无法核实磁盘，状态类信息一律写「⚠️ 未核实」，禁止推测）"}`,
+            "",
+            ...tail,
+        ].join("\n");
+    }
+    /**
+     * 生成迁移后追加的「交接断点」消息（role=user）：只给路径，让接手方自己 read。
+     *
+     * 为什么不内联全文：接手方第一次真正需要的是「去哪里取交接」，读一次文件的输入成本
+     * 与内联全文相当，但内联会让每条请求都携带全文；路径方案把成本推迟到真正需要时。
+     */
+    static createPostMessages(handoffPath) {
+        const content = [
+            "上一轮对话已交接，交接文档保存在：",
+            handoffPath,
+            "",
+            "请先用 read 工具读取该文件，理解上下文与未完成事项后，再继续协助用户完成任务。",
+        ].join("\n");
+        return [Message.User(content)];
+    }
+    /** 序列化消息为 `[role]: content` 文本（仅 `summary` 模式使用） */
+    static serializeMessages(messages) {
+        return messages
+            .map((m) => {
+            const role = m.role ?? "unknown";
+            const content = typeof m.content === "string" ? m.content : JSON.stringify(m.content);
+            return `[${role}]: ${content}`;
+        })
+            .join("\n\n");
+    }
+    // ==================================================================
+    // 公开流程
+    // ==================================================================
+    /**
+     * 只产出交接文档，**不改动会话**（`/handoff`）。
+     *
+     * 不清理历史：交接回合（指令 + 工具调用 + 回执）会留在 `agent.messages` 里，
+     * 用户可继续让 agent 打磨这份文档（重写同一路径即可）。
+     */
+    async handoff(params) {
+        return this.withBusy(() => this.runHandoff(params, false));
+    }
+    /**
+     * 交接 + 开新会话（`/migrate`、自动迁移）。
+     *
+     * 策略（`strategy`）：
+     *   - `omit`（默认）：历史标记 `omit: true`（保留可审计），末尾追加交接断点；
+     *   - `prune`：物理剔除历史，只留 `definition.messages` + 交接断点。
+     */
+    async migrate(params) {
+        return this.withBusy(async () => {
+            const ctx = await this.runHandoff(params, true);
+            const { agent } = ctx;
+            const strategy = params.strategy ?? this.defaultStrategy;
+            const breakpointMessages = HandoffService.createPostMessages(ctx.handoffPath);
+            if (strategy === "prune") {
+                // 浅拷贝模板消息，避免污染 definition.messages 引用的对象
+                agent.messages = [...agent.definition.messages, ...breakpointMessages];
+            }
+            else {
+                const preserveCount = Math.min(agent.definition.messages.length, agent.messages.length);
+                agent.messages = [
+                    ...agent.messages.map((m, i) => ({
+                        ...m,
+                        omit: i >= preserveCount ? true : m.omit,
+                    })),
+                    ...breakpointMessages,
+                ];
+            }
+            await this.safeHook(this.onMigrated, ctx);
+            return ctx;
+        });
+    }
+    // ==================================================================
+    // 内部
+    // ==================================================================
+    /** 串行化 + 防重入：交接与迁移共用同一把锁 */
+    async withBusy(fn) {
+        if (this._busy)
+            throw new Error("交接流程已在进行中，请等待当前交接完成");
+        this._busy = true;
+        try {
+            return await fn();
+        }
+        finally {
+            this._busy = false;
+        }
+    }
+    async runHandoff(params, migrating) {
+        const { agent, promptTokens, maxTokens, conversationId } = params;
+        const requestedMode = params.mode ?? this.defaultMode;
+        const handoffPath = join(this.handoffDirPath, HandoffService.createHandoffFileName(new Date(), conversationId));
+        const model = this.model ?? agent.model;
+        const messageCountBefore = agent.messages.length;
+        // 迁移前上下文（不含文档，语义固定）
+        const beforeCtx = {
+            agent,
+            mode: requestedMode,
+            requestedMode,
+            handoffPath,
+            model,
+            promptTokens,
+            maxTokens,
+            migrating,
+            messageCountBefore,
+            historyText: "",
+        };
+        await this.safeHook(this.onBeforeHandoff, beforeCtx);
+        // ---- 执行者：self 优先，失败/不可用则单向降级 summary ----
+        let mode = requestedMode;
+        let handoffDoc;
+        let historyText = "";
+        if (mode === "self" && !this.supportsSelfHandoff(agent)) {
+            this.logger.warn("[handoff] agent 不具备 write 工具或 send 能力，降级为独立摘要模式");
+            mode = "summary";
+        }
+        if (mode === "self") {
+            const ok = await this.runSelfHandoff(agent, handoffPath);
+            if (!ok) {
+                this.logger.warn("[handoff] 自交接失败，降级为独立摘要模式");
+                mode = "summary";
+            }
+        }
+        if (mode === "summary") {
+            historyText = HandoffService.serializeMessages(agent.messages.filter((m) => !m.omit));
+            handoffDoc = await this.generateSummary(agent, historyText, handoffPath);
+            await this.writeHandoffFile(handoffPath, handoffDoc);
+        }
+        const ctx = {
+            agent,
+            mode,
+            requestedMode,
+            handoffPath,
+            handoffDoc,
+            model,
+            promptTokens,
+            maxTokens,
+            migrating,
+            messageCountBefore,
+            historyText,
+        };
+        await this.safeHook(this.onHandoff, ctx);
+        return ctx;
+    }
+    /** 自交接是否可用：需要 `write` 工具 + `send` 能力 */
+    supportsSelfHandoff(agent) {
+        if (typeof agent.send !== "function")
+            return false;
+        return Boolean(agent.tools?.some((tool) => tool.function?.name === "write"));
+    }
+    /**
+     * 自交接回合：让原 agent 停工、核实、写文档，并校验文件确实落盘。
+     *
+     * 失败判定（任一成立即视为失败，交由上层单向降级 summary）：
+     *   - 文件不存在 / 小于阈值；
+     *   - 模型/工具链抛错（例如没有权限、被护栏中断）。
+     */
+    async runSelfHandoff(agent, handoffPath) {
+        const guard = this.ensureGuard(agent);
+        const skillContent = await this.readSkillContent();
+        const cwd = agent.scope?.cwd ?? process.cwd();
+        /*
+         * 清空 lastUsage 再开跑：
+         *   - 护栏（ContextGuardPlugin）在每轮请求前用 lastUsage 判定严重超限，
+         *     而交接恰好发生在上下文最满的时刻；
+         *   - AutoMigratePlugin 也会读它。busy 已能让两者让行，这里再清一次是纵深防御。
+         * 交接回合结束后 lastUsage 由本轮真实响应用量回填，无需恢复旧值。
+         */
+        agent.lastUsage = undefined;
+        guard.arm(handoffPath, cwd);
+        try {
+            await agent.send(HandoffService.createHandoffInstruction({
+                skillContent,
+                handoffPath,
+                toolsAvailable: true,
+            }));
+            if (await this.isHandoffFileReady(handoffPath))
+                return true;
+            this.logger.warn(`[handoff] 交接文档缺失或过小，重试一次：${handoffPath}`);
+            await agent.send([
+                `交接文档不存在或内容过少，无法交付：${handoffPath}`,
+                "请立即用 write 工具把**完整**交接文档写入该路径（路径原样使用），不要做其他任何事。",
+            ].join("\n"));
+            return await this.isHandoffFileReady(handoffPath);
+        }
+        catch (err) {
+            this.logger.error(`[handoff] 自交接回合失败：${err?.message ?? err}`);
+            return false;
+        }
+        finally {
+            guard.disarm();
+        }
+    }
+    /** 独立摘要：一次模型调用，用同一份 Skill 正文作为规范 */
+    async generateSummary(agent, historyText, handoffPath) {
+        const client = this.client ?? agent.client;
+        const model = this.model ?? agent.model;
+        const modelConfig = this.modelConfig ?? agent.modelConfig;
+        const skillContent = await this.readSkillContent();
+        const response = await client.chat.completions.create({
+            model,
+            ...(modelConfig ?? {}),
+            messages: [
+                {
+                    role: "system",
+                    content: HandoffService.createHandoffInstruction({
+                        skillContent,
+                        handoffPath,
+                        toolsAvailable: false,
+                    }),
+                },
+                { role: "user", content: historyText },
+            ],
+        });
+        const handoffDoc = response.choices[0]?.message?.content;
+        if (!handoffDoc || !handoffDoc.trim()) {
+            throw new Error("未能生成任务交接文档");
+        }
+        return handoffDoc;
+    }
+    /** 落盘（仅 `summary` 模式需要；`self` 模式由 agent 的 write 工具完成） */
+    async writeHandoffFile(handoffPath, content) {
+        await fs.mkdir(dirname(handoffPath), { recursive: true });
+        await fs.writeFile(handoffPath, content, "utf-8");
+    }
+    /** 交接文档是否可用：文件存在且不小于阈值（不读内容，避免二次读取） */ async isHandoffFileReady(handoffPath) {
+        try {
+            const stat = await fs.stat(handoffPath);
+            return stat.isFile() && stat.size >= this.minHandoffBytes;
+        }
+        catch {
+            return false;
+        }
+    }
+    /** 读取 `handoff` Skill 正文；读不到时回落到兜底模板 */
+    async readSkillContent() {
+        if (this.skillDirs.length > 0) {
+            const skill = await readSkill(this.skillDirs, HANDOFF_SKILL_ID, { silent: true });
+            if (skill?.content?.trim())
+                return skill.content;
+        }
+        this.logger.warn(`[handoff] 未找到 ${HANDOFF_SKILL_ID} Skill，使用内置兜底模板（路径：${this.skillDirs.join(", ") || "未配置"}）`);
+        return FALLBACK_HANDOFF_TEMPLATE;
+    }
+    /** 守卫按 agent 注册一次（`Agent.use()` 无移除 API，故复用实例 + 开关） */
+    ensureGuard(agent) {
+        const guard = (this.guard ??= new HandoffGuardPlugin());
+        if (!this.guardedAgents.has(agent)) {
+            agent.use(guard);
+            this.guardedAgents.add(agent);
+        }
+        return guard;
+    }
+    /** 钩子容错：抛错只记录，不中断交接（与既有迁移钩子语义一致） */
+    async safeHook(hook, ctx) {
+        if (!hook)
+            return;
+        try {
+            await hook(ctx);
+        }
+        catch (err) {
+            this.logger.error(`[handoff] 钩子执行失败: ${err?.message ?? err}`);
+        }
+    }
+}

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

@@ -2,7 +2,7 @@ import * as fsp from "fs/promises";
 import { SdkCallbackTool } from "./SdkCallbackTool.js";
 export class BatchEditTool extends SdkCallbackTool {
     function = {
-        name: "batchEdit",
+        name: "batch_edit",
         description: "批量编辑文件文本，可以优先使用这个工具对文件进行编辑",
         parameters: {
             type: "object",

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

@@ -3,7 +3,7 @@ import * as path from "path";
 import { SdkCallbackTool } from "./SdkCallbackTool.js";
 export class DownloadFileTool extends SdkCallbackTool {
     function = {
-        name: "downloadFile",
+        name: "download_file",
         description: "从 URL 下载文件（图片、PDF 等二进制文件）并保存到本地磁盘。自动从 URL 推断文件名，也可指定保存路径。",
         parameters: {
             type: "object",

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

@@ -14,7 +14,7 @@ export class ExecTool extends SdkCallbackTool {
                 },
                 timeout: {
                     type: "number",
-                    description: "超时时间（毫秒），必填。超时后会终止进程；超过该时长仍未完成即视为超时并终止。建议长时间运行的命令使用 exec_async 异步执行。",
+                    description: "超时时间（毫秒），必填。超时后会终止进程；超过该时长仍未完成即视为超时并终止。建议长时间运行的命令使用 spawn 异步执行。",
                 },
             },
             required: ["command", "timeout"],
@@ -98,7 +98,7 @@ export class ExecTool extends SdkCallbackTool {
                 return JSON.stringify({
                     outputTooLarge: true,
                     warning: `输出过大：stdout + stderr 合计 ${result.stdout.length + result.stderr.length} 字符，` +
-                        `超过上限 ${limit} 字符。完整内容已分文件落盘（stdout.log / stderr.log），可用 readFile 分批读取。`,
+                        `超过上限 ${limit} 字符。完整内容已分文件落盘（stdout.log / stderr.log），可用 read 分批读取。`,
                     files: ctx.files,
                     stdout: { chars: result.stdout.length, lines: countLines(result.stdout), ...stdout },
                     stderr: { chars: result.stderr.length, lines: countLines(result.stderr), ...stderr },

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

@@ -4,13 +4,13 @@ import { SdkCallbackTool } from "./SdkCallbackTool.js";
 import { DEFAULT_MAX_TOOL_OUTPUT, guardOutput, headPreview } from "./outputGuard.js";
 /** 默认总匹配数上限 */
 const DEFAULT_MAX_MATCHES = 200;
-/** 默认文件大小上限（字节，与 ReadFileTool 的 300KB 口径一致） */
+/** 默认文件大小上限（字节，与 ReadTool 的 300KB 口径一致） */
 const DEFAULT_MAX_FILE_SIZE = 300 * 1024;
 /** 默认行内容/匹配子串截断长度 */
 const DEFAULT_MAX_LINE_LENGTH = 200;
 export class FindTextTool extends SdkCallbackTool {
     function = {
-        name: "findText",
+        name: "find_text",
         description: "查找文本出现的位置，支持普通文本或正则匹配，返回文件名及具体行号、行内容。为避免结果撑爆上下文，默认限制总匹配数、单文件大小与行内容长度，超限会截断并标记 truncated。",
         parameters: {
             type: "object",
@@ -89,12 +89,12 @@ export class FindTextTool extends SdkCallbackTool {
                     break; // 中断：stat 后再次检查
                 if (!stats.isFile())
                     continue;
-                // 文件过大则跳过（避免撑爆上下文；与 ReadFileTool 300KB 口径一致，但此处为跳过而非报错）
+                // 文件过大则跳过（避免撑爆上下文；与 ReadTool 300KB 口径一致，但此处为跳过而非报错）
                 if (stats.size > maxFileSize)
                     continue;
                 const content = await fsp.readFile(fullPath, "utf-8");
                 if (signal?.aborted)
-                    break; // 中断：readFile 后再次检查
+                    break; // 中断：read 后再次检查
                 const lines = content.split("\n");
                 const matches = [];
                 for (let index = 0; index < lines.length; index++) {
@@ -145,7 +145,7 @@ export class FindTextTool extends SdkCallbackTool {
     async protect(json) {
         const limit = this.env.config.maxToolOutput ?? DEFAULT_MAX_TOOL_OUTPUT;
         return await guardOutput({
-            tool: "findText",
+            tool: "find_text",
             content: json,
             isOverLimit: (text) => text.length > limit,
             dump: (_dir, text) => [{ name: "result.json", content: text }],
@@ -154,7 +154,7 @@ export class FindTextTool extends SdkCallbackTool {
                 return JSON.stringify({
                     outputTooLarge: true,
                     warning: `输出过大：结果共 ${json.length} 字符，超过上限 ${limit} 字符。` +
-                        `完整结果已落盘（result.json），可用 readFile 分批读取。`,
+                        `完整结果已落盘（result.json），可用 read 分批读取。`,
                     files: ctx.files,
                     chars: json.length,
                     ...preview,

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

@@ -4,7 +4,7 @@ import type { AgentDefinition, AppConfig, ToolEnv } from "../../../types/index.j
 /**
  * 根据文字描述生成图片。**统一返回字符串**（JSON，含图片 URL 列表）：
  * 生成结果如何处理（查看/下载/转发）由模型与上层自由决定——
- * 需要让模型看图时，模型可主动调用 viewImage(URL)；需要保存时用 downloadFile。
+ * 需要让模型看图时，模型可主动调用 view_image(URL)；需要保存时用 download_file。
  *
  * 依赖 AppConfig 中的 imageModels 和 defaultImageModel 配置（isAvailable 声明），
  * 未配置时由 buildTools 过滤，不暴露给 Agent。

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

@@ -3,7 +3,7 @@ import { SdkCallbackTool } from "./SdkCallbackTool.js";
 /**
  * 根据文字描述生成图片。**统一返回字符串**（JSON，含图片 URL 列表）：
  * 生成结果如何处理（查看/下载/转发）由模型与上层自由决定——
- * 需要让模型看图时，模型可主动调用 viewImage(URL)；需要保存时用 downloadFile。
+ * 需要让模型看图时，模型可主动调用 view_image(URL)；需要保存时用 download_file。
  *
  * 依赖 AppConfig 中的 imageModels 和 defaultImageModel 配置（isAvailable 声明），
  * 未配置时由 buildTools 过滤，不暴露给 Agent。
@@ -14,8 +14,8 @@ export class GenerateImageTool extends SdkCallbackTool {
         return !!config.defaultImageModel;
     }
     function = {
-        name: "generateImage",
-        description: "根据文字描述生成图片，返回图片 URL 列表（JSON）。如需查看图片内容，请用 viewImage 工具（传入图片 URL）；如需保存到本地，用 downloadFile 下载。",
+        name: "generate_image",
+        description: "根据文字描述生成图片，返回图片 URL 列表（JSON）。如需查看图片内容，请用 view_image 工具（传入图片 URL）；如需保存到本地，用 download_file 下载。",
         parameters: {
             type: "object",
             properties: {
@@ -25,7 +25,7 @@ export class GenerateImageTool extends SdkCallbackTool {
                 },
                 model: {
                     type: "string",
-                    description: "图片模型 ID，不指定则使用配置中的默认图片模型。配置中的图片模型可通过 'aiz config show' 查看。",
+                    description: "图片模型 ID，不指定则使用配置中的默认图片模型；若指定的模型不存在，本工具会返回当前可用的模型列表。",
                 },
                 size: {
                     type: "string",
@@ -99,15 +99,15 @@ export class GenerateImageTool extends SdkCallbackTool {
                 .map((img) => img.url)
                 .filter((url) => !!url);
             // 统一返回字符串（JSON）：生成结果如何处理（查看/下载/转发）由模型与上层自由决定，
-            // 不替模型做「看或不看」的假设。需要让模型看图 → 模型可主动调用 viewImage(URL)；
-            // 需要保存 → downloadFile 下载。
+            // 不替模型做「看或不看」的假设。需要让模型看图 → 模型可主动调用 view_image(URL)；
+            // 需要保存 → download_file 下载。
             return JSON.stringify({
                 success: true,
                 model: imageModel.name,
                 modelId: imageModel.id,
                 created: result.created,
                 images: urls.map((url, i) => ({ index: i, url })),
-                note: "图片临时链接有效期为30天。如需查看图片内容，可用 viewImage 工具（传入图片 URL）；如需保存，可用 downloadFile 下载。",
+                note: "图片临时链接有效期为30天。如需查看图片内容，可用 view_image 工具（传入图片 URL）；如需保存，可用 download_file 下载。",
             }, null, 2);
         }
         catch (error) {

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

@@ -69,7 +69,7 @@ export class GlobTool extends SdkCallbackTool {
                 return JSON.stringify({
                     outputTooLarge: true,
                     warning: `输出过大：匹配结果共 ${json.length} 字符，超过上限 ${limit} 字符。` +
-                        `完整结果已落盘（result.json），可用 readFile 分批读取；` +
+                        `完整结果已落盘（result.json），可用 read 分批读取；` +
                         `也可用更精确的 pattern 或 exclude 缩小范围后重新查找。`,
                     files: ctx.files,
                     chars: json.length,

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

@@ -4,8 +4,8 @@ import type { AgentNS } from "@ai-zen/agents-core";
 /**
  * 勘察文件结构概况（行数、每行列数等），不做内容读取。
  *
- * 定位与 readFile 的 range 配套：大文件先看结构（有多少行、每行多长），
- * 再决定 readFile 的读取范围。流式扫描，故不受 readFile 的 300KB 读取阈值限制。
+ * 定位与 read 的 range 配套：大文件先看结构（有多少行、每行多长），
+ * 再决定 read 的读取范围。流式扫描，故不受 read 的 300KB 读取阈值限制。
  */
 export declare class InspectFileTool extends SdkCallbackTool {
     function: AgentNS.FunctionDefine;

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

@@ -6,13 +6,13 @@ import { DEFAULT_MAX_TOOL_OUTPUT } from "./outputGuard.js";
 /**
  * 勘察文件结构概况（行数、每行列数等），不做内容读取。
  *
- * 定位与 readFile 的 range 配套：大文件先看结构（有多少行、每行多长），
- * 再决定 readFile 的读取范围。流式扫描，故不受 readFile 的 300KB 读取阈值限制。
+ * 定位与 read 的 range 配套：大文件先看结构（有多少行、每行多长），
+ * 再决定 read 的读取范围。流式扫描，故不受 read 的 300KB 读取阈值限制。
  */
 export class InspectFileTool extends SdkCallbackTool {
     function = {
-        name: "inspectFile",
-        description: "勘察文件的结构概况：总行数、总字符数、最长行的列数及其行索引、平均列数、行尾类型（LF/CRLF）。可选返回每行的列数映射。适用于在 readFile 之前先了解文件规模，再决定用 range 读取哪一段。仅做流式扫描，不受 readFile 的 300KB 读取阈值限制。",
+        name: "inspect_file",
+        description: "勘察文件的结构概况：总行数、总字符数、最长行的列数及其行索引、平均列数、行尾类型（LF/CRLF）。可选返回每行的列数映射。适用于在 read 之前先了解文件规模，再决定用 range 读取哪一段。仅做流式扫描，不受 read 的 300KB 读取阈值限制。",
         parameters: {
             type: "object",
             properties: {
@@ -63,7 +63,7 @@ export class InspectFileTool extends SdkCallbackTool {
                     colCountMapOmitted: true,
                     warning: `行长度明细过大：概况与 colCountMap 合计 ${payload.length} 字符，` +
                         `超过上限 ${limit} 字符，未落盘返回。文件规模超出可处理范围，` +
-                        `建议改用 findText 定位后再按 range 分段读取。`,
+                        `建议改用 find_text 定位后再按 range 分段读取。`,
                 });
             }
             return payload;

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

@@ -36,7 +36,7 @@ export class LsTool extends SdkCallbackTool {
                     return JSON.stringify({
                         outputTooLarge: true,
                         warning: `输出过大：目录条目共 ${entries.length} 项、${json.length} 字符，超过上限 ${limit} 字符。` +
-                            `完整列表已落盘（result.json），可用 readFile 分批读取；` +
+                            `完整列表已落盘（result.json），可用 read 分批读取；` +
                             `也可改用 glob 按模式筛选。`,
                         files: ctx.files,
                         chars: json.length,

package/dist/scope/plugins/builtin/{ReadFileTool.d.ts → ReadTool.d.ts}

@@ -1,7 +1,7 @@
 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 {
+export declare class ReadTool extends SdkCallbackTool {
     function: AgentNS.FunctionDefine;
     constructor(env: ToolEnv);
     call(input: {

package/dist/scope/plugins/builtin/{ReadFileTool.js → ReadTool.js}

@@ -1,9 +1,9 @@
 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 {
+export class ReadTool extends SdkCallbackTool {
     function = {
-        name: "readFile",
+        name: "read",
         description: "读取文件",
         parameters: {
             type: "object",
@@ -41,7 +41,7 @@ export class ReadFileTool extends SdkCallbackTool {
             // 输出保护：本次返回内容超过上限时只警告、不落盘，并提示用 range 分批读取
             const limit = this.env.config.maxToolOutput ?? DEFAULT_MAX_TOOL_OUTPUT;
             return await guardOutput({
-                tool: "readFile",
+                tool: "read",
                 content: output,
                 isOverLimit: (text) => text.length > limit,
                 buildWarning: () => `读取内容过大：本次输出 ${output.length} 字符，超过上限 ${limit} 字符，未落盘。` +

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

@@ -1,7 +1,7 @@
 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 {
+export declare class SpawnTool extends SdkCallbackTool {
     function: AgentNS.FunctionDefine;
     constructor(env: ToolEnv);
     call(input: {

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

@@ -1,8 +1,8 @@
 import { spawn } from "child_process";
 import { SdkCallbackTool } from "./SdkCallbackTool.js";
-export class ExecAsyncTool extends SdkCallbackTool {
+export class SpawnTool extends SdkCallbackTool {
     function = {
-        name: "exec_async",
+        name: "spawn",
         description: "异步执行命令，启动程序后立即返回，不等待执行结果。适用于启动长期运行的进程（如服务器、监听程序、GUI应用等）或不需要等待结果的命令。注意：该工具本身不捕获命令的输出；若需获取/留存输出，可在命令中使用 shell 重定向写入文件（如 `> /path/file`，支持 `>>` 追加、`|` 管道）。命令经 shell 解析执行。",
         parameters: {
             type: "object",

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

@@ -33,7 +33,7 @@ export class ViewImageTool extends SdkCallbackTool {
         return model?.vision === true;
     }
     function = {
-        name: "viewImage",
+        name: "view_image",
         description: "查看一张图片并分析其内容。传入本地图片路径或 http(s) 图片 URL。本地图片会自动上传（Files API）后引用，网络图片直接引用。不支持本地 URL（如 file:// 协议、指向本机 localhost/127.0.0.1 的 http(s) 地址），本地图片请使用文件路径。适合识别图片文字、描述图片内容、分析图表等。",
         parameters: {
             type: "object",
@@ -54,7 +54,7 @@ export class ViewImageTool extends SdkCallbackTool {
         const signal = ctx?.signal;
         const target = input?.path_or_url;
         if (!target || !target.trim()) {
-            return "viewImage 需要提供 path_or_url 参数（本地图片路径或 http(s) URL）。";
+            return "view_image 需要提供 path_or_url 参数（本地图片路径或 http(s) URL）。";
         }
         const value = target.trim();
         // 拒绝服务商无法访问的"本地 URL"：file:// 等本地协议，或指向本机回环地址（localhost/127.0.0.1/[::1]/0.0.0.0）的 http(s) 地址