主 agent 不能碰代码。没有 write，没有 edit，没有 bash。它只有 read、grep、find、ls 四个只读工具，外加一个 subagent 工具用来委派任务。所有修改文件、跑命令、执行逻辑的工作，全部交给子 agent——每个子 agent 跑在独立的 pi 进程中，有自己的 system prompt 和 skills。主 agent 和子 agent 之间，子 agent 和子 agent 之间，进程完全隔离。
subagent-isolation 是 Pi Agent 的扩展。Pi 本身已经支持子 agent，但这个扩展做了一个关键的约束——剥夺主 agent 的执行能力，强制隔离。主 agent 变成纯粹的计划者和观察者。
大模型的有效上下文不是无限的。当一个 agent 同时负责读代码、改文件、跑测试，工具调用痕迹、报错信息、中间结果会迅速堆积。总上下文超过模型能稳定处理的阈值后，推理质量会明显下降——关键信息被淹没、重复劳动增多、决策开始基于嘈杂的上下文。
子 agent 系统的核心目的就是把一个不断膨胀的上下文切成多块。每个 agent 只处理自己那一小块任务，避免单一会话被历史痕迹拖垮。
很多子 agent 实现只是“在主 agent 内部开一个工具调用”。子 agent 仍然复用主 agent 的提示词和 skills，主 agent 也仍然保留着写文件、跑命令的能力——隔离是可选的、不彻底的。
subagent-isolation 做的是强制且完全的隔离：
- 进程完全隔离：每个子 agent 启动独立的
pi进程。 - 提示词完全隔离：子 agent 有自己的 agent 定义文件（如
coder.md），不继承主 agent 的master.md。 - Skills 完全隔离：主 agent 和每个子 agent 各自加载自己的 skill，互不干扰。
- 执行能力完全隔离：主 agent 被剥夺
write/edit/bash，只能委派，无法自己执行。 - 独立可配置：每个 agent 单独定义自己的
tools和skills，精确控制它能做什么、不能做什么。
常规子 agent 是“分工”；subagent-isolation 是“彻底分家”。
| Before | After |
|---|---|
| 一个 agent 同时做规划和执行，上下文超过阈值后推理质量下降 | 主 agent 只规划委派，每个子 agent 只处理自己的任务片段 |
| 主 agent 仍保留写文件、跑命令能力，隔离不彻底 | 主 agent 被剥夺 write/edit/bash，子 agent 在独立进程中运行 |
| 所有 skill 和工具堆在一个 agent 里，互相干扰 | 每个子 agent 只加载自己需要的 skill 和 tools |
| 角色 | 职责 | 运行位置 |
|---|---|---|
| 主 agent | 理解需求、拆分任务、委派与汇总 | 你的 pi 主会话 |
| 子 agent | 读代码、改代码、跑验证并返回结果 | 独立的 pi --mode json 进程 |
一个典型任务这样流转：
- 你向主 agent 提出任务。
- 主 agent 通过
subagenttool 启动一个独立 pi 进程。 - 子 agent 只拿到委派的那一句话和自身配置，完成具体修改。
- 子 agent 返回结果并退出，主 agent 决定下一步。
四个层面的隔离：
- 进程隔离：每个子 agent 启动新的
pi --mode json进程，system prompt 写入临时文件并通过--append-system-prompt注入，互不污染。 - 上下文隔离：子 agent 看不到主 agent 的执行痕迹，只拿到你委派的那一句话。
- 能力隔离：通过
tools和skills字段，给不同子 agent 配备不同的工具箱。 - 递归边界：子 agent 可配置为禁止继续向下委派，任务范围始终可控。
subagent-isolation 是一个 Pi Package，需要先安装 Pi Agent。
本扩展需要 Node.js >= 20（与 package.json 中的 engines.node 一致）。
curl -fsSL https://pi.dev/install.sh | shnpm install -g --ignore-scripts @earendil-works/pi-coding-agent安装完成后，你就可以在终端使用 pi 命令了。
pi install npm:subagent-isolation示例已经包含这个配置，你可以直接复制，也可以按需修改：
cp examples/pi/agent/agents/*.md ~/.pi/agent/agents/
cp examples/pi/agent/master.md ~/.pi/agent/master.md
cp -r examples/pi/agent/skills/* ~/.pi/agent/skills/各 agent 的具体定义见 examples/pi/agent/agents/ 目录，可按需修改。
直接复制即可使用，也可以根据自己的需求调整。
pi --tools read,grep,find,ls,subagent \
--no-skills \
--append-system-prompt ~/.pi/agent/master.md \
--skill ~/.pi/agent/skills/brainstorming/这条命令把主 agent 限制为只读工具 + subagent 委派，加载主 agent 提示词和 brainstorming skill。
为了方便日常使用，建议在 shell 配置里给它设一个 alias。比如在 ~/.zshrc 中加入：
alias pp='pi --tools read,grep,find,ls,subagent --no-skills --append-system-prompt ~/.pi/agent/master.md --skill ~/.pi/agent/skills/brainstorming/'之后直接输入 pp 即可启动主 agent。
启动后，直接对主 agent 说：
把认证中间件重构为 async/await。
主 agent 会自动通过 subagent tool 调用 coder。你不需要手写 JSON，也不需要关心 sessionId——扩展会处理隔离进程的启动和回收。
如果你需要继续同一任务，子 agent 输出末尾会附带 session ID。具体调用格式与复用方式见 ADVANCED.md。
GitHub 仓库的 examples/pi/agent/agents/ 提供了三个可直接参考的 agent：
| Agent | 作用 | 可用工具 | 加载的 skill |
|---|---|---|---|
coder |
写代码、改代码、跑验证 | read, write, edit, bash, grep, find, ls |
systematic-debugging |
reviewer |
只读评审，输出可操作的反馈 | read, grep, find, ls |
(无) |
writer |
写文档、改 README、生成 commit message | read, write, edit, grep, find, ls |
writing-clearly-and-concisely |
把它们复制到 ~/.pi/agent/agents/（用户级）或项目内的 .pi/agents/（项目级）即可使用。
如果你已经克隆了仓库，可以直接复制：
cp examples/pi/agent/agents/*.md ~/.pi/agent/agents/也可以单独从 GitHub 下载（以 coder 为例）：
curl -fsSL https://raw.githubusercontent.com/Wolido/subagent-isolation/main/examples/pi/agent/agents/coder.md \
-o ~/.pi/agent/agents/coder.md这些只是示例，你可以根据自己的需求修改或新建 agent。
Agent 搜索规则：
user作用域：~/.pi/agent/agents/project作用域：.pi/agents/（从工作目录向上搜索）- 默认合并两个作用域，project 同名时覆盖 user
主 agent 应该是一个纯粹的规划者：只读代码、做判断、委派任务。所有写文件、跑命令、改代码的具体操作都交给子 agent，每个子 agent 在独立的 pi 进程中运行。这样主 agent 的上下文只会保留“要做什么”和“结果是什么”，不会被工具调用细节污染。
主 agent 的系统提示示例见 examples/pi/agent/master.md，复制到 ~/.pi/agent/master.md 即可。
完整的示例文件见 examples/pi/agent/master.md，可直接复制到 ~/.pi/agent/master.md 使用。
把示例 agent 复制到 ~/.pi/agent/agents/：
cp examples/pi/agent/agents/*.md ~/.pi/agent/agents/然后使用以下命令启动主 agent：
pi --tools read,grep,find,ls,subagent \
--no-skills \
--append-system-prompt ~/.pi/agent/master.md \
--skill ~/.pi/agent/skills/brainstorming/各参数含义：
--tools read,grep,find,ls,subagent：只允许读、搜、列目录和委派子 agent。没有write、edit、bash，主 agent 不能自己改代码或跑命令。--no-skills：不加载默认 skills，保持主 agent 上下文干净。--append-system-prompt ~/.pi/agent/master.md：把主 agent 的系统提示追加到默认提示后。--skill ~/.pi/agent/skills/brainstorming/：加载 brainstorming skill，主 agent 用它做任务规划。
子 agent（coder、writer）通过 frontmatter 中的 skills: 字段自动加载各自的 skill，无需在启动命令中指定。
如果只想在当前项目生效，把 agent 放到 .pi/agents/ 目录即可；扩展会在调用 subagent 时自动加载这些项目级 agent。
- 用户提出需求。
- 主 agent 拆分任务，并决定委派给哪个子 agent。
subagenttool 为子 agent 启动独立的 pi 进程。- 子 agent 在干净上下文中执行，只使用指定的 tools/skills。
- 子 agent 返回结果并退出，主 agent 汇总后继续。
主 agent 只保留"要做什么"和"结果是什么"，中间的工具调用痕迹全部留在子 agent 的进程里。任务越复杂，这种隔离带来的收益越明显。
GitHub 仓库的 examples/pi/agent/skills/ 提供了三个可直接使用的 skill：
| Skill | 使用者 | 描述 |
|---|---|---|
brainstorming |
主 agent | 通过协作对话把想法变成完整设计 |
systematic-debugging |
coder |
修 bug 前先找根因（四阶段流程） |
writing-clearly-and-concisely |
writer |
用简洁规则、AI 痕迹检测和人味注入打磨文字 |
把这些 skill 复制到 ~/.pi/agent/skills/：
mkdir -p ~/.pi/agent/skills
cp -r examples/pi/agent/skills/brainstorming ~/.pi/agent/skills/
cp -r examples/pi/agent/skills/systematic-debugging ~/.pi/agent/skills/
cp -r examples/pi/agent/skills/writing-clearly-and-concisely ~/.pi/agent/skills/Skill 的加载方式有两种：
- 子 agent：在 frontmatter 中用
skills:字段声明（如 coder 的skills: systematic-debugging），pi 启动子 agent 时自动加载。 - 主 agent：在命令行用
--skill标志加载（如--skill ~/.pi/agent/skills/brainstorming/）。
Skill 搜索规则与 agent 相同：~/.pi/agent/skills/（用户级）和 .pi/skills/（项目级），子 agent 会根据 skills: 字段中的名称在这两个目录中查找匹配的 skill。
如果需要手写 subagent 调用、复用 sessionId、查看完整 frontmatter 字段或调整环境变量，请参阅 ADVANCED.md。
src/index.ts— 扩展主源码examples/pi/agent/— 示例 agent 和 skill 定义master.md— 主 agent 系统提示agents/— 子 agent 定义skills/— skill 定义
package.json— npm 包清单tsconfig.json— TypeScript 配置README.md/README.en.md— 说明文档LICENSE— MIT 许可证
MIT