# @s8fy/xdoc 中文文档

规范地址：https://npmcn.com/package/%40s8fy/xdoc/

版本：0\.18\.0
npm 元数据更新时间：2026-11-02T08:54:02.412Z
中文译文更新时间：2026-11-02T09:40:54.510Z
软件包许可：PolyForm-Noncommercial-1\.0\.0

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

原始 npm 页面：https://www.npmjs.com/package/%40s8fy/xdoc
原文对照：https://npmcn.com/package/%40s8fy/xdoc/?lang=original
项目主页：https://structurify.io/en/products/pptx-runtime
源码仓库：https://github.com/hustcer/workers

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

- 包体积（解压后）：23.4 kB，8 个文件
- TypeScript 类型：未声明
- Node.js 要求：\>=22\.0\.0
- 运行依赖：0 个
- 首次发布：2026-09-10T09:22:57.965Z
- 最新版本发布：2026-11-02T08:54:02.058Z
- 已发布版本数：19（近 12 个月 19 个）

## 中文简介

本地PowerPoint CLI和MCP服务器可编辑的PPTX，本地3D图表，JSON补丁，模板数据绑定，PDF/PNG导出和Markdown提取的RAG。

## 安装

```sh
npm install @s8fy/xdoc
```

也可以使用：`pnpm add @s8fy/xdoc`、`yarn add @s8fy/xdoc`、`bun add @s8fy/xdoc`

## README

# xdoc

**创建可编辑的ppt。自动化文档工作流。给你的AI代理一个文档运行时。**

`@s8fy/xdoc` 带来了本地人 **xdoc CLI** npm。创建和编辑 `.pptx` 文件，导出PDF和幻灯片图像，提取AI工作流的内容，以及 通过结构化报告检查结果。文本、形状、表格和 支持的图表仍然是原生的PowerPoint对象，您可以继续编辑。

从JSON构建季度回顾。从业务数据刷新报表。 重新设计现有桥牌的样式。让代理解析精确的对象，预览其 更改，并留下演示文稿如何制作的记录。

## 关键特性

-   **本地PowerPoint创建和编辑。** 使用可编辑的文本、形状、 表格、图片、连接器、方程式和支持的图表。集中编辑 保持原始的OOXML；现有的SmartArt和复杂的时序已经分开 保护边界。
-   **带有真实数据的图表。** 创建和更新支持的经典，3D和现代 办公图表，包括嵌入的工作簿数据。支持的3D场景字段 保持原生OOXML。表类型、变体和样式遵循已安装的 模式;创作和呈现支持是分开的。
-   **JSON补丁和数据驱动报告。** 使用闭模式操作， 确定性选择器、配方、模板绑定、循环、条件、 以及用于从提供的内容组装或更新表示的宏。
-   **本地PDF和PNG渲染。** 导出支持的文本，矢量，图像， 表格、图表、方程式和效果，无需PowerPoint、LibreOffice、 浏览器或转换服务。提供合适的字体；使用一些特效 栅格层，PDF/PNG不播放动画。
-   **RAG和AI输入的降价。** 保留源幻灯片编号，支持 图表数据、表格、注释和打包的图像参考/资产。人工智能的细节 添加元素上下文。OCR，嵌入，索引和答案生成属于 到消费应用程序。
-   **可审查的代理自动化。** 发现运行时模式，之前进行演练 编写、检查结构化错误，并保留修订工具。CLI, JSON-RPC和MCP提供不同的集成界面。

## 测试和保真度验证

-   **6000多个自动化测试用例** 跨运行时和相关的创作， 解析、PDF/PNG、Markdown、数学和元文件引擎有助于检测回归。
-   **在500多个真实的演示平台上测试**，除了聚焦装置， 评估真实文档的行为和渲染。
-   **内部开发的专有保真工作流程** 支持正在进行的 渲染改进和回归预防。

探索 [产品概述](https://docs.structurify.io/en/pptx-runtime/)， [快速入门](https://docs.structurify.io/en/pptx-runtime/getting-started/)， 和 [代理协议指南](https://docs.structurify.io/en/pptx-runtime/agents/).

## 安装并试用

需要 **Node.js 22或更新版本**． 看到 [支持的平台上](https://npmcn.com/package/%40s8fy/xdoc/#readme-supported-platforms).

```sh
npm install --global @s8fy/xdoc
xdoc --version
```

从一个现有的演示开始，用一个命令生成一个review bundle：

```sh
# Export PDF, slide PNGs, a contact sheet, and AI-ready Markdown
xdoc convert deck.pptx --to pdf,png,md --md-detail ai --contact-sheet --output-dir exports
```

转换和本地PPTX编辑无需Office即可在本地运行 安装。渲染使用xdoc自己的后端；可用字体会影响 结果。自由模式有 [任务限制和视觉水印](https://npmcn.com/package/%40s8fy/xdoc/#readme-free-mode-and-licensing).

## 你能做什么

| 目标 | Xdoc给你 |
| --- | --- |
| **构建一个可编辑的桥牌** | 声明式JSON补丁、幻灯片配方、文本、预设形状、连接器、图像、表格、支持的图表、方程和注释。 |
| **更改现有表示** | 检查它的结构，根据id、名称或查询选择对象，并首先使用非写的试运行应用有重点的更改。 |
| **生成循环报告** | 从JSON中填充PPTX模板；绑定文本、表格和图表数据；使用宏、循环和条件补丁操作。 |
| **刷新桥牌设计** | 应用品牌配置文件，交换主题/风格包，在套牌之间复制幻灯片，或使用本地的DeckKit皮肤。 |
| **准备本地化** | 扫描文本，从提供的翻译中计划替换，并在编辑后比较样式和布局。 |
| **转换和提取** | PPTX到PDF， PNG， JSON, Markdown，或文本；结构化的注释、链接、字体和资源清单；PDF文本/渲染;HTML到Markdown。 |
| **发货前检查** | 字体、链接、资产、可访问性和Office兼容性检查；静态布局诊断；渲染预览;语义和视觉差异。 |
| **连接AI代理** | 运行时模式、版本化JSON报告、结构化错误、本地守护进程、stdio JSON- rpc和基于stdio的MCP。 |

## 从JSON创建第一个deck

另存为 `review.patch.json`． 它创建了一个标题幻灯片和一个KPI幻灯片 使用内置食谱：

```json
{
  "schemaVersion": "pptx-patch/v1",
  "ops": [
    {
      "op": "add-slide",
      "recipe": {
        "kind": "title",
        "title": "Quarterly momentum",
        "subtitle": "A business review built with xdoc"
      }
    },
    {
      "op": "add-slide",
      "recipe": {
        "kind": "kpi-grid",
        "title": "Growth at a glance",
        "items": [
          { "label": "Revenue", "value": "$2.4M", "delta": "+18%" },
          { "label": "Customers", "value": "1,280", "delta": "+22%" },
          { "label": "Retention", "value": "98%", "delta": "+2 pts" }
        ]
      }
    }
  ]
}
```

验证计划，创建甲板，并渲染预览：

```sh
# Resolve and simulate the patch without writing the presentation
xdoc pptx apply --patch review.patch.json --output review.pptx --dry-run --json

# Create review.pptx and its review.pptx.xdoc.json sidecar
xdoc pptx apply --patch review.patch.json --output review.pptx --json

# Render PNGs and a contact sheet
xdoc pptx preview review.pptx --output-dir review-previews --contact-sheet --json
```

开放 `review.pptx` 并编辑生成的文本和形状。 更改JSON中的KPI值以生成另一个审阅，或探索食谱 如 `timeline`， `roadmap`， `process-flow`， `comparison-table`, `gantt`. 组合单独的操作来添加图表、表格、图表和支持 动画或过渡。补丁 `slide` 索引从 **0**，而CLI `--slides` 选择从 **1**.

默认情况下，保护现有的输出路径。添加 `--overwrite` 当你 打算替换以前的输出。

## 将日常甲板工作转化为命令

### 检查、瞄准和编辑

在构建编辑补丁之前找到实际的PowerPoint对象：

```sh
xdoc pptx inspect deck.pptx --json
xdoc pptx select deck.pptx --query '{"textRegex":"Revenue"}' --json

# edit.patch.json contains your schema-valid changes to the selected objects
xdoc pptx apply --patch edit.patch.json --input deck.pptx --output updated.pptx --dry-run --json
xdoc pptx apply --patch edit.patch.json --input deck.pptx --output updated.pptx --json
```

检查提供对象标识、文本、几何、布局和样式。选择器 确定地解决目标；歧义匹配会产生错误 候选人。只有在全操作集设置完成后，才能使用补丁操作 成功。上面的命令编写了一个单独的候选项以供审查。

### 填充模板或尝试新的外观

用你自己的 `template.pptx`，业务数据 `data.json`，以及模式定义的 文本/表格/图表映射 `bindings.json`：

```sh
xdoc pptx template-fill data.json --template template.pptx --bindings bindings.json --output report.pptx
```

发现内置的主题包，然后在套牌上尝试一个：

```sh
xdoc pptx catalog themes --json
xdoc pptx swap-theme deck.pptx --theme corporate-blue --output themed.pptx
xdoc pptx swap-style deck.pptx --style consulting --output styled.pptx
```

### 提取原料并进行批次转换

```sh
# Extract the outline, resource inventory, notes, links, and fonts
xdoc extract deck.pptx --parts map,resources,notes,links,fonts --pretty --output artifacts.json

# Read text from a PDF and normalize a local HTML page to Markdown
xdoc pdf extract-text source.pdf --json --pretty
xdoc html2md page.html --output page.md

# Convert a directory and retain a structured batch summary
xdoc convert ./decks --recursive --to pdf --output-dir ./converted --report batch.json
```

PDF文本和HTML Markdown可以提供摘要或代理的内容管道。 然后使用配方、补丁或PPTX模板创建表示。

### 检查结果并保留证据

```sh
# Include accessibility alongside the standard preflight checks
xdoc check updated.pptx --checks all --output preflight.json

# Check static layout risks and compare the source with the candidate
xdoc pptx vision-check updated.pptx --json
xdoc pptx diff deck.pptx updated.pptx --json

# Review the actual rendered slides
xdoc pptx preview updated.pptx --output-dir updated-previews --contact-sheet --json

# Inspect the revision record or replay its patch
xdoc pptx audit --from-sidecar updated.pptx.xdoc.json --json
xdoc pptx replay --from-sidecar updated.pptx.xdoc.json --output replayed.pptx
```

默认的 `.xdoc.json` Sidecar记录物化补丁，运行时 识别，并申请报告。同时保留源牌组：重播现有牌组 编辑要求记录的输入保持可用。Sidecars包含修订 证据;新的检查和预览验证当前的表示。

## 为AI智能体构建

Xdoc公开了自己的操作、字段契约、示例、目录和特性 支持和报告格式。代理可以发现已安装的运行时， 检查甲板，构建补丁，干式运行，应用，并验证结果 在每一步使用机器可读的数据。你的代理提供内容， 翻译和设计决策；Xdoc执行文档工作。

```sh
# Discover patch operations, then ask for the exact fields you need
xdoc schema --mode index
xdoc schema --mode ops --ops add-chart,set-chart-data --minimal

# Explore built-in examples and the complete runtime contract
xdoc schema --mode examples
xdoc schema > runtime-schema.json

# Browse native PowerPoint shapes
xdoc pptx catalog shapes --json
```

这个 **0.12.2** 运行时暴露 **58种贴片操作，18种幻灯片配方， 182个预设形状，9个主题包和4个风格包**． 图表类型和高级 特性带有单独的支持状态。使用已安装的模式进行选择 支持操作和读取范围的部分或仅保留特性。

选择适合您的主机的进程接口：

| 接口 | 入口点 | 用它来 |
| --- | --- | --- |
| 命令行界面 | `xdoc pptx ... --json` | 本地脚本和单独的操作。 |
| 当地的守护进程 | `xdoc daemon start`,然后 `inspect`/`apply` 与 `--daemon` | 在内存中跨本地步骤保存解析过的deck会话。 |
| 它的json - rpc | `xdoc json-rpc` | 通过JSON-RPC 2.0管理持久子进程的主机。 |
| MCP在演播室 | `xdoc mcp` | MCP客户端发现模式、检查甲板和应用补丁。 |

对于接受的MCP客户端 `mcpServers` 配置:

```json
{
  "mcpServers": {
    "xdoc": {
      "command": "xdoc",
      "args": ["mcp"]
    }
  }
}
```

MCP适配器暴露 `xdoc_schema`， `pptx_inspect`, `pptx_apply`. 转换、预览和其他检查使用CLI。对于可重复的集成， 固定NPM版本并捕获可执行文件的模式。这个包暴露了 这个 `xdoc` 命令;处理参数、演播室协议和JSON报告表单 公共融合边界。

## 支持的平台上

| 操作系统 | 体系结构 | 二进制包 |
| --- | --- | --- |
| Linux | arm64 | `@s8fy/xdoc-linux-arm64` |
| Linux | x64 | `@s8fy/xdoc-linux-x64` |
| macOS 13或更新版本 | arm64（苹果芯片） | `@s8fy/xdoc-macos-arm64` |
| 窗户 | x64 | `@s8fy/xdoc-windows-x64` |

NPM选择包含本机可执行文件的精确版本平台包 和捆绑的PDFium后端。安装脚本不需要从文件下载二进制文件 外部发布服务器。不受支持的操作系统、体系结构或 macOS版本收到一个可操作的错误。

## 范围和兼容性

-   **当前的输入:** PPTX， PDF和HTML，加上JSON补丁，配方和数据 用于PPTX创作的绑定。DOCX和XLSX转换仍然保留。
-   **编辑保存：** 普通的PowerPoint对象具有本机编辑功能 路径。复杂动画、SmartArt等高级功能都有自己的 拥有支持、部分、仅保留或不支持的状态。
-   **渲染及评审：** 字体可用性和所选功能的影响 输出。静态检查、呈现预览和目标- office兼容性 报告回答不同的问题；检查呈现的结果以便交付。

## 免费模式和授权

免费模式提供了所有的核心功能 **单用户本地使用**，以…为 **每个任务10张幻灯片** 和 **5 MiB的压缩PPTX输入组合**. 可视输出，包括可编辑的PPTX、PDF和PNG，都带有a `structurify.io` 水印。启动不需要帐户或许可证凭证；任务超过 自由极限被否定了。

个人和企业许可证是离线授权，可以删除 计划级幻灯片/PPTX字节限制和新的计划水印。本地脚本和 每个用户守护进程都包含在启动计划中；CI、共享服务器和 服务/API的使用不在这些计划之内。

公共包使用 [PolyForm非商业许可证1.0.0](https://github.com/hustcer/workers/blob/main/xdoc-npm/LICENSE) 除非另行许可。运行时访问和合法使用权是分开的； 商业用途需要适用单独的条款。平台包也 保留捆绑的PDFium第三方许可通知。

## 支持和包维护

中报告安装、平台选择和启动程序问题 [`hustcer/xdoc-feedback` 问题跟踪器](https://github.com/hustcer/xdoc-feedback/issues). 对于本机运行时行为，请使用附带的上游支持通道 您的xdoc发行版或许可证。

这个目录维护npm的打包和发布自动化。本地版本 资产被固定到审查的SHA-256摘要中 [`release-lock.json`](https://github.com/hustcer/workers/blob/main/xdoc-npm/release-lock.json). 看到 [维护者发布过程](https://github.com/hustcer/workers/blob/main/xdoc-npm/CONTRIBUTING.md).

## 常见问题

### @s8fy/xdoc 是什么？

本地PowerPoint CLI和MCP服务器可编辑的PPTX，本地3D图表，JSON补丁，模板数据绑定，PDF/PNG导出和Markdown提取的RAG。

### 如何安装 @s8fy/xdoc？

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

### @s8fy/xdoc 支持 TypeScript 吗？

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

### @s8fy/xdoc 需要什么版本的 Node\.js？

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

### @s8fy/xdoc 可以商用吗？

@s8fy/xdoc 使用 PolyForm-Noncommercial-1\.0\.0 许可。声明的许可为 PolyForm-Noncommercial-1\.0\.0，请阅读许可原文确认使用条件。以上为概括，不构成法律意见，请以许可原文为准。

### @s8fy/xdoc 还在维护吗？

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