Agents 与 Model Roles

taskflow 如何从三层发现 agents、将它们映射到四个语义 model roles，并为每个 phase 解析出正确的 agent。

taskflow 中的每个 phase 都作为 subagent 运行——一个独立的 LLM 进程，拥有自己的 context window、system prompt 和工具集。正是这种隔离让中间的 transcript 不进入你的对话：只有最终的 phase 输出会返回。

但是哪个 agent 运行哪个 phase？这个 agent 又用哪个模型？taskflow 用一套分层发现系统和基于角色的模型映射来回答这两个问题。你可以直接使用 18 个内置 agent、用项目专用的版本覆盖它们，或者编写完全自定义的 agent——所有这些都不需要改动任何 flow 定义。

本指南涵盖完整图景：agent 如何被发现、内置 agent 做什么、model role 如何工作，以及如何自定义这一切。

Agent 发现

taskflow 从三层加载 agent，顺序如下：

内置 agent。 taskflow 包内置了十八个 agent。它们覆盖完整的软件开发生命周期：规划、执行、审查、安全、测试和恢复。除非显式禁用，这些 agent 始终可用。

用户 agent。 位于 ~/.pi/agent/agents/（或由 TASKFLOW_AGENT_DIR / PI_CODING_AGENT_DIR 设置的目录）。这些是你的个人 agent，在你所有项目间共享。

项目 agent。 位于项目根目录（或任意父目录）的 .pi/agents/。taskflow 从当前工作目录向上遍历目录树，找到最近的 .pi/agents/ 文件夹。这些是项目专用的 agent，与你的代码库一起版本化。

各层之间按名称相互覆盖。如果你有一个名为 executor 的项目 agent，同时内置 agent 也叫 executor，则项目版本胜出。这让你可以在不 fork 整个 agent 集合的情况下自定义行为。

Agent 名称使用连字符，而不是下划线：executor-code 是正确的，executor_code 是错误的。运行时会校验这一点，并在你使用下划线时发出警告。

`agentScope` 字段

并非每个 flow 都需要全部三层。taskflow 上的 agentScope 字段控制哪些层处于激活状态：

Scope	加载内容	使用场景
`"user"`（默认）	内置 + 用户 agent	不依赖项目专用 agent 的个人工作流。
`"project"`	内置 + 项目 agent	项目 agent 覆盖用户偏好的团队工作流。
`"both"`	内置 + 用户 + 项目 agent	完整解析：项目覆盖用户覆盖内置。

在 taskflow 顶层设置 agentScope：

project-scoped.json

{
  "name": "project-review",
  "agentScope": "project",
  "phases": [...]
}

如果你要构建一个会在队友机器上运行的 flow，请使用 agentScope: "project"，这样它就不会依赖对方个人的 ~/.pi/agent/agents/ 目录。

18 个内置 agent

taskflow 内置了 18 个 agent，按四类组织。每个 agent 都是一个带 YAML frontmatter 的 markdown 文件，指定其名称、描述、工具、model role 和 thinking 级别。

规划与分析

这些 agent 在代码编写之前分析需求、创建计划并挑战假设。

Agent	Role	Thinking	用途
`analyst`	`{{expert}}`	high	分析需求，暴露歧义，识别隐藏约束。只读。
`critic`	`{{expert}}`	xhigh	挑战计划和结论，在承诺之前发现矛盾。只读。
`planner`	`{{steward}}`	high	创建带文件级细节的具体实现计划。只读。
`plan-arbiter`	`{{expert}}`	high	在执行开始之前审查并挑战计划。只读。

analyst 在复杂流水线中率先运行以澄清需求。planner 把这些需求转化为可执行的计划。critic 和 plan-arbiter 充当质量门控——它们在昂贵的执行开始之前对薄弱的计划推回。

执行

这些 agent 编写代码。它们在范围和复杂度上有所不同。

Agent	Role	Thinking	用途
`executor`	`{{builder}}`	high	默认 executor，用于有清晰计划的 1–4 文件改动。
`executor-fast`	`{{scout}}`	off	琐碎改动：≤2 文件、≤50 行、不涉及架构决策。
`executor-code`	`{{builder}}`	high	复杂的多文件改动：≥5 文件、跨模块、结构性重构。
`executor-ui`	`{{builder}}`	high	UI/前端改动：组件、样式、布局、响应式设计。

默认的 executor 处理大部分工作。机械清理用 executor-fast，结构性重构用 executor-code，当你需要视觉能力来理解设计意图时用 executor-ui。

审查与质量

这些 agent 审查代码、评估风险并验证结果。它们都不编辑文件。

Agent	Role	Thinking	用途
`reviewer`	`{{builder}}`	high	通用代码审查：质量、架构、测试覆盖。
`risk-reviewer`	`{{expert}}`	high	后端/基础设施风险：数据完整性、并发、迁移。
`security-reviewer`	`{{expert}}`	high	安全漏洞：认证、注入、密钥、信任边界。
`final-arbiter`	`{{steward}}`	xhigh	在多个审查者意见冲突时裁决。决胜者。

reviewer 处理通用质量。risk-reviewer 和 security-reviewer 专注于高风险领域，并在领域边界处互相推让。final-arbiter 在审查冲突时打破平局。

支持

这些 agent 处理辅助任务：测试、文档、探索和恢复。

Agent	Role	Thinking	用途
`test-engineer`	`{{builder}}`	high	设计和实现测试策略，检测不稳定模式。
`verifier`	`{{scout}}`	off	运行校验命令，复现失败，检查日志。只读。
`scout`	`{{scout}}`	off	快速代码库探索，为其他 agent 返回结构化发现。
`doc-writer`	`{{builder}}`	off	编写和编辑文档文件（README、指南、changelog）。
`visual-explorer`	`{{builder}}`	high	分析 Figma 设计，提取颜色、token 和组件规格。
`recover`	`{{builder}}`	low	在 context compaction 之后恢复工作，从交接文件接续。

scout 做快速侦察，让其他 agent 不必重新读取所有内容。test-engineer 和 verifier 处理验证。visual-explorer 解析设计文件。recover agent 在 context window 重置之后接续工作。

Model roles

每个内置 agent 在其 frontmatter 中指定一个 model role——不是具体的模型 ID，而是用双花括号包裹的四种语义责任之一：{{steward}}、{{expert}}、{{builder}} 或 {{scout}}。

这种间接层存在是因为不同用户可用的模型不同。role 描述 agent 承担的责任，具体模型只是可替换的绑定。模型厂商增加或重命名档位时，不需要修改 flow 定义。

四个 roles

Role	语义契约	默认模型	使用者
`{{steward}}`	守住目标、长周期计划、跨阶段一致性与最终综合	`openrouter/anthropic/claude-fable-5`	`planner`、`final-arbiter`
`{{expert}}`	深度专业推理与高风险局部判断	`openrouter/anthropic/claude-opus-5`	`analyst`、`critic`、`plan-arbiter`、`risk-reviewer`、`security-reviewer`
`{{builder}}`	实现、审查、UI、测试、文档与恢复的通用默认执行者	`openrouter/anthropic/claude-sonnet-5`	`executor`、`executor-code`、`executor-ui`、`reviewer`、`test-engineer`、`doc-writer`、`visual-explorer`、`recover`
`{{scout}}`	快速、高吞吐侦察与可机械验证的工作	`openrouter/anthropic/claude-haiku-4.5`	`scout`、`executor-fast`、`verifier`

默认绑定构成能力阶梯，但 role 名刻意保持模型中立。未来如果出现更好的日常执行模型，只需重新绑定 {{builder}}；只有工作责任真的新增时才新增 role。

从 0.2.4 升级不会让现有设置失效。旧的 fast、strong、thinker、arbiter、vision、reasoner 键会保留；在新 role 尚未配置时，内置 agent 会精确回退到自己原来的键。新 role 始终优先。仍引用旧键的自定义 agent 也会继续正常解析。

Roles 如何解析

当一个 phase 生成一个 subagent 时，运行时会检查 agent 的 model 字段。如果它匹配 {{roleName}} 模式，运行时会查找该 role 的设置并替换为具体的模型 ID。如果不存在映射，则 model 字段留空，并使用宿主的默认模型。

Agent frontmatter:  model: "{{builder}}"
                       ↓
settings.json:      modelRoles: { "builder": "openrouter/anthropic/claude-sonnet-5" }
                       ↓
Subagent spawns with: model: "openrouter/anthropic/claude-sonnet-5"

带有字面模型 ID（无花括号）的 agent 完全绕过 role 解析。这对于必须始终使用特定模型的自定义 agent 很有用。

使用 `/tf init` 配置

/tf init 命令会交互式地引导你完成 role 配置。它读取你当前的设置，从你的 provider registry 显示可用模型，并以原子方式写回你的选择。

安装或升级 taskflow 后运行 /tf init。用 scout 承担便宜的广度工作，以 builder 为默认；只有风险或时间跨度值得时才使用 expert 和 steward。

操作菜单

当你运行 /tf init 时，会看到一个操作菜单：

使用推荐默认值 —— 应用上表中的默认模型。
逐个配置 role —— 依次遍历全部四个 role。
编辑单个 role —— 只改一个 role，不动其他。
配置 taskflow 偏好 —— 调整内置 agent 设置。
显示当前 roles —— 不做改动地显示当前配置。

对于每个 role，选择器会从你的 registry 显示可用模型，并带有能力标签（多模态 image ✓、推理能力 reasoning ✓），以及你当前选择和推荐默认值的标记。

自定义模型标识符

你也可以在 provider/model-id 格式中输入自定义模型标识符。运行时会根据你的模型 registry 校验它，并在模型不存在时发出警告——一个拼写错误会静默破坏使用该 role 的每个 flow。确认提示可防止拼写错误。

设置存储位置

所有配置都保存到 ~/.pi/agent/settings.json（或由 TASKFLOW_AGENT_DIR / PI_CODING_AGENT_DIR 设置的路径）：

settings.json

{
  "modelRoles": {
    "steward": "openrouter/anthropic/claude-fable-5",
    "expert": "openrouter/anthropic/claude-opus-5",
    "builder": "openrouter/anthropic/claude-sonnet-5",
    "scout": "openrouter/anthropic/claude-haiku-4.5"
  },
  "taskflow": {
    "builtInAgents": true,
    "syncBuiltinAgentsToProject": false,
    "maxKeptRuns": 100,
    "maxRunAgeDays": 30
  }
}

Taskflow 偏好

/tf init 中的"配置 taskflow 偏好"选项调整四个设置：

设置	默认值	说明
`builtInAgents`	`true`	启用或禁用 18 个内置 agent。如果你只想要自己的 agent，请禁用。
`syncBuiltinAgentsToProject`	`false`	在会话开始时把内置 agent 复制到项目的 `.pi/agents/`，以便原生 Pi `@agent` 语法也能发现它们。
`maxKeptRuns`	`100`	保留的非活动运行（`completed`、`failed`、`paused`、`blocked`）最大数量；运行中的工作永不修剪。设为 `0` 禁用按数量清理。
`maxRunAgeDays`	`30`	非活动运行的最大保留天数；运行中的工作永不修剪。设为 `0` 禁用按时间清理。

清理自动运行，节流为每分钟一次。它只移除终态（已完成或失败）的运行——活跃的运行永远不会被触碰。

自定义 agent

你可以通过编写带 YAML frontmatter 的 markdown 文件来创建自定义 agent。自定义 agent 位于用户范围（~/.pi/agent/agents/）或项目范围（.pi/agents/）。

Agent 文件格式

每个 agent 文件有三部分：--- 分隔符之间的 YAML frontmatter、一个空行，以及 system prompt 正文。

~/.pi/agent/agents/code-reviewer.md

---
name: code-reviewer
description: Review code for quality and best practices
tools: read, grep, find, ls, bash
model: "{{builder}}"
thinking: high
---

You are a code reviewer focused on quality and best practices.

Review the provided code for:
- Code style and consistency
- Performance implications
- Error handling
- Test coverage

Be specific and actionable. Don't just say "this could be better" — explain why and how.

Frontmatter 字段

字段	必需	说明
`name`	是	唯一标识符，用于在 flow 中引用该 agent。使用连字符。
`description`	是	简短描述，显示在 agent 列表和选择器 UI 中。
`tools`	否	逗号分隔的工具列表：`read`、`write`、`edit`、`bash`、`grep`、`find`、`ls`。省略时默认为全部工具。
`model`	否	模型 ID 或 role 引用（如 `openai/gpt-4o` 或 `"{{builder}}"`）。回退到宿主默认模型。
`thinking`	否	Thinking 级别：`off`、`none`、`minimal`、`low`、`medium`、`high`、`xhigh`、`max` 或 `ultra`。回退到 `globalThinking`；非法值 fail-closed。各宿主映射不同。

格式错误的 agent 文件永远不会破坏发现过程。运行时会捕获解析错误并跳过坏文件（附带警告），因此其余 agent 仍正常加载。

覆盖内置 agent

要覆盖内置 agent，请在用户或项目 agent 目录中创建同名自定义 agent。层级顺序决定哪个版本胜出：

.pi/agents/executor.md

---
name: executor
description: Custom executor with project-specific conventions
tools: read, grep, find, ls, bash, edit, write
model: "{{builder}}"
thinking: high
---

You are the executor agent for the Acme Corp codebase.

Always follow these project-specific rules:
- Use TypeScript strict mode
- Prefer functional patterns over classes
- Write tests for all public functions
- Run `pnpm typecheck` before committing

这个项目级 executor 会替换内置 executor，对在此项目中运行的任何 flow 生效。~/.pi/agent/agents/executor.md 中的用户级覆盖则会在你所有项目中生效。

覆盖按精确名称匹配。my-executor 不会覆盖 executor。如果你想要一个变体，请给它起不同的名字，并在你的 flow 中显式引用。

Flow 中的 agent 解析

当一个 phase 运行时，运行时通过一个特定过程解析其 agent：

检查 phase 的 agent 字段。 如果 phase 指定了 agent 名称，在发现结果中查找它。

对未知 agent 发出警告。 如果指定的 agent 在发现结果中不存在，记录一条警告（每个未知 agent 每次运行一次），并回退到默认 agent。

回退到默认 agent。 默认值是发现结果中的第一个 agent——通常是按字母序的第一个内置 agent，除非用户或项目 agent 覆盖了它。如果根本没有任何 agent，则使用名称 "default"。

在 phase 中指定 agent

大多数 phase 显式指定 agent：

phase-with-agent.json

{
  "id": "review",
  "type": "agent",
  "agent": "reviewer",
  "task": "Review the code changes for quality issues."
}

你也可以省略 agent 字段。该 phase 会使用默认 agent：

phase-without-agent.json

{
  "id": "review",
  "type": "agent",
  "task": "Review the code changes for quality issues."
}

默认 agent 取决于你的 agentScope 以及每层中存在哪些 agent。为了在不同环境下行为可预测，请显式指定 agent。

Phase 级别覆盖

Phase 可以覆盖 agent 的 model、thinking 级别和工具访问，而无需修改 agent 文件：

phase-with-overrides.json

{
  "id": "deep-review",
  "type": "agent",
  "agent": "reviewer",
  "model": "anthropic/claude-3.5-sonnet",
  "thinking": "xhigh",
  "tools": ["read", "grep"],
  "task": "Deep review of the authentication module."
}

这些覆盖只对该次 phase 调用生效。未覆盖的 phase 仍使用 agent frontmatter 的设置。

覆盖	效果
`model`	替换该 phase 的 agent 模型。接受 role（`"{{builder}}"`）或字面模型 ID。
`thinking`	用受支持值覆盖 thinking。Codex 映射到 `model_reasoning_effort`（`max`/`ultra` → `xhigh`）。
`tools`	请求能力集合。Pi 使用白名单；Codex 仅映射只读/可写 sandbox，而不严格执行工具名。

分支与子 phase

带多个分支的 phase 类型（parallel、tournament）允许每个分支指定自己的 agent：

parallel-with-per-branch-agents.json

{
  "id": "review-all",
  "type": "parallel",
  "branches": [
    {
      "agent": "security-reviewer",
      "task": "Review for security vulnerabilities."
    },
    {
      "agent": "risk-reviewer",
      "task": "Review for data integrity risks."
    },
    {
      "agent": "reviewer",
      "task": "Review for general code quality."
    }
  ]
}

未指定 agent 的分支继承父 phase 的 agent。Tournament phase 还支持 judgeAgent 字段用于 judge 步骤，默认为 phase 的主 agent。

{
  "name": "review-pipeline",
  "phases": [
    {
      "id": "plan",
      "type": "agent",
      "agent": "planner",
      "task": "Analyze the code changes and create a review plan."
    },
    {
      "id": "security-review",
      "type": "agent",
      "agent": "security-reviewer",
      "dependsOn": ["plan"],
      "task": "Review for security issues based on this plan: {steps.plan.output}"
    },
    {
      "id": "quality-review",
      "type": "agent",
      "agent": "reviewer",
      "dependsOn": ["plan"],
      "task": "Review for code quality: {steps.plan.output}"
    },
    {
      "id": "synthesis",
      "type": "agent",
      "agent": "final-arbiter",
      "dependsOn": ["security-review", "quality-review"],
      "task": "Synthesize these reviews and resolve any conflicts:\n\nSecurity: {steps.security-review.output}\n\nQuality: {steps.quality-review.output}",
      "final": true
    }
  ]
}

自定义领域 agent

为你的领域创建一个专用 agent，然后在 flow 中引用它：

.pi/agents/api-designer.md

---
name: api-designer
description: Design RESTful APIs following OpenAPI 3.0 spec
tools: read, grep, find, ls, write
model: "{{builder}}"
thinking: high
---

You are an API designer specializing in RESTful APIs.

Follow these principles:
- Use nouns for resource names, verbs for actions
- Return appropriate HTTP status codes
- Include pagination for list endpoints
- Version APIs in the URL path (e.g., /v1/users)
- Write OpenAPI 3.0 specs in YAML format

api-design-flow.json

{
  "id": "design-api",
  "type": "agent",
  "agent": "api-designer",
  "output": "text",
  "task": "Design a REST API for a task management system with projects, tasks, and users."
}

项目范围的团队工作流

使用 agentScope: "project"，让每个团队成员获得相同的 agent 行为：

team-review.json

{
  "name": "team-review",
  "agentScope": "project",
  "phases": [
    {
      "id": "review",
      "type": "agent",
      "agent": "team-reviewer",
      "task": "Review the code using team standards documented in .pi/agents/team-reviewer.md."
    }
  ]
}

配合 .pi/agents/team-reviewer.md 中编码了你们团队特定审查标准的项目 agent。这个 flow 对团队中的每个人运行方式相同，不受他们个人 agent 目录的影响。