@ai-zen/agents-sdk 1.0.0-alpha.21 → 1.0.0-alpha.23

package/dist/runtime/HandoffService.js

@@ -16,7 +16,7 @@ import { HandoffGuardPlugin } from "./HandoffGuardPlugin.js";
  */
 export class HandoffAbortedError extends Error {
     constructor() {
-        super("交接已取消");
+        super("Handoff cancelled");
         this.name = "HandoffAbortedError";
     }
 }
@@ -115,14 +115,14 @@ export class HandoffService {
         const { skillContent, handoffPath, toolsAvailable } = params;
         const tail = toolsAvailable
             ? [
-                "请立即开始撰写，并用 write 工具把完整文档写入上面给出的路径（路径原样使用，不要改名、不要换目录）。",
-                "写完后用 read 回读一次确认完整，然后只回一句不超过 40 字的确认，**不要复述文档内容**。",
+                "Start writing now: use the write tool to put the complete document at the path given above (use the path exactly as given, do not rename it and do not move it to another directory).",
+                "After writing, read it back once with the read tool to confirm it is complete, then reply with a single confirmation of no more than 40 words, **do not restate the document content**.",
             ]
             : [
-                "请直接输出完整文档正文：不要任何解释、不要用代码块包裹，调用方会自行落盘。",
+                "Output the complete document body directly: no explanations, do not wrap it in a code block, the caller will persist it to disk itself.",
             ];
         return [
-            "你现在要为本轮对话编写一份任务交接文档。以下是必须遵守的交接规范。",
+            "You are now to write a task handoff document for this conversation. The following handoff rules are mandatory.",
             "",
             "---",
             "",
@@ -130,11 +130,11 @@ export class HandoffService {
             "",
             "---",
             "",
-            "## 本次交接参数",
-            `- 交接文档绝对路径：${handoffPath}`,
-            `- 工具能力：${toolsAvailable
-                ? "可用（read / exec 等，请据此核实真实状态）"
-                : "不可用（你无法核实磁盘，状态类信息一律写「⚠️ 未核实」，禁止推测）"}`,
+            "## Handoff parameters",
+            `- Handoff document absolute path: ${handoffPath}`,
+            `- Tools available: ${toolsAvailable
+                ? "yes (read / exec, etc., use them to verify the actual state)"
+                : "no (you cannot inspect the disk, so for any state information always write '⚠️ Unverified', never speculate)"}`,
             "",
             ...tail,
         ].join("\n");
@@ -147,10 +147,10 @@ export class HandoffService {
      */
     static createPostMessages(handoffPath) {
         const content = [
-            "上一轮对话已交接，交接文档保存在：",
+            "The previous conversation has been handed off, the handoff document is saved at:",
             handoffPath,
             "",
-            "请先用 read 工具读取该文件，理解上下文与未完成事项后，再继续协助用户完成任务。",
+            "Read that file first with the read tool, and once you understand the context and the unfinished work, continue helping the user with the task.",
         ].join("\n");
         return [Message.User(content)];
     }
@@ -213,7 +213,7 @@ export class HandoffService {
     /** 串行化 + 防重入：交接与迁移共用同一把锁 */
     async withBusy(fn) {
         if (this._busy)
-            throw new Error("交接流程已在进行中，请等待当前交接完成");
+            throw new Error("A handoff is already in progress, wait for it to finish");
         this._busy = true;
         try {
             return await fn();
@@ -298,13 +298,13 @@ export class HandoffService {
         let handoffDoc;
         let historyText = "";
         if (mode === "self" && !this.supportsSelfHandoff(agent)) {
-            this.logger.warn("[handoff] agent 不具备 write 工具或 send 能力，降级为独立摘要模式");
+            this.logger.warn("[handoff] agent has no write tool or send capability, falling back to standalone summary mode");
             mode = "summary";
         }
         if (mode === "self") {
             const ok = await this.runSelfHandoff(agent, handoffPath, signal);
             if (!ok) {
-                this.logger.warn("[handoff] 自交接失败，降级为独立摘要模式");
+                this.logger.warn("[handoff] self handoff failed, falling back to standalone summary mode");
                 mode = "summary";
             }
         }
@@ -375,10 +375,10 @@ export class HandoffService {
             this.throwIfAborted(signal);
             if (await this.isHandoffFileReady(handoffPath))
                 return true;
-            this.logger.warn(`[handoff] 交接文档缺失或过小，重试一次：${handoffPath}`);
+            this.logger.warn(`[handoff] handoff document missing or too small, retrying once: ${handoffPath}`);
             await agent.send([
-                `交接文档不存在或内容过少，无法交付：${handoffPath}`,
-                "请立即用 write 工具把**完整**交接文档写入该路径（路径原样使用），不要做其他任何事。",
+                `The handoff document does not exist or is too small to deliver: ${handoffPath}`,
+                "Use the write tool right now to write the **complete** handoff document to that path (use the path exactly as given) and do nothing else.",
             ].join("\n"));
             this.throwIfAborted(signal);
             return await this.isHandoffFileReady(handoffPath);
@@ -388,7 +388,7 @@ export class HandoffService {
                 await this.discardPartialFile(handoffPath, existedBefore);
                 throw new HandoffAbortedError();
             }
-            this.logger.error(`[handoff] 自交接回合失败：${err?.message ?? err}`);
+            this.logger.error(`[handoff] self handoff round failed: ${err?.message ?? err}`);
             return false;
         }
         finally {
@@ -421,7 +421,7 @@ export class HandoffService {
         }, signal ? { signal } : undefined);
         const handoffDoc = response.choices[0]?.message?.content;
         if (!handoffDoc || !handoffDoc.trim()) {
-            throw new Error("未能生成任务交接文档");
+            throw new Error("Failed to generate the handoff document");
         }
         return handoffDoc;
     }
@@ -446,7 +446,7 @@ export class HandoffService {
             if (skill?.content?.trim())
                 return skill.content;
         }
-        this.logger.warn(`[handoff] 未找到 ${HANDOFF_SKILL_ID} Skill，使用内置兜底模板（路径：${this.skillDirs.join(", ") || "未配置"}）`);
+        this.logger.warn(`[handoff] ${HANDOFF_SKILL_ID} skill not found, using the built-in fallback template (paths: ${this.skillDirs.join(", ") || "none configured"})`);
         return FALLBACK_HANDOFF_TEMPLATE;
     }
     /** 守卫按 agent 注册一次（`Agent.use()` 无移除 API，故复用实例 + 开关） */
@@ -466,7 +466,7 @@ export class HandoffService {
             await hook(ctx);
         }
         catch (err) {
-            this.logger.error(`[handoff] 钩子执行失败: ${err?.message ?? err}`);
+            this.logger.error(`[handoff] hook execution failed: ${err?.message ?? err}`);
         }
     }
 }

package/dist/runtime/createAgent.d.ts

@@ -2,7 +2,10 @@ import { SdkAgent } from "./SdkAgent.js";
 import type { Scope } from "../scope/Scope.js";
 import type { AbortedMessageStrategy, AbortedToolRoundStrategy } from "@ai-zen/agents-core";
 /**
- * `createAgent` 的可选行为开关（不传则全部沿用 core 默认值）。
+ * `createAgent` 的可选行为开关。
+ *
+ * 不传时先取 `scope.config`（`config.json`）里的同名配置，再往下才是 core 默认值：
+ * 中断策略属于**产品配置**，调用方不该自己读配置再转一道参数。
  */
 export interface CreateAgentOptions {
     /** 工具轮次被中断（或结果不完整）时的归一策略（core 默认 `fill`） */
@@ -10,8 +13,9 @@ export interface CreateAgentOptions {
     /** `fill` 策略下，未完成工具结果的填充原因 */
     abortedToolRoundReason?: string;
     /**
-     * 被中断的 assistant 消息（已输出的内容 / 思考）如何处置（core 默认 `drop`）。
-     * 传 `keep` 可让模型在下一轮接着半截往下说，而不是忘掉自己说过什么。
+     * 被中断的 assistant 消息（已输出的内容 / 思考）如何处置（未传时取 `scope.config`，
+     * 再缺则用 core 默认 `drop`）。
+     * `keep` 可让模型在下一轮接着半截往下说，而不是忘掉自己说过什么。
      */
     abortedMessageStrategy?: AbortedMessageStrategy;
 }

package/dist/runtime/createAgent.js

@@ -14,10 +14,10 @@ import { createModel } from "./createModel.js";
 export async function createAgent(scope, agentId, options = {}) {
     const definition = await new AgentRepository(scope.agentsDir).read(agentId);
     if (!definition)
-        throw new Error(`Agent "${agentId}" 不存在`);
+        throw new Error(`Agent "${agentId}" not found`);
     const modelId = definition.modelId;
     if (!modelId) {
-        throw new Error(`Agent "${agentId}" 未绑定模型（缺少 modelId）。请在配置里给它指定一个模型。`);
+        throw new Error(`Agent "${agentId}" has no model bound (modelId is missing). Assign a model to it in the config`);
     }
     const { client, model, modelConfig } = createModel(scope, modelId, definition.modelParams);
     const tools = scope.buildTools(definition, {
@@ -40,10 +40,12 @@ export async function createAgent(scope, agentId, options = {}) {
         // 快照后，运行时改动只作用于会话副本，模板保持纯净。
         messages: [...(definition.messages ?? [])],
         tools,
-        // 中断相关策略：不传则由 core 取默认值（工具轮次 fill / 消息保留 drop）
-        abortedToolRoundStrategy: options.abortedToolRoundStrategy,
+        // 中断相关策略：**显式参数 > `scope.config` > core 默认值**。
+        // 中间那一层是「配置即事实」：策略写在 `config.json` 里，各端（CLI / Desktop）
+        // 不必自己读配置再转成参数，子 Agent 创建时也能自然继承同一份策略。
+        abortedToolRoundStrategy: options.abortedToolRoundStrategy ?? scope.config?.abortedToolRoundStrategy,
         abortedToolRoundReason: options.abortedToolRoundReason,
-        abortedMessageStrategy: options.abortedMessageStrategy,
+        abortedMessageStrategy: options.abortedMessageStrategy ?? scope.config?.abortedMessageStrategy,
     });
     return agent;
 }

package/dist/runtime/createModel.js

@@ -26,12 +26,12 @@ export function createModel(scope, modelId, overrides) {
     const config = scope.config;
     const modelConfig = config.models.find((m) => m.id === modelId);
     if (!modelConfig)
-        throw new Error(`模型 "${modelId}" 不存在`);
+        throw new Error(`Model "${modelId}" not found`);
     const endpointConfig = config.endpoints.find((e) => e.id === modelConfig.endpointId);
     if (!endpointConfig)
-        throw new Error(`端点 "${modelConfig.endpointId}" 未配置`);
+        throw new Error(`Endpoint "${modelConfig.endpointId}" is not configured`);
     if (!endpointConfig.apiKey) {
-        throw new Error(`端点 "${endpointConfig.name}" 的 API Key 未设置`);
+        throw new Error(`API key for endpoint "${endpointConfig.name}" is not set`);
     }
     const client = new OpenAI({
         apiKey: endpointConfig.apiKey,

package/dist/scope/PermissionEvaluator.js

@@ -44,7 +44,7 @@ export class PermissionEvaluator {
     }
     validatePolicy(policy) {
         if ("allow" in policy && "deny" in policy) {
-            throw new Error("权限维度不能同时配置 allow 和 deny");
+            throw new Error("A permission dimension cannot set both allow and deny");
         }
     }
 }

package/dist/scope/Scope.js

@@ -57,7 +57,7 @@ export class Scope {
      */
     use(...plugins) {
         if (this._initialized) {
-            throw new Error("Scope.use() 必须在 init() 之前调用");
+            throw new Error("Scope.use() must be called before init()");
         }
         for (const plugin of plugins) {
             this._plugins.push(plugin);

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

@@ -4,33 +4,33 @@ export class BatchEditTool extends SdkCallbackTool {
     function = {
         name: "batch_edit",
         description: [
-            "批量编辑文件文本，可以优先使用这个工具对文件进行编辑。",
-            "对同一个文件的多处修改应在一次调用中全部提交（replacements 数组），而不是并行多次调用 edit——并行编辑同一文件会互相覆盖。",
+            "Edit text in a file in batches. Prefer this tool when making edits to a file.",
+            "Submit all changes to the same file in a single call (the replacements array) instead of calling edit in parallel multiple times — parallel edits to the same file overwrite each other.",
         ].join("\n"),
         parameters: {
             type: "object",
             properties: {
                 path: {
                     type: "string",
-                    description: "文件路径",
+                    description: "File path",
                 },
                 replacements: {
                     type: "array",
-                    description: "要替换的文本数组",
+                    description: "Array of replacements",
                     items: {
                         type: "object",
                         properties: {
                             oldText: {
                                 type: "string",
-                                description: "要替换的文本",
+                                description: "Text to replace",
                             },
                             newText: {
                                 type: "string",
-                                description: "替换后的文本",
+                                description: "Replacement text",
                             },
                             isReplaceAll: {
                                 type: "boolean",
-                                description: "是否替换所有匹配的文本（默认仅替换首次匹配）。使用此功能前应确保你提供的 oldText 足够精确，避免误替换",
+                                description: "Whether to replace all matches (by default only the first match is replaced). Make sure the oldText you provide is precise enough to avoid unintended replacements",
                                 default: false,
                             },
                         },
@@ -60,7 +60,7 @@ export class BatchEditTool extends SdkCallbackTool {
                     failed.push({
                         oldText: replacement.oldText,
                         newText: replacement.newText,
-                        reason: "文件中未精确匹配到要替换的文本",
+                        reason: "No exact match found for the text to replace",
                     });
                     continue;
                 }

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

@@ -3,21 +3,21 @@ import { SdkCallbackTool } from "./SdkCallbackTool.js";
 export class CopyTool extends SdkCallbackTool {
     function = {
         name: "copy",
-        description: "复制文件或目录（相当于 cp 命令）",
+        description: "Copy a file or directory (equivalent to the cp command)",
         parameters: {
             type: "object",
             properties: {
                 src: {
                     type: "string",
-                    description: "源路径",
+                    description: "Source path",
                 },
                 dest: {
                     type: "string",
-                    description: "目标路径",
+                    description: "Destination path",
                 },
                 recursive: {
                     type: "boolean",
-                    description: "是否递归复制目录，复制目录时需设为 true",
+                    description: "Whether to copy directories recursively; must be true when copying a directory",
                 },
             },
             required: ["src", "dest"],

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

@@ -2,7 +2,7 @@ import { SdkCallbackTool } from "./SdkCallbackTool.js";
 export class CwdTool extends SdkCallbackTool {
     function = {
         name: "cwd",
-        description: "获取当前工作目录 cwd",
+        description: "Get the current working directory (cwd)",
         parameters: {
             type: "object",
             properties: {},

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

@@ -4,17 +4,17 @@ import { SdkCallbackTool } from "./SdkCallbackTool.js";
 export class DownloadFileTool extends SdkCallbackTool {
     function = {
         name: "download_file",
-        description: "从 URL 下载文件（图片、PDF 等二进制文件）并保存到本地磁盘。自动从 URL 推断文件名，也可指定保存路径。",
+        description: "Download a file from a URL (images, PDFs and other binary files) and save it to the local disk. The file name is inferred from the URL, or you can specify the save path.",
         parameters: {
             type: "object",
             properties: {
                 url: {
                     type: "string",
-                    description: "文件下载链接",
+                    description: "URL to download the file from",
                 },
                 outputPath: {
                     type: "string",
-                    description: "保存路径（可选）。可以是目录或完整文件路径。不指定则下载到当前工作目录，自动从 URL 推断文件名。",
+                    description: "Save path (optional). May be a directory or a full file path. If omitted, the file is saved to the current working directory with the file name inferred from the URL.",
                 },
             },
             required: ["url"],
@@ -30,7 +30,7 @@ export class DownloadFileTool extends SdkCallbackTool {
         try {
             const url = input.url;
             if (!url)
-                throw new Error("url 不能为空");
+                throw new Error("url must not be empty");
             if (input.outputPath) {
                 savePath = this.resolve(input.outputPath);
                 const stat = await fsp.stat(savePath).catch(() => null);
@@ -48,7 +48,7 @@ export class DownloadFileTool extends SdkCallbackTool {
             await fsp.mkdir(path.dirname(savePath), { recursive: true });
             const response = await fetch(url, { signal });
             if (!response.ok) {
-                throw new Error(`下载失败: HTTP ${response.status} ${response.statusText}`);
+                throw new Error(`Download failed: HTTP ${response.status} ${response.statusText}`);
             }
             const contentType = response.headers.get("content-type") || "";
             const arrayBuffer = await response.arrayBuffer();
@@ -61,7 +61,7 @@ export class DownloadFileTool extends SdkCallbackTool {
                 filePath: path.resolve(savePath),
                 fileSize: `${fileSizeKB} KB`,
                 contentType,
-                note: "文件已保存到本地",
+                note: "File saved to local disk",
             });
         }
         catch (error) {
@@ -71,12 +71,12 @@ export class DownloadFileTool extends SdkCallbackTool {
                 return JSON.stringify({
                     success: false,
                     aborted: true,
-                    error: "下载被中断（aborted）",
+                    error: "Download aborted",
                 });
             }
             return JSON.stringify({
                 success: false,
-                error: error?.message || "下载失败",
+                error: error?.message || "Download failed",
             });
         }
     }

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

@@ -16,29 +16,29 @@ export class EditTool extends SdkCallbackTool {
     function = {
         name: "edit",
         description: [
-            "编辑文件中的文本，支持精确替换或替换所有匹配项。",
+            "Edit text in a file, supporting exact replacement or replacing all matches.",
             "",
-            "并发限制（重要）：同一个文件禁止并行编辑。不要在同一轮回复中对同一路径发起多个 edit 调用——这些调用会各自读取旧内容再写回，后写者覆盖先写者，导致修改丢失或文件被写坏。",
-            "如需对同一个文件施加多处修改，请改用 batch_edit，在一次调用里提交全部替换。只有编辑不同文件时才可以并行调用 edit。",
+            "Concurrency limit (important): never edit the same file in parallel. Do not issue multiple edit calls for the same path within one reply — each call reads the old content and writes it back, so the later write overwrites the earlier one, losing changes or corrupting the file.",
+            "To apply multiple changes to one file, use batch_edit instead and submit all replacements in a single call. Only edit different files in parallel.",
         ].join("\n"),
         parameters: {
             type: "object",
             properties: {
                 path: {
                     type: "string",
-                    description: "文件路径",
+                    description: "File path",
                 },
                 oldText: {
                     type: "string",
-                    description: "要替换的文本",
+                    description: "Text to replace",
                 },
                 newText: {
                     type: "string",
-                    description: "替换后的文本",
+                    description: "Replacement text",
                 },
                 isReplaceAll: {
                     type: "boolean",
-                    description: "是否替换所有匹配的文本（默认 false，仅替换首次匹配）。使用此功能前应确保你提供的 oldText 足够精确，避免误替换",
+                    description: "Whether to replace all matches (default false, only the first match is replaced). Make sure the oldText you provide is precise enough to avoid unintended replacements",
                     default: false,
                 },
             },
@@ -59,7 +59,7 @@ export class EditTool extends SdkCallbackTool {
             const count = countOccurrences(content, oldText);
             if (count === 0) {
                 return JSON.stringify({
-                    result: "文件中未精确匹配到要替换的文本",
+                    result: "No exact match found for the text to replace",
                     matchCount: 0,
                 });
             }
@@ -69,7 +69,7 @@ export class EditTool extends SdkCallbackTool {
             await fsp.writeFile(filePath, newContent);
             if (!isReplaceAll && count > 1) {
                 return JSON.stringify({
-                    result: `警告：未开启替换所有（isReplaceAll=false），但文本 "${oldText}" 在文件中出现了 ${count} 次，仅替换了首次匹配。如果希望替换所有匹配，请将 isReplaceAll 设为 true`,
+                    result: `Warning: replace-all is off (isReplaceAll=false), but the text "${oldText}" occurs ${count} times in the file; only the first match was replaced. Set isReplaceAll to true to replace all matches`,
                     matchCount: count,
                     replacedCount: 1,
                 });

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

@@ -4,17 +4,17 @@ import { DEFAULT_MAX_TOOL_OUTPUT, guardOutput, headTailPreview } from "./outputG
 export class ExecTool extends SdkCallbackTool {
     function = {
         name: "exec",
-        description: "执行命令",
+        description: "Execute a shell command",
         parameters: {
             type: "object",
             properties: {
                 command: {
                     type: "string",
-                    description: "要执行的命令",
+                    description: "Command to execute",
                 },
                 timeout: {
                     type: "number",
-                    description: "超时时间（毫秒），必填。超时后会终止进程；超过该时长仍未完成即视为超时并终止。建议长时间运行的命令使用 spawn 异步执行。",
+                    description: "Timeout in milliseconds (required). The process is killed on timeout. For long-running commands, prefer spawn to run them asynchronously.",
                 },
             },
             required: ["command", "timeout"],
@@ -29,7 +29,7 @@ export class ExecTool extends SdkCallbackTool {
         const { timeout } = input;
         // 运行时双校验：timeout 必填且必须为正数
         if (typeof timeout !== "number" || !Number.isFinite(timeout) || timeout <= 0) {
-            throw new Error(`exec: 参数 timeout 为必填项，且必须是正数（毫秒），当前值: ${JSON.stringify(timeout)}`);
+            throw new Error(`exec: timeout is required and must be a positive number (milliseconds), got: ${JSON.stringify(timeout)}`);
         }
         const signal = ctx?.signal;
         const result = await new Promise((resolve) => {
@@ -37,7 +37,7 @@ export class ExecTool extends SdkCallbackTool {
             if (signal?.aborted) {
                 resolve({
                     stdout: "",
-                    stderr: "进程已中断（aborted）",
+                    stderr: "Process aborted",
                     exitCode: null,
                     killed: true,
                     terminated: "aborted",
@@ -72,7 +72,7 @@ export class ExecTool extends SdkCallbackTool {
                 // 即便 exec 回调因信号处理而未能及时触发，也立即返回中断结果，避免挂起
                 settle({
                     stdout: "",
-                    stderr: "进程已中断（aborted）",
+                    stderr: "Process aborted",
                     exitCode: null,
                     killed: true,
                     terminated: "aborted",
@@ -97,8 +97,8 @@ export class ExecTool extends SdkCallbackTool {
                 const stderr = headTailPreview(result.stderr);
                 return JSON.stringify({
                     outputTooLarge: true,
-                    warning: `输出过大：stdout + stderr 合计 ${result.stdout.length + result.stderr.length} 字符，` +
-                        `超过上限 ${limit} 字符。完整内容已分文件落盘（stdout.log / stderr.log），可用 read 分批读取。`,
+                    warning: `Output too large: stdout + stderr total ${result.stdout.length + result.stderr.length} characters, ` +
+                        `exceeds the limit of ${limit} characters. Full content was written to separate files (stdout.log / stderr.log); use read to fetch it in chunks`,
                     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/ExistTool.js

@@ -3,13 +3,13 @@ import { SdkCallbackTool } from "./SdkCallbackTool.js";
 export class ExistTool extends SdkCallbackTool {
     function = {
         name: "exist",
-        description: "检查文件或目录是否存在",
+        description: "Check whether a file or directory exists",
         parameters: {
             type: "object",
             properties: {
                 path: {
                     type: "string",
-                    description: "文件或目录路径",
+                    description: "File or directory path",
                 },
             },
             required: ["path"],

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

@@ -11,7 +11,7 @@ const DEFAULT_MAX_LINE_LENGTH = 200;
 export class FindTextTool extends SdkCallbackTool {
     function = {
         name: "find_text",
-        description: "查找文本出现的位置，支持普通文本或正则匹配，返回文件名及具体行号、行内容。为避免结果撑爆上下文，默认限制总匹配数、单文件大小与行内容长度，超限会截断并标记 truncated。",
+        description: "Find where text occurs, supporting plain text or regex matching; returns file names with line numbers and line content. To avoid blowing up the context, the total match count, per-file size and line content length are limited by default, and results beyond the limits are truncated and marked truncated.",
         parameters: {
             type: "object",
             properties: {
@@ -25,30 +25,30 @@ export class FindTextTool extends SdkCallbackTool {
                 },
                 text: {
                     type: "string",
-                    description: "要查找的文本（与 regex 二选一）",
+                    description: "Text to search for (mutually exclusive with regex)",
                 },
                 regex: {
                     type: "string",
-                    description: "正则表达式（与 text 二选一，例如 \\bconst\\s+\\w+）",
+                    description: "Regular expression (mutually exclusive with text, e.g. \\bconst\\s+\\w+)",
                 },
                 exclude: {
                     type: "array",
-                    description: "要排除的 glob 模式数组",
+                    description: "Array of glob patterns to exclude",
                     items: {
                         type: "string",
                     },
                 },
                 maxMatches: {
                     type: "number",
-                    description: "总匹配数上限，默认 200",
+                    description: "Maximum total matches (default 200)",
                 },
                 maxFileSize: {
                     type: "number",
-                    description: "单文件大小上限（字节），超过则跳过该文件，默认 307200（300KB）",
+                    description: "Maximum file size in bytes; larger files are skipped (default 307200, i.e. 300KB)",
                 },
                 maxLineLength: {
                     type: "number",
-                    description: "行内容与匹配子串的截断长度，默认 200",
+                    description: "Truncation length for line content and matched substrings (default 200)",
                 },
             },
             required: ["path", "pattern"],
@@ -65,7 +65,7 @@ export class FindTextTool extends SdkCallbackTool {
             const text = input.text;
             const regexStr = input.regex;
             if (!text && !regexStr) {
-                return "请提供 text 或 regex 参数";
+                return "Provide either the text or the regex parameter";
             }
             const regex = regexStr ? new RegExp(regexStr) : null;
             const maxMatches = input.maxMatches ?? DEFAULT_MAX_MATCHES;
@@ -153,8 +153,8 @@ export class FindTextTool extends SdkCallbackTool {
                 const preview = headPreview(json);
                 return JSON.stringify({
                     outputTooLarge: true,
-                    warning: `输出过大：结果共 ${json.length} 字符，超过上限 ${limit} 字符。` +
-                        `完整结果已落盘（result.json），可用 read 分批读取。`,
+                    warning: `Output too large: the results total ${json.length} characters, exceeding the limit of ${limit} characters. ` +
+                        `The full result has been written to disk (result.json) and can be read in chunks with read.`,
                     files: ctx.files,
                     chars: json.length,
                     ...preview,