# @adelie/use-wps-office 中文文档

规范地址：https://npmcn.com/package/%40adelie/use-wps-office/

版本：0\.6\.4
npm 元数据更新时间：2026-11-05T05:09:05.689Z
中文译文更新时间：2026-11-06T15:32:12.910Z
软件包许可：Apache-2\.0

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

原始 npm 页面：https://www.npmjs.com/package/%40adelie/use-wps-office
原文对照：https://npmcn.com/package/%40adelie/use-wps-office/?lang=original
源码仓库：https://github.com/lmliheng/Adelie

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

- 包体积（解压后）：180 kB，20 个文件
- TypeScript 类型：未声明
- 运行依赖：0 个
- 首次发布：2026-10-17T01:12:23.522Z
- 最新版本发布：2026-11-05T05:09:05.479Z
- 近 30 天下载量：2896（2026-10-05 至 2026-11-03，npm 官方下载统计）
- 已发布版本数：18（近 12 个月 18 个）

## 中文简介

WPS Writer内部的Adelie:一个没有依赖性的桥,它托管一个WPS加载面板,让Agent通过MCP工具来读取并编辑打开的文档,并用WPS自己的本地出版服务来注册加载——只回回.

## 安装

```sh
npm install @adelie/use-wps-office
```

也可以使用：`pnpm add @adelie/use-wps-office`、`yarn add @adelie/use-wps-office`、`bun add @adelie/use-wps-office`

## README

# WPS（`@adelie/use-wps-office`）

把 Adelie 的对话搬进 **WPS 文字**：功能区多一个「Adelie」按钮，点开是侧栏——问它、让它读、让它改 当前这篇文档；同一套文档操作也作为 MCP 工具交给 Agent（`mcp__wps__*`）。

运行时就是一个**零依赖的 Node 文件**（`skills/wps-office/kit/serve.mjs`）。它同时是四样东西：

| 身份 | 接口 | 干什么 |
| --- | --- | --- |
| 面板的宿主 | `GET /addin/*` | 发加载项那一页（WPS 以「在线加载项」加载这个目录） |
| Agent 的手 | `GET /addin/commands`（SSE）+ `POST /addin/result`，以及 `POST /mcp` | 把文档操作下发给面板执行，一次只跑一条；同一个操作也作为 MCP 工具给 Adelie |
| Adelie 的客户端 | \`GET /panel/state | history |
| WPS 的安装按钮 | `GET /publish`、\`POST /publish/enable | disable\` |

**为什么要中间这个桥**：面板跑在 WPS 的内嵌浏览器里，与 Adelie 不同源，而 Adelie 明确不开 CORS （仅限同源）。桥就是那个「另一个源」——面板只跟它说话，它再跟 Adelie 说话。全程只走 `127.0.0.1`。

## 装

```bash
node skills/wps-office/kit/install.mjs
```

它写设置、把加载项交给 WPS（这一步 WPS 要开着）、把桥登记成 Agent 的一个 MCP 服务器并自检、 在 Windows 上放一个开机自启的 `.cmd`、然后把桥拉起来。**每一步都可以重复跑，重跑就是修复。**

诊断页：`http://127.0.0.1:3891/status`；安装按钮那一页：`/publish`。文件都在数据根的 `wps-bridge/`（设置、状态、`bridge.log`）——**不放插件目录**，因为插件更新会整体替换。

卸载：`node skills/wps-office/kit/uninstall.mjs`（加 `--purge` 连日志一起删）。

## 文件

| 路径 | 是什么 |
| --- | --- |
| `skills/wps-office/kit/serve.mjs` | 桥，也是这个插件的全部运行时 |
| `skills/wps-office/kit/adelie.mjs` | 找 Adelie、带令牌调它的 HTTP 客户端（`install.mjs` 也用） |
| `skills/wps-office/kit/wps.mjs` | WPS 本机上架服务（58890）的客户端 |
| `skills/wps-office/kit/install.mjs` / `uninstall.mjs` | 装与卸 |
| `skills/wps-office/kit/addin/` | 加载项本身：`manifest.xml`、`ribbon.xml`、面板页与文档操作层 |
| `skills/wps-office/SKILL.md` | Agent 读的说明书 |
| `test/` | 桥、安装脚本、加载项托管、面板冒烟四组测试 |

## 测试

```bash
node --test plugins/use-wps-office/test/          # 桥、安装脚本、加载项托管（不需要浏览器）
cd packages/web && npx playwright test -c ../../plugins/use-wps-office/test/playwright.config.mjs
                                                  # 面板在 Chromium 里真的跑一遍（14 条）
```

面板那组跑的时候 `stub-wps.js` 会顶掉 WPS：假文档、假 Range、假任务窗格接口，所以没有 WPS 的 机器也能验。**真机上没验过的**：ribbon 按钮图标呈现、`CreateTaskPane`/`PluginStorage`/`app.Enum` 的真实行为、`app.Selection` 的字符偏移、`Documents.Add` 四参数的老版本兼容、IME 回车。这些只能 在 Windows + WPS 上跑第一次。

## 来源

加载项的清单形状、ribbon 回调写法、`InsertBreak` 的位置取法（段落标记之前一格）参考了 Apache-2.0 的文策 AI（`visresearch/WordAgent`，`frontend/wps_word_plugin/`）与其发布页 （`backend/gui/resources/publish.html`，58890 那套接口的出处）；代码按本项目的契约重写，没有整段搬运。

## 常见问题

### @adelie/use-wps-office 是什么？

WPS Writer内部的Adelie:一个没有依赖性的桥,它托管一个WPS加载面板,让Agent通过MCP工具来读取并编辑打开的文档,并用WPS自己的本地出版服务来注册加载——只回回\.

### 如何安装 @adelie/use-wps-office？

在项目目录运行 npm install @adelie/use-wps-office，或使用 pnpm add / yarn add / bun add。

### @adelie/use-wps-office 支持 TypeScript 吗？

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

### @adelie/use-wps-office 可以商用吗？

@adelie/use-wps-office 使用 Apache-2\.0 许可。宽松许可：允许商业使用、修改和再分发，并附带明确的专利授权；分发时需保留许可与 NOTICE 文件，修改过的文件要注明改动。以上为概括，不构成法律意见，请以许可原文为准。

### @adelie/use-wps-office 的下载量有多少？

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

### @adelie/use-wps-office 还在维护吗？

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