genoffice

genoffice — 在终端中使用 GenOffice

genoffice 随 GenOffice 一同安装。先运行 genoffice --version。如果找不到该命令，GenOffice 每次启动时都会将启动器目录写入 ~/.genoffice/launcher（Windows：%USERPROFILE%\.genoffice\launcher）；读取该文件中的一行内容，然后在 bash 中运行 "<dir>/genoffice"，或在 PowerShell / cmd 中运行 "<dir>\genoffice.cmd"（均需加引号），以替代下文中的 genoffice。该文件不存在时的默认位置：macOS /Applications/GenOffice.app/Contents/Resources/cli、Windows %LOCALAPPDATA%\Programs\GenOffice\resources\cli、Linux /opt/GenOffice/resources/cli。所有命令都在应用自身的引擎上以无头模式运行；只有 search、image 和 media 会将数据发送到机器外部，发送给 GenOffice 中配置的提供方。

程序读取输出时，始终添加 --json：stdout 上会输出一个 JSON 对象，格式为 { "status": "ok" | "partial", "command", "summary", "output_path"?, "warnings"?, "detail"? }（partial：apply 使用 --best-effort / --stop-on-error 后写入了文件，但有操作未成功）或 { "status": "error", "code", "error", "message", "suggestion"?, "detail"? }。退出代码：0 成功，1 用法错误或操作被拒绝，2 文件不存在 / 输出文件已存在 / 文件在 GenOffice 中打开，3 转换失败，4 应用不可用。error 是机器可读的原因（参见“命令失败时”下的表格）；suggestion 是一句话形式的下一步建议；如果命令、选项、操作名称、元素 ID 或工作表名称只差一个拼写错误，还会包含 did you mean "…"?。detail 包含字段形式的事实（failures[]，其中含有 index、op、error、reason、valid_range、available、supported、usage；以及 sheets、options、commands）；切勿解析 message。

命令

命令	功能
genoffice info <file> [--password <pw>]	元数据和结构摘要（docx 块和标题、pptx 幻灯片、xlsx 工作表、pdf 页面）
genoffice convert <file> --to <fmt> [--out <path>] [--force]	pdf→docx/pptx/xlsx、csv→xlsx、xls/xlsb/ods→xlsx、md→docx/html、docx→html/md、html→docx、xlsx→csv（--sheet），以及 docx/xlsx/pptx/md/html→pdf
genoffice create --type pptx --ops <file> --out <path>	根据幻灯片操作列表创建新演示文稿
genoffice create --type pptx --spec <dir|file> [--outline <file>] --out <path> [--render [dir]] [--audit]	根据页面规格文件（每张幻灯片一个，按名称排序）或单个演示文稿规格文件创建新演示文稿：包含按 px 定位的文本、形状和图像（设计型演示文稿路径，见下文）
genoffice create --type xlsx --from <data.csv | table.json> [--header] [--decimal ,] --out <path>	根据 CSV 或二维数组 / {sheets:[{name,rows}]} 创建新工作簿；"=..." 单元格为公式；--header 冻结第 1 行并为区域添加筛选器
genoffice create --type docx --from <text.md | fragment.html> --out <path>	根据 Markdown 或受限的 HTML 片段创建新的 Word 文档
genoffice create --type pdf --from <document> --out <path>	使用 GenOffice 渲染器将任意 md/html/docx/xlsx/pptx 文件打印为 PDF
genoffice slides read <pptx> [--slide n] [--full | --max-chars n] [--layouts] [--units in|cm|pt|px] / genoffice slides apply <pptx> --ops <file> [--dry-run]	检查 ID、几何信息（box 和 size 以 EMU 为单位，或在指定 --units 时按所命名单位转换）和文本预览（截断至 300 个字符，以 …(+n chars) 结尾，并带有 truncated: true；--max-chars 可调整上限，--full：完整文本、所有表格行、演讲者备注），然后使用 ops 编辑。文本元素包含 effective（第一个 run 的字体大小 / 字体系列 / 颜色 / 粗体 / 斜体和段落对齐方式），以及用于标明每个值来源的 src：run、paragraph defRPr、shape lstStyle、layout placeholder、master placeholder、master titleStyle/bodyStyle、presentation defaultTextStyle、theme major/minor；setFont 会写入 run 级别并覆盖以上所有设置，applyTheme 会更改主题字体和颜色。包含超链接的元素带有 link（url、幻灯片跳转或 PowerPoint action：nextslide / previousslide / firstslide / lastslide / lastslideviewed / endshow）；setLink 和 setText 的 run link 字段会写入相同的三种类型。
genoffice slides audit <pptx> [--slide n] / genoffice slides render <pptx> --out <dir> [--scale 2]	几何审计（out_of_bounds、off_slide、text_overflow、text_overflow_width、overlap、picture_distorted = 框的宽高比与裁剪后源图的宽高比相差超过 5%）：issues[] 包含 code、level、path（s_n/e_*），除 overlap 外还包含 suggest setTransform op，可直接传给 slides apply；每张幻灯片生成一张 PNG 供查看
genoffice render <file> --out <dir> [--page n] [--scale 2] [--el e_12 [--pad px]] [--grid [--cols 4] [--tile 320]]	使用 GenOffice 渲染器为 docx、xlsx、pptx、md、html 或 pdf 文件的每页生成一张 PNG：在报告文档或工作簿已完成之前先查看渲染结果；--el（pptx）还会将页面裁剪到单个元素（<stem>-NN-e_12.png，ID 来自 slides read），使小框内容清晰可读；--grid 还会将每页放到一张联系表中（<stem>-grid.png，按行排列，图块位置见 grid.tiles），以便一次查看整个演示文稿
genoffice slides check <outline.json|page.json> / genoffice slides replace <pptx> --slide n --spec <page.json>	验证演示文稿大纲（出错时退出码为 1），或构建并审计一个页面文件，并根据其大纲条目和 style.md 检查该页面；根据页面文件重建一张幻灯片，其他幻灯片保持不变
genoffice sheet read <xlsx> [--sheet name] [--range A1:D20] [--cols A,C:E] [--max-rows n] [--where formula|error|empty|number|text] [--stats] [--formats] / genoffice sheet apply <xlsx> --ops <file> | --cells <file> / genoffice sheet check <xlsx>	读取一个区域及其 features（工作表的窗格、筛选器、图表、表格和规则数量；区域内的合并单元格和链接；--formats 会添加单元格格式、列宽和行高）；使用 --cols（仅显示指定列，列名列在 columns 中）、--max-rows（显示 rowsShown / rowsTotal，并在 note 中给出用于继续读取的 --range）、--where（仅显示一种类型的单元格，格式为 {ref, value, formula}，不显示网格）或 --stats（计数、已用区域和工作表列表，不显示单元格）控制输出大小；使用工作簿 DSL 或单元格地址进行编辑；check 会列出公式错误、引用缺失工作表的情况、失效的定义名称、超出数据范围的图表区域、### 列（并提供 set_col_width 建议）、占位文本和现有规则
genoffice docs read <docx> [--range a-b] [--html] [--full \ / genoffice docs compare <original.docx> <revised.docx> --out <redline.docx> [--author name] [--date ] [--granularity word	char] [--ignore formatting,case,whitespace]`
genoffice merge <template.docx|pptx|xlsx> --data <values.json | inline JSON> --out <path> [--force] [--strict]	使用引擎自身的查找 / 替换功能（Word、PowerPoint：文本、表格、演讲者备注）和类型化的 set_cell 写入（Excel：整单元格占位符会采用值的类型，数字保持为数字；替换后的文本即使以 = 开头也仍是文本），根据 JSON 对象填充 Word、PowerPoint 或 Excel 模板中的 {{key}} 占位符（嵌套对象会展平为点分隔的键 a.b；花括号内允许空格）。detail.used_keys、detail.unused_keys 和 detail.unresolved_placeholders[]（{placeholder, key, reason: no_key | split_placeholder | unreachable_nested, location} — 块索引 / 幻灯片 + 元素 ID / 工作表 + 单元格）会说明处理结果；未解决的占位符会保留原样，并附带 unresolved_placeholder 警告，除非 --strict 将其视为错误。split_placeholder = Word 将 {{…}} 拆分到格式不同的多个 run 中；请在模板中将其重新输入到单个 run 中（PowerPoint 可以填充跨多个 run 的占位符）。unreachable_nested = 位于嵌套的 pptx 组（或组内表格）中，而演示文稿的 findReplace 无法访问该位置；请取消组合。未填充内容的 Word 表格会保持不变
genoffice pdf read <pdf> [--page n | --range a-b] [--password <pw>] [--full | --max-chars n]	逐页读取 PDF 的文本层：page 从 1 开始，提供 width_pt / height_pt、截断至 4000 个字符且以 …(+n chars) 结尾的 text，并带有 truncated: true（--max-chars 可调整上限，--full 可取消上限并读取每一页），以及页数、encrypted 和标题 / 作者 / 制作程序元数据；未指定 --page / --range 时会返回前 20 页，其余页数列在 detail.truncated 中；扫描页的文本为空（convert --to docx 会执行 OCR）
genoffice guide <slides|docs|sheets> [group|op|design|spec] [--json] [--index] [--fingerprint]	每个领域的 op 参考，由与 apply 验证所用的相同定义生成（编写 ops 前请先阅读）；按需查看一个组或一个 op 及其 JSON 架构；slides design / slides spec 用于创建演示文稿
genoffice search <query> [--images] [--max n]	通过 GenOffice 中配置的提供商搜索网页 / 图像；detail.results[] 为 {title,url,snippet}
genoffice image <prompt> [--out f.png] [--aspect 16:9] [--ref a.png,b.png] [--model <name>]	使用已配置的提供商生成图像并保存；detail.mime、output_path
genoffice media <file|url> [--ask <question>]	描述图像、视频或音频文件，或针对其提问；答案位于 summary 和 detail.text 中
genoffice capabilities	查看 GenOffice 中配置了哪些云功能（搜索、图像搜索、图像生成、媒体分析），以及应用是否已安装；不会进行网络调用
genoffice open <file> [--slide n [--el e_12] | --block n | --range [Sheet!]B2:D5 | --page n]	在 GenOffice 应用中打开文件（仅当用户要求在应用中查看时）；指定目标后，还会滚动到该幻灯片元素 / 块 / 区域 / 页面并选中它，使用户看到与当前相同的位置（若无法找到目标或目标超出范围，则会返回 target_not_found / out_of_range 以及有效的 ID 或区域）
genoffice selection <file> --json	查看用户在显示该文件的编辑器中选中的内容：{slide, elements[], types[]}、{blocks:[a,b], text, collapsed}、{sheet, range, values?} 或 {page, text?}；编辑前先据此解析“这个” / “这里”所指的内容；若没有标签页显示该文件，则返回 file_not_open_in_gui
genoffice skill list / genoffice skill install <agent|all> [--dir <path>] [--force] / genoffice skill path	列出此机器上找到的编码 Agent（Claude Code、Codex、Cursor、Gemini CLI、Copilot、OpenCode、Windsurf）及其各自拥有的技能版本；将此技能复制或更新到它们的技能目录，或打印随附的 SKILL.md；除非运行此命令或在 Settings → Integrations 中点击，否则不会安装任何内容
--ops - 和 --cells - 从标准输入读取内容。--out 默认为输入文件所在文件夹，并使用新扩展名（convert）；也可以原地编辑（apply）。未知选项会被拒绝（退出码为 1）。默认情况下，mcp 服务通过 stdio 运行；mcp [--http <port> [--host <addr>] [--token <secret>]] 则提供 Streamable HTTP 服务；`genoffice mcp install <agent	all> [--dir ] [--force] 会在编码 Agent 的 MCP 配置中注册 stdio 服务（mcp uninstall 会将其移除，mcp list` 会显示每个 Agent）。

genoffice mcp 作为 MCP 客户端时可见的内容：

• 工具与命令一一对应（info、convert、create_docx / create_xlsx / create_pptx / create_pdf、docs_read / docs_apply / docs_check、sheet_read / sheet_apply / sheet_check、slides_read / slides_apply / slides_audit / slides_render / slides_check / slides_replace、render、guide、capabilities、search、image、media、open、selection）；ops、cells、specs 和 Markdown 会内联传递，结果采用 --json 信封格式（部分批次不属于 isError，其第一个文本块会列出丢失的 ops）；open 和 selection 仅在 stdio 模式下可用。
• deck_start / deck_page / deck_build / deck_replace 是上述分阶段的演示文稿流程，以演示文稿文件夹作为状态存储；内容明确的短演示文稿只需调用一次 create_pptx。
• op 参考资料作为资源提供：genoffice://guide/docs、…/sheets、…/slides、…/slides/design、…/slides/spec。
• ops、cells 和 data 携带 guide <domain> --json 中定义的每个 op 的架构（每个 op 对应一个变体：op、字段、必填项）；对于上下文预算较小的客户端，mcp --compact-schemas（或 GENOFFICE_MCP_COMPACT_SCHEMAS=1）会提供普通数组。
• --http：文件随调用传输（PUT /files/<name> 上传文件并返回 URL，每个路径参数也接受 http(s) URL，省略 out 时会返回文件的下载 URL）。
• GenOffice 应用会在 127.0.0.1:3093 上运行自己的 MCP 服务（Settings → Integrations）。其工具（create_session、read_document、apply_ops、apply_slide_ops、apply_sheet_ops、read_pdf、open_documents）会编辑可见编辑器中已打开的文档；genoffice mcp 则处理磁盘上的文件。

使用哪个命令

任务	命令路径	不适用于
根据简报制作演示文稿，无论简报多短	guide slides design → style.md + outline.json → 每页执行 slides check → create --type pptx --spec → render --grid → slides audit	编辑现有演示文稿（slides apply）；样例演示文稿（create --type pptx --ops）
修改现有演示文稿中的文本、图片或单张幻灯片	slides read → slides apply --ops → slides audit → render --page	重新设计整个演示文稿（applyTheme 操作，或通过分阶段路径重建）
根据数据创建工作簿	create --type xlsx --from data.csv | table.json → 使用 sheet apply --ops 设置格式／图表 → sheet check	修复现有文件中的单元格（sheet apply --cells）
编辑现有工作簿的单元格、格式、图表、规则	sheet read → guide sheets <op> → sheet apply --ops → sheet check	refresh_pivot、会话表格和形状（已拒绝：需要使用编辑器）
根据文本创建 Word 文档	create --type docx --from report.md | fragment.html → docs check → render	真正的网页（convert page.html --to docx）
编辑现有 Word 文档	docs read → docs apply --ops → docs check	读取其文本（convert --to md 或 docs read --full）
将用户的文件作为源材料读取	convert --to md/csv 或 <domain> read --full --json	对 Office 文件使用 unzip／cat；render（获取像素，而非文本）
更改文件格式	convert <file> --to <fmt>	更改任何内容（先编辑，再转换）
查看页面的外观	render（--page、--el、--grid）	提取文本或 ID（read）
指示用户查看某个位置，或处理用户选中的内容	open <file> --slide/--el/--block/--range/--page → selection <file> --json	读取内容（read）；用户尚未打开的文件（selection 需要对应标签页）
查找操作字段	guide <domain> [group|op] [--json]	根据此文件猜测：指南由验证器生成，始终保持最新
为其他 Agent（或新机器）提供此技能	skill list → skill install <agent>（或使用 skill path 并复制文件）	手动编写技能；install-cli（该命令会将 genoffice 添加到 PATH）

Behaviour to know

• Word (docs)：同一批次中的块索引会实时变化——insert_content 添加两个块后，后续索引会偏移 2。目标未匹配到任何块时，整个批次都会失败（退出码为 1）。findReplace 不会处理表格单元格（请对表格使用 replace_blocks）。受限集合之外的标签会被静默剥除。convert docx→md 会写入 GFM：& < > 会转换为实体，公式会转换为 $…$，图像会被丢弃并计入 detail.skipped。create --from x.md 会嵌入通过相对路径引用的本地图像。insert_image 接受本地路径（先相对于当前目录解析，再相对于 ops 文件解析）、data: URL 或 http(s) URL（png/jpg/gif），并会追加图像，除非指定了 afterBlockIndex；edit_chart 的目标是 docs read 列出的 kind 为 chart 的块；set_header_footer 会写入纯文本，并支持 {PAGE} / {NUMPAGES} 标记，view: "first" 会启用首页不同设置；评论 ID 来自 docs read --comments；add_comment 会将新讨论串锚定到一个块，或锚定到块内精确的 text 片段（occurrence 用于从多个匹配项中选择），且不会修改文档文本；对于带回复的讨论串根评论，使用 delete_comment 时需要设置 withReplies: true；修订 ID（r1、r2 等）来自 docs read --revisions，且按位置确定，因此每次编辑后，在执行 accept_changes / reject_changes 前都要重新读取。insertField 会在本地计算 SEQ 编号、REF 文本、DATE 和 MERGEFIELD；PAGE / NUMPAGES / AUTHOR 等样式的结果是占位符，由 Word 在打开时重新计算（docs check 会将其报告为信息），因此交付文件时请说明这一点。edit_note / delete_note 使用的注释 ID 来自 docs read --notes；edit_note 是在单条注释内执行 findReplace（{ id, find, replace, matchCase? }，仅当脚注和尾注共享同一 ID 时才需要 kind），并会保留注释的 ID、引用标记和格式——findReplace 本身不会处理注释文本。define_style 只会修改给定字段（已有样式的其他字段会保留）；applyStyle 使用 docs read --styles 中的段落样式 ID；如果该样式是标题样式，则会将块转换为标题；将 text: null 传给 set_watermark 会移除水印；insert_picture / insert_text_box 的长度接受 2.54cm / 1in / 72pt / 96px 或点数。set_page_setup 会修改每个分节或单个分节（section: N 或 blockIndex）的纸张 / 方向 / 页边距 / 分栏 / titlePg / 页码设置，长度格式为 "2.54cm" / "1in" / "72pt"；insert_section_break 会在一个块后拆分分节（之后可通过 set_page_setup section: N 修改副本）；docs read --sections 会列出各分节及其块范围。原生表格支持结构操作：insertTableRow / deleteTableRow / insertTableColumn / deleteTableColumn（从 0 开始，position: "before"|"after"，count）、mergeTableCells / splitTableCell（网格 range / cell；如果合并操作会截断现有合并单元格，则会被拒绝）、setTableCellFormat（填充、vAlign、边框、以缇为单位或 "2.5cm" 的 width）、setTableStyle（来自 docs read 的 tableStyles 的样式 ID，以及外观标志）；使用 nodeType: "table" 指定目标，docs read 会显示每个表格的 rows、cols 和合并的单元格。
• Excel (sheet)：操作会按顺序运行，每项操作都会使用前一项操作的结果：执行 insert_rows / delete_cols 后，后续操作会针对偏移后的网格（偏移后写入的公式会按给定内容存储，偏移前写入的公式则会像现有公式一样移动）；在批次中较早添加或重命名的工作表，后续操作会使用其新名称寻址；工作表上的规则、链接、注释、筛选器和视觉元素必须在任何行 / 列操作之后添加；定义名称操作不能与工作表或行 / 列操作放在同一批次中。set_cell 的字符串若以 = 开头，则会写入公式；type: "text" 会将其保留为字面文本。除了单元格之外，sheet apply --ops 还可写入图表（add_chart、对 xl/charts/chartN.xml 执行的 edit_chart）、图像和形状、Excel 表格、冻结窗格、隐藏行 / 列、带勾选值的筛选器、条件格式、数据验证、超链接、注释、页面设置、工作表保护、定义名称以及工作表标签的顺序 / 可见性（genoffice guide sheets 列出了所有字段）。--cells 的 style 接受与 format_range.format 相同的对象（{bold, fillColor, numberFormat, …}）。颜色可以是 #RRGGBB，也可以是跟随工作簿主题的主题槽位："accent1"、"accent1+40%"（较亮）、"dk2-25%"（较暗）或 {theme, tint}；fill: {pattern: "lightGray", fg, bg?} 或 fill: {gradient: {angle, stops: [{position, color}]}} 可写入图案填充和渐变填充，而 --formats 会回显槽位、色调和解析后的 rgb。sheet read 会分别返回原始值（0.25、序列日期）和公式，以及 features（工作表级窗格、筛选器、图表、表格和规则数量；范围内的合并单元格和链接）；使用 --formats 时，还会返回设有样式的单元格、列宽（px）和行高（pt）；convert --to csv 会返回显示的文本（百分比、日期），编码为带 BOM 的 UTF-8，行尾为 CRLF，默认使用活动工作表，除非指定 --sheet。create --from x.csv：会识别首行中的 sep=;，ISO 日期（2024-01-01、2024-01-02 09:30）会转换为带日期格式的真实日期，--decimal , 会将 1.234,5 读取为 1234.5。使用本地引擎无法计算的函数（FILTER、SORT、UNIQUE、LET 等）的公式会在不带缓存值的情况下写入，由 Excel 在打开时计算；溢出公式会存储为动态数组，以便在 Excel 365 中溢出；formulas_not_cached 警告会列出这些单元格。
• PowerPoint (slides)：图片操作（addPicture、replacePicture、addMedia、setImageFill、setBackground）在 bytes 中接受本地路径或 data URL；扩展名会自动推断。除非显式设置某个字段（如 bold: false），否则 setText 运行会继承元素首个运行的样式。同一 apply 批次中的操作按顺序运行，因此后续操作可以指定较早操作添加的幻灯片；只有所有操作都成功应用时，原子模式才会写入任何内容；--best-effort（原为 --isolation per_op）和 --stop-on-error 会写入已应用的内容，并返回 status: "partial"。创建的元素会获得新的 e_* ID：再次运行 slides read 后再指定这些元素。convert pptx→pdf 的渲染效果与应用的导出效果相同：每张幻灯片为一张位图，不含文本层。所有 EMU 长度字段（box、offset、dx / dy、wEmu / hEmu、colWidthsEmu、insets）也接受带单位后缀的字符串："2.54cm"、"1in"、"10mm"、"12pt"、"96px"。slides read 会列出每页的 animations[]（seq、el、effect、kind、trigger、durationMs、delayMs、direction）；addAnimation / removeAnimation / reorderAnimation 可编辑单个时间线项目（presetXml 会原样传递 PowerPoint 导出的效果），insertEquation 可从 LaTeX 添加排版公式（由 PowerPoint 渲染，预览中显示线性文本）。
• 应用内转换（→pdf、docx→html、html→docx、create --type pdf、render）：每次调用都会启动一个隐藏的 GenOffice 进程，耗时 1–6 秒，超时时间最长为 180 秒，可安全并发运行。对于真实网页，html→docx 使用 html2docx；带 <formula> 的受限 HTML 片段应改用 create --type docx --from fragment.html。
• 云服务（search、image、media）：--images 会返回 detail.images[] {title,imageUrl,sourceUrl,source,width,height}；提供方返回的结果可能少于 --max。image 会按照提供方的实际格式保存（output_path 会告知实际格式；请求 .png 可能返回 .jpg，并会在 detail.note 中注明）；--aspect / --size 会在本地验证。

工作流

1. 使用 genoffice info 或 genoffice <domain> read --json 了解结构：块索引（docx）、s_<n> / e_* ID 和 EMU 几何信息（pptx）、工作表名称和单元格值（xlsx）。
2. 使用 genoffice guide <domain> 查看操作字段（使用 guide <domain> <op> --json 查看单个操作的架构），然后自行编写 ops JSON。
3. 批量操作较多时，使用 genoffice <domain> apply --dry-run；被拒绝的操作会以 op_rejected 返回，并附带执行器的用法说明行——修正该操作后重新发送整个批次。默认采用原子模式：发生拒绝时文件不会更改，且 detail.batch 为 {total, applied: 0, failed, skipped}。--best-effort 会应用所有可执行的操作，--stop-on-error 会按顺序应用操作，直到遇到第一个拒绝；这两种模式都会写入文件，并以 status: "partial"（退出码为 0）返回，未执行的操作列在 detail.failures 中，计数列在 detail.batch 中——程序必须检查 status，不能只检查退出码。
4. 执行下方的 QA 检查，然后报告输出路径。

注意事项

易踩问题	规则
slides read/audit/render/replace --slide n 和操作目标 { "slide": n } 从 0 开始计数；render --page n 从 1 开始计数；docx 块索引从 0 开始	s_0 是 PNG 中的第 1 页。
--ops -、--cells - 和 --spec - 从标准输入读取（--from 不会）；其他任何值都必须是现有文件	不存在的路径会触发 file_not_found，而不是空批次。
结构性编辑会重新编号：addElement 后生成新的 e_* ID，添加幻灯片后生成新的 s_*，insert_content/delete_blocks 后 docx 块索引会变化	同一批次内的索引是实时的（后续操作会看到先前操作的结果）；开始下一批次前，请再次运行 read。
EMU 字段（offset、box、dx/dy、wEmu/hEmu、colWidthsEmu、insets）接受整数或单位字符串 "2.54cm"、"1in"、"10mm"、"12pt"、"96px"	不要自行乘以 914400；slides read 会返回 EMU 整数。
CSV 导入：首行 sep=; 会被识别并移除，ISO 日期会转换为实际日期，1.234,5 使用 --decimal ,	--header 会冻结第 1 行并添加筛选器；不使用时，首行会作为数据。
本地引擎无法计算的公式（FILTER、SORT、UNIQUE、LET、LAMBDA …）会在写入时不带缓存值	formulas_not_cached 警告会列出这些公式；Excel 打开文件前，sheet read 会显示公式但没有值。这不是错误。
sheet apply 按文件中当前工作表标签名定位工作表，名称必须与标签中的拼写一致	sheet_not_found 会包含 detail.sheets 和 did you mean。
结构性工作表操作（插入/删除行、列、工作表）会调整同一批次中后续操作的地址；定义名称操作不得与工作表或行/列操作混用	后续操作使用调整后的坐标（或将结构性操作放在最后）；规则、链接、备注、筛选器和视觉效果操作应放在其工作表的行/列操作之后。
GenOffice 在某个标签页中打开了文件 → apply 会拒绝操作（退出码 2，file_open_in_gui）	请用户关闭该标签页，或使用 --out other.ext；只有用户接受编辑器可能覆盖文件时，才使用 --force。
create/convert/image 从不覆盖文件（退出码 2，output_exists）；对现有文件使用 apply --out 也会被拒绝	选择其他名称；或仅在用户要求替换时使用 --force。
apply --best-effort / --stop-on-error（原为 slides apply --isolation per_op）会以退出码 0 返回 status: "partial"；check/audit 即使存在问题也会以退出码 0 退出，问题包含在 detail 中	检查 status、detail.batch、detail.failures / detail.issues；退出码 0 不代表“没有问题”。
幻灯片组规格使用 1280×720 画布上的像素；操作使用 EMU	不要在同一文件中混用两者。
convert pptx→pdf 不包含文本层；convert docx→md 会丢弃图片（detail.skipped）	需要获取所有文字时，请使用 docs read --full。
docs findReplace 会跳过表格单元格；insert_content 中的未知 HTML 标签会被静默剥除	对表格块使用 replace_blocks；请遵守受限的 HTML 集合（guide docs）。

命令失败时

根据 error 分支处理，按照 suggestion 的说明操作，然后重新发送整个批次（原子应用未写入任何内容）。detail 以字段形式提供事实，切勿解析 message。

error	后续命令
unknown_command, unknown_option	使用 suggestion 的 did you mean；detail.commands / detail.options 会列出有效项；如果此技能版本早于应用，请运行 genoffice <command> --help
missing_argument, invalid_argument	修正 message 中指定的标志；genoffice <command> --help 会显示标志
invalid_json	重新序列化 ops 文件；通过 --ops - 传输时检查引号
unknown_op	查看 detail.failures[].supported 和 did_you_mean；运行 genoffice guide <domain> 查看列表
op_rejected	detail.failures[].usage 是执行器的用法说明；运行 genoffice guide <domain> <op> --json 查看架构；修正该操作
unresolved_placeholder	使用 merge --strict：detail.unresolved_placeholders[] 会列出每个占位符及其位置；将键添加到 --data（或修正模板中的 split_placeholder），然后重新运行
target_not_found	detail.failures[].available 会列出该幻灯片上的 ID / 匹配的块；否则运行 genoffice <domain> read <file> --json 并重新指定目标
out_of_range	查看 detail.failures[].valid_range（或 detail.valid_range）；read 会显示当前计数
sheet_not_found	detail.sheets 包含文件中的工作表标签名称；原样使用其中一个
file_not_found	检查路径（相对于当前目录）；对于 --ops，- 表示标准输入
output_exists	指定另一个 --out；如果用户要求替换，则使用 --force
file_open_in_gui	请用户关闭该标签页，或使用 --out 写入；仅在获得同意后使用 --force
file_not_open_in_gui	selection/open --el 需要文件已在标签页中打开：先运行 genoffice open <file>，然后请用户选择
outside_allowed_roots	操作范围限定在 GENOFFICE_ALLOWED_ROOTS 内；不要尝试其他位置
resource_limit	该软件包包含过多或过大的部分、压缩比异常，或条目路径超出存档范围；detail 会指出条目和限制。不要重试；告知用户
unsupported	detail.supported 会列出此命令接受的内容；从上表中选择其他处理方式
conversion_failed, app_unavailable	文件或应用出现问题：重试一次；如果 capabilities --json 显示应用缺失，请告知用户（PDF 和 →html/html→ 转换路径需要 GenOffice）
app_crashed	GenOffice 在无头导出期间崩溃（detail.signal）：重试一次；如果再次发生，请告知用户，并指出文档名称和 suggestion 中的崩溃日志路径
成功的结果仍可能携带 warnings[]（{code, message, suggestion?}）：formulas_not_cached、op_warning（已调整某项工作表操作）、images_dropped（convert docx→md）、output_renamed（image 已使用提供方的实际扩展名保存）、unresolved_placeholder（merge 保留了没有值的占位符）。请查看这些警告，报告重要事项，不要重试。

在说“完成”之前

每个文件都要执行以下三项：

文件	1. 检查	2. 查看	3. 报告
演示文稿	slides audit deck.pptx --json → detail.issues 为空（否则应用 suggest 操作）	render deck.pptx --out shots --grid --json，打开联系表	.pptx 路径以及所有保留原样的内容
工作簿	sheet check book.xlsx --json → 没有 formula_error、missing_sheet_ref、number_overflow（应用 set_col_width 建议）	render book.xlsx --out shots --json，查看工作表 PNG	.xlsx 路径；如有未缓存的公式，请列出名称
文档	docs check report.docx --json → 没有可以修复的 broken_ref、placeholder_left、field_not_evaluated	render report.docx --out shots --json，查看第 1 页和最后一页	.docx 路径

无论是否发现问题，check/audit 的退出码都是 0；检查结果位于 detail.issues[] 中，其中包含稳定的 code、path，并且在可能的情况下还包含一个 suggest 操作，可原样传递给 apply。除非用户要求在 GenOffice 中查看文件，否则不要运行 genoffice open。

读取用户的文件

用户提供的源材料（例如要制作成幻灯片的报告、要总结的工作簿）由你读取，而不是由 genoffice 读取：md、txt、csv、pdf 和图片都直接打开。Office 文件采用 ZIP XML 格式，因此请先使用 CLI：

• docx：使用 genoffice convert file.docx --to md --out file.md 获取全文（图片会被丢弃），或者使用 genoffice docs read file.docx --full --json / --html 获取带索引的内容块。
• xlsx：使用 genoffice convert file.xlsx --to csv --sheet <name> --out file.csv 获取整张工作表的显示文本，或者使用 genoffice sheet read file.xlsx --range A1:H200 --json 获取原始值（不指定 --range 时最多读取 500 行，并会提示 truncated: true；先使用 --stats 查看工作簿大小，再使用 --cols/--max-rows 分页读取较宽或较长的工作表；使用 --where formula 仅获取公式）。
• pptx：使用 genoffice slides read file.pptx --full --json 获取每张幻灯片的文本、表格和演讲者备注；需要查看页面时，使用 genoffice slides render file.pptx --out shots。
• pdf：无法自行打开 PDF 时（例如文件受密码保护，或需要页面尺寸和元数据），使用 genoffice pdf read file.pdf --range 1-20 --json。

从这些材料中提取数据和措辞；绝不要对 Office 文件本身运行 cat 或 unzip。

设计演示文稿

无论用户需要的演示文稿多短，都不要手动放置 ops：请遵循 GenOffice 应用本身使用的分阶段流程。你是模型，genoffice 是引擎，每个阶段都会生成一个文件，CLI 会在下一阶段开始前检查该文件。Ops（create --ops、slides apply）用于编辑已存在的演示文稿。

1. 每个会话运行一次 genoffice guide slides design，然后运行 genoffice guide slides spec。运行一次 genoffice capabilities --json：它会说明 GenOffice 是否已配置搜索、图片搜索和图片生成；只有在已配置的情况下，才将它们用于事实和照片，否则请规划不使用照片的页面。
2. 为演示文稿创建一个文件夹。将样式表写入 deck/style.md（颜色、字体、布局变体、一句话描述风格）。然后将大纲写入 deck/outline.json（核心切入点 + 每页一个条目：标题、类型、布局、包含真实数据的简介、image_queries），并运行 genoffice slides check deck/outline.json --json；继续之前先修复所有错误。只有在用户要求审核时，才向用户展示大纲。
3. 每个步骤只处理一页：重新阅读 deck/style.md 和该页的大纲条目，确定该页所需照片，并写入 deck/pages/NN.json（一个页面对象，包含与条目一致的 title、type、layout），运行 genoffice slides check deck/pages/NN.json --json；它会在上一级文件夹中找到 outline.json 和 style.md，并根据第 N 个条目和调色板检查页面。修复问题，直到 detail.audit、detail.outline.findings 和 detail.style.offPalette 均为空（与大纲不一致会以状态码 1 退出），然后再处理下一页。绝不要在一个文件或一个步骤中编写多个页面。
4. 运行 genoffice create --type pptx --spec deck/pages --outline deck/outline.json --out deck/deck.pptx --json（只要有大纲页面尚无对应文件，或页面与其条目不一致，就会拒绝运行）。然后运行 genoffice slides render deck/deck.pptx --out deck/shots --json 并查看 PNG；运行 genoffice slides audit deck/deck.pptx --json 查看几何问题。修复页面文件，然后运行 genoffice slides replace deck/deck.pptx --slide n --spec deck/pages/NN.json --json。最多进行两轮修复。
5. 报告文件路径。照片来自 genoffice search --images 的结果、genoffice image，或用户提供的本地文件；绝不要用灰色方框代替照片。数据来自用户提供的材料或 genoffice search；如果数字仅用于示例，请说明这一点。

编辑现有演示文稿

重写一张幻灯片、新增标题或更换图片时：使用 ops，而不是分阶段流程，并保留演示文稿原有的设计。

1. 使用 genoffice slides read deck.pptx --slide n --full --json 获取元素 ID 和当前文本；如果仅凭文字无法了解页面的外观，则运行 genoffice slides render deck.pptx --slide n --out shots --json。
2. 对现有元素使用 setText（未设置样式的文本运行会继承原有字体、字号和颜色）；使用 addElement / addPicture 添加内容，使用 deleteElement 删除内容。用户希望保留原文件时，使用 --out 写入。
3. 编辑后运行 genoffice slides audit deck.pptx --slide n --json：同一文本框中的句子变长会导致溢出；应用它返回的 suggest ops（这些 ops 会增大或移动文本框），然后再次渲染并检查。
4. 已编辑元素的 ID 会变化：进行第二轮 ops 前，重新运行 slides read。slides replace --slide n --spec 会根据 spec 重建页面，适用于通过分阶段流程创建的演示文稿，不适用于重新设置用户提供的演示文稿样式。

示例

通过 ops 创建演示文稿（编辑现有演示文稿或使用 fixture；为某个人制作的演示文稿应遵循上文所述的分阶段流程）：

[
  {
    "op": "addElement",
    "target": { "slide": 0 },
    "kind": "textbox",
    "offset": { "x": 914400, "y": 685800, "cx": 7315200, "cy": 914400 },
    "paragraphs": [{ "runs": [{ "text": "Q3 Review", "bold": true, "fontSize": 36 }] }]
  },
  { "op": "addBlankSlide", "target": { "slide": 0 } },
  {
    "op": "addTable",
    "target": { "slide": 1 },
    "rows": 3,
    "cols": 3,
    "offset": { "x": 914400, "y": 1828800, "cx": 7315200, "cy": 2286000 }
  }
]

genoffice create --type pptx --ops deck.json --out q3.pptx --json

包含公式的工作簿，然后添加格式化标题行：

echo '[["item","qty","price"],["Apple",2,1.5],["Total","=SUM(B2:B2)",""]]' > table.json
genoffice create --type xlsx --from table.json --out sales.xlsx
echo '[{"op":"format_range","range":"A1:C1","format":{"bold":true,"fillColor":"#FFFF00"}}]' | genoffice sheet apply sales.xlsx --ops - --json

从 Markdown 创建 Word 文档，然后在区块 0 后插入一个段落：

genoffice create --type docx --from report.md --out report.docx
echo '[{"op":"insert_content","afterBlockIndex":0,"html":"<p>Executive summary.</p>"}]' | genoffice docs apply report.docx --ops -

路径规则

• 传入绝对路径或相对于当前目录的路径；genoffice 不会写入 --out 路径或正在编辑的文件之外的位置。
• create 和 convert 在未使用 --force 时会拒绝覆盖已有输出文件。apply 会原地编辑，除非指定了 --out；使用 --out 写入另一个已有文件时也需要 --force。
• 如果 GenOffice 窗口当前打开了某个文件，genoffice 会拒绝重写该文件（退出码为 2，提示信息为 "GenOffice has this file open"）。请让用户关闭该标签页、使用 --out 写入另一个路径，或仅在用户接受编辑器可能覆盖所做更改的情况下传入 --force。
• 如果环境中设置了 GENOFFICE_ALLOWED_ROOTS，genoffice 只会在这些目录内读取和写入（否则退出码为 2）；请确保操作位于这些目录内。每条执行的命令都会记录到 ~/.genoffice/cli-audit.jsonl（GENOFFICE_AUDIT_LOG 可更改日志位置或禁用日志）。GENOFFICE_USER_DATA 可将 genoffice 指向非默认的 GenOffice 配置文件（打开文档注册表、AI 设置）。
• 图片操作（addPicture、setImageFill、addMedia）接受在其 bytes 字段中传入本地文件路径；genoffice 会读取该文件。

限制

• 转换为 PDF 时会在 GenOffice 应用中运行（隐藏运行，每次需要几秒）；需要安装 GenOffice，或将 GENOFFICE_APP_BIN 指向它；docx→html 和 html→docx 也同样如此。
• add_pivot 会在 targetCell 处写入数据透视表的单元格（该位置不能有值或公式，且所在工作表必须已存在于文件中），并创建一个可由 Excel 刷新的原生数据透视表；源公式会从文件中求值，因此请在较早的批次中设置这些公式；add_sparkline 会为每个数据行写入一个单元格内迷你图（每次操作最多 200 行）；convert_to_values 会将公式替换为工作簿引擎根据文件计算出的值（错误结果会保留其公式；单元格编辑应放在较早的批次中）；set_page_setup 还支持 printTitles、header/footer 和 rowBreaks/colBreaks。仍需使用实时编辑器的 Excel 操作（refresh_pivot、编辑会话中创建的表格和形状）会被拒绝，并说明原因。add_conditional_format 和 set_data_validation 会将规则添加到工作表已有的规则中（对已有规则的范围使用 set_data_validation 会替换该规则，null 会将其移除）；clear_conditional_formats 会清除现有规则并重新开始。
• 写入后会使用工作簿引擎计算公式，因此 sheet read 和读取缓存值的工具会看到数值。