# document-rest 中文文档 规范地址：https://npmcn.com/package/document-rest/ 版本：1\.4\.204 npm 元数据更新时间：2026-11-03T11:37:46.182Z 中文译文更新时间：2026-11-03T12:41:40.612Z 软件包许可：MIT 本文由上游 README 机器翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。 原始 npm 页面：https://www.npmjs.com/package/document-rest 原文对照：https://npmcn.com/package/document-rest/?lang=original 项目主页：https://github.com/ExaDev/documents.js/tree/main/packages/document-rest 源码仓库：https://github.com/ExaDev/documents.js ## 关键信息（来自 npm 元数据） - 包体积（解压后）：28.9 kB，8 个文件 - 模块格式：ESM + CJS - TypeScript 类型：包内自带 - Node.js 要求：\>=20 - 运行依赖：3 个 - 首次发布：2026-09-11T11:16:16.333Z - 最新版本发布：2026-11-03T11:37:45.796Z - 已发布版本数：208（近 12 个月 208 个） ## 中文简介 一个普通的REST API服务器，公开文档操作的转换、编辑、检查和操作。odb操作作为JSON-over-HTTP端点—对于没有MCP客户端和自己的Node运行时的调用者，每个操作一个POST路由。 ## 安装 ```sh npm install document-rest ``` 也可以使用：`pnpm add document-rest`、`yarn add document-rest`、`bun add document-rest` ## README # document-rest [![GitHub](https://img.shields.io/badge/GitHub-181717?logo=github&logoColor=white)](https://github.com/ExaDev/documents.js/tree/main/packages/document-rest) [![npm](https://img.shields.io/badge/npm-CB3837?logo=npm&logoColor=white)](https://www.npmjs.com/package/document-rest) [![npm version](https://img.shields.io/npm/v/document-rest)](https://www.npmjs.com/package/document-rest) [![CI](https://img.shields.io/github/actions/workflow/status/ExaDev/documents.js/ci.yml?branch=main)](https://github.com/ExaDev/documents.js/actions) > 一个普通的REST API服务器公开 [`document-operations`](https://npmcn.com/package/document-operations/README.md)文档转换, `.odb`、元数据和字体工具作为JSON-over-HTTP `POST` 对于没有MCP客户端和自己的Node运行时（Kotlin/JVM应用程序，Python脚本或任何其他具有HTTP客户端的语言）的调用者来说，路由。 `document-rest` 不添加自己的转换或编辑逻辑 [`document-mcp`](https://npmcn.com/package/document-mcp/README.md)，它是一个调度层 [`document-operations`](https://npmcn.com/package/document-operations/README.md)，唯一的区别是运输方式：1 `POST` 每个操作路由，而不是一个MCP工具。 `document-mcp`现有的 `--transport http` 模式并不能替代它：它在一个单一的接口上使用MCP自己的JSON-RPC协议 `/mcp` 路径，它仍然需要一个MCP客户端库来调用——这个包是为那些想要普通的请求/响应JSON而没有自己的协议分层的调用者准备的。 ## 开始 直接运行服务器-不需要安装步骤： ```sh npx document-rest --port 3100 ``` 这就绑定了一个plain `node:http` 侦听器到 `127.0.0.1` （仅环回） `--port` (默认 `3100`； `--port 0` 向操作系统请求一个空闲端口，绑定后在stderr上报告)。 > **安全注意事项:** 这个监听器没有身份验证，也没有自己的Host/Origin允许列表——任何可以访问它的人都可以调用每个操作，包括读取和写入任意文件系统路径的操作。默认情况下，它是安全的，因为它绑定了环回；无论它为远程访问（隧道，反向代理）提供什么，都负责在流量到达此进程之前对调用者进行身份验证。匹配 [`document-mcp`的自己的 `--transport http` 侦听器](https://npmcn.com/package/document-mcp/README.md#remote-transport-http)，因为同样的原因，它带有相同的音符。 ### 独立的二进制 每个版本还附加一个Node [单一可执行文件的应用程序](https://nodejs.org/api/single-executable-applications.html) 构建Linux (x64和arm64), Windows （x64和arm64）和macOS （Apple Silicon和Intel）到该版本自己的GitHub发布资产-整个服务器及其依赖项嵌入在一个文件中，不需要Node.js安装或 `npx` 在所有。对于“没有自己的Node运行时的调用者”这种情况，这个包首先存在，这也删除了最后一个Node依赖：从包的标签上下载与您的平台匹配的资源 [发布页面](https://github.com/ExaDev/documents.js/releases)，直接运行(`chmod +x` 首先在Linux/macOS上)，并且它需要相同的 `--port` 国旗。 ### 集装箱图片 每个版本还发布了一个多arch (`linux/amd64` + `linux/arm64`)容器映像到GitHub容器注册表，包装相同的独立二进制以上的最小 [distroless](https://github.com/GoogleContainerTools/distroless) base而不是Node安装： ```sh docker run -p 3100:3100 ghcr.io/exadev/documents.js:VERSION --port 3100 ``` 取代 `VERSION` 使用软件包自己的确切发布版本(例如。 `1.2.0`) -与此存储库中其他工件使用的版本固定约定相匹配，此映像永远不会在松散的主要/次要标签下发布，例如 `1` 或 `1.2`,虽然 `latest` 跟踪最新的版本。图像绑定到 `0.0.0.0` 在容器内不管 `--port`,所以 `-p :` 是到达它所需要的一切；请参阅上面关于此侦听器本身没有身份验证的安全说明-发布容器的端口使任何可以到达主机的东西都可以访问它，因此在将其公开到您自己的机器之外之前，请在其前面放置反向代理或防火墙。 ## API **`GET /`** 列出所有可用的操作： ```sh curl http://127.0.0.1:3100/ ``` ```json { "operations": [{ "name": "convert_document", "title": "Convert document", "description": "..." }, ...] } ``` **`POST /`** 运行一个操作：请求体是JSON，根据该操作自己的输入模式进行验证，响应是JSON `{ "result": ... }` 在成功。每个操作 `document-operations` 定义可以通过这种方式访问-参见 [该软件包自己的README](https://npmcn.com/package/document-operations/README.md#operations) 有关操作名称的完整列表以及每个操作的功能；请求/响应形状与等效MCP工具自己的形状相同 `structuredContent`，因为这两个调度到完全相同的 `run()` 函数。 ```sh curl -X POST http://127.0.0.1:3100/convert_document \ -H 'content-type: application/json' \ -d '{"source":{"path":"/tmp/report.docx"},"targetFormat":"markdown"}' ``` ### 错误 | 状态 | 当 | | --- | --- | | `400` | 请求体不是有效的JSON，操作自己的输入模式失败(`{ error, issues }`从佐德那里 `treeifyError`)，或者操作本身抛出(`{ error }`抛出的消息)。 | | `404` | 该名称不存在任何操作。 | | `405` | 一种方法 `POST` 被用来对付已知的行动路线(`GET /` 是唯一的例外)。 | 两个操作丰富了他们的 `400` 身体超越赤裸 `{ error }`,反映 `document-mcp`的自己的 `registerOperation` `mapError` 用于相同的两个类型错误的钩子： `odb_render_report`的 `OdbReportNotSpecifiedError` 增加了 `availableReports` (每一个报告的名称 `.odb` 实际上声明)，和 `odm_to_pdf`的 `OdmUnresolvedSectionError` 增加了 `hrefs` （未能解决的每一章参考）。 ## 入门（开发） 需要node . js `>=20` 和规划 `11.6.0` (固定通过 `packageManager` 在 `package.json`）. ```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, driving a real ephemeral-port HTTP server through fetch() ``` ## 陷阱 - **没有流媒体，没有块上传。** `readJsonBody` 在解析为JSON之前，将整个请求体缓冲到内存中，匹配每个操作自己的混合 `bytesBase64`或者,`path` 输入约定（大型文档最好由filesystem提供） `path`（由操作本身读取一次，而不是在HTTP上使用base64填充）。 - **客户端断开连接时中止。** 每个请求都有自己的请求 `AbortSignal`，连接到底层 `IncomingMessage`的 `close` 事件（节点：http携带no） `AbortSignal` 它自己的)-在转换过程中断开连接的客户端会导致操作自己的信号感知工作(例如； `convert_document`（如页面边界取消）停止在下一个检查点，而不是运行到不再侦听的调用者完成。 ## 贡献 发布、CI和提交消息约定都是工作空间范围的，而不是包本地的——请参阅 [monorepo root README](https://npmcn.com/README.md#releases) 对于释放机制和 [CONTRIBUTING.md](https://npmcn.com/CONTRIBUTING.md) 对于共享的git钩子和历史约定。工作内 `packages/document-rest/`。 ## 许可证 麻省理工学院 ## 常见问题 ### document-rest 是什么？ 一个普通的REST API服务器，公开文档操作的转换、编辑、检查和操作。odb操作作为JSON-over-HTTP端点—对于没有MCP客户端和自己的Node运行时的调用者，每个操作一个POST路由。 ### 如何安装 document-rest？ 在项目目录运行 npm install document-rest，或使用 pnpm add / yarn add / bun add。它还提供命令行工具 document-rest，可以用 npx document-rest 直接运行。 ### document-rest 支持 TypeScript 吗？ 支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。 ### document-rest 支持 ESM 还是 CommonJS？ 同时提供 ES Module 与 CommonJS 入口，import 和 require\(\) 都可以使用，打包工具会自动选择合适的版本。 ### document-rest 需要什么版本的 Node\.js？ package\.json 的 engines 字段要求 Node\.js \>=20。版本不符时 npm 默认只给出警告，开启 engine-strict 后会拒绝安装。 ### document-rest 可以商用吗？ document-rest 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。 ### document-rest 还在维护吗？ 最新版本 1\.4\.204 发布于 2026/11/03（今天）；至今共发布 208 个版本，其中过去 12 个月发布了 208 个；首次发布于 2026/09/11。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。