背景与插件概述

如果你曾使用过 Codex 或 Claude Code，应该对 subagent（子代理） 的概念并不陌生。这种架构允许将相对独立的任务交给不同的 agent 分头处理，最后再汇总结果以提升效率。然而，Pi（由 Mario 开发）默认并没有内置 subagent 功能。对于有此类需求的用户，可以通过安装插件来补上这一能力。本期视频将详细介绍由 Pi 作者 Mario 开发的 pi-subagent 插件。该插件的核心机制是：每个 subagent 都在独立的 tmux 会话里运行。这意味着你可以直接打开对应的终端窗口，实时查看任务的进展细节。此外，用户还可以向这些独立的会话中补充要求或继续追问。插件会为每个 subagent 启动一个独立的 Pi 进程，并且为它们单独保存聊天记录。不过需要注意的是，尽管会话独立，但它们默认仍然访问同一个项目目录。

“把相对独立的任务交给其他 agent 分头处理再汇总结果。Pi默认没有内置的subagent。”

安装与环境准备

在开始使用之前，需要确保环境满足特定要求。首先必须准备好 Pi、Node.js 以及 tmux。其中，tmux 需要单独安装。对于 macOS 用户，可以通过执行 brew install tmux 命令来完成安装。安装好以后，插件会自动地为每个 subagent 创建会话，用户并不需要手动创建 tmux 窗口，也无需提前把 Pi 放进 tmux 里运行。接下来，使用 Pi 官方的 pi install 命令从 Git 仓库安装该插件。执行完毕后，使用 pi list 确认安装结果是否成功。随后需要将 subagent 命令加入 PATH，以便系统能识别相关指令。如果 Pi 已经在运行中，只需在会话中输入 /reload 命令即可加载刚安装的扩展。这里需要明确的是：我们提到的“扩展”实际上就是插件，是同一个概念。安装完成后，即可在 Pi 对话中安排任务。在执行过程中，你会看到 subagent 命令的出现，那是 Pi 通过 bash 工具完成的操作，用户并不需要自己逐条输入这些底层命令。完整的安装指令通常会在视频描述中提供。

“插件会自动地为每个subagent创建会话。你并不需要手动创建，也不需要提前把Pi放进tmux里运行。”

并行代码审查实战案例

为了演示插件的实际效果，我们在 Pi 的会话中提出一个具体需求：创建 2 个 subagent，分别负责检查代码中的“分页函数”和“账单函数”。在指令中明确限制权限：只允许读取和搜索，不修改文件。需求描述清晰后，Pi 会创建任务并显示任务的名称和编号。这些编号用于后续的管理，在日常使用中也可以直接告诉 Pi 要继续处理哪个特定任务。如果想查看 subagent 的执行过程，可以在 Pi 中输入 /subagent，选择对应的任务进入其会话。查看完毕后，按 Ctrl-b 再按 d 即可返回原来的 Pi 会话。

第一个任务是检查分页函数。Pi 发现了一个 bug：slice 不包含结束位置。例如，代码意图取 3 项，但因为错误地减去了结束位置的索引值（-1），导致只返回了 2 项。修复方法很简单：去掉结束位置里的减 1，就符合需求了。接着创建第 2 个任务检查账单函数。代码中 discount 表示折扣比例，0.2 代表打 8 折。然而代码逻辑错误地将其当作固定金额直接减掉。举例来说，单价 100、数量为 2 时： - 错误计算结果：(100 - 0.2) * 2 = 199.8 - 正确计算结果：(100 * (1 - 0.2)) * 2 = 160 这两个任务由 Pi 分别创建，各自保留独立的聊天记录。我们在原对话中等待 Pi 把检查结果整理出来。这里使用的是方便核对的小样本演示场景，尚不能据此判断在复杂项目中的全面审查效果。

“slice不包含结束位置。想取3项，代码呢，却只返回了2项。”

追问机制与底层原理

有了初步的审查结果，我们可以在原来的 Pi 对话中继续追问。例如：让检查分页的 subagent 补充一条回归测试，但暂时不修改文件。Pi 会找到对应的任务编号，将要求发送过去并获取回答。用户不需要自己手动复制任务编号或拼接命令。底层的实现逻辑如下： 1. send：发送要求。 2. follow-up：把追问排在当前问题之后。 3. wait：读取最新的回答。

对话负责表达需求，插件提供执行和管理任务的能力。当需要查看完整过程时，仍可进入对应的会话。这些任务之所以能被查看、追问并保留记录，主要依赖于插件保存的三类信息： - metadata：记录任务的标识、模型和运行状态。 - inbox：接收追加的消息队列。 - session.jsonl：保存聊天的详细记录。

在创建任务时，插件通过 tmux 启动独立的 Pi 进程。当用户补充要求或追加提问时，命令会先将消息写入 inbox。subagent 中的扩展会定期检查 inbox，再将消息交给 Pi 处理。执行 wait 命令时，它会检查任务状态并从聊天记录中读取回答。因此打开终端可以观察过程，而 wait 用来取得最终的回答。

“插件主要保存了3类信息：metadata记录任务的标识模型和运行状态，inbox接收追加的消息，session.jsonl保存聊天的记录。”

会话恢复与潜在风险测试

当负责分派任务的 Pi 会话正常退出时，插件会停止它创建的 subagent，同时保留聊天记录和任务的信息。如果之后恢复原来保存的会话，这些 subagent 也会重新启动。但需要注意的是：它们会停在空闲状态，需要再次发出指令才会继续工作。

在实测中，恢复会话后再追问账单的问题，它仍然能够给出之前的修正公式。我们还测试了 subagent 还在工作时，正常关闭负责分派任务的 Pi 进程。需要注意的是：重新加载的是聊天记录，执行到一半的工具不会从中断处接着运行。本次测试未涉及断电强制结束进程或异常崩溃的场景。

在会话恢复后，存在一个容易误判的情况：我们发出一条新的解释请求，在它回答前中断任务并恢复会话。此时聊天记录里这条新请求尚未得到回答。但执行 wait，返回的却是上一轮的修正公式，且显示 finished，退出代码也是 0。从源代码分析，wait 会检查任务是否开始过、现在是否空闲以及是否有消息等待投递。满足条件后就能读取最新的模型回答，但并没有核对这条回答是否对应刚才的请求。因此，中断恢复后必须检查聊天记录确认当前问题是否有答。如果只看 finished 状态，还不能够判断任务是否真的已经完成。

“从源代码看wait会检查任务是否开始过、现在是否空闲以及是否有消息等待投递。满足条件后就能读取最新的模型回答，但并没有核对这条回答是否对应刚才的请求。”

使用建议与限制说明

首次使用时，建议从一个小任务或者小文件开始。在对话中明确检查目标并声明不要修改代码。如果让多个 subagent 同时修改代码，需要自己分配文件或者准备独立的工作目录。此外，该插件有一个重要限制：不允许 subagent 再来创建 subagent（即不支持嵌套子代理）。任务结束后，可以让 Pi 先汇总结论，再停掉这些任务。停止操作会删除对应任务的聊天记录和任务信息，因此需要的内容需提前保存好。

“这个插件并不允许subagent再来创建subagent。任务结束后可以让Pi先汇总结论，再停掉这些任务。”

结论

本文详细介绍了 Pi 作者 Mario 开发的 pi-subagent 插件，它通过 tmux 为每个子代理提供独立的进程和会话环境。该方案支持并行代码审查（如分页逻辑错误、折扣计算错误等案例），并通过 inbox 机制实现主会话对子任务的追问。然而，用户需注意其局限性：任务恢复时可能返回旧回答导致误判（需人工核对聊天日志），且不支持嵌套子代理。在并发修改代码时需自行隔离工作目录，停止任务会清除记录，需提前备份关键信息。该插件填补了 Pi 原生缺乏并行处理能力的空白，适合需要多任务协同但需精细控制执行环境的场景。