GenOffice 开源 AI 办公套件技术指南：Docs/Sheets/Slides/PDF 真格式编辑、genoffice CLI 与 MCP 智能体集成

• 人工智能
• AI 应用
• 桌面应用
• AI Agent
• MCP 服务
• AI 技能

GenOffice 是面向 macOS、Windows 与 Linux 的免费开源 AI 办公套件，直接打开、编辑并保存原生.docx、.xlsx、.pptx文件，同时支持 PDF、Markdown 与 HTML，并为每个文档内置一位 AI 智能体——它不是贴在侧边的聊天窗口，而是会读取文件、执行修改并精确展示改动内容的编辑器。本文以 docs/i18n/README.cs.md（捷克语官方 README）为主体，结合 packages/cli/README.md、skills/genoffice/SKILL.md 与 CONTRIBUTING.md 等仓库源码级资料，完整梳理其核心能力、CLI/Agent Skill/MCP 三种自动化接入方式、字节级保留的引擎原理与安装开发流程。读完本文，你将掌握如何在本地用 AI 编辑真实 Office 文件，以及如何让 Claude Code、Codex、Cursor 等编码智能体通过命令行或 MCP 协议在无窗口环境下创建、转换、读取和编辑这些文件。

项目定位：本地优先的开源 AI Office 套件

GenOffice 的核心承诺可以概括为四条：

• 真实格式、字节级保留。只有你编辑的内容会被重写，文件中其余部分按字节原样保留，因此文档在 Word、Excel、PowerPoint 中依然正常工作。
• AI 可审查。编辑以“修订/差异”形式呈现，支持一键回滚；表格写入的是活公式而非粘贴的数字；演示文稿与网页直接生成到画布上，保持完全可编辑。
• 本地是设计原则。文件在本机完成打开、编辑、保存与转换；PDF → Word/Excel/PowerPoint、Markdown → Word、HTML → Word 全部在设备端执行。离开机器的只有 AI 调用，且发往你自己选择的提供商。
• 脚本化且面向智能体。应用内置genoffice命令行与 Agent Skill，编码智能体可以在不打开任何窗口的情况下创建、转换、读取和编辑真实 Office 文件。

六个编辑器 + 一个 AI 面板

• Docs（.docx）：按 Word 的排版还原文件——双栏章节、通栏图片、着色表格、页眉页脚、基于 Word 行距度量的分页；样式、批注、修订、公式与墨迹笔记原样往返。AI 只读取需要的块，改写段落并插入新章节，每个 AI 回合都是可回滚的快照；开启“修订”后编辑以 Word 风格修订呈现。
• Sheets（.xlsx）：AI 用真实SUMIF公式按地区与类别新增 Summary 表，插入柱状图，43 处改动作为一个可撤销批次一次应用；对工作簿提问会返回推理过程与可点击引用的具体单元格。底层是自研 Rust.xlsx引擎（见 apps/sheets/native/xlsx-engine）、数据透视表、切片器、条件格式与公式追踪。
• Slides（.pptx）：一句话输入——“为 Aurora Home 创建 10 页投资人演示文稿”——AI 规划叙事线、核实数据并把每张幻灯片草绘为真实.pptx；输出保持统一的字体排印、图片与行动号召，可继续用母版、版式、智能参考线和非破坏性裁剪编辑。
• PDF：就地编辑模式为每个文本块描边，直接输入替换；内容流经 PDFium 以原始字体重写，而非覆盖式批注。PDF Converter → PDF to Word在设备端产出可编辑.docx，标题、统计行与段落完整；Excel 与 PowerPoint 目标同理，扫描页走系统 OCR。
• HTML：先由 AI 提出设计简报（钩子、调色板、字体排印与风格方向），再据此生成单个自包含.html文件；一次Restyle请求即可交换简报令牌令整页换风格，所有章节与文案原样保留。内置“个人仪表盘”“数据报告”等起始模板，可导出 PDF 或原生可编辑 Word 文档。
• Markdown：基于纯.md的 Tiptap 块编辑器，渲染标题、列表、表格、图片、代码块与 Mermaid 图，写回仍是干净.md；选中任意段落出现Ask AI芯片，可输入指令或选建议（润色、精简、扩写、修语法），立即发送或排入队列批量执行。该入口在每款应用中一致存在。

AI 后端：登录 Genspark 或自带密钥

通过 Genspark 登录则无需任何配置：模型调用经由 Genspark 代理（Claude、GPT、Gemini 系列），智能体自动获得网页与图片搜索、图片生成、图片/音频/视频分析能力。

或使用自带密钥。设置 → AI 提供 Claude、OpenAI、Gemini、DeepSeek、Kimi、GLM、Qwen、Doubao、MiniMax、Grok、Mistral、OpenRouter、Requesty 以及 OpenCode Zen/Go；另有自定义槽位可填任意 OpenAI 兼容 endpoint（base URL + 密钥），包括本地模型服务器。搜索与媒体能力在AI Media & Search下按能力独立配置：网页搜索可选 Serper 或 Tavily；图片、图片生成与图片/视频分析可选 OpenAI、Gemini、Doubao/Seedream、GLM、Grok、Qwen、MiniMax 或任意 OpenAI 兼容 endpoint。

整套套件提供浅色、深色与跟随系统三种外观。外观只改变屏幕显示，导出、打印与保存的文件始终保留文档自身的颜色——这一约束在 CLAUDE.md 中被列为强制主题规则：文档内容（页面底色、单元格填充、幻灯片内容、PDF 页位图、导出/打印样式表等）永不随主题重写。

genoffice 命令行与 Agent Skill

应用在图形界面之外能对文件做的一切，genoffice命令行在终端里都能做：查看、转换、创建、读取和编辑 Word、Excel、PowerPoint、PDF、Markdown 与 HTML，使用与图形界面相同的引擎，无图形界面。它随 GenOffice 一起安装，不需要独立运行时，并且从不把任何文档发送到任何地方。配合随附的Agent Skill，可以把编码智能体变成“文档工作者”，产出真实 Office 文件而非 Markdown 仿制品。

开箱即用支持：Claude Code、Codex、Cursor、Gemini CLI、GitHub Copilot、OpenCode 与 Windsurf；任何能读取 skill 的智能体均可，通过 MCP 服务器还可服务 Claude Desktop 与任意 MCP 客户端。

Skill 安装的三种方式

安装后开启新会话并索要文档即可。skill 会教智能体何时调用genoffice、编辑前如何读取文件、以及如何自查工作。当前仓库中的 skill 定义位于 skills/genoffice/SKILL.md（version: 2.51.0，要求cli >= 0.9.0）。

终端快速开始

genoffice --version genoffice info report.docx --json # 标题与块结构；sheets/slides/pages 同理 genoffice convert report.md --to pdf # md/html/docx/xlsx/pptx → pdf，pdf → docx/xlsx/pptx，… genoffice create --type docx --from notes.md --out notes.docx genoffice create --type xlsx --from table.json --out sales.xlsx # "=SUM(B2:B9)" 单元格保持活公式 genoffice docs read report.docx --range 0-9 --json # 然后 `docs apply --ops edits.json` 原地编辑 genoffice render report.docx --out shots/ # 每页一张 PNG，用来查看产出 genoffice open sales.xlsx # 把结果交给编辑器

每个命令默认输出一行人类可读摘要，加--json则输出单个 JSON 对象。编辑是原子的：被拒绝的操作会让文件保持原样，并返回带指引的错误信息。genoffice help列出当前命令集；完整参考在 packages/cli/README.md。

智能体实际执行的流程：从一句话到八页演示文稿

前文“太阳系演示文稿”示例正是由 Claude Code 中的单一 prompt 生成的。智能体按 skill 中的分阶段工作流推进，CLI 在每一阶段开始前完成校验：

genoffice capabilities --json # GenOffice 配置了哪些云工具 genoffice guide slides design # 演示文稿工作流与版式库 genoffice image "the eight planets in a row …" --aspect 16:9 --out deck/assets/cover.jpg genoffice slides check deck/outline.json --json # 8 页，无问题 genoffice slides check deck/pages/01.json --json # 构建一页并审计溢出与重叠 … # 每张幻灯片一个页面文件，直到每项检查干净 genoffice create --type pptx --spec deck/pages --outline deck/outline.json --out deck/solar-system.pptx --json genoffice slides render deck/solar-system.pptx --out deck/shots --json genoffice slides audit deck/solar-system.pptx --json # 8 张幻灯片，无版式问题 genoffice slides replace deck/solar-system.pptx --slide 4 --spec deck/pages/05.json --json genoffice open deck/solar-system.pptx

genoffice内部不发起任何模型调用：智能体负责思考，CLI 负责构建与校验，结果作为普通.pptx在 GenOffice 或 PowerPoint 中打开。智能体驱动的演示文稿设计全流程（guide slides design→style.md+outline.json→ 逐页slides check→create --spec→render --grid→slides audit）在 skills/genoffice/SKILL.md 中有完整分步说明。

CLI 输出契约与错误处理

程序化调用请始终加--json：stdout 上是单个 JSON 对象，成功为{ "status": "ok" | "partial", "command", "summary", "output_path"?, "warnings"?, "detail"? }，失败为{ "status": "error", "code", "error", "message", "suggestion"?, "detail"? }。退出码：0成功、1用法错误或操作被拒、2文件不存在/输出已存在/文件正在 GenOffice 中打开、3转换失败、4应用不可用。error是稳定的机器可读原因（unknown_op、target_not_found、out_of_range、sheet_not_found、file_open_in_gui等），suggestion给出下一步（对一字之差会提示did you mean "…"?），detail以字段形式携带重试所需事实（可用 id、有效范围、工作表名、用法行）——规范要求永远不要解析message。成功结果仍可能携带warnings[]（如formulas_not_cached、images_dropped、output_renamed），应按其提示处理而非重试。

apply默认原子：一批操作中任何一个被拒，整个批次不写入。--best-effort/--stop-on-error会写入已应用部分并返回status: "partial"（退出码 0），因此程序必须检查status而非仅看退出码。完整的“哪个命令处理哪种任务”对照表与逐错误恢复建议见 skills/genoffice/SKILL.md。

环境变量与安全边界

• GENOFFICE_ALLOWED_ROOTS（PATH 风格目录列表）：把genoffice的读写限制在指定目录树内，符号链接会在检查前解析，越界退出码 2。
• GENOFFICE_AUDIT_LOG=<path>重定向审计日志（默认~/.genoffice/cli-audit.jsonl，每条命令追加一行 JSON，2 MB 轮转），off则禁用。
• GENOFFICE_USER_DATA指向非默认 GenOffice 配置目录（打开文档注册表、AI 设置）。
• GENOFFICE_APP_BIN指定可执行文件（PDF 与 HTML 相关转换需要 GenOffice 应用或其无头导出模式）。
• 唯一把数据发出机器的命令是search、image、media，且仅发往 GenOffice 中配置的提供商（~/.genoffice/auth.json与 AI 设置中的 provider 路由）。

MCP 服务器：Model Context Protocol 接入

同一批命令也可作为 Model Context Protocol 工具提供给无法运行终端、或你不想授予终端权限的助手。两条路径均可在设置 → 集成 → MCP找到即拷即用的配置片段：

# Claude Code claude mcp add --transport stdio genoffice -- genoffice mcp

// Cursor、Claude Desktop 或任意 MCP 客户端 { "mcpServers": { "genoffice": { "command": "genoffice", "args": ["mcp"] } } }

此处的genoffice是应用内置的 CLI（macOS 位于/Applications/GenOffice.app/Contents/Resources/cli/genoffice；设置面板会列出你安装的具体路径）。服务器自带工作流指令，并以genoffice://guide/*资源暴露操作参考，因此无需 skill；skill 与 MCP 服务器可以共存，助手任选其一。云功能（search、image、media）仍走 GenOffice 中配置的提供商，其余全部本地运行，GENOFFICE_ALLOWED_ROOTS把每个工具限制在你指定的目录内。反向代理场景下可设GENOFFICE_TRUST_PROXY_HEADERS=1；genoffice mcp --http <port> [--host <addr>] [--token <secret>]则对跨机器客户端提供 Streamable HTTP，文件随调用以PUT /files/<name>上传并返回 URL。

上文中“可再生能源”演示文稿，就是只连接genofficeMCP 服务器的 Claude Code 在一次 prompt 下的真实协议轨迹：

capabilities · guide(slides, spec) · guide(slides, design) search(query) ×4 → IEA、BNEF 与 IRENA 数据 search(query, images) ×7 · media(url, ask) ×7 → 候选图片，每一张都经 media 确认为真实照片 deck_start(dir, style, outline) → 大纲通过检查：需写 8 页 deck_page(dir, 0, page) … deck_page(dir, 7, page) → 每页对照大纲与调色板校验；其中一页重新提交 deck_build(dir, out) → renewables-2026.pptx，无图片失败 slides_audit(file) · slides_render(file, out) → 无版式问题；8 张 PNG 以图片内容返回 deck_replace(dir, n, page) ×3 · slides_render(file, out) → 查看渲染图后修复三页

38 次工具调用、约 13 分钟，助手全程未触碰 shell：图片、照片核查、指南、校验与渲染全部以 MCP 工具调用结果的形式往返。只有search与media离开本机，发往 GenOffice 中配置的提供商。

下图展示了 CLI 工作流的产物——八页太阳系演示文稿在 GenOffice Slides 中打开，左侧缩略图条与 AI 面板清晰可见：

下载与安装

所有构建产物均出自main分支；macOS 与 Windows 安装器已签名。Linux 安装示例：

# Debian / Ubuntu：apt 安装，自动拉取依赖并加入应用菜单 sudo apt install ./genoffice_<version>_amd64.deb # Fedora / RHEL 系 / openSUSE：改用 rpm sudo dnf install ./genoffice-<version>.x86_64.rpm # Fedora / RHEL 系 sudo zypper install ./genoffice-<version>.x86_64.rpm # openSUSE # AppImage：就地运行，先装 FUSE 2 运行时 sudo apt install libfuse2 # Ubuntu 24.04 的包名是 libfuse2t64 chmod +x GenOffice-<version>.AppImage ./GenOffice-<version>.AppImage

工作原理：字节级保留的引擎架构

七个 Electron 应用（Docs、Sheets、Slides、PDF、Markdown、HTML 与标签式 shell）共享同一层由纯 TypeScript 包组成的引擎，外加为.xlsx准备的 Rust sidecar。原始文件永远是事实来源：编辑以窄补丁的形式应用，编辑器未触及的一切在保存后原样存活。

open docx ─► 按哈希归档原始文件（永不触碰） ─► 解析 word/document.xml 为块树，每个块锚定到其原始 XML ─► Tiptap 编辑器（手动 + AI 编辑，脏追踪） save ─► 脏块 → OOXML 片段（仅引用已有样式） ─► 拼回原始 document.xml；未触碰的块保留其原始字节 ─► 重新打包 zip；其余每个条目逐字节复制

这套哲学同样适用于 sheets 与 slides。逐包导览（docx/pptx 引擎、pdf2docx、html2docx、agent 核心与提供商）见 CONTRIBUTING.md：packages/docx-engine负责 docx 解析为块树、OOXML 片段生成与字节级段落补丁；packages/pptx-engine/packages/pptx-render负责 pptx 模型与渲染；packages/pdf2docx通过 PDFium 字符级提取与纯几何版式分析实现本地 PDF → DOCX，同一分析还驱动 PDF 应用的 PowerPoint/Excel 导出；packages/html2docx在应用自带 Chromium 中渲染页面、归约为文档意图树并写成原生 OOXML；另有 packages/agent-core、packages/ai-provider、packages/ai-search 构成 AI 侧基础。

genofficeCLI 本身位于 packages/cli，运行在应用自带 Node 运行时上（ELECTRON_RUN_AS_NODE），无需额外安装；Word/Markdown 命令经 jsdom 引导（packages/cli/README.md 中的src/dom.ts），工作簿写入走@genoffice/xlsx-gateway即应用保存路径，写公式后用 xlsx sidecar 求值并缓存结果，因此sheet read与普通阅读器看到的是数值而非空值。

开发与构建

npm install npm run fixtures # 生成测试用 .docx fixtures npm test # 引擎 + 应用单元测试（docs/sheets/slides 无需显示器） npm run typecheck # 全工作区 tsc --noEmit npm run dev # 六个编辑器 + shell 对 Vite dev server npm run dev:docs # 单独运行一个应用（每个工作区同模式） npm run dist:mac # 打包 macOS dmg（会重新生成第三方声明） npm run dist:win # 打包 Windows nsis 安装器 npm run dist:linux # 打包 Linux AppImage + deb + rpm

sheets 应用额外需要 Rust 工具链（cargo在 PATH 上）来编译 xlsx sidecar；npm run build -w @genoffice/sheets会自动编译。必须通过的检查（format:check、lint、typecheck、test、licenses）与 PR 合入流程见 CONTRIBUTING.md。

常见问题

• GenOffice 免费吗？是。Apache-2.0 开源，无试用期，应用本身无付费档位。
• 能打开 Microsoft Word/Excel/PowerPoint 文件吗？能，原生打开并保存.docx、.xlsx、.pptx；保存字节保留，未触及部分原样写回，文档在 Microsoft Office 中照常工作。
• 离线可用吗？文档编辑完全本地，打开、编辑、保存与转换都不离开电脑。AI 功能（智能体、搜索、图片工具）需要网络，经 Genspark 登录或自带模型 API 密钥。
• 能编辑 PDF 吗？能——真正的文本与图片就地编辑，重写页面内容流并保留原始字体，而非覆盖式批注。
• 能把 PDF 转成 Word/Excel/PowerPoint 吗？能，完全设备端：PDFium 字符级提取 + 基于几何的版式分析，无云服务、无上传；扫描页在 macOS/Windows 上经系统 OCR 转为可编辑文本。
• 能用自有 AI 模型或 API 密钥吗？能。除无密钥的 Genspark 登录外，支持 Claude、OpenAI、Gemini、DeepSeek、Kimi、GLM、Qwen、Doubao、MiniMax、Grok、Mistral、OpenRouter、Requesty、OpenCode Zen/Go 以及任意 OpenAI 兼容 endpoint（含本地服务器）；搜索、图片生成与图片/视频分析在 设置 → AI Media & Search 下单独配置密钥。
• 能把 HTML 转成 Word 吗？能——HTML 应用中的Export as Word在设备端生成原生可编辑.docx：页面在自带 Chromium 中渲染，归约为真实 Word 结构（标题、段落、列表、表格、选项卡、KPI 行、表单字段、页面背景）；无 Word 对应物的纯视觉元素（图表、图标、装饰框）以图片插入。
• 能从 Claude Code、Codex、Cursor 或脚本控制 GenOffice 吗？能。genoffice命令行以无图形界面方式运行同一批引擎：从终端或脚本查看、转换、创建、读取与编辑文档，支持--json输出；随附 Agent Skill 教 Claude Code、Codex、Cursor、Gemini CLI、GitHub Copilot、OpenCode、Windsurf 如何使用它，在设置 → 集成安装。
• GenOffice 收集数据吗？官方打包版本默认发送有限的使用分析，可在 设置 → 常规 随时关闭；分析从不发送文档内容、文件名、文件路径、账户身份或邮箱。完整事件清单与数据披露见 PRIVACY.md。

安全、许可与致谢

进程级安全立场（renderer 沙箱、IPC 校验、外部链接过滤）与 AI 生成内容的威胁模型见 SECURITY.md。GenOffice 以 Apache License 2.0 授权，唯ee/目录保留给未来企业模块，适用 GenOffice Enterprise License；Apache-2.0 授权不包含使用 GenOffice/Genspark 名称与标识的许可，fork 应使用自有品牌。其核心组件来自多个开源项目：Electron 运行时、Univer（Sheets UI 内核，Apache-2.0）、PDFium（PDF 内容流引擎，经 @embedpdf/pdfium 打包）、pdf.js 与 pdf-lib（PDF 渲染与组装）、Tiptap/ProseMirror（Docs 与 Markdown 块编辑器）、CodeMirror（HTML 源码视图）、Konva（Slides 画布与 Sheets 图表）、HarfBuzz wasm（复杂字体文本整形度量）、calamine 与 IronCalc（Rust xlsx sidecar 的读取与计算层）、libeot（PowerPoint 嵌入字体的 MicroType Express 解码，已移植到 TypeScript）、React、Mermaid 与 KaTeX（Markdown/Docs 的图表与数学）、opentype.js、JSZip 与 fast-xml-parser（OOXML 容器与 XML）、Fluent UI System Icons、electron-updater，以及随附的 Liberation/Carlito/Caladea/Noto CJK 字体。npm run notices可重新生成第三方许可证汇总（tools/gen-third-party-notices.mjs），全部运行时依赖均在 MIT/Apache-2.0/BSD-3-Clause/OFL 许可白名单内。

• 人工智能
• AI 应用
• 桌面应用
• AI Agent
• MCP 服务
• AI 技能