# @dieulc/pi-office-protocol 中文文档

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

版本：0\.5\.1
npm 元数据更新时间：2026-10-31T07:18:30.297Z
中文译文更新时间：2026-11-13T05:44:43.058Z
软件包许可：MIT

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

原始 npm 页面：https://www.npmjs.com/package/%40dieulc/pi-office-protocol
原文对照：https://npmcn.com/package/%40dieulc/pi-office-protocol/?lang=original

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

- 包体积（解压后）：88.4 kB，4 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- 运行依赖：1 个
- 首次发布：2026-09-08T17:14:22.200Z
- 最新版本发布：2026-10-31T07:18:30.129Z
- 近 30 天下载量：2186（2026-10-12 至 2026-11-10，npm 官方下载统计）
- 已发布版本数：6（近 12 个月 6 个）

## 中文简介

Pi-office-bridge Pi扩展站和Pi-for-office任务板加插间共享桥接线协议+办公Op目录.

## 安装

```sh
npm install @dieulc/pi-office-protocol
```

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

## README

# @dieulc/pi-office-protocol (英语)

共享 Pi- for- office 任务表添加的 WebSocket 线条协议 (单位:千美元)`packages/add-in/src/bridge/`)和皮桥分机 (单位:千美元)`packages/bridge-extension/`) (中文(简体) ).

将协议放在一个包里 将桥的两半放在 锁定步骤——突破的改变是一次承诺,端到端的对接测试 (单位:千美元)`packages/bridge-extension/tests/pane-interop.mjs`证明双方说话 运行时格式相同.

## 信件

-   **客户端 – 服务器 :** `hello`, (中文(简体) ), `ping`, (中文(简体) ), `tool_result`, (中文(简体) ), `user_message`, (中文(简体) ), `status`, (中文(简体) ), `pane_state`, (中文(简体) ), `abort`
-   **服务器 – 客户端 :** `welcome`, (中文(简体) ), `pong`, (中文(简体) ), `tool_call`, (中文(简体) ), `agent_message` (德尔塔/最后), `tool_activity`, (中文(简体) ), `error`

## 议定书v2(打破)

v2 添加 **证件身份和瞄准目标** 桥可以打开几个 同一主机应用程序的文档 :

-   `hello.document: DocumentIdentity` —— 说 **所需经费**。 。 。 . `{ id, name, source }` 地点 `id` 是一个稳定的本地散列( o)`url_sha256:…` 编号 : `wps_path_sha256:…`)或(或) `null` 未保存的文档,以及 `source` 这是其中之一 `"document.url"`, (中文(简体) ), `"wps.activeWorkbook.fullName"`, (中文(简体) ), `"unknown"`。原始 URL/路径从未发送.
-   `pane_state` (客户 ) —— 最佳 `{ focused?, visible?, activeAt? }` 这样 `document: "active"` 可解析用户正在查看的文档.
-   `tool_call.documentId?: string` - 电话被传送到(echoed) 用于伐木和平面验证.
-   `agent_message` 最后收益 `promptId?: string` - 将答复与 窗格触发它.
-   `OFFICE_TARGET_PARAM = "document"` ——选择 a 的工具参数键 目标;服务器在将调用转发到窗格之前将其剥离.

V1客户端在握手时被拒绝 `protocol_mismatch`; 更新两者 一半合起来(protocol0.4.0,桥0.4.0).

## 议定书v3(补充)

v3使一扇窗帘迅速感觉活泼而可中断. 没错 **添加剂**: 一个 v2 框仍然被接受,只收到最后答复.

-   `agent_message` **三角洲** 现在实际生产了帧 : 解答窗格提示服务器流 `{ type: "agent_message", kind: "delta", text, promptId?, messageId? }`, (中文(简体) ), 组合以保留在 `MAX_TEXT_CHARS`三角洲是 **只显示**页:1 连接不能保证与最终文本相等,所以面板替换 它的活缓冲器 `kind: "final"` 当它到达.
-   `abort` (客户-服务器) - `{ type: "abort", promptId? }` 停止运行 回答这个提示( 或任何运行在飞行中, 当 `promptId` 页:1 v2 服务器忽略了框架, 所以必须停止按钮 如果答复不断到来,仍可使用.
-   `MIN_SUPPORTED_PROTOCOL_VERSION = 2` 财务报告和审定财务报表 `isProtocolVersionSupported()` - 那个 服务器接受整个 `[MIN_SUPPORTED_PROTOCOL_VERSION, BRIDGE_PROTOCOL_VERSION]` 窗口,而不是要求精确匹配.
-   三角洲只发给那些 `hello.protocolVersion >= 3`; 服务器 从不向v2平面发送三角地(它会放弃它).

将两个部分一起更新到破碎的改变上;添加剂的改变可能运走 (protocol 0.5.1,桥口0.6.0).

## 版本容量( C)

`BRIDGE_PROTOCOL_VERSION` 仅被撞上 **断开** 信件形状更改. 添加字段使两者相容:

-   `welcome.serverVersion?: string` ——桥口扩展包版本.
-   `welcome.capabilities?: BridgeCapability[]` 目前 `"http-health"` (服务器答案) `GET /health` 与JSON元数据), `"agent-deltas"` (服务器流) `agent_message` 三角洲(三角洲), `"client-abort"` (服务器) 阁下: `abort` 框架),以及 `"manual-lifecycle"` (桥停了) 直至 `/office connect`;客户端不得假定 0.6 命令存在于 没有这种能力的桥梁)。 优先检查一个版本的能力 比较,所以在运行时间可以发现对等者的特性.

两者都是 **选项**。缺席 `capabilities` 数组( 或缺失) `serverVersion`)表示对等点是一个遗留的0.1.0桥:客户必须降解 优雅( 直播的 WebSocket 状态仍为权威) 而不是 假设服务器无法访问 .

见 `src/protocol.ts` 为打入的形状.

## 常见问题

### @dieulc/pi-office-protocol 是什么？

Pi-office-bridge Pi扩展站和Pi-for-office任务板加插间共享桥接线协议\+办公Op目录\.

### 如何安装 @dieulc/pi-office-protocol？

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

### @dieulc/pi-office-protocol 支持 TypeScript 吗？

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

### @dieulc/pi-office-protocol 支持 ESM 还是 CommonJS？

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

### @dieulc/pi-office-protocol 可以商用吗？

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

### @dieulc/pi-office-protocol 的下载量有多少？

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

### @dieulc/pi-office-protocol 还在维护吗？

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