subagent-isolation

主 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 仍然复用主 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

| Before | After | |--------|-------| | 一个 agent 同时做规划和执行，上下文超过阈值后推理质量下降 | 主 agent 只规划委派，每个子 agent 只处理自己的任务片段 | | 主 agent 仍保留写文件、跑命令能力，隔离不彻底 | 主 agent 被剥夺 write/edit/bash，子 agent 在独立进程中运行 | | 所有 skill 和工具堆在一个 agent 里，互相干扰 | 每个子 agent 只加载自己需要的 skill 和 tools |

核心设计

| 角色 | 职责 | 运行位置 | |------|------|----------| | 主 agent | 理解需求、拆分任务、委派与汇总 | 你的 pi 主会话 | | 子 agent | 读代码、改代码、跑验证并返回结果 | 独立的 pi --mode json 进程 |

一个典型任务这样流转：

1. 你向主 agent 提出任务。
2. 主 agent 通过 subagent tool 启动一个独立 pi 进程。
3. 子 agent 只拿到委派的那一句话和自身配置，完成具体修改。
4. 子 agent 返回结果并退出，主 agent 决定下一步。

四个层面的隔离：

• 进程隔离：每个子 agent 启动新的 pi --mode json 进程，system prompt 写入临时文件并通过 --append-system-prompt 注入，互不污染。
• 上下文隔离：子 agent 看不到主 agent 的执行痕迹，只拿到你委派的那一句话。
• 能力隔离：通过 tools 和 skills 字段，给不同子 agent 配备不同的工具箱。
• 递归边界：子 agent 可配置为禁止继续向下委派，任务范围始终可控。

前置条件：安装 Pi Agent

subagent-isolation 是一个 Pi Package，需要先安装 Pi Agent。

本扩展需要 Node.js >= 20（与 package.json 中的 engines.node 一致）。

方式一：一键安装（推荐 Linux / macOS）

curl -fsSL https://pi.dev/install.sh | sh

方式二：通过 npm 全局安装

npm install -g --ignore-scripts @earendil-works/pi-coding-agent

安装完成后，你就可以在终端使用 pi 命令了。

30 秒快速开始

1. 安装扩展

pi install npm:subagent-isolation

2. 复制示例 agent

示例已经包含这个配置，你可以直接复制，也可以按需修改：

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/ 目录，可按需修改。

直接复制即可使用，也可以根据自己的需求调整。

3. 用自然语言指派任务

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。

示例 agents

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，每个子 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。

架构与工作流程

1. 用户提出需求。
2. 主 agent 拆分任务，并决定委派给哪个子 agent。
3. subagent tool 为子 agent 启动独立的 pi 进程。
4. 子 agent 在干净上下文中执行，只使用指定的 tools/skills。
5. 子 agent 返回结果并退出，主 agent 汇总后继续。

主 agent 只保留"要做什么"和"结果是什么"，中间的工具调用痕迹全部留在子 agent 的进程里。任务越复杂，这种隔离带来的收益越明显。

示例 skills

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 许可证

License

MIT