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

智能体（agent）是一个 Markdown 文件：顶部是 YAML frontmatter，下方是系统提示词。Frontmatter 定义了作为子会话运行的专家角色。

---
name: scout
description: Fast codebase recon
tools: read, grep, find, ls
---
Your system prompt goes here.

智能体的存放位置

按优先级从低到高：

作用域	路径
内置	~/.pi/agent/extensions/subagent/agents/
已安装包	package.json 的 pi-subagents.agents 或 pi.subagents.agents
用户级	~/.pi/agent/agents/**/*.md
项目级	项目配置 agents/**/*.md（标准 Pi 中为 .pi/agents/**/*.md）

发现规则说明：

• 项目发现还会顺带读取旧的 .agents/**/*.md 文件。若 .agents/ 与项目配置智能体目录同时定义了解析后运行时名称相同的智能体，则项目配置目录胜出。
• 嵌套子目录以递归方式发现。.chain.md 文件不定义智能体。
• 用户和项目设置可通过 subagents.agentScanDirs 添加额外的递归扫描根目录；固定的用户/项目智能体目录优先级仍高于同名的扫描根目录中的智能体。
• 使用 subagents.agentExcludeDirs 裁剪字面意义上的目录子树，但不会禁用旧版智能体。路径解析规则、作用域和豁免项见 configuration.md。
• 已安装的 Pi 包可通过包清单中的 {"pi-subagents":{"agents":["./agents"]}} 或 {"pi":{"subagents":{"agents":["./agents"]}}} 暴露智能体目录。包级智能体的加载优先级在内置之上、用户/项目智能体之下。
• 使用 agentScope: "user" | "project" | "both" 控制发现范围。both 为默认值，发生运行时名称冲突时项目定义胜出。

内置智能体

内置智能体以最低优先级加载，因此同名的用户或项目智能体会覆盖它们。它们不绑定某个提供方模型；除非设置了 subagents.defaultModel 或 subagents.agentOverrides.<name>.model，否则它们会沿用你当前的 Pi 默认模型（参见 models.md）。

智能体	适用场景（你想要……时用它）
scout	快速在本地代码库做勘察：相关文件、入口点、数据流、风险点，以及另一个智能体该从哪里入手。
researcher	带来源的 Web/文档调研：官方文档、规范、基准、最近变更，并输出一份简洁的调研简报。
evidence-auditor	对现有调研简报中重要论断做独立证据复核。
worker	实现类工作，包括已批准的 oracle 交接。它会编辑文件、做校验，并在遇到未批准决策时上报而不是自行猜测。
reviewer	代码评审和小幅修复。它对照任务/计划、测试、边界情况和简洁性来检查实现。
oracle	行动前的第二意见。它会质疑假设、捕捉偏差，并推荐最稳妥的下一步，但不会编辑文件。
delegate	一个轻量的通用委派者，当你希望某个子智能体的行为接近父会话时使用。

经验法则：在你还不了解代码时用 scout，在你要采信外部事实前用 researcher，在你要依赖重要调研结论前用 evidence-auditor，实现用 worker，检查用 reviewer，而当决策本身让你感到有风险时用 oracle。

oracle 是一个咨询型评审者，批判方向并提出执行提示词，但不会编辑文件。advisor 是同一打包角色在 Claude Code 兼容命名下的别名。

可选的 Surf 集成

当 surf-cli 已安装并加载时，Surf 可以通过 surf-oracle 外部任务提供方暴露一个 gpt-pro 包级智能体。它通过与任何其他智能体相同的 subagent({ agent: "gpt-pro" }) 心智模型启动，但智能体与提供方由 Surf 拥有。Surf 将 model: pro 映射到 ChatGPT GPT-5.6 Sol Pro Web 模式。pi-subagents 不拥有该模型映射。

如果你曾用 agentOverrides.gpt-pro.disabled 禁用了旧版内置的 gpt-pro 兜底，请在使用 Surf 的包级智能体前移除该覆盖。

Pi 异步运行仍是状态、产物、唤醒/等待、任务记录挂接、保留和诊断信息的权威来源。

咨询型运行器的数据边界

外部 CLI 智能体使用各自的运行器契约。它们是有意为之的执行模式，并不是原生 subagent 工作流失败时的隐式恢复路径。对于待办工作泳道和其他由子智能体管理的工作流，切换到外部、前台或 CLI 运行器，都需要先明确记录具体的失败/运行/工作树状态，并确认工作树干净或已捕获其部分差异，然后再经显式的所有者批准。不要传入原生的 Pi 子选项，例如模型覆盖、结构化输出、验收/智能体契约、工具预算、快速模式、分叉上下文、技能或原生 Pi 工具，除非适配器显式实现了它们。

内置的 codex-exec 和 codex-exec-writer 配置档是受支持的 Codex 一次性执行模式。两者都要求安装并完成身份验证的 Codex CLI。适配器自行管理 codex exec --json 的 argv（忽略用户配置与规则）、临时会话、审批策略 never，以及一条最终消息产物。

配置档	访问权限	沙箱
codex-exec	只读分析	read-only
codex-exec-writer	显式工作区编辑	workspace-write

两种适配器都不使用完全访问权限、审批或沙箱绕过、自动审批复核，也不增加额外的可写根目录。用户配置档无法追加 argv。codex-exec 这一选择标识符保留给只读适配器。

以异步方式运行：

Use codex-exec to analyze this change without editing files.

Use codex-exec-writer to make the requested workspace changes.

适配器仅在运行启动时校验 codex --version 与 codex exec --help。发现、列表、状态以及原生 Pi 启动都不会执行 Codex 或其版本/帮助探测。能力清单只执行被动的 PATH/PATHEXT/X_OK 查询，并将该命令暴露为 runner.available；这并不能证明身份验证或启动兼容性。JSONL、stderr 和 stdout 一律视为不可信。只有在受约束的有效 JSONL 内包含一条 turn.completed 事件、且受约束的最终消息产物存在时，运行才算成功。

维护者可以收集真实的烟雾测试证据，但不必将其纳入常规测试套件：

PI_SUBAGENTS_CODEX_EXEC_SMOKE=1 \
PI_SUBAGENTS_CODEX_EXEC_SMOKE_REPORT=/tmp/pi-subagents-codex-exec-smoke.json \
node --experimental-strip-types --import ./test/support/register-loader.mjs \
  --test test/integration/codex-exec-smoke.test.ts

PI_SUBAGENTS_CODEX_EXEC_WRITER_SMOKE=1 \
PI_SUBAGENTS_CODEX_EXEC_WRITER_SMOKE_REPORT=/tmp/pi-subagents-codex-exec-writer-smoke.json \
node --experimental-strip-types --import ./test/support/register-loader.mjs \
  --test test/integration/codex-exec-writer-smoke.test.ts

只读烟雾测试必须报告 writeCanaryExists: false。写入烟雾测试必须报告 writeCanaryMatches: true。两份报告均包含启动耗时与终态证明，但不包含原始协议输出、提示词或凭据。

内置的 claude-code 和 claude-code-writer 配置档是受支持的 Claude Code 一次性执行模式。两者都要求安装 Claude Code CLI，且已通过其常规本地登录完成身份验证。Claude Code 2.1.150 需要用户级设置源来实现常规 OAuth/钥匙串身份验证，因此两种适配器都会加载用户级设置，但排除项目级和本地级设置。因此，用户级 Claude Code 设置与钩子（hook）属于运维人员必须信任的前置条件。在使用任一配置档前，请检查或禁用不安全的用户级钩子。

配置档	访问权限	权限模式	内置工具
claude-code	仅交接的只读建议	plan	无
claude-code-writer	显式工作区文件编辑	acceptEdits	Read,Write,Edit,Glob,Grep

两种适配器都自行管理 claude -p 的 argv，包括流式 JSON、严格的空 MCP 配置、仅用户级设置源、不持久化会话、禁用斜杠命令、禁用 Chrome 集成。写入模式不包含 Bash 或任何权限绕过。两种模式都不使用 --bare，因为它不会读取常规 OAuth/钥匙串身份验证。两种模式都不要求 --safe-mode，因为它不出现在已安装的 2.1.150 帮助中。用户配置档无法追加 argv。选择由代码所有的 claude-code-writer 适配器标识是启用其写入工具的唯一方式；只读适配器无法通过用户 argv 扩展。

以异步方式运行：

Use claude-code to analyze this handoff without editing files.

Use claude-code-writer to make the requested file changes.

适配器仅在运行启动时校验 claude --version 与 claude --help。发现、列表、状态以及原生 Pi 启动都不会执行 Claude Code 或探测其身份验证。能力清单只执行被动的 PATH/PATHEXT/X_OK 查询，并将该命令暴露为 runner.available；这并不能证明身份验证或启动兼容性。JSONL、stderr 和 stdout 一律视为不可信。只有在受约束的有效 JSONL 内恰好包含一条成功的终态 result、且最终文本非空时，运行才算成功。缺失或被撤销的本地身份验证、限流停止、格式错误的 JSON、重复的终态结果、以及在终态结果之前的 EOF 都会触发失败闭合。

维护者可分别对只读和写入烟雾探针进行选择性启用：

PI_SUBAGENTS_CLAUDE_CODE_SMOKE=1 \
PI_SUBAGENTS_CLAUDE_CODE_SMOKE_REPORT=/tmp/pi-subagents-claude-code-smoke.json \
node --experimental-strip-types --import ./test/support/register-loader.mjs \
  --test test/integration/claude-code-smoke.test.ts

PI_SUBAGENTS_CLAUDE_CODE_WRITER_SMOKE=1 \
PI_SUBAGENTS_CLAUDE_CODE_WRITER_SMOKE_REPORT=/tmp/pi-subagents-claude-code-writer-smoke.json \
node --experimental-strip-types --import ./test/support/register-loader.mjs \
  --test test/integration/claude-code-writer-smoke.test.ts

两份烟雾报告都会记录 authentication: "existing-cli-required"、settingSources: "user" 与 userSettingsTrust: "required"，而不记录凭据细节。对于只读，请确认 terminalState 为 completed，且 writeCanaryExists 为 false。对于写入，请确认 terminalState 为 completed，且 writeCanaryMatches 为 true。durationMs 记录冷启动进程耗时。若身份验证缺失或被撤销，请修复常规本地 Claude Code 登录后重新运行烟雾测试。报告不包含原始协议输出或凭据。

内置的 cursor-agent 与 cursor-agent-writer 配置档是受支持的 Cursor CLI 一次性执行模式。两者都要求安装 Cursor CLI，且具备 CURSOR_API_KEY 或现有的本地登录。

配置档	访问权限	Cursor 模式
cursor-agent	只读分析	ask
cursor-agent-writer	显式工作区编辑	non-interactive print

两种适配器都使用流式 JSON、已启用的沙箱以及主工作区。它们将完整的交接内容写入一个私有临时目录下的 0600 权限文件。进程 argv 只包含指向该路径的简短指令。只有当该临时目录位于主工作区之外时，才会被添加为工作区根目录。提示词文件与目录会在完成、失败或停止后被移除。

适配器不会传入 force、yolo、auto-review、MCP 审批、插件、会话恢复、continue、工作树或工作区信任等标志。用户配置档无法追加 argv 或工作区根目录。cursor-agent 这一选择标识符保留给只读适配器。

启动预检仅在运行启动时校验 cursor-agent --version 与 cursor-agent --help。发现、列表、状态以及原生 Pi 启动都不会执行 Cursor 或探测其身份验证。能力清单只执行被动的 PATH/PATHEXT/X_OK 查询，并将该命令暴露为 runner.available；这并不能证明身份验证或启动兼容性。只有在受约束的有效 JSONL 以一条带非空最终文本的成功 result 事件结束时，运行才算成功。错误事件、失败的结果、格式错误的 JSON、终态事件之后的输出，以及在结果之前的 EOF 都会触发失败闭合。

这些无头烟雾测试依赖已保存的工作区信任。Cursor 文档中没有任何被动的命令可用于检查工作区信任，因此烟雾测试在启动前无法验证它。运维人员必须对恰好的一次性工作区和恰好派生的提示词目录 <state-root>/external-0.cursor-prompt 使用 Cursor 的交互式信任流程。完成信任步骤后，请保留该提示词目录。该目录必须为空、由运行烟雾测试的运维人员所有，且不得为符号链接。测试夹具会保留该目录，并以独占的 0600 权限创建其私有交接内容，并在每次运行后移除该交接内容。若任意一个精确路径发生变化，请重新执行信任设置。

烟雾测试要求两个已存在的、由运维人员分别管理的目录，以及一份显式的一次性工作区声明：

export PI_SUBAGENTS_CURSOR_SMOKE_WORKSPACE=/tmp/pi-subagents-cursor-smoke-workspace
export PI_SUBAGENTS_CURSOR_SMOKE_STATE_ROOT=/tmp/pi-subagents-cursor-smoke-state
export PI_SUBAGENTS_CURSOR_SMOKE_DISPOSABLE=1
mkdir -p "$PI_SUBAGENTS_CURSOR_SMOKE_WORKSPACE" "$PI_SUBAGENTS_CURSOR_SMOKE_STATE_ROOT"
mkdir -p "$PI_SUBAGENTS_CURSOR_SMOKE_STATE_ROOT/external-0.cursor-prompt"

请勿在工作区中放置 pi-subagents-cursor-write-canary.txt 文件，也勿在提示词目录中放置任何文件（包括 handoff.txt）。测试夹具会拒绝预先存在的探针文件和任何非空的提示词目录。它不会删除工作区、状态根目录或运维人员所有的提示词目录；只会移除其自身的探针文件和私有交接文件。

随后，维护者可以分别运行只读和写入的探针：

PI_SUBAGENTS_CURSOR_AGENT_SMOKE=1 \
PI_SUBAGENTS_CURSOR_AGENT_SMOKE_REPORT=/tmp/pi-subagents-cursor-agent-smoke.json \
node --experimental-strip-types --import ./test/support/register-loader.mjs \
  --test test/integration/cursor-agent-smoke.test.ts

PI_SUBAGENTS_CURSOR_AGENT_WRITER_SMOKE=1 \
PI_SUBAGENTS_CURSOR_AGENT_WRITER_SMOKE_REPORT=/tmp/pi-subagents-cursor-agent-writer-smoke.json \
node --experimental-strip-types --import ./test/support/register-loader.mjs \
  --test test/integration/cursor-agent-writer-smoke.test.ts

只读烟雾测试必须报告 writeCanaryExists: false。写入烟雾测试必须报告 writeCanaryMatches: true。两份报告都会记录 workspaceTrust: "operator-managed-saved"，确认外部提示词根目录已被添加，并包含启动耗时与终态证明，但不包含原始协议输出、提示词或凭据。需要信任的错误仍属于终态；测试夹具不会使用 trust、force 或 yolo 标志重试。

原生 oracle 在 Pi 内部运行，可使用其配置的读取工具。Claude 配置档通过 stdin 将组装好的提示词发送给本地 Claude Code CLI。外部任务智能体将组装好的提示词发送给其注册提供方。提供方选项与提示词摘要会持久化在 Pi 运行状态中。提示词文本通过本地宿主桥接交付给提供方，不会存储在公共结果负载中。除非目标提供方已获批准可接收敏感信息，否则请勿在咨询提示词中放置机密。

外部任务状态表

持久化文件	所有者	状态	释放条件	回滚条件	陈旧头处理	失败闭合场景
status.json 步骤 runner 与 externalJob	pi-subagents 异步运行器	queued、running、completed、failed、stopped、blocked	提供方 result 返回终态数据并写入异步结果	提供方 start/follow-up/status/result/reattach 返回错误	若状态文件已有提供方作业 ID，恢复时调用 reattach 与 result；当提供方、提示词摘要、父作业 ID、请求 ID、请求摘要或选项不一致时，拒绝启动新提示词	缺失提供方、不受支持的跟进提供方、容量冲突、提供方响应格式错误、桥接超时、提示词摘要不匹配、父会话缺失
result.json 或会话结果负载	pi-subagents 异步运行器	complete、failed、stopped	所有步骤达到终态且结果发布成功或可恢复地建立索引	结果写入失败，挂起的结果修复记录终态	陈旧状态可从已存在的结果文件中修复	未建立索引的无会话陈旧失败
external-job-requests/ 与 external-job-responses/	宿主中介的提供方桥接	待处理请求、终态响应	宿主进程写入匹配的响应并移除请求	桥接超时或请求响应格式错误	请求按操作作用域划分。恢复时发送 reattach/result，而非 start 或 follow-up（当作业元数据存在时）。start 与 follow-up 使用持久的派发声明	提供方未注册、宿主桥接未加载、请求格式错误、提供方异常、在没有提供方作业 ID 时的歧义派发
提供方产物路径	外部提供方	提供方定义的终态产物	提供方返回 artifactPath，或 Pi 将返回文本写入 external-job-<index>.result.md	提供方报告失败或没有结果	已存在的产物路径会保留在 status.json 中	缺失产物且无文本输出时，返回一条终态消息，而非凭空生成内容

Web 调研前置条件

researcher 与 evidence-auditor 这两个内置智能体使用 web_search、fetch_content、get_search_content 以及选择性的 source_check 校验。它们要求安装 pi-web-access：

pi install npm:pi-web-access

提供方必须在子智能体中加载，并在启动前注册全部四种工具，包括 source_check；任何必需工具缺失都会阻止一次成功的运行。前台子智能体不会加载父会话的环境扩展：请通过 extensions 或 subagentOnlyExtensions 显式配置，或使用后台扩展发现机制（见工具与扩展选择）。对于 researcher，对已抓取来源的检查仅作为已注册 source_check 调用失败时的兜底，不能用来替代缺失的注册。

覆盖内置与自定义智能体

你可以选择性地覆盖智能体的部分字段，而无需复制整个智能体。覆盖项写在设置里：

• 用户级：~/.pi/agent/settings.json
• 项目级：项目配置文件（标准 Pi 中为 .pi/settings.json）

{
  "subagents": {
    "agentOverrides": {
      "reviewer": {
        "description": "Independent review tier",
        "inheritProjectContext": false
      }
    }
  }
}

受支持的覆盖字段包括：description、machine、output、outputMode、defaultReads、model、defaultProvider、fallbackModels、thinking、systemPromptMode、inheritProjectContext、inheritGlobalContext、inheritSkills、defaultContext、acceptanceRole、disabled、skills、tools 与 systemPrompt。

• description 会替换内置与自定义智能体被发现时所使用的描述，使列表输出能展示部署相关的路由或模型元数据。
• 使用 output: false、defaultReads: false、defaultContext: false、acceptanceRole: false 或 machine: false 来清除继承的值。
• 当某个角色应当省略其内置或 frontmatter 工具白名单、并接收 Pi 的常规内置工具（在作为后台子智能体运行时还会加上环境扩展）时，使用 tools: "inherit"。
• 项目覆盖优先于用户覆盖。
• 已匹配的包级、用户级和项目级智能体也会接收这些覆盖字段，并替换其 frontmatter 中声明的相同字段。这让一个共享的智能体可以保持其人设，同时由本地设置选择实际生效的模型、上下文、工具或其他受支持的选项。

禁用与恢复：

• disabled: true 会从运行时发现和面向智能体的 subagent({ action: "list" }) 输出中隐藏一个内置智能体。
• subagents.disableBuiltins: true 会一次性禁用所有内置智能体。
• subagent({ action: "disable", agent: "reviewer" }) 不需要手动编辑设置即可写入覆盖；subagent({ action: "enable", agent: "reviewer" }) 会移除该覆盖。
• subagent({ action: "eject", agent: "reviewer" }) 会逐字将某个内置或包级智能体复制到用户或项目智能体目录（默认 user）中，作为一个可编辑的自定义文件以覆盖原文件。
• subagent({ action: "reset", agent: "reviewer" }) 会删除该作用域下的自定义智能体文件和/或设置覆盖项，从而恢复打包的默认设置。若不存在打包的默认设置则会拒绝（对纯自定义智能体请使用 delete）。

eject、disable、enable 与 reset 都接受 agentScope: "user" | "project"，且一次只在一个作用域下操作。项目覆盖仍优先于用户覆盖，因此项目作用域下的禁用会在用户作用域的 enable 后继续生效，直至你针对项目作用域执行相应操作。

在 Herdr 保存的机器上运行外部 CLI 智能体

这六个由代码所有的外部 CLI 配置档可在 Herdr 机器上运行（herdr machine add <target> --label <name>）。本地父进程会派生 ssh -T <target>，并保留提示词投递、流式解析、停止与退出证明。Herdr 的目录是主机白名单；裸的 ssh 目标会被拒绝。

machine 是一个顶层 frontmatter 键、一个设置覆盖项（subagents.agentOverrides.<agent>.machine，项目覆盖优先于用户，false 清除已固定的机器），也是 subagent 工具、workflow runs.run、chain、parallel、dynamic-fanout 步骤上的一个启动选项。启动选项优先级最高。该设置在 subagent({ action: "disable" })、reset 以及模型配置档切换后依然保留。

cwd 在设置了机器时表示在该机器上的目录。绝对路径或 ~/... 会按字面使用；相对路径会与仓库为该机器配置的根目录拼接；未提供 cwd 时则使用根目录；若根目录也未提供，启动会失败闭合，并提示相应设置的名称：

{
  "subagents": {
    "agentOverrides": { "claude-code": { "machine": "workmac" } },
    "machines": {
      "workmac": {
        "cwd": "/home/nico/proj",
        "env": { "CLAUDE_CONFIG_DIR": "/home/nico/.claude-work" }
      }
    }
  }
}

machines.<label-or-id>.env 是可选的，会在远程命令前导出。除此之外不传递任何东西：本地 ssh 进程只会接收 PATH、HOME、USER、LOGNAME、TMPDIR 与 SSH_AUTH_SOCK，不会复制任何本地 API 密钥。远程运行使用该机器自身的凭据，因此请在该机器上登录一次 CLI。非交互式 ssh shell 会跳过 rc 文件，因此 ~/.local/bin、/opt/homebrew/bin 与 /usr/local/bin 会预置到远程 PATH 之前；对于其他位置，请将智能体的 command 设置为该机器上的绝对路径。

远程的 --version 与 --help 探测使用一个就绪标记来丢弃 rc 文件噪声。每台机器的运行共享一个 OpenSSH ControlMaster socket（~/.pi/agent/ssh-control/，ControlPersist=60）。状态、回执与舰队视图会携带机器标识、远程 cwd 与远程 git 状态；写入结果会声明这些改动发生在远程。

pi-subagents 不会在远端机器上克隆、拉取或检出；目录缺失会导致远程 cd 失败并附带提示。原生 Pi 智能体、通用的 external-cli 命令、托管工作树与 Windows 主机会在启动前被拒绝。Codex 的最终消息与 Cursor 的交接文件使用 ssh 流和远程临时文件，而非本地路径。

父提示词发现

在某个专家智能体的智能体文件 frontmatter 中设置 advertise: true 以启用父提示词发现。当 subagent 工具激活时，pi-subagents 会向父会话的系统提示词追加一份由该智能体所有的名称与描述目录。被禁用的智能体、以及被当前能力上限排除的智能体都会被省略。advertisement 不能通过设置覆盖或运行时注册启用。

advertisement 是一种选择性的发现机制，而非自动路由。该目录按名称排序，最多包含 16 个智能体，整体渲染后的 UTF-8 字节数（含 XML 转义、指令和省略计数）上限为 12,288 字节。描述在转义前上限为 512 个 UTF-8 字节。无法容纳的条目会被省略；规范智能体名称永远不会被截断。父会话在执行前仍会调用 subagent({ action: "list", capabilities: true }) 以确认所选智能体可执行（对于外部 CLI 智能体还包括 runner.available === true）。

文件目录快照在会话开始/重载时刷新，并在由扩展所有的智能体管理变更后刷新。外部文件或设置的修改需要执行 /reload；常规回合不会轮询文件系统。工具可用性和能力上限过滤在每次提示词时按内存检查。管理触发的刷新失败会使目录被收回，直至下一次刷新成功，但不会改变已持久化的变更结果。

提示词组装

子智能体默认是"窄"的。自定义智能体从一个干净的系统提示词开始，只包含你有意给予它的上下文。它们不会自动继承 Pi 的全部基础提示词、项目指令文件或已发现的技能目录。

当你希望某个智能体看到更多上下文时，请使用以下字段：

字段	作用
systemPromptMode: append	将该智能体的提示词追加到 Pi 常规基础提示词之后。
inheritProjectContext: true	保留继承自仓库的指令，如 AGENTS.md 与 CLAUDE.md。
inheritGlobalContext: true	同时保留来自 Pi 配置智能体目录下运维人员的全局上下文文件（如 ~/.pi/agent/AGENTS.md）。默认 false。
inheritSkills: true	让子智能体看到 Pi 已发现的技能目录。
defaultContext: fork	当启动时省略了 context，优先使用分叉会话上下文；若父会话没有已持久化的会话文件或当前叶子节点，则隐式默认回退到 fresh，而不会先发起一次失败的尝试。显式的 context: "fork" 仍保持严格，显式的 context: "fresh" 仍胜出。

内置智能体默认启用仓库指令继承，从而开箱即即遵循仓库规则，但全局上下文默认仍被排除，除非显式设置 inheritGlobalContext: true。这改变了原本因 inheritProjectContext: true 而接收全局上下文的那些既有智能体的行为。delegate 也使用追加模式，因为其职责是在父工作流内进行编排。

Frontmatter 参考

一个完整示例：

---
name: scout
# 可选：注册为 code-analysis.scout，同时保留 name: scout
package: code-analysis
description: Fast codebase recon
advertise: true
aliases: explorer, code-scout
tools: read, grep, find, ls, bash, mcp:chrome-devtools
excludeTools: bash
extensions:
subagentOnlyExtensions: ./tools/child-only-search.ts
model: claude-haiku-4-5
fallbackModels: openai-codex/gpt-5.6-luna:low, anthropic/claude-sonnet-4
thinking: high
systemPromptMode: replace
inheritProjectContext: false
inheritGlobalContext: false
inheritSkills: false
skills: safe-bash, review-checklist
skillPath: ./skills, ../shared-skills
output: context.md
defaultReads: context.md
defaultProgress: true
async: true
timeoutMs: 900000
toolTimeoutMs: 600000
acceptance: { 'level': 'none', 'reason': 'lightweight lookup' }
acceptanceRole: read-only
completionGuard: false
interactive: true
maxSubagentDepth: 1
allowNestedSubagents: true
---
Your system prompt goes here.

简单标量列表字段同时接受逗号分隔形式和换行块列表（每行一个 - item）。这适用于 tools、excludeTools、defaultReads、skill/skills、skillPath、fallbackModels、extensions 与 subagentOnlyExtensions：

tools:
  - read
  - mcp:github/search_repositories
fallbackModels:
  - openai-codex/gpt-5.6-luna:low
  - anthropic/claude-sonnet-4

字段说明：

字段	说明
package	可选的包标识符。带有 name: scout 和 package: code-analysis 的文件会注册为 code-analysis.scout；序列化时 name 与 package 各自独立。
advertise	设为 true 时，当 subagent 工具处于激活状态，会将该智能体的名称和描述加入父系统提示词。默认 false。
aliases	可选的逗号分隔或块列表形式的别名，会解析到该智能体用于选择以及显式的 agent 与任务输入。运行时状态、持久化与配置仍使用规范 name。精确的规范名称优先于别名，不同规范智能体之间的别名冲突会以歧义失败。
tools	严格的子智能体工具白名单。命名的扩展工具还需要其提供方已加载。mcp: 条目在安装了 pi-mcp-adapter 时选择直接的 MCP 工具。
excludeTools	可选的子智能体工具拒绝名单，在常规工具解析后应用。当存在显式 tools 白名单时，会移除其中匹配的名字；当省略 tools 时，这些名字会从子会话的默认工具集中排除。未知名字会被 Pi 忽略，而不会让智能体定义失效。
allowNestedSubagents	设为 true 以授权子智能体可安全使用的嵌套 subagent 运行时，但不会把省略的 tools 视为白名单。继承的深度与能力上限仍然有效。
extensions	省略时，后台子智能体会加载父会话的环境扩展；为空时，表示无环境扩展；列表值时，仅加载列出的扩展。前台子智能体永远不会加载环境扩展，因此对它们而言只有列出的值生效。
subagentOnlyExtensions	仅在该智能体的子会话中加载的扩展路径。在此处注册的工具在主智能体中不可用，除非也通过常规 Pi 扩展配置进行了安装。
model	默认模型。裸 ID 在可能的情况下优先使用当前提供方，再考虑唯一的注册表匹配。
fallbackModels	在任何工具活动之前，针对可重试的提供方/模型失败的有序备用模型。在工具活动之后，仅一个符合条件的原生前台或后台只读 HTTP 429 可在配置相同提供方的兼容模型上继续一次，并以固定的续接提示词重新打开恰好保留的文件，而不是重放任务。这与压缩中止恢复共享一次恢复额度，并保留原始的截止时间与取消。普通的任务/截止时间失败和外部运行器不享有此例外。要求使用由本扩展拥有的内置 read/ls 能力画像，不包含等待、协调、自定义工具或已配置的工具预算。前台拒绝任何已配置的用量预算；后台仅允许权威的剩余令牌额度，而非费用或未知覆盖。仅凭保留的历史不足为凭据。见受支持的配置与兼容性限制。
thinking	除非已带后缀，否则在运行时会作为 :level 后缀追加。
systemPromptMode	默认 replace；append 时保留 Pi 的基础提示词。
inheritProjectContext	保留或剥离继承自仓库的指令块。
inheritGlobalContext	保留或剥离 Pi 配置智能体目录下运维人员的全局上下文文件（如 ~/.pi/agent/AGENTS.md）。仅当 inheritProjectContext: true 时生效；否则所有上下文文件本来就不会被加载。默认 false。
inheritSkills	保留或剥离 Pi 已发现的技能目录。
defaultContext	可选的 fresh 或 fork 启动上下文偏好。当父会话没有持久化的会话文件或当前叶子节点时，隐式 fork 回退到 fresh；显式启动 context: "fork" 仍保持严格。
skills	不论 inheritSkills 如何，为子智能体选择指定的技能。
skillPath	调用私有的技能文件或发现目录。相对路径相对于智能体定义文件解析。本地匹配优先；未解析或不可读的匹配回退到常规技能发现。该字段仅发现候选；skills 仍决定子智能体接收哪些。
output	默认的单智能体输出文件。
defaultReads	在运行该智能体前读取的文件。
defaultProgress	维护 progress.md。
async	当调用省略了 async 时，将单智能体启动默认为后台（true）或前台（false）。显式的调用值与 forceTopLevelAsync 优先。
timeoutMs	单智能体启动的正整数默认运行截止时间（毫秒）。前台启动在调用与智能体都未提供超时时使用 30 分钟；显式的 timeoutMs/maxRuntimeMs 与智能体默认值优先。
toolTimeoutMs	可选的正整数硬性单次工具调用截止时间（毫秒）。显式调用值优先，然后是本智能体默认值，再后是全局 toolTimeoutMs，最后是 PI_SUBAGENT_TOOL_TIMEOUT_MS。省略时，已知的快速内置工具默认 5 分钟；长时间运行的工具会收到关注通知，没有硬性默认值。它不会延长运行级截止时间；contact_supervisor、intercom 与 bg_wait 不受其限制。
acceptance	单智能体启动的验收默认值。可使用标量级别如 checked，也可使用行内/块 YAML 映射如 { level: "none", reason: "lightweight lookup" }。显式调用值优先；链式与并行的验收仍由任务/步骤配置决定。
acceptanceRole	自动推断验收时可选的 read-only 或 writer 角色。显式任务变更或无编辑意图优先；否则已声明的角色会替代基于智能体名称的猜测。这不会授予或撤销工具。
mutationTools	以逗号分隔的扩展工具名称，其调用会计入完成防护的"尝试变更"计数。本字段仅声明证据；仍需通过 tools 与相应的扩展提供方列出并加载每个工具。
completionGuard	仅对那些在使用具备变更能力的工具（如 bash）时仍可能提到"实现"字眼的非实现类智能体，设为 false。
interactive	出于兼容性而解析，但不强制执行。
maxSubagentDepth	收紧该智能体子代的嵌套委派深度。
memory	可选的、按角色划分的持久化记忆。见下文。

必需宿主扩展

宿主可从 pi-subagents/required-child-extensions 导入 registerRequiredChildExtensions，并注册 { sessionId, extensions: [{ id, path }] }。路径会解析到已存在的文件，并被规范化到不可变的启动快照中；在证据中显示的是有界的安全 ID，而非路径。每个父会话只允许一次注册，直到其幂等的 dispose() 运行（通常在 session_shutdown 时）。

必需的路径遵循常规扩展解析，并在原生前台、分离、嵌套和恢复启动中跨智能体默认值与 extensions: [] 生效。capabilityCeiling.denyExtensions 冲突或必需加载/提供方注册失败会在模型解析前拒绝。外部运行器被排除，状态/监视路径不会查询此注册表。

当完成防护将要标记缺失的编辑时，模型意图仲裁器只能挽救一次明确的只读任务。前台使用父会话模型；原生后台在子智能体关闭后使用该子智能体尝试的现有模型服务。普通的完成不会调用分类或解析仲裁器身份验证。禁用仲裁（PI_SUBAGENTS_LLM_INTENT_ARBITER=0）、模型/身份验证不可用、错误、意图不明以及超过 8,000 字符的任务都会保留防护结果。分类提示词的限时为 10 秒；前置的身份验证与模块加载不在该限时范围内。这不会改变能力限制或 v1 契约的默认关闭防护与显式"缺失效果"语义。

按智能体的持久化记忆

一个周期性的自定义智能体可通过 memory frontmatter 字段选择启用持久化、角色专属的记忆作用域：

memory:
  scope: project
  path: security-reviewer

这独立于 Pi 自身的父/会话/项目记忆系统，并不会向其写入任何内容。记忆存放在专用的 agent-memory/ 命名空间下，因此两者永远不会冲突。

工作方式：

• 每次运行时，已解析记忆目录下 MEMORY.md 的前 200 行会被注入子系统提示词，使智能体能够回想起累积的角色笔记，例如威胁建模条目、版本踩坑记录或已验证的命令。
• 具备写入工具（edit、write 或 bash，或根本没有 tools 白名单）的智能体被告知可以追加简洁的、带日期的条目到该文件。
• 没有写入工具的智能体收到的是只读的记忆块，且不会被指示去编辑它。一个只读的评审者可以回想起先前的笔记，而不会获得写入能力。
• 记忆目录永远不会被急切创建。智能体自身的 write 工具会在第一次持久化时创建该目录（以及 MEMORY.md）。
• 记忆路径会针对 ./.. 越界和符号链接逃逸进行校验。不安全或无法解析的作用域会被静默跳过，而不是破坏运行。

作用域：

• 项目：解析到 <project>/.pi/agent-memory/<path>，随仓库一起迁移。
• 用户：解析到 ~/.pi/agent/agent-memory/<path>，在该智能体名下跨项目共享。

精化覆盖层

精化覆盖层是限定范围的、仅项目本地的指引，叠加在某个智能体的系统提示词之上，而无需编辑智能体文件。当某个智能体在同一个项目特定问题上反复跌倒，并且近期的运行证据已经清楚说明了该如何纠正时，可以使用它。

/subagents-refine reviewer

subagent({ action: 'refine', agent: 'reviewer' });
subagent({ action: 'refine.show', agent: 'reviewer' });
subagent({ action: 'refine.rollback', agent: 'reviewer' });

工作方式：

• refine 会从该智能体在该项目的近期运行中收集有限的证据（状态、错误、评审发现、残留风险、输出尾部），然后启动一个全新的只读提案子智能体，依据这些证据起草小幅的指引编辑。
• 拟议的指引在写入前会进行校验。试图覆盖安全、策略、工具、输出、验收、开发者或系统指令的编辑会被拒绝；针对所有智能体或基础智能体文件的编辑同样会被拒绝。
• 已接受的覆盖层存储在 .pi/subagents/refinements/<agent>.md，并附带修订元数据与快照。每次 refine 或 refine.rollback 都会新增一份快照；refine.rollback 会恢复到上一版本。
• 在启动时，当前的覆盖层会作为 <pi-subagents-refinement> 块注入该智能体的子系统提示词，作用域限定为本项目。基础智能体定义永远不会被修改。

refine.show 会打印当前的覆盖层和修订历史。删除覆盖层文件即可完全移除该精化。

工具与扩展选择

tools 的行为：

• tools 省略：子会话获得 Pi 常规的内置工具。
• tools 存在：常规工具名称变为显式白名单。
• tools: 为空：子会话不获得任何工具。
• allowNestedSubagents: true：显式启用子智能体可安全使用的嵌套扇出，而不会把省略的 tools 变成白名单。深度与继承的能力上限仍然适用。

excludeTools 在此解析之后应用。它可以收窄显式的 tools 白名单，或在 tools 省略时从 Pi 的默认内置工具集中移除名称。仅当运行时注入的工具的精确名称被列出时，才会被排除。空的 excludeTools 列表没有作用。

白名单中的某个名称并不会加载注册该名称的扩展。通过 extensions、subagentOnlyExtensions、路径形式的 tools 条目或（仅限后台子智能体）常规 Pi 扩展发现来加载相应的提供方。

环境扩展依赖于子智能体的运行位置。前台子智能体是父 Pi 进程内部的会话，永远不会加载父会话的环境扩展；否则父会话会启动每个环境扩展的第二份拷贝，包括本扩展。后台子智能体是分离的运行器进程内部的会话，会加载环境扩展，除非该智能体设置了 extensions 或能力上限拒绝了扩展。因此，需要 MCP 工具（mcpDirectTools，或来自 pi-mcp-adapter 等环境适配器的 MCP 工具）或来自提供方扩展的模型的智能体必须作为后台子智能体运行（async: true）。此类智能体以前台方式启动会以一条明确的诊断失败。

更多规则：

• mcp: 条目会被拆分并作为直接的 MCP 选择转发，除非还列出了常规内置工具，否则不会授予这些工具。
• 路径形式的 tools 条目，例如扩展路径或 .ts/.js 文件，会被视为工具扩展路径，而非工具名称。
• 内部运行时工具（如 structured_output）仅在它们的契约激活时才会加入显式白名单。
• 未知的扩展工具调用仅在其名称列在 mutationTools 中时，才会计入"尝试变更"计数；未声明的未知工具仍保持"无编辑"防护。
• 仅声明已知只读内置工具的智能体会跳过实现完成防护。bash、未知工具和 MCP 工具仍具备变更能力。对于启用了 bash 的校验器或顾问类智能体，若永远不应被当作实现类智能体判断，请使用 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：在该子智能体内部可使用子智能体可安全使用的 subagent 工具，以便其运行显式分配的嵌套扇出。
• allowNestedSubagents: true 且 tools 省略：保留常规内置工具（对于后台子智能体，还包括环境扩展），并加入子智能体可安全使用的嵌套 subagent 运行时。
• tools: read, fixture_search 加上 subagentOnlyExtensions: ./tools/fixture-search.ts：该提供方仅在该智能体的子会话中加载，已注册的 fixture_search 名称可以经受严格的白名单。

直接的 MCP 工具要求安装 pi-mcp-adapter。子智能体仅当其 frontmatter 中列出了 mcp: 条目时，才会接收直接的 MCP 工具；mcp.json 中全局的 directTools: true 单独并不足够。通用的 mcp 代理工具在可用时仍可用于发现。适配器在启动时缓存工具元数据，因此首次连接新的 MCP 服务器后，请重启 Pi 再依赖直接工具。在为子智能体解析已缓存的元数据时，强制执行服务器的 includeTools 与 excludeTools 策略：两者均接受精确名称和针对原始、生成资源以及 server/short/none 前缀名称的 */? 通配符模式，其中 excludeTools 优先。mcp: 条目必须以来自适配器配置文件的服务器命名。仅存在于适配器运行时快照中的服务器（运行时注册，未持久化）无法提供给子智能体：子智能体是父进程或运行器进程内的 Pi 会话，而非可以接收 MCP 配置参数的 pi 进程，因此这种启动会以一条错误失败，说明 MCP 工具必须来自后台子智能体中的环境适配器扩展。命名为 subagent 的 mcp: 条目不会授权嵌套扇出；请声明内置的 subagent 工具或设置 allowNestedSubagents: true。若已解析的直接 MCP 名称未出现在子智能体注册表中，pi-subagents 会让启动在严格白名单下失败，并将该情况识别为主机/pi-mcp-adapter 注册问题；请确认在子智能体启动前适配器已注册所选的工具。

extensions 控制子智能体的扩展加载：

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

# 空：不加载任何扩展
extensions:

# 白名单
extensions: /abs/path/to/ext-a.ts, /abs/path/to/ext-b.ts

当 extensions 存在时，常规已发现的扩展会被禁用。列出的扩展、路径形式的 tools 条目、必需的 pi-subagents 运行时扩展以及 subagentOnlyExtensions 仍会加载。

当你希望某个自定义扩展工具仅存在于子会话中时，请使用 subagentOnlyExtensions。它按智能体配置限定作用域：该智能体的每次运行都会接收这些扩展路径，而其他智能体不会，除非它们声明了相同的字段。当前的模型在同一个智能体定义内不区分带名字的子智能体受众。

要为每个未声明自己 extensions 的智能体应用同样的 extensions 白名单，请在用户或项目设置中设置 subagents.defaultExtensions（见 configuration.md）。

在首次模型回合之前，子运行时会比对每个显式工具名称与 Pi 最终过滤后的注册表。提供方缺失会使运行失败，并提示不可用的名称以及具体的 subagentOnlyExtensions/extensions 指引，而不是让直接或链式的子智能体在没有请求的工具时悄悄继续。

技能（Skills）

技能是提供给某个智能体的 SKILL.md 文件。提示词中包含技能的元数据及其文件位置；智能体仅在任务匹配时才会读取完整的技能文件。

发现顺序按项目优先：

1. 项目配置 skills/{name}/SKILL.md（标准 Pi 中为 .pi/skills/{name}/SKILL.md）
2. 项目包和项目设置包，通过 package.json -> pi.skills
3. 当前任务 cwd 所在的包，通过 package.json -> pi.skills
4. 项目配置 settings.json -> skills
5. ~/.pi/agent/skills/{name}/SKILL.md
6. 用户包和用户设置包，通过 package.json -> pi.skills
7. ~/.pi/agent/settings.json -> skills

可以使用智能体默认值、在运行时覆盖它们，或禁用它们：

{
  workflowScript: `return runs.run("main", { agent: "scout", task: "..." })`;
}
{
  workflowScript: `return runs.run("main", { agent: "scout", task: "...", skill: "tmux, safe-bash" })`;
}
{
  workflowScript: `return runs.run("main", { agent: "scout", task: "...", skill: false })`;
}

对于链式调用，顶层的 skill 是叠加的。步骤级的 skill 会覆盖该步骤；false 会禁用该步骤的技能。

可用技能在子提示词中使用以下结构：

The following configured skills are available to this subagent.
Use the read tool to load a skill's file when the task matches its description.
When a skill file references a relative path, resolve it against the skill directory (parent of SKILL.md / dirname of the path) and use that absolute path in tool commands.

<available_skills>
  <skill>
    <name>safe-bash</name>
    <description>Run shell commands safely.</description>
    <location>/absolute/path/to/safe-bash/SKILL.md</location>
  </skill>
</available_skills>

如果某个智能体具有显式的 tools 白名单和已解析的技能，会为该子智能体运行额外添加 read，以便按需加载列出的技能文件。

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

智能体本地的 skillPath 候选永远不会进入 Pi 的父/全局技能目录。当希望某个子智能体仅接收其选定的私有技能时，请将 inheritSkills: false 与显式的 skills 和 skillPath 配合使用。

自带的 pi-subagents 技能

该包自带一个 pi-subagents 技能，在扩展安装后会自动提供给父智能体。它仅供编排用的父智能体使用：子智能体永远不会接收到它；其上下文会被显式过滤，去除仅限父级的编排指令。

它涵盖的内容：

• 委派模式：何时启动哪个智能体，使用单智能体、并行、链式还是异步模式，以及使用全新上下文还是分叉上下文。
• 提示词工作流配方：当用户以自然语言描述工作流，而非调用斜杠命令时，如何直接通过 subagent(...) 应用打包的技巧。这包括并行评审、评审循环、并行调研、并行上下文构建、并行交接计划、收集上下文并澄清，以及并行清理。
• 角色智能体的提示词指南：使用紧凑的契约提示词而非长脚本、在角色特定的元提示词中应包含哪些内容，以及调研者的检索预算。
• 安全边界：子智能体不得运行子智能体，除非其已解析的内置工具明确包含 subagent；不得凭空捏造对讲机目标；必须上报未批准的决策。
• 对讲机约定：何时询问与何时发送，以及父侧的监督者/结果交付如何通过原生通道进行。
• 控制与诊断：关注信号、软中断、状态以及 doctor 操作。

如果你正在编写一个编排子智能体的智能体，该自带技能可以帮助其表现得当，而无需自行摸索这些模式。如果你是人类用户，则无需阅读它；README 与提示词快捷方式以用户友好的形式承载了相同的工作流。