@ai-zen/agents-sdk 1.0.0-alpha.3 → 1.0.0-alpha.6

package/CHANGELOG.md

@@ -1,5 +1,49 @@
 # Changelog
 
+## [1.0.0-alpha.6] - 2026-10-13
+
+### 💥 Breaking Changes
+
+- **`exec_async` renamed to `spawn`** — the tool wraps `child_process.spawn` and returns `{ success, pid, message }`, so the new name matches both the implementation and the "start a process, get its pid" contract. It also pairs cleanly with `exec`: `exec` runs and **waits** (captures output, has a `timeout`), `spawn` starts and **returns immediately**. Permission lists, skill `allowed-tools` and any prompt naming `exec_async` must switch to `spawn`. The behaviour is otherwise unchanged — still shell-parsed, still does **not** capture output (redirect to a file if you need it).
+- **Built-in tool classes renamed to match their new tool names** — `ReadFileTool` → `ReadTool`, `WriteFileTool` → `WriteTool`, `ExecAsyncTool` → `SpawnTool`, with the source files renamed to match. The classes re-exported from `@ai-zen/agents-sdk` change accordingly, so consumers importing them by name must update.
+
+## [1.0.0-alpha.5] - 2026-10-13
+
+### 💥 Breaking Changes
+
+- **All built-in tool names unified on `snake_case`** — the multi-word tools that used camelCase were renamed. A tool name is the API contract the model sees and is matched **verbatim** by the permission system, so any `permissions.allow` / `deny` list, skill `allowed-tools` entry or prompt that names a tool must be updated:
+
+  | old | new |
+  |---|---|
+  | `readFile` | `read` |
+  | `writeFile` | `write` |
+  | `inspectFile` | `inspect_file` |
+  | `findText` | `find_text` |
+  | `batchEdit` | `batch_edit` |
+  | `downloadFile` | `download_file` |
+  | `generateImage` | `generate_image` |
+  | `viewImage` | `view_image` |
+
+  Single-word tools (`cwd`, `edit`, `glob`, `ls`, `mkdir`, `rm`, `rename`, `copy`, `exec`, `exist`, `sleep`), the already-`snake_case` `exec_async`, the MCP / skill wrapper tools and core's `indexed_search` are unchanged. Tool descriptions and docs were updated in the same pass.
+
+### 🔧 Changed
+
+- **Dependency `@ai-zen/agents-core` bumped to `^4.3.2`** (carries the `indexedSearch` → `indexed_search` rename).
+
+### 📄 Docs
+
+- Current-version references in `docs/zh` and `docs/en` updated to `1.0.0-alpha.5`.
+
+## [1.0.0-alpha.4] - 2026-10-13
+
+### 🔧 Changed
+
+- **Dependency `@ai-zen/agents-core` bumped to `^4.3.1`** (declared as `workspace:^`, expanded to `^4.3.1` at publish time). Pulls in core 4.3.1's fix for interrupted parallel tool rounds — the assistant message carrying `tool_calls` and its results now stay all-in or all-out, so an interrupted parallel tool call no longer leaves orphan `tool` results that the server rejects. `AgentContext` gains `abortedToolRoundStrategy` (default `"fill"`) and `abortedToolRoundReason`; set `agent.abortedToolRoundStrategy = "drop"` to drop the whole round instead
+
+### 📄 Docs
+
+- Current-version references in `docs/zh` and `docs/en` updated to `1.0.0-alpha.4`.
+
 ## [1.0.0-alpha.3] - 2026-10-03
 
 ### 🔧 Fixed

package/README.md

@@ -97,21 +97,21 @@ All built-in tools are classes (extending `SdkCallbackTool`), instantiated by th
 | Tool | Description |
 |------|-------------|
 | `cwd` | Get the current working directory |
-| `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 |
+| `read` | Read a file (optional `range` for line/column slicing; oversized output warns and suggests batched reads) |
+| `inspect_file` | Inspect a file's structural overview (line count, column distribution, etc.); streamed scan, not limited by the 300KB read threshold |
+| `write` | Write a file |
 | `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 |
+| `spawn` | 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 (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 (oversized output dumped to `result.json`) |
-| `downloadFile` | Download a file from a URL and save it locally |
+| `find_text` | Search for text or regex in files (oversized output dumped to `result.json`) |
+| `download_file` | 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 (only unmatched items are echoed back; successful ones are counted) |
+| `batch_edit` | 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 |
 
@@ -119,10 +119,10 @@ Conditionally injected based on the active model / config:
 
 | Tool | Injection Condition | Description |
 |------|---------------------|-------------|
-| `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 |
+| `generate_image` | Only when `defaultImageModel` is configured | Generate an image from a text description |
+| `view_image` | 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-v1.md` §12](docs/sdk-design-v1.md).
+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), `find_text` / `glob` / `ls` dump `result.json` (returning a head preview), and `read` 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-v1.md` §12](docs/sdk-design-v1.md).
 
 ## Built-in Plugins
 

package/README.zh.md

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

package/dist/index.d.ts

@@ -39,7 +39,7 @@ export { ContextGuardPlugin } from "./agent-plugins/ContextGuardPlugin.js";
 export type { ContextGuardOptions } from "./agent-plugins/ContextGuardPlugin.js";
 export { UnknownToolHintPlugin } from "./agent-plugins/UnknownToolHintPlugin.js";
 export { BUILTIN_TOOL_CLASSES } from "./scope/plugins/builtin/index.js";
-export { CwdTool, ReadFileTool, InspectFileTool, WriteFileTool, ExecTool, MkdirTool, RmTool, GlobTool, LsTool, ExistTool, FindTextTool, DownloadFileTool, RenameTool, CopyTool, BatchEditTool, EditTool, ExecAsyncTool, SleepTool, } from "./scope/plugins/builtin/index.js";
+export { CwdTool, ReadTool, InspectFileTool, WriteTool, ExecTool, MkdirTool, RmTool, GlobTool, LsTool, ExistTool, FindTextTool, DownloadFileTool, RenameTool, CopyTool, BatchEditTool, EditTool, SpawnTool, SleepTool, } from "./scope/plugins/builtin/index.js";
 export { GenerateImageTool } from "./scope/plugins/builtin/GenerateImageTool.js";
 export { ViewImageTool } from "./scope/plugins/builtin/ViewImageTool.js";
 export { createLoadSkillTool, createCallSkillSubAgentTool } from "./scope/plugins/skills/skillTools.js";

package/dist/index.js

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

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: {
@@ -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) 地址

package/dist/scope/plugins/builtin/{WriteFileTool.d.ts → WriteTool.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 WriteFileTool extends SdkCallbackTool {
+export declare class WriteTool extends SdkCallbackTool {
     function: AgentNS.FunctionDefine;
     constructor(env: ToolEnv);
     call(input: {

package/dist/scope/plugins/builtin/{WriteFileTool.js → WriteTool.js}

@@ -1,9 +1,9 @@
 import * as fsp from "fs/promises";
 import * as path from "path";
 import { SdkCallbackTool } from "./SdkCallbackTool.js";
-export class WriteFileTool extends SdkCallbackTool {
+export class WriteTool extends SdkCallbackTool {
     function = {
-        name: "writeFile",
+        name: "write",
         description: "写入文件",
         parameters: {
             type: "object",

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

@@ -1,9 +1,9 @@
 import type { SdkCallbackTool } from "./SdkCallbackTool.js";
 import type { ToolEnv } from "../../../types/index.js";
 import { CwdTool } from "./CwdTool.js";
-import { ReadFileTool } from "./ReadFileTool.js";
+import { ReadTool } from "./ReadTool.js";
 import { InspectFileTool } from "./InspectFileTool.js";
-import { WriteFileTool } from "./WriteFileTool.js";
+import { WriteTool } from "./WriteTool.js";
 import { ExecTool } from "./ExecTool.js";
 import { MkdirTool } from "./MkdirTool.js";
 import { RmTool } from "./RmTool.js";
@@ -16,7 +16,7 @@ import { RenameTool } from "./RenameTool.js";
 import { CopyTool } from "./CopyTool.js";
 import { BatchEditTool } from "./BatchEditTool.js";
 import { EditTool } from "./EditTool.js";
-import { ExecAsyncTool } from "./ExecAsyncTool.js";
+import { SpawnTool } from "./SpawnTool.js";
 import { SleepTool } from "./SleepTool.js";
 import { ViewImageTool } from "./ViewImageTool.js";
 import { GenerateImageTool } from "./GenerateImageTool.js";
@@ -29,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, InspectFileTool, WriteFileTool, ExecTool, MkdirTool, RmTool, GlobTool, LsTool, ExistTool, FindTextTool, DownloadFileTool, RenameTool, CopyTool, BatchEditTool, EditTool, ExecAsyncTool, SleepTool, ViewImageTool, GenerateImageTool, };
+export { CwdTool, ReadTool, InspectFileTool, WriteTool, ExecTool, MkdirTool, RmTool, GlobTool, LsTool, ExistTool, FindTextTool, DownloadFileTool, RenameTool, CopyTool, BatchEditTool, EditTool, SpawnTool, SleepTool, ViewImageTool, GenerateImageTool, };

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

@@ -1,7 +1,7 @@
 import { CwdTool } from "./CwdTool.js";
-import { ReadFileTool } from "./ReadFileTool.js";
+import { ReadTool } from "./ReadTool.js";
 import { InspectFileTool } from "./InspectFileTool.js";
-import { WriteFileTool } from "./WriteFileTool.js";
+import { WriteTool } from "./WriteTool.js";
 import { ExecTool } from "./ExecTool.js";
 import { MkdirTool } from "./MkdirTool.js";
 import { RmTool } from "./RmTool.js";
@@ -14,7 +14,7 @@ import { RenameTool } from "./RenameTool.js";
 import { CopyTool } from "./CopyTool.js";
 import { BatchEditTool } from "./BatchEditTool.js";
 import { EditTool } from "./EditTool.js";
-import { ExecAsyncTool } from "./ExecAsyncTool.js";
+import { SpawnTool } from "./SpawnTool.js";
 import { SleepTool } from "./SleepTool.js";
 import { ViewImageTool } from "./ViewImageTool.js";
 import { GenerateImageTool } from "./GenerateImageTool.js";
@@ -28,9 +28,9 @@ import { GenerateImageTool } from "./GenerateImageTool.js";
  */
 export const BUILTIN_TOOL_CLASSES = [
     CwdTool,
-    ReadFileTool,
+    ReadTool,
     InspectFileTool,
-    WriteFileTool,
+    WriteTool,
     ExecTool,
     MkdirTool,
     RmTool,
@@ -43,9 +43,9 @@ export const BUILTIN_TOOL_CLASSES = [
     CopyTool,
     BatchEditTool,
     EditTool,
-    ExecAsyncTool,
+    SpawnTool,
     SleepTool,
     ViewImageTool,
     GenerateImageTool,
 ];
-export { CwdTool, ReadFileTool, InspectFileTool, WriteFileTool, ExecTool, MkdirTool, RmTool, GlobTool, LsTool, ExistTool, FindTextTool, DownloadFileTool, RenameTool, CopyTool, BatchEditTool, EditTool, ExecAsyncTool, SleepTool, ViewImageTool, GenerateImageTool, };
+export { CwdTool, ReadTool, InspectFileTool, WriteTool, ExecTool, MkdirTool, RmTool, GlobTool, LsTool, ExistTool, FindTextTool, DownloadFileTool, RenameTool, CopyTool, BatchEditTool, EditTool, SpawnTool, SleepTool, ViewImageTool, GenerateImageTool, };

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

@@ -28,7 +28,7 @@ export interface OutputGuardOptions<T> {
     /** 超限判定：上限由工具自行从 config 读取，骨架不传参 */
     isOverLimit: (content: T) => boolean;
     /**
-     * 落盘内容组织（可选）。缺省表示"只警告、不落盘"（如 readFile）。
+     * 落盘内容组织（可选）。缺省表示"只警告、不落盘"（如 read）。
      * 返回的文件按顺序写入本次调用专属的目录。
      */
     dump?: (dir: string, content: T) => GuardDumpFile[] | Promise<GuardDumpFile[]>;
@@ -61,7 +61,7 @@ export interface HeadPreview {
 /**
  * 生成头部预览：最多 size 字符。
  *
- * 适用于结果按出现顺序排列、尾部参考价值低的工具（如 findText）。
+ * 适用于结果按出现顺序排列、尾部参考价值低的工具（如 find_text）。
  */
 export declare function headPreview(text: string, size?: number): HeadPreview;
 /** 头尾预览 */

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

@@ -42,7 +42,7 @@ export async function guardOutput(options) {
 /**
  * 生成头部预览：最多 size 字符。
  *
- * 适用于结果按出现顺序排列、尾部参考价值低的工具（如 findText）。
+ * 适用于结果按出现顺序排列、尾部参考价值低的工具（如 find_text）。
  */
 export function headPreview(text, size = 1000) {
     if (text.length <= size)

package/dist/types/index.d.ts

@@ -36,7 +36,7 @@ export interface Model {
     /** 旧版字符数阈值（兼容迁移） */
     maxContextChars?: number;
     defaultParams?: Record<string, unknown>;
-    /** 是否支持图片输入（视觉模型）。看图工具（viewImage）仅对视觉模型启用；generateImage 是否返回图片内容块也据此判断 */
+    /** 是否支持图片输入（视觉模型）。看图工具（view_image）仅对视觉模型启用；generate_image 是否返回图片内容块也据此判断 */
     vision?: boolean;
     description?: string;
     version?: number;
@@ -104,7 +104,7 @@ export interface AppConfig {
      *
      * 工具本次输出超过该值时，由工具自身的保护策略处置（落盘或仅警告），
      * 避免超长输出撑爆上下文。仅作用于"输出"，与工具的读取阈值无关
-     * （如 readFile/findText 对 300KB 文件的读取上限）。
+     * （如 read/find_text 对 300KB 文件的读取上限）。
      */
     maxToolOutput?: number;
 }
@@ -112,7 +112,7 @@ export interface AppConfig {
  * 工具环境 — Scope 的能力插件在实例化内置工具时注入的环境信息。
  *
  * cwd 是相对路径解析的基准（每个 Scope 对应一个工作目录）；
- * config 供需要模型/端点配置的工具（如 generateImage）使用。
+ * config 供需要模型/端点配置的工具（如 generate_image）使用。
  */
 export interface ToolEnv {
     /** 当前工作目录 */

package/package.json

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