hanafubuki-agent

工具

模型可以使用的工具:命令和终端、文件读写和补丁、网页搜索和抓取、子代理,以及工作区目录和 AGENTS.md。

模型通过工具完成工作。每个工具来自一个插件,可以用 disabledPlugins 整个关闭(见配置参考)。哪些工具需要审批见权限与审批。

插件工具
executionexec_command、write_stdin、resize_execution
workspace-fsread_file、list_directory、search_text、apply_patch、move_path、delete_path
webweb_search、fetch_web_page
view-imageview_image(只在模型接受图片时提供)
mcpMCP 服务器的工具,以及 list_mcp_resources、list_mcp_resource_templates、read_mcp_resource
skillsskills_list、skills_read、enable_skill、disable_skill
memorylist_agent_memories、search_agent_memories、read_agent_memory、append_agent_memory_note(启用记忆时)
goalget_goal、create_goal、update_goal
subagentsspawn_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)
Windowspwsh(没有时用 powershell),输出为 UTF-8;也可以选择 cmd.exe,或 Git for Windows、MSYS2 的 bash

shell 有七个取值。posix 和 power_shell 是平台的自动选择,各自带有回退;四个具体名字只运行它自己,不会换成同类的另一个:

shell运行
posixbash,没有时用 sh(Linux、macOS 与 Windows 相同)
bash只用 bash;没有它时不运行任何东西,并说明原因
sh只用 sh
power_shellpwsh,没有时用 powershell
pwsh只用 pwsh,不会换成 powershell
powershell只用 Windows PowerShell,不会换成 pwsh
cmdcmd.exe
  • Windows 上的 POSIX Shell:模型要求时(shell: "posix"、"bash" 或 "sh"),命令在 Git for Windows 或 MSYS2 的 bash(没有时用 sh)中运行,默认以登录 Shell 运行(-lc),与 Linux 上相同;默认的 Shell 仍是 PowerShell。posix 每一步都先找 bash 再找 sh,而 bash 或 sh 只找它自己那一个名字。按以下顺序查找:

    1. Agent 本身运行在 MSYS2 或 Git Bash 的 Shell 中(设置了 MSYSTEM)时,通过 Agent 的 PATH 找那个环境的 Shell。
    2. 命令的 PATH 中,跳过 System32(以及 SysWOW64、Sysnative)和 WindowsApps 目录中的 bash.exe:它们启动的是 WSL,而不是本机的 Shell。
    3. %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 运行时如何处理这种路径尚未测试。
  • 长时间运行的命令:命令默认最多等待 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 代码页的程序,输出依然显示为 �。
  • 工作目录:命令在模型指定的目录中运行,相对路径从第一个工作区根目录算起;模型没有指定时,在第一个工作区根目录运行:工作目录(-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_agenttask_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_messagetarget、message运行中的子代理在下一步读到消息;空闲的子代理随下一个任务读到。不开始新回合。子代理用 target parent 给创建它的会话发消息,该会话在下一步读到,或被唤醒来读(见下);最多排队 16 条未读,第 17 条被拒绝:your parent has 16 unread messages; wait until it reads them
followup_tasktarget、message给子代理新任务:空闲时开始新回合,否则加入它正在运行的回合
wait_agenttimeout_ms(10 秒到 5 分钟,默认 30 秒)等到某个子代理结束一个回合,返回每个已结束、会话尚未得知的子代理的最终回答(或错误);没有子代理仍在工作时立即返回(None of your agents is still working.)
list_agents该会话的子代理,每个都带有状态、角色(agent_type)以及它当前运行的 provider、model 和 reasoning_effort(null 表示 Provider 的默认值),从它的会话读取,所以对它执行的 /model 会体现出来,之前一次运行的子代理也一样
interrupt_agenttarget停止子代理的回合;它仍然接受消息和任务

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 会去掉这些工具和指引。

工作区目录

工作区目录告诉模型它在哪些目录中工作,依次是:

  1. 工作目录:-C 目录,默认为当前目录;
  2. 工作目录所在的 Git 仓库根目录;
  3. 每个 --add-dir 目录。

位于前面某个目录之内的目录会被去掉。第一个目录是相对路径的基准,@ 文件提及和 /diff 也使用它。

hanafubuki-agent -C ~/src/app --add-dir ~/src/shared-lib

AGENTS.md

每个回合开始时,Agent 读取这些说明文件并交给模型:

  1. 你自己的说明:数据目录中的 AGENTS.override.md,没有时读 AGENTS.md(Linux 上是 ~/.local/share/hanafubuki-agent/AGENTS.md);
  2. 每个工作区目录中的 AGENTS.override.md,没有时读 AGENTS.md。

只读取工作区目录本身中的文件,不读取 Git 根目录和工作目录之间各级目录中的文件。所有说明合计最多 32 KiB,每组最多 16 KiB。

关闭 workspace-context 插件后,模型不再看到这些说明、工作区目录和环境信息。

内置 Web 工具还包括多引擎搜索、原生平台/专业数据源、天气、研究与缓存查询。工具目录和配置见网络搜索与研究。

本页目录