# @elpapi42/pi-fleet-sdk 中文文档

规范地址：https://npmcn.com/package/%40elpapi42/pi-fleet-sdk/

版本：0\.14\.0
npm 元数据更新时间：2026-09-06T04:03:54.833Z
中文译文更新时间：2026-11-13T13:48:54.992Z
软件包许可：MIT

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40elpapi42/pi-fleet-sdk
原文对照：https://npmcn.com/package/%40elpapi42/pi-fleet-sdk/?lang=original
项目主页：https://github.com/elpapi42/pi-fleet#readme
源码仓库：https://github.com/elpapi42/pi-fleet

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：278 kB，46 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- Node.js 要求：\>=22
- 运行依赖：2 个
- 首次发布：2026-08-22T05:12:37.530Z
- 最新版本发布：2026-09-06T04:03:54.466Z
- 近 30 天下载量：4977（2026-10-14 至 2026-11-12，npm 官方下载统计）
- 已发布版本数：26（近 12 个月 26 个）

## 中文简介

耐用本地 Pi 代理的 SDK

## 安装

```sh
npm install @elpapi42/pi-fleet-sdk
```

也可以使用：`pnpm add @elpapi42/pi-fleet-sdk`、`yarn add @elpapi42/pi-fleet-sdk`、`bun add @elpapi42/pi-fleet-sdk`

## README

# @elpapi42/pi-fleet-sdk (英语)

创建并发现耐用,主机-本地的Pi代理.

```bash
npm install @elpapi42/pi-fleet-sdk
```

```ts
import { connectPiFleet } from "@elpapi42/pi-fleet-sdk"

const client = await connectPiFleet()
const agent = await client.create({
  name: "researcher",
  cwd: process.cwd(),
  agentDir: "/home/user/pi-profiles/researcher",
  env: {
    RESEARCH_MODE: "schema-review",
    EMPTY_OVERRIDE: "",
  },
})

await agent.send("Investigate the database schema")
console.log(await agent.status())
await client.close()
```

`piArgs` 通过 Pi 选项。 Pi-fleet 添加( P) `--mode rpc` 和拒绝 `--mode` 财务报告和审定财务报表 `--no-session`。用户会话选择器仍然具有权威性:

```ts
await client.create({
  name: "existing-session",
  cwd: process.cwd(),
  piArgs: ["--session", "/path/to/session.jsonl"],
})
```

Pi拥有会话查询,工作-指导选择,提示,以及失败. 呼叫者拥有的Pi会话选择者保持不变并具有权威性. 对于舰队拥有的会话,pi-fleet按其准确路径恢复了现有的物理会话. 如果 Pi 报告了会话路径和ID,但没有实现文件, pi-fleet 则会用持续会话ID重启,仍需要 Pi 报告准确的ID.

`agentDir` 是可选的不可变 Pi 配置。 跟经纪人不一样 `cwd` {\\fn黑体\\fs22\\bord1\\shad0\\3ahbe\\4ah00\\fscx67\\fscy66\\2chffffff\\3ch808080}还有水手 `stateDir`。当提供时,SDK从创建进程当前目录中解析,坚持绝对路径,并作为 `PI_CODING_AGENT_DIR` 给每个Pi孩子的启动、Pi康复和工人康复。 省略后,pi-fleet保留了今天所继承的Pi环境行为. 用户拥有配置创建,内容,证书,权限,共享,以及出错. Pi决定了证书优先级. 所选择的配置文件可以提供证书,从进程环境继承的提供者证书仍然可供Pi使用. Pi-fleet不复制或删除配置文件数据,改变信任,或将其作为沙盒处理. 项目 `.pi` 资源与项目或祖先 `AGENTS.md` 保持Pi自有行为.

`env` 是 SDK 唯一不可改变的 Pi 儿童配置 。 提供 `Record<string, string>` 在私人代理记录中长期存在,并在初始启动、Pi恢复和工人恢复期间适用。 Pi-fleet合并了继承的工人环境,然后 `env`,则 `agentDir` 页:1 `PI_CODING_AGENT_DIR`。地图必须是普通的或无效的原型对象。 密钥必须是非空并包含无 `=` 或无字节. 值必须是没有空字节的字符串 。 空字符串覆盖已继承的值 。 没有未设置或更新操作 。 变化中的环境覆盖需要销毁并再造该剂. 娱乐创造出新的不可改变的代理ID,并通过正常的破坏来去除旧世代的活动历史. `PATH` 财务报告和审定财务报表 `PI_CODING_AGENT_DIR` 保留和拒绝 `env`。 。 。 .

处理 `env` 作为可信任的本地进程配置,而不是秘密商店或沙盒。 Pi和它开始的过程可以继承它的价值观. 值是LMDB中的平正文字,可以留在进程环境和备份中. Pi-fleet不直接将环境配置添加到状态,列表或事件上,但Pi和工具可以读取值并将其纳入活动输出. 在验证错误、日志或测试输出中不要打印秘密值或用户提供的实际值。 在文档示例中只使用无害占位符 。 销毁会删除逻辑代理记录, 但不会安全地去除旧的 LMDB 页面或备份 .

默认情况下, pi- fleet 将它的 LMDB 环境和工人 IPC 套接字存储在 `~/.pi-fleet`。稳定前释放不会自动从较早的地点迁移。 明确 `stateDir` 必须为生成的 Unix IP 套接字路径留下空间。 超长路径抛出 `InvalidStateDirectoryError` 在Pi-fleet创建状态之前. 过 `stateDir` 改为 `connectPiFleet` 只有当您需要明确位置时,例如孤立测试或本地高级设置时:

```ts
const client = await connectPiFleet({ stateDir: "/path/to/pi-fleet-state" })
```

`client.get(name)` 财务报告和审定财务报表 `client.list()` 发现另一个本地客户端创建的代理. `client.close()` 只关闭 SDK 客户端 。 它不会阻止代理工人.

运行的代理保持了创建时使用的工人版本. 在更新了SDK后,在测试工人康复等新的工人行为之前,先创建出一个新的代理. SDK 软件 `0.12.2` 删除 `work.interrupted` 从回放,所以由更古老的版本所创建的代理在升级后得不到支持,必须被销毁再被再创建.

`agent.send(message)` pi闲暇时开始工作。 在积极工作期间,它使用 `steer` 默认。 使用 `followUp` 在当前工作结束后交付:

```ts
await agent.send("Summarize the findings", { delivery: "followUp" })
```

`send()` 只有在 Pi 确认指令后才能解决。 在皮或出厂前工人康复期间,它等待修复和交付. 它不等待工作完成。 如果老工人可能接受了请求,但其承认却丢失了, `AgentSendUncertainError` 报告pi -fleet没有重新测试它.

`agent.receive()` 提供持久的语义活性流。 每个客户都收到独立的单一消费者流。 溪流报告 `thinking.started`, (中文(简体) ), `thinking.finished`, (中文(简体) ), `message.started`, (中文(简体) ), `message.finished`, (中文(简体) ), `tool.started`, (中文(简体) ), `tool.finished`,以及 `agent.destroyed`. . . . . 工人恢复在上次交付光标后重新连接,重放一次错过的事件,并继续进行直播. 健康的活流产量 `agent.destroyed` 然后,当所有者摧毁代理人时,通常结束。 当消费者停止或客户端关闭时,流也正常结束. 它会扔 `AgentUnavailableError` 如果有限度的恢复失败.

运行中的 Pi 运行时丢失会改变代理状态为粘滞 `interrupted`调用 `agent.status()` 来探测它. `interrupted` 工人或Pi准备就绪后和 `send()` 验收。 改为: `working` 只当Pi开始新发工作,然后 `idle` 当Pi和解. `list()` 是登记清单,可以暂时显示已失效 `working` 在未观察的工人损失之后。 Pi拥有普通工具故障和活模式或工具摊位.

每个事件都有不透明的 `cursor`,语义 `eventId`,一个 `activityId` 连接匹配的开始和结束事件, 以及一个由工人指派的 Unix- millisecond `timestamp`。流序是权威的。 时间戳不定义命令,并且 `eventId` 不是重放光标。 Pi-fleet项目Pi助理信封入语义活性:思考和只使用工具的信封不发出消息事件; `message.started` a. 在第一个非空白助理文本中发出;以及 `message.finished.text` 包含辅助文本块的最后非白空空间连接。 如果一个提供者只发送一个已完成的消息, pi-fleet 将发送一个匹配的消息开始并一起完成.

```ts
let cursor: string | undefined
for await (const event of agent.receive({ fromStart: true })) {
  cursor = event.cursor
}

for await (const event of agent.receive({ after: cursor })) {
  // Events after cursor, then live events.
}
```

平面 `receive()` 仅限直播。 它开始订阅第一个执行者读取,这样它就可能错过在工人承认之前承诺的活动. 使用 `receive({ fromStart: true })` 当工作在接收器创建后立即开始,并且不能错过第一个活动. `receive({ after: cursor })` 从光标后开始。 这些方案是相互排斥的。 光标的版本为不透明值,与一个不可变的代理ID相接. 无效、 错误的代理或未来光标 `InvalidCursorError`。 。 。 .

`await agent.destroy()` 无需确认。 它可以停止活动,立即删除代理名称,产量 `agent.destroyed` 然后去掉工人、皮、IPC套接字、代理记录和完整的事件记录。 拨打旧手柄然后抛出 `AgentNotFoundError`。重新创建此名称将创建一个新的不可移动代理ID.

`tool.started.args` 包含 Pi 的模型请求参数。 皮可以先验证或改造后再执行. 何时 `argsTruncated` 实值 `true`, (中文(简体) ), `args` 实值 `null` 因为所要求的参数超过 16 KiB.

`tool.finished.output` 包含有边框的最后文本、图像省略元数据以及可选的结构细节. `detailsTruncated` 报告省略了结构化的细节. `truncated` 报告任何省略或缩短的输出,包括图像数据。 语义事件从未包含基础64图像数据. 工人将文本输出限制在64 KiB,结构化细节限制在16 KiB. CLI 显示每个参数或输出预览最多 8 KiB . `tool.updated` 尚未提供.

在Pi恢复期间,工人最多持有32个发送和1个MiB的短信. `AgentRecoveryQueueFullError` 说明Pi没有收到被拒绝的指示. `AgentSendUncertainError` 表示Pi或老工人在确认丢失前可能已经接受了该指示,因此Pi-fleet不重试.

工具参数和输出可以包含敏感的本地数据. Pi-fleet不默地编辑此数据,因为编辑可以改变其意义. 相同的受限事件数据持续存在于 `~/.pi-fleet` 直到主人打电话 `destroy()`。还没有过期或保留设置,所以磁盘的使用可以增加。 SDK消费者必须将事件历史视为具有与代理商及其Pi会话相同的本地信任级别.

切片 8 用 ZeroMQ 支持类似 Unix 的主机 `ipc://` 支助。 它提供创建,获取,列表,状态,发送,持久接收,破坏,以及透明的皮和工人过程恢复. `status`, (中文(简体) ), `send`,以及 `receive` 通过附带条件的LMDB索赔,对无法工作的工人进行懒散调节. `get` 财务报告和审定财务报表 `list` 保持只登记操作。 回收从不显示持续存在的 PID 或 处理组; 它失败 `AgentUnavailableError` 如果旧的运行时间不 安全排出。 运行时间退休和收缩在初始产品之外.

## 常见问题

### @elpapi42/pi-fleet-sdk 是什么？

耐用本地 Pi 代理的 SDK

### 如何安装 @elpapi42/pi-fleet-sdk？

在项目目录运行 npm install @elpapi42/pi-fleet-sdk，或使用 pnpm add / yarn add / bun add。

### @elpapi42/pi-fleet-sdk 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### @elpapi42/pi-fleet-sdk 支持 ESM 还是 CommonJS？

以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node\.js 20\.19\+ / 22\.12\+ 可以直接 require\(\) 不含顶层 await 的 ES Module，更早的版本需要改用动态 import\(\)。

### @elpapi42/pi-fleet-sdk 需要什么版本的 Node\.js？

package\.json 的 engines 字段要求 Node\.js \>=22。版本不符时 npm 默认只给出警告，开启 engine-strict 后会拒绝安装。

### @elpapi42/pi-fleet-sdk 可以商用吗？

@elpapi42/pi-fleet-sdk 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### @elpapi42/pi-fleet-sdk 的下载量有多少？

根据 npm 官方下载统计，@elpapi42/pi-fleet-sdk 在 2026/10/14 – 2026/11/12 这 30 天内被下载 4,977 次，日均约 166 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @elpapi42/pi-fleet-sdk 还在维护吗？

最新版本 0\.14\.0 发布于 2026/09/06（2 个月前）；至今共发布 26 个版本，其中过去 12 个月发布了 26 个；首次发布于 2026/08/22。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。