@1oid/pi-subagents-team0.1.0

pi-subagents-team

English | 简体中文

让当前 Pi 对话充当 leader，由它给多个成员派工。成员各有自己的上下文、模型、工具和 skill 配置。支持并行工作，以及继续向原成员追问。

需要 Pi 1.2.0 和 Node.js 22.18+。

安装与试用

在本仓库执行：

npm install
pi install .
mkdir -p ~/.pi/agent/agents/pi-subagents-team
cp -R examples/dev-team ~/.pi/agent/agents/pi-subagents-team/

如果使用了 PI_CODING_AGENT_DIR，把配置放到该目录的 agents/pi-subagents-team/ 下。插件通过 Pi 的 getAgentDir() 获取路径。

重新启动 Pi，或在 Pi 中执行 /reload。也可以不安装，临时执行 pi -e ./index.ts。

/dev-lead 调查这个项目的登录流程，修复已确认的问题并审查修改
请让 reviewer 再检查一下错误处理。
/team
/team exit

/dev-lead 不带任务只切换模式。进入之后，普通消息都由 leader 处理。再次输入同一个 leader 命令不会清空成员上下文。切换到其他 leader 时，旧成员会话结束。

/team 列出可用小队和当前成员状态。/team exit 停止正在执行的成员任务，恢复进入小队前的工具、模型和思考强度。普通对话历史保留。

也可以直接说：

使用 dev-team 进行登录流程的调查、修复和审查。
切换到 review-team，检查刚才的修改。

插件会把可用小队的 ID、leader 名称和说明提供给模型。模型识别到使用小队的要求后，调用 team_activate({ team: "dev-team" })；激活完成就以对应 leader 的角色、模型和白名单继续当前任务，再调用 team_delegate 派工，不需要重发任务。

小队 ID 就是 agents/pi-subagents-team/ 下的目录名，/team 可以查看。这里只由模型理解自然语言并调用工具，没有固定句式匹配；名称不明确时应先澄清，普通对话不会由插件强制切队。重复激活当前小队保留成员上下文，切换到其他小队会释放旧成员会话。

Pi 1.2 的非交互模式使用斜杠命令时，需要将命令和任务作为两个输入传入；使用自然语言激活时只需一个输入：

pi -p "/dev-lead" "调查登录流程并审查实现"
pi -p "使用 dev-team 调查登录流程并审查实现"

配置

每个小队一个目录：

~/.pi/agent/agents/pi-subagents-team/
└── dev-team/
    ├── team.yaml
    ├── leader.md
    ├── scout.md
    ├── worker.md
    └── reviewer.md

完整的可运行示例见 examples/dev-team/。team.yaml 定义角色，Markdown 文件只写提示词，不需要 YAML frontmatter。

description: 开发小队
leader:
  name: dev-lead
  prompt: leader.md
  tools: [read, grep, find, ls]
  skills: []
members:
  - name: worker
    description: 修改代码并运行测试
    prompt: worker.md

字段	含义
description	小队说明；每个成员也必须有职责说明
leader	唯一的 leader
members	一个或多个成员
name	小写字母开头，后续允许小写字母、数字和连字符；leader 名即调用命令
prompt	提示词文件，相对于本小队目录解析
tools	可选的工具名称数组，精确匹配，不支持通配符或 + / - 修饰
skills	可选的技能名称数组，使用技能声明的名称，不是路径
model	可选，格式为 provider/model-id，必须是当前 Pi 已配置的模型
thinkingLevel	可选：off、minimal、low、medium、high、xhigh；Pi 会按模型能力调整

所有角色都可以分别配置 model 和 thinkingLevel。省略时使用进入小队前的模型和思考强度，不会因为 leader 配了另一个模型就改变成员默认值。

tools 与 skills 独立生效：

• 省略：开放当前 Pi 配置中可用的这一类资源，包括扩展提供的内容。
• []：不开放任何这一类资源。
• 名称数组：只开放列出的项。名称不存在则报错，不回退到全部资源。

leader 始终额外拥有 team_activate 和 team_delegate，即使 tools: [] 也能切换小队和派工。不要把这两个工具写进白名单，成员没有这两个工具。

让模型自行读取 skill 说明时，工具白名单也需要允许 read。插件不会因为配置了 skill 就偷偷增加文件读取工具。

同名 leader 的所有配置都会被拒绝；同队成员不能重名。与已有命令或 Pi 内置命令重名时不会覆盖原命令。修改配置或提示词后执行 /reload。

执行方式

leader 可以调用：

{
  "tasks": [
    { "member": "scout", "task": "调查登录流程，返回相关文件和调用关系" },
    { "member": "reviewer", "task": "检查登录相关测试有哪些遗漏" }
  ]
}

不同成员同时执行，全部结束后返回各自状态、输出和用量。再次给同一成员派工时复用上下文。同一成员不能同时执行两个任务，也不能在一批任务中重复出现。一个成员失败不会丢掉其他成员的结果。

成员按需启动独立 Pi SDK 会话，使用当前项目目录、已信任的项目配置和用户配置。成员不会获得 leader 的完整聊天记录；leader 应在任务中提供足够背景。成员中的扩展按非交互模式运行，依赖终端对话框的扩展可能无法使用。仅存在于其他扩展内存中的临时资源不能保证在成员中重建；显式白名单资源缺失会报错。

team_delegate 在 Pi 终端中使用当前主题显示成员列表，单个任务和并行任务采用相同布局：

team_delegate · 2 位成员
● [scout] [调查登录流程] 运行中 · 执行 read
✓ [reviewer] [检查现有测试的遗漏] 已完成

列表会保留本次派工的所有成员，每行随启动、思考、工具执行、完成、失败或取消更新。任务简介自动合并换行并截短，适配终端宽度；展开工具结果可查看完整任务和成员输出。颜色跟随当前 Pi 主题，无需额外配置。

取消 leader 当前任务时会同时取消它正在等待的成员任务。退出小队、切换小队、切换 Pi 会话、/new、/reload 或退出 Pi 都会释放成员会话；不做后台运行或重启恢复。成员修改过的文件不会因此撤销。

所有成员共享工作目录，示例要求 leader 分清文件职责，不同时安排修改同一文件。插件不创建独立工作目录，也不自动提交代码。

白名单的范围

工具限制同时用于模型可见列表和 Pi 的实际工具调用，包括 codemode 等工具通过 Pi 接口发起的间接调用。工具搜索改变激活列表后会恢复角色配置。

skill 限制控制提供给角色的技能目录和 /skill:name 调用，不是文件系统隔离。允许 read 或 bash 后，角色仍然可能读取其他技能文件。已存在于对话历史中的技能内容也不会被抹除。

插件不审计其他扩展在 JavaScript 内部直接执行的操作，也不限制用户手动执行的 shell 命令或扩展命令。需要限制角色操作范围时，应同时选择合适的工具，不要只限制 skill。

开发与验证

npm run check

测试使用临时 Pi 配置目录和模拟模型，真实运行 SDK 会话，不读取用户认证，也不调用付费模型。覆盖配置错误、命令冲突、白名单、并行派工、成员追问、失败、取消和模式退出。命令行测试还会加载随附示例，让 scout、worker、reviewer 依次调查、修复、审查临时 JavaScript 文件，再实际调用修复后的函数验证结果。

手动验收：复制示例配置，在一个测试项目中运行 /dev-lead，完成调查、修改、审查和追问，再运行 /team exit 检查原模型及工具恢复。真实任务会使用你在 Pi 中配置的模型。

参考：Pi Packages、Pi SDK。