hanafubuki-agent

配置分层

默认值、用户文件、配置档、受信任项目的配置和 -c 覆盖如何叠加,以及选项的优先级。

config.toml 中的设置分层读取,从低到高。每一层只设置它写出的键;没写的键保留下一层的值。以安装和添加的内容为键的两个表 [plugins] 和 [marketplaces] 按条目合并:某一层的 [plugins."demo@my-mkt"] 只改变这个包中它写出的键,其他条目保持不变。[pluginOptions] 同样按插件和键合并(插件选项)。只有 config.toml 分层,providers.toml 和 mcp.toml 没有分层。

  1. 默认值
  2. 用户的 config.toml
  3. 配置档:-p 名字 选择的 [profiles.名字]
  4. 项目配置:受信任项目中的 .hanafubuki-agent/config.toml
  5. -c 键=值 覆盖,按给出的顺序;然后是 --permission-mode 和 --log-level

hanafubuki-agent config get 显示叠加后的结果,hanafubuki-agent doctor 的 config 行列出读取了哪些层。

配置档

配置档是用户 config.toml 中的一个表,可以包含任何设置的键:

[profiles.review]
permissionMode = "auto_review"
logLevel = "debug"

[profiles.offline]
disabledPlugins = ["web"]
hanafubuki-agent -p review
hanafubuki-agent -p offline exec "整理这个目录下的笔记"

选择文件中不存在的配置档会报错。配置档中的列表(如 disabledPlugins)会替换下一层的列表,而不是合并。

设置中心的配置档也提供所有内置插件和宿主插件注册的 pluginOptions.<插件>.<选项>,复用插件声明的类型、范围和密钥编辑方式,不给新配置档填入默认值。保存时先校验整批值,再一起写入;删除某个选项就恢复使用下一层的值。

表单还提供角色覆盖和已安装插件注册的设置。Configuration layers 编辑用户文件或当前项目文件,Profiles 编辑指定配置档。每个目标显示保存位置和优先级,保存后提示更高层的覆盖。已有字段损坏时显示警告,其余有效字段仍可编辑;未知字段及无关的损坏值予以保留。

终端界面的设置中心编辑配置档(Advanced 标签页中的 Profiles):a 添加一个,每个键改动时即保存,r 把它从配置档中删除,Delete 删除整个配置档,但 Agent 当前使用的那个除外。

项目配置

项目是工作目录(-C,默认为当前目录)所在的 Git 仓库根目录;不在仓库中时就是工作目录本身。项目可以有自己的配置文件 <项目>/.hanafubuki-agent/config.toml,内容与用户文件的设置相同。

项目配置只有在用户的 config.toml 信任这个项目时才会读取,因为它来自仓库,可能是别人写的:

[projects."/home/me/src/my-project"]
trustLevel = "trusted"

或者在项目目录中运行:

hanafubuki-agent config set "projects.'$PWD'.trustLevel" trusted
  • 路径按实际位置比较,而不是按文本比较:符号链接或同一目录的不同写法都能匹配。
  • Windows 上用 TOML 的字面字符串书写路径,反斜杠不需要转义:[projects.'C:\Users\me\src\my-project']。
  • trustLevel 不是 "trusted" 的值(例如 "untrusted")都表示不信任;config set ... untrusted 可以撤销信任。
  • 读取时不会修复或改写项目配置,其中无法使用的值会告警并跳过。在 Configuration layers 中显式编辑时,可以创建或更新受信任的当前项目配置;提交的字段经校验后原子保存。
  • 项目配置中不能写 profiles 和 projects。

-c 覆盖

-c 键=值 只在本次运行中覆盖一个键,可以重复,后面的优先:

hanafubuki-agent -c memory.enabled=true -c 'disabledPlugins=["titles"]'
hanafubuki-agent -c logLevel=debug exec "..."
  • 键是点分路径,例如 memory.enabled、network.proxy。每一段按 . 拆分,不支持引号。
  • 值按 TOML 解析(true、7、"full_access"、["a", "b"])。不是合法 TOML 时作为字符串,并去掉两端的引号,所以 -c logLevel=debug 不需要引号。
  • 缺少 = 或键为空时,命令以退出码 2 退出。
  • 不认识的键(包括 profiles.*、projects.* 以及 providers.toml、mcp.toml 的键)不会报错,只会记录到日志并忽略。

选项的优先级

--permission-mode 和 --log-level 相当于追加在所有 -c 之后的覆盖,所以总是最终生效:

hanafubuki-agent -c permissionMode=manual --permission-mode full-access config get permissionMode
# full_access

-m、-C、--add-dir 和 --data-dir 不是 config.toml 的键,不参与分层。

角色

角色在设置之外有自己的分层:用户的(用户 config.toml 旁边的 agents/ 目录及其中的 [agents])、配置档的 [profiles.名字.agents],以及受信任项目的(.hanafubuki-agent/agents/ 和其配置文件中的 [agents];只在项目受信任时读取,即使项目没有 config.toml)。它们不按键合并:较高层的角色整体替换下一层的同名角色,角色要在另一个角色之上构建时使用 extends(角色的来源)。-c 覆盖中没有角色。

无法使用的值

一层中无法使用的值不会生效,通常保留下一层的值。有两个例外:

  • disabledPlugins 不是数组时,结果是空列表(所有插件都启用),而不是下一层的值。
  • webSearchProvider = "searxng" 但这一层及以下都没有可用的 searxngBaseUrl 时,使用 "auto"。

用户文件中的问题会被修复,见配置恢复。

示例

用户文件:

# ~/.config/hanafubuki-agent/config.toml
logLevel = "info"

[network]
proxy = "http://127.0.0.1:7890"

[profiles.review]
permissionMode = "auto_review"

[projects."/home/me/src/my-project"]
trustLevel = "trusted"

项目配置:

# /home/me/src/my-project/.hanafubuki-agent/config.toml
webSearchProvider = "duckduckgo"

[memory]
enabled = false

在 /home/me/src/my-project/crates/core 中运行 hanafubuki-agent -p review -c logLevel=debug 时:权限模式是 auto_review(配置档),记忆关闭(项目),网页搜索用 DuckDuckGo(项目),代理是 http://127.0.0.1:7890(用户文件),日志级别是 debug(-c)。

Agent 写入什么

普通的全局设置写入和 config set 编辑用户的 config.toml。设置中心还支持明确选择目标:Profiles 编辑选中的配置档表,Configuration layers 可以编辑用户文件或受信任的当前项目文件;其来源操作会显示保存路径和优先级。写入保留注释和未知键,不会隐式把高层的生效值复制到其他层。保存后仍可能被更高优先级的层覆盖。

本页目录