工具
模型可以使用的工具:命令和终端、文件读写和补丁、网页搜索和抓取、子代理,以及工作区目录和 AGENTS.md。
模型通过工具完成工作。每个工具来自一个插件,可以用 disabledPlugins 整个关闭(见配置参考)。哪些工具需要审批见权限与审批。
| 插件 | 工具 |
|---|---|
execution | exec_command、write_stdin、resize_execution |
workspace-fs | read_file、list_directory、search_text、apply_patch、move_path、delete_path |
web | web_search、fetch_web_page |
view-image | view_image(只在模型接受图片时提供) |
mcp | MCP 服务器的工具,以及 list_mcp_resources、list_mcp_resource_templates、read_mcp_resource |
skills | skills_list、skills_read、enable_skill、disable_skill |
memory | list_agent_memories、search_agent_memories、read_agent_memory、append_agent_memory_note(启用记忆时) |
goal | get_goal、create_goal、update_goal |
subagents | spawn_agent、send_message、followup_task、wait_agent、list_agents、interrupt_agent |
另外有几个总是存在的工具:update_plan(更新任务计划)、request_user_input(向你提问)、new_context(开始新的上下文窗口),以及在有延迟提供的工具时出现的 search_tools 和 tool_list。
工具发现
tool_list 让模型浏览延迟工具的名称,不加载它们的说明或 schema,也不启用它们。它按名称排序,分页返回当前步骤可用的延迟工具。隐藏或不允许使用的工具不会列出。
所有参数均可省略:source 是精确的提供者 ID(例如 mcp.rea;可用来源列在 search_tools 的说明中),offset 默认为 0,limit 默认为 50,超出 1–50 的值会收敛到这个范围。省略 source 时跨提供者列举。例如,模型可以用以下参数调用 tool_list:
{ "source": "mcp.rea", "offset": 0, "limit": 50 }结果包含 tools(只有名称)、total(匹配的工具总数)和 next_offset(下一页偏移量,末页为 null)。未知来源或超出末尾的偏移量返回空页。分页反映当前步骤的目录;连接或禁用服务器会改变目录。
找到名称后,模型用精确名称调用普通函数 search_tools,只获取该工具的定义(含输入 schema),并在下一次请求中启用它。其他查询使用 BM25 搜索元数据。三种协议都提供这个普通函数,Responses 还保留原生 tool_search,使用不同名称以避免工具声明重名。之后模型即可调用所选工具。仅列举不会授予调用权限。Responses、Chat Completions 和 Anthropic Messages 均支持此流程;MCP 的资源列举工具列出的是资源,不是工具。
命令和终端
exec_command 在 Shell 中运行一条命令:
只有 cmd 是必填的:shell、login、tty、yield_time_ms、max_output_bytes、workdir、sandbox_permissions 和 justification 都可以省略,省略与给 null 取同一个默认值(平台自己的 Shell、不分配 PTY、等待 10000 毫秒等)。
| 系统 | Shell |
|---|---|
| Linux、macOS | /bin/bash(没有时用 /bin/sh),默认以登录 Shell 运行(-lc) |
| Windows | pwsh(没有时用 powershell),输出为 UTF-8;也可以选择 cmd.exe,或 Git for Windows、MSYS2 的 bash |
shell 有七个取值。posix 和 power_shell 是平台的自动选择,各自带有回退;四个具体名字只运行它自己,不会换成同类的另一个:
shell | 运行 |
|---|---|
posix | bash,没有时用 sh(Linux、macOS 与 Windows 相同) |
bash | 只用 bash;没有它时不运行任何东西,并说明原因 |
sh | 只用 sh |
power_shell | pwsh,没有时用 powershell |
pwsh | 只用 pwsh,不会换成 powershell |
powershell | 只用 Windows PowerShell,不会换成 pwsh |
cmd | cmd.exe |
-
Windows 上的 POSIX Shell:模型要求时(
shell: "posix"、"bash"或"sh"),命令在 Git for Windows 或 MSYS2 的 bash(没有时用sh)中运行,默认以登录 Shell 运行(-lc),与 Linux 上相同;默认的 Shell 仍是 PowerShell。posix每一步都先找 bash 再找sh,而bash或sh只找它自己那一个名字。按以下顺序查找:- Agent 本身运行在 MSYS2 或 Git Bash 的 Shell 中(设置了
MSYSTEM)时,通过 Agent 的PATH找那个环境的 Shell。 - 命令的
PATH中,跳过System32(以及SysWOW64、Sysnative)和WindowsApps目录中的bash.exe:它们启动的是 WSL,而不是本机的 Shell。 %ProgramFiles%\Git、%ProgramFiles(x86)%\Git、%LOCALAPPDATA%\Programs\Git和%SystemDrive%\msys64下的usr\bin。
Git for Windows 的
bin\bash.exe只是把它的usr\bin\bash.exe作为自己的子进程启动,因此改为直接运行后者:停止命令时结束的就是 Shell 本身。找不到 Shell 时命令不会运行,模型会得知查找过的位置,以及可以改用power_shell。这种 Shell 得到的环境变量见环境变量。- 基于 MSYS 运行时的程序自己拆分命令行,方式与其他 Windows 程序不同,因此命令行中的脚本按它的规则书写:没有空格或制表符的脚本前面加一个空格,不在
"前面的每一串反斜杠加倍。审批显示的是原样的脚本;审批绑定的命令行是改写后的那一个。 - 该运行时会把超过 8186 个字符的命令行参数不加提示地截断(在 Git for Windows 和 MSYS2 的运行时上、用基本多文种平面内的文本测得),因此超过 8000 个 UTF-16 单元(对大多数文本来说即字符)的脚本会被拒绝:模型会被告知把脚本写入文件再运行,或改用
power_shell。 - 它无法在 Windows 沙箱中启动:在沙箱的受限令牌下,MSYS 运行时会以
couldn't create signal pipe, Win32 error 5退出。 - 超过 247 字节的工作目录以 verbatim 形式(
\\?\)交给 Windows;MSYS 运行时如何处理这种路径尚未测试。
- Agent 本身运行在 MSYS2 或 Git Bash 的 Shell 中(设置了
-
长时间运行的命令:命令默认最多等待 10 秒(模型可以要求最多 30 秒)。到时还没结束的命令继续在后台运行,模型用
write_stdin读取后续输出或向它输入。 -
交互式终端:模型可以要求在伪终端(PTY)中运行,此时可以输入任意内容,并用
resize_execution调整大小;普通模式下只能发送 Ctrl-C。 -
输出:每次调用返回自上一次以来的输出,最多到模型指定的上限(
max_output_bytes:默认 64 KiB,最多 256 KiB)。无论上限是多少,一个会话都为这些调用保留它最新的 4 MiB 输出。- 超过上限时,调用返回输出的开头和结尾,各自在换行处截断,中间是一行
[… N bytes omitted …],并标明truncated;之后从末尾接着读。落后超过 4 MiB 的调用会先得到这个标记(写明错过了多少),再得到最新的输出。会话保留的字节中,没有标记就不会省略任何内容,也不会有两行粘在一起。 - 转义序列被去掉;回车、退格、行内的光标移动和擦除按单元格应用,宽字符(中日韩文字)占两格,所以进度行只留下最后的状态。被调用末尾截断的序列由下一次调用完整读取。模型读到的是这样的纯文本;输出中 SGR 序列的颜色和属性另外保存在一旁,只供显示使用(终端界面的命令输出),从不出现在模型读到的内容、历史中的工具输出或导出中。
- 在伪终端中,输出按 PTY 的大小(连同它的每次调整)在一个终端屏幕(
vt100)上重放:每次调用返回自上一次以来滚出屏幕的行,然后是屏幕上从第一行有变化的行起的各行,因此重绘(尤其是 ConPTY 的)、进度条、光标移动和擦除都落在终端会显示的位置。仍在书写中的一行(例如提示符)在有内容追加时会完整地再出现一次。和终端一样,在程序设置的滚动区域内滚动的行不会保留,调整大小也不会让已写出的行重新换行。终端界面中运行中命令的预览也以同样方式读取屏幕。
- 超过上限时,调用返回输出的开头和结尾,各自在换行处截断,中间是一行
-
时限:每个进程(包括后台终端的)在命令超时后被停止:默认 10 分钟,可由
pluginOptions.execution.commandTimeoutMinutes设为 1 到 1440 分钟(一天),在设置中心的 Plugins 标签页(/config pluginOptions.execution)、config set或config.toml中设置。更改作用于此后启动的命令;正在运行的命令保留启动时的超时,什么都不会重启。工具 10 分钟没有进展也会被停止。 -
沙箱:命令在会话的沙箱中运行:Linux 和 macOS 上默认只能写入工作区根目录和临时目录,不能使用网络;需要这台机器无法提供的沙箱的命令不会运行。
-
在沙箱之外运行:和 Codex 一样,模型可以请求在沙箱之外运行一条命令,参数是
sandbox_permissions("use_default",即默认值,或"require_escalated")和justification(随审批显示的一个问题,最多 1024 字节;只能和"require_escalated"一起使用,否则是模型会读到的错误)。这样的命令需要单独的审批,完全访问模式永远不会给出;见权限。 -
环境:命令继承 Agent 的环境,并应用非交互默认值和显式代理覆盖,见环境变量。
-
文本编码:输出以 UTF-8 交给模型。
- PowerShell(5.1 和 7 都一样)开始时把控制台的输出和输入代码页,以及它通过管道传给程序的文本的编码(
$OutputEncoding,5.1 中默认是 ASCII)设为不带字节顺序标记的 UTF-8,并关闭进度条($ProgressPreference = 'SilentlyContinue')。 cmd.exe先运行chcp 65001,因此它启动的、遵循控制台代码页的程序写出 UTF-8。它自己的内置命令(dir、echo、type)写入管道时仍使用cmd.exe启动时的代码页,即控制台的(OEM)代码页;在伪终端中,或从 PowerShell 中以cmd /c …运行时,它们的输出完整无误。- Python 写出 UTF-8(
PYTHONUTF8=1、PYTHONIOENCODING=utf-8)。 - 程序仍然用其他编码写出的内容会分段解码,因此同一段输出中可以混有多种编码:ASCII 原样保留,其余字节的每一段若是 UTF-8 就保持不变,否则按 Windows 的 ANSI 代码页读取(中文 Windows 上是 936,即 GBK;西文 Windows 上是 1252)。Linux 和 macOS 没有这样的后备编码,因为命令得到
LANG=C.UTF-8:不是 UTF-8 的字节显示为�。 - 后备编码是 ANSI 代码页,而不是控制台的(OEM)代码页。中文、日文和韩文 Windows 上两者相同(936、932、949、950),因此在那里
cmd.exe的内置命令能被正确读取。其他 Windows 上两者不同(1252 和 437 或 850,1251 和 866,1253 和 737):遵循控制台代码页的程序在chcp 65001或 PowerShell 的设置之后写出 UTF-8,但cmd.exe自己的内置命令写入管道的非 ASCII 文本会按错误的代码页读取。 - 在伪终端中,Windows 的控制台主机自己把程序写出的内容转换为 UTF-8,按控制台代码页(即 UTF-8)读取:在那里仍然写出 ANSI 代码页的程序,输出依然显示为
�。
- PowerShell(5.1 和 7 都一样)开始时把控制台的输出和输入代码页,以及它通过管道传给程序的文本的编码(
-
工作目录:命令在模型指定的目录中运行,相对路径从第一个工作区根目录算起;模型没有指定时,在第一个工作区根目录运行:工作目录(
-C),或 Agent 运行时改到的那个目录。 -
清理:Agent 记录它启动的进程组,关闭时结束它们;崩溃后,下次启动时会清理遗留的进程。
终端界面中,运行中的命令显示为 • Running ...,并流式显示它的输出(工具调用);exec --json 中是 execution_progress 事件。
在评审中只运行普通的 git --no-pager 读取命令;见权限。
后台终端的退出、失败或超时会在 wakeOnBackgroundTasks 打开时排入更新,包含退出码、运行时间和末尾输出:正在运行的回合在下一步读到它,等待中的会话则由新回合唤醒。轮询如果已报告结束,会撤回待交付的更新,避免重复报告。! 命令和取消不会产生终端结束更新。
文件
| 工具 | 作用 |
|---|---|
read_file | 读取文件,按页读取,每页最多 256 KiB |
list_directory | 列出目录 |
search_text | 用正则表达式在目录或单个文件中搜索文本,遵循 .gitignore 等忽略规则 |
apply_patch | 以补丁的形式创建、修改和删除文件 |
move_path | 移动或重命名 |
delete_path | 删除文件或目录 |
- 相对路径相对于第一个工作区目录。
apply_patch的Add File和Move to会自动创建缺失的父目录,支持多层嵌套。创建目录属于已批准的补丁操作;准备和审批阶段不会创建目录。写入仍按单个文件保证原子性,整个补丁不是事务;取消或 I/O 失败可能留下已经创建的目录。- 读取不受工作区目录限制;写入、移动和删除在任何位置都需要审批,涉及工作区目录以外的路径时风险等级为严重,并在摘要中列出这些路径。
read_file按字节分页:offset是本页开始的位置,nextOffset是下一页开始的位置。结果还会数出本页从第几行开始,即startLine(从 1 开始),以便给读到的行编号;lineNumbers会把这些行连同各自的编号一起给出,本页的content保持不变。search_text的path可以是目录或单个文件。目录会被遍历,maxDepth限制这一遍历的深度;文件则直接搜索它本身,maxDepth对它不适用。- 终端界面中,
apply_patch的审批会显示修改的差异,结果显示它修改的文件,展开后显示差异(工具调用),各行按补丁应用的位置编号。工具在结果旁边报告这些位置,只用于显示:模型读到的仍是它修改的文件,与以前相同。
网页
web_search 搜索网页,fetch_web_page 读取一个网页的正文。两者都不需要审批。fetch_web_page 只读取公网页面,即使通过代理,也会在本机检查页面的地址(网页抓取与域名解析)。
webSearchProvider 决定使用哪个搜索服务:
| 值 | 行为 |
|---|---|
"auto"(默认) | 设置了 searxngBaseUrl 时先用 SearXNG,没有结果或失败时改用 DuckDuckGo;否则用 DuckDuckGo |
"duckduckgo" | 总是用 DuckDuckGo |
"searxng" | 总是用 SearXNG,需要设置 searxngBaseUrl |
hanafubuki-agent config set searxngBaseUrl https://searx.example.com
hanafubuki-agent config set webSearchProvider searxng- 每次搜索最多 10 条结果,结果缓存 5 分钟。
- 抓取默认返回最多 50,000 字节的正文,可以分页继续读取。最多跟随 5 次重定向,单次 20 秒。
- 抓取拒绝私有地址、本机地址和带凭据的 URL。
webFetchUseJinaReader = true时,直接抓取失败(被拒绝、超时、内容为空、类型不支持等)后改用https://r.jina.ai/读取。这会把 URL 发送给 Jina。- 网页工具使用
network.proxy,见网络与日志。
目标
goal 插件的工具操作会话的目标:
get_goal读取目标:目标内容、状态、预算、已用的 token 和时间,以及预算中剩余的 token。create_goal(objective,可选的token_budget)创建一个活动的目标。模型被告知只在你或指令要求时才创建目标;会话有未完成的目标时它会失败。update_goal(status:complete、blocked或paused)在目标达成并经过验证后把它标为完成,在同一个阻碍在三个目标回合中反复出现后标为阻塞,或按你的要求暂停。它不能恢复目标,也不能解除预算限制。
它们都不需要审批。计划模式中只提供 get_goal;在临时会话(旁路对话)中它们会失败。
子代理
模型可以把任务交给子代理:一个独立的对话,是该会话的子会话(会话),在后台运行,使用该会话的权限模式;除非 spawn_agent 的参数或子代理的角色另有规定,也使用该会话的模型和工具。这组工具来自 Codex(它的第二套多代理工具):
| 工具 | 参数 | 作用 |
|---|---|---|
spawn_agent | task_name、message、fork_turns(all/none)、agent_type、model、reasoning_effort、provider | 以可派生角色 agent_type(不带时为该会话自己的角色)、在给定的模型、推理强度和 Provider 上创建名为 task_name(小写字母、数字、下划线)的子代理,把 message 作为它的第一个回合运行;all 从当前回合之前的对话开始,none 从空白开始。返回它的任务名、ID,以及它实际使用的 Provider、模型和推理强度(null:Provider 的默认值) |
send_message | target、message | 运行中的子代理在下一步读到消息;空闲的子代理随下一个任务读到。不开始新回合。子代理用 target parent 给创建它的会话发消息,该会话在下一步读到,或被唤醒来读(见下);最多排队 16 条未读,第 17 条被拒绝:your parent has 16 unread messages; wait until it reads them |
followup_task | target、message | 给子代理新任务:空闲时开始新回合,否则加入它正在运行的回合 |
wait_agent | timeout_ms(10 秒到 5 分钟,默认 30 秒) | 等到某个子代理结束一个回合,返回每个已结束、会话尚未得知的子代理的最终回答(或错误);没有子代理仍在工作时立即返回(None of your agents is still working.) |
list_agents | 该会话的子代理,每个都带有状态、角色(agent_type)以及它当前运行的 provider、model 和 reasoning_effort(null 表示 Provider 的默认值),从它的会话读取,所以对它执行的 /model 会体现出来,之前一次运行的子代理也一样 | |
interrupt_agent | target | 停止子代理的回合;它仍然接受消息和任务 |
target 是子代理的任务名或会话 ID。
- 限制:主对话可以创建子代理,一级子代理还可以创建一级(主对话 → 子代理 → 子代理)。二级子代理、旁路对话和评审不能继续派生。默认整棵树同时最多有 8 个工作的子代理,包括正在等待自己子代理的父代理;被唤醒的回合不受这个上限拒绝。同一父会话中任务名不能重复。
list_agents只列出调用者直接创建的子代理;状态包括等待后台工作的waiting和手动关闭后的closed。 - 模型、推理强度和 Provider:每一项取
spawn_agent的参数,否则取角色的,否则取该会话自己的。provider是一个已启用 Provider 的 ID,或者在恰好只有一个已启用 Provider 使用该显示名称时(不区分大小写)是它的显示名称;只给 Provider 不给model时,沿用继承来的模型 ID。传入的值在子代理创建之前检查,被拒绝时返回指明该参数、并说明可以改传什么的错误,不会创建子代理:未启用的 Provider(错误列出已启用的);有已记录的模型列表时,该列表、它的models."<id>"设置、会话在其 Provider 上自己的模型、默认 Provider 上的默认模型都没有的模型(错误列出至多 20 个已知 ID,与所请求 ID 开头相同部分最长的排在前面),没有已记录的列表时任何模型都原样传给 Provider;在模型的推理强度档位已配置或已上报(错误列出这些档位,并标出默认值)或已知它不接受推理强度时,它不接受的推理强度;none。没有传入的推理强度从不检查,请求时会像任何会话一样收窄(推理强度与思考过程)。父会话的历史(fork_turns为all)会发往子代理所用的 Provider。后续任务在子代理自己的模型上运行;查看子代理时用/model可以更改。 - 嵌套回答:子代理结束回合时,如果它自己的子代理仍在工作,它进入
waiting,不保留运行任务。只有子树安静且排队更新已读完后,它的最终回答才发送给父会话。子代理的错误只发给直接父会话,父会话可以处理后再向上报告。 - 唤醒:
wakeOnBackgroundTasks打开时(默认,配置参考),会话不必等待它的子代理。子代理的结束(它的最终回答,截断到 32 KiB,或它的错误)和它的消息会持久地排队在该会话上。正在运行的回合在下一步读到它们,作为一条不是用户写的<background_events>更新;已经结束回合的会话被唤醒:一个新回合以这条更新开头,模型自行回应它(终端界面和exec会这样做;宿主自行决定)。一起到来的结束合成一个回合;用户的消息会先读到在它之前排队的内容。wait_agent从同一个队列取最终状态,所以每个状态只告知一次,要么由等待告知,要么由更新告知。中断(模型的interrupt_agent或用户的中断)不会被报告。用户中断会话的回合会暂停它的唤醒,直到用户的下一条消息;没有用户消息时连续 100 个被唤醒的回合也会暂停:这期间排队的内容随那条消息读到。选项关闭时,模型被告知在回答前等待子代理,不会唤醒会话,子代理也不能给它发消息;子代理的最终状态仍在它的队列中等待wait_agent,重启后也是。 - 审批:这些工具不需要审批。子代理自己的工具调用在它自己的对话中审批,使用它在每个任务开始时从该会话取得的权限模式:需要你回答的调用会在那里等待,直到你打开该子代理并回答。
- 指引:步骤提供
spawn_agent的顶层会话(不在 Plan 模式下,也不在略去这个工具的角色中)的模型还会读到协调子代理的指引(只在被要求时创建,并行运行彼此独立的步骤;唤醒打开时,与其等待不如结束回合,因为它们报告时会话会被恢复,只在需要某个结果才能继续时才调用wait_agent;唤醒关闭时,回答之前等待它们)以及可以赋予它们的角色(子代理的角色)。接着,为provider、model和reasoning_effort,它读到自己的模型,以及按 ID 和名称列出的已启用 Provider,自己的排在最前,其余按名称排序:每个 Provider 下是它已知的模型(自己的模型、models."<id>"设置、默认 Provider 上的默认模型,然后是已记录的模型列表,按 ID 排序),在已知时附上每个模型接受的推理强度并标出默认值,或者说明它不接受推理强度;没有已记录列表的 Provider 会说明任何模型 ID 都原样传给它。最多 8 个 Provider、每个 8 个模型,总共不超过 4 KiB;略去的部分会说明("… and 3 more"),并且仍然被接受。列出的一切派生时都会被接受,名称写法与派生的错误一致;令牌、请求头和 base URL 从不显示。这份列表在每一步不发请求地读取,所以 Provider 被编辑、记录到模型或档位不同的列表、模型的推理参数被其 Provider 拒绝(在保留这次拒绝的 7 天内)或/model更换,都从下一步起体现;Provider 为某个模型上报的档位在其最新列表不再包含该模型时,会在被观察到 7 天后失效,这也从下一步起体现。其他情况都不会改变它。Plan 模式下只提供wait_agent和list_agents。 - 子代理和其他会话一样:它的回合和事件在它自己的历史中,界面通过
subagents调用列出会话的子代理(嵌入 Agent)。在disabledPlugins中加入subagents会去掉这些工具和指引。
工作区目录
工作区目录告诉模型它在哪些目录中工作,依次是:
- 工作目录:
-C 目录,默认为当前目录; - 工作目录所在的 Git 仓库根目录;
- 每个
--add-dir 目录。
位于前面某个目录之内的目录会被去掉。第一个目录是相对路径的基准,@ 文件提及和 /diff 也使用它。
hanafubuki-agent -C ~/src/app --add-dir ~/src/shared-libAGENTS.md
每个回合开始时,Agent 读取这些说明文件并交给模型:
- 你自己的说明:数据目录中的
AGENTS.override.md,没有时读AGENTS.md(Linux 上是~/.local/share/hanafubuki-agent/AGENTS.md); - 每个工作区目录中的
AGENTS.override.md,没有时读AGENTS.md。
只读取工作区目录本身中的文件,不读取 Git 根目录和工作目录之间各级目录中的文件。所有说明合计最多 32 KiB,每组最多 16 KiB。
关闭 workspace-context 插件后,模型不再看到这些说明、工作区目录和环境信息。
内置 Web 工具还包括多引擎搜索、原生平台/专业数据源、天气、研究与缓存查询。工具目录和配置见网络搜索与研究。