文档核心能力

工具总览

工具是「模型能对本地做什么」的开关。所有内置工具默认关闭;只有在顶部工具栏的工具里打开后,它们才会出现在模型的工具列表中。

工具清单

面板名称 配置 id 模型看到的工具 用途 教程
文件操作 file_actions file_actions 在工作区内读写/搜索/patch/改名/删除文件(含 .data) 文件与命令
运行命令 run_cmd run_cmd 直接运行单个程序或工作区脚本(不经 shell);维护 .data/scripts 文件与命令
运行脚本 run_shell run_shell 运行 PowerShell/Bash 脚本,含后台 serve 文件与命令
计算器 calculator calculator 计算表达式:四则、幂、括号、阶乘、位运算、函数与常量 —
记忆 memory memory 四个作用域:session / user / repo / evolution 记忆待办与定时器
待办 todo_list(别名 todo) todos 会话级计划与进度 记忆待办与定时器
定时器 timer timer_set / timer_list / timer_cancel 稍后恢复对话 记忆待办与定时器

状态存在 config.selected_tools;改动对下一次请求生效,不需要重启。

工具边界

三个执行类工具的边界是刻意不同的:

工具 能到哪 怎么审计
file_actions 只在工作区根目录内,包括隐藏的 .data。唯一例外是工作区数据库(.data/chat.db),不可修改。 路径沙箱:工作区外的绝对路径、../ 越界、软链越界都会被拒绝
run_cmd 第一个词先按工作区脚本库 .data/scripts(裸名)解析,再按 PATH 解析(python、python3、git …)。绝对/相对路径会被拒绝。 风险评估 L0–L6、L0–L3 需确认、危险脚本按内容审批、技能 allowed-commands 并集
run_shell 任意位置:脚本从工作区启动,但可以 cd 出去执行任何东西。shell 在构建时固定,schema 里带宿主系统信息。 风险评估 L0–L6、L0–L3 需确认、语法闸门

见 文件与命令 与 安全与边界。

后台工具任务

开启设置 → 运行时与调试 → 后台执行(config.background_tools)后,慢工具可以接受 run_in_background: true:

工具 后台形式 行为
run_cmd 任意调用 程序通过带超时的 runner 独立运行(默认 600 秒)
run_shell 仅 run_type: "direct" serve 本身已有生命周期
file_actions 仅 action: "search" 并行遍历会轮询任务的取消标记
MCP 工具 任意调用 stdio 服务器拿到独立短命进程,共享池不会被堵住
call_subagent 任意调用 子智能体运行时主智能体继续干活

行为细节:

  • 调用立即返回一个带 bg-… id 的占位结果,模型可以继续工作,而不是卡在慢构建、搜索或 MCP 往返上。
  • 真实输出会在模型下一次请求前以 user 消息([BACKGROUND TASK RESULT …])送达,并保存在助手消息行上,重载后仍在,像轮内更新一样回放。
  • 如果模型想在有任务未结时收尾,这一轮会被挂住(最多 3 轮 × 120 秒,之后剩余任务被取消)。
  • 模型用 background_task 管理任务:list(运行中与已完成,带耗时)、wait(阻塞到结束,可用 timeout_seconds)、get(完整结果)、cancel(task_id 或 "all")。
  • 记录里把运行/等待中的任务和 serve 进程收进回复末尾一张可折叠的后台卡片,带中止/停止按钮;结果交给模型,不打印进记录。
  • 任务是按轮的:停止或这一轮结束时,所有取消标记被置位,各 runner 杀掉自己的进程树;应用退出由进程守卫覆盖。

后台任务保留所有正常检查:风险评估与确认仍在任务启动前发生,被取消的任务不再等待确认对话框。子智能体永远拿不到这个标记。

并行工具调用

一轮回复里模型可以给出多个工具调用。工具侧边栏底部的“并行工具调用”(config.parallel_tools,默认开启)决定它们是否同时执行:

  • 同时执行:file_actions 的 read / list / search / diff、run_cmd、run_shell、calculator、skill_read、call_subagent,以及所有 MCP 工具。它们的执行时间从"逐个相加"变成"取最慢的那个"。
  • 独占执行(按模型给出的顺序,并把这一轮切成若干段):use_skill(会改变本轮后续调用看到的允许命令与技能目录)、memory / todos / timer_*(会话文件的读改写)、写/改/删/重命名类的 file_actions、background_task、mcp_self、skill_merge、experience、任务板工具,以及任何本应用不认识的工具。
  • 单轮并发数(config.max_parallel_tools,默认 4,范围 1–8):一次最多同时跑几个独立调用。设为 1 等于关闭该开关,回到严格逐个执行。
  • 子智能体用同一套规则,另外把 mbus 和所有 MCP 调用作为独占段(MCP 会独占该任务的 AgentMcpSession)。
  • 顺序不变:工具结果、失败计数和记录里的行始终按模型给出的顺序排列,与完成先后无关。停止按钮仍等当前批次结束后退出。
  • 一处行为变化:同一批里某个工具因连续失败被禁用时,旁边的调用已经发出去了,不会被拦下——禁用只对下一批生效。

自我进化模式强制打开两个工具

设置 → 工作区与配置 → 启用自我进化模式不只是解锁技能目录——它还强制打开 file_actions 与 memory:

  • 工具面板里这两个开关显示为锁定状态(勾选、变灰、标记为必需);
  • 后端强制同一不变式(AppConfig::effective_tools()),所以工具面板、配置方案、备份恢复或手改 config.json 都关不掉;
  • 即使还没有启用任何技能也会提供 use_skill,助手刚写好的技能可以在同一轮内加载;
  • 模型还会拿到 mcp_self(见 MCP服务器)和专用的 evolution 记忆作用域。

关闭该模式不会改动选择——这两个工具只是重新变回可选。

自动注入的工具

这些不由工具面板控制,取决于上下文:

工具 出现条件
use_skill 会话有已启用技能,或自我进化模式开着
skill_read 有已启用/已加载的技能目录可访问
call_subagent 智能体 → 子智能体系统开着且至少启用一个子智能体(自动规划另有开关)
MCP 工具 MCP 里至少启用一个服务器;名字来自服务器
mcp_self 自我进化模式开着——搭建/注册/启动助手自己的 MCP 服务器
todos 待办工具已启用
timer_* 定时器工具已启用
background_task 设置 → 运行时与调试 → 后台执行开着(管理 run_in_background 任务)

子智能体拿到的是它 allowed_tools 授予的工具,减去 timer(那是稍后恢复对话的会话工具)。每个 llm 子智能体一开始就带共享的 memory 工具(面板里提供,可以按智能体取消勾选):session 作用域以主对话的 session id 为键,user / repo 是工作区文件,所以任务能查主智能体已经学到的东西。自我进化模式下子智能体还会被强制打开 file_actions 与 memory——它可能要进化技能,也必须记得自己学过什么。mcp_self 从不交给子智能体。

轮次预算与失败工具

设置 → 高级限制单轮消耗(两者 0 = 不限):

字段 默认 含义
main_agent_max_rounds 40 每轮请求数
main_agent_max_tool_calls 120 每轮工具调用数

额度用完后这一轮不会半路死掉:追加一个上下文预算标记,然后发出一次收尾请求,工具列表不变但禁止使用工具,让模型基于已收集的信息作答。这一轮的最终回合里的工具调用会被告知无法执行而不是真的执行。

字段 默认 含义
tool_failure_limit 3 连续失败多少次后,该工具在本次会话内被禁用

计数器按会话、按工具;一次成功即重置。被禁用的工具在下一轮之前仍会声明(提示词前缀与其缓存保持稳定),但调用会被拒绝并说明原因;下一轮或改动上限后会重新出现在请求里。这个守卫在主智能体、子智能体与主智能体助手之间共享,所以某个工具不会在并行任务里反复失败。

风险等级 L0–L6

run_cmd 与 run_shell 在执行前做静态风险评估,得到 0–100 分,映射成七级:

等级 分数 含义 确认
L0 ≥ 85 系统风险;可能破坏系统文件/引导/服务 需要(dangerous)
L1 70–84 修改系统配置或系统软件 需要(system_config)
L2 55–69 安装/卸载/修改用户软件 需要(user_software)
L3 40–54 修改或删除用户数据 需要(user_data)
L4 25–39 敏感读取(配置、密钥、日志) 不需要;执行并记录
L5 10–24 一般查询/只读状态 不需要
L6 0–9 已知安全/只读 不需要

分数是静态启发式,不是沙箱。命令仍以你的用户权限执行。

确认流程

L0–L3 会触发前端确认:

  • 对话框显示风险等级、分数、命中的规则与扣分项。
  • 选择允许或拒绝。
  • 等待超过 120 秒视为拒绝。
  • 拒绝会返回 ⛔ Execution rejected by user,模型能看到原因。
  • 部分命令在工具调用卡片里显示内联的允许/拒绝行,而不是弹窗。

自动接受

工具 → 自动接受模式可以跳过确认:

选项 含义
危险命令(L0) 跳过 L0 确认
系统配置变更(L1) 跳过 L1 确认
用户软件变更(L2) 跳过 L2 确认
用户数据变更(L3) 跳过 L3 确认
全部自动接受 存入 "*" 通配符;跳过现在与将来所有确认类型

存在 config.auto_accept_confirm_kinds。"*" 也覆盖 external_agent。

cli / cloud 子智能体的审批不在这个面板,而在智能体面板里按智能体用需要批准控制,每个应用会话一次。

自动接受只跳过对话框,不跳过风险评估、路径检查、技能命令白名单与日志记录。

工具输出与界面

  • 工具调用会归并成「已完成 N 次工具调用」卡片;展开可见每一步的输入/输出/耗时。
  • 超大工具结果保留前 6000 字符 + 后 2000 字符,中间有截断标记。模型可以再读一个更小的范围。
  • todos 的改动会实时镜像到助手消息里的待办卡片。
  • run_shell 的 serve 进程出现在记录的后台卡片里,带 pid、运行时长与停止按钮。它们只活在发起它们的这一轮:轮结束时应用停掉所有进程树、校验退出码并记录结果。
  • 后台工具任务(run_in_background)与 serve 进程都收在回复末尾的后台卡片里,各自带中止/停止按钮;结果以 [BACKGROUND TASK RESULT …] 用户消息送达模型,不打印进记录。
  • 每次工具调用都会写入交互日志,见 监控与日志。

建议的开启顺序

从小开始:

  1. 文件操作:先用只读,确认模型理解工作区路径。
  2. 记忆 + 待办:让它记住结论、维护计划。
  3. 运行命令:先用 git status、ls 这类只读命令。
  4. 运行脚本:需要管道、循环或构建时再开。
  5. MCP / 子智能体:按需。

不要在含有生产密钥、生产数据库或不可恢复数据的工作区里打开高权限工具。

相关页面

源文件: docs/wiki/zh/tools-overview.md ↗ · 文档版本 v3.3.3