hanafubuki-agent

会话

列出、查看、归档、删除和恢复保存在本地历史中的会话。

每一次对话都是一个会话,保存在数据目录的 history/ 中:终端界面里的对话、resume 继续的对话,以及每一次 exec。会话用一个数字 ID 标识,sessions list 会列出它们。

列出会话

hanafubuki-agent sessions list
2  2026-11-09 04:37  gpt-5.1  解释这个仓库是做什么的
1  2026-11-08 21:12  gpt-5.1  修复 lint 报错

每行依次是 ID、最后更新时间(本地时间)、模型和标题,最新的在最前面。标题由第一条消息生成:先立即用这条消息本身(截到 36 个字符),再换成模型根据它写的标题。模型没能给出时,第一条消息仍是标题,你发下一条消息时会再请模型生成,直到它给出标题或你重命名会话。还没有标题的会话显示 (untitled)。

  • --archived 列出已归档的会话,而不是正常的会话。
  • --json 每行输出一个会话摘要的 JSON 对象,包含 ID、模型、Provider、模式、标题、token 用量、创建和更新时间、创建时所在的目录和 Git 分支(cwd 和 branch)、不是 default 时的角色(role)等字段,适合脚本处理。
  • 只列出没有父会话的会话:子会话要在它的父会话下面找。

终端界面启动时还没有会话;提交第一条消息,或执行需要会话的命令时才创建。 /new 和 /clear 回到这个空白状态,不会立即分配另一个会话。其他入口创建的空会话 仍可能出现在 sessions list 中,恢复选择器会隐藏它们。

查看会话

hanafubuki-agent sessions show 2
session 2  gpt-5.1  解释这个仓库是做什么的
assistant: 这是一个……
  done
→ exec_command
thought for 3s
user: 解释这个仓库是做什么的

show 打印会话最近的 200 项记录,最新的在前:你的消息(user:,回合进行中补充的消息是 user (steering):)、模型思考了多久(thought for 3s,整秒,向下取整;不含思考内容)、模型的回答(assistant:)、工具调用(→ 工具名)及其结果(done 或 failed),你用 ! 运行的命令(user ran: 命令,没有成功时附上 (exit N) 或 (failed)),以及会话的后台工作报告的内容,每个事件一行(background: …,唤醒事件)。更早的记录不会显示,此时会先打印 (older items are not shown)。只给模型看的上下文不会显示。

--json 输出这一页记录的完整 JSON,包括每一项的全部字段,思考内容也在其中。在终端界面恢复会话时也能看到思考过程。

导出

在终端界面中,/export 把会话的完整对话以 Markdown 复制到剪贴板或保存到文件(终端界面);宿主程序调用 export_session_markdown。导出内容从历史中读取,读取全部页面,最早的在前:

# Hanafubuki Agent conversation

## User

解释这个仓库是做什么的

## Activity

    exec_command({"cmd":"ls"})
    Cargo.toml
    crates

## Assistant

这是一个……
  • 每条消息是一个 ## User 或 ## Assistant 小节,内容保持原样;回合进行中发送的消息也是 ## User,其中的图片会标出([Image #1])。模型提出的计划是 ## Plan。
  • 每次工具调用是一个 ## Activity 小节,缩进成代码块:一行工具名和参数(超过 200 个字符的部分截掉),失败时附上 · failed,然后是输出的前 10 行,以及还剩多少行。你用 ! 运行的命令(终端界面)也是一个:! 加命令,退出码不为 0 时附上 · exit N,没有运行完时附上 · failed,然后同样是它的输出。上下文压缩显示为 Context compacted。
  • 会话的后台工作(它的子代理和后台终端)报告的内容是一个 ## Background updates 小节,每个事件一行。
  • 模型的思考过程和只给模型看的上下文不会导出。没有可显示内容的会话不能导出。

归档与删除

hanafubuki-agent sessions archive 2
hanafubuki-agent sessions delete 2
  • 归档:会话从 sessions list 和恢复选择器中消失,但仍然保存,可以用 sessions list --archived 找到。它的子会话会一起归档。
  • 删除:永久删除会话及其历史,无法恢复;它的子会话不论是否已归档,都会一起删除。如果某个分叉或被隔离的会话文件仍然需要这个会话或它的某个子会话,删除会被拒绝,错误信息说明原因;只要有一个子会话不能删除,整个删除都会被拒绝。
  • 归档和删除都会关闭这个会话的旁路对话。恢复(取消归档)一个会话不会恢复它的子会话。
  • 在终端界面中,/archive 和 /delete 经确认后对当前显示的会话做同样的事,之后界面没有会话。恢复选择器按 Tab 列出归档的会话,在那里按 Ctrl+A 或 Enter 恢复其中一个;在正常列表中按 Ctrl+A 归档另一个会话(终端界面)。

编辑之前的消息

编辑你之前发过的一条消息(在终端界面中按两次 Esc;宿主使用 edit_from_turn)不会改写会话的历史:

  • 会话在这条消息开始的回合之前分叉。分叉出的会话包含这条消息之前的全部内容,把原会话记为来源(forkedFromSessionId),并拿回这条消息的文本和图片,供你编辑后发送。
  • 原会话被完整归档,连同它的子会话:sessions list --archived 可以找到它,sessions show 可以查看它。列表中由分叉出的会话取代它。
  • Agent 修改过的文件不会恢复。
  • 会话中有回合运行时会被拒绝;在子会话中也会被拒绝:旁路对话是临时的。

工作树

工作树是工作目录所在仓库的一份独立检出,由 Agent 建在数据目录的 worktrees/ 下(名为 <仓库名>-<8 位十六进制数>),处于仓库 HEAD 的分离状态。它可以属于一个会话,归属记录在工作树的 Git 元数据中。

  • 在终端界面中,/worktree 可以在新的工作树中继续当前对话(会话的一个分叉在那里继续,并拥有这个工作树),或在那里开始新对话(你的下一条消息创建的会话拥有它);在 Git 仓库中,/fork 也提供前一种选择。两者都会把工作目录切换到工作树中。见终端界面。
  • /worktree 的 Browse worktrees 列出仓库的工作树,带有提交、分支和所属会话:可以恢复工作树所属的会话、复制它的路径或删除它。
  • 删除工作树会删除它检出的文件及其本地修改,并清理仓库中关于它的记录;它所属的会话保留。工作目录所在的工作树不会被删除。
  • 会话会记录它创建时所在的目录(cwd):在工作树中创建的会话记录工作树,分叉记录来源会话的目录。
  • worktree 插件关闭(disabledPlugins)时工作树不可用,界面会说明这一点。

角色

每个会话都有一个角色:除非你用 --role 名字 开始它,或在轮次之间用 /role 名字 切换,否则是什么都不收窄的 default。角色的指令、工具、插件和权限模式上限随会话保存:之后编辑或删除角色文件不会改变已有它的会话,恢复的会话保留它原来的角色。/status 会显示它。

子会话

一个会话可以是另一个会话的子会话:它是为那个会话创建的,而不是由你直接开始的。有旁路对话、子代理和评审。子会话记录它的父会话(摘要中的 parentSessionId)和创建它的原因(origin:side、subagent 或 review),并沿用父会话的目录、模型和设置(子代理可以被指定另一个模型,见下文)。它保留父会话的角色,只能进一步收窄:子会话得到的永远不会比父会话多。子代理可以被赋予它自己的、更窄的角色(见下文)。分叉保留源会话的角色。

每个会话在创建时都会记录工作区的主目录(cwd)和该目录中检出的 Git 分支(branch,从仓库的 HEAD 读取;HEAD 处于分离状态或不在仓库中时没有分支)。子会话和分叉沿用来源会话的记录。在这些字段出现之前创建的会话没有这两项。

旁路对话

旁路对话是在某个会话旁边临时开的一段对话,用来问一个问题,而不打扰这个会话正在做的事。

  • 它从会话最近的回合边界开始,带着会话当时的全部内容:没有回合在运行时是整段对话,有回合在运行时是这个回合之前的对话,所以可以在会话工作时提问。会话的历史中至少要有一个回合。
  • 模型会被告知它处在旁路对话中:继承来的对话只供参考,不是要继续执行的指令;它回答问题、做只读的探索,除非你在旁路对话里明确要求,否则不修改文件、工作区或设置。
  • 它是临时的:只保存在内存中,从不写入历史,也不会被列出;关闭它、归档或删除它所属的会话、或 Agent 停止时,它就消失了。它的记录从旁路对话开始,不包含继承来的历史。
  • 一个会话最多只有一个旁路对话,再次打开会返回已经打开的那个。关闭它会停止它正在运行的回合和后台终端。
  • 在终端界面中,/side(或 /btw)打开它:Fullscreen 中是对话旁边的窗格,Scrollback 中切换到它;Esc 返回,/side close 关闭它(终端界面)。

子代理

关闭子代理会停止它及其存活后代的回合和终端,清除它们的待处理更新,并告知父会话它被用户关闭了。它仍可接收后续任务。仅中断回合会保留后台工作。

关闭或重启后,工作被中断的子代理会向父会话报告为丢失。嵌套子树丢失时,只报告一次最上层的子代理。其历史仍可用于后续任务。报告等待父会话的下一回合;启动 Agent 不会自动恢复执行。

子代理是会话的模型用 spawn_agent 创建的子会话,在后台完成一项任务(工具)。

  • 它是持久的:和任何会话一样写入历史,origin 为 subagent,标题是任务名。会话列表和其他子会话一样不列出它;列出父会话的子会话时才会列出它。
  • 它从空白开始,或者带着父会话在创建它的那个回合之前的对话开始;使用父会话下一个回合会使用的权限模式;它的回合由父会话的模型发起,而不是由你。
  • 它具有 spawn_agent 的 agent_type 指定的角色,必须是可派生的角色:它的工具是父会话的工具再按角色收窄,指令是角色的,模型和推理强度是角色的,否则是父会话的。不带 agent_type 时,它保留父会话的角色、模型和推理强度。list_agents 给出每个子代理的角色。
  • spawn_agent 的 model、reasoning_effort 和 provider 选择它的模型、推理强度和 Provider,优先于角色和父会话的,每一项都在子代理创建之前检查(工具)。使用另一个模型或 Provider 的子代理具有该模型的上下文窗口和图片输入能力,并在它的各个任务之间以及重启之后保留它的模型。
  • 它的结束(最终回答或错误)以及它发给父会话的消息(send_message 发往 parent)会持久地排队在父会话上:wakeOnBackgroundTasks 打开时,父会话正在运行的回合在下一步读到它们,已经结束回合的父会话被唤醒来读(工具)。父会话的 wait_agent 从同一个队列取它的最终状态,重启后也是。
  • 归档或删除父会话时,它的子代理随之归档或删除。
  • 主对话之下可以嵌套两级子代理;旁路对话和评审不能派生。默认整棵树最多有 8 个工作的子代理([pluginOptions.subagents] 的 maximumRunningAgents),包括等待自己子代理的父代理。等待中的子代理由它的子代理唤醒;这些工作和排队的更新处理完后,才把回答发给父会话。
  • 在终端界面中,/subagents 列出子代理及其状态、模型和推理强度,并用其中一个代替它的父会话显示,运行时实时更新;在 Manual 模式下,子代理等待的审批显示在它的父会话中,标有子代理的标题,回答发给子代理(终端界面)。/agents(或在空输入框上按 Left)列出所有没有父会话的会话,每个会话的状态汇总了它的子会话的状态(等待审批的子代理会让父会话显示为 Needs input),可以打开、分叉、重命名、停止、归档或删除它们(终端界面)。

评审

评审是一个子会话,它评审会话所在仓库中的改动,并把发现报告给会话:门面的 start_review(嵌入 Agent),即 Codex 的 /review。

  • 评审什么:未提交的改动(已暂存、未暂存和未跟踪的文件)、相对一个基础分支的改动(从 HEAD 与该分支的合并基础起,评审会拿到它)、一个提交,或你自己的要求。review_targets 列出工作目录的分支、当前分支和最近 100 个提交供选择。
  • 它是持久的,origin 为 review,标题为 Review: <目标>,从空开始:不带会话对话的任何内容,第一条消息只有对该目标的请求。它用会话的模型,不论会话处于什么模式都在默认模式下运行,并会看到 Codex 的评审准则,准则要求以 JSON 给出发现(标题、正文、置信度、优先级、文件和行,以及总体结论)。
  • 它是只读的(权限):读取文件并运行普通的 git --no-pager 读取命令;其他需要审批的操作不经询问直接拒绝。
  • 它运行一个回合,最终回答被读作发现:不是该 JSON 的回答整体保留为说明,读不出的单条发现被略去。随后会话会被告知评审的发现,或评审被中断(cancel_review)或失败,作为它的模型在下一回合读到的上下文。如果那时会话正在运行回合,这条说明会等回合结束。
  • 会话必须已经有过一个回合:历史从回合开始,没有回合的会话无法被告知结果,对它的评审会被拒绝。
  • 归档或删除会话时,它的评审一同被归档或删除。
  • 在终端界面中:/review 选择评审目标,显示正在运行的评审(Esc 取消),然后显示结论和发现(终端界面)。

目标

会话可以有一个目标:它在一次回答之外持续推进的任务,直到目标完成或预算用尽。

  • 设置目标。 你通过门面(set_goal)或终端界面的 /goal 设置目标,或者让模型设置,它会调用 create_goal(工具)。你设置的目标替换会话现有的目标,用量从头计算;模型只能在会话没有目标或目标已完成时创建目标。目标内容最多 4,000 个字符(更长的会被拒绝:把说明写进文件,在目标里写明文件),目标可以有 token 预算和时间预算。
  • 如何持续推进。 目标处于 active 时,以最终回答结束的回合会继续下去:每个最终回答之后,模型都会被告知继续推进目标,直到它把目标标为 complete 或 blocked、你暂停目标,或预算用尽。终端界面中,空闲时设置或恢复活动目标会立即提交目标内容并启动回合;回合进行中则不会重复启动。facade 的目标设置方法负责保存目标,嵌入宿主自行决定何时提交任务。计划模式的回合不会被继续。
  • 预算与用量。 目标处于活动状态时,它计入会话花费的模型 token(输入和输出,按服务商报告或估算的数量;各协议的输入都是提示总量,包含缓存读取与写入,所以在 Anthropic 上预算比 0.3 之前用得更快)和回合中花费的时间。预算用尽时目标变为 budget_limited,回合再得到一次回答,模型被告知收尾。没有预算的目标仍受每个回合自身上限的约束(每个回合的工具调用、token 和继续上下文):到达上限的回合失败,目标在下一个回合仍是活动的。
  • 状态:active、paused、blocked(模型陷入僵局,没有你就无法推进)、budget_limited 和 complete。预算用尽优先于暂停和阻塞,恢复一个预算受限的目标,它仍是预算受限的。
  • 模型看到什么。 每个回合开始时,目标在它的上下文中:作为引用数据的目标内容(引用形式超过 700 字节时省略)、谁设置的、状态和预算。你在回合运行时设置或替换的目标,会在该回合的下一个最终回答时告知模型。
  • 保存在哪里。 目标与会话的状态一起保存在历史中,所以重启后仍在,分叉保留它(包括状态和用量),归档和删除会话时随会话一起处理。子会话(旁路对话、子代理)不继承父会话的目标,临时会话不能有目标。
  • 关闭 goal 插件(disabledPlugins)时,目标工具消失,不再继续推进,目标调用不可用;已经设置的目标仍然保存着。
  • 在终端界面中:/goal 显示目标及其状态、预算和用量,并可以设置、替换、编辑、暂停、恢复和清除目标(终端界面)。

恢复会话

在终端界面中继续一个会话:

hanafubuki-agent resume 2        # 指定 ID
hanafubuki-agent resume --last   # 最近一个运行过回合的会话
hanafubuki-agent resume          # 从列表中选择

恢复后,界面会重放会话最近的 200 项记录,下一条消息接着这个会话继续。也可以在终端界面中输入 /resume 打开同样的选择器。详见终端界面。

exec 总是创建新会话,不能继续已有的会话;但 exec 创建的会话可以用 resume ID 在终端界面中继续。

注意

  • sessions 命令和 resume 可以与其他 Agent 同时启动。历史列表可共享查看;打开或修改其他实例拥有的会话时,需要先关闭拥有者。见故障排查。
  • 会话 ID 必须是数字,否则命令以退出码 2 退出。

本页目录