---
slug: "subagent-isolation"
source_type: "readme"
source_url: "https://cdn.jsdelivr.net/gh/Wolido/subagent-isolation@main/README.md"
repo: "https://github.com/Wolido/subagent-isolation"
source_file: "README.md"
branch: "main"
---
# subagent-isolation
[]()
[]()
[](https://www.npmjs.com/package/subagent-isolation)
[](LICENSE)
主 agent 不能碰代码。没有 `write`，没有 `edit`，没有 `bash`。它只有 `read`、`grep`、`find`、`ls` 四个只读工具，外加一个 `subagent` 工具用来委派任务。所有修改文件、跑命令、执行逻辑的工作，全部交给子 agent——每个子 agent 跑在独立的 `pi` 进程中，有自己的 system prompt 和 skills。主 agent 和子 agent 之间，子 agent 和子 agent 之间，进程完全隔离。
**subagent-isolation** 是 [Pi Agent](https://github.com/earendil-works/pi) 的扩展。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）
```bash
curl -fsSL https://pi.dev/install.sh | sh
```
### 方式二：通过 npm 全局安装
```bash
npm install -g --ignore-scripts @earendil-works/pi-coding-agent
```
安装完成后，你就可以在终端使用 `pi` 命令了。
---
## 30 秒快速开始
### 1. 安装扩展
```bash
pi install npm:subagent-isolation
```
### 2. 复制示例 agent
示例已经包含这个配置，你可以直接复制，也可以按需修改：
```bash
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. 用自然语言指派任务
```bash
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` 中加入：
```bash
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](https://github.com/Wolido/subagent-isolation/blob/HEAD/ADVANCED.md)。
---
## 示例 agents
GitHub 仓库的 [`examples/pi/agent/agents/`](https://github.com/Wolido/subagent-isolation/tree/main/examples/pi/agent/agents) 提供了三个可直接参考的 agent：
| Agent | 作用 | 可用工具 | 加载的 skill |
|-------|------|----------|-------------|
| [`coder`](https://github.com/Wolido/subagent-isolation/blob/main/examples/pi/agent/agents/coder.md) | 写代码、改代码、跑验证 | `read, write, edit, bash, grep, find, ls` | `systematic-debugging` |
| [`reviewer`](https://github.com/Wolido/subagent-isolation/blob/main/examples/pi/agent/agents/reviewer.md) | 只读评审，输出可操作的反馈 | `read, grep, find, ls` | _(无)_ |
| [`writer`](https://github.com/Wolido/subagent-isolation/blob/main/examples/pi/agent/agents/writer.md) | 写文档、改 README、生成 commit message | `read, write, edit, grep, find, ls` | `writing-clearly-and-concisely` |
把它们复制到 `~/.pi/agent/agents/`（用户级）或项目内的 `.pi/agents/`（项目级）即可使用。
如果你已经克隆了仓库，可以直接复制：
```bash
cp examples/pi/agent/agents/*.md ~/.pi/agent/agents/
```
也可以单独从 GitHub 下载（以 `coder` 为例）：
```bash
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/`：
```bash
cp examples/pi/agent/agents/*.md ~/.pi/agent/agents/
```
然后使用以下命令启动主 agent：
```bash
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 适合不同模型。如果你的主 agent 默认使用 Kimi K3（$3/$15 per M token），给 `coder`、`writer`、`reviewer` 全部用 Kimi K3 成本会很高。`coder` 需要强推理能力，适合 DeepSeek V4 Pro（$0.44/$0.87，性价比高）；`writer` 和 `reviewer` 任务较轻，用最便宜的 DeepSeek V4 Flash（$0.14/$0.28）就够了。把昂贵模型留给主 agent 做规划，能显著降低成本。
### 配置文件
通过 `subagent-isolation.json` 为每个子 agent 单独指定模型名称：
- **用户级**：`~/.pi/agent/subagent-isolation.json`
- **项目级**：`.pi/subagent-isolation.json`（从工作目录向上搜索）
格式为 JSON key-value map，key 是 agent 名，value 是模型字符串：
```json
{
"coder": "deepseek/deepseek-v4-pro",
"writer": "deepseek/deepseek-v4-flash",
"reviewer": "deepseek/deepseek-v4-flash"
}
```
这样配置后，主 agent 仍使用默认的 Kimi K3 做规划和决策，`coder` 使用 DeepSeek V4 Pro 处理代码修改，`writer` 和 `reviewer` 使用最便宜的 DeepSeek V4 Flash。整体成本大幅降低——大部分工作由低价模型完成，只有规划和复杂推理才用到高价模型。
### 优先级规则
模型选择的优先级（从高到低）：
1. `subagent-isolation.json` 中的配置
2. Agent frontmatter 中的 `model` 字段
3. 继承父 agent 的模型
### 合并规则
项目级配置覆盖用户级同名 key。例如用户级为 `coder` 指定了 `deepseek/deepseek-v4-pro`，项目级为 `coder` 指定了 `kimi-coding/k3`，则项目中使用 Kimi K3。
---
## 架构与工作流程
1. 用户提出需求。
2. 主 agent 拆分任务，并决定委派给哪个子 agent。
3. `subagent` tool 为子 agent 启动独立的 pi 进程。
4. 子 agent 在干净上下文中执行，只使用指定的 tools/skills。
5. 子 agent 返回结果并退出，主 agent 汇总后继续。
主 agent 只保留"要做什么"和"结果是什么"，中间的工具调用痕迹全部留在子 agent 的进程里。任务越复杂，这种隔离带来的收益越明显。
---
## 示例 skills
GitHub 仓库的 [`examples/pi/agent/skills/`](https://github.com/Wolido/subagent-isolation/tree/main/examples/pi/agent/skills) 提供了三个可直接使用的 skill：
| Skill | 使用者 | 描述 |
|-------|--------|------|
| [`brainstorming`](https://github.com/Wolido/subagent-isolation/tree/main/examples/pi/agent/skills/brainstorming) | 主 agent | 通过协作对话把想法变成完整设计 |
| [`systematic-debugging`](https://github.com/Wolido/subagent-isolation/tree/main/examples/pi/agent/skills/systematic-debugging) | `coder` | 修 bug 前先找根因（四阶段流程） |
| [`writing-clearly-and-concisely`](https://github.com/Wolido/subagent-isolation/tree/main/examples/pi/agent/skills/writing-clearly-and-concisely) | `writer` | 用简洁规则、AI 痕迹检测和人味注入打磨文字 |
把这些 skill 复制到 `~/.pi/agent/skills/`：
```bash
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](https://github.com/Wolido/subagent-isolation/blob/HEAD/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
