数据目录
配置目录和数据目录的位置,以及数据目录中保存了什么。
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默认位置
| Linux | macOS | Windows | |
|---|---|---|---|
| 配置目录 | ~/.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.json | Agent 启动的进程组。下次启动时会清理上次遗留的进程 |
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.json | Agent 对用过的每个模型所知道的内容: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 令牌保存在系统密钥环中,不在这两个目录里。