# document-operations 中文文档

规范地址：https://npmcn.com/package/document-operations/

版本：1\.1\.201
npm 元数据更新时间：2026-11-03T11:39:58.023Z
中文译文更新时间：2026-11-03T12:39:34.659Z
软件包许可：MIT

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

原始 npm 页面：https://www.npmjs.com/package/document-operations
原文对照：https://npmcn.com/package/document-operations/?lang=original
项目主页：https://github.com/ExaDev/documents.js/tree/main/packages/document-operations
源码仓库：https://github.com/ExaDev/documents.js

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

- 包体积（解压后）：250 kB，7 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- Node.js 要求：\>=20
- 运行依赖：5 个
- 首次发布：2026-09-11T10:38:59.639Z
- 最新版本发布：2026-11-03T11:39:57.584Z
- 已发布版本数：203（近 12 个月 203 个）

## 中文简介

规范的文档转换、编辑、检查和。odb operations documents.js对每个操作公开一个Zod输入/输出模式和一个与传输无关的run（）函数，由document-mcp、document-cli和REST API服务器路径共享

## 安装

```sh
npm install document-operations
```

也可以使用：`pnpm add document-operations`、`yarn add document-operations`、`bun add document-operations`

## README

# 文档操作

[![GitHub](https://img.shields.io/badge/GitHub-181717?logo=github&logoColor=white)](https://github.com/ExaDev/documents.js/tree/main/packages/document-operations) [![npm](https://img.shields.io/badge/npm-CB3837?logo=npm&logoColor=white)](https://www.npmjs.com/package/document-operations) [![npm version](https://img.shields.io/npm/v/document-operations)](https://www.npmjs.com/package/document-operations) [![CI](https://img.shields.io/github/actions/workflow/status/ExaDev/documents.js/ci.yml?branch=main)](https://github.com/ExaDev/documents.js/actions)

> 规范的文档转换、编辑、检查和 `.odb` 操作 [`documents.js`](https://github.com/ExaDev/documents.js) 暴露—一个Zod输入/输出模式和一个与传输无关的模式 `run()` 每个操作的函数 [`document-mcp`](https://npmcn.com/package/document-mcp/README.md)， [`document-rest`](https://npmcn.com/package/document-rest/README.md), [`document-cli`](https://npmcn.com/package/document-cli/README.md) 是否可以在不重新定义其形状或行为的情况下公开相同的操作。

在这个包裹出现之前， `document-mcp` 直接在自己的工具中定义每个MCP工具的Zod模式和分派逻辑 `src/tools/*.ts`, `document-cli` 再次以手写方式描述相同的底层操作 `commander` 标志——“做什么”的两个独立定义 `convert_document` 以“可以默默地漂流，没有第三个表面可以建立的共同真相来源”为例。 `document-operations` 那是真相的来源吗，所有行动的来源 `document-mcp`它自己的工具集在行为上没有改变，从任何一个传输自己的结果塑造中解耦，并且 `document-rest` 第一个新消费者是直接针对它而不是针对第二个副本构建的吗？

```mermaid
graph TD
    schema("document-schema.js")
    documents("documents.js")
    outline("document-outline.js")
    compute("document-compute.js")
    operations("document-operations")
    mcp("document-mcp")
    rest("document-rest")

    schema --> documents
    schema --> outline
    schema --> compute
    documents --> operations
    outline --> operations
    compute --> operations
    operations --> mcp
    operations --> rest

    click schema "https://github.com/ExaDev/documents.js/tree/main/packages/document-schema.js" "document-schema.js"
    click documents "https://github.com/ExaDev/documents.js" "documents.js"
    click outline "https://github.com/ExaDev/documents.js/tree/main/packages/document-outline.js" "document-outline.js"
    click compute "https://github.com/ExaDev/documents.js/tree/main/packages/document-compute.js" "document-compute.js"
    click operations "https://github.com/ExaDev/documents.js/tree/main/packages/document-operations" "document-operations"
    click mcp "https://github.com/ExaDev/documents.js/tree/main/packages/document-mcp" "document-mcp"
    click rest "https://github.com/ExaDev/documents.js/tree/main/packages/document-rest" "document-rest"

    style operations fill:#f9a825,stroke:#333,stroke-width:3px
```

## 这个 `DocumentOperation` 合同

此包导出的每个操作都具有相同的形状(`src/operation.ts`）：

```ts
interface DocumentOperation<In, Out> {
  readonly name: string;
  readonly title: string;
  readonly description: string;
  readonly inputSchema: z.ZodType<In>;
  readonly outputSchema?: z.ZodType<Out>;
  run(input: In, context?: { readonly signal?: AbortSignal }): Promise<Out>;
}
```

`inputSchema`/`outputSchema` 是验证和描述文本的唯一真实来源； `run()` 是与传输无关的实现。失败总是抛出错误（普通错误，或以下错误之一） `documents.js`自己的打字错误，例如： `OdbReportNotSpecifiedError`， `OdmUnresolvedSectionError`) - - - `run()` 永远不要塑造特定于传输的结果。每个传输自己决定如何呈现抛出的错误： `document-mcp` 将其封装为 `isError` 工具结果(带有可选的 `mapError` （这两个操作的错误携带了值得在结构上显示的数据），REST路由会将其映射到4xx JSON体，CLI命令会将其打印到带有非零退出码的stderr。

`defineOperation()`/`defineOperationWithoutOutputSchema()` 从一个普通的对象中构建一个，进行推断 `In`/`Out` 从Zod模式中删除，这样调用站点就不会重复 `z.infer<typeof Schema>` 本身。使用 `WithoutOutputSchema` 少数操作的变体，其原始MCP工具注册声明no `outputSchema` 一点也不(`metadata_read`每个格式的返回形状不同；这个 `.odb`\-读取操作返回 `documents.js`—在那里添加一个猜测的模式可能会有引入以前不存在的输出验证的风险，并且可能会拒绝猜测没有预料到的真实值。

`DOCUMENT_OPERATIONS` （`src/registry.ts`)是一个数组中的每个操作——“与MCP相同的注册表”——一个希望枚举每个操作而不是按名称导入操作的调用者可以达到：MCP服务器将每个条目注册为工具，REST服务器将为每个条目添加一条路由，CLI将根据条目验证其自己的解析标志 `inputSchema` 发送之前 `run()`。

## 操作

下面的每个操作都是在行为不变的情况下从 `document-mcp`的自己的 `src/tools/*.ts` -请参阅该包的README以获得每个包的完整描述；该表是索引。

| 出口 | 名字 |
| --- | --- |
| `convertDocumentOperation` | `convert_document` |
| `listDocumentConversionsOperation` | `list_document_conversions` |
| `metadataReadOperation` | `metadata_read` |
| `metadataWriteOperation` | `metadata_write` |
| `documentCreateOperation` | `document_create` |
| `documentAppendParagraphsOperation` | `document_append_paragraphs` |
| `fontsOperation` | `fonts` |
| `describeFontFileOperation` | `describe_font_file` |
| `docxExtrasOperation` | `docx_extras` |
| `fromPackageOperation` | `from_package` |
| `outlineDocumentOperation` | `outline_document` |
| `pdfInspectOperation` | `pdf_inspect` |
| `computeFormulaOperation` | `compute_formula` |
| `odmToPdfOperation` | `odm_to_pdf` |
| `odbTablesOperation` | `odb_tables` |
| `odbFormsOperation` | `odb_forms` |
| `odbReportsOperation` | `odb_reports` |
| `odbQueryOperation` | `odb_query` |
| `odbToCsvOperation` | `odb_to_csv` |
| `odbToXlsxOperation` | `odb_to_xlsx` |
| `odbRenderReportOperation` | `odb_render_report` |

## 开始

```sh
pnpm install
pnpm build         # turbo -> tsdown -> dist/ (ESM + CJS + .d.ts)
pnpm typecheck     # turbo -> tsc --noEmit, plus attw --pack
pnpm lint          # turbo -> eslint . --fix --cache --max-warnings 0
pnpm test          # turbo -> vitest run
pnpm test:workers  # turbo -> vitest under the real Cloudflare Workers runtime (workerd) via @cloudflare/vitest-pool-workers, exercising every operation's bytesBase64 input path
```

## 陷阱

-   **不支持Worker同构，不像它所依赖的基础包。** `resolveDocumentInput`的 `path` 分支(`src/io/document-input.ts`)通过从磁盘读取文件 `node:fs/promises`, `odm_to_pdf`章节目录解析(`src/operations/odm.ts`)使用 `node:fs`的同步API——同样的原因 `document-mcp` 和 `document-cli` 的同构包列表中排除的 [monorepo root README](https://npmcn.com/README.md#conventions)。 `pnpm test:workers` 仍然证明了每一个操作 `bytesBase64` 输入路径在workerd下正确运行 `path`/`chaptersDir` 涉及),匹配 `document-mcp`自己的工人测试范围。
-   **`document-mcp`他自己的测试没有被移到这里** 他们继续测试完整的MCP注册(`createServer()` +一个真正的客户机/服务器JSON-RPC往返)，它仍然执行这个包自己的 `run()` 下面的函数——移动它们意味着重新验证现有的3000行代码，通过测试行为，没有功能上的好处。这个包自己的测试是对每个测试进行独立的、更直接的单元级检查 `run()` 独立运行。
-   **`odb_render_report`的 `OdbReportNotSpecifiedError` 和 `odm_to_pdf`的 `OdmUnresolvedSectionError` 不在这里被抓。** 两者都是由底层抛出的 `documents.js` 功能和繁殖- mcp特异性富集（修复提示）， `structuredContent.availableReports`/`.hrefs`)住在 `document-mcp`的自己的 `mapError` 钩子(`src/tools/odb-render-report.ts`， `src/tools/odm.ts`)，因为这种塑造是表示，而不是操作逻辑。

## 贡献

发布、CI和提交消息约定都是工作空间范围的，而不是包本地的——请参阅 [monorepo root README](https://npmcn.com/README.md#releases) 对于释放机制和 [CONTRIBUTING.md](https://npmcn.com/CONTRIBUTING.md) 对于共享的git钩子和历史约定。工作内 `packages/document-operations/`。

## 许可证

麻省理工学院

## 常见问题

### document-operations 是什么？

规范的文档转换、编辑、检查和。odb operations documents\.js对每个操作公开一个Zod输入/输出模式和一个与传输无关的run（）函数，由document-mcp、document-cli和REST API服务器路径共享

### 如何安装 document-operations？

在项目目录运行 npm install document-operations，或使用 pnpm add / yarn add / bun add。

### document-operations 支持 TypeScript 吗？

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

### document-operations 支持 ESM 还是 CommonJS？

同时提供 ES Module 与 CommonJS 入口，import 和 require\(\) 都可以使用，打包工具会自动选择合适的版本。

### document-operations 需要什么版本的 Node\.js？

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

### document-operations 可以商用吗？

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

### document-operations 还在维护吗？

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