# pi-delegate

[English](README.md) | [简体中文](README.zh-CN.md)

无需离开当前会话，即可将专注的任务委派给全新的 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 安装

```sh
pi install npm:@wangjq4214/pi-delegate
```

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

### 本地开发配置

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

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

开发用 Git hook 通过 `bun run hooks:install` 显式安装；npm 用户安装时不会运行开发 hook。具体配置请参阅[开发指南](docs/development.md)。

### 直接加载扩展

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

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

### 作为本地 Pi package 安装

安装 Pi CLI 后执行：

```sh
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 概览](../../README.zh-CN.md)。

## 使用

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

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

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

```json
{
  "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。

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

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

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

参数、结果状态、催促配置和状态 UI 的详细说明请参阅[使用指南](docs/usage.md)。

## 限制

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

工具继承、生命周期、交互和清理边界请参阅[运行机制与安全边界](docs/runtime.md)。

## 文档

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

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

## 参与贡献

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

## 许可证

采用 [MIT 许可证](../../LICENSE)，完整许可文本位于 workspace 根目录。