@ai-zen/agents-sdk 1.0.0-alpha.2 → 1.0.0-alpha.5

package/CHANGELOG.md

@@ -1,5 +1,52 @@
 # Changelog
 
+## [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
+
+- **`generateImage` `model` parameter description no longer points at a host-CLI command** — the description used to read "配置中的图片模型可通过 'aiz config show' 查看" (the configured image models can be viewed via `aiz config show`). Since tool descriptions ship inside every request's `tools` payload, that hint propagated into **every layer** of the agent stack: the model would `exec("aiz config show")`, but the CLI resolves a bare `aiz config show` invocation as stdio mode with the instruction `config show` — i.e. a **brand-new agent** — whose own `generateImage` description repeats the very same hint, producing a self-referential recursion that keeps spawning nested agents. The parameter now reads "若指定的模型不存在，本工具会返回当前可用的模型列表" (if the specified model does not exist, this tool returns the list of currently available models), which matches the actual `!imageModel` branch in `call()` and stops the model from shelling out to the host CLI.
+
+### 📄 Docs
+
+- Current-version references in `docs/zh` and `docs/en` updated to `1.0.0-alpha.3`.
+
 ## [1.0.0-alpha.2] - 2026-10-03
 
 ### 🚀 New Features

package/README.md

@@ -97,9 +97,9 @@ 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 |
 | `mkdir` | Create a directory |
@@ -107,11 +107,11 @@ All built-in tools are classes (extending `SdkCallbackTool`), instantiated by th
 | `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,9 +96,9 @@ 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` | 异步执行命令，启动后立即返回，不等待结果 |
 | `mkdir` | 创建目录 |
@@ -106,11 +106,11 @@ await scope.dispose(); // 断开 MCP、释放插件资源
 | `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/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

@@ -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

@@ -10,7 +10,7 @@ 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",
@@ -94,7 +94,7 @@ export class FindTextTool extends SdkCallbackTool {
                     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.js

@@ -3,7 +3,7 @@ import { SdkCallbackTool } from "./SdkCallbackTool.js";
 import { DEFAULT_MAX_TOOL_OUTPUT, guardOutput } from "./outputGuard.js";
 export class ReadFileTool 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/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.js

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

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.2",
+  "version": "1.0.0-alpha.5",
   "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",