AgentDefinition 与 Persona 如何合并
拆解 Agent 定义、Persona 覆盖与最终会话行为的合并顺序
本页解决的问题
先给结论「AgentDefinition 与 Persona 如何合并」要解决的关键问题是什么？
拆解 Agent 定义、Persona 覆盖与最终会话行为的合并顺序
让这个结论先证明自己值得留下。 把这一页当成决策工具，而不是需要背下来的定义。把概念连到一个真实任务、一个可观察结果，以及一个能改变你判断的失败上。
写下一个问题：试完这个方法后，你能用什么证据回答它？
结论听起来很完整，却没有检查最关键的假设。
能区分 AgentDefinition、SubagentRole、SubagentPersona 与 EffectiveRuntimeConfig，并按字段准确判断合并优先级。
定义解析与运行时覆盖是两条输入线
图中类型和函数名来自源码，箭头用于讲解数据汇合关系。
AgentDefinition：可版本化的 Agent 合同
从 .grok/agents/*.md 解析，真实字段包括 prompt_mode、tool_config、capability_mode、permission_mode、tools、isolation、model、hooks 与 MCP 继承等。项目定义的发现优先级高于 user 与 bundled。
SubagentRole：按类型命中的运行时预设
role 可给出 capability、model、reasoning effort、prompt file 与默认 isolation。它由 subagent_type 查找，role prompt 在 spawn 时读取。
SubagentPersona：按名称选择的行为层
Persona 有 inline instructions、instructions file、inputs、outputs、model、reasoning effort 与 default isolation。inline 文本在文件内容之前合并，再作为 <persona> 块进入 prompt。
EffectiveRuntimeConfig：已解析结果
真实字段是 model、reasoning_effort、capability_mode、persona、persona_instructions、role_prompt、role_prompt_warning、role_name、persona_error 与 isolation。源码中没有 temperature、max_tokens 或 tools 字段。
EffectiveRuntimeConfig 之后还有 definition fallback
shell 收到解析结果后，若 reasoning_effort 仍为空，会读取 AgentDefinition.effort；若 runtime isolation 为 None 且 definition isolation 为 Worktree，也会升级为 Worktree。model 解析中，已解析的 runtime override 先于 per-agent pin、AgentDefinition.model 与父模型继承。
失败关闭：Persona
请求了 Persona 后，找不到、内容为空或读取文件失败都会写入 persona_error。文件 I/O 失败会提前返回默认化结果；spawn 侧看到 Persona 错误后中止创建。
软降级：role prompt
role 的 prompt_file 读取失败只产生 role_prompt_warning，其余 model、reasoning、capability 与 isolation 仍继续解析。
pub struct EffectiveRuntimeConfig {
pub model: Option<String>,
pub reasoning_effort: Option<String>,
pub capability_mode: Option<SubagentCapabilityMode>,
pub persona: Option<String>,
pub persona_instructions: Option<String>,
pub role_prompt: Option<String>,
pub persona_error: Option<String>,
pub isolation: SubagentIsolationMode,
}快照说明：字段名与类型来自真实结构体，省略了注释和两个观测字段。上方合流图是教学化视觉，不表示源码中存在同名的单体管线类。
课堂练习：手算有效配置
spawn 指定 reasoning_effort=high 和 Persona reviewer；role 指定 model=A、capability=read-only、isolation=worktree；Persona 指定 model=B、reasoning=low、isolation=none。写出四个字段的最终值，并解释 capability 为何不会读取 Persona。
「定义解析与运行时覆盖是两条输入线」为什么要看操作
「能区分 AgentDefinition 、 SubagentRole 、 SubagentPersona 与 EffectiveRuntimeConfig ，并按字段准确判断合并优先级」把结构落到了一个具体动作。这里真正要比较的不是名词谁更高级，而是数据如何被放置，以及最常发生的操作需要走多远。
读懂结构，要同时看访问方式和变化方式
「从 .grok/agents/*.md 解析，真实字段包括 prompt_mode 、 tool_config 、 capability_mode 、 permission_mode 、 tools 、 isolation 、 model 、hooks 与 MCP 继承等。项目定义的发现优先级高于 user 与 bundled」揭示了一个容易被忽略的取舍：按位置读取、按键查找、从两端进出、插入新元素和遍历关系，适合的组织方式并不相同。一个结构在某个操作上很快，不代表它在所有操作上都快。
把规模和更新频率一起算进去
实践时可以把「spawn 指定 reasoning_effort=high 和 Persona reviewer；role 指定 model=A、capability=read-only、isolation=worktree；Persona 指定 model=B、reasoning=low、isolation=none。写出四个字段的最终值，并解释 capability…」当作边界提醒：先写下数据量、最常用的操作和允许的延迟，再看 AI 给出的结构是否真的匹配。
从「定义解析与运行时覆盖是两条输入线」走到「AgentDefinition：可版本化的 Agent 合同」
「定义解析与运行时覆盖是两条输入线」先把问题落在「图中类型和函数名来自源码，箭头用于讲解数据汇合关系」上；到了「AgentDefinition：可版本化的 Agent 合同」，讨论继续推进到「从 .grok/agents/*.md 解析，真实字段包括 prompt_mode 、 tool_config 、 capability_mode 、 permission_mode 、 tools 、 isolation 、 model 、hooks 与 MCP 继承等。项目定义的发现优先级高于 user 与 bundled」。两段连起来，重点就不只是记住一个结论，而是看清它成立所依赖的条件。
把这条判断带到下一个场景
遇到一个新的数据结构时，不要从定义开始背。先写出最频繁的操作，再估计数据量和更新方式，最后检查结构是否让这三个条件同时成立。
- 「定义解析与运行时覆盖是两条输入线」：图中类型和函数名来自源码，箭头用于讲解数据汇合关系
- 「AgentDefinition：可版本化的 Agent 合同」：从 .grok/agents/*.md 解析，真实字段包括 prompt_mode 、 tool_config 、 capability_mode 、 permission_mode 、 tools 、 isolation 、 model 、hooks 与 MCP 继承等。项目定义的发现优先级高于 user 与 bundled
- 「最后的要点」：shell 收到解析结果后，若 reasoning_effort 仍为空，会读取 AgentDefinition.effort ；若 runtime isolation 为 None 且 definition isolation 为 Worktree，也会升级为 Worktree。model 解析中，已解析的 runtime override 先于 per-agent pin、 AgentDefinition.mod…
最后的「最后的要点」把讨论落到「shell 收到解析结果后，若 reasoning_effort 仍为空，会读取 AgentDefinition.effort ；若 runtime isolation 为 None 且 definition isolation 为 Worktree，也会升级为 Worktree。model 解析中，已解析的 runtime override 先于 per-agent pin、 AgentDefinition.mod…」。回看这条线索时，最值得保留的是：当输入、规模或风险改变，哪些判断需要重新做一遍。
我把这篇文章里的一个判断改写成了今天可以验证的小实验。比记住结论更有用的是，知道下一步要观察什么。
读完以后我先回头找它成立的条件，而不是直接把方法搬进项目。这个顺序让后面的取舍清楚很多。
如果把这个判断放到真实工作里，最先需要补的约束是什么？我想知道从阅读到第一次实践之间，哪一步最值得先做。
还没有这篇文章的讨论。