@yeaft/webchat-agent 0.1.1016 → 0.1.1018

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@yeaft/webchat-agent",
-  "version": "0.1.1016",
+  "version": "0.1.1018",
   "description": "Remote agent for Yeaft WebChat — connects worker machines to the central server",
   "main": "index.js",
   "type": "module",

package/yeaft/tools/agent.js

@@ -216,7 +216,8 @@ export function tickAgent(agentId, delta = {}, now = Date.now()) {
 export default defineTool({
   name: 'SpawnAgent',
   aliases: ['Agent'],
-  description: `Create a sub-agent to work on an independent task in parallel.
+  description: {
+    en: `Create a sub-agent to work on an independent task in parallel.
 
 Sub-agents run in their own context and can be given a concrete mission
 with an optional expected_output schema. Optional budget limits
@@ -242,42 +243,97 @@ Async orchestration:
 Completion/failure is delivered through sub-agent notifications on later parent
 turns. WaitAgent remains available only as a short compatibility poll; do not
 use it as the default workflow or call it repeatedly in a loop.`,
+    zh: `创建一个子 Agent 并行处理独立任务。
+
+子 Agent 在独立上下文中运行，可给定具体 mission 和可选的 expected_output schema。
+可选的预算限制（max_tokens/max_turns/wall_time_ms）仅在设置后作为安全截止。
+选择预设 persona 来预配置工具子集和模型层级：
+  - explorer   : 快速只读侦察（Read/Grep/Glob/ListDir）
+  - implementer: 具备完整工作工具的构建者（主模型）
+  - reviewer   : 只读审查者（主模型）
+  - researcher : 面向网络的信息收集者（WebSearch/WebFetch/Read）
+
+使用指南：
+- 给出清晰聚焦的 mission——"完成"是什么样子
+- 当返回结构重要时使用 expected_output
+- 仅在需要明确安全截止时添加 budget
+
+异步编排流程：
+  1. SpawnAgent  — 启动子 Agent 作为后台任务并立即返回。
+  2. Continue    — 父 VP 继续工作；不要仅仅为了轮询而阻塞。
+  3. ListAgents  — 需要进度信息时的非阻塞状态检查。
+  4. WaitAgent   — 短轮询（<5s）或仅在真正需要结果时才明确长等待。
+  5. CloseAgent  — 完成后销毁子 Agent。
+
+不要在循环中无终止条件地调用 WaitAgent。如果短检查后子 Agent 仍在运行，继续前进，
+让 notification 在下个 turn 告知你。`
+  },
   parameters: {
     type: 'object',
     properties: {
       name: {
         type: 'string',
-        description: 'A descriptive name for the sub-agent (e.g. "test-writer", "refactor-auth")',
+        description: {
+          en: 'A descriptive name for the sub-agent (e.g. "test-writer", "refactor-auth")',
+          zh: '子 Agent 的描述性名称（如 "test-writer"、"refactor-auth"）',
+        },
       },
       task: {
         type: 'string',
-        description: 'Legacy one-line task description (used if `mission` is omitted)',
+        description: {
+          en: 'Legacy one-line task description (used if `mission` is omitted)',
+          zh: '旧式单行任务描述（当 `mission` 省略时使用）',
+        },
       },
       mission: {
         type: 'string',
-        description: 'Concrete mission statement — what this agent must accomplish',
+        description: {
+          en: 'Concrete mission statement — what this agent must accomplish',
+          zh: '具体任务陈述 — 该 Agent 必须完成什么',
+        },
       },
       expected_output: {
         type: 'object',
-        description: 'JSON schema describing the structure the agent should return',
+        description: {
+          en: 'JSON schema describing the structure the agent should return',
+          zh: '描述 Agent 应返回结构的 JSON schema',
+        },
       },
       persona: {
         type: 'string',
         enum: ['explorer', 'implementer', 'reviewer', 'researcher'],
-        description: 'Preset persona that pre-wires tool subset + model tier',
+        description: {
+          en: 'Preset persona that pre-wires tool subset + model tier',
+          zh: '预设 persona，预装工具子集和模型等级',
+        },
       },
       budget: {
         type: 'object',
         properties: {
-          max_tokens: { type: 'number', description: 'Optional token ceiling; no default limit is applied' },
-          max_turns: { type: 'number', description: 'Optional turn ceiling; no default limit is applied' },
-          wall_time_ms: { type: 'number', description: 'Optional elapsed-time ceiling in milliseconds; no default limit is applied' },
+          max_tokens: { type: 'number', description: {
+          en: 'Optional token ceiling; no default limit is applied',
+          zh: '可选 token 上限；默认不设限制',
+        } },
+          max_turns: { type: 'number', description: {
+          en: 'Optional turn ceiling; no default limit is applied',
+          zh: '可选 turn 上限；默认不设限制',
+        } },
+          wall_time_ms: { type: 'number', description: {
+          en: 'Optional elapsed-time ceiling in milliseconds; no default limit is applied',
+          zh: '可选耗时上限（毫秒）；默认不设限制',
+        } },
+        },
+        description: {
+          en: 'Optional safety limits; no max_tokens/max_turns/wall_time_ms defaults are applied. Exceeding an explicit limit returns { status: "budget_exceeded", partial_output, reason }',
+          zh: '可选安全限制；默认不限制 max_tokens/max_turns/wall_time_ms。超过显式限制会返回 { status: "budget_exceeded", partial_output, reason }',
         },
-        description: 'Optional safety limits; no max_tokens/max_turns/wall_time_ms defaults are applied. Exceeding an explicit limit returns { status: "budget_exceeded", partial_output, reason }',
       },
       cwd: {
         type: 'string',
-        description: 'Working directory for the sub-agent (optional, defaults to parent cwd)',
+        description: {
+          en: 'Working directory for the sub-agent (optional, defaults to parent cwd)',
+          zh: '子 Agent 的工作目录（可选，默认使用父级当前工作目录）',
+        },
       },
     },
     required: ['name'],

package/yeaft/tools/apply-patch.js

@@ -96,7 +96,8 @@ function applyHunks(content, hunks) {
 
 export default defineTool({
   name: 'ApplyPatch',
-  description: `Apply a unified diff patch to files.
+  description: {
+    en: `Apply a unified diff patch to files.
 
 Parses unified diff format (like git diff output) and applies changes.
 Supports patching multiple files in a single diff.
@@ -105,12 +106,24 @@ Guidelines:
 - Provide standard unified diff format (--- a/file, +++ b/file, @@ hunks)
 - Ensure the diff matches the current file content exactly
 - New files are created automatically with parent directories`,
+    zh: `将 unified diff 补丁应用到文件。
+
+解析 unified diff 格式（如 git diff 输出）并应用更改。支持单个 diff 修补多个文件。
+
+使用指南：
+- 提供标准 unified diff 格式（--- a/file, +++ b/file, @@ 块）
+- 确保 diff 与当前文件内容精确匹配
+- 新文件自动创建并创建父目录`
+  },
   parameters: {
     type: 'object',
     properties: {
       patch: {
         type: 'string',
-        description: 'The unified diff patch content',
+        description: {
+          en: 'The unified diff patch content',
+          zh: 'unified diff 补丁内容',
+        },
       },
     },
     required: ['patch'],

package/yeaft/tools/ask-user.js

@@ -13,7 +13,8 @@ import { randomUUID } from 'crypto';
 
 export default defineTool({
   name: 'AskUser',
-  description: `Ask the user a question and wait for their response.
+  description: {
+    en: `Ask the user a question and wait for their response.
 
 Use this tool when you need additional information or clarification from the user.
 The user will see your question in the chat interface and can type a response.
@@ -23,17 +24,33 @@ Guidelines:
 - Provide context about why you need the information
 - If presenting options, list them clearly
 - Don't use this for rhetorical questions — only when you genuinely need user input`,
+    zh: `向用户提问并等待回复。
+
+当你需要用户提供更多信息或澄清时使用此工具。用户会在聊天界面中看到你的问题并输入回复。
+
+使用指南：
+- 提出具体、聚焦的问题
+- 说明你为什么需要这些信息
+- 如果提供选项，请清晰列出
+- 不要用于反问句——只有真正需要用户输入时才使用`
+  },
   parameters: {
     type: 'object',
     properties: {
       question: {
         type: 'string',
-        description: 'The question to ask the user',
+        description: {
+          en: 'The question to ask the user',
+          zh: '向用户提出的问题',
+        },
       },
       options: {
         type: 'array',
         items: { type: 'string' },
-        description: 'Optional list of choices for the user to pick from',
+        description: {
+          en: 'Optional list of choices for the user to pick from',
+          zh: '供用户选择的选项列表（可选）',
+        },
       },
     },
     required: ['question'],

package/yeaft/tools/bash.js

@@ -155,7 +155,8 @@ function runCommand(command, { cwd, timeout, signal, runtimePlatform }) {
 
 export default defineTool({
   name: 'Bash',
-  description: `Execute a shell command and return its output.
+  description: {
+    en: `Execute a shell command and return its output.
 
 Use this tool to run CLI commands, scripts, and system operations. The tool name
 is kept as Bash for compatibility; on Windows the command is executed through
@@ -170,20 +171,42 @@ Guidelines:
 - Avoid interactive commands (no stdin support)
 - For long-running tasks, consider redirecting output to a file
 - stderr is captured separately and included in the result`,
+    zh: `执行 Shell 命令并返回输出。
+
+用于运行 CLI 命令、脚本和系统操作。
+
+使用指南：
+- 命令在工作目录中执行（上下文中的 cwd）
+- 默认超时 2 分钟（最大 10 分钟）
+- 大输出在 256KB 处截断
+- 尽量使用绝对路径
+- 避免交互式命令（不支持 stdin）
+- 长时间任务建议重定向输出到文件
+- stderr 单独捕获并包含在结果中`
+  },
   parameters: {
     type: 'object',
     properties: {
       command: {
         type: 'string',
-        description: 'The shell command to execute using the Agent OS default shell',
+        description: {
+          en: 'The shell command to execute using the Agent OS default shell',
+          zh: '要使用 Agent 操作系统默认 shell 执行的命令',
+        },
       },
       cwd: {
         type: 'string',
-        description: 'Working directory for the command (default: engine cwd)',
+        description: {
+          en: 'Working directory for the command (default: engine cwd)',
+          zh: '命令的工作目录（默认为引擎当前目录）',
+        },
       },
       timeout_ms: {
         type: 'number',
-        description: `Timeout in milliseconds (default: ${DEFAULT_TIMEOUT_MS}, max: ${MAX_TIMEOUT_MS})`,
+        description: {
+          en: `Timeout in milliseconds (default: ${DEFAULT_TIMEOUT_MS}, max: ${MAX_TIMEOUT_MS})`,
+          zh: `超时时间，单位毫秒（默认 ${DEFAULT_TIMEOUT_MS}，最大 ${MAX_TIMEOUT_MS}）`,
+        },
       },
     },
     required: ['command'],

package/yeaft/tools/close-agent.js

@@ -15,7 +15,8 @@ import { snapshotLiveness } from '../sub-agent/liveness.js';
 
 export default defineTool({
   name: 'CloseAgent',
-  description: `Close a sub-agent and release its resources.
+  description: {
+    en: `Close a sub-agent and release its resources.
 
 Use when a sub-agent's task is complete or no longer needed.
 The agent's final \`result\` (if any) is returned in the envelope before closing.
@@ -24,16 +25,29 @@ CRITICAL — closing the sub-agent is NOT the end of YOUR turn. After CloseAgent
 you MUST relay the \`result\` to the user in your own reply (or summarize what
 was accomplished). The user has not seen the sub-agent's reply — only you have.
 Do NOT end your turn silently right after CloseAgent.`,
+    zh: `关闭子 Agent 并释放其资源。
+
+当子 Agent 的任务完成或不再需要时使用。关闭前会返回子 Agent 的最终 result（如有）。
+
+关键——关闭子 Agent 不是你 turn 的结束。CloseAgent 后你必须用自己的回复将 result 传达给用户
+（或总结已完成的内容）。用户看不到子 Agent 的回复——只有你能看到。不要在 CloseAgent 后默默结束 turn。`
+  },
   parameters: {
     type: 'object',
     properties: {
       agent_id: {
         type: 'string',
-        description: 'The sub-agent ID to close',
+        description: {
+          en: 'The sub-agent ID to close',
+          zh: '要关闭的子 Agent ID',
+        },
       },
       result: {
         type: 'string',
-        description: 'Optional final result to set before closing',
+        description: {
+          en: 'Optional final result to set before closing',
+          zh: '关闭前设置的可选最终结果',
+        },
       },
     },
     required: ['agent_id'],

package/yeaft/tools/enter-worktree.js

@@ -16,7 +16,8 @@ import { randomUUID } from 'crypto';
 
 export default defineTool({
   name: 'EnterWorktree',
-  description: `Create an isolated git worktree for development.
+  description: {
+    en: `Create an isolated git worktree for development.
 
 Creates a new git worktree with a dedicated branch, allowing parallel
 development without file conflicts. Useful for:
@@ -26,16 +27,31 @@ development without file conflicts. Useful for:
 
 The worktree is created in .yeaft/worktrees/ with a new branch based on HEAD.
 Returns the worktree path and branch name.`,
+    zh: `创建一个独立的 git worktree 用于开发。
+
+创建带独立分支的新 git worktree，允许并行开发无文件冲突。适用于：
+- 子 Agent 处理独立子任务
+- 合并前隔离测试改动
+- 并行功能开发
+
+Worktree 创建在 .yeaft/worktrees/ 中，基于 HEAD 创建新分支。返回 worktree 路径和分支名。`
+  },
   parameters: {
     type: 'object',
     properties: {
       name: {
         type: 'string',
-        description: 'Name for the worktree (used in path and branch name). If omitted, a random name is generated.',
+        description: {
+          en: 'Name for the worktree (used in path and branch name). If omitted, a random name is generated.',
+          zh: 'worktree 名称（用于路径和分支名）。如省略，自动生成随机名。',
+        },
       },
       base_ref: {
         type: 'string',
-        description: 'Git ref to base the worktree on (default: HEAD)',
+        description: {
+          en: 'Git ref to base the worktree on (default: HEAD)',
+          zh: '基于哪个 Git 引用创建（默认 HEAD）',
+        },
       },
     },
   },

package/yeaft/tools/exit-worktree.js

@@ -14,7 +14,8 @@ import { resolve } from 'path';
 
 export default defineTool({
   name: 'ExitWorktree',
-  description: `Exit a git worktree session.
+  description: {
+    en: `Exit a git worktree session.
 
 Options:
 - "keep": Leave the worktree and branch on disk (can return later)
@@ -22,21 +23,38 @@ Options:
 
 If removing and there are uncommitted changes, the operation will fail
 unless discard_changes is set to true.`,
+    zh: `退出 git worktree 会话。
+
+选项：
+- "keep"：保留 worktree 和分支在磁盘上（之后可返回）
+- "remove"：删除 worktree 目录及其分支
+
+如果删除时有未提交的更改，操作会失败，除非设置 discard_changes 为 true。`
+  },
   parameters: {
     type: 'object',
     properties: {
       path: {
         type: 'string',
-        description: 'Path to the worktree to exit (required)',
+        description: {
+          en: 'Path to the worktree to exit (required)',
+          zh: '要退出的 worktree 路径（必填）',
+        },
       },
       action: {
         type: 'string',
         enum: ['keep', 'remove'],
-        description: '"keep" leaves the worktree on disk; "remove" deletes it',
+        description: {
+          en: '"keep" leaves the worktree on disk; "remove" deletes it',
+          zh: '"keep" 在磁盘上保留 worktree；"remove" 删除它',
+        },
       },
       discard_changes: {
         type: 'boolean',
-        description: 'Force remove even with uncommitted changes (default: false)',
+        description: {
+          en: 'Force remove even with uncommitted changes (default: false)',
+          zh: '即使有未提交改动也强制删除（默认 false）',
+        },
       },
     },
     required: ['path', 'action'],

package/yeaft/tools/file-edit.js

@@ -13,7 +13,8 @@ import { resolve } from 'path';
 
 export default defineTool({
   name: 'FileEdit',
-  description: `Make surgical text replacements in an existing file.
+  description: {
+    en: `Make surgical text replacements in an existing file.
 
 Replaces exact occurrences of old_string with new_string.
 The old_string must be unique in the file unless replace_all is true.
@@ -24,24 +25,47 @@ Guidelines:
 - Use replace_all: true to replace ALL occurrences
 - For creating new files or full rewrites, use FileWrite instead
 - Always read the file first to understand its current content`,
+    zh: `在已有文件中做精确文本替换。
+
+用 new_string 替换 old_string 的精确出现。old_string 在文件中必须唯一，除非设置 replace_all 为 true。
+
+使用指南：
+- old_string 必须完全匹配（包括空白和缩进）
+- 若 old_string 找不到或不唯一，编辑失败
+- 使用 replace_all: true 替换所有出现位置
+- 创建新文件或全量重写请用 FileWrite
+- 始终先读文件了解其当前内容`
+  },
   parameters: {
     type: 'object',
     properties: {
       file_path: {
         type: 'string',
-        description: 'Path to the file to edit (absolute or relative to cwd)',
+        description: {
+          en: 'Path to the file to edit (absolute or relative to cwd)',
+          zh: '要编辑的文件路径（绝对路径或相对于工作目录）',
+        },
       },
       old_string: {
         type: 'string',
-        description: 'The exact text to find and replace',
+        description: {
+          en: 'The exact text to find and replace',
+          zh: '要查找并替换的精确文本',
+        },
       },
       new_string: {
         type: 'string',
-        description: 'The replacement text',
+        description: {
+          en: 'The replacement text',
+          zh: '替换后的文本',
+        },
       },
       replace_all: {
         type: 'boolean',
-        description: 'Replace all occurrences (default: false — fails if not unique)',
+        description: {
+          en: 'Replace all occurrences (default: false — fails if not unique)',
+          zh: '替换所有出现（默认 false — 不唯一时失败）',
+        },
       },
     },
     required: ['file_path', 'old_string', 'new_string'],

package/yeaft/tools/file-read.js

@@ -36,7 +36,8 @@ const DEFAULT_LIMIT = 3000;
 
 export default defineTool({
   name: 'FileRead',
-  description: `Read a file from the filesystem with line numbers.
+  description: {
+    en: `Read a file from the filesystem with line numbers.
 
 Returns file contents with line numbers (like \`cat -n\`).
 Supports offset and limit for reading specific portions of large files.
@@ -47,20 +48,40 @@ Guidelines:
 - Binary files are detected by extension and rejected
 - Maximum file size: 10MB
 - Default limit: 3000 lines (matches the "large file = >3000 lines" threshold)`,
+    zh: `读取文件系统中的文件内容，带行号。
+
+返回带行号的文件内容（类似 cat -n）。支持 offset/limit 读取大文件的特定部分。
+
+使用指南：
+- 尽量使用绝对路径
+- 超过 3000 行才算大文件。默认读完整文件；仅在超过此阈值或已知精确行范围时使用 offset/limit
+- 二进制文件通过扩展名识别并拒绝
+- 最大文件大小：10MB
+- 默认行数限制：3000 行`
+  },
   parameters: {
     type: 'object',
     properties: {
       file_path: {
         type: 'string',
-        description: 'Path to the file to read (absolute or relative to cwd)',
+        description: {
+          en: 'Path to the file to read (absolute or relative to cwd)',
+          zh: '要读取的文件路径（绝对路径或相对于当前工作目录）',
+        },
       },
       offset: {
         type: 'number',
-        description: 'Line number to start reading from (0-based, default: 0)',
+        description: {
+          en: 'Line number to start reading from (0-based, default: 0)',
+          zh: '起始行号（从 0 开始计数，默认 0）',
+        },
       },
       limit: {
         type: 'number',
-        description: `Maximum number of lines to read (default: ${DEFAULT_LIMIT})`,
+        description: {
+          en: `Maximum number of lines to read (default: ${DEFAULT_LIMIT})`,
+          zh: `最多读取行数（默认 ${DEFAULT_LIMIT} 行）`,
+        },
       },
     },
     required: ['file_path'],

package/yeaft/tools/file-write.js

@@ -11,7 +11,8 @@ import { resolve, dirname } from 'path';
 
 export default defineTool({
   name: 'FileWrite',
-  description: `Write content to a file, creating it if it doesn't exist.
+  description: {
+    en: `Write content to a file, creating it if it doesn't exist.
 
 Creates parent directories automatically. Overwrites existing files.
 
@@ -20,16 +21,32 @@ Guidelines:
 - For modifying existing files, prefer FileEdit (surgical edits) over FileWrite (full overwrite)
 - Parent directories are created automatically
 - Content should be the complete file content`,
+    zh: `将内容写入文件，若文件不存在则创建。
+
+自动创建父目录。覆盖已存在的文件。
+
+使用指南：
+- 尽量使用绝对路径
+- 修改已有文件时优先使用 FileEdit（精确编辑）而非 FileWrite（全量覆盖）
+- 父目录自动创建
+- 内容应为完整文件内容`
+  },
   parameters: {
     type: 'object',
     properties: {
       file_path: {
         type: 'string',
-        description: 'Path to the file to write (absolute or relative to cwd)',
+        description: {
+          en: 'Path to the file to write (absolute or relative to cwd)',
+          zh: '要写入的文件路径（绝对路径或相对于工作目录）',
+        },
       },
       content: {
         type: 'string',
-        description: 'The complete file content to write',
+        description: {
+          en: 'The complete file content to write',
+          zh: '要写入的完整文件内容',
+        },
       },
     },
     required: ['file_path', 'content'],

package/yeaft/tools/glob.js

@@ -67,7 +67,8 @@ async function* walkDir(dir, baseDir, maxDepth = 10, depth = 0) {
 
 export default defineTool({
   name: 'Glob',
-  description: `Find files matching a glob pattern.
+  description: {
+    en: `Find files matching a glob pattern.
 
 Supports glob patterns like "**/*.js", "src/**/*.ts", "*.md".
 Results are sorted by modification time (newest first).
@@ -77,20 +78,39 @@ Guidelines:
 - Common directories (node_modules, .git, etc.) are skipped
 - Returns file paths relative to the search directory
 - Limited to 500 results by default`,
+    zh: `查找匹配 glob 模式的文件。
+
+支持如 "**/*.js"、"src/**/*.ts"、"*.md" 等 glob 模式。结果按修改时间排序（最新优先）。
+
+使用指南：
+- 用 "**/" 进行递归目录匹配
+- 常见目录（node_modules、.git 等）被跳过
+- 返回相对于搜索目录的文件路径
+- 默认限制 500 条结果`
+  },
   parameters: {
     type: 'object',
     properties: {
       pattern: {
         type: 'string',
-        description: 'Glob pattern to match files (e.g. "**/*.js")',
+        description: {
+          en: 'Glob pattern to match files (e.g. "**/*.js")',
+          zh: '匹配文件的 glob 模式（如 "**/*.js"）',
+        },
       },
       path: {
         type: 'string',
-        description: 'Directory to search in (default: cwd)',
+        description: {
+          en: 'Directory to search in (default: cwd)',
+          zh: '搜索目录（默认当前工作目录）',
+        },
       },
       limit: {
         type: 'number',
-        description: 'Maximum number of results (default: 500)',
+        description: {
+          en: 'Maximum number of results (default: 500)',
+          zh: '最多返回结果数（默认 500）',
+        },
       },
     },
     required: ['pattern'],