hanafubuki-agent

数据目录

配置目录和数据目录的位置,以及数据目录中保存了什么。

Agent 使用两个目录:配置目录保存三个配置文件,数据目录保存会话历史、记忆、Skill 和日志。hanafubuki-agent config path 打印当前使用的位置:

config    /home/me/.config/hanafubuki-agent/config.toml
providers /home/me/.config/hanafubuki-agent/providers.toml
mcp       /home/me/.config/hanafubuki-agent/mcp.toml
data      /home/me/.local/share/hanafubuki-agent
log       /home/me/.local/share/hanafubuki-agent/logs/hanafubuki-agent.log

默认位置

LinuxmacOSWindows
配置目录~/.config/hanafubuki-agent/~/Library/Application Support/hanafubuki-agent/%APPDATA%\hanafubuki-agent\
数据目录~/.local/share/hanafubuki-agent/与配置目录相同与配置目录相同

Linux 上的位置遵循 $XDG_CONFIG_HOME 和 $XDG_DATA_HOME。

  • HANAFUBUKI_AGENT_HOME 设置后,用这一个目录同时代替两者,配置文件和数据并排放在其中。
  • --data-dir 目录 只代替数据目录。

两者的相对路径都相对于当前目录解析。

数据目录里有什么

路径内容
history/会话历史:index.sqlite3 索引,active/ 和 archived/ 中的会话记录,attachments/ 中的附件和 decompress 导出,trash/ 是删除过程中的暂存
memory/记忆:memory.sqlite3 及其工作目录
skills/Skill:system/ 中的内置 Skill,packages/ 中安装的 Skill,state.json 记录启用状态
logs/hanafubuki-agent.log日志文件,超过 8 MiB 时轮换,保留 .log.1 到 .log.3 三个旧文件
themes/自定义的语法高亮主题,名字.tmTheme,由你添加;Agent 不会创建这个目录
start-marker.json记录未正常结束的启动次数,用于发现反复崩溃
crash-record.json最近一次崩溃的记录
process-groups.jsonAgent 启动的进程组。下次启动时会清理上次遗留的进程
worktrees/Agent 创建的 Git 工作树,每个是 <仓库>-<id>,一个分离的检出;它所属的会话记录在它的 Git 元数据中(仓库里该工作树自己的 HEAD 旁的 hanafubuki-agent-owner.json),随它一起删除
tui-state.json指挥中心置顶和隐藏的会话,以及每个会话上次显示的时间,由终端界面保存;不认识的键原样保留,无法读取的条目会被略去,并在下次写入前把文件移到 .recovery/,不是 JSON 对象的文件会立即移到那里,存在但无法读取的文件永远不会被覆盖
update-check.json终端界面的更新检查上次询问 GitHub 的时间(checkedAtMs)、找到的最新稳定版本(latestVersion),以及更新提示被要求跳过的版本(dismissedVersion),由命令行保存;不认识的键原样保留,无法读取的字段会被略去,并在下次写入前把文件移到 .recovery/,不是 JSON 对象的文件会立即移到那里,存在但无法读取的文件永远不会被覆盖(也不进行检查)
hooks-state.json你信任了哪些钩子(每个钩子定义的哈希),关闭了哪些;无法读取的文件会被移到一旁,所有钩子重新变为不信任
model-metadata.jsonAgent 对用过的每个模型所知道的内容:Provider 的模型列表报告的上下文窗口、最大输出、图片输入和推理,以及从拒绝中学到的内容(图片输入、更小的上下文窗口、不接受推理参数、请求结构化回答的方式,保留 7 天,除非被遗忘:providers forget、/model forget);打开 modelMetadata.modelsDev 时还有 models.dev 目录的副本,使用一周(遗忘时保留,关闭时丢弃);无法读取的文件会被移到一旁,在下一次列出模型之前什么都不知道
plugins/已安装的插件:每个包在 cache/<市场>/<插件>/<版本>/ 中,它自己的数据在 data/ 中(卸载时保留;也是它的代码的工作目录),你添加的 git 市场在 marketplaces/ 中,install.json 记录每个包的版本、来源、内容哈希以及你授予其代码的权限,linked.json 记录每个已链接插件的目录和授权(已链接的插件只有它的条目;旧版本重写 install.json 不会碰它);无法读取的记录文件会被移到 plugins/.recovery/,包仍然保持安装;读取时略去了某个条目或字段的记录文件,会在商店下次写入它之前复制到那里;存在却无法打开的记录文件(例如权限不足)永远不会被覆盖:在它能打开之前,对插件的更改都会失败
.lock数据目录锁

所有文件都是在需要时才创建的。

多个 Agent 同时运行

多个 Agent 进程可以共用数据目录,同时运行不同会话。每个会话只允许一个实例写入:要继续另一个实例拥有的会话,需要先关闭该实例。恢复会跳过活动拥有者,并保留对中断运行的恢复。锁由操作系统持有,进程结束(包括崩溃)时自动释放,不要手动删除锁文件。仍持有目录独占锁的旧版 Agent 必须先退出,新版实例才能启动。

需要隔离历史和记忆存储时,可以指定不同的数据目录:

hanafubuki-agent --data-dir ~/agent-data/review exec "审查这次改动"

备份与迁移

退出所有 Agent 进程后,复制配置目录和数据目录即可备份或迁移到另一台机器。注意:

  • providers.toml 和 mcp.toml 包含 API 令牌等凭据。
  • MCP 服务器的 OAuth 令牌保存在系统密钥环中,不在这两个目录里。

本页目录