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

# Pi Smart Subagents

在 [Pi](https://pi.dev/) 中运行独立子代理和托管 shell 命令。子代理模型由 Jev 选择；普通命令任务直接使用现有的 `bash` 工具，不调用模型选择器。

本项目是 Luke Parke 的 `@parke.dev/pi-subagent` 的独立社区分支，上游来自 [LukasParke/pi-extensions](https://github.com/LukasParke/pi-extensions/tree/main/packages/pi-subagent)。保留命名代理、并行与后台任务、工作树隔离和用量统计，增加 Jev 模型路由与子代理能力检查。

<a id="quick-start"></a>
## 安装

需要 Node.js 22.19.0 或更高版本及 Pi。不要同时启用本分支和 `@parke.dev/pi-subagent`，两者会注册相同的工具。

```bash
pi install npm:@cr1ms0n/pi-subagent
```

首次使用**子代理**前，在 `~/.pi/subagent.json` 中配置 TypeSafe API key 和候选模型。参阅[配置示例](docs/REFERENCE.md#jev-routing)，妥善保管凭据；已有配置时，请合并修改，不要直接覆盖。

独立的 `task` 工具需要 Pi 1.2.0+ 和可调用的 `bash`，不需要 Jev 配置。本包包含两个扩展入口，也支持分别加载。

## 命令任务

在当前目录运行非交互式构建、命令或脚本时，使用 `task`：

```json
{ "command": "npm run build" }
```

默认最多等待 30 秒，然后返回同一个 task ID，原命令继续在后台执行。设置 `"background": true` 可立即返回回执，`timeout_ms` 可调整本次等待时间。原生 `bash.timeout` 仍然是硬性停止期限。

保留完整 task ID，通过 `list`、`status`、`output`、`wait` 和 `cancel` 管理。日志保留在配置的会话目录下，输出支持可重复读取的 UTF-8 字节游标。后台完成时通知所属会话，除非关闭了通知。退出、重新加载、分支或会话替换会请求取消；任务不是持久守护进程。详见[命令任务示例与限制](docs/REFERENCE.md#managed-shell-tasks)。

<a id="delegation"></a>
## 子代理使用

直接对 Pi 说，例如：

> 用只读子代理查看这个项目的目录结构，并总结主要模块。

Jev 选择模型，不逐个选择工具。本地策略控制允许的工具集，启动时检查子代理实际可用的能力。显式请求的工具必须可用，详细规则见[工具策略与路由参考](docs/REFERENCE.md#jev-routing)。

默认的 **compact（精简）** 模式保留常规委派、并行与后台任务、预算和工作树管理。如需恢复会话、汇总、结构化输出等高级请求参数，请将以下字段合并到 `~/.pi/subagent.json`，等活动任务结束后重新加载或重启 Pi：

```json
{ "toolMode": "full" }
```

参数划分和升级行为见[工具模式说明](docs/REFERENCE.md#tool-modes)。

子代理的 `timeout_ms` 是提醒阈值，不再是停止期限。达到阈值时，前台调用返回 run ID，同一任务继续在后台执行。通过 `status`、`wait`、`steer` 或 `cancel` 决定下一步。已有时间设置也改为此提醒语义；轮数、费用预算和独立故障检查仍保留。详见[预算与重试说明](docs/REFERENCE.md#budgets-and-retries)。

本包启动的每个子代理都会自动收到一条包内置的强制规则：不得运行测试或测试命令，也不得创建或修改测试代码。子代理只做实现和静态审查，并如实说明未测试的部分；可执行的测试工作只归顶层主代理（TOP-LEVEL main agent），任何子代理都不拥有测试权，中间层委派代理同样是子代理。日志和备份在既有任务范围与工具权限内仍然允许。这是提示词层面的指令，不是沙箱；它只对更新后的包代码加载之后新启动的子代理生效，不追溯已运行的子代理，也不覆盖独立启动或自定义后端的进程。详见[委派测试边界](docs/REFERENCE.md#delegated-testing-boundary)。

- 使用 `/subagents` 查看和管理子代理运行。
- 使用 `/subagent-cost` 查看用量。
- 命名代理、并行任务、后台执行、工作树和结构化结果见[使用参考](docs/REFERENCE.md#quick-usage)，键盘操作见 [TUI 指南](docs/UX.md)。

模型执行与 Jev 选择可能分别产生费用。规划操作也会调用 Jev；`max_cost` 不限制 TypeSafe 选择器费用。详见[费用统计说明](docs/COST-ACCOUNTING.md)。

路由会向选择器发送任务文本和候选模型信息。仅将 `jevRouting.baseUrl` 设置为受信任的端点，因为它会改变路由数据和路由凭据的接收方。详见[安全说明](docs/SECURITY.md)。

<a id="license"></a>
## 许可证

[MIT](LICENSE)。Copyright (c) 2026 Luke Parke。社区分支由 cr1ms0n（awoaCrim）维护。重新分发时请保留原始版权声明和许可证。

译自 [README.md](README.md)，英文文件 blob：`2bdbbd761b0f180eb910a268534dcafffbde2989`。中英文内容如有差异，以英文为准。

感谢 [Linux.do](https://linux.do/)。