pi-subagents

pi-subagents

pi-subagents 让 Pi 将工作委托给专注的子 agent。用于代码审查（code review）、侦查（scouting）、实现（implementation）、并行审计（parallel audits）、保存的工作流（saved workflows）、后台任务（background jobs）以及任何可以从第二或第三组模型视角中获益的场景。

https://github.com/user-attachments/assets/702554ec-faaf-4635-80aa-fb5d6e292fd1

安装

pi install npm:pi-subagents

这是唯一必需的步骤。后续可以添加可选组件。

先试试这个

你不需要创建 agent、编写配置或学习斜杠命令。安装后，直接用自然语言要求 Pi 进行委托：

Use reviewer to review this diff.

Ask oracle for a second opinion on my current plan.

Use scout to understand this code based on our discussion then ask me clarification questions.

Run parallel reviewers: one for correctness, one for tests, and one for unnecessary complexity.

这样就够了。

会发生什么

Pi 是父会话（parent session）。subagent 是一个专注于自身任务的子 Pi 会话（child Pi session）。

当你要求一个 subagent 时，Pi 启动子会话，分配任务，并把结果带回来。前台运行会在对话中流式显示结果。后台运行会持续工作，之后可以查看。

安装扩展不会在后台自动启动一个审查者。它只给 Pi 提供了一个委托工具。如果你希望每次实现后都进行审查，可以在提示语或项目指令中声明：

When you finish implementing, run a reviewer subagent before summarizing.

好的初始提示

这些覆盖了大部分日常使用：

Ask oracle for a second opinion on my current plan. Challenge assumptions and tell me what I might be missing.

Use oracle to help solve this hard bug. Have it inspect the code and propose the best next move before we edit anything.

Run parallel reviewers on this diff. I want one focused on correctness, one on tests, and one on unnecessary complexity.

Have worker implement this approved plan. Afterward, run parallel reviewers, summarize their feedback, and apply the fixes that make sense.

Run a review loop on this change until reviewers stop finding fixes worth doing, with a max of 3 rounds.

Use scout to understand the auth flow, then have planner turn that into an implementation plan.

这些都是普通的 Pi 请求。Pi 会决定是否调用 subagent、使用哪个 agent、以及串行或并行运行是否合理。

常见工作流

想要	自然地问
获得第二意见	“Ask oracle to review this plan and challenge assumptions.”
解决难题	“Use oracle to investigate this bug before we edit.”
审查 diff	“Use reviewer to review this diff.”
并行审查	“Run reviewers for correctness, tests, and cleanup.”
实现后审查	“Implement this, then review it.”
审查直到干净	“Run a review loop on this change with a max of 3 rounds.”
仔细执行计划	“Have worker implement this approved plan, then run reviewers and apply the feedback.”
计划前侦查	“Use scout to inspect the auth flow before planning.”
后台运行	“Run this in the background.”
浏览 agent	“Show me the available subagents.”
使用保存的工作流	“Run the review chain on this branch.”
查看正在运行的任务	“Show active async runs.”
检查设置	“Check whether subagents are configured correctly.”

扩展附带了一些内置 agent，你可以立即使用。

内置 agent 通俗说明

Agent	当你需要...时使用
scout	快速的本地代码库侦察：相关文件、入口点、数据流、风险，以及另一个 agent 应该从哪里开始。
researcher	带来源的 Web/文档研究：官方文档、规范、基准测试、近期变更，以及一份简洁的研究简报。
planner	基于现有上下文的具体实现计划。它应该阅读和计划，而不是编辑代码。
worker	实现工作，包括已批准的 oracle 交接单。它编辑文件、验证，并在遇到未批准的决策时上报，而不是猜测。
reviewer	代码审查和小型修复。它检查实现是否遵循任务/计划、测试、边界情况和简洁性。
context-builder	在计划前进行更强的设置：收集代码上下文并编写交接材料，如 context.md 和 meta-prompt.md。
oracle	行动前征求第二意见。它挑战假设、捕捉偏差，并推荐最安全的下一个行动而不进行编辑。
delegate	当你需要一个行为接近父会话的轻量级通用委托 agent 时使用。

简单的经验法则：在理解代码前使用 scout，在信任外部事实前使用 researcher，在进行较大改动前使用 planner，用 worker 实现，用 reviewer 检查，当决策本身感觉有风险时使用 oracle。

更改内置 agent 的模型

内置 agent 默认继承你当前的 Pi 默认模型。这可以避免新安装依赖于你可能尚未配置的 provider。如果你希望某个角色使用特定模型，请设置覆盖，而不是复制捆绑的 agent 文件。

单次运行，在命令中设置覆盖：

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

持久覆盖，编辑设置。以下示例将 reviewer 固定在一个模型上，为 provider 故障添加备份模型，同时保持其他内置 agent 使用你的常规默认模型：

{
  "subagents": {
    "agentOverrides": {
      "reviewer": {
        "model": "anthropic/claude-sonnet-4",
        "thinking": "high",
        "fallbackModels": ["openai/gpt-5-mini"]
      }
    }
  }
}

使用 ~/.pi/agent/settings.json 作为用户覆盖，或 .pi/settings.json 作为项目覆盖。相同的 agentOverrides 块可以更改 tools、skills、继承的上下文、提示文本，或禁用某个内置 agent。如果你需要一个完全不同的 agent，请在用户或项目范围内创建同名的 agent；对于常规调整，优先使用覆盖。

运行中的 subagent 显示在哪里

前台运行会在运行时将进度流式显示在对话中。

后台运行在控制权返回给你后继续工作。使用 subagent({ action: "status" }) 检查活动运行，或使用 subagent({ action: "status", id: "..." }) 检查特定运行。

它们还会显示一个紧凑的异步小部件，并发送完成通知。并行后台运行会显示每个 agent 的进度，而不是虚假的链步骤。带有并行组的链会在进度和结果中保持分组形状，因此失败或暂停的 agent 会与已完成的 agent 一同可见。当子 agent 被显式允许通过 tools: subagent 进行扇出时，其嵌套运行会出现在主状态树中该父子项下，而不是隐藏在子进程内部。

你也可以自然地问：

Show me the current async runs.

如果感觉配置有问题，运行：

/subagents-doctor

或询问：

Check whether subagents and intercom are set up correctly.

推荐的编排模式（脚手架）

将编排用作父 agent 的指导，而不是运行时的工作流模式。对于实现工作，推荐的循环是：

clarify → planner → worker → fresh reviewers → worker

当你希望模式可重复时，可以使用下面可选提示快捷方式。

打包的 planner、worker 和 oracle 在启动时如果省略 context，默认使用分叉上下文（forked context）；当你故意想要一个全新的子运行时，传递 context: "fresh"。

子安全边界在运行时强制执行。生成的子会话不会获得捆绑的 pi-subagents 技能，并且分叉子上下文过滤会移除仅父 agent 的 subagent 工件（包括旧的隐藏编排指令消息、斜杠/状态/控制消息，以及先前的父 subagent 工具调用/工具结果历史），同时保留普通散文和不相关的工具调用/结果。默认情况下，子 agent 不会注册 subagent 工具，并收到边界指令：它们不是父编排器，不得提议或运行 subagent。显式例外是其解析后的内置 tools 包含 subagent 的 agent；该子 agent 会获得一个子安全的 subagent 工具，用于父 agent 分配的扇出工作，并受 maxSubagentDepth 限制。

可选快捷方式

该包包含用于常见工作流的可复用提示模板。你不需要它们，但当你想每次使用相同结构时，它们很方便：

提示	用途
/parallel-review	启动具有不同角度且使用全新上下文的审查者，然后综合需要修复的内容。
/review-loop	运行父控制的 worker、reviewer 和 fix-worker 循环，直到干净或达到上限。
/parallel-research	结合 researcher 和 scout，获取外部证据、本地代码上下文和实际权衡。
/parallel-context-build	并行运行 context-builder agent，生成计划交接上下文和元提示。
/parallel-handoff-plan	结合外部研究和 context-builder 传递，生成实现交接计划和元提示。
/gather-context-and-clarify	先侦查/研究，然后向用户提出真正重要的澄清问题。
/parallel-cleanup	实现后仅运行审查清理。

在 /parallel-review 或 /parallel-cleanup 中添加 autofix，以便在审查者返回后仅应用当前值得做的综合修复。

可选的 pi-intercom 伴侣

pi-subagents 可以在没有 pi-intercom 的情况下工作。只有当你希望子 agent 在运行时向父 Pi 会话回传消息时，才安装 pi-intercom。

pi install npm:pi-intercom

大多数用户不会直接调用 intercom。安装 pi-intercom 后，pi-subagents 可以自动为子 agent 提供一个私有的协调通道，连接回父会话。该桥接器识别正常的 pi install npm:pi-intercom 包安装以及旧版的本地扩展检出。

在子 agent 可能需要做出决策而不是猜测时使用：

Run this implementation in the background. If the worker gets blocked or needs a product decision, have it ask me through intercom.

Ask oracle to review this plan. If it sees a decision I need to make, have it ask me instead of assuming.

子 agent 可以使用一个专用的协调工具：

• contact_supervisor：子 agent 联系分派任务的父/监督者会话。对于阻塞性决策或澄清，使用 reason: "need_decision"；对于发现改变计划时的简短非阻塞更新，使用 reason: "progress_update"。当唯一的冲突是仅审查/不编辑与进度写入或工件写入指令时，不要求澄清；不编辑优先。

子侧的常规完成交接仍然不被期望。在 intercom 桥接器激活的情况下，父侧的 pi-subagents 会将分组的完成结果通过 pi-intercom 发送：每个前台父 subagent 运行发送一条分组消息，每个完成的异步结果文件发送一条。确认的前台投递会返回一个紧凑回执，包含工件/会话路径；如果未确认，则保留正常完整输出。分组消息包含子 intercom 目标、完整的子摘要，以及启动它们的父子项下的紧凑嵌套子摘要。

如果子 agent 似乎停滞或需要注意，父会话中可能会出现通知，显示有用的下一步操作，例如检查 subagent({ action: "status" })、中断运行或推动子 agent。

如果消息没有显示，运行：

/subagents-doctor

对于正常使用，你不需要配置任何东西。高级用户可以在下面的配置部分使用 intercomBridge 进行调整。

到此，你已经了解足够多的信息来使用该插件。本 README 的其余部分是精确命令语法、自定义 agent、保存的链、工作树（worktrees）和配置的参考材料。

直接命令

在需要精确语法之前，跳过本节。

命令	描述
/run <agent> [task]	运行一个 agent；对于自包含的 agent 可省略 task
/chain agent1 "task1" -> agent2 "task2"	按顺序运行 agent
/parallel agent1 "task1" -> agent2 "task2"	并行运行 agent
/run-chain <chainName> -- <task>	启动保存的 .chain.md 或 .chain.json 工作流
/subagents-doctor	显示只读的设置诊断

命令在本地验证 agent 名称，支持 Tab 补全，并将结果返回对话。

每步任务

使用 -> 分隔步骤，并为每个步骤分配自己的任务：

/chain scout "scan the codebase" -> planner "create an implementation plan"
/parallel scanner "find security issues" -> reviewer "check code style"

双引号和单引号都可用。你也可以使用 -- 作为分隔符：

/chain scout -- scan code -> planner -- analyze auth

没有任务的步骤会继承执行模式的行为。链步骤获得 {previous}，即前一个步骤的输出。并行步骤使用第一个可用的任务作为后备。

/chain scout "analyze auth" -> planner -> worker
# scout 得到 "analyze auth"；planner 得到 scout 的输出；worker 得到 planner 的输出

对于共享任务，列出 agent 并在任务前放置一个 --：

/chain scout planner -- analyze the auth system
/parallel scout reviewer -- check for security issues

内联每步配置

在 agent 名称后附加 [key=value,...] 来覆盖该步骤的默认值：

/chain scout[output=context.md] "scan code" -> planner[reads=context.md] "analyze auth"
/run scout[model=anthropic/claude-sonnet-4] summarize this codebase
/parallel reviewer[skills=code-review+security] "review backend" -> reviewer[model=openai/gpt-5-mini] "review frontend"

Key	示例	描述
output	output=context.md	将结果写入文件。对于 /chain 和 /parallel，相对路径位于链目录下；对于 /run，相对路径相对于 cwd 解析。
outputMode	outputMode=file-only	返回保存的输出的简洁文件引用，而不是完整内容。需要 output；默认为 inline。
reads	reads=a.md+b.md	在执行前读取文件。+ 分隔多个路径。
model	model=anthropic/claude-sonnet-4	覆盖该步骤的模型。
skills	skills=planning+review	覆盖注入的技能。+ 分隔多个技能。
progress	progress	启用进度追踪。

设置 output=false、reads=false 或 skills=false 显式禁用该行为。不要使用 output=false 进行仅文件返回；应使用 outputMode=file-only 并配合 output 路径。

后台与分叉运行

添加 --bg 在后台运行：

/run scout "audit the codebase" --bg
/chain scout "analyze auth" -> planner "design refactor" -> worker --bg
/parallel scout "scan frontend" -> scout "scan backend" --bg

添加 --fork 从父会话的当前叶节点创建一个真正的分支会话，作为每个子会话的起点：

/run reviewer "review this diff" --fork
/chain scout "analyze this branch" -> planner "plan next steps" --fork
/parallel scout "audit frontend" -> reviewer "audit backend" --fork

可以按任意顺序组合：

/run reviewer "review this diff" --fork --bg
/run reviewer "review this diff" --bg --fork

后台运行是分离的。如果父 agent 有其他独立工作，它应该继续工作。如果它在后台结果到达之前没有有用的事情可做，它应该结束当前轮次，而不是运行睡眠或状态轮询循环。Pi 会在运行完成时投递完成通知。

oracle 和 worker 内置 agent 被设计为显式决策循环。典型的模式是：先让 oracle 进行诊断并推荐执行提示，然后只在主 agent 批准该方向后运行 worker。

澄清与启动 UI

链默认打开一个澄清 UI，以便你在运行前预览和编辑工作流。单个工具调用和并行工具调用可以通过 clarify: true 选择进入相同流程；斜杠命令直接启动。

常见的澄清快捷键：

• Enter：前台运行，如果开启了后台则后台运行
• Esc：取消或退出
• ↑↓：在步骤或任务之间移动
• e：编辑任务/模板
• m：选择模型
• t：选择思考级别
• s：选择技能
• b：切换后台执行
• w：编辑输出/写入行为（如果支持）
• r：编辑读取（如果支持）
• p：切换进度追踪（如果支持）

选择器屏幕使用 ↑↓、Enter、Esc 和输入过滤。全屏编辑器支持自动换行、粘贴、Esc 保存和 Ctrl+C 放弃。

Agent 与链

Agent 是带有 YAML 前置元数据和系统提示主体（system prompt body）的 markdown 文件。它们定义了将在子 Pi 进程中运行的专业角色。

Agent 位置，从低到高优先级：

范围	路径
内置（Builtin）	~/.pi/agent/extensions/subagent/agents/
用户（User）	~/.pi/agent/agents/**/*.md
项目（Project）	.pi/agents/**/*.md

项目发现也会读取旧版的 .agents/**/*.md 文件。嵌套的子目录会被递归发现。.chain.md 文件不定义 agent。如果 .agents/ 和 .pi/agents/ 定义了相同的解析后运行时 agent 名称，则 .pi/agents/ 获胜。使用 agentScope: "user" | "project" | "both" 控制发现范围；both 是默认值，项目定义在运行时名称冲突中获胜。

内置 agent 以最低优先级加载，因此同名的用户或项目 agent 会覆盖它们。它们不固定 provider 模型；除非你设置了 subagents.agentOverrides.<name>.model，否则它们会继承你当前的 Pi 默认模型。oracle 是一个顾问审查者，它批判方向并提出执行提示而不编辑文件。worker 是用于常规任务和已批准的 oracle 交接单的实现 agent。

researcher 内置 agent 使用 web_search、fetch_content 和 get_search_content；这些需要 pi-web-access：

pi install npm:pi-web-access

内置覆盖

你可以覆盖选定的内置字段，而无需复制整个 agent。覆盖位于设置中：

• 用户：~/.pi/agent/settings.json
• 项目：.pi/settings.json

示例：

{
  "subagents": {
    "agentOverrides": {
      "reviewer": {
        "inheritProjectContext": false
      }
    }
  }
}

支持的覆盖字段有 model、fallbackModels、thinking、systemPromptMode、inheritProjectContext、inheritSkills、defaultContext、disabled、skills、tools 和 systemPrompt。在内置覆盖中使用 defaultContext: false 清除继承的上下文默认值。项目覆盖优于用户覆盖。

设置 disabled: true 可将内置 agent 从运行时发现和面向 agent 的 subagent({ action: "list" }) 输出中隐藏。要进行批量控制，在设置中设置 subagents.disableBuiltins: true。

提示组装

Subagent 默认设计为窄聚焦。自定义 agent 以干净的系统提示开始，只包含你有意赋予的上下文。它们不会自动继承 Pi 的整个基础提示、项目指令文件或发现的技能目录。

当 agent 应该看到更多时，使用以下字段：

字段	效果
systemPromptMode: append	将 agent 提示附加到 Pi 的正常基础提示后面。
inheritProjectContext: true	保留从 AGENTS.md 和 CLAUDE.md 等文件继承的项目指令。
inheritSkills: true	让子 agent 看到 Pi 发现的技能目录。
defaultContext: fork	当启动时省略 context 时，使用分叉会话上下文；显式的 context: "fresh" 仍然优先。

内置 agent 默认选择继承项目指令，因此它们开箱即用地遵循仓库特定规则。delegate 还使用追加模式，因为它的任务是在父工作流中进行编排。

Agent 前置元数据

一个典型的 agent 如下所示：

---
name: scout
# 可选：注册为 code-analysis.scout，同时保留 name: scout
package: code-analysis
description: Fast codebase recon
tools: read, grep, find, ls, bash, mcp:chrome-devtools
extensions:
model: claude-haiku-4-5
fallbackModels: openai/gpt-5-mini, anthropic/claude-sonnet-4
thinking: high
systemPromptMode: replace
inheritProjectContext: false
inheritSkills: false
skills: safe-bash, chrome-devtools
output: context.md
defaultReads: context.md
defaultProgress: true
completionGuard: false
interactive: true
maxSubagentDepth: 1
---

Your system prompt goes here.

重要字段：

字段	说明
package	可选包标识符。一个 name: scout 且 package: code-analysis 的文件注册为 code-analysis.scout；序列化保持 name 和 package 独立。
tools	内置工具允许列表。mcp: 条目在安装 pi-mcp-adapter 时选择直接的 MCP 工具。
extensions	省略表示正常扩展；空表示无扩展；逗号分隔的值允许特定扩展。
model	默认模型。裸 ID 在可能时优先使用当前 provider，然后是唯一注册表匹配。
fallbackModels	针对 provider/模型故障（如配额、认证、超时或模型不可用）的有序备份模型。普通任务失败不会触发回退。
thinking	运行时作为 :level 后缀附加，除非已存在后缀。
systemPromptMode	默认为 replace；append 保留 Pi 的基础提示。
inheritProjectContext	保留或移除继承的项目指令块。
inheritSkills	保留或移除 Pi 发现的技能目录。
defaultContext	该 agent 的可选 fresh 或 fork 启动上下文默认值。
skills	直接注入特定技能，不受 inheritSkills 影响。
output	默认单 agent 输出文件。
defaultReads	在链/并行行为之前要读取的文件。
defaultProgress	维护 progress.md。
completionGuard	仅对非实现 agent 设为 false，这些 agent 可能在使用 bash 等具有修改能力的工具时提到实现相关词汇。
interactive	为兼容性解析，但在 v1 中不强制。
maxSubagentDepth	收紧该 agent 子项的嵌套委托限制。

工具和扩展选择

如果省略 tools，pi-subagents 不会传递 --tools，因此子 agent 获得 Pi 的普通内置工具。如果存在 tools，常规工具名称变为显式允许列表。mcp: 条目被分离出来并作为直接 MCP 选择转发。路径形式的 tools 条目，如扩展路径或 .ts/.js 文件，被视为工具扩展路径，而不是内置工具名称。只声明已知只读内置工具的 agent 会跳过实现完成守卫，但 bash、未知工具和 MCP 工具仍然具有修改能力。对于启用了 bash 的验证器或顾问，它们绝不应被判定为实现 agent，请使用 completionGuard: false。

示例：

• tools 省略且 extensions 省略：正常内置工具和正常扩展。
• tools: mcp:chrome-devtools：正常内置工具加上直接的 Chrome DevTools MCP 工具。
• tools: read, bash, mcp:chrome-devtools：只有 read 和 bash 作为内置工具，加上直接的 Chrome DevTools MCP 工具。
• tools: subagent, read：该子 agent 内部存在一个子安全的 subagent 工具，因此它可以运行显式分配的嵌套扇出。

直接 MCP 工具需要 pi-mcp-adapter。Subagent 只在其前置元数据中列出了 mcp: 条目时才会收到直接 MCP 工具；全局 directTools: true 在 mcp.json 中本身不足够。仍可使用通用 mcp 代理工具进行发现（如果可用）。适配器在启动时缓存工具元数据，因此在首次连接新的 MCP 服务器后，在依赖直接工具之前重启 Pi。名为 subagent 的 mcp: 条目不会授权嵌套扇出；只有内置的 subagent 工具名称才会。

extensions 控制子扩展加载：

# 省略：所有正常扩展加载

# 空：无扩展
extensions:

# 允许列表
extensions: /abs/path/to/ext-a.ts, /abs/path/to/ext-b.ts

当存在 extensions 时，它优先于由 tools 条目隐含的扩展路径。

链文件

链是独立于 agent 文件存储的可复用工作流。对于简单的顺序保存链，使用 .chain.md。当链需要动态扇出时，使用 .chain.json。

范围	路径
用户	~/.pi/agent/chains/**/*.chain.md，~/.pi/agent/chains/**/*.chain.json
项目	.pi/chains/**/*.chain.md，.pi/chains/**/*.chain.json

嵌套子目录会被递归发现。如果 .chain.md 和 .chain.json 在同一范围内定义了相同的解析后运行时链名称，则 .chain.json 获胜。如果用户和项目范围定义了相同的解析后运行时链名称，则项目链获胜。链支持与 agent 相同的可选 package 前置元数据；name: review-flow 加 package: code-analysis 以 code-analysis.review-flow 运行。

示例：

---
name: scout-planner
description: Gather context then plan implementation
---

## scout
phase: Context
label: Map auth flow
as: context
output: context.md

Analyze the codebase for {task}

## planner
phase: Planning
label: Implementation plan
reads: context.md
model: anthropic/claude-sonnet-4-5:high
progress: true

Create an implementation plan based on {outputs.context}

每个 .chain.md 中的 ## agent-name 部分是一个步骤。配置行如 phase、label、as、outputSchema、output、outputMode、reads、model、skills 和 progress 直接跟在标题之后。空白行分隔配置和任务文本。在保存的 .chain.md 文件中，outputSchema 是 JSON Schema 文件的路径；直接工具调用和 .chain.json 文件可以内联传递 schema 对象。

对于 output、reads、skills 和 progress，链行为是三种状态：省略则继承 agent 的，值覆盖，false 禁用。

使用 phase 在状态输出中对相关工作分组，label 作为可读的步骤名称，as 存储成功步骤或并行任务的结果，以便稍后通过 {outputs.name} 引用。重复的 as 名称、无效标识符和未知的输出引用会在子执行之前失败。

动态扇出仅可通过直接 subagent({ chain: [...] }) JSON 或保存的 .chain.json 文件使用。它从一个先前结构化命名输出中展开一个数组，为每个项目运行一个子模板，并将有序集合存储在 collect.as 下。源必须是结构化输出；纯文本永远不会被解析。expand.maxItems 是必需的，超出限制的数组会失败，不支持嵌套扇出和任意表达式，并且 .chain.md 在此版本中没有动态语法。

{
  "name": "dynamic-review",
  "description": "Find review targets, fan out reviewers, then synthesize.",
  "chain": [
    {
      "agent": "scout",
      "task": "Return {\"items\":[{\"path\":\"...\",\"reason\":\"...\"}]} via structured_output.",
      "as": "targets",
      "outputSchema": { "type": "object" }
    },
    {
      "expand": {
        "from": { "output": "targets", "path": "/items" },
        "item": "target",
        "key": "/path",
        "maxItems": 12
      },
      "parallel": {
        "agent": "reviewer",
        "label": "Review {target.path}",
        "task": "Review {target.path}. Reason: {target.reason}",
        "outputSchema": { "type": "object" }
      },
      "collect": { "as": "reviews" },
      "concurrency": 4
    },
    {
      "agent": "worker",
      "task": "Synthesize fixes from {outputs.reviews}"
    }
  ]
}

通过直接写入文件或使用 subagent({ action: "create", config: ... }) 管理操作来创建简单的 .chain.md 链。通过直接写入 JSON 文件来创建动态的 .chain.json 链。使用自然语言或以下命令运行保存的链：

/run-chain scout-planner -- refactor authentication

链变量

任务模板支持：

变量	描述
{task}	第一步的原始任务。
{previous}	前一步的输出，或并行步骤的聚合输出。
{chain_dir}	链工件目录的路径。
{outputs.name}	来自先前步骤或带有 as: "name" 的已完成并行任务的文本值。

并行输出在传递给下一步之前会用清晰的分隔符聚合：

=== Parallel Task 1 (worker) ===
...

=== Parallel Task 2 (worker) ===
...

技能

技能是注入到 agent 系统提示中的 SKILL.md 文件。

发现使用项目优先的顺序：

1. .pi/skills/{name}/SKILL.md
2. 项目包和项目设置包，通过 package.json -> pi.skills
3. 当前任务 cwd 包，通过 package.json -> pi.skills
4. .pi/settings.json -> skills
5. ~/.pi/agent/skills/{name}/SKILL.md
6. 用户包和用户设置包，通过 package.json -> pi.skills
7. ~/.pi/agent/settings.json -> skills

使用 agent 默认值，在运行时覆盖它们，或禁用它们：

{ agent: "scout", task: "..." }
{ agent: "scout", task: "...", skill: "tmux, safe-bash" }
{ agent: "scout", task: "...", skill: false }

对于链，顶级 skill 是追加的。步骤级别的 skill 覆盖该步骤；false 禁用该步骤的技能。

注入的技能使用以下形状：

<skill name="safe-bash">
[skill content from SKILL.md, frontmatter stripped]
</skill>

缺失的技能不会导致执行失败。结果摘要会显示警告。

捆绑技能

该包捆绑了一个 pi-subagents 技能，当扩展安装后，该技能对父 agent 自动可用。它仅适用于编排父 agent：子 subagent 永远不会收到它，它们的上下文会被显式过滤，以移除仅父 agent 的编排指令。

捆绑技能涵盖的内容：

• 委托模式：何时启动哪个 agent，是否使用单模式、并行、链或异步模式，以及是否使用全新或分叉上下文
• 提示工作流配方：如何将打包的技术直接与 subagent(...) 配合使用，当用户用自然语言描述工作流而不是调用斜杠命令时。这包括并行审查、审查循环、并行研究、并行上下文构建、并行交接计划、收集上下文并澄清，以及并行清理
• 角色 agent 提示指导：紧凑的契约提示而非长脚本，角色特定元提示中应包含什么，以及研究者的检索预算
• 安全边界：子 agent 不得运行 subagent，除非其解析后的内置工具显式包含 subagent；不得发明 intercom 目标；必须上报未批准的决策
• Intercom 约定：何时询问 vs 发送，以及父侧结果交付如何与 pi-intercom 协作
• 控制和诊断：注意信号、软中断、状态和 doctor 动作

如果你正在编写编排 subagent 的 agent，捆绑技能有助于它正确行为，而无需猜测模式。如果你是人工用户，则无需直接阅读它；README 和提示快捷方式已以面向用户的形式编码了相同的工作流。

程序化工具用法

以下是 LLM 在调用 subagent 工具时传递的参数。大多数用户使用自然语言或斜杠命令。

执行示例

// 单 agent
{ agent: "worker", task: "refactor auth" }
{ agent: "scout", task: "find todos", maxOutput: { lines: 1000 } }
{ agent: "scout", task: "investigate", output: false }
{ agent: "scout", task: "write a large report