@yeaft/webchat-agent 0.1.1016 → 0.1.1018

package/yeaft/tools/route-forward.js

@@ -27,7 +27,8 @@ import { defineTool } from './types.js';
 
 export default defineTool({
   name: 'RouteForward',
-  description: `Hand this turn off to another VP in the same session.
+  description: {
+    en: `Hand this turn off to another VP in the same session.
 
 Use this tool — NOT free-text @mentions — to route a question or task to
 another VP. VP-authored @mentions in chat text are NOT automatically routed
@@ -55,20 +56,47 @@ Rules:
     per session (throttled).
 
 Returns JSON: { ok, dispatched?, error?, detail? }.`,
+    zh: `将当前 turn 转发给同一 Session 中的其他 VP。
+
+使用此工具——而非自由文本 @mention——将问题或任务路由给其他 VP。VP 在聊天文本中写的 @mention
+不会自动路由（Session 协调器仅对用户消息做文本路由）；你必须调用 RouteForward 才能完成转交。
+
+参数：
+  - to（字符串）：目标 vpId，或字面量 "all" 向 Session 中所有其他成员广播（受 Session fan-out 上限限制）。
+  - text（字符串）：以你名义发送的消息正文。
+  - reason（字符串，可选）：转发原因的简短说明，记录在消息元数据中用于审计/界面显示。
+
+规则：
+  - 转发给自己会被拒绝（self_forward_rejected）。
+  - 转发给非成员会被拒绝（target_not_in_roster）。
+  - 转发带有 causedBy 链；超过 10 跳的链会被阻止（chain_depth_exceeded）。
+  - 同一目标在每 5 秒窗口内最多被转发 8 次（节流限制）。
+
+返回 JSON：{ ok, dispatched?, error?, detail? }。`
+  },
   parameters: {
     type: 'object',
     properties: {
       to: {
         type: 'string',
-        description: 'Target vpId, or "all" for broadcast',
+        description: {
+          en: 'Target vpId, or "all" for broadcast',
+          zh: '目标 vpId，或 "all" 广播给所有人',
+        },
       },
       text: {
         type: 'string',
-        description: 'The message body to forward',
+        description: {
+          en: 'The message body to forward',
+          zh: '要转发的消息正文',
+        },
       },
       reason: {
         type: 'string',
-        description: 'Optional: short rationale for the forward',
+        description: {
+          en: 'Optional: short rationale for the forward',
+          zh: '可选：转交的简短原因',
+        },
       },
     },
     required: ['to', 'text'],

package/yeaft/tools/send-message.js

@@ -12,7 +12,8 @@ import { isTerminalAgentStatus, isPromptableAgentStatus, STATUS, describeAgentSt
 export default defineTool({
   name: 'PromptAgent',
   aliases: ['SendMessage'],
-  description: `Send a follow-up prompt to a sub-agent you previously spawned.
+  description: {
+    en: `Send a follow-up prompt to a sub-agent you previously spawned.
 
 Use this to give the sub-agent more work, additional instructions, or relay
 information. The prompt is queued for the agent to process on its next turn.
@@ -26,16 +27,34 @@ SpawnAgent → (PromptAgent ↔ WaitAgent)+ → CloseAgent → final reply to us
 
 PromptAgent is rejected if the sub-agent is in a terminal state
 (completed/failed/closed/abandoned). Use SpawnAgent to start a fresh one.`,
+    zh: `向之前创建的子 Agent 发送后续提示。
+
+用于给子 Agent 更多工作、额外指令或传递信息。提示会排队等待子 Agent 在其下一个 turn 处理。
+
+重要——PromptAgent 仅将消息排队，不阻塞。返回后你通常需要立即调用 WaitAgent 来收集回复。
+不要在 PromptAgent 后直接结束 turn，除非：(a) 调用 WaitAgent，(b) 向用户说明你刚让子 Agent
+做了什么，或 (c) 调用 CloseAgent。编排循环为：
+SpawnAgent -> (PromptAgent <-> WaitAgent)+ -> CloseAgent -> 最终回复给用户。
+
+如果子 Agent 处于终止状态（completed/failed/closed/abandoned），PromptAgent 会被拒绝。
+用 SpawnAgent 启动新的。`
+  },
   parameters: {
     type: 'object',
     properties: {
       agent_id: {
         type: 'string',
-        description: 'The sub-agent ID (returned by Agent tool)',
+        description: {
+          en: 'The sub-agent ID (returned by Agent tool)',
+          zh: '子 Agent ID（由 Agent 工具返回）',
+        },
       },
       message: {
         type: 'string',
-        description: 'The message to send to the agent',
+        description: {
+          en: 'The message to send to the agent',
+          zh: '要发送给 Agent 的消息',
+        },
       },
     },
     required: ['agent_id', 'message'],

package/yeaft/tools/skill.js

@@ -17,7 +17,8 @@ import { defineTool } from './types.js';
 
 export default defineTool({
   name: 'Skill',
-  description: `Load and query skills from the Yeaft skill library.
+  description: {
+    en: `Load and query skills from the Yeaft skill library.
 
 Skills are specialized behaviors or workflows in ~/.yeaft/skills/.
 Two formats supported:
@@ -29,29 +30,56 @@ Actions:
 - "view" — view a skill's full content. For directory skills, also lists linked files. Pass filePath to read a specific reference/template.
 - "search" — find relevant skills for a query string
 - "load" — alias for "view" (backward compatible)`,
+    zh: `从 Yeaft 技能库加载和查询技能。
+
+技能是 ~/.yeaft/skills/ 中的专业化行为或工作流。支持两种格式：
+- 单文件：skills/my-skill.md
+- 目录：skills/my-skill/SKILL.md + references/ + templates/
+
+操作：
+- "list" — 列出所有技能（仅元数据：名称、描述、分类）
+- "view" — 查看技能的完整内容。对目录型技能同时列出关联文件。传 filePath 可读取特定引用/模板。
+- "search" — 为查询字符串查找相关技能
+- "load" — "view" 的别名（向后兼容）`
+  },
   parameters: {
     type: 'object',
     properties: {
       action: {
         type: 'string',
         enum: ['list', 'view', 'load', 'search'],
-        description: '"list" lists all skills, "view"/"load" loads a specific skill, "search" finds relevant skills',
+        description: {
+          en: '"list" lists all skills, "view"/"load" loads a specific skill, "search" finds relevant skills',
+          zh: '"list" 列出所有 skill，"view"/"load" 加载特定 skill，"search" 查找相关 skill',
+        },
       },
       name: {
         type: 'string',
-        description: 'Skill name (for "view"/"load" action)',
+        description: {
+          en: 'Skill name (for "view"/"load" action)',
+          zh: 'Skill 名称（用于 "view"/"load" 动作）',
+        },
       },
       query: {
         type: 'string',
-        description: 'Search query (for "search" action)',
+        description: {
+          en: 'Search query (for "search" action)',
+          zh: '搜索查询（用于 "search" 动作）',
+        },
       },
       filePath: {
         type: 'string',
-        description: 'Read a linked file from a directory skill (e.g. "references/style-guide.md")',
+        description: {
+          en: 'Read a linked file from a directory skill (e.g. "references/style-guide.md")',
+          zh: '读取目录式 skill 的关联文件（如 "references/style-guide.md"）',
+        },
       },
       category: {
         type: 'string',
-        description: 'Filter by category (for "list" action)',
+        description: {
+          en: 'Filter by category (for "list" action)',
+          zh: '按分类过滤（用于 "list" 动作）',
+        },
       },
     },
     required: ['action'],

package/yeaft/tools/start-plan.js

@@ -40,7 +40,8 @@ import { getDefaultPlanInstruction } from '../prompts.js';
 
 export default defineTool({
   name: 'StartPlan',
-  description: `Enter planning mode for a non-trivial task. Use BEFORE you start working when the request needs multiple steps, has unclear scope, or the user said "make a plan" / "think through this first".
+  description: {
+    en: `Enter planning mode for a non-trivial task. Use BEFORE you start working when the request needs multiple steps, has unclear scope, or the user said "make a plan" / "think through this first".
 
 This tool returns a planning instruction. Use it to land a structured plan, then keep working in the same turn. The expected flow is:
 1. Produce a short prose plan (problem, approach, risks).
@@ -59,28 +60,64 @@ WHEN NOT TO USE:
 EXCEPTION — stop after the plan only if the first step is genuinely "ask the user" (an unresolved unknown that blocks every other step). Otherwise keep moving.
 
 The tool takes the topic plus optional guiding fields (stuckAt, userProblem, expectedScale, additionalContext) that help you think; they're echoed back verbatim, so don't repeat the full user request in \`topic\`.`,
+    zh: `进入规划模式，用于非平凡任务。在开始工作之前使用——当需求涉及多步骤、范围不明确，或用户说"先做个计划"/"先想清楚"时。
+
+此工具返回规划指令。用它产出一份结构化计划，然后在同一个 turn 中继续工作。预期流程是：
+1. 产出简短文字计划（问题、方法、风险）。
+2. 调用 TodoWrite 写出有序步骤。将第一个具体步骤标记为 "in_progress"，其余标记为 "pending"。
+3. 开始执行第一个步骤——调用工作所需的任何工具。不要因为计划写完了就结束 turn；计划是跑道。
+
+何时使用：
+- 多步骤实现（3+ 步）、重构或开放式调查。
+- 用户明确要求计划、TODO 列表或"想清楚"再动手。
+- 你即将开始一个大型改动，想在动手前有个检查点。
+
+何时不使用：
+- 单个琐碎改动、单个命令执行、查询式问题。
+- 中途执行——一旦过了第一步，直接用 TodoWrite。
+
+例外——只有当第一步确实是"询问用户"（一个未解决的未知因素，阻塞所有其他步骤）时才在计划后停止。否则继续前进。
+
+此工具接收 topic 加上可选引导字段（stuckAt、userProblem、expectedScale、additionalContext）
+帮助你思考；它们会被原样回显，所以不要在 topic 中重复完整的用户请求。`
+  },
   parameters: {
     type: 'object',
     properties: {
       topic: {
         type: 'string',
-        description: 'One-sentence statement of what is being planned (e.g. "Add dark-mode toggle to YeaftPage settings").',
+        description: {
+          en: 'One-sentence statement of what is being planned (e.g. "Add dark-mode toggle to YeaftPage settings").',
+          zh: '用一句话说明要规划什么（如"为 YeaftPage 设置添加深色模式切换"）',
+        },
       },
       userProblem: {
         type: 'string',
-        description: 'Optional. The underlying problem the user is trying to solve (often broader than the immediate ask).',
+        description: {
+          en: 'Optional. The underlying problem the user is trying to solve (often broader than the immediate ask).',
+          zh: '可选。用户试图解决的根本问题（通常比即时请求更宽泛）',
+        },
       },
       stuckAt: {
         type: 'string',
-        description: 'Optional. If you are blocked or unsure, the specific decision or unknown that needs resolving first.',
+        description: {
+          en: 'Optional. If you are blocked or unsure, the specific decision or unknown that needs resolving first.',
+          zh: '可选。如果你被阻塞或不确定，需要首先解决的具体决策或未知点',
+        },
       },
       expectedScale: {
         type: 'string',
-        description: 'Optional. Rough scope estimate — number of files touched, lines of code, time horizon, etc.',
+        description: {
+          en: 'Optional. Rough scope estimate — number of files touched, lines of code, time horizon, etc.',
+          zh: '可选。粗略范围估计 — 涉及文件数、代码行数、时间预期等',
+        },
       },
       additionalContext: {
         type: 'string',
-        description: 'Optional. Any other facts that shape the plan (constraints, deadlines, related prior work).',
+        description: {
+          en: 'Optional. Any other facts that shape the plan (constraints, deadlines, related prior work).',
+          zh: '可选。影响计划的其他事实（约束、截止日期、相关先前工作）',
+        },
       },
     },
     required: ['topic'],

package/yeaft/tools/todo-write.js

@@ -25,7 +25,8 @@ const VALID_STATUS = new Set(['pending', 'in_progress', 'completed']);
 
 export default defineTool({
   name: 'TodoWrite',
-  description: `Track multi-step task progress with a checklist that the user can see ticked off in real time.
+  description: {
+    en: `Track multi-step task progress with a checklist that the user can see ticked off in real time.
 
 WHEN TO USE:
 - The task has 3+ meaningful steps, or
@@ -40,27 +41,55 @@ HOW TO USE:
 
 WHEN NOT TO USE:
 - Single trivial change, single command run, pure conversation/question.`,
+    zh: `用 checklist 跟踪多步骤任务进度，用户可以实时看到勾选。
+
+何时使用：
+- 任务有 3 步或以上有意义步骤，或
+- 用户给了你一份待办列表（编号/逗号分隔），或
+- 你即将开始一个非平凡的多文件改动。
+
+如何使用：
+- 首次调用：枚举所有 todo，状态为 "pending"，将其中恰好一个设为 "in_progress"。
+- 每次后续调用：重写完整列表——将刚完成的项标记为 "completed"，将下一项标记为 "in_progress"。
+- 任何时候最多只能有一个 "in_progress"。
+- content 是祈使形式（如 "Run tests"）；activeForm 是执行时显示的进行时态（如 "Running tests"）。
+
+何时不使用：
+- 单个琐碎改动、单个命令执行、纯对话/提问。`
+  },
   parameters: {
     type: 'object',
     properties: {
       todos: {
         type: 'array',
-        description: 'The full current todo list. Always send the entire list, not a diff.',
+        description: {
+          en: 'The full current todo list. Always send the entire list, not a diff.',
+          zh: '当前完整的待办清单。始终发送整个列表，而非增量。',
+        },
         items: {
           type: 'object',
           properties: {
             content: {
               type: 'string',
-              description: 'Imperative description of the step (e.g. "Run tests").',
+              description: {
+          en: 'Imperative description of the step (e.g. "Run tests").',
+          zh: '步骤的命令式描述（如 "Run tests"）。',
+        },
             },
             status: {
               type: 'string',
               enum: ['pending', 'in_progress', 'completed'],
-              description: 'Current state. At most one item may be "in_progress".',
+              description: {
+          en: 'Current state. At most one item may be "in_progress".',
+          zh: '当前状态。最多只能有一项为 "in_progress"。',
+        },
             },
             activeForm: {
               type: 'string',
-              description: 'Present-continuous form shown while executing (e.g. "Running tests").',
+              description: {
+          en: 'Present-continuous form shown while executing (e.g. "Running tests").',
+          zh: '执行中展示的进行时描述（如 "Running tests"）。',
+        },
             },
           },
           required: ['content', 'status', 'activeForm'],

package/yeaft/tools/types.js

@@ -51,7 +51,7 @@
 /**
  * @typedef {Object} ToolDef
  * @property {string} name — unique tool name (e.g. 'Bash', 'FileRead')
- * @property {string} description — LLM-facing description
+ * @property {string | { en: string, zh: string, default?: string }} description — LLM-facing localized description
  * @property {object} parameters — JSON Schema for input
  * @property {(input: object, ctx?: ToolContext) => Promise<string>} execute — execution function
  * @property {(input?: object) => boolean} [isConcurrencySafe] — can run in parallel?
@@ -64,7 +64,7 @@
  *
  * @param {{
  *   name: string,
- *   description: string,
+ *   description: string | { en: string, zh: string, default?: string },
  *   parameters: object,
  *   execute: (input: object, ctx?: ToolContext) => Promise<string>,
  *   isConcurrencySafe?: (input?: object) => boolean,

package/yeaft/tools/view-image.js

@@ -119,7 +119,8 @@ function formatBytes(n) {
 
 export default defineTool({
   name: 'ViewImage',
-  description: `Load a local image file and attach it to the conversation so the LLM can see it.
+  description: {
+    en: `Load a local image file and attach it to the conversation so the LLM can see it.
 
 Returns a base64 data URI (\`image\` field) plus metadata (format, dimensions,
 size). The caller/bridge is responsible for turning the data URI into the
@@ -148,12 +149,37 @@ Path examples:
 Supported formats: PNG, JPEG (.jpg/.jpeg/.jfif), GIF, WebP.
 Max size: 20 MiB by default (configurable via ctx.maxImageBytes).
 Path must live under the project directory or an explicit host allowlist.`,
+    zh: `加载本地图片文件并附加到对话中，使 LLM 可以查看。
+
+返回 base64 data URI（image 字段）及元数据（格式、尺寸、大小）。调用方/桥接层负责将 data URI 转换为
+provider 特定的图片内容块。
+
+何时调用：
+  - 用户引用本地图片路径（截图、设计稿、日志/图表）并要求你读取、分析或描述它。
+  - 用户说"看看这个文件"/"检查 xxx 处的截图"/"docs/assets/arch.png 里有什么？"。
+
+何时不调用：
+  - 图片已附加到当前消息中（宿主已上传——你无需此工具即可看到）。
+  - 图片是远程 URL（http/https）。ViewImage 只读本地文件；对 URL 使用抓取类工具。
+  - 你只需要文件的存续/修改时间/大小——用 Read 或文件系统工具；ViewImage 会将完整文件字节加载到内存。
+
+路径示例：
+  - 相对路径（相对项目 cwd 解析）："./screenshots/bug.png"、"docs/assets/arch.png"
+  - 白名单目录内的绝对路径："/home/user/Downloads/error.png"（仅当宿主将该目录加入 ctx.imageAllowlist 时有效）
+
+支持格式：PNG、JPEG（.jpg/.jpeg/.jfif）、GIF、WebP。
+最大文件：默认 20 MiB（可通过 ctx.maxImageBytes 配置）。
+路径必须在项目目录下或已加入宿主白名单。`
+  },
   parameters: {
     type: 'object',
     properties: {
       file_path: {
         type: 'string',
-        description: 'Path to the image file. Relative paths are resolved against the project cwd.',
+        description: {
+          en: 'Path to the image file. Relative paths are resolved against the project cwd.',
+          zh: '图片文件路径。相对路径相对于项目工作目录解析。',
+        },
       },
     },
     required: ['file_path'],

package/yeaft/tools/wait-agent.js

@@ -173,7 +173,8 @@ function buildEnvelope(agent, { timedOut = false } = {}) {
 
 export default defineTool({
   name: 'WaitAgent',
-  description: `Wait for a sub-agent's next state change (turn end, terminal, or wait-timeout) and retrieve a status envelope.
+  description: {
+    en: `Wait for a sub-agent's next state change (turn end, terminal, or wait-timeout) and retrieve a status envelope.
 
 Returns JSON with explicit \`status\`, latest \`result\` text, \`liveness\`
 counters (toolUseCount, tokenCount, msSinceLastEvent, recentTools), the
@@ -200,18 +201,44 @@ the sub-agent's reply yet; only you have. The orchestration loop is
 SpawnAgent → (PromptAgent ↔ WaitAgent)+ → CloseAgent → final reply to user.
 
 Compatibility tool. The default wait is a short 5000ms poll. Callers may request up to 300000ms (5 minutes), but this is no longer the primary sub-agent workflow; prefer SpawnAgent + ListAgents + completion notifications for async background work.`,
+    zh: `等待子 Agent 的下一次状态变更（turn 结束、终止或等待超时）并获取状态信封。
+
+返回 JSON，含明确的 status、最新的 result 文本、liveness 计数器（toolUseCount、tokenCount、
+msSinceLastEvent、recentTools）、可随时 Read 的持久化 outputFile 路径，以及状态相关的 next_steps
+指令告诉你下一步该调用什么。
+
+状态语义：
+  - completed / closed / failed / abandoned -> 终止。子 Agent 不再做任何事。将结果传达给用户
+    （或重试/报告失败）。
+  - idle -> 子 Agent 完成了一个 turn 并停在空队列。你可以 PromptAgent 继续或 CloseAgent 结束。
+  - timedOut=true（status='running' 且 runningInBackground=true）-> 等待时间耗尽但子 Agent
+    仍在运行。不需要再 PromptAgent。要么用更大 timeout 再次 WaitAgent，要么 CloseAgent 中断，
+    要么告知用户它仍在工作。
+
+关键——如果信封显示 stale/stalled，子 Agent 可能卡死或空转。不要反复调用 WaitAgent——向用户
+报告情况，决定是 CloseAgent（带 close_reason）还是重试。
+
+此工具保留用于向后兼容。现代异步流程请用 ListAgents 做非阻塞状态检查，依赖 turn 开始时的
+notification 获取完成事件。`
+  },
   parameters: {
     type: 'object',
     properties: {
       agent_id: {
         type: 'string',
-        description: 'The sub-agent ID to wait for',
+        description: {
+          en: 'The sub-agent ID to wait for',
+          zh: '要等待的子 Agent ID',
+        },
       },
       timeout_ms: {
         type: 'number',
         minimum: 0,
         maximum: 300000,
-        description: 'Maximum time to wait in milliseconds (default: 5000 short poll, max: 300000 / 5 minutes)',
+        description: {
+          en: 'Maximum time to wait in milliseconds (default: 5000 short poll, max: 300000 / 5 minutes)',
+          zh: '最长等待时间，单位毫秒（默认 5000 短轮询，最大 300000 / 5 分钟）',
+        },
       },
     },
     required: ['agent_id'],

package/yeaft/tools/web-fetch.js

@@ -34,7 +34,8 @@ function htmlToText(html) {
 
 export default defineTool({
   name: 'WebFetch',
-  description: `Fetch and read the content of a web page.
+  description: {
+    en: `Fetch and read the content of a web page.
 
 Retrieves the URL content, strips HTML tags, and returns readable text.
 Use this to read documentation, articles, or any web page.
@@ -44,20 +45,39 @@ Guidelines:
 - Large pages will be truncated — use the offset parameter for pagination
 - For APIs, the raw response body is returned as-is
 - Respects the abort signal for cancellation`,
+    zh: `获取并读取网页内容。
+
+获取 URL 内容，去除 HTML 标签，返回可读文本。用于阅读文档、文章或任何网页。
+
+使用指南：
+- 提供完整 URL 含协议（https://）
+- 大页面会截断——用 offset 参数做分页
+- 对 API 请求，原始响应体原样返回
+- 尊重取消信号`
+  },
   parameters: {
     type: 'object',
     properties: {
       url: {
         type: 'string',
-        description: 'The URL to fetch',
+        description: {
+          en: 'The URL to fetch',
+          zh: '要获取的 URL',
+        },
       },
       max_length: {
         type: 'number',
-        description: 'Maximum content length in characters (default: 50000)',
+        description: {
+          en: 'Maximum content length in characters (default: 50000)',
+          zh: '最大内容长度，单位字符（默认 50000）',
+        },
       },
       raw: {
         type: 'boolean',
-        description: 'If true, return raw response without HTML stripping (for APIs)',
+        description: {
+          en: 'If true, return raw response without HTML stripping (for APIs)',
+          zh: '如果为 true，返回原始响应不去除 HTML（用于 API）',
+        },
       },
     },
     required: ['url'],

package/yeaft/tools/web-search.js

@@ -25,7 +25,8 @@ import { defineTool } from './types.js';
 
 export default defineTool({
   name: 'WebSearch',
-  description: `Search the web for current information.
+  description: {
+    en: `Search the web for current information.
 
 Use this when you need up-to-date information that may not be in your training data.
 Returns search results with titles, URLs, and snippets.
@@ -34,16 +35,31 @@ Guidelines:
 - Use specific, targeted search queries
 - Include the current year for time-sensitive queries
 - Combine with WebFetch to read full page content from results`,
+    zh: `搜索网页获取最新信息。
+
+当你需要训练数据中可能没有的最新信息时使用。返回搜索结果，含标题、URL 和摘要。
+
+使用指南：
+- 使用具体、有针对性的搜索关键词
+- 时间敏感的查询要包含当前年份
+- 配合 WebFetch 读取搜索结果中的完整页面内容`
+  },
   parameters: {
     type: 'object',
     properties: {
       query: {
         type: 'string',
-        description: 'The search query',
+        description: {
+          en: 'The search query',
+          zh: '搜索查询词',
+        },
       },
       limit: {
         type: 'number',
-        description: 'Maximum number of results (default: 5)',
+        description: {
+          en: 'Maximum number of results (default: 5)',
+          zh: '最多返回结果数（默认 5）',
+        },
       },
     },
     required: ['query'],