工具是「模型能对本地做什么」的开关。所有内置工具默认关闭;只有在顶部工具栏的工具里打开后,它们才会出现在模型的工具列表中。
工具清单
| 面板名称 | 配置 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 …]用户消息送达模型,不打印进记录。 - 每次工具调用都会写入交互日志,见 监控与日志。
建议的开启顺序
从小开始:
- 文件操作:先用只读,确认模型理解工作区路径。
- 记忆 + 待办:让它记住结论、维护计划。
- 运行命令:先用
git status、ls这类只读命令。 - 运行脚本:需要管道、循环或构建时再开。
- MCP / 子智能体:按需。
不要在含有生产密钥、生产数据库或不可恢复数据的工作区里打开高权限工具。