hanafubuki-agent

exec

不打开终端界面,运行一轮对话:提示词来源、输出格式、审批、退出码和脚本示例。

hanafubuki-agent exec 创建一个新会话,在其中运行一轮对话,回合结束后退出;如果回合把工作交给了子代理,则等它们完成后退出(见下)。它适合脚本、CI 和任何没有交互终端的场合。

hanafubuki-agent exec "总结这个仓库中未完成的 TODO"

每次 exec 都会创建一个新会话,并像终端界面中的会话一样保存在历史里。之后可以用 hanafubuki-agent sessions show ID 查看,或用 hanafubuki-agent resume ID 在终端界面中继续。exec 本身不能继续已有的会话。

提示词从哪里来

写法提示词
exec "文本"参数本身
exec -从标准输入读取,直到结束
exec,且标准输入不是终端从标准输入读取(管道或重定向)
exec,且标准输入是终端报错并以退出码 2 退出

从标准输入读到的内容为空时,同样以退出码 2 退出。

hanafubuki-agent exec - < task.md
{ echo "审查下面的改动,指出可能的问题:"; git diff; } | hanafubuki-agent exec -

全局选项对 exec 同样有效:--role 给会话一个角色(它的指令、模型、工具和权限模式上限;未知的角色让命令在任何回合之前以退出码 1 失败),-m 选择这个会话的模型(优先于角色的),-C 指定工作目录,--add-dir 添加工作区目录,--permission-mode 选择权限模式,-p 和 -c 调整配置。

给人看的输出

不加 --json 时,标准输出是给人阅读的回合记录:

→ exec_command
  exec_command done
· 工作区里有一个 build 目录,我先把它删掉。
→ exec_command
· approval denied: exec_command: Run Posix command in /home/me/project: rm -rf build
  exec_command failed
· 没有获准删除 build 目录,我改为……
最终的回答。
行含义
→ 工具名: 对象一次工具调用开始;对象(命令、路径等)可能没有
工具名 done/failed这次工具调用成功或失败
folded into N block(s), ~T tokens (tier K)分层压缩的一次 compress 调用折叠了部分上下文
· 文本模型的过程说明(commentary),或 exec 自己的提示
plan: 及其内容模型提出的计划(见计划模式)
没有前缀的文本模型的最终回答

每条消息在完整收到后才打印。标准错误中是会话 ID(session 3)、模型请求的重试(retrying the model request (1/3): 原因),没有正常完成的回合是如何结束的(error: the turn failed (...)、the turn was cancelled (...)),分层压缩的失败(warning: context compression failed; the turn goes on with the full history: ...),以及从 Provider 对过长请求的拒绝中学到的上下文窗口(the Provider refused the request as too long; this model's window is taken as 131072 from now on,见上下文窗口与压缩)。

模型每完成一段思考,标准错误就打印一行,如 · thought for 12s(整秒,向下取整),只有时长,没有思考内容。被回合结束打断的思考不打印这一行。思考内容可以在 --json 的事件中读取(思考)。

JSON 输出

加上 --json 后,标准输出的每一行都是一个 JSON 对象,即回合中按顺序发生的每个事件;exec 自己的提示改到标准错误。

hanafubuki-agent exec --json "列出最大的五个文件"
{
  "sessionId": 2,
  "turnId": 1,
  "generation": 1,
  "sequence": 1,
  "activity": null,
  "kind": { "type": "turn_started", "role": null }
}

回合的最后一行是 turn_completed、turn_cancelled 或 turn_failed;子代理唤醒会话的回合随后作为一组独立的事件出现,从它的 turn_started 开始(见下),没有专门的事件种类。每种事件的字段、顺序和兼容性规则见 exec --json 事件。第一行 turn_started 给出会话的角色(role,default 时为 null),即 --role 给它的角色。

审批与提问

哪些工具调用需要审批由权限模式决定;exec 用 --approve 回答这些审批:

--approve行为
deny(默认)拒绝所有审批。模型会得知被拒绝,回合继续
ask询问终端前的人:y 允许一次,s 在本会话内都允许(仅在可用时提供),其他输入拒绝
allow:工具[,工具…]列出的工具每次请求时都允许一次,其他工具一律拒绝,例如 allow:exec_command,apply_patch

ask 需要标准输入和标准错误都是终端,否则一律拒绝。每个回答都会打印一行,例如 · approval denied: exec_command: Run ...。

模型也可能向你提问(例如让你在几个方案中选择)。exec 会把问题和选项打印到标准错误,你输入选项编号回答。没有终端,或者没有给出有效回答时,exec 取消回合并以退出码 3 退出。

谨慎放行

allow: 放行的是整个工具,而不是某一条具体命令。allow:exec_command 意味着模型提出的任何命令都会执行,包括它请求在沙箱之外运行的命令。在 CI 中使用时,确保运行环境是可以丢弃的。

子代理的审批也遵循相同的 --approve 策略,无论根会话正在工作还是等待。提示会标明子代理,例如 · approval denied: sub-agent runner: exec_command: Run ...。问题也标明子代理;没有终端或有效回答时,关闭该子代理及其存活子树,并告知父会话;整个运行继续,退出结果仍取决于根会话。等待由后台事件驱动,不再定期检查状态。使用 --json 时,这些提示写到标准错误,标准输出仍是根会话的事件流。

Ctrl-C 会在退出前关闭存活的委派子树和终端,并以 130 退出。重新打开会话时,保存的更新会说明这些工作由用户关闭。

等待子代理

exec 也等待模型启动的后台终端。它会说明当前等待的工作,在终端退出、失败或超时时运行被唤醒的回合,并将最后一个回合的回答写入 -o。不会自行退出的命令会使 exec 一直等待到启动时配置的 pluginOptions.execution.commandTimeoutMinutes 到期(默认 10 分钟)。Ctrl-C 会先关闭这些后台工作,再关闭 Agent。

回合完成时,如果它创建的子代理仍在工作,exec 不会退出:它等待它们,期间不运行任何东西。其中一个结束或给会话发消息时,exec 运行为所报告内容唤醒会话的回合,像任何回合一样输出:先把每条报告作为一条说明输出(· background update: Sub-agent `counter` (agent id 2) completed: Twelve files.,使用 --json 时输出到标准错误),然后是回合本身。它一直进行,直到没有子代理在工作、也没有剩下要读的内容,然后按最后一个回合的结束方式退出,-o 写入那个回合的最终回答。

wakeOnBackgroundTasks 关闭时、回合没有完成时,以及子代理唤醒会话 100 次之后(会输出一条说明),它像以前一样在回合结束时退出。exec 等待时按 Ctrl-C 会关闭后台工作,并以 130 退出。

保存最终回答

-o FILE(--output-last-message FILE)在回合结束后把模型的最终回答写入 FILE(等待子代理之后,是最后一个回合的)。回合没有最终回答时(例如失败了),写入一个空文件。

hanafubuki-agent exec -o summary.md "用三段话总结 README"

中断

按 Ctrl-C 会取消回合,exec 等 Agent 关闭后以退出码 130 退出。再按一次 Ctrl-C 会立即退出。

退出码

退出码含义
0回合完成(等待子代理之后的最后一个回合)
1回合失败、Agent 在回合中停止,或者命令无法运行(没有 Provider、数据目录被占用等)
2命令行有误:未知选项、没有提示词、无效的 --approve 策略
3模型提出的问题无人回答,回合被取消
130回合被 Ctrl-C 中断

所有命令的退出码见退出码。

脚本示例

只取最终回答,丢掉过程:

hanafubuki-agent exec -o answer.txt "这个项目用的是什么许可证?" > /dev/null
cat answer.txt

用 jq 列出回合中调用过的工具:

hanafubuki-agent exec --json "运行测试并修复失败的用例" \
  | jq -r 'select(.kind.type == "tool_started") | .kind.name'

在 CI 中允许命令和补丁,并根据退出码处理结果:

hanafubuki-agent exec --approve allow:exec_command,apply_patch "修复 lint 报错"
case $? in
  0) echo "完成" ;;
  3) echo "模型需要人来回答问题" ;;
  *) echo "失败"; exit 1 ;;
esac

本页目录