# @earendil-works/pi-client 中文文档

规范地址：https://npmcn.com/package/%40earendil-works/pi-client/

版本：1\.1\.0
npm 元数据更新时间：2026-10-07T22:13:10.433Z
中文译文更新时间：2026-11-13T03:35:40.511Z
软件包许可：MIT

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

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

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

- 包体积（解压后）：125 kB，35 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- Node.js 要求：\>=22\.19\.0
- 运行依赖：2 个
- 首次发布：2026-08-06T10:51:18.108Z
- 最新版本发布：2026-10-07T22:13:10.109Z
- 近 30 天下载量：2506543（2026-10-13 至 2026-11-11，npm 官方下载统计）
- 已发布版本数：20（近 12 个月 20 个）

## 中文简介

边框 CBOR 字节的远程 pi 会话的运输中性客户端

## 安装

```sh
npm install @earendil-works/pi-client
```

也可以使用：`pnpm add @earendil-works/pi-client`、`yarn add @earendil-works/pi-client`、`bun add @earendil-works/pi-client`

## README

# @ earendil- works/ pi- 客户端

实验Pi服务协议的运输中性客户端.

```ts
import { Client, type ByteTransportFactory } from "@earendil-works/pi-client";

const transportFactory: ByteTransportFactory = async (handlers) => {
  // Connect using WebSocket, Unix socket, or another ordered byte transport.
  return {
    async send(chunk) {
      // Deliver bytes in invocation order and honor backpressure.
    },
    close() {},
  };
};

const client = await Client.connect({
  serverId: "01234567-89ab-4def-8123-456789abcdef",
  transportFactory,
});
const result = await client.request(
  { serverId: client.hello.serverId },
  { serviceId: "example.service", member: "read", args: [] },
);
```

客户端验证物理端点报告预期逻辑 `serverId`。全服务器请求携带该ID,每个会话请求都携带全程直播目标 `{ serverId, sessionId, attachmentId }`。合并持久地址可以防止交叉服务器或交叉会话错误的路由;服务器生成的附件ID在切换或重新连接后拒绝延迟帧.

已打入的服务器和会话API由应用程序拥有的Chord服务绑定提供. `createClientServiceTransport()` 将懒解的服务器或会话路由调整为和弦传输; `request()` 财务报告和审定财务报表 `subscribeService()` 仍然是低等原始人 客户端使用Chord的服务控制解析器和每个订阅状态解码器; `pi-protocol` 只验证路由信封和严格的JSON边界。 服务订阅返回一个完整的提供者快照; 装订安装然后调用 `start()` 以释放水合过程中缓冲的更新. `Client` 应用命令外附件更改,但故意不构建打字服务代理或解释应用合同.

应用观察 API 如编码代理 `Transcript` 是普通的和弦服务。 客户端不解释其快照或更新.

在断开或处理时,待处理的请求会在当地拒绝,但在附件发布之前,被接受的工作仍可能远程完成. 客户端清除其活性附件路径. 它永远不会自动重接或重放请求. 断开后,请拨 `reconnect()`,通过应用程序的管理服务再次附加,并明确重复已知的安全操作.

实验性局部协调员只提供稳定的终点并接通流量. 可替换服务器进程在公共客户端协议之外拥有会话和工人生命周期.

调用运输处理器如下:

-   `handlers.onData(chunk)` 用于输入字节;
-   `handlers.onClose()` 有序关闭终端;
-   `handlers.onError(error)` 运输故障.

运输厂为每次尝试创造了新的认证连接. 请求与ID相关,服务器失败被曝光为 `ServerError`。 。 。 .

## Unix 域插座

节点.js和Bun消费者可以使用单独的Unix运输:

```ts
import { Client } from "@earendil-works/pi-client";
import { createUnixTransportFactory } from "@earendil-works/pi-client/unix";

const client = new Client({
  serverId: "01234567-89ab-4def-8123-456789abcdef",
  transportFactory: createUnixTransportFactory({ path: "/tmp/pi.sock" }),
});
await client.connect();
```

Unix 发现扫描一个明确的物理路由目录,从文件名中获取每个预期的服务器ID,并通过现有的握手方式验证:

```ts
import { discoverUnixServers } from "@earendil-works/pi-client/unix";

const routes = await discoverUnixServers({ directory: "/run/user/1000/pi" });
// [{ serverId: "...", path: "/run/user/1000/pi/<serverId>.sock" }]
```

错误的条目,非sockets, stale或无响应端点,以及服务器-ID不匹配被忽略. 发现是只读的,最多16个套接字同时进行探测。 无法预料的文件系统和套接字错误拒绝发现 。 过 `timeoutMs` 覆盖默认探测器超时.

`ClientOptions.maxFrameLength` 限定协议有效载荷. `maxPendingBytes` 将 Unix 传输输出排队。 配置对等端的匹配限制 .

## 常见问题

### @earendil-works/pi-client 是什么？

边框 CBOR 字节的远程 pi 会话的运输中性客户端

### 如何安装 @earendil-works/pi-client？

在项目目录运行 npm install @earendil-works/pi-client，或使用 pnpm add / yarn add / bun add。

### @earendil-works/pi-client 支持 TypeScript 吗？

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

### @earendil-works/pi-client 支持 ESM 还是 CommonJS？

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

### @earendil-works/pi-client 需要什么版本的 Node\.js？

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

### @earendil-works/pi-client 可以商用吗？

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

### @earendil-works/pi-client 的下载量有多少？

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

### @earendil-works/pi-client 还在维护吗？

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