@dieulc/pi-office-bridge (英语)
允许本地 Pi 进程驱动的本地 Pi 扩展 埃克塞尔, (中文(简体) ), 单词,以及 电源点 通过 pi- for- office (单位) 任务表 添加进.
纯粹的扩展——它只使用皮的公用扩展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 释放端口用于另一个会话.
两种流动:
-
工具代理( Pi ) : pi代理电话
office_excel_read_range, (中文(简体) ),office_word_insert_text,...; 扩展转发 atool_call页:1 ; 窗格运行 Office.js 的操作和回答tool_result。然后 LLM 查看文档内容 财务报告和审定财务报表 皮满了 系统工具(bash, git, 文件). -
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。 。 。 .
安装
pi install npm:@dieulc/pi-office-bridge
最新资料 (完整的29个工具目录包含. 结构/格式工具
0.3.0;多文件目标, office_list_documents 财务报告和审定财务报表 # 提及
自动完成需要 ^ 0.4.0 (protocol v2, 需要匹配添加)
建筑) /health 探测器和版本显示需要 0.2.0 :
pi install npm:@dieulc/pi-office-bridge@latest
然后重新启动 Pi。注意 pi install 针入它获取的版本
~/.pi/agent/npm/package.json,所以皮会 没有 自动升级——重新运行
上面的指挥来获得最新的桥梁.
或从单体(开发)作为 dev 桥 在端口时 38618
(单位:千美元)--no-extensions 忽略设置, 因此全球安装的 prod 桥
从未在同一过程中重复装入 :
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(小组行动+) 目录版本).
在添加中启用
- 安装/ 运行桥接, 因此此扩展的 Pi 进程正在监听 (见上文)。 保持Pi进程在背景中运行.
- 在 Excel / Word / PowerPoint 中打开 pi- for-office .
- 转到 设置 ~ 连接 ~ 本地 Pi 代理 (高级) 翻转 启用本地 Pi 代理 继续 卡片显示实时连接 状态( 连接... ) ; 不需要重装任务表 .
- 用卡片验证 测试连接 按钮,或从终端:
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。 。 。 .
版本容量( 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+)
/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
登记从共享目录中漂移.
发展
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 换行记.
许可证
麻省理工学院