Pi Subagent Cluster

这是一个 Pi 扩展包，用于把复杂任务拆成任务图，交给隔离的 Pi 子进程执行，并通过同模型审核器自动重试和升级 worker 等级。

使用建议

为了让主 agent 更稳定地判断任务复杂度、拆解任务并提交可审核的任务图，建议将本仓库 AGENTS.md 中的内容添加到你自己的 AGENTS.md 中。这样 Pi 在处理项目任务时可以遵循统一的任务分流、验收标准和协作约束，通常能获得最佳效果。

安装

当前 Pi CLI 的 npm 包源使用 npm: 前缀：

pi install npm:@0xbb2b/pi-subagent-cluster

安装后重启 Pi。扩展会自动注册 subagent_cluster 工具、/subagent-cluster dashboard 命令和 /subagent-settings 设置命令。

从 Git 克隆后本地安装

将 <仓库地址> 替换为实际 Git 仓库地址，将扩展克隆到本地：

git clone <仓库地址> "$HOME/Projects/pi-subagent-cluster"

Pi 的包根目录必须是包含 package.json 的目录。可以全局安装这个本地包：

pi install "$HOME/Projects/pi-subagent-cluster"

如果只希望某个项目使用本地版本，请在目标项目目录执行：

cd /path/to/your-project
pi install -l --approve "$HOME/Projects/pi-subagent-cluster"

-l 会把配置写入当前项目的 .pi/settings.json。本地路径安装不会复制文件，Pi 会直接读取 Git 克隆目录，因此修改代码后无需重新安装，也不需要先执行 npm publish。当前包只使用 Pi 已提供的核心依赖，无需在扩展目录单独执行 npm install。

二次开发

进入本地克隆目录后，直接修改 extensions/ 下的 TypeScript 文件：

cd "$HOME/Projects/pi-subagent-cluster"
# 修改 extensions/index.ts、extensions/scheduler.ts 等文件

正在运行 Pi 时可以输入 /reload 重新加载扩展；如果当前 Pi 版本或运行模式不适合热重载，退出后重新启动 Pi 即可。也可以不写入任何安装配置，临时加载入口进行验证：

pi --no-extensions \
  --extension "$HOME/Projects/pi-subagent-cluster/extensions/index.ts"

发布前可以检查 npm 包实际会包含哪些文件：

cd "$HOME/Projects/pi-subagent-cluster"
npm pack --dry-run

查看或移除本地安装：

pi list
pi remove "$HOME/Projects/pi-subagent-cluster"

# 如果使用了项目级安装：
cd /path/to/your-project
pi list
pi remove -l "$HOME/Projects/pi-subagent-cluster"

配置

项目配置放在 .pi/subagent-cluster.json，也可以放在 ~/.pi/agent/subagent-cluster.json 作为全局配置。配置会从当前工作目录向上查找，项目配置优先于全局配置。

当前只支持标准 JSON：配置文件中不能写 //、/* ... */ 注释，也不能使用尾逗号。下面的示例可以直接复制到 .pi/subagent-cluster.json；参数解释见后面的参数速查表。

{
  "levels": {
    "high": {
      "model": "openai/gpt-5.6",
      "thinkingLevel": "high",
      "tools": ["read", "grep", "find", "ls", "bash", "edit", "write"],
      "timeoutMs": 1800000
    },
    "medium": {
      "model": "openai/gpt-5.6",
      "thinkingLevel": "medium",
      "tools": ["read", "grep", "find", "ls", "bash", "edit", "write"],
      "timeoutMs": 1200000
    },
    "low": {
      "model": "openai/gpt-5.6",
      "thinkingLevel": "low",
      "tools": ["read", "grep", "find", "ls", "bash", "edit", "write"],
      "timeoutMs": 900000
    }
  },
  "reviewer": {
    "thinkingLevel": "medium",
    "tools": ["read", "grep", "find", "ls"],
    "timeoutMs": 180000
  },
  "maxConcurrency": 4,
  "maxTasks": 8,
  "maxRetriesPerLevel": 1
}

参数速查

| 参数 | 类型 | 作用 | |---|---|---| | levels | 对象 | 配置三个 worker 等级；必须包含 low、medium、high。 | | levels.<level>.model | 字符串 | worker 使用的模型，推荐使用 provider/model 格式。 | | levels.<level>.thinkingLevel | 字符串 | worker 的推理强度；/subagent-settings 会根据当前模型能力过滤可选值。 | | levels.<level>.tools | 字符串数组 | worker 可调用的工具；写入类工具会允许 worker 修改项目。 | | levels.<level>.timeoutMs | 正整数 | 该等级 worker 的单次超时时间，单位毫秒。 | | reviewer.model | 字符串 | 审核器使用的固定模型；省略时跟随主 agent。 | | reviewer.thinkingLevel | 字符串 | 审核器推理强度；省略时跟随主 agent，固定模型时按模型能力选择。 | | reviewer.tools | 字符串数组 | 审核器工具，只能是 read、grep、find、ls。 | | reviewer.timeoutMs | 正整数 | 单次审核超时时间，单位毫秒。 | | maxConcurrency | 正整数 | 同时运行的最大 worker 数量。 | | maxTasks | 正整数 | 单次集群允许的最大任务数量。 | | maxRetriesPerLevel | 非负整数 | 自动升级前的同等级重试次数。 |

reviewer.model 可配置固定审核模型；省略时审核器使用当前主 agent 的模型。reviewer 只控制审核器的模型、thinking level、只读工具和超时。

设置命令

使用 /subagent-settings 打开 subagent-cluster 专属设置页。它不会覆盖 Pi 内置的 /settings：

• /settings：Pi 自身设置。
• /subagent-settings：subagent-cluster 设置。

设置页主菜单按分组显示：

HIGH
MEDIUM
LOW
REVIEWER
CLUSTER

进入 HIGH、MEDIUM 或 LOW 二级菜单后，可以配置模型、thinking level、worker tools 和 timeout。进入 REVIEWER 二级菜单后，可以配置固定模型、thinking level、只读 tools 和 timeout；当 Model 选择“跟随主 agent”时，Thinking level 也可以选择“跟随主 agent”。reviewer tools 可在 read、grep、find、ls 中多选。CLUSTER 二级菜单配置最大并发数、最大任务数和同等级重试次数。

每次模型、thinking、tools 或数字参数切换后都会自动保存，不需要单独点击保存。

每次修改后自动写入全局配置：

~/.pi/agent/subagent-cluster.json

项目配置仍然可以放在 .pi/subagent-cluster.json，并且优先于全局配置；/subagent-settings 修改的是全局配置，便于多个项目共享同一套模型和调度参数。如果当前项目存在 .pi/subagent-cluster.json，它会覆盖全局配置；要让当前项目使用全局设置，需要删除或移走项目级配置。

使用方式

主 agent 会根据任务复杂度决定是否调用 subagent_cluster。调用时必须提交结构化任务图：

{
  "goal": "实现用户管理后台",
  "tasks": [
    {
      "id": "backend",
      "title": "实现后端接口",
      "task": "实现用户列表、创建、编辑和删除接口",
      "acceptanceCriteria": [
        "接口遵循项目现有路由约定",
        "包含输入校验",
        "测试全部通过"
      ],
      "level": "low",
      "dependsOn": []
    },
    {
      "id": "frontend",
      "title": "实现管理页面",
      "task": "实现用户列表和编辑表单页面",
      "acceptanceCriteria": [
        "页面可以加载用户列表",
        "表单错误可见",
        "构建和测试全部通过"
      ],
      "level": "medium",
      "dependsOn": ["backend"]
    }
  ]
}

执行集群后任务会在后台运行，不会占用输入栏。输入栏下方会显示一行集群状态栏：

• 输入栏为空时按 ↓：选择集群状态栏
• 按 Enter：打开集群管理 dashboard，等价于 /subagent-cluster
• 也可以随时输入 /subagent-cluster 打开 dashboard
• 集群完成后，结果会作为后台消息自动返回主 agent

Dashboard 操作

• ↑↓ 或 j/k：选择任务
• Enter：展开或收起选中任务的输出
• p：暂停或继续新任务调度
• r：重试等待用户决策的任务
• e：手动提升等待用户决策的任务等级
• a：接受当前结果
• x：放弃当前任务
• Escape：退出 dashboard，返回输入栏，不会取消集群
• Ctrl+C：取消整个集群

任务需要用户决策时，问题会回到主对话区，并暂停任务调度及正在运行的 worker/reviewer 子进程，避免等待期间消耗超时时间。请在主输入框回复选项编号或动作（例如 1、retry、升级）；答复会直接恢复对应任务，不会再触发一轮无关的主 agent 对话。

底部快捷键会按状态动态显示：运行中显示暂停和取消；手动暂停时显示继续；等待用户决策时显示重试、升级、接受和放弃；完成、失败或取消后只保留查看、返回和退出。

正在执行的 worker 不会被 p 强制杀死；p 和用户决策等待会挂起子进程，恢复后继续执行。取消会向所有 worker 和审核器子进程发送终止信号。

Dashboard 布局

管理页采用分层 workflow navigator：

• 概览页：左侧是任务列表，显示完成标识、任务标题、状态、等级和尝试次数；右侧显示当前 subagent 的 Prompt、Result 和 Recent activity。
• 在任务列表按 Enter：进入当前 subagent 详情页，查看状态、等级、模型、Prompt、Result 和最近活动。
• 在 subagent 详情页再次按 Enter：进入完整历史 pager，查看 assistant 消息、工具调用、工具结果和审核阶段。
• 历史 pager 默认使用终端可用的最大垂直空间，尽可能显示全部记录；历史超过屏幕高度时，支持 ↑↓、j/k、PgUp/PgDn、Home/End 翻阅全部上下文。
• Escape 按页面层级逐级返回；概览页按 Escape 退出 dashboard。

执行和审核流程

1. 主 agent 提交任务图。
2. 调度器校验任务 ID、依赖关系、任务数和验收标准。
3. 没有未完成依赖的任务按配置并行执行。
4. worker 使用独立的 pi --mode json --no-session 子进程执行。
5. 同模型只读审核器逐条检查验收标准。
6. 审核通过后任务完成；审核重试达到当前等级上限后自动升级。
7. 高等级仍不能通过时进入 paused_for_user，问题回到主对话区等待用户决策；等待期间暂停任务调度及正在运行的子进程。
8. 审核器超时会将任务标记为 timed_out，审核器返回无效 JSON 会将任务标记为审核失败，不会误进入 paused_for_user。
9. Pi 会话退出或重载后，无法恢复的运行中快照会显示为已取消，而不是继续显示等待用户决策。
10. 每次运行会保存到 ~/.pi/agent/subagent-cluster/runs/--项目绝对路径编码--/<run-id>/，例如当前项目对应 ~/.pi/agent/subagent-cluster/runs/--Users-bb-Projects-pi-subagent-cluster--/<run-id>/，包括状态快照和各任务输出。

worker 子进程不会加载当前扩展，避免扩展递归启动；它会在任务目录中使用项目上下文和配置的工具权限。审核器只使用只读工具。