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