本页为 pi-subagents 官方文档的非官方中文翻译，请以官方英文文档为准。 原文 · 许可证

子智能体如何选择模型，以及如何改变这一行为。

内置智能体沿用你当前的 Pi 默认模型。这使得全新安装不必依赖于某个你可能尚未配置的提供方。从那里开始，你可以分层叠加默认值与覆盖项：

• subagents.defaultModel — 为每个未设置自己模型的子智能体提供默认值。
• subagents.defaultProvider — 对裸模型 id（例如 llama-3）的提供方偏好，当多个提供方暴露相同 id 时使用。
• subagents.agentOverrides.<name>.model — 为单个角色固定一个模型。
• subagents.agentOverrides.<name>.defaultProvider — 为单个角色选择或清除提供方偏好。
• subagents.agentOverridesByProvider.<provider>.<name> — 为活跃父会话提供方分层叠加角色字段。
• 每次运行的覆盖项 — 仅作用于单次启动。

优先级，由强到弱：每次运行的覆盖 → 提供方作用域的角色覆盖 → agentOverrides.<name>.model → 智能体 frontmatter 中的 model → subagents.defaultModel → 父会话模型。提供方偏好不替换此顺序；它仅在活跃注册表存在多个匹配时解析裸模型 id。完整限定的 provider/model 字符串仍严格优先。

在智能体 frontmatter 或 agentOverrides.<name>.model 中使用 model: "inherit" 可显式选择当前的父会话模型。

设置默认值与覆盖项

在 ~/.pi/agent/settings.json（用户）或项目配置文件（标准 Pi 中为 .pi/settings.json；项目优先）中：

{
  "defaultModel": "deepseek-v4-pro",
  "subagents": {
    "defaultModel": "deepseek-v4-flash",
    "defaultProvider": "gpu-a",
    "agentOverrides": {
      "oracle": {
        "model": "deepseek-v4-pro"
      },
      "worker": {
        "defaultProvider": "gpu-b"
      }
    }
  }
}

若要保留同一角色定义，但为工作与个人提供方做不同配置，请在 agentOverrides 旁边添加明确的提供方映射：

{
  "subagents": {
    "agentOverrides": {
      "worker": { "thinking": "medium" }
    },
    "agentOverridesByProvider": {
      "github-copilot": {
        "worker": { "model": "github-copilot/gpt-5-mini" }
      },
      "openrouter": {
        "worker": { "model": "openrouter/openai/gpt-5-mini" }
      }
    }
  }
}

提供方键来自活跃父会话的模型（或显式的宿主 preferredProvider），先于回退选择。提供方作用域的字段在同一设置文件中叠加在普通覆盖之上；项目设置仍优先于用户设置。回退尝试不会切换所选的提供方配置。

若只想在一次运行时覆盖，请在命令中指定：

/run reviewer[model=anthropic/claude-sonnet-4:high] "Review this diff"

若要持久化的角色覆盖，并附带用于提供方故障的备用模型：

{
  "subagents": {
    "agentOverrides": {
      "reviewer": {
        "model": "anthropic/claude-sonnet-4",
        "thinking": "high",
        "fallbackModels": ["openai-codex/gpt-5.6-luna:low"]
      }
    }
  }
}

subagents.defaultModel 与 subagents.defaultProvider 适用于内置、包、用户与项目智能体。defaultModel 仅填充那些在 frontmatter 中未设置 model 的智能体。defaultProvider 也应用于 frontmatter 与覆盖中的模型，以便裸 id 能针对目标提供方解析。每次运行的模型覆盖与 agentOverrides.<name>.model 优先于 frontmatter 与全局默认值。同一 agentOverrides 块可以修改 tools、skills、继承的上下文、提示词文本，或禁用一个智能体（见 agents.md）；匹配的智能体 frontmatter 会被替换为该覆盖所设置的任何字段。

快速模式

在运行、智能体 frontmatter 或 subagents.agentOverrides.<name>.fast 中设置 fast: true，即可为受支持的原生 OpenAI-Codex 子智能体请求 OpenAI 优先服务等级。这可能使用更高的配额等级或带来更高的成本。默认关闭。

除非每个已解析的模型候选都在白名单中，否则快速模式会在启动前失败。当前白名单为 openai-codex/gpt-5.6-luna 与 openai-codex/gpt-5.6-sol。外部运行器、Anthropic 模型与其他提供方不使用快速模式。

推荐的模型分层（可选）

一种实践中效果不错的设置：按任务形态而非统一模型来路由智能体。四个层级：

1. 快速主力 — 能胜任任务的最便宜模型加上低思考，用于勘察、查找与机械性编辑。示例：openai-codex/gpt-5.6-luna:low 用于 scout。
2. 标准有界 — 中等模型加上中等思考，用于大多数委派：常规的多文件编辑、聚焦的评审、直接的实现。示例：openai-codex/gpt-5.6-luna:max 用于 worker、reviewer 与一个轻量的 delegate 智能体。
3. 深度但有界 — 顶级推理模型加上高思考，仅用于带有明确目标与完成标准的难题。这些模型倾向于在模糊目标上循环，因此应远离开放式工作。示例：openai-codex/gpt-5.6-sol:high 用于 oracle 类智能体。
4. 品味与意图 — 能良好理解人类意图并能做出判断而非循环的模型，用于模糊的工作：UX 与设计决策、产品权衡、模糊需求下的规划、写作质量。示例：anthropic/claude-fable-5，轻度任务用 low，较难任务用 medium。

路由规则：任务有界时使用能力层（1–3），而当任务本身就是"界定或判断"时使用意图层（4）。

为 tier-4 智能体提供 fallbackModels，用于在首次工具活动之前处理可重试的提供方/模型故障，例如限流、过载、模型不可用与提供方报告的超时错误。首次工具活动之后，除下方狭义的原生只读 HTTP 429 续接外，失败仍为终态；任务绝不会在工具工作后被自动重放。普通的任务失败与外部的运行级 timeoutMs / maxRuntimeMs 截止时间不会触发回退。

回退使用原生 Pi 会话，而非全新的 pi CLI 进程。即使在重新打开完全相同的会话文件时，常规的回退也会重新提交原始任务；仅凭保留的历史并不足以让工具工作后的自动续接变得安全。

回退配置示例：

---
name: shaper
description: Open-ended design/UX/product/planning agent for ambiguous tasks
model: anthropic/claude-fable-5
thinking: medium
fallbackModels: openai-codex/gpt-5.5:high
---

对于 tier 4，有一个值得了解的交互：在 Anthropic 父会话的转录上进行 fork 上下文时，会从子会话中剥离父会话已签名的思考块，因为思考签名无法被重放到分支中。子会话仍以其请求的思考级别运行，并在第一回合中全新地推理。

工具工作后 HTTP 429 的原生只读续接

一个原生前台或后台子智能体可以在已完成的只读工具工作与一次观察到的 HTTP 429 之后，在 fallbackModels 中一个合格的靠后条目上续接一次。这并非通用的运行中回退，也不适用于外部运行器。当前的覆盖范围为 Pi SDK 0.85.1、已配置的 baseten / openai-completions 提供方及其观察到的请求路径，而非任意提供方、API、提供方扩展或包含"429"的错误文本。

接纳要求默认子智能体工厂所拥有的画像：仅包含内置 read 和/或 ls 的显式白名单、没有环境或自定义扩展/工具或已注册的后台工作提供方，且已验证空闲结算与关闭。等待、监督者协调、嵌套/扇出工作、权限/看门狗、结构化输出、快速模式与已配置的工具预算会在两个宿主上都排除此次续接。仅凭只读的角色名或提示词是不够的；默认的协调画像被排除在外。

用量预算的接纳因宿主而异：

• 前台： 任何已配置的用量预算（包括工作流所有的预算）都会拒绝续接，因为此宿主不证明剩余的可用额度。
• 原生后台： 仅当运行所有者的权威账本已收到当前尝试的事件且覆盖完整（包括并发工作）时，未用尽的、仅限令牌的预算才有资格。已配置的费用预算、缺失/未知的用量、或不受支持的外部/导入/动态覆盖都会拒绝续接。这不会引入新的计费或续期额度。

子智能体必须具有精确分配的会话文件：要么是有效的持久化历史，要么是 SDK 在本次尝试中初始化并持久化的初始缺失分配文件。内存或仅目录的存储是不够的。交接时缺失或变更的检查点会失败闭合；恢复绝不会修复它或提升存储。常规的执行器启动会分配子文件并将其传递给原生宿主；较低级别的仅目录启动仍不具备资格。无需新的存储选项。

下一个模型必须通过同一已配置的提供方运行时解析，具有相同的提供方/API 以及不同的、未尝试过的模型身份，并通过保守的保留输入兼容性检查。跨提供方的候选会被跳过而不启动；未知的解析或不受支持/未知的容量会拒绝续接。两个宿主都会拒绝图像与未知内容；这些是保守的检查，而非精确的令牌估算：

• 前台： 接受文本与受支持的助手工具调用/结果历史。其 UTF-8 字节上限包含保留历史、实际系统提示词与工具定义、4096 字节的框架/续接预留以及候选的完整输出额度。如果此边界适合，则同等窗口的模型也可以合格。
• 原生后台： 解析精确的注册表身份，并接受保留文本、思考块与工具调用块。它会预留整个源上下文窗口加上保留上下文的 UTF-8 字节以及固定提示词字节，并要求候选的正输出额度不大于源的额度。因此，相等/更小的上下文窗口会拒绝续接；请选择一个足够大的同提供方兄弟模型。

兄弟模型会重新打开相同的会话/文件，保留原始任务、已完成的工具结果与终态的提供方错误。其新提示词是一条固定指令，从这些结果继续而不重启或重做已完成的工作；它不会重新提交原始任务。一次恢复额度与压缩中止恢复共享，并在创建兄弟模型前被消耗。任何兄弟模型的结果都会终止恢复，包括启动失败、中止或又一次 429；它不能级联到启动回退或更改模型排除。取消、停止/分离与原始运行截止时间仍为权威，并在交接时重新检查。新计费的尝试用量会被聚合，而非从文件中恢复的历史用量。

对于一个有意不协调的读取器，请将这些现有键合并到 ~/.pi/agent/extensions/subagent/config.json（见 configuration.md）：

{
  "waitTool": { "enabled": false },
  "intercomBridge": { "mode": "off" }
}

这些设置会影响其他子智能体；不要仅仅为了获得恢复能力而禁用必需的协调。请使用现有 frontmatter 定义一个自定义智能体（将 model-a 与 model-b 替换为你已配置的 Baseten 目录中实际的文本能力模型）：

---
name: reader
description: Read-only file analysis without coordination
tools: read, ls
extensions:
model: baseten/model-a
fallbackModels: baseten/model-b
systemPromptMode: append
inheritProjectContext: false
inheritGlobalContext: false
inheritSkills: false
allowNestedSubagents: false
async: false
---
Read the assigned files and return your findings without editing.

通过 subagent({ agent: "reader", task: "Read README.md and summarize it", async: false, context: "fresh", output: false }) 启动。请保持 forceTopLevelAsync 禁用，并省略工具/用量预算与上述被排除的运行时功能。不需要新的恢复标志：这些设置使画像有资格，但续接仍需要实际的已完成只读工作、观察到的 429 以及所有检查点/提供方/生命周期检查。这是一个受信宿主的兼容性边界，而非沙箱或通用的提供方证明。

对于原生后台执行，请使用相同的调用并加上 async: true，这会覆盖该智能体的前台默认。请保留显式空的 extensions: 字段：省略它会在后台子智能体中允许环境扩展，并且无法证明此画像。请选择一个满足上述更严格的后台容量边界的回退模型；未配置的预算最简单，而仅令牌的预算仍需要权威的额度检查。不要仅仅为了获得续接能力而禁用所需的协调或环境能力。

思考级别默认值

设置 subagents.defaultThinking，为没有 thinking 值的内置、包、用户与项目智能体提供一个共享的思考级别，且独立于父会话的默认值。项目设置优先于用户设置。匹配的 agentOverrides.<name>.thinking 与每次运行的思考覆盖会替换 frontmatter；否则显式的 frontmatter 保持生效。thinking: false 仍为显式选择退出：

{
  "subagents": {
    "defaultThinking": "medium",
    "agentOverrides": {
      "reviewer": { "thinking": "high" }
    }
  }
}

如果你的提供方拒绝带思考后缀的模型 ID，请在用户或项目设置中设置 subagents.disableThinking: true。这会在一处清空打包的内置思考默认值。显式的更高优先级 agentOverrides.<name>.thinking 值可以让某个角色重新选择加入，或替换自定义智能体 frontmatter 的思考。

思考上限

设置 subagents.maxThinking 以对每个原生 Pi 子智能体强制一个硬上限。从最少到最多思考，受支持的级别为 off、minimal、low、medium、high、xhigh 与 max：

{
  "subagents": {
    "defaultThinking": "medium",
    "maxThinking": "xhigh"
  }
}

超出上限的请求会在子启动前失败；该设置覆盖 frontmatter、agentOverrides、每次运行的覆盖、回退模型、并行/链式子节点、嵌套启动以及恢复的子节点。项目设置优先于用户设置。外部运行器保留其既有行为。

扩展默认值

设置 subagents.defaultExtensions，为没有 extensions 字段的内置、包、用户与项目智能体提供一个共享的扩展白名单：

• 缺失：保留 Pi 常规的环境扩展发现。
• 空数组：为未明确定义 extensions 的智能体设置 extensions: []，禁用环境扩展加载。
• 非空数组：为未明确定义扩展的智能体提供该白名单。

项目设置优先于用户设置。请使用 agentOverrides.<name>.extensions 进行按智能体的设置；匹配的覆盖会替换该字段的自定义智能体 frontmatter。

{
  "subagents": {
    "defaultExtensions": [],
    "agentOverrides": {
      "researcher": {
        "extensions": ["./tools/research.ts"]
      }
    }
  }
}

非数组值、包含非字符串条目的数组，或空/仅空白字符串会引发一个命名 defaultExtensions 与出错设置文件的设置错误，匹配 defaultModel 与 defaultThinking 所采用的验证模式。

检查实时映射

若要查看 pi-subagents 当前实际加载的内容：

/subagents-models
/subagents-models reviewer

它会报告实时的运行时映射，在重新加载 Pi 之前可能与磁盘上的设置不同。

模糊模型匹配

你不必精确拼写模型 ID。模型 id 会以模糊方式与注册表匹配，因此以下都能解析到同一模型：

• 提供方分隔符变体：anthropic/claude-sonnet-4、anthropic:claude-sonnet-4、anthropic.claude-sonnet-4
• ID 分隔符变体：claude-haiku-4.5 与 claude-haiku-4-5
• 大小写差异：Claude-Sonnet-4 与 claude-sonnet-4
• 可选的尾部日期戳：claude-haiku-4-5-20251001 或 claude-haiku-4-5-2025-10-01 与 claude-haiku-4-5

精确的 provider/id 匹配仍胜出，并且有限定的提供方查询永远不会悄悄切换提供方——它仅在该命名提供方内匹配。仍存在歧义的、在多个提供方下的裸 id 仍需要提供方前缀或当前会话的提供方来消歧。

注册表 id 自身包含 /（Hugging Face owner/name）的解析方式与 Pi 的主智能体相同：thinkingmachines/Inkling 在该 id 唯一或由当前会话提供方提供时变为 huggingface/thinkingmachines/Inkling。匹配已注册提供方的第一段路径仍然表示 provider/id。

模型作用域强制

为了将子智能体限制在预算或合规配置文件内，请强制一个模型作用域。在用户或项目设置中放置 subagents.modelScope（项目覆盖用户）：

{
  "subagents": {
    "modelScope": {
      "enforce": true,
      "strict": true,
      "allow": ["inherit", "openai/gpt-5-*", "openai-codex/gpt-5.6-*"],
      "agents": {
        "worker": { "allow": ["openai-codex/gpt-5.6-luna"] },
        "reviewer": { "allow": ["inherit"] }
      }
    }
  }
}

• allow 是与已解析的 provider/id 进行匹配的通配符模式列表（仅 * 是特殊的，大小写不敏感）。字面量 inherit 表示当前的父会话模型。
• agents.<name> 为该智能体添加第二个白名单。模型必须同时通过全局列表与匹配的智能体列表，因此智能体规则不能削弱全局规则。当那些字段缺失时，智能体规则会继承 enforce 与 strict。
• 仅带智能体白名单的顶层 enforce: true 只会限制那些具名智能体。未知名称是被允许的，以便设置可以在项目与机器之间共享。
• 你显式传入的模型——工具调用的 model、--model 或澄清选择——会报错并中止运行。
• 默认情况下，来自智能体 frontmatter、subagents.defaultModel、继承的父会话模型或回退链的模型仅发出警告且仍可用，因此既有配置可以继续工作，同时你可以收紧作用域。
• 在 enforce: true 的同时设置 strict: true 以拒绝每一个已解析的超范围模型。这包括继承的模型与回退候选。一个无效的回退会使运行失败，而不是从候选链中移除。
• enforce: true 要求至少一个非空的全局或智能体 allow 列表；否则该配置在加载时被拒绝。

模型作用域仅为策略。它拒绝或警告；不会选择更便宜的模型。请设置 agentOverrides.worker.model 来选择一个 worker 模型，并使用 modelScope.agents.worker 来阻止每次运行的覆盖或回退逃逸该限制。

inherit 在父进程中于每次启动时展开。它永远不会作为模型 id 发送给子智能体。因此嵌套子智能体继承其直接父会话的当前模型，而非原始的顶层模型。如果没有父会话模型可用，被强制的 inherit 条目不会匹配，并失败闭合。

项目 modelScope 设置会替换完整的用户 modelScope，与既有的项目覆盖用户的设置优先级一致。项目设置是受信任的，因此可以替换用户限制。

配置档与提供方模型目录

配置档允许你从一个提供方的实时目录生成并保存"角色到模型"的分配。

配置档存储于：

~/.pi/agent/profiles/pi-subagents/

提供方模型目录缓存于：

~/.pi/agent/profiles/pi-subagents/providers/

工作流：

/subagents-refresh-provider-models openai-codex
/subagents-generate-profiles openai-codex
/subagents-load-profile openai-codex.quota

• /subagents-refresh-provider-models 会写入一份序列化的提供方模型目录，其中包含观察到的注册表数据、简单的面向角色的分类，以及来自小型一次性 pi -p --model ... --no-tools 检查的实时探测结果。当目录缺失或过期时会刷新；请使用 --force 忽略新鲜度并立即重新探测。
• /subagents-generate-profiles 使用提供方目录生成配额与质量配置档。
• /subagents-check-profile 会对已保存配置档中的每个已分配模型，在当前注册表与实时探测下重新检查，以便你能检测到模型下架、身份验证问题或过时的分配。