pi-delegate

English | 简体中文

无需离开当前会话，即可将专注的任务委派给全新的 Pi 子 agent。

pi-delegate 是一个 Pi TypeScript 扩展，通过 RPC 启动一次性子 agent，支持同步返回结果或显式启用后台执行。

功能

• 全新的子 agent：每个任务使用新会话；委派工具仅对主 agent 可用。
• 工具继承：重新初始化主 agent 的工具和扩展，保留启用状态与可发现性。
• 同步与后台执行：等待结果，或在会话所属任务运行期间继续其他工作。
• 任务管理：发现同步／后台任务、查看保留的结果，通过浮动 /delegates TUI 面板或工具管理后台任务。
• 运行时 steering：向活跃后台子 agent 补充背景、缩小范围或请求报告，无需取消并重启。
• 软催促与状态 UI：配置任务级收尾提醒，在 TUI 输入框上方查看子 agent 状态。
• 可选执行预算：提前向子 agent 披露任务级时间／轮次上限，观察到任一上限即取消，与软催促相互独立。

环境要求

• 本地安装需要 Git 和 Bun 1.4.1 或更高版本。
• Node.js 22.19 或更高版本。Pi 在 Bun 下运行时，子进程需要能从 PATH 找到 node。
• 兼容的 Pi 宿主。本扩展已在 @earendil-works/pi-coding-agent@1.1.0 上验证；其他宿主版本尚未验证。

安装

从 npm 安装

pi install npm:@wangjq4214/pi-delegate

npm 包包含构建后的扩展和 worktree skill，无需本地构建。

本地开发配置

在本地 Git 仓库的根目录执行：

bun install --frozen-lockfile
bun run hooks:install
bun run build

开发用 Git hook 通过 bun run hooks:install 显式安装；npm 用户安装时不会运行开发 hook。具体配置请参阅开发指南。

直接加载扩展

bun run --cwd packages/pi-delegate pi --extension ./src/index.ts

Pi 直接加载 TypeScript 源码，无需构建。

作为本地 Pi package 安装

安装 Pi CLI 后执行：

pi install /absolute/path/to/checkout/packages/pi-delegate

package.json 声明了构建后的 dist/index.js 扩展入口和随包提供的 delegate-worktree skill。本地仓库安装前请先安装依赖，并执行 bun run build。

此包现位于 Bun workspace 的 packages/pi-delegate 中。根目录为 private，请在本包目录打包/发布。参阅 workspace 概览。

使用

主 agent 可以调用 delegate，明确提供任务及所需背景：

{
  "task": "Review error handling in src/ and report findings with file paths",
  "context": "Analyze only; do not modify files"
}

默认情况下，调用会等待子 agent 的最终结果。如需在子 agent 运行期间继续工作，可以显式启用后台模式：

{
  "task": "Analyze test coverage and report gaps",
  "context": "Analyze only; do not modify files",
  "background": true
}

后台任务结束时不会自动发送完成消息，也不会唤醒主 agent。请通过 delegate_list 发现任务，再用 delegate_status 按需获取结果。

工具	用途
delegate	启动全新的同步或后台子 agent。
delegate_list	返回当前会话／分支内的有界任务摘要。
delegate_status	使用精确 taskId 查看同步或后台任务详情。
delegate_cancel	取消后台任务并等待资源清理。
delegate_steer	使用 taskId 向活跃后台任务提交纯文本指令。

在 TUI 模式中，/delegates 打开单个浮动面板，依次浏览列表、详情、取消确认／指令输入。同步任务 ID 仅供查询，独立取消与 steering 仍只适用于后台任务。记录／结果不会随五秒状态行消失而删除，但会随所属作用域失效；无需安装 pi-open-tui。

两种模式都可选择执行上限：

{ "task": "分析核心风险，并如实报告未完成工作", "budget": { "maxSeconds": 120, "maxTurns": 8 } }

每个省略的维度均不受限，不增加默认强制预算。秒数必须为正有限数，轮次必须为正整数（零无效）。子 agent 开始工作前会收到预算说明。时间不包含排队／初始化，但包含 provider／工具及等待；轮次指完成的 assistant 响应及其关联工具。观察到任一上限即取消，不提供额外报告生成机会。结果明确标识预算取消并保留可用的部分文本／usage；不会回滚副作用，也不保证瞬时停止进程。详见执行预算。

参数、结果状态、催促配置和状态 UI 的详细说明请参阅使用指南。

限制

• 后台执行需要长期运行的 TUI 或 RPC 会话。退出、重载、替换会话或分支导航后，任务不会继续运行。
• 主／子 agent 默认共享工作目录；可通过 cwd 选择其他已有目录。随包提供的 delegate-worktree skill 指导主 agent 管理 Git 工作区；扩展本身不管理 worktree、不强制文件系统隔离，也不提供操作系统沙箱。
• 不会自动复制主 agent 的完整对话，请明确提供相关背景。
• 软催促只是建议，不是强制超时。后台 usage 与 Pi 主会话总量分开报告。
• Steering 回执只确认 RPC 处理结果，不确认模型消费或任务完成；初始化期间返回 not_ready，超时结果不确定，不应自动重试。

工具继承、生命周期、交互和清理边界请参阅运行机制与安全边界。

文档

• 使用指南 — 工具、参数、结果、催促和 TUI 行为。
• 运行机制与安全边界 — 工具继承、进程归属、取消和安全边界。
• 开发指南 — 环境配置、检查、测试、Git hooks 和仓库结构。
• 路线图 — 按优先级排列的能力候选与 TODO。

详细文档统一使用英文维护。

参与贡献

修改前请阅读开发指南。运行其中列出的检查与测试；更新项目级文档时，请保持中英文 README 内容一致。

许可证

采用 MIT 许可证，完整许可文本位于 workspace 根目录。