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

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

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

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

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

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

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

## 中文简介

远程 pi 会话的运输中性 CBOR 协议

## 安装

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

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

## README

# @ earendil- works/ pi- protocol

运行时中和路由信封,CBOR编码,以及实验Pi协议的字节流框架.

协议版本 `8` 定义 :

-   用于识别逻辑的版本握手 `serverId`· ;
-   明确的服务器和会话请求目标;
-   与不透明的严格JSON有效载荷有关的请求和反应;
-   要求取消、不透明的订阅更新和带外附件更改;
-   非空的不透明错误代码和有边框的运输信息.

服务器目标包含 `{ serverId }`; 会话目标包含 `{ serverId, sessionId, attachmentId }`。合并的路由栅栏呼叫一个逻辑服务器、持久会话和现场演示文稿附件。 管理层 `attach()` 财务报告和审定财务报表 `detach()` 返回无路由标识符; 服务器以带外方式发布选定的活路 `attachment` 留言。 断开连接只发布演示文稿的附加内容在被允许通话后结算.

弦拥有这些信封内载的有效载荷语义: `{ serviceId, instance?, member, args }` 电话 `$chord.service` 控制词汇,服务目录,订阅快照和更新,服务出错代码,以及复制状态的独立Delta路径编码. `pi-protocol` 验证每个不透明有效载荷都是严格的JSON,但不验证或导出其弦法. 客户端和服务器通过 `@earendil-works/chord` 在服务适配器边界.

会话-指令状态,管理结果,笔录,模型,插件,以及所有其他应用值仍然不透明服务数据. 持久会议及其召开方式仍然是会议工人进程的地方。 服务器和会话不透明地将路由调用到他们自己的提供者,在那里Cord和应用程序验证并引用它们.

服务器和工人的生命周期被故意置于这一公开协议之外。 实验性本地协调器只是不透明的消息路由器;每个可替换的服务器进程都拥有私有的生命周期协议.

每个线框由四字节无标记的大尾有效载荷长度所组成,再取一个确定长的CBOR项目. `encodeClientMessage()` 财务报告和审定财务报表 `encodeServerMessage()` 验证和编码完整的框架. `ClientMessageDecoder` 财务报告和审定财务报表 `ServerMessageDecoder` 接受任意的溪流分解和汇合.

```ts
import {
  PROTOCOL_VERSION,
  encodeClientMessage,
  ServerMessageDecoder,
  type ClientHello,
} from "@earendil-works/pi-protocol";

const hello: ClientHello = { type: "hello", version: PROTOCOL_VERSION };
transport.send(encodeClientMessage(hello));

const decoder = new ServerMessageDecoder({ maxFrameLength: 1024 * 1024 });
for (const message of decoder.push(incomingChunk)) handleServerMessage(message);
decoder.end();
```

所有信封计划都拒绝未知物体属性,编码器递归拒绝非JSON不透明有效载荷,包括非无限数,字节数组, `undefined`原型和循环 信封违反、 CBOR 格式错误和设定无效 `ProtocolValidationError`. 有效载荷特定适配器必须在解码后进行自己的语义验证. 运输必须保持字节顺序。 实验运输没有实施同行认证和认证服务环境.

默认限值为每CBOR有效载荷/帧16个米B,1,000,000个阵列元素或映射条目,以及64个嵌入物等. 协议是实验性的,没有兼容性保证.

## 常见问题

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

远程 pi 会话的运输中性 CBOR 协议

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

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

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

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

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

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

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

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

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

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

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

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

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

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