hanafubuki-agent

角色

有名字、可继承、只会收窄 Agent 的工作方式定义——角色文件、[agents] 条目、来源与优先级、extends 与合并规则、内置角色,以及会话和子代理中的角色。

角色是 Agent 工作方式的一份有名字的定义:指令、模型、推理强度、权限模式上限,以及它可以使用的工具和插件。角色只会收窄它所在的 Agent:它可以拿走工具和插件、收紧权限模式,但绝不增加或放宽任何东西,所以没有哪个角色比实例本身能做的更多。审批规则、你的钩子和沙箱都不受任何角色影响。

角色用 TOML 定义,可以由你、配置档或受信任的项目提供,另有两个内置角色;已安装插件也可以带来角色。Agent 会读取、检查并列出角色(hanafubuki-agent roles、doctor、/warnings),会话以你选择的角色运行(会话中的角色),子代理以父会话的模型给它的角色运行(子代理的角色)。

定义角色

角色文件是 agents/ 目录中的 .toml 文件:用户的在 config.toml 旁边(Linux 上是 ~/.config/hanafubuki-agent/agents/),受信任项目的在 .hanafubuki-agent/agents/。

# ~/.config/hanafubuki-agent/agents/reader.toml
description = "阅读代码并报告发现;从不编辑文件。"
extends = "explorer"
instructions = """
回答时给出文件路径和行号。
"""
model = "gpt-5.4-mini"
reasoningEffort = "low"
permissionModeCap = "manual"

[tools]
allow = ["read_file", "search_text", "list_directory"]
deny = ["fetch_web_page"]

[plugins]
off = ["titles", "goal"]

角色名是文件中的 name 键,没有时是去掉 .toml 的文件名(reader)。agents/ 子目录中的文件也会读取。

键

键类型和取值默认值含义
name角色名文件名(不含扩展名)角色文件中的角色名。[agents.名字] 条目以它的键为名
description文本父角色的角色的用途,将由提供它的引导文字展示。角色必须有描述,自己的或继承来的都可以
extends一个角色的名字无它所基于的角色(见下)
instructions文本无角色追加到 Agent 指令中的内容
instructionsMode"append" 或 "replace""append"指令是接在所继承角色的指令之后,还是替换它们
model模型 id父角色的,否则会话的角色运行的模型,在父会话的 Provider 下,除非 spawn_agent 的 provider 指定了另一个
reasoningEffortminimal、low、medium、high、xhigh 或模型接受的其他强度父角色的推理强度
permissionModeCap"manual"、"auto_review" 或 "full_access"无角色运行时最宽的权限模式;只会收紧
spawnabletrue 或 false父角色的,否则 true子代理能否被赋予这个角色(见下文)
tools.allow工具模式数组父角色允许的全部角色只能使用的工具
tools.deny工具模式数组无不论 allow 怎样写,角色都不能使用的工具
plugins.off插件名数组(已安装插件的代码写作 guest:<id>)无角色的会话不获得其工具和上下文的插件

角色名为 1 到 128 字节,不含空格、控制字符或 :;: 由已安装插件的角色使用(<插件>:<角色>,见下)。

工具模式

tools.allow 和 tools.deny 的每一项是下面之一:

  • 工具名,即模型调用时使用的名字(read_file、mcp__github__list_issues),其中 * 匹配任意一段字符(mcp__github__*、read_*);
  • plugin:名字:插件 名字 注册或提供的全部工具(plugin:web;已安装插件的代码写作 plugin:guest:demo@my-mkt);
  • provider:ID:某个工具提供方提供的全部工具,可以用 *(provider:mcp.github、provider:plugin.demo.*)。

不属于以上任何一种的项(空的、含空格的、带其他 类型: 前缀的)会被略去,并记一条问题。匹配不到任何工具的模式不是错误:工具会出现也会消失。

角色的来源

角色来自以下来源,从低到高。较高来源中的角色会整体替换较低来源中的同名角色:较低那个什么都不保留。想在某个角色的基础上修改,请给你的角色另起名字并 extends 它。

  1. 内置角色:default 和 explorer(见下)。
  2. 已安装插件的:在插件开启期间提供,各以 <插件>:<角色> 命名(见下)。
  3. 用户的:用户 agents/ 中的角色文件,以及用户 config.toml 中的 [agents] 条目。
  4. 配置档的:-p 名字 选择的配置档中的 [profiles.名字.agents] 条目。
  5. 受信任项目的:.hanafubuki-agent/agents/ 中的角色文件,以及 .hanafubuki-agent/config.toml 中的 [agents] 条目;只有用户的 config.toml 信任该项目时才读取(项目配置)。

同一来源中,先是 [agents] 条目(按名字),再是角色文件(按路径)。两者定义了同一个名字时,前一个保留这个名字,另一个被忽略并记一条问题。不可用的角色依然占有它的名字:它不会让较低来源的同名角色顶上来。

嵌入应用的配置只有用户这一个来源:它的 agents/ 和 [agents]。

config.toml 中的条目

角色也可以写在任意一层的 config.toml 中,而不是单独的文件,键相同:

[agents.reviewer]
description = "审查一处改动并列出发现的问题。"
extends = "explorer"
reasoningEffort = "high"

[agents.reader]
configFile = "agents/reader.toml"
model = "gpt-5.4"

configFile(Codex 的 config_file)指向一个角色文件,路径相对于写着它的 config.toml 所在的文件夹:条目的键覆盖在文件的键之上读取,条目的键名就是角色名。这个文件归这个条目所有,目录不会再读一遍。读不了的 configFile 会让角色不可用。

[agents] 不是设置:config get 和 config set 不处理它,-c agents.… 覆盖是未知的键。终端界面的设置中心编辑用户自己的条目(Model 标签页中的 Roles):a 添加一个;description、instructions、instructionsMode、model、reasoningEffort、spawnable、extends、permissionModeCap、tools.allow、tools.deny 和 plugins.off 改动时即保存(r 删除一个键)。删除 tools.allow 会继承父角色的允许范围,设为空列表则不允许任何工具。Delete 删除整个条目,每次改动后角色会重新读取。角色文件、profile、项目、插件或 Agent 自带的角色在那里只显示,并说明写在哪里。

extends 与合并

extends 指定一个父角色,按名字在应用优先级之后的所有来源的角色中查找。一条继承链最多包含 8 个角色(角色本身和它继承的角色)。父角色不存在或不可用、继承链成环(包括继承自己)或长于 8 的角色是不可用的,并说明原因;它从不悄悄退回到别的东西。

继承链从根到角色逐字段合并,每条规则都只会收窄:

字段规则
description、model、reasoningEffort、spawnable角色设置了就用角色的,否则用父角色的
instructionsappend:父角色的、一个空行、再接角色的。replace:只用角色自己的(它没有就没有)
permissionModeCap两者中更严格的:manual,其次 auto_review,再次 full_access
tools.allow工具必须被链上每一个设置了 allow 的角色允许:角色自己的列表不会加入父角色排除的工具。没有 allow 即父角色的
tools.deny、plugins.off所有角色的合在一起

因此角色可以用 deny 去掉任意一个继承来的工具,而 allow 列表只会收窄父角色允许的范围:explorer 的子角色写 allow = ["read_*"],就只能使用 read_file。

内置角色

角色收窄的内容可派生
default什么都不收窄:即按配置运行的 Agent。没有指定角色的会话就是这个角色是
explorer它的工具:只有 list_directory、search_text、read_file、view_image、web_search、fetch_web_page是

explorer 的描述改编自 Codex:explorer 回答关于代码库的具体问题,其结果直接采信而不必再核对,彼此独立的问题可以并行交给多个 explorer。你自己名为 explorer 的角色会替换内置的那个。default 这个名字是保留的:default 始终什么都不收窄,所以你自己名为 default 的角色不可用,并附带一条问题(换个名字即可;它仍可以 extends = "default")。

会话中的角色

会话有一个角色,除非你选择别的,否则是 default:

  • 开始时:终端界面的新会话和 exec 用 --role NAME;Agent 嵌入时用 create_session 的 role。
  • 轮次之间:在终端界面中用 /role NAME(单独的 /role 列出可用角色),或用 set_session_role。有轮次在运行时它被拒绝。/role default 再去掉所有收窄。

没有任何来源定义的角色、或不可用的角色会被拒绝,消息中会列出可用的角色。

会话从角色中取得:

  • 指令。 会话的指令始终是 Agent 的基础指令(其中有审批指引),后面跟着角色继承链合并后的指令:instructionsMode = "replace" 只替换它所继承角色的指令,从不替换基础指令。选择别的模型会保留它们。

  • 模型和推理强度(角色设置了的话),通过模型选择应用,所以上下文窗口与任何模型一样解析。之后用 --model(或 /model)仍可以选择别的。

  • 它的收窄,作为会话的能力范围(能力范围):

    • 只提供角色允许且没有拒绝的工具;内核自己的工具(update_plan、request_user_input、new_context、压缩工具)和 search_tools 始终提供。调用角色排除的工具,得到的回答与调用不存在的工具相同;
    • plugins.off 中的插件不给会话任何东西:没有工具、没有上下文段、没有提示、不继续轮次。skills 关闭时,你显式引用的 Skill 被拒绝("the Skill catalog is unavailable"),$mention 不选中任何 Skill(保持为文本),Skill 工具缺失;memory 关闭时,记忆摘要和记忆工具缺失,但会话仍按它的贡献模式贡献记忆;
    • 每个轮次以它的权限模式和角色的 permissionModeCap 中更严的那个运行。

    审批规则、你的钩子、插件的观察者和沙箱不受角色影响。计划模式仍只在角色保留的工具中保留只读工具。

会话把这些保存在它自己的记录中:之后编辑或删除角色文件不会改变已有它的会话(重启后也一样),直到你再次选择这个角色。子代理或旁路对话从不比父会话的角色宽,分叉保留源会话的角色。

子代理的角色

模型用 spawn_agent 的 agent_type(沿用 Codex 的名字)给子代理一个角色:必须是可派生的角色,即 spawnable 为 true 的角色(两个内置角色都是)。

  • 模型读到什么。 子代理指引按名字列出可派生的角色及其描述(agent_type 的描述指向它):最多 16 个角色,按名字排序,每条描述占一行,截断到 200 个字符。所以角色的 description 要写给这位读者看:什么时候该选它。角色之后,它列出已启用的 Provider 及其已知的模型和推理强度,spawn_agent 的 provider、model 和 reasoning_effort 可以传入这些值来取代角色的(工具)。
  • 不带 agent_type,或者用 default,子代理保留父会话的角色:它的收窄和它的指令。
  • 带一个角色时,子代理的指令是基础指令加上这个角色的指令;它的收窄是父会话的收窄再按角色进一步收窄,所以子代理永远不会有父会话没有的工具;它的模型是角色的 model(父会话的 Provider 下的),否则是父会话的;推理强度是角色的 reasoningEffort,否则是父会话的;除非 spawn_agent 的 model、reasoning_effort 或 provider 另有规定:逐项而言,参数优先于角色(工具)。角色自己的推理强度在派生时从不检查,它的模型也只在传入了 provider 或 model 时才检查:否则 Provider 不提供的模型会在子代理的第一个请求时失败。它始终使用父会话的权限模式,并受角色的 permissionModeCap 限制。
  • 未知的、不可用的或不可派生的角色会被拒绝:模型读到一条指明 agent_type 并列出可派生角色的错误,不会创建子代理。
  • list_agents 给出每个子代理的角色(agent_type)。

每次派生都读取当时的角色,指引在每一步也是如此。指引只显示给步骤提供 spawn_agent 的会话:所在角色略去这个工具的会话(比如 explorer)读不到它。

插件的角色

已安装插件通过它的 agents 组件带来角色(编写插件):

  • 本项目格式的插件提供角色文件:它的 agents/(或清单中 agents 指定的路径)中的 .toml 文件,读取方式和你的完全一样,包括每一个键;
  • Claude Code 插件提供代理文件:它的 agents/ 中的 .md 文件,frontmatter 中的 name、description、tools、disallowedTools、permissionMode、model 和正文(即指令)作为角色读取,Claude 的工具名映射为本 Agent 的,permissionMode 映射为 permissionModeCap(对照表);
  • Codex、Cursor 或 Agent Plugins 格式的插件没有角色。

名字。 插件的角色名为 <插件>:<角色>:插件 id 中的插件名(demo@my-mkt 的 demo),再加上角色自己的名字(它的 name,没有时是文件名)。你的角色不会占用这个名字,因为你的角色名不含 :。来自不同市场的两个同名插件同时开启时:id 在前的(demo@alpha 先于 demo@beta)保留这个名字,另一个不带来任何角色,并记一条问题。extends 按目录中的名字引用角色,所以插件的角色继承同一插件的另一个角色时写作 extends = "demo:base"。

生命周期。 插件的角色只在插件开启期间存在于目录中:开启或关闭插件(以及安装、更新或移除它)都会重新读取角色,无需重启。安全模式下没有插件带来角色。已经有某个插件角色的会话保留它当时取得的内容,和任何角色一样。

只会收窄。 插件的角色和你的角色经过同样的合并:它只能拿走工具和插件、收紧权限模式,所以绝不会比它所在的实例更宽。你的角色 extends 它时会进一步收窄它,也可以重新设置它的 spawnable。

读取插件角色文件时略去的内容(未知的键、没有对应工具的 Claude 工具名)是插件的问题,显示在 plugins info 和 /plugins 中该插件的条目里;插件中无法使用的角色是角色问题,和你的一样。插件的角色属于运行中 Agent 的角色目录:会话(--role demo:reviewer、/role)和子代理(agent_type)都可以使用它们,/plugins 按插件列出它们。roles list、roles show 和 doctor 也显示它们,且不启动 Agent:它们按磁盘上的样子读取已安装插件,不向插件目录写入任何东西,也不取任何锁,所以可以在 Agent 运行时使用;和运行中的 Agent 一样,只有开启的插件(--safe-mode 时一个都没有)带来它的角色。在这几个命令中,读取插件角色时略去的内容与角色问题一同列出,每条都写明它的插件。

Codex 角色文件

Codex 的角色文件放进 agents/ 无需修改即可使用:它的 developer_instructions、model 和 model_reasoning_effort 分别作为 instructions、model 和 reasoningEffort 读取。一个键和它的 Codex 名字同时设置时使用我们的,并记一条问题。其他 Codex 键(sandbox_mode、nickname_candidates 等)在这里是整个 Agent 的设置,因此被忽略,各记一条问题。Codex 的 [agents] 设置(max_threads 之类)不是角色,被忽略并记一条问题。

无法使用的内容

角色文件是你写的配置,因此宽容地读取,并且从不改写:

  • 每个键单独读取。类型错误的键(例如 model 写成数字)会被略去并记一条问题,改用父角色的值或默认值。未知的键被忽略并记一条问题。
  • tools.allow、tools.deny 或 plugins.off 中不是文本的数组项会被单独略去,这只会让列表变窄,不会变宽。
  • 起收窄作用、却完全读不出来的键(不是名字的 extends、不是权限模式的 permissionModeCap、不是表的 tools 或 plugins、不是数组的 allow、deny 或 off)会让角色不可用:略去它会允许比角色写明的更多。
  • 不是有效 TOML 的文件,作为以其文件名命名的不可用角色列出;文件名无法作为角色名的文件被忽略并记一条问题。
  • 没有描述(自己的或继承来的)的角色不可用。
  • 继承链中的工具模式(允许列表和拒绝模式合计)超过 128 个的角色不可用:会话最多只能容纳这么多。

这些问题以及不可用的角色和原因,会显示在 hanafubuki-agent roles list(标准错误)、doctor 的 roles 行,以及终端界面 /warnings 的 roles 来源下。无法使用的角色从不会让 Agent 停止。

查看角色

在 /config 中,Roles 编辑用户表格定义和 configFile 关联,Role source files 编辑用户 agents 目录中文件的类型化字段。只读角色支持查看来源和复制到用户角色;副本继承原角色,保留能力限制。

hanafubuki-agent roles list
hanafubuki-agent roles show reader
hanafubuki-agent -p review roles show reader   # 带上配置档的角色
reader  user file /home/me/.config/hanafubuki-agent/agents/reader.toml
chain: reader (user file /home/me/.config/hanafubuki-agent/agents/reader.toml) → explorer (built-in)
description: 阅读代码并报告发现;从不编辑文件。  [from reader]
instructions: 回答时给出文件路径和行号。  [from reader]
model: gpt-5.4-mini  [from reader]
reasoningEffort: low  [from reader]
spawnable: true  [from explorer]
permissionModeCap: manual  [from reader]
tools.allow: every one of [list_directory, read_file, search_text] and [fetch_web_page, list_directory, read_file, search_text, view_image, web_search]  [from reader, explorer]
tools.deny: fetch_web_page  [from reader]
plugins.off: goal, titles  [from reader]

roles show 按继承链解析后的结果打印每个字段,以及链上决定它的角色,最近的在前。两个命令都不会启动 Agent(命令行参考)。

何时读取角色

运行中的 Agent 在启动时读取角色,之后每次重新加载已安装插件时再读一次(插件的角色按这次重新加载的结果),而它自己每次写入设置后、每次已安装插件发生变化后都会重新加载。手动编辑的角色文件在那时生效,或者在下次启动时生效,对此后选择它的会话有效;已经有这个角色的会话保留它当时取得的内容。roles list、roles show 和 doctor 每次运行都会读取这些文件。

本页目录