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

# Pi Smart Subagents

在 [Pi](https://pi.dev/) 中运行独立子代理，由 Jev 为每项任务选择执行模型和具体工具。

npm 包名为 `@cr1ms0n/pi-subagent`。本项目是 Luke Parke 的 `@parke.dev/pi-subagent` 0.8.0 的独立社区分支，上游来自 [LukasParke/pi-extensions](https://github.com/LukasParke/pi-extensions/tree/main/packages/pi-subagent)，并非上游官方发行版。原始 MIT 许可证和版权声明均予以保留。

上游扩展提供子进程引擎、命名代理、后台任务、工作树和用量统计。本分支增加了强制 Jev 模型与工具选择，并在发送任务前核验子进程实际采用的模型和工具权限。

---

<a id="quick-start"></a>
### 安装与快速开始

需要 Node.js 22.19.0 或更高版本，以及已安装、已配置可用模型提供方的 Pi CLI。Pi 0.86.0 是已验证的宿主基线，能够执行内置工具、扩展工具和延迟注册工具的允许列表。若宿主无法核验所选能力，扩展会拒绝启动，不会扩大工具权限。

**1. 安装已发布的软件包。**

安装精确的 `0.10.0` 版本。较早的 `0.9.0` 使用旧的 `apiKeyEnv` 配置契约，不接受 `apiKey`：

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

Pi 会直接加载这个软件包。不要同时启用本扩展的其他副本或 `@parke.dev/pi-subagent`，它们会注册同名工具。本包提供 `subagent`、`subagent_wait`、`/subagents`、`/subagent-cost` 和 `/btw`。

**2. 将 TypeSafe 凭据保存到私有配置。**

在用户级 `~/.pi/subagent.json` 中设置 `jevRouting.apiKey`，格式如下。如果从 `0.9.0` 升级，请在启动新任务前将 `jevRouting.apiKeyEnv` 中的现有值移到 `jevRouting.apiKey`，并删除旧字段。不要把密钥放进聊天或仓库文件。配置文件以明文保存密钥，需要限制文件访问权限并保护备份。迁移与安全说明见[凭据配置](docs/REFERENCE.md#credential-setup)。子模型所需的提供方认证需要另行在 Pi 中配置。

**3. 配置候选模型。**

将下面的配置加入 `~/.pi/subagent.json`，保留其他已有设置。把示例模型 ID 替换为当前 Pi 中可用的精确 `provider/model-id`，并自行描述模型特点。如果存在旧的 `modelPolicy` 配置，需要将其移除；扩展不会自动迁移。

```json
{
  "jevRouting": {
    "selectorModel": "jev-latest",
    "apiKey": "<your-typesafe-api-key>",
    "timeoutMs": 15000,
    "models": [
      {
        "model": "<provider/model-id>",
        "description": "Describe this model's strengths and the tasks you want it to handle."
      }
    ]
  }
}
```

将 `apiKey` 占位符替换为自己的 TypeSafe 密钥，并移除旧的 `apiKeyEnv` 字段。扩展不会回退读取环境变量，也不会自动迁移。模型描述可以使用中文。可选的 thinking 默认值、profile 默认值和限制见[配置参考](docs/REFERENCE.md#configuration)。

Jev 选择可能产生 TypeSafe 费用。它会接收委派任务文本、模型 ID 与描述、候选工具名称与描述，以及必要约束；不会自动上传仓库文件或对话历史，但任务中主动包含的文本仍可能泄露敏感信息。`action: "plan"` 同样会调用 Jev，之后实际执行时还会重新选择。

**4. 启动 Pi，委派一个只读任务。**

启动 Pi；如果刚切换扩展代码，需要重新加载或重启。加载 `0.10.0` 后，每次新任务都会重新读取配置，修改 `apiKey` 不需要更新 shell 环境变量。

```bash
pi
```

让主代理使用 `subagent`，例如传入下面的请求：

```json
{
  "task": "Read README.md and summarize what this package does.",
  "description": "Summarize the README",
  "profile": "explore",
  "tools": ["read"],
  "max_turns": 4,
  "timeout_ms": 120000,
  "max_retries": 0
}
```

不要传入 `model` 或 `fallback_models`。Jev 从配置的模型列表和允许的工具中进行选择；路由失败会阻止本次新任务启动，不会改用兜底方案。已有任务的管理操作不依赖路由凭据。

---

<a id="delegation"></a>
### 任务委派

- **模型与工具路由：**本分支让 Jev 根据任务和模型描述进行匹配，逐个选择工具；本地权限检查和子进程启动核验负责落实选择结果。
- **命名代理与并行工作：**上游引擎支持可复用的代理角色和并发子进程。本分支为每个新子代理执行 Jev 路由，代理文件不能固定其模型或工具选择。
- **后台任务：**上游引擎支持状态查询、可中断等待、取消和中途指导。本分支会显示所选模型，并在展开结果中展示工具详情。
- **隔离修改：**上游工作树机制支持检查、应用或丢弃改动，避免并行代理共用同一个可写工作区。
- **结构化结果与预算：**上游引擎在父进程中校验结构化输出，并保留部分工作成果。本分支始终使用已选定的模型和工具集进行重试，单独统计选择器 token。

后台任务设置 `async: true`，之后使用 `subagent_wait` 或 `action: "wait"` 收取结果。中断等待或等待超时不会取消子代理，需要停止任务时使用 `action: "cancel"`。通过 `/subagents` 检查任务，通过 `/subagent-cost` 查看用量。

[使用参考](docs/REFERENCE.md#quick-usage)涵盖并行任务、结果汇总、恢复与分叉、结构化输出、预算，以及工作树的 diff/apply/discard 操作。[TUI 指南](docs/UX.md)介绍任务查看器和键盘操作。

---

<a id="permissions-and-costs"></a>
### 权限与费用

| Profile | 工具选择 | 修改项目文件 |
| --- | --- | --- |
| `explore` | Jev 选择的本地允许的只读工具，加上可用的 Pi 上下文控制工具 | 不允许 |
| `review` | 与 explore 相同的只读策略 | 不允许 |
| `general` | Jev 选择的本地允许的工具，加上可用的 Pi 上下文控制工具 | 选中可写工具时可以修改 |

单任务默认使用 `general`，并行任务默认使用 `explore`。显式传入的 `tools` 列表限定候选工具范围。即使传入 `tools: []`，本地仍会补充可用的 Pi 上下文管理工具。工具选择为空绝不表示允许所有工具。

Profile 是工具选择策略，不是操作系统沙箱。子进程继承主进程环境，也能读取同一用户有权访问的文件，包括私有配置。工作树只隔离代码工作区。委派不可信任务前，请阅读[安全模型](docs/SECURITY.md)。

用量账本分别记录主代理、子代理、路由和合计用量。TypeSafe 只报告路由 token，不报告金额，因此选择器费用标记为**未报告**，不代表免费。`max_cost` 限制子代理执行时由提供方报告的费用，不限制 TypeSafe 费用。结果交付、重试和会话分支的统计规则见[费用统计](docs/COST-ACCOUNTING.md)。

扩展管理的新任务只支持 Pi 后端，原生 Codex/Claude 后端请求会被拒绝。[底层 SDK](docs/REFERENCE.md#using-the-runner-as-a-library)是另一套显式任务规格 API，不会自动调用 Jev，嵌入方需要自行负责模型和工具选择。

---

<a id="development"></a>
### 开发

源码是使用 peer dependencies 的独立 TypeScript 包，没有构建步骤，也没有随仓库提供的测试运行器或类型检查脚本。本仓库支持的检查方式见[开发与验证](docs/DEVELOPMENT.md)。语法转换不等于语义类型检查；`npm pack --dry-run --ignore-scripts --json` 用于检查打包内容，不会发布包。

[架构约定](docs/ARCHITECTURE.md)记录模块职责和不变量。[发布维护](docs/RELEASING.md)说明如何选择性更新源码，以及需要单独明确授权的 npm 发布流程。

---

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

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

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

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