# @av-pi-studio/protocol 中文文档

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

版本：0\.0\.115
npm 元数据更新时间：2026-11-04T07:05:28.515Z
中文译文更新时间：2026-11-07T07:30:31.803Z
软件包许可：未声明

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

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

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

- 包体积（解压后）：2.6 MB，24 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- 运行依赖：1 个
- 首次发布：2026-07-18T12:50:55.554Z
- 最新版本发布：2026-11-04T07:05:28.172Z
- 近 30 天下载量：2244（2026-10-07 至 2026-11-05，npm 官方下载统计）
- 已发布版本数：114（近 12 个月 114 个）

## 中文简介

共享有线计,二进制帧编解码器,以及皮-斯图迪奥的能力旗. 这个包是 **所有穿越 WebSocket 的真相单一来源** 在守护进程和任何客户端(CLI,网络,移动,桌面)之间.

## 安装

```sh
npm install @av-pi-studio/protocol
```

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

## README

# `@av-pi-studio/protocol`

共享有线计,二进制帧编解码器,以及皮-斯图迪奥的能力旗. 这个包是 **所有穿越 WebSocket 的真相单一来源** 在守护进程和任意之间 客户端(CLI,网络,移动,桌面).

这是一个 **零运行时间工作空间依赖性** 库——唯一的外部依赖是 `zod` —— 说 因此它可以被浏览器和React Industrial客户端像Node.js守护进程一样自由导入.

* * *

## 安装

```bash
npm install @av-pi-studio/protocol
```

## 这里面是什么

-   **JSON 电线计划** (单位:千美元)`messages.ts`)——可以出现在WebSocket上的每一个消息类型, 作为 [佐德语Name](https://zod.dev/) 方案及其推断类型: `hello`编号 :`status` 握手、RPC请求/答复、广播`agent_update`, (中文(简体) ), `agent_stream`页:1 顶级信封联盟,可以包到底.
-   **二进制框架编码器** (单位:千美元)`binary-frames/`) ——两条二元线的编码/解码功能 格式:终端 I/O(`[opcode][slot][payload]`)和块文件传输。 双用 `Uint8Array`永远 `Buffer`在浏览器中运行.
-   **客户能力标记** (单位:千美元)`client-capabilities.ts`(b) —— `CLIENT_CAPS` (一个客户可以 在广告中 `hello.capabilities`和 `SERVER_FEATURES` (守护进程广告内容) `server_info.features`页:1 `supports()` 帮手.
-   **端点解析** (单位:千美元)`endpoint.ts`)——转动守护进程目标字符串(`host:port`, (中文(简体) ), `ws://…`, (中文(简体) ), `relay://…`)成为结构化的 `EndpointDescriptor`。 。 。 .
-   **提供者清单类型** (单位:千美元)`provider-manifest.ts`)——UI-faceing脚手架来描述 提供者/模型(标签、颜色等级、能力旗帜).

## 使用量

```ts
import {
  helloSchema,
  agentStreamEventSchema,
  encodeTerminalFrame,
  decodeTerminalFrame,
  parseEndpoint,
  rpcName,
} from "@av-pi-studio/protocol";

// Validate + parse an inbound message
const hello = helloSchema.parse(rawJson);

// Build a canonical dotted RPC name
const name = rpcName("agent", "permission", "respond", "request");
// → "agent.permission.respond.request"

// Parse a daemon connection target
const endpoint = parseEndpoint("workstation.local:6767");
// → { kind: "direct", host: "workstation.local", port: 6767, ssl: false, raw: "…" }
```

每个导出的计划都有一对类型Script(`XSchema` 编号 : `X`),用 `z.infer<>` —— 说 导入任意一个选项.

## 设计规则

这些是通过公约和包件本身的测试,而不是通过工具执行的:

-   **仅附录.** 球场只被添加过,并且只是作为可选的. 没有任何东西被移除, 缩小或赋予新的歧视性价值。 这就是让一个更老的守护进程加载数据的原因 由较新者(反之亦然)所写,没有迁移步骤.
-   **司马传通.** 大多数计划都使用Zod的 `.passthrough()`,所以未知的字段从更新 协议版本通过更古老的解码器在往返中存活下来,而不是被剥去或 拒绝.
-   **零工作空间进口.** 此软件包从不从另一软件包导入 `@av-pi-studio/*` 软件包 - 未来任何客户都要保持独立 包括其他客户 取决于其余的单体.
-   **跨平台二进制解码器.** 二进制框架编码/解码函数只使用 `Uint8Array` ——不只节点 API ——所以它们在节点,浏览器,和React中工作相同 原产地.
-   **点出RPC名字.** 新的RPC通过 `rpcName(domain, sub, op, dir)` → `"domain.provider.operation.direction"` (例如:. `agent.permission.respond.request`) (中文(简体) ). 遗产平地 名称仍然通过别名在线上被接受,但从未由新代码生成.

## 添加新电线消息类型

1.  定义 Zod 计划(及其推断类型) `messages.ts` 或一个新的兄弟文件.
2.  把它加进 `sessionMessageSchema` 歧视工会.
3.  导出它从 `index.ts`。 。 。 .
4.  添加回程测试( E)`messages.envelopes.test.ts` 或一个新的 `*.test.ts`) (中文(简体) ).
5.  在守护进程中注册相应的处理器 `HandlerRegistry` (单位:千美元)`@av-pi-studio/server`) (中文(简体) ).

## 发展

```bash
npm run build       # tsc -b
npx vitest run packages/protocol
```

测试为 Vitest , 并与其源文件共存 `*.test.ts`。 。 。 .

## 常见问题

### @av-pi-studio/protocol 是什么？

共享有线计,二进制帧编解码器,以及皮-斯图迪奥的能力旗\. 这个包是 所有穿越 WebSocket 的真相单一来源 在守护进程和任何客户端\(CLI,网络,移动,桌面\)之间\.

### 如何安装 @av-pi-studio/protocol？

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

### @av-pi-studio/protocol 支持 TypeScript 吗？

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

### @av-pi-studio/protocol 支持 ESM 还是 CommonJS？

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

### @av-pi-studio/protocol 可以商用吗？

@av-pi-studio/protocol 使用 未声明 许可。package\.json 没有声明许可证。没有许可证的代码默认保留全部权利，商用前请联系作者或查看仓库中的 LICENSE 文件。以上为概括，不构成法律意见，请以许可原文为准。

### @av-pi-studio/protocol 的下载量有多少？

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

### @av-pi-studio/protocol 还在维护吗？

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