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

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

版本：0\.6\.0
npm 元数据更新时间：2026-10-31T07:20:06.983Z
中文译文更新时间：2026-11-13T04:38:24.184Z
软件包许可：MIT

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

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

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

- 包体积（解压后）：112 kB，12 个文件
- 模块格式：ES Module
- TypeScript 类型：未声明
- Node.js 要求：\>=20
- 运行依赖：2 个
- peer 依赖：typebox \*，@earendil-works/pi-ai \>=0\.83\.0，@earendil-works/pi-coding-agent \>=0\.85\.0
- 首次发布：2026-09-08T17:14:35.929Z
- 最新版本发布：2026-10-31T07:20:06.846Z
- 近 30 天下载量：2311（2026-10-12 至 2026-11-10，npm 官方下载统计）
- 已发布版本数：7（近 12 个月 7 个）

## 中文简介

原生 Pi 扩展名 — WebSocket Bridge + Office 工具代理,使 Pi 能通过 pi- for-office 添加来驱动 Excel, Word, and PowerPoint .

## 安装

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

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

## README

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

允许本地 Pi 进程驱动的本地 Pi 扩展 **埃克塞尔**, (中文(简体) ), **单词**,以及 **电源点** 通过 [pi- for- office (单位)](https://npmcn.com/package/%40dieulc/add-in/README.md) 任务表 添加进.

纯粹的扩展——它只使用皮的公用扩展API,所以 **Pi核心从不 触动** pi可以自由更新.

## 如何运作

```
Excel / Word / PowerPoint  (pi-for-office task pane)
        │  WebSocket  ws://127.0.0.1:38617
        ▼
local Pi process  (this extension)
   • registers office_<host>_<op> tools
   • proxies Office.js calls back to the pane
   • injects pane prompts into the Pi session
```

**服务器关闭直到您要求它( Bridge 0. 6+) .** 届会开幕 更长时间地要求桥口。 运行 `/office connect` 在您想要的会话中 使用,或单击 **连接此会话** 在 Pi 桌面文档栏中。 每个新的 会话开始; `/office close` 释放端口用于另一个会话.

两种流动:

1.  **工具代理( Pi ) :** pi代理电话 `office_excel_read_range`, (中文(简体) ), `office_word_insert_text`,...; 扩展转发 a `tool_call` 页:1 ; 窗格运行 Office.js 的操作和回答 `tool_result`。然后 LLM 查看文档内容 **财务报告和审定财务报表** 皮满了 系统工具(bash, git, 文件).
    
2.  **Pane 驱动聊天( pane ~ Pi) :** 在添加边栏中的用户类型 窗格向前移动 a `user_message`; 扩展将其注入 Pi 会话 和流 助理的最后回覆 回到窗帘.
    

## 多个打开的文档( protocol v2)

该桥服务 **每个附件主机应用程序的每个打开文档**不仅仅是 最近连接的 单位 `hello` 每个窗格报告a 隐私保存文件身份(`document.id` =当地大麻, `document.name` = 显示名称, `document.source`),每个服务器路径 工具调用一个特定的文档:

-   每个 `office_*` 工具要选择 **`document`** 参数: 文档编号 (从) `office_list_documents`),一个唯一的文档名称,或 `"active"`。 。 。 .
-   省略/ 省略 `"active"` 目标解析到 **重点** 文档,然后改为 该主机的唯一所附文件。 如果多个文件打开 没有一个是焦点,呼叫 **未使用候选人名单** 改为 编辑一个猜测.
-   场景报告重点/可见度 `pane_state` 框架; 在窗格中输入 计为焦点,以及 Excel 的额外用途 `Workbook.onActivated`。 。 。 .
-   `office_list_documents` 列出所附文件(编号、名称、主机、焦点、, 窗口);系统提示在每次转弯前都带有相同的列表.
-   两个窗口 **同一文件** 共享一个文档 id: 到 焦点窗口,如果两者都不集中,则错误.
-   在 Pi TUI 中,类型 **`#`** 生成一个从一个 降(先专注. 输入插入 `#<name>` -或者说 `#<document id>` 何时 两个打开的文档共享一个名称。 服务器剥去主线 `#` 何时 解析目标,所以该引用可以直接使用.
-   代理回复与引起回复的窗格提示匹配,并发送 **只到那个窗帘** (从未播出),注射的即时携带一个 `[office:<host> "<name>" id=…]` 标签,所以共享对话保持可追踪.

**协议v2正在打破:** 将加载和桥一起更新 (protocol 0.4.0 + 桥0.4.0). 在握手时拒绝使用 v1 面板 `protocol_mismatch`。 。 。 .

## 安装

```bash
pi install npm:@dieulc/pi-office-bridge
```

**最新资料** (完整的29个工具目录包含. 结构/格式工具 0.3.0;多文件目标, `office_list_documents` 财务报告和审定财务报表 `#` 提及 自动完成需要 ^ 0.4.0 (protocol v2, 需要匹配添加) 建筑) `/health` 探测器和版本显示需要 0.2.0 :

```bash
pi install npm:@dieulc/pi-office-bridge@latest
```

然后重新启动 Pi。注意 `pi install` 针入它获取的版本 `~/.pi/agent/npm/package.json`,所以皮会 **没有** 自动升级——重新运行 上面的指挥来获得最新的桥梁.

或从单体(开发)作为 **dev 桥** 在端口时 `38618` (单位:千美元)`--no-extensions` 忽略设置, 因此全球安装的 prod 桥 从未在同一过程中重复装入 :

```bash
npm run bridge:dev   # repo root → pi --no-extensions -e ./packages/bridge-extension/src/index.ts --office-bridge-port 38618
```

> **问题解决:经纪人说没有 `office_excel_modify_structure`** (或任何其他较新的工具). 一个桥 **< 0.3.0 (英语)** 小型硬码船 目录( 12个工具) 而忽略了窗格 `hello.ops`,所以新的行动沉默 从不注册。 修补 : `pi install npm:@dieulc/pi-office-bridge@latest`开始 皮,然后确认一下 `/office-tools` (29个工具)和 `/office` (小组行动+) 目录版本).

## 在添加中启用

1.  安装/ 运行桥接, 因此此扩展的 Pi 进程正在监听 (见上文)。 保持Pi进程在背景中运行.
2.  在 Excel / Word / PowerPoint 中打开 pi- for-office .
3.  转到 **设置 ~ 连接 ~ 本地 Pi 代理 (高级)** 翻转 **启用本地 Pi 代理** 继续 卡片显示实时连接 状态( 连接... ) ; 不需要重装任务表 .
4.  用卡片验证 **测试连接** 按钮,或从终端:

```bash
curl http://127.0.0.1:38617/health
# → { "ok": true, "service": "pi-office-bridge", "serverVersion": "0.2.0",
#     "capabilities": ["http-health"], "panes": [ … ] }
```

`/health` 列出所附的窗体及其主机应用(excel / word /) powerpoint),因此作为快速主机检测检查的双倍. 补入的 探测器对响应进行分类( 当前/ 旧桥/ 超时/ 浏览器) 而不是报告一个明显的失败——见 [`docs/local-development.md`](https://npmcn.com/package/docs/local-development.md)。 。 。 .

## 版本容量( C)

每个 `welcome` 框架(和 `GET /health`广告添加剂服务器 元数据 :

-   `serverVersion` ——这个包的版本(例如. `"0.6.0"`) (中文(简体) ).
-   `capabilities` —— 说 `http-health`, (中文(简体) ), `agent-deltas`, (中文(简体) ), `client-abort` 财务报告和审定财务报表 `manual-lifecycle`。 。 。 . `manual-lifecycle` 意思是大桥停通到 `/office connect`;需要启动或停止的客户端必须检查此 能力(或版本),绝不假定0.6命令存在.
-   `GET /health` 还携带 `owner` —— 说 `{ pid, sessionId, client, cwd }` 这样啊 Pi桌面可以将活桥映射到标签或报告终端所有者. 没错 断断续续的桥.

客户端( 加卡) 处理缺勤 `capabilities` 作为“遗产桥梁” ( < 0.2.0))”,并告诉用户更新而不是声称桥是 下来。 连接状态一有窗帘就浮出水面 附加或分解( n)`onPanesChanged`) (中文(简体) ).

## 图标

| 命令 | 说明 |
| --- | --- |
| `/office` | 状况(与 `/office status`(中文(简体) ) |
| `/office status` | 显示状态、 端口、 所有者和附带的应用程序 |
| `/office connect [port]` | 启动桥; 端口默认为配置的端口 |
| `/office close` | 停止桥接并断开添加 |
| `/office restart [port]` | 停止, 然后启动( 选择在另一个端口) |
| `/office help` | 显示命令列表 |
| `/office-tools` | 列表 `office_*` 工具及其是否活动 |

别名 : `on`编号 :`start` =: `connect`· ; `stop`编号 :`off`编号 :`disconnect` =: `close`· ; `info` =: `status`。 。 。 .

## 生命周期(桥口0.6+)

```text
/office connect → listening → /office close → off
```

-   只有一个Pi会话可以拥有端口. 一秒钟 `/office connect` 失败 命令您关闭所有者( 或连接在 不同端口).
-   状态行在运行时显示绑定的端口和所附的应用程序; 是 桥关了就清空了.
-   办公室工具注册于 `session_start` 不过 **关闭时不活动**编辑 发现工具 `office_list_documents` 桥一通就动了 ;目录工具只为所附的窗格广告操作激活.
-   `session_shutdown` 总是停止桥梁. `/new`, (中文(简体) ), `/resume`, (中文(简体) ), `/reload` (单位:千美元) 桌面主机因此重新开始; 明确重新连接 。 保持一个 整个Pi扩展的服务器 重新证实会把它孤儿化.
-   桥从不自动连接 只因为会话开通 选入 `--office-bridge-autostart` 编号 : `PI_OFFICE_BRIDGE_AUTOSTART=1` 恢复旧的 用于脚本和权力用户的行为.

## 配置

-   **端口** 旗帜 `--office-bridge-port <port>` 或嵌入 `PI_OFFICE_BRIDGE_PORT` (默认) `38617`) (中文(简体) ). `/office connect <port>` 一跑两跑都超了 这个 加入连接到同一默认值;如果您超过此默认值,则同时更改( 添加的桥卡有一个 **桥口 URL** 划出两个 WebSocket 客户端 和探测器的使用。 如果端口已被另一个 Pi 进程所取,则 延期报告 `EADDRINUSE` 带有所有者/关闭提示.
-   **自动启动** - 默认关闭. `--office-bridge-autostart` 或者说 `PI_OFFICE_BRIDGE_AUTOSTART=1` 启动桥在 `session_start` (旧的) 行为)。 没有持续的图形界面设置.
-   **允许来源** - 门 `PI_OFFICE_BRIDGE_ALLOWED_ORIGINS` (合并分离) 扩展允许读取的浏览器来源 `GET /health`默认覆盖 dev Vite 服务器 (`https://localhost:3141`)和主机 GitHub Pages 添加 (单位:千美元)`https://dieuluucanh.github.io`) (中文(简体) ). 窗格的 WebSocket 连接是 仅循环且不受此列表限制 .

## 办公工具

扩展登记 a `office_<host>_<op>` 共享中的每个操作工具 目录. 该目录是真理的唯一来源:它生活在 `@dieulc/pi-office-protocol` (单位:千美元)`office-catalog.ts`和两个Pi扩展 加上的就是它——这里的"皮"一面,和"平板桥"的操作 登记(`packages/add-in/src/bridge/`这里。 Op ID 由主机命名 :

| 东道主 | 行动 |
| --- | --- |
| 埃克塞尔 | `get_overview`, (中文(简体) ), `read_range`, (中文(简体) ), `write_cells`, (中文(简体) ), `fill_formula`, (中文(简体) ), `search_workbook`, (中文(简体) ), `modify_structure`, (中文(简体) ), `format_cells`, (中文(简体) ), `conditional_format`, (中文(简体) ), `charts`, (中文(简体) ), `trace_dependencies`, (中文(简体) ), `explain_formula`, (中文(简体) ), `view_settings`, (中文(简体) ), `comments`, (中文(简体) ), `workbook_history` |
| 单词 | `get_overview`, (中文(简体) ), `read_document`, (中文(简体) ), `insert_text`, (中文(简体) ), `replace_text`, (中文(简体) ), `format_range`, (中文(简体) ), `insert_blocks`, (中文(简体) ), `insert_table`, (中文(简体) ), `insert_page_break`, (中文(简体) ), `insert_image`, (中文(简体) ), `insert_hyperlink` |
| 电源点 | `get_overview`, (中文(简体) ), `read_slide`, (中文(简体) ), `add_slide`, (中文(简体) ), `add_text_box`, (中文(简体) ), `format_slide` |

加上主机不可知的发现工具 **`office_list_documents`** (编号、名称、, 主机,焦点,窗口). 它只在桥上活动.

### 主动工具调节

办公室工具登记在 `session_start` 从目录,但 活动集跟随生命周期和相接的窗格 (单位:千美元)`pi.setActiveTools()`:

| 状态 | 目录工具 | `office_list_documents` |
| --- | --- | --- |
| 断桥 | 不活动 | 不活动 |
| 桥上,没有窗帘 | 不活动 | 活动 |
| 桥接上, 窗帘接上 | 风扇的广告行动 | 活动 |

打开一个应用程序激活主机的工具;关闭它会解除它们; 关闭大桥 解除整个家庭。 其他的都留下来了 无所未有. 没有广告的纸条 `ops` 列表(遗留的0.2.x客户端)是 仅提供了 v1 操作集.

### 握手能力

纸条发送 `hello.ops` + 键 `hello.catalogVersion` 用他们可以的操作码 执行。 服务器根据自己的目录验证它们(不包含) 属于窗格的主机,或服务器不知道的,被丢弃 页:1. `callOfficeTool` 然后拒绝任何没有广告的操作 一个可操作的信息, 因此一个不匹配的加/ 桥配对会响亮失败 默默无声 行动清单——连同 `opsIgnoredCount` -是真实的 执行: `catalogVersion` 只有信息(在 `/health` 财务报告和审定财务报表 页:1 `/office` 因此它不会悄悄地改变一个面板 执行.

-   `/office` 显示每个附件窗格的主机、操作计数、目录版本和任意 忽略- op 计数 .
-   `/office-tools` 列出每个已注册工具+目录版本.
-   `GET /health` 曝光情况 `catalogVersion` 和每页 `ops` 编号 : `catalogVersion`。 。 。 .
-   `before_agent_start` 附加一个平板文字块(随附主机,“the office QQ工具编辑活文档,“从不发出 HTML for Word ”) 代理直接使用工具。 故意这样做的 **没有** 索赔的格式是: 普遍支持: 每个工具的图案都列出了它的确切属性 接受,并且块指示代理商说没有财产 而不是坚持支持——咨询 `office_word_get_capabilities` 当 a 请求取决于它不确定的Word 特性.

工具永远不会无声地降解:当请求的特性需要 Office.js 时 要求设置主机缺少,调用返回信件命名能力, 设定 + 版本, 平台, 和补救 。 两名CI警卫守住地表 诚实的——每个广告格式化的财产必须在 实施《公约》的每一个已宣布的能力都必须是: 被呼叫者消耗 或被明确只探测。 面板和这个扩展 都读了 _不变_ 目录参数对象(无每边计划副本),所以 新参数不能在两个代理之间漂移.

玻璃边执行员是 本地工具工厂的瘦小代表 只使用浏览器路径( 见 `packages/add-in/src/bridge/`),并进行对等测试 (单位:千美元)`packages/add-in/tests/bridge-catalog-parity.test.ts`如果窗格显示失败 CI 登记从共享目录中漂移.

## 发展

```bash
npm run typecheck     # typecheck against @earendil-works/pi-coding-agent 0.85.x
npm run build         # emit dist/ (for the node smoke tests)
npm test              # smoke test + end-to-end interop test (real client ↔ real server)
```

`tests/pane-interop.mjs` 电线 **真实** 加进 `PaneBridgeClient` 页:1 **真实** 通过共享的桥接服务器 `@dieulc/pi-office-protocol` 软件包 - 最有力的证据 两半都同意电线格式.

## 议定书

电线协议共享于 `@dieulc/pi-office-protocol` (单位:千美元)`packages/protocol`) (中文(简体) ). 目前为 **页:1** (流化三角洲+花板中止); 凸起 `BRIDGE_PROTOCOL_VERSION` 打开更改。 生命周期命令和 页:1 `/health` 所有人是添加剂,不改变电线版本。 见 [`packages/protocol/README.md`](https://npmcn.com/package/%40dieulc/protocol/README.md) 换行记.

## 许可证

麻省理工学院

## 常见问题

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

原生 Pi 扩展名 — WebSocket Bridge \+ Office 工具代理,使 Pi 能通过 pi- for-office 添加来驱动 Excel, Word, and PowerPoint \.

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

在项目目录运行 npm install @dieulc/pi-office-bridge，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：typebox（\*）、@earendil-works/pi-ai（\>=0\.83\.0）、@earendil-works/pi-coding-agent（\>=0\.85\.0）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。

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

该包的 package\.json 没有声明类型入口。需要类型提示时，可以在 npm 上查找社区维护的 @types/dieulc\_\_pi-office-bridge 是否存在。

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

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

### @dieulc/pi-office-bridge 需要什么版本的 Node\.js？

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

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

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

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

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

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

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