# @betteroffice/agents 中文文档

规范地址：https://npmcn.com/package/%40betteroffice/agents/

版本：0\.3\.0
npm 元数据更新时间：2026-10-27T11:28:03.151Z
中文译文更新时间：2026-11-08T00:26:20.242Z
软件包许可：Apache-2\.0

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

原始 npm 页面：https://www.npmjs.com/package/%40betteroffice/agents
原文对照：https://npmcn.com/package/%40betteroffice/agents/?lang=original
项目主页：https://betteroffice.dev/
源码仓库：https://github.com/openooxml/betteroffice

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

- 包体积（解压后）：367 kB，16 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- Node.js 要求：\>=22
- 运行依赖：9 个
- 首次发布：2026-10-23T13:11:57.595Z
- 最新版本发布：2026-10-27T11:28:02.630Z
- 近 30 天下载量：7648（2026-10-08 至 2026-11-06，npm 官方下载统计）
- 已发布版本数：4（近 12 个月 4 个）

## 中文简介

搜索、检查、提议、预览和导出Office文档,通过打入的工具和MCP进行编辑.

## 安装

```sh
npm install @betteroffice/agents
```

也可以使用：`pnpm add @betteroffice/agents`、`yarn add @betteroffice/agents`、`bun add @betteroffice/agents`

## README

# @ betteroffice/ 代理服务器

通过 TypeScript SDK 从代理服务器搜索、阅读、编辑和预览 DOCX、 XLSX 和 PPTX 文件 或 `betteroffice-mcp` 服务器。 代理处理大型文件的方式 : grep,读取一个小区域,进行精确的编辑,检查结果,导出.

不需要模型提供者,API密钥或代理框架.

## 安装

```bash
bun add @betteroffice/agents
```

要求节点.js 22或后.

## 使用量

### MCP 服务器

```bash
bunx --package @betteroffice/agents betteroffice-mcp --root /absolute/path/to/documents
```

服务器在stdin/stdout上会说出MCP,所以从一个MCP客户端连接. 例如,使用 Codex :

```bash
codex mcp add betteroffice -- /absolute/path/to/node_modules/.bin/betteroffice-mcp --root /absolute/path/to/documents
```

| 旗帜 | 说明 |
| --- | --- |
| `--root <directory>` | 要求。 每个文件路径都会针对它解决,包括同义链接. |
| `--read-only` | 仅展示检查工具:不推荐、编辑、接受或导出. |

导出时总是写出一个新的文件, 并且绝不覆盖已有的文件 。 路径检查不是 操作系统沙盒,所以使用您控制的工作空间目录.

### SDK 软件

```ts
import { readFile, writeFile } from 'node:fs/promises';
import { openDocx } from '@betteroffice/agents';
import { renderDocxPage } from '@betteroffice/agents/render';

const doc = await openDocx(await readFile('report.docx'), {
  name: 'report.docx',
  renderer: renderDocxPage,
});

try {
  const [hit] = doc.grep({ query: '€4.2 million' }).matches;
  if (!hit) throw new Error('Revenue text not found');
  const proposal = doc.propose({
    author: 'report-agent',
    note: 'Update the executive summary revenue',
    edits: [{ match: hit.match, newText: '€5.1 million' }],
  });

  const preview = await doc.render(1, proposal.id);
  await writeFile('preview.png', preview.png);
  console.log(doc.review(proposal.id), await doc.verify(proposal.id));
  await writeFile('report-revised.docx', await doc.export(proposal.id), { flag: 'wx' });
} finally {
  doc.close();
}
```

出口待决提案后,该文件保持不变。 要应用它,打电话 `await doc.accept(proposal.id)` 接下来 `doc.export()` 没有身份证 对于Word跟踪的变化, 调用 `doc.accept(id, { tracked: true, date: '2026-09-27T12:00:00Z' })`。 。 。 .

## 入境点

| 导出 | 说明 |
| --- | --- |
| `openDocx(bytes, { name?, renderer? })` | 在自己的会话中打开 DOCX 文件. |
| `attachDocx(session, options?)` | 包装活编辑器 `YrsSession`。关闭适配器后,会话开始. |
| `openXlsx(bytes, { name?, wasm? })` | 打开 XLSX 工作手册:单元格读取和单元格提议. |
| `attachXlsx(handle, options?)` | 包成活页 `WorkbookHandle`。 。 。 . |
| `openPptx(bytes, { name?, wasm? })` | 打开 PPTX 演示文稿:大纲、幻灯片读取、文本提案、原子 `edit` 批次和 `preview`。 。 。 . |
| `attachPptx(handle, options?)` | 包成活页 `PresentationHandle`。 。 。 . |
| `renderDocxPage` (从) `@betteroffice/agents/render`(中文(简体) ) | DOCX 页面预览的节点画布渲染器 . |
| `renderPptxSlide` | PPTX 幻灯片预览的节点画布渲染器. |
| `createOfficeMcpServer({ root, renderer?, readOnly? })` (从) `@betteroffice/agents/mcp`(中文(简体) ) | MCP服务器,用于连接自身运输的主机. |

DOCX 和 PPTX 文档阶段文本编辑 `grep`, (中文(简体) ), `read` 财务报告和审定财务报表 `propose`; 工作手册的使用 `readCells` 财务报告和审定财务报表 `proposeCells` 换句话说 所有适配器共享 `review`, (中文(简体) ), `accept`, (中文(简体) ), `reject`, (中文(简体) ), `verify`, (中文(简体) ), `export` 财务报告和审定财务报表 `close`。 。 。 . `openXlsx` 财务报告和审定财务报表 `openPptx` 在节点装入捆绑的 Web Assembly; 在 a 浏览器,将模块字节传递为 `wasm`。浏览器中的 DOCX 预览需要自定义 `DocumentRenderer` 而不是节点帆布渲染器.

## MCP工具

| 工具 | 目的 |
| --- | --- |
| `office_files` | 列出DOCX,XLSX和PPTX文件,子目录和打开文档ID. |
| `office_open` | 打开文件并返回其文档ID,格式和能力. |
| `office_outline` | 通过 DOCX 段落, PPTX 幻灯片段落或 XLSX 工作表的页面. |
| `office_grep` | 带有上下文的字形搜索;返回匹配ID或单元格手柄. |
| `office_read` | 读取段落或单元格字段; DOCX 读取内容包括运行格式. |
| `office_cells` | XLSX:读取一个有值,公式和单元格手柄的A1范围. |
| `office_propose` | DOCX/PPTX: 阶段1-32文本替换为 `{ match, newText }`。 。 。 . |
| `office_propose_cells` | XLSX:阶段1-32全细胞输入或公式. |
| `office_review` | 列出提案或显示一项提案的修改前后. |
| `office_accept` | 将提案应用为倒置步骤; DOCX 可以将其保留为跟踪更改 . |
| `office_reject` | 弃取正议. |
| `office_render` | DOCX:当前或拟议页面的PNG. |
| `office_verify` | 保存并重新打开内存; 检查运行的报告 . |
| `office_export` | 将已接受的编辑或待决建议写入新文件 . |
| `office_close` | 发布一份公开文件及其建议. |
| `docx_edit` | DOCX: 原子直接编辑段落样式、粗体/斜体/下行、段落、表格行、单元格合并、注释(添加、回复、解决或重开)和页面设置 `insert_section_break` 财务报告和审定财务报表 `set_section`· ; `runFormat: 'anchor'` 复制插入时的第一个普通运行. |
| `xlsx_outline`, (中文(简体) ), `xlsx_read_range` | XLSX:工作表,被使用的范围,表格和被定义的名称;范围读取有版本. |
| `xlsx_write_range`, (中文(简体) ), `xlsx_format`, (中文(简体) ), `xlsx_sort` | XLSX:已版本的值和公式写入,格式化和排序. |
| `xlsx_list_defined_names`, (中文(简体) ), `xlsx_edit_defined_names` | XLSX:用页标列出完整的名称;在原子上设置或删除工作簿和工作表所标注的名称,包括隐藏的旗帜. |
| `xlsx_edit_grid`, (中文(简体) ), `xlsx_edit_sheets` | XLSX:插入或删除行和列;添加,重命名,删除或移动工作表. |
| `xlsx_set_auto_filter` | XLSX:设置,扩展或去除工作表的过滤按钮;表格过滤器被拒绝. |
| `xlsx_list_charts`, (中文(简体) ), `xlsx_read_chart_text`, (中文(简体) ), `xlsx_edit_charts` | XLSX:通过完整的标题,名称和引用来检查工作表和图表表及页面上的图表;替换或去掉标题并编辑序列名称,类别 refs和值 refs 原子. |
| `xlsx_list_conditional_formats`, (中文(简体) ), `xlsx_read_conditional_format_formula`, (中文(简体) ), `xlsx_edit_conditional_formats` | XLSX: 通过完整的公式列出绑定规则预览和页面; 添加或删除 `cellIs` 财务报告和审定财务报表 `expression` 使用不同格式的规则. |
| `xlsx_find_replace`, (中文(简体) ), `xlsx_preview` | XLSX: 查找并替换已显示的文本; 范围为 PNG. |
| `pptx_outline`, (中文(简体) ), `pptx_read_slide` | PPTX:幻灯片,布局和形状;形状树,段落,运行和注释. `office_outline` 与 `story: 'comments'` 列出讨论情况; `office_read` 读取全文. |
| `pptx_edit`, (中文(简体) ), `pptx_preview` | PPTX:原子文本,幻灯片,布局映射,形状,图像,注释,注释(`add_comment`, (中文(简体) ), `reply_comment`, (中文(简体) ), `resolve_comment`)和表格结构编辑(`insert_table_row`, (中文(简体) ), `delete_table_row`, (中文(简体) ), `insert_table_column`, (中文(简体) ), `delete_table_column`); 幻灯片的PNG. |

## 编辑和参考

-   参考资料`ref`, (中文(简体) ), `match`, (中文(简体) ), `revision`, (中文(简体) ), `version`)属于公开会议。 重新打开文件 创造出新的。 页面,幻灯片和段落编号为一基;文本抵消为零基.
-   DOCX和PPTX搜索默认为字面和大小写不敏感. XLSX 密码 `office_grep` 搜索 以区分大小写的方式显示值.
-   一项提案有1-32个单独的替换人,在一份临时副本之前经过验证 原子更新. 改变目标使其变得僵化(`STALE_TARGET`:再读再求婚.
-   新文本采用第一个被替换字符的格式。 保留几种风格 将该段改为整个段.
-   段落间隔、内嵌和现有跟踪改动不受文本提案的影响.
-   承诺的 XLSX 或 PPTX 编辑无效所有未完成的手柄、光标和为此提出的建议 文档.
-   结果被分解(`nextCursor`, (中文(简体) ), `nextOffset`, (中文(简体) ), `nextStart`) (中文(简体) ). 结果的一页从来不是 彻底搜索.

## 限制

-   最多16 000个UTF-16单元的读取返回和100个格式化运行;最多100个项目的读取返回.
-   MCP服务器最多可打开10个文件,每个文件最多64个米B,每个文件最多可保存64个提案 文档。 所有状态都在内存中:关闭客户端前导出.
-   Stdin上面的MCP消息封顶为一米B.
-   `verify` 证实保存的文件重新打开 。 它不检查视觉的忠诚度或者 编辑完全正确;为此使用读取并预览.
-   预览使用 BetterOffice 版式引擎和捆绑的字体,而不是像素等同的字体 办公室 安装 `@betteroffice/fonts-cjk` 为CJK格言.

## 文档

-   [代理指南](https://docs.betteroffice.dev/docs/agents)
-   [`@betteroffice/docx`](https://www.npmjs.com/package/@betteroffice/docx)
-   [`@betteroffice/xlsx`](https://www.npmjs.com/package/@betteroffice/xlsx)
-   [`@betteroffice/pptx`](https://www.npmjs.com/package/@betteroffice/pptx)
-   [格式化 eval 套件](https://github.com/openooxml/betteroffice/blob/main/eval/README.md)
-   [仓库](https://github.com/openooxml/betteroffice/tree/main/packages/agents)

## 常见问题

### @betteroffice/agents 是什么？

搜索、检查、提议、预览和导出Office文档,通过打入的工具和MCP进行编辑\.

### 如何安装 @betteroffice/agents？

在项目目录运行 npm install @betteroffice/agents，或使用 pnpm add / yarn add / bun add。它还提供命令行工具 betteroffice-mcp，可以用 npx betteroffice-mcp 直接运行。

### @betteroffice/agents 支持 TypeScript 吗？

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

### @betteroffice/agents 支持 ESM 还是 CommonJS？

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

### @betteroffice/agents 需要什么版本的 Node\.js？

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

### @betteroffice/agents 可以商用吗？

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

### @betteroffice/agents 的下载量有多少？

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

### @betteroffice/agents 还在维护吗？

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