AIOffice

# AIOffice **English** | [简体中文](README.zh-CN.md) [](https://github.com/onecer/AIOffice/actions/workflows/ci.yml) [](LICENSE)   **赋予您的智能代理一个 Office 引擎。** AIOffice 让 AI 代理创建、查询、编辑、渲染、预览和验证真正的 `.docx` / `.xlsx` / `.pptx` 文件，就像调用函数一样：**一个命令输入，准确地输出一个 JSON 信封**。 100% 自主构建于纯 C#/.NET 之上 —— **一个约 36 MB 的单文件二进制文件，无需 Microsoft Office，无运行时依赖，无第三方引擎封装。** ```bash # 安装（选择一种）—— 然后运行 `aioffice version` 进行检查 npx aioffice version # 零安装，非常适合 CI / MCP 主机 npm install -g aioffice # 在您的 PATH 上全局安装 `aioffice` brew install onecer/tap/aioffice # macOS / Linux curl -fsSL https://raw.githubusercontent.com/onecer/AIOffice/main/dist/install.sh | sh ``` ```bash aioffice create report.docx --title "Q3 Report" aioffice edit report.docx --set '/body/p[1]' text="Revenue grew 12%" aioffice read report.docx --view outline aioffice diff report.docx old.docx # 语义比较：一个排序的更改列表 aioffice convert report.docx deck.pptx # 跨格式：每页一个幻灯片，下面是项目符号 aioffice mcp # 17 种功能，与 stdio 上的 MCP 工具相同 ``` ### 为什么选择 AIOffice - **100% 自主构建的单二进制文件** —— 纯 C#/.NET，直接通过 DocumentFormat.OpenXml + ClosedXML 进行无损 OOXML 操作。无需 Office，无需云服务，无需封装引擎，无需安装运行时。 - **三种真实格式，一个工具** —— 创作和编辑真正的 `.docx`、`.xlsx`、`.pptx` 文件，可以在真正的 Word、Excel 和 PowerPoint 中打开。 - **提供教学的错误** —— 每个失败都返回一个带有可操作 `suggestion`（和 `candidates` 用于错误路径）的 JSON 信封，以便代理自我纠正而不是猜测。 - **渲染 → 查看 → 修复** —— 通过系统浏览器将任何节点渲染为 PNG，并 *查看* 您创建的内容；通过 MCP，图像会内联返回。 - **冻结的 1.0 合同** —— 一个稳定、可机器读取的接口（`surfaceVersion` 1.0），您的代理可以依赖。参见 [CONTRACT.md](CONTRACT.md)。 - **CLI = MCP，一个思维模型** —— **18 个 CLI 动词**，**17 个 MCP 工具**（与动词一一对应）。学习一次，通过 shell 或 stdio 驱动。 ## 不仅要说，还要做 三个真实的 Office 文件 —— 一个推销幻灯片、一个收入仪表板和一个功能报告 —— **仅使用 `aioffice` 命令逐一构建**。无需安装 Office，无需模板，无需手动调整。下面截图中的文件是在 **LibreOffice** 中打开的 —— 独立的第三方证明 `aioffice` 编写的是真正的、有效的 OOXML 文件，可以被任何 Office 应用程序正确渲染。完整的画廊以及每个文件背后的逐行命令序列都在 **[SHOWCASE.md](SHOWCASE.md)** 中；使用一个脚本 **[`examples/tour.sh`](examples/tour.sh)** 即可重现所有三个文件。 | | | | |---|---|---| | [](SHOWCASE.md#1--a-product-pitch-deck--deckpptx) | [](SHOWCASE.md#2--a-regional-revenue-dashboard--dashboardxlsx) | [](SHOWCASE.md#3--a-capability-report--reportdocx) | | **`deck.pptx`** — 6 个深色幻灯片 + 一个原生条形图（17 个命令） | **`dashboard.xlsx`** — KPI 带、实时 `=SUM`/`=XLOOKUP`、2 个图表（11 个命令） | **`report.docx`** — 表格公式、LaTeX→Office-Math、引用（18 个命令） | <details> <summary>它们是如何制作的 —— 以及更小的示例中的渲染 → 查看 → 修复循环</summary> 上述三个制品均由 **[`examples/tour.sh`](examples/tour.sh)**（每个命令逐一记录）构建，并记录在 **[SHOWCASE.md](SHOWCASE.md)** 中。下面是一个自成体系的迷你示例 —— 三个小文件和渲染 → 查看 → 修复循环 —— 您可以将其粘贴到一个空目录中： ```bash # 在一个空的工作目录中，PATH 上有 aioffice # ---- deck.pptx — 3 个幻灯片，深色背景 + 强调形状 ---- aioffice create deck.pptx aioffice edit deck.pptx --ops '[ {"op":"add","path":"/slide[1]","type":"shape","props":{"name":"bg","x":0,"y":0,"w":"33.87cm","h":"19.05cm","fill":"0F172A"}}, {"op":"add","path":"/slide[1]","type":"shape","props":{"name":"deco-1","x":26.2,"y":10.8,"w":12,"h":12,"fill":"1E293B"}}, {"op":"add","path":"/slide[1]","type":"shape","props":{"name":"deco-2","x":30.4,"y":15,"w":8,"h":8,"fill":"38BDF8"}}, {"op":"add","path":"/slide[1]","type":"shape","props":{"name":"accent","x":2.6,"y":6.1,"w":5.2,"h":0.16,"fill":"38BDF8"}}, {"op":"add","path":"/slide[1]","type":"shape","props":{"text":"AIOffice","x":2.5,"y":6.6,"w":24,"h":3.6,"fontSize":60,"bold":true,"color":"FFFFFF"}}, {"op":"add","path":"/slide[1]","type":"shape","props":{"text":"An AI-native CLI + MCP server for real Office files","x":2.5,"y":10.4,"w":26,"h":1.8,"fontSize":20,"color":"94A3B8"}}, {"op":"add","path":"/slide[1]","type":"shape","props":{"text":"This deck was built entirely by aioffice edit — no Office installed","x":2.5,"y":16.9,"w":26,"h":1.2,"fontSize":12,"color":"64748B"}}]' aioffice edit deck.pptx --ops '[ {"op":"add","path":"/slide[1]","type":"slide","position":"after"}, {"op":"add","path":"/slide[2]","type":"shape","props":{"name":"bg","x":0,"y":0,"w":"33.87cm","h":"19.05cm","fill":"0F172A"}}, {"op":"add","path":"/slide[2]","type":"shape","props":{"name":"accent","x":2.6,"y":2.0,"w":3.6,"h":0.16,"fill":"38BDF8"}}, {"op":"add","path":"/slide[2]","type":"shape","props":{"text":"M1 in numbers","x":2.5,"y":2.5,"w":20,"h":2.2,"fontSize":34,"bold":true,"color":"FFFFFF"}}, {"op":"add","path":"/slide[2]","type":"shape","props":{"name":"card-1","x":2.5,"y":6.4,"w":8.6,"h":8.2,"fill":"1E293B"}}, {"op":"add","path":"/slide[2]","type":"shape","props":{"text":"3","x":3.4,"y":7.4,"w":6.8,"h":2.6,"fontSize":48,"bold":true,"color":"38BDF8"}}, {"op":"add","path":"/slide[2]","type":"shape","props":{"text":"file formats — docx, xlsx, pptx — one 36 MB binary","x":3.4,"y":10.6,"w":6.8,"h":3.4,"fontSize":13,"color":"94A3B8"}}, {"op":"add","path":"/slide[2]","type":"shape","props":{"name":"card-2","x":12.6,"y":6.4,"w":8.6,"h":8.2,"fill":"1E293B"}}, {"op":"add","path":"/slide[2]","type":"shape","props":{"text":"17","x":13.5,"y":7.4,"w":6.8,"h":2.6,"fontSize":48,"bold":true,"color":"38BDF8"}}, {"op":"add","path":"/slide[2]","type":"shape","props":{"text":"MCP tools, 1:1 with the CLI","x":13.5,"y":10.6,"w":6.8,"h":3.4,"fontSize":13,"color":"94A3B8"}}, {"op":"add","path":"/slide[2]","type":"shape","props":{"name":"card-3","x":22.7,"y":6.4,"w":8.6,"h":8.2,"fill":"1E293B"}}, {"op":"add","path":"/slide[2]","type":"shape","props":{"text":"0","x":23.6,"y":7.4,"w":6.8,"h":2.6,"fontSize":48,"bold":true","color":"38BDF8"}}, {"op":"add","path":"/slide[2]","type":"shape","props":{"text":"Office installs required — render, preview, validate built in","x":23.6,"y":10.6,"w":6.8,"h":3.4","text":"Office installs required"}}]' aioffice edit deck.pptx --ops '[ {"op":"add","path":"/slide[2]","type":"slide","position":"after"}, {"op":"add","path":"/slide[3]","type":"shape","props":{"name":"bg","x":0,"y":0,"w":"33.87cm","h":"19.05cm","fill":"0F172A"}}, {"op":"add","path":"/slide[3]","type":"shape","props":{"name":"deco","x":-3,"y":13.5,"w":10,"h":10,"fill":"1E293B"}}, {"op":"add","path":"/slide[3]","type":"shape","props":{"name":"accent","x":2.6,"y":7.0,"w":5.2,"h":0.16,"fill":"38BDF8"}}, {"op":"add","path":"/slide[3]","type":"shape","props":{"text":"render → look → fix","x":2.5,"y":7.5,"w":28,"h":3.2,"fontSize":44,"bold":true,"color":"FFFFFF"}}, {"op":"add","path":"/slide[3]","type":"shape","props":{"text":"One JSON envelope at a time. github.com/onecer/AIOffice","x":2.5,"y":11,"w":26,"h":1.6,"fontSize":18,"color":"94A3B8"}}]' aioffice validate deck.pptx # ---- report.docx — running header, Heading1/2, intro, table ---- aioffice create report.docx aioffice edit report.docx --ops '[ {"op":"add","path":"/header[1]","type":"header","props":{"text":"AIOffice Demo"}}, {"op":"add","path":"/body","type":"p","position":"inside","props":{"text":"AIOffice M1 Report","style":"Heading1"}}, {"op":"add","path":"/body","type":"p","position":"inside","props":{"text":"This document was created entirely from the command line by aioffice — headings, header, table and styles included. Every block below is addressable (/body/p[2], /body/table[1]) and was written through the same atomic edit batches an AI agent would use."}}, {"op":"add","path":"/body","type":"p","position":"inside","props":{"text":"Milestone snapshot","style":"Heading2"}}, {"op":"add","path":"/body","type":"table","position":"inside","props":{"rows":4,"cols":3}}, {"op":"set","path":"/body/table[1]/tr[1]/tc[1]","props":{"text":"Milestone"}}, {"op":"set","path":"/body/table[1]/tr[1]/tc[2]","props":{"text":"Highlights"}}, {"op":"set","path":"/body/table[1]/tr[1]/tc[3]","props":{"text":"Status"}}, {"op":"set","path":"/body/table[1]/tr[2]/tc[1]","props":{"text":"M0"}}, {"op":"set","path":"/body/table[1]/tr[2]/tc[2]","props":{"text":"create / query / edit / render / validate"}}, {"op":"set","path":"/body/table[1]/tr[2]/tc[3]","props":{"text":"shipped"}}, {"op":"set","path":"/body/table[1]/tr[3]/tc[1]","props":{"text":"M1"}}, {"op":"set","path":"/body/table[1]/tr[3]/tc[2]","props":{"text":"png render, live preview, headers/footers, xlsx charts"}}, {"op":"set","path":"/body/table[1]/tr[3]/tc[3]","props":{"text":"shipped"}}, {"op":"set","path":"/body/table[1]/tr[4]/tc[1]","props":{"text":"M2"}}, {"op":"set","path":"/body/table[1]/tr[4]/tc[2]","props":{"text":"tracked changes, comments, pivot tables"}}, {"op":"set","path":"/body/table[1]/tr[4]/tc[3]","props":{"text":"next"}}, {"op":"add","path":"/body","type":"p","position":"inside","props":{"text":"How it was made","style":"Heading2"}}, {"op":"add","path":"/body","type":"p","position":"inside","props":{"text":"aioffice edit report.docx --ops … applied all of the above in one atomic batch; aioffice validate confirms the OOXML is clean, and aioffice render --to png produced the image you are looking at."}}]' aioffice read report.docx --view outline # orient: headings + canonical paths aioffice edit report.docx --remove '/body/p[1]' # drop the empty paragraph create left behind aioffice validate report.docx aioffice get report.docx '/header[1]/p[1]' # → "text": "AIOffice Demo" # ---- metrics.xlsx — sales table, SUM/AVERAGE, formats, bar chart ---- aioffice create metrics.xlsx aioffice edit metrics.xlsx --ops '[ {"op":"set","path":"/Sheet1/A1","props":{"value":"Month"}}, {"op":"set","path":"/Sheet1/B1","props":{"value":"Revenue"}}, {"op":"set","path":"/Sheet1/C1","props":{"value":"Units"}}, {"op":"set","path":"/Sheet1/A1:C1","props":{"bold":true,"fill":"DBEAFE"}}, {"op":"set","path":"/Sheet1/A2","props":{"value":"Jan"}}, {"op":"set","path":"/Sheet1/B2","props":{"value":48800}}, {"op":"set","path":"/Sheet1/C2","props":{"value":305}}, {"op":"set","path":"/Sheet1/A3","props":{"value":"Feb"}}, {"op":"set","path":"/Sheet1/B3","props":{"value":52400}}, {"op":"set","path":"/Sheet1/C3","props":{"value":327}}, {"op":"set","path":"/Sheet1/A4","props":{"value":"Mar"}}, {"op":"set","path":"/Sheet1/B4","props":{"value":61200}}, {"op":"set","path":"/Sheet1/C4","props":{"value":382}}, {"op":"set","path":"/Sheet1/A5","props":{"value":"Apr"}}, {"op":"set","path":"/Sheet1/B5","props":{"value":57600}}, {"op":"set","path":"/Sheet1/C5","props":{"value":360}}, {"op":"set","path":"/Sheet1/A6","props":{"value":"May"}}, {"op":"set","path":"/Sheet1/B6","props":{"value":66900}}, {"op":"set","path":"/Sheet1/C6","props":{"value":418}}, {"op":"set","path":"/Sheet1/A7","props":{"value":"Total","bold":true}}, {"op":"set","path":"/Sheet1/B7","props":{"value":"=SUM(B2:B6)","bold":true}}, {"op":"set","path":"/Sheet1/C7","props":{"value":"=SUM(C2:C6)","bold":true}}, {"op":"set","path":"/Sheet1/A8","props":{"value":"Average"}}, {"op":"set","path":"/Sheet1/B8","props":{"value":"=AVERAGE(B2:B6)"}}, {"op":"set","path":"/Sheet1/C8","props":{"value":"=AVERAGE(C2:C6)","numberFormat":"0.0"}}, {"op":"set","path":"/Sheet1/B2:B8","props":{"numberFormat":"$#,##0"}}, {"op":"add","path":"/Sheet1","type":"chart","props":{"kind":"bar","dataRange":"A1:B6","anchor":"E2","title":"Revenue by month"}}]' aioffice get metrics.xlsx /Sheet1/B7 # → "formula": "=SUM(B2:B6)", "cachedValue": 286900 aioffice get metrics.xlsx /Sheet1/B8 # → "formula": "=AVERAGE(B2:B6)", "cachedValue": 57380 aioffice get metrics.xlsx '/Sheet1/chart[1]' # → bar chart "Revenue by month", A1:B6 @ E2 aioffice validate metrics.xlsx # ---- render: the "look" step ---- aioffice render deck.pptx --to png --scope '/slide[1]' -o deck-1.png aioffice render deck.pptx --to png --scope '/slide[2]' -o deck-2.png aioffice render deck.pptx --to svg --scope '/slide[1]' -o deck-1.svg aioffice render report.docx --to png -o report.png aioffice render metrics.xlsx --to png -o metrics.png # ---- look → fix: the slide-2 card labels overflowed their cards ---- aioffice query deck.pptx 'shape:contains("formats")' # find the label → /slide[2]/shape[6] aioffice edit deck.pptx --ops '[ {"op":"set","path":"/slide[2]/shape[6]","props":{"text":"file formats — one binary"}}, {"op":"set","path":"/slide[2]/shape[9]","props":{"text":"MCP tools, 1:1 with the CLI"}}, {"op":"set","path":"/slide[2]/shape[12]","props":{"text":"Office installs required"}}]' aioffice validate deck.pptx aioffice render deck.pptx --to png --scope '/slide[2]' -o deck-2.png ``` 这个迷你示例使用了与完整展示相同的循环：`create` → 批量 `edit` → `validate` → `render --to png` → 查看 → `edit` 进行修复。xlsx 的 PNG 显示了工作表在 HTML 渲染器中的样子：单元格、格式和缓存的公式结果；条形图存在于文件中（参见 `get '/Sheet1/chart[1]'`）并在 Excel 打开时显示。对于三个精致的制品及其逐行命令，请参见 **[SHOWCASE.md](SHOWCASE.md)** 和 **[`examples/tour.sh`](examples/tour.sh)**。 </details> ## 为什么是 AI-native？ 大多数办公库都是为程序员构建的。大多数办公 CLI 都是为人类构建的。AIOffice 是为 **智能代理** 构建的 —— 每个设计决策都优化了 LLM 实际运行的循环：*act → observe → recover → verify*。 | 功能 | 对智能代理意味着什么 | |---|---| | **每个命令一个 JSON 信封** | `stdout` 上始终有 `{ok, data, error, meta}`。没有什么可刮擦的，也没有什么可猜测的。 | | **提供教学的错误** | 每个错误都带有强制性的 `suggestion`。`invalid_path` 甚至会提供 `candidates` —— 最接近的有效路径，由服务器端计算。一次调用失败，零次恢复尝试。 | | **稳定的寻址** | `/body/p[3]`、`/Sheet1/A1:C10`、`/slide[2]/shape[3]` —— 1 为基数，规范，由 `query` 返回，因此编辑永远不会瞄准猜测的索引。 | | **原子批量编辑** | `edit --ops '[...]'` 应用所有或不应用，支持 `--dry-run`，并使用乐观并发 (`--expect-rev`) 保护 —— 陈旧的文件在写入之前会失败，并带有 `stale_address`。 | | **自动撤销** | 每个突变都会将预先镜像快照到一个 20 深的环中。`snapshot restore` 只需一次调用 —— 而且本身也是可撤销的。 | | **写入时公式求值** | Excel 公式被计算并 **缓存到文件中** (`=SUM(A1:A2)` → 重新打开显示 `42` 立即)。引擎无法评估的函数会产生明确的 `formula_not_evaluated` 警告 —— 从不出现无声的过期值。 | | **渲染 → 查看 → 修复** | 将 docx/xlsx 渲染为 HTML，将 pptx 幻灯片渲染为 SVG —— 以及它们中的任何一个到 **PNG**，无需安装 Office。代理 **查看** 它创建的内容并进行修复。 | | **人类在环中的预览** | `preview open` 在 localhost 上提供实时视图；渲染的节点带有 `data-aio-path`，因此人类 **点击** 返回带有路径的代理作为规范路径，通过 `preview selection`。 | | **默认沙盒隔离** | 所有文件参数在工作区 allowlist (`--workspace`，检查符号链接转义) 内解析。超出范围的访问 → `sandbox_denied`，退出 4。 | | **可内省的接口** | `aioffice schema` 返回整个命令接口作为机器可读的 JSON。代理读取规范而不是臆测它。 | | **CLI = MCP，一个思维模型** | 18 个 CLI 动词（17 个与 MCP 工具 1:1 映射；第 18 个是 CLI 独有的 `version`）。学习一次，通过 shell 或 stdio 驱动。 | ### 错误提供教学 - 真实输出 ```bash $ aioffice get report.docx '/body/paragraph[1]' ``` ```json { "ok": false, "error": { "code": "invalid_path", "message": "'paragraph' cannot appear under /body (body contains: p, table).", "suggestion": "Use a candidate path, or run 'aioffice query <file> \"*\"' to list addressable nodes.", "candidates": ["/body/p[1]"] }, "meta": { "file": "report.docx", "rev": "c73500e407fc", "elapsedMs": 143, "version": "0.1.0" } } ``` ### 真实的公式 - 真实输出 ```bash $ aioffice edit data.xlsx --ops '[{"op":"set","path":"/Sheet1/B1","props":{"value":"=SEQUENCE(3)"}}]' ``` ```json { "ok": true, "data": { "applied": 1, "ops": [{ "op": "set", "path": "/Sheet1/B1", "applied": ["formula"] }] }, "meta": { "warnings": [{ "code": "formula_not_evaluated", "message": "1 formula cell(s) use functions the built-in engine cannot evaluate: /Sheet1/B1. The formula text is saved without a cached value; Excel computes it when the file opens." }] } } ``` ## 安装 AIOffice 以 **单个自包含的本地二进制文件**形式提供 - 无需 .NET 运行时，无需 Microsoft Office，无需额外文件。请选择适合您设置的安装方法；每种方法都会下载与您的操作系统/CPU 匹配的二进制文件，并根据发布的 `SHA256SUMS` 进行验证。完整的矩阵和平台说明请参见 **[docs/INSTALL.md](docs/INSTALL.md)**。 ```bash # 1) npm (Node ≥ 18) - 全局安装，或在需要时使用 npx 运行 npm install -g aioffice # 将 `aioffice` 放入您的 PATH 中 npx aioffice doctor # 一次性，无需安装（适用于 CI / MCP 主机） # 2) Homebrew（macOS / Linux） brew install onecer/tap/aioffice # 3) 单行脚本（macOS / Linux；Windows 使用 PowerShell - 请参见下方） curl -fsSL https://raw.githubusercontent.com/onecer/AIOffice/main/dist/install.sh | sh # 4) 直接下载 - 从发布页面为您的平台获取资产， # 验证其 SHA256，chmod +x，然后将其放入您的 PATH 中： # https://github.com/onecer/AIOffice/releases/latest ``` Windows（PowerShell）：`irm https://raw.githubusercontent.com/onecer/AIOffice/main/dist/install.ps1 | iex`。 在 macOS 上，直接下载的二进制文件可能需要 `xattr -d com.apple.quarantine <path>` 一次（脚本和 Homebrew 为您执行此操作；二进制文件尚未经过 notarization - 请参见 [docs/SIGNING.md](docs/SIGNING.md)）。安装后，`aioffice version` 应该打印 `{"ok":true,"data":{"name":"aioffice","version":"1.7.0",…}}`。 ### 从您的代理（MCP）使用它 AIOffice **两次公开相同的接口** - 一个 CLI 和一个 stdio **MCP 服务器**，包含 17 种工具，这些工具与动词一一对应。运行 `aioffice mcp --workspace <dir>` 并将您的代理指向它： ```bash aioffice mcp --workspace /path/to/your/documents # stdio JSON-RPC，沙盒化到 <dir> ``` 每台主机的配置（Claude Desktop，Claude Code，Cursor，通用 stdio，TonoBraid）位于 **[docs/MCP-SETUP.md](docs/MCP-SETUP.md)**。将代理的系统提示指向 **[SKILL.md](SKILL.md)** - 面向 AI 的 onboarding 指南（信封形状，地址语法，读写循环）。复制粘贴任务配方在 **[docs/COOKBOOK.md](docs/COOKBOOK.md)** 中实时生效。 ### 从源代码构建 ```bash # 构建（需要 .NET 10 SDK） dotnet build AIOffice.sln # 从源代码运行 alias aioffice='dotnet run --project src/AIOffice.Cli --' # 或发布单个文件二进制文件（~36 MB，自包含） dotnet publish src/AIOffice.Cli -r osx-arm64 -c Release \ -p:PublishSingleFile=true --self-contained # rids: osx-arm64 | osx-x64 | win-x64 | win-arm64 | linux-x64 | linux-arm64 aioffice doctor # 环境 / 处理程序 / 工作区诊断 ``` ### 60 秒游览 ```bash # Word aioffice create report.docx --title "Q3 报告" aioffice edit report.docx --ops '[ {"op":"add","path":"/body","type":"p","position":"inside", "props":{"text":"季度结果","style":"Heading1"}}]' aioffice query report.docx 'p[style=Heading1]' # → 标准路径 + 片段 aioffice render report.docx --to html -o report.html # Excel - 公式在写入时计算 aioffice create data.xlsx aioffice edit data.xlsx --ops '[ {"op":"set","path":"/Sheet1/A1","props":{"value":21}}, {"op":"set","path":"/Sheet1/A2","props":{"value":21}}, {"op":"set","path":"/Sheet1/A3","props":{"value":"=SUM(A1:A2)"}}]' aioffice get data.xlsx /Sheet1/A3 # → "cachedValue": 42 # PowerPoint - 看看你做了什么 aioffice create deck.pptx # 从一个空白幻灯片开始 aioffice edit deck.pptx --ops '[{"op":"add","path":"/slide[1]","type":"slide", "position":"after","props":{"title":"你好"}}]' aioffice edit deck.pptx --add '/slide[1]' --type shape text="AIOffice" x=2cm y=3cm w=10cm h=2cm aioffice render deck.pptx --to svg --scope '/slide[1]' -o slide1.svg # 安全网 aioffice snapshot list report.docx # 自动预编辑快照 aioffice snapshot restore report.docx 1 # 一键回滚 aioffice validate report.docx # OOXML 验证 + 校验 ``` ## Markdown 输入，Office 输出 代理以 markdown 和 csv 格式思考。M5（v0.6.0）使这些成为前门 - 以下每个命令都直接来自发布烟雾测试： ```bash # markdown -> 真实 docx（标题，嵌套列表，管道表格，链接，粗体，代码） aioffice create report.docx --from notes.md aioffice read report.docx --view outline # 标题 + 标准路径 aioffice read report.docx --view markdown # …并以 GFM 格式输出 - 结构循环 aioffice validate report.docx # "valid": true, 0 errors # csv -> 类型化的 xlsx（引用逗号保留，日期类型，“007”保留为文本） aioffice create orders.xlsx --from orders.csv aioffice get orders.xlsx /Sheet1/A2 # → "value": "007", "type": "text" aioffice read orders.xlsx --view csv # 一个工作表以 RFC 4180 csv 格式输出 ``` 不匹配的对会快速失败，并带有建议中的矩阵：`.md/.markdown → .docx, .csv/.tsv → .xlsx`。相同的线路在 MCP 上：`office_create {file, from}` 和 `office_read {view:"markdown"|"csv"}`。 ## LaTeX 输入，公式输出 M6（v0.7.0）添加了一个手工卷动的 LaTeX → OOXML Math 转换器（无 LaTeX 依赖）。您编写 LaTeX；文档获得 **真正的 Office Math**，Word 将其渲染为公式。下面命令直接来自发布烟雾测试： ```bash # 创建一个文档并添加一个内联公式 + 显示块（二次公式）+ 矩阵 aioffice create report.docx --title "M6 报告" aioffice edit report.docx --ops '[{"op":"add","path":"/body/p[1]","type":"equation","props":{"latex":"E = mc^2"}}]' aioffice edit report.docx --ops '[{"op":"add","path":"/body/p[1]","type":"equation","props":{"latex":"\\frac{-b \\pm \\sqrt{b^2-4ac}}{2a}","display":true}}]' aioffice edit report.docx --ops '[{"op":"add","path":"/body/p[1]","type":"equation","props":{"latex":"\\begin{pmatrix}1&0\\\\0&1\\end{pmatrix}","display":true}}]' aioffice read report.docx --view text # → "M6 报告$E = mc^2$", "$$\frac{-b \pm \sqrt{b^2-4ac}}{2a}$$", … aioffice get report.docx /body/p[1]/omath[1] # → "latex": "E = mc^2", "display": false aioffice validate report.docx # "valid": true, 0 errors # 未知命令降级 - 文件仍然有效，您只会收到警告 aioffice edit report.docx --ops '[{"op":"add","path":"/body/p[4]","type":"equation","props":{"latex":"\\foobar{x} + \\alpha"}}]' # → ok:true + meta.warnings: [{ "code": "equation_partial", "message": "…\\foobar… 出现字面值…" }] ``` 原始 LaTeX 存储在每个公式上（作为 `mc:Ignorable` 供应商属性），因此 `get` 返回您的源代码逐字节，并且循环保持字节忠实。支持的子集 - 分数，根，上下标，大运算符，矩阵（`pmatrix`/`bmatrix`/…），`\left…\right`，口音，`\text`，希腊字母和运算符 - 在 `aioffice help equations` 中有文档记录。渲染它，数学是真实的： ```bash aioffice render report.docx --to png -o quadratic.png # 以下公式通过这种方式精确生成 ```  **M10（v0.11.0）：相同的转换器现在驱动 PowerPoint。** LaTeX → OMML 引擎进入 Core（纯 `System.Xml.Linq` 生产者，无 `DocumentFormat.OpenXml` 依赖），因此给定的 LaTeX 字符串在 docx 和 **pptx** 中呈现相同。幻灯片上的公式作为原生 OMML 存储在文本框中，地址为 `/slide[i]/shape[@id=N]/omath[k]`： ```bash aioffice edit deck.pptx --ops '[{"op":"add","path":"/slide[1]","type":"equation","props":{"latex":"x = \\frac{1}{2}"}}]' # → 目标 "/slide[1]/shape[@id=5]/omath[1]" aioffice get deck.pptx "/slide[1]/shape[@id=5]/omath[1]" # → "latex": "x = \\frac{1}{2}" aioffice validate deck.pptx # "valid": true, 0 errors ``` Excel 因设计而不可用 - 工作表带有单元格公式，而不是数学对象 - 因此在 `.xlsx` 上添加 `type:equation` 返回 `unsupported_feature`，命名变通方法（单元格公式或嵌入的渲染图像）。 ## 审计后您再发布 `aioffice audit` 是 Office 文件的无障碍性和质量校验。发现结果是 **数据**，永远不是错误 - 命令退出状态为 0，即使它显示了严重性为错误的发现结果，就像 `validate` 一样。`--fix` 只应用 **安全、非破坏性** 的自动修复并重新审计，因此您可以查看剩余的内容。 ```bash # 一个故意制作的坏报告：图像无替代文本，H1 然后是 H3，无标题的表格，空标题，无文档标题。 $ aioffice audit report.docx { "ok": true, "data": { "findings": [ { "code": "a11y_no_doc_title", "severity": "warning", "path": "/properties", "autofixable": true }, { "code": "a11y_no_alt_text", "severity": "error", "path": "/body/p[5]", "autofixable": true }, { "code": "a11y_heading_skip", "severity": "warning", "path": "/body/p[3]", "autofixable": false }, { "code": "quality_empty_heading","severity": "warning", "path": "/body/p[4]", "autofixable": false }, { "code": "a11y_no_table_header", "severity": "error", "path": "/body/table[1]", "autofixable": true } ], "summary": { "errors": 2, "warnings": 3, "infos": 0 } } } # --fix 应用安全自动修复（替代文本，表格标题，文档标题），然后 # 重新审计。跳过标题和空标题的发现结果仅报告，不会在您手动修复之前 # 保留在 `remaining` 中。 $ aioffice audit report.docx --fix { "ok": true, "data": { "findings": [ { "code": "a11y_heading_skip", "path": "/body/p[3]", "autofixable": false }, { "code": "quality_empty_heading", "path": "/body/p[4]", "autofixable": false } ], "summary": { "errors": 0, "warnings": 2, "infos": 0 }, "fixed": 3, "remaining": ["a11y_heading_skip#/body/p[3]", "quality_empty_heading#/body/p[4]"] } } # 之后仍然有效的 OOXML。 $ aioffice validate report.docx { "ok": true, "data": { "valid": true, "count": 0, "issues": [] } } ``` 相同的动词，相同的发现结果，相同的 `--fix` 语义适用于 **.xlsx**（公式错误，如 `#DIV/0!`，合并的数据单元格，缺少替代文本/标题）和 **.pptx**（图片替代文本，幻灯片标题，画布外形状，微小字体，阅读顺序）。使用 `--category accessibility|quality|all` 和 `--severity error|warning|info` 进行范围限定；在 `aioffice help audit` 中有完整的代码列表和哪些代码可自动修复。通过 MCP，它是 `office_audit {file, category?, severity?, fix?}` - 第 15 种工具。 ## 差异和审查 `aioffice diff` **语义** 比较文档与基线并返回排序的确定性更改列表 - `added` / `removed` / `modified`（带有 `before`/`after`）/ `moved`。更改是 **数据**：即使两个文档差异很大，退出状态为 0。基线是 **另一个相同格式的文件** 或 **文件自己的预编辑快照**。 ```console # 两个文件 - 在此草稿和上一个草稿之间发生了什么变化 $ aioffice diff new.docx old.docx { "ok": true, "data": { "changes": [ { "kind": "modified", "path": "/body/p[1]", "before": "Heading1", "after": "Heading2", "detail": "style" }, { "kind": "modified", "path": "/body/p[2]", "before": "Second paragraph.", "after": "Second paragraph EDITED.", "detail": "text" }, { "kind": "added", "path": "/body/p[4]", "detail": "paragraph" } ], "summary": { "added": 1, "removed": 0, "modified": 2, "moved": 0 }, "baseline": "old.docx", "view": "detailed" } } # 对比快照 - “我刚刚做了什么？”（每次编辑都自动快照） $ aioffice edit report.docx --set '/body/p[2]' text='Revised' $ aioffice diff report.docx --snapshot 1 # → 编辑所做的单个更改，before/after，确定 # 简洁的审查 - 计数 + 每种更改一行路径 + 类型 $ aioffice diff metrics.xlsx baseline.xlsx --view summary ``` 更改列表始终按 `(path, kind)` 排序，因此相同的两个文档在每个平台和每次运行都完全不同。跨格式基线（`.docx` 对 `.xlsx`）是 `invalid_args`，命名不匹配。MCP 上它是 `office_diff {file, other? | snapshot?, view?}` - 第 16 种工具。 ## 转换格式 `convert` 将文档从一种格式转换为另一种格式。它通过 `(source, destination)` 扩展名对进行路由：相同的家族文本桥接器重用现有代码（`docx↔md`, `xlsx↔csv`），跨格式对通过 **内容中立的模型**（标题，段落，格式化运行，列表，表格，图像），并且`任意 → PDF/PNG/SVG/HTML` 路由到渲染层。转换本质上是有损的 - 目标无法表示的内容会诚实地命名为 `data.dropped` 和单个 `convert_lossy` 警告。 ```bash # docx → pptx - 每个标题一个幻灯片，其项目符号作为幻灯片正文，表格作为原生 pptx 表格 $ aioffice convert report.docx deck.pptx # → {"from":"docx","to":"pptx","blocksWritten":10,"dropped":[],"written":".../deck.pptx"} # xlsx → docx - 每张表格/工作表对应一个标题和表格；公式以缓存值形式交叉 $ aioffice convert data.xlsx data.docx # → 一个 docx，其 Sheet1/Totals 表格保留显示值（例如 =SUM(...) → 30） # 任意 → markdown - 通过中立模型，因此 xlsx 和 pptx 也可达 md $ aioffice convert report.docx report.md # 标题，项目符号和管道表格 $ aioffice convert report.md roundtrip.docx # 并返回 - 大纲循环 ``` ## 嵌入和提取 M10（v0.11.0）允许文档 **携带另一个文件** 作为嵌入的 OLE/包对象 - 源 `.xlsx` 附加到报告，`.pdf`, `.zip`, 任何文件 - 在所有三种格式中。嵌入它，列出嵌入，提取字节后完全相同，删除它。下面命令直接来自发布烟雾测试： ```bash # 将工作簿嵌入到报告中，列出它，提取它，然后检查是否完全相同 aioffice edit report.docx --add /body --type embed src=data.xlsx name="Q3 模型" # → "/embed[1]", mediaType "…spreadsheetml.sheet" aioffice read report.docx --view embeds # → [{ path:/embed[1], name:"Q3 模型", mediaType, size }] aioffice edit report.docx --ops '[{"op":"extract","path":"/embed[1]","props":{"to":"out.xlsx"}}]' shasum -a 256 data.xlsx out.xlsx # 相同 - 有效载荷完全循环 aioffice edit report.docx --ops '[{"op":"remove","path":"/embed[1]"}]' aioffice validate report.docx # "valid": true, 0 errors ``` 容器是每种格式的（docx `/body` 或 tc/header/footer，xlsx `/Sheet1` 锚定，pptx `/slide[i]`），嵌入文件被寻址为 `/embed[i]`，`/Sheet1/embed[i]`，`/slide[i]/embed[@id=N]`。`extract` 是一个 **生成** 操作：它写入目标但从不修改源文档，提取的字节与嵌入的文件在打开 + 保存循环后相同。媒体类型从源文件嗅探；嵌入 `src` 和提取 `to` 都经过沙盒解析（转义路径是 `sandbox_denied`）。它依赖于 `office_edit` / `office_read` - 没有新的 MCP 工具，仍然是 17 个。有关详细信息，请参见 `aioffice help embeds`。 ## 新增功能 1.7 1.7.0 是第六个 **1.0 后特性发布版本** — 纯粹 **增加**，因此 `surfaceVersion` 仍为 **`1.0`**（以下所有内容均位于冻结的 [CONTRACT.md](CONTRACT.md) 行内；无删除或重命名，`op` 类型不变，且 **无新动词或 MCP 工具**）。它完善了 **打印就绪**，添加了 **相机工具** 和 **计算设置**，并 **深化了公式引擎**。18 个动词 / 17 个 MCP 工具保持不变。 - **xlsx 打印完整性** — 在 `/SheetN` 上设置：`printTitleRows`/`printTitleCols`（重复带），`pageBreaks`（`{rows,cols}`），`fitToPage`（`{fitToWidth,fitToHeight}` 或 `{scale}`），`centerHorizontally`/`centerVertically`，`printGridlines`/`printHeadings`，以及 `printHeader`/`printFooter`（`{left,center,right}` 字段代码字符串：`&P` `&N` `&D` `&T` `&F` `&A`）。`get /SheetN` 会反映它们。参见 `aioffice help print-setup`。 - **xlsx 链接图片 / 相机工具** — `add type:linkedPicture` 镜像一个单元格范围为图片；一个诚实的 **静态快照**（一个真正的实时链接是验证器脆弱的），通过 `linked_picture_static` 警告触发。地址 `/SheetN/linkedPicture[i]`。 - **xlsx 计算设置** — 设置 `/`（工作簿根）：`calculationMode`（`auto`/`manual`/`autoExceptTables`），`iterativeCalc`，`maxIterations`，`maxChange`，`fullPrecision`。`get /` 现在返回 `{calculation, workbookProtection}`（以前是 `unsupported_feature` — 处理旧错误的代理仍然有效）。 - **docx 首字母缩写, 图片水印, 更多字段, 编号公式** — 在段落上设置 `{dropCap,dropCapLines,dropCapFont}`；添加类型 `watermark {image,washout}` 用于图片水印；添加类型 `field` 类型 `styleRef`（STYLEREF），`symbol`（SYMBOL），`quote`（QUOTE）；添加类型 `equation {display:true,number:…}` 用于编号显示公式，地址 `/equation[@num=…]`。 - **更深层次的公式（docx + pptx，共享核心转换器）** — `\begin{aligned|gathered|cases}` 数组，`\binom`/`\dbinom`/`\tbinom`，`\overbrace`/`\underbrace`，多重积分 `\iint`/`\iiint`，更多重音符号和关系/箭头。**向后兼容** — 严格 *更多* LaTeX 渲染（更少的 `equation_partial` 警告）；pptx 公式会自动继承所有这些。参见 `aioffice help equations`。 - **pptx 备注/讲义母版, 动画计时, 表格单元格对齐** — 设置 `/notesMaster`（`{background,bodyFont}`）和 `/handoutMaster`（`{background,headerFooter,slidesPerPage}`）；通过 `set /slide[i]/animation[k]` 进行动画 `repeat`/`rewind`/`autoReverse`；表格单元格 `valign`/`marginLeft|Right|Top|Bottom`/`textDirection`。参见 `aioffice help masters`。 这些功能在 `schema` / `office_schema` 中可见，文档详见 `aioffice help`（新主题 `print-setup`, `masters`; `equations`/`animations`/`properties-*`/`addressing` 深化），并通过 `SchemaConsistencyTests` 保持同步（MCP 工具表面在 3500 个令牌预算内）。新的 `add` 类型（`linkedPicture`），新的设置路径（`/notesMaster`, `/handoutMaster`），新的寻址形式（`/SheetN/linkedPicture[i]`，`/equation[@num=…]`），新的属性键，以及两个新的警告代码（`linked_picture_static`, `equation_numbers_cached`）— 所有这些都是增加的。参见 [CONTRACT.md §7g](CONTRACT.md) 和 [CHANGELOG.md](CHANGELOG.md)。**2331 测试** 在 macOS + Windows 上通过（核心 180 · Word 681 · Excel 619 · Pptx 709 · MCP 87 · 预览 24 · 渲染 31）。 ## 新增功能 1.6 1.6.0 是一个 **分发和 onboarding 版本 — 无功能变更**。原生二进制文件与 1.5.0 相同，字节对字节完全相同：**18 个 CLI 动词 / 17 个 MCP 工具 / `surfaceVersion` `1.0`**，冻结的 [CONTRACT.md](CONTRACT.md) 行，每种信封、错误代码和寻址形式保持不变。1.6 新增的是二进制文件周围的所有内容，允许代理和人类可以安装并配置它： - **npm 包** — `npm i -g aioffice`（或 `npx aioffice …`）。一个微小的包装器，从 GitHub 版本中下载匹配的原生二进制文件并进行 SHA256 验证；二进制文件不包含在 tarball 中。参见 [`npm/README.md`](npm/README.md) 和 `AIOFFICE_DOWNLOAD_VERSION` / `AIOFFICE_DOWNLOAD_BASEURL` 重写。 - **Homebrew 公式** — `brew install onecer/tap/aioffice`，安装预构建的每个平台二进制文件（[`dist/Formula/aioffice.rb`](dist/Formula/aioffice.rb)）。 - **一键安装脚本** — `dist/install.sh`（macOS/Linux，POSIX sh）和 `dist/install.ps1`（Windows PowerShell）：检测平台 → 下载 → SHA256 验证 → 安装 → PATH 提示；macOS 隔离自动剥离。 - **Onboarding 文档** — [SKILL.md](SKILL.md)（AI 面向的技能指南），[docs/COOKBOOK.md](docs/COOKBOOK.md)（10 个复制粘贴的配方），[docs/INSTALL.md](docs/INSTALL.md)（所有四种安装路径），[docs/MCP-SETUP.md](docs/MCP-SETUP.md)（Claude Desktop / Claude Code / Cursor / 通用 stdio / TonoBraid 配置），[docs/SIGNING.md](docs/SIGNING.md)（代码签名 / notarization 路线图）。 整个版本 **在 C#/.NET 源代码树之外** — 构建和测试不受影响。**2125 测试** 在 7 个项目上通过（核心 124 · Word 612 · Excel 572 · Pptx 675 · MCP 87 · 预览 24 · 渲染 31）。要发布：`cd npm && npm publish --access public`（在 `npm login` 之后）；使用 `dist/Formula/aioffice.rb` 创建 `onecer/homebrew-tap` 并填写四个 `sha256` 值（来自 v1.6.0 的 `SHA256SUMS`）；安装脚本直接从 `main` 提供。参见 [CHANGELOG.md](CHANGELOG.md)。 ## 新增功能 1.5 1.5.0 是第五个 **1.0 后特性发布版本** — 纯粹 **增加**，因此 `surfaceVersion` 仍为 **`1.0`**（以下所有内容均位于冻结的 1.0 合同行内；无删除或重命名，`op` 类型不变）。**它关闭了现代标量函数差距**（`XLOOKUP`/`IFS`/`SWITCH`/`LET`/… 现在求值）和完善了电子表格 **假设分析工具**（情景管理器 + 目标搜索），而 Word 获得表格单元格公式、构建块和行号，PowerPoint 获得嵌入字体、动作按钮和自定义布局。18 个动词 / 17 个 MCP 工具保持不变。 - **标量函数求值（xlsx）** — `=XLOOKUP`, `=IFS`, `=SWITCH`, `=LET`, `=MAXIFS`, `=MINIFS`, `=AVERAGEIFS`（以及 `=TEXTSPLIT`，它会溢出）现在 **求值** 在写入时，缓存值被写入，因此无头读取器会看到一个真实的结果，而不会出现 `formula_not_evaluated` 警告。`TEXTJOIN`/`CONCAT`/`IFERROR`/`SUMIFS`/`COUNTIFS` 已经求值并继续工作。 - **情景管理器（xlsx）** — `add type:scenario`（`{name, cells:{addr:value,…}, comment?}`）保存一个命名的更改单元格集；`set {applyScenario:"name"}` 写入值并 **重新计算** 依赖项。地址 `/Sheet1/scenario[@name=…]`。 - **目标搜索（xlsx）** — 在更改单元格上设置 `{goalSeek:{targetCell, targetValue}}` 求解使目标公式达到目标的输入（牛顿 + 二分法），设置它并重新计算；如果没有收敛，则新的 `goal_seek_no_solution` 警告（单元格保持不变）。 - **表格单元格公式（docx）** — 表格单元格上的 `formula` 属性（`=SUM(ABOVE)`，`=AVERAGE(LEFT)` 或单元格引用算术，如 `=A1*B2`）变为 `w:fldSimple` 字段，值在无头计算并缓存。可选的 `numberFormat` 形状；字段输入引发 `table_formula_cached` 警告。 - **构建块（docx）** — `add type:buildingBlock` 在词汇部分存储可重用的 AutoText / Quick Parts 内容；`add type:buildingBlockRef` 将存储的块的内容插入正文。地址 `/buildingBlock[@name=…]`。 - **行号（docx）** — 在 `/section[i]` 上设置 `lineNumbers` 属性（`{start, increment, restart, distance?}`，或 `"none"`）。 - **嵌入字体（pptx）** — 在 `/fonts` 上添加 `type:font` 嵌入一个沙箱解析的 `.ttf`/`.otf` 作为字体部分，并注册 `p:embeddedFont`（常规插槽，或全部四个 `embedAll`）。`src` 是必需的，并且必须位于工作区内。地址 `/fonts/font[@name=…]`。 - **动作按钮（pptx）** — 在幻灯片上添加 `type:actionButton`（`{action, target?, …}`；`action` ∈ `first|last|next|prev|home|end|slide|url`）— 构建在 M8 形状超链接上。 - **自定义布局（pptx）** — M6 `add type:layout` 获得一个 `placeholders` 属性（`[{type, x, y, w, h}]`），它在主幻灯片上构建一个新的 `slideLayout` 部分；幻灯片通过名称绑定到它（`add type:slide {layoutName:"Hero"}`）。 这些功能在 `schema` / `office_schema` 中可见，文档详见 `aioffice help`（新主题 `scenarios`, `goal-seek`, `table-formulas`, `building-blocks`, `embedded-fonts`, `action-buttons`, `layouts`, `line-numbers`; `formulas` 扩展了标量函数），并通过 `SchemaConsistencyTests` 保持同步（MCP 工具表面在 3500 个令牌预算内 — 详细信息位于 `office_help`，而非工具架构）。新的 `add` 类型（`scenario`/`buildingBlock`/`buildingBlockRef`/`font`/`actionButton`），新的属性键（`applyScenario`/`goalSeek`/表格单元格 `formula`/`lineNumbers`/`embedAll`/布局 `placeholders`），新的寻址形式（`/Sheet1/scenario[@name=…]`，`/buildingBlock[@name=…]`，`/fonts`），以及两个新的警告代码（`goal_seek_no_solution`, `table_formula_cached`）— 所有这些都是增加的。标量函数求值 **向后兼容**：单元格以前会为这些函数携带 `formula_not_evaluated`，现在携带缓存值，处理警告的代理仍然有效。参见 [CONTRACT.md §7e](CONTRACT.md) 和 [CHANGELOG.md](CHANGELOG.md)。**2125 测试** 在 macOS + Windows 上通过。 ## 新增功能 1.4 1.4.0 是第四个 **1.0 后特性发布版本** — 纯粹 **增加**，因此 `surfaceVersion` 仍为 **`1.0`**（以下所有内容均位于冻结的 1.0 合同行内；无删除或重命名，`op` 类型不变）。**它关闭了长期存在的动态数组差距**：`FILTER`/`UNIQUE`/`SORT`（和朋友）现在求值并溢出，而不是仅被识别。18 个动词 / 17 个 MCP 工具保持不变。 - **动态数组求值 + 溢出（xlsx）** — 设置单元格为 `=FILTER`, `=UNIQUE`, `=SORT`, `=SORTBY`, `=SEQUENCE`, `=RANDARRAY` 或 `=TRANSPOSE` 现在 **求值** 公式并 **溢出** 结果数组到以单元格为锚点的矩形（锚点保留数组公式；每个溢出的单元格都带有缓存值）。这些不再引发 `formula_not_evaluated`; 在锚点上获取报告一个 `spillRange`。`RANDARRAY` 具有确定性的种子，以实现稳定的往返。 - **财务函数（xlsx）** — `RATE`, `IRR`, `XIRR`, `NPV`, `PV`, `FV`, `PMT`, `NPER` 在写入时求值（迭代式通过牛顿法和二分法求解），并写入缓存的数值 — 对它们不再出现 `formula_not_evaluated`。 - **假设数据表（xlsx）** — `add type:dataTable` 构建一个单变量或双变量数据表（`{rowInput?, colInput?}`）；角落公式在输入轴上重新计算成一个带有 Excel `{=TABLE(…)}` 构造的缓存正文。地址 `/Sheet1/dataTable[i]`。阻止溢出会引发新的 `spill_blocked` 错误（退出 2）。 - **邮件合并执行（docx）** — 现有的 `template` 动词在 `--data` 是 JSON **数组** 记录时运行邮件合并：每个记录一个合并文档（`--output` 模式 `{n}` = 记录索引，`{Field}` = 记录值；每个扩展路径沙箱解析），或一个合并文档（一个记录部分）。`office_template` 增加一个可选的 `output` 参数 — 仍然 17 个工具。单个对象 `--data` 仍然填充一个文档不变。 - **IF 字段（docx）** — `add type:ifField` 添加一个 Word «IF» 字段（`{field, operator, value, trueText, falseText}`）在合并期间根据记录解析。 - **页面边框（docx）** — 在 `/section[i]` 上的 `pageBorder` 属性（`{style, color?, widthPt?, sides?}`，或 `"none"`）。 - **幻灯片缩放（pptx）** — `add type:zoom` 在幻灯片上添加一个幻灯片/章节/摘要缩放导航对象（`{kind, target?, x?, y?, w?, h?}`），地址 `/slide[i]/zoom[k]`. - **点击触发动画（pptx）** — `add type:animation` 上的 `triggerOn:"@N"` 属性在另一个形状（稳定 ID `N`) 被点击时播放效果。 - **表格样式（pptx）** — `add type:table` 接受内置样式（`none|light1|light2|medium1|medium2|medium3|dark1|dark2`) 以及带状/边缘标志 `firstRow`, `lastRow`, `bandRow`, `firstCol`。 这些功能在 `schema` / `office_schema` 中可见，文档详见 `aioffice help`（新主题 `formulas`, `data-tables`, `mail-merge`, `page-borders`, `zoom`, `table-styles`; `animations` 扩展了 `triggerOn`），并通过 `SchemaConsistencyTests` 保持同步（MCP 工具表面在 3500 个令牌预算内 — 详细信息位于 `office_help`，而非工具架构）。新的 `add` 类型（`dataTable`/`ifField`/`zoom`），新的属性键（`pageBorder`/`triggerOn`/表格 `style`），新的寻址形式（`/Sheet1/dataTable[i]`，`/slide[i]/zoom[k]`），扩展的 `template` 行为，以及一个新错误代码（`spill_blocked`）— 所有这些都是增加的。动态数组/财务评估 **向后兼容**：单元格以前会为这些函数携带 `formula_not_evaluated`，现在携带缓存值，处理警告的代理仍然有效。参见 [CONTRACT.md §7d](CONTRACT.md) 和 [CHANGELOG.md](CHANGELOG.md)。**2016 测试** 在 macOS + Windows 上通过。 ## 新增功能 1.3 1.3.0 是第三个 **1.0 后特性发布版本** — 纯粹 **增加**，因此 `surfaceVersion` 仍为 **`1.0`**（以下所有内容均位于冻结的 1.0 合同行内；无删除或重命名，`op` 类型不变）。18 个动词 / 17 个 MCP 工具保持不变。 - **图表润色（xlsx + pptx）** — 添加演示属性时，接受 `chart` 并且通过 `set` 在现有图表路径上（`/Sheet1/chart[i]`，`/slide[i]/chart[k]`）：`dataLabels`（`true` 或 `{show, position?}`），`legend`（`none|right|left|top|bottom`），`axisTitles`（`{category?, value?}`），`trendline`（`none|linear|exponential|movingAverage`），`errorBars`（`none|stdErr|stdDev|percent`），`gridlines`（`{major?, minor?}`），`secondaryAxis`（命名系列 → 次要值轴）。`get` 在 `polish` 下报告它们。 - **高级条件格式（xlsx）** — 三种新的 `conditionalFormat` 类型：`formula`（`=expression` 规则，如 `$B1>100`），`topBottom`（顶部/底部 N 或 N%），`aboveBelowAverage`（高于/低于范围均值，可选 `stdDev`）。 - **数据透视表计算字段（xlsx）** — `add type:pivot` 上的 `calculatedFields` 属性：`[{name, formula}]` 公式字段从源标题计算（例如 `Margin = Revenue - Cost`），并在 `get` 时验证和报告。 - **正文形状和文本框（docx）** — `add type:shape`（一个浮动的 DrawingML 形状：`rect|roundRect|ellipse|line|arrow`，在 `/body/shape[i]`）和 `add type:textBox`（在 `/body/textBox[i]`），每个都有填充/线条/内联文本。 - **旧版表单字段（docx）** — `add type:formField`（`text|checkbox|dropdown`）通过 `/formField[@name=…]` 进行寻址，通过 `set` 进行赋值，通过 `read --view fields` 进行列出。 - **主题编辑（docx）** — `set /theme` 编辑主题颜色方案（`dk1/lt1/dk2/lt2`，`accent1`…`accent6`，`hlink`，`folHlink`）和字体（`majorFont`，`minorFont`）；`get /theme` 报告它们。 - **3D 模型（pptx）** — `add type:model3d` 嵌入 `.glb`/`.gltf` 作为真正的 3DModel 媒体对象（PowerPoint 2019+ 渲染它）；`src`/`poster` 被沙箱解析，并带有 `model3d_as_media` 警告。地址 `/slide[i]/model3d[@id=N]`。 - **运动路径动画（pptx）** — 一种新的 `motionPath` 动画效果，`path` 为 `line|arc|circle|custom`（自定义采用归一化的 `points` 列表）；`read --view structure` 列出它。 这些功能在 `schema` / `office_schema` 中可见，文档详见 `aioffice help`（新主题 `chart-polish`, `conditional-format`, `themes`, `3d-models`, `form-fields`, `animations`; 扩展的 `properties-docx` / `properties-xlsx` / `properties-pptx`），并通过 `SchemaConsistencyTests` 保持同步（MCP 工具表面在 3500 个令牌预算内 — 详细信息位于 `office_help`，而非工具架构）。新的 `add` 类型（`shape`/`textBox`/`formField`/`model3d`），新的属性键，`/theme` 寻址形式，以及一个新警告（`model3d_as_media`）— 所有这些都是增加的。参见 [CONTRACT.md §7c](CONTRACT.md) 和 [CHANGELOG.md](CHANGELOG.md)。**1924 测试** 在 macOS + Windows 上通过。 ## 1.2 新增功能 1.2.0 是第二个 **1.0 后功能发布版** —— 纯粹是 **增加** 功能，所以 `surfaceVersion` 仍为 **`1.0`** （所有内容都位于冻结的 1.0 合同线内；没有任何内容被删除或重命名，`op` 类型保持不变 — `group`/`ungroup` 是 `add` **类型**，而不是新的 `op` 类型）。18 个动词 / 17 个 MCP 工具保持不变。 - **SmartArt（pptx，创建 + 读取）** — `add type:smartart` 构建一个真正的图表：布局 `list`/`process`/`hierarchy`/`orgChart`/`cycle`，每个布局映射到一个内置的 PowerPoint 布局，在打开时重新生成。节点是一个扁平的 `{text, level}` 列表（0-based level 构建层次结构）。`office_get /slide[i]/smartart[k]` 返回布局和节点树。在原位编辑节点是不支持的（rebuild）。 - **连接符（pptx）** — `add type:connector` 在两个形状之间连接一个 `p:cxnSp` （按 `@id` 或名称）：`kind` straight/elbow/curved，`startArrow`/`endArrow` none/arrow/triangle，`color`/`width`/`name`。 - **分组（pptx）** — `add type:group` 将两个或多个形状包装在一起（`/slide[i]/group[@id=N]`，子项可作为 `…/group[@id=N]/shape[@id=M]` 访问）；`add type:ungroup` 解散一个分组，提升子项的绝对坐标。 - **图表目录（docx）** — `add type:tableOfFigures` 列出图形/表格/公式的标题；条目来自缓存的标题，带有 `figures_cached` 警告。 - **索引（docx）** — `add type:indexEntry` 标记一个 `XE` 字段；`add type:index` 构建字母排序的索引（`columns`），页码缓存并带有 `index_cached` 警告。 - **邮件合并字段（docx）** — `add type:mergeField` 插入一个 `MERGEFIELD`，模板动词按名称填充 — 来自同一个 `--data` 映射，填充 `{{key}}` 占位符。 - **表单控件（xlsx）** — `add type:formControl` 授权 `checkbox`/`optionButton`/`spinner`/`comboBox`/`listBox`/`button`，带有 `linkedCell`、`items`/`listFillRange`、`min`/`max`/`increment`。 - **保护（xlsx）** — 每个单元格 `locked`；工作表路径 `protected`（+ `password`、`allow*` 标志）；工作簿根 `protectStructure`（+ `protectWindows`）。Excel 的轻量级 UI 保护（不是加密）；AIOffice 始终拥有并可以解除它。 - **数字格式预设（xlsx）** — `numberFormat` 属性的命名代码：`accounting-usd`、`currency-usd/eur/gbp/jpy`、`percent`、`scientific`、`date-iso`、`datetime-iso`、`duration`，… 预设解析为其 Excel 代码；任何非预设字符串保持不变。 这些功能在 `schema` / `office_schema` 中可见，记录在 `aioffice help` 下（新主题 `smartart`、`connectors`、`number-formats`、`structural-fields`；扩展 `properties-pptx` / `properties-xlsx`），并通过 `SchemaConsistencyTests` 保持同步（MCP 工具表面在 3,500 个令牌预算内）。参见 [CONTRACT.md §7b](CONTRACT.md) 和 [CHANGELOG.md](CHANGELOG.md)。 ## 1.1 新增功能 1.1.0 是第一个 **1.0 后功能发布版** —— 纯粹是 **增加** 功能，所以 `surfaceVersion` 仍为 **`1.0`** （所有内容都位于冻结的 1.0 合同线内；没有任何内容被删除或重命名）。18 个动词 / 17 个 MCP 工具保持不变。 - **更多图表类型，所有位置** — xlsx *和* pptx 图表工厂获得 `doughnut`、`radar`、`bubble`、`stackedBar`、`percentStackedBar`、`stackedArea` 和 `combo`，以及现有的 `bar`/`line`/`pie`/`scatter`/`area`。`bubble` 每个点需要 x/y/size 三元组；`combo` 将第一个系列绘制为柱形，其余系列绘制为线形（≥2 个系列）。不支持的图表类型仍返回 `unsupported_feature`，列出扩展的集合。 - **xlsx 条件格式的图标集** — 一种新的 `conditionalFormat` 类型，绘制 3/4/5 个图标的图标集（`3TrafficLights1`、`3Arrows`、`4Rating`、`5Quarters`，…），带有 `reverse`/`showValue`。 - **引用和参考文献（docx）** — `add type:source` 到参考文献存储，`add type:citation`（一个 `CITATION` 字段），`add type:bibliography`（在 `APA`/`MLA`/`Chicago` 中渲染所有引用的来源）。`read --view sources` 列出存储；参考文献被缓存（Word 在 `F9` 时重新生成），因此 `bibliography_cached` 警告随之而来。 - **嵌入媒体（pptx）** — `add type:media` 将音频/视频（mp4/mov/m4a/mp3/wav）嵌入为一个 `p:pic`，带有 `a:videoFile`/`a:audioFile`；`src` 和可选的 `poster` 图像通过沙盒解析（转义路径为 `sandbox_denied`）。 - **文本和形状效果** — 在 docx 段落（Word 2010 `w14:` 效果）或 pptx 形状（`a:effectLst`）上设置 `shadow`/`glow`/`reflection`/`outline`；每个效果取 `true`（默认强调）或颜色/对象，`false` 清除。 - **新的幻灯片过渡效果（pptx）** — `split`、`reveal`、`cut`、`zoom`，在 `none`/`fade`/`push`/`wipe` 之上。 这些功能在 `schema` / `office_schema` 中可见，记录在 `aioffice help` 下（新主题 `docx/citation`、`docx/effect`、`pptx/media`、`pptx/effect`；扩展 `charts` / `conditional-format` / `transition`），并通过 `SchemaConsistencyTests` 保持同步。参见 [CONTRACT.md §7a](CONTRACT.md) 和 [CHANGELOG.md](CHANGELOG.md)。 ## MCP（适用于 Claude 和其他代理） ```bash aioffice mcp # 标准输入/输出 MCP 服务器 — 17 个工具，与 CLI 动词 1:1 对应 ``` Claude Desktop / Claude Code 配置： ```json { "mcpServers": { "aioffice": { "command": "aioffice", "args": ["mcp", "--workspace", "/path/to/your/documents"] } } } ``` | MCP 工具 | CLI 动词 | MCP 工具 | CLI 动词 | |---|---|---|---| | `office_create` | create | `office_template` | template | | `office_read` | read | `file_snapshot` | snapshot | | `office_query` | query | `office_status` | doctor | | `office_get` | get | `office_help` | help | | `office_edit` | edit | `office_schema` | schema | | `office_render` | render | `preview_open` | preview open | | `office_validate` | validate | `preview_selection` | preview selection | | `office_audit` | audit | `office_diff` | diff | | `office_convert` | convert | | | `preview_open` / `preview_selection`（实时预览，人类点击选择）注册在 M1（v0.2.0）；`office_audit`（无障碍 + 质量检查）是第 15 个工具，在 M7（v0.8.0）中添加；`office_diff`（语义比较）是第 16 个工具，在 M8（v0.9.0）中添加；`office_convert`（跨格式转换）是第 17 个工具，在 M9（v0.10.0）中添加。总工具模式预算上限为 3,500 个令牌 — 通过测试强制执行，添加 `office_convert` 后仍在预算内。 ## 命令表面（v1.7.0） | 动词 | 摘要 | |---|---| | `create <file> [--from notes.md\|data.csv] [--kind] [--title]` | 新文档（根据扩展名推断类型）— 或 **导入**：`.md` → `.docx`，`.csv` → `.xlsx` | | `read <file> [--view outline\|text\|stats\|structure\|properties\|embeds\|markdown\|csv]` | 廉价的检查投影，按页；`properties` 返回核心 + 自定义文档属性，位于 `data.properties.{core,custom}` 下（所有格式），`embeds` 列出嵌入的 OLE/包对象（所有格式），`markdown` 导出 docx 正文为 GFM，`csv` 导出一个 xlsx 工作表（ `--sheet`， `--range`） | | `query <file> <selector>` | 类似 CSS 的选择器 → 标准路径 (`p[style=Heading1]`，`cell[value>100]`，`shape:contains('Q3')`) | | `get <file> <path>` | 一个节点及其属性 | | `edit <file> --ops <json\|@file>` | **原子** 批量设置/添加/删除/移动/替换/接受/拒绝/**提取** · `--dry-run` · `--expect-rev` · 糖果 `--set/--add/--remove` · 添加类型包括 **`embed`** （任何文件作为 OLE/包对象，所有格式）和 **`equation`** （LaTeX → OMML 数学，docx+pptx）； **`extract`** 将嵌入对象的字节写回 · **文档范围查找/替换糖果** `--find X --replace Y [--regex] [--match-case] [--whole-word]` （docx 正文 + 页眉页脚，每个工作表，每个幻灯片，包括备注；聚合 `{replacements, locations}`；docx 每个命中变成修订版对） | | `render <file> [--to html\|svg\|text\|png\|pdf] [--scope]` | *外观* 步骤 — docx/xlsx 的 html，pptx 每个幻灯片的 svg， **png/pdf** 通过系统浏览器（pptx pdf：整个幻灯片组，一页一个幻灯片） | | `validate <file>` | OOXML 验证 + lint，带有修复建议 | | `audit <file> [--category accessibility\|quality\|all] [--severity error\|warning\|info] [--fix]` | **无障碍 + 质量检查** — 发现是数据 (`ok:true`，退出 0）； `--fix` 仅应用安全的自动修复（替代文本，表格标题，文档/幻灯片标题，孤立书签）并报告 `{fixed, remaining}` | | `diff <file> [<other>] [--snapshot N] [--view summary\|detailed]` | **语义比较** 针对相同格式的文件 *或* 文件本身的快照 — 一个排序的，确定性的 `{changes:[added/removed/modified/moved], summary, baseline}` （更改是数据，退出 0）； `--view summary` 修剪为计数 + 路径 + 类型 | | `convert <src> <dest>` | **跨格式转换** — docx/xlsx/pptx ↔ 彼此（内容中立模型），docx↔md，xlsx↔csv，任意→pdf/png/svg/html。跨格式时有损耗：`data.dropped` + `convert_lossy` 警告名称说明哪些内容未存活下来；相同扩展名 → `invalid_args`，未知目标 → `unsupported_feature` | | `template <file> --data <json\|@file>` | `{{key}}` 在 docx/xlsx/pptx 中合并（分段运行安全） | | `snapshot <list\|restore> <file> [n]` | 预编辑快照环（20） | | `preview <open\|selection\|close> <file> [--port N]` | 实时 localhost 预览；人类点击 → 通过 `selection` 获取标准路径 | | `doctor` | 环境/运行时/处理程序诊断 | | `schema [verb]` | 整个表面的机器可读 JSON | | `help [topic]` | 地址 · 选择器 · 属性-docx/xlsx/pptx · 错误 · **公式** （docx+pptx） · **嵌入** · **rtl** · **章节** · **检查** · **差异** · **转换** · **docx/citation** · **docx/effect** · **pptx/media** · **pptx/effect** | | `mcp` | 标准输入/输出 MCP 服务器 | | `version` | 版本信息 | 全局标志： `--json`（默认当非 TTY 时） · `--pretty` · `--workspace <dir>`（沙盒根目录，默认 cwd，或 `AIOFFICE_WORKSPACE`） · `--quiet`。 退出代码： `0` ok · `2` 用户错误 · `3` 内部/格式错误 · `4` sandbox_denied · `5` unsupported_feature。 **地址**（1-based）： `/body/p[3]` · `/body/table[1]/tr[2]/tc[1]` · `/body/p[3]/omath[1]` · `/Sheet1/A1:C10` · `/Sheet1/table[@name=Sales]` · `/Sheet1/row[2]:row[6]` · `/'Q3 Data'/B2` · `/slide[2]/shape[3]` · `/section[1]` · `/master[1]/layout[2]` · `/` （pptx 幻灯片大小 + 章节） · **M7**： `/properties`（核心 + 自定义文档属性） · `/sdt[@tag=status]` （docx 内容控件） · `/style[@name=Currency-Red]` （xlsx 命名单元格样式） · **M8**： `/caption[@label=Figure][1]` （docx 标题） · `/Sheet1/slicer[1]` （xlsx 切片器） · **M10**： `/embed[1]` · `/Sheet1/embed[1]` · `/slide[2]/embed[@id=7]` （嵌入对象） · `/slide[2]/shape[@id=7]/omath[1]` （pptx 公式）。 **AI 面向的合同** — 稳定的 v1.0 表面（信封形状，冻结错误代码，地址语法，退出代码，操作/视图/工具词汇，以及 [已知限制](CONTRACT.md#10-known-limitations-what-aioffice-does-not-do)）在 **[CONTRACT.md](CONTRACT.md)** 中记录，并作为 `surfaceVersion` （`1.0`）在 `schema` 和 `doctor` 中报告。 ## 当前功能（M0 + M1 + M2 + M3 + M4 + M5 + M6 + M7 + M8 + M9 + M10 + 1.1） | 格式 | M0 (v0.1.0) | + M1 (v0.2.0) | + M2 (v0.3.0) | + M3 (v0.4.0) | + M4 (v0.5.0) | + M5 (v0.6.0) | + M6 (v0.7.0) | + M7 (v0.8.0) | + M8 (v0.9.0) | + M9 (v0.10.0) | + M10 (v0.11.0) | + 1.1 (v1.1.0) | |---|---|---|---|---|---|---|---|---|---|---|---|---| | **.docx** | 创建 · 段落/标题/样式 · 表格 · 文本及格式编辑（粗体/斜体/颜色/对齐/大小）· 查询/获取 · 大纲/文本/统计/结构视图 · HTML 渲染 · `{{key}}` 模板 · 验证 | **页眉/页脚** （创建 + 编辑，`/header[1]/p[1]`）· PNG 渲染 · 实时预览 | **修订记录** （`--track --author`，`read --view revisions`，接受/拒绝通过 `/revision[@id=N]` 或范围）· **评论** （添加/读取/删除，`/comment[@id=N]`）· **自定义样式** （`/styles` 添加，`/style[@id=X]` 设置/获取/删除）· **图片** （PNG/JPEG，沙盒 `src`，保持长宽比） | **列表** （编号/项目符号，嵌套级别，重启；`1.`/`•` 标记在文本视图中，HTML 中真正的 `<ol>/<ul>`）· **超链接** （外部 URL + 书签锚点）· **书签** · **脚注** · **页面设置** （`/section[1]`：页面大小/方向/边距）· **格式修订接受/拒绝** （w:rPrChange/w:pPrChange）· **评论线程** （在 `/comment[@id=N]` 上添加 `type:reply`） | **目录** （`add type:toc`，级别/标题/位置；`/toc[1]` 获取带有条目数量）· **文本水印** （`add type:watermark`，每个标题，自动创建）· **尾注** （`/endnote[@id=N]`）· **分节符** （`add type:sectionBreak`，每节页面设置 — 一份文件中 portrait & landscape）· **查找/替换** （分段安全；`--track` 使每个命中成为 w:del+w:ins 对） | **Markdown 桥** （`create --from notes.md` 导入 GFM — 标题/列表/表格/链接/代码；`read --view markdown` 导出回，结构循环）· **深度表格** （`mergeRight`/`mergeDown`，边框全部/外部/无，阴影，`headerRow` 重复，`columnWidths`，垂直对齐；HTML 中真正的 colspan/rowspan）· **字段** （PAGE/NUMPAGES/DATE/TITLE + `leadingText` — 'Page X of Y' 页脚）· **第一页/偶数页头+页脚变体** （`/header[firstPage]`，自动 `w:titlePg`/`w:evenAndOddHeaders`） | **等式** （`add type:equation` — LaTeX → 真实的 Office 数学；内联 `/body/p[i]/omath[j]` 或显示块； `$…$`/`$$…$$` 在文本视图中；未知命令降级为 `equation_partial` 警告；原始 LaTeX 存储以便忠实读取）· **从右到左 / 双向** （段落 `w:bidi` / 运行 `w:rtl` / 表格 `w:bidiVisual`）· **多列节** （`/section[1]` 上的 `columns`/`columnGap` + `add type:columnBreak`） | **审计** （`audit report.docx [--fix]` — 无替代文本，标题跳过，表格标题，低对比度，文档标题，空/损坏标题，损坏链接，孤立书签；替代文本/标题/书签的安全自动修复）· **文档属性** （设置 `/properties` 核心 + 类型自定义；`read --view properties`）· **内容控件** （`add type:contentControl` 文本/下拉列表/日期/复选框；`/sdt[@tag=X]`；`read --view fields`）· **图片替代文本** （设置 `{alt}`） | **差异** （`diff new.docx old.docx` — 段落/表格/页眉/属性更改为添加/删除/修改/移动，确定）· **标题** （`add type:caption` 图/表/等式 + SEQ；`/caption[@label=Figure][i]`）· **交叉引用** （`add type:crossRef` REF/PAGEREF；`labelAndNumber`/`numberOnly`/`text`/`page`） | **转换** （`convert report.docx deck.pptx` / `report.xlsx` / `report.md` / `report.pdf` — 通过中立模型进行跨格式转换，docx↔md 文本桥，任意→pdf/png/svg/html；`convert_lossy` 名称删除）· **功能检测** （`doctor` 携带动词/工具计数，格式，转换 + 渲染目标，审计类别） | **嵌入对象** （`add type:embed` 任意文件作为 OLE/包对象在 `/body`/tc/页眉/页脚；`read --view embeds`；`extract` 以字节为单位写回；`/embed[i]`）· **统一属性形状** （`read --view properties` → `data.properties.{core,custom}`，在所有格式中相同） | **引用和参考文献** （`add type:source`/`citation`/`bibliography`，`APA`/`MLA`/`Chicago`；`read --view sources`；`bibliography_cached` 警告）· **文本效果** （在运行上设置 `{shadow,glow,reflection,outline}` — Word 2010 `w14:` 效果） | | **.xlsx** | 创建 · 类型单元格写入（数字/布尔/字符串/日期）· **带有缓存值的公式求值** + 诚实警告 · 数字格式 · 合并 · 表格/工作表 · 范围读取 · 按值/公式查询 · HTML 渲染 · 模板 · 验证 | **图表** （条形/线形/饼图，`add type:chart`）· PNG 渲染 · 实时预览 | **数据透视表** （行/列/筛选 + 求和/平均值/计数/最小值/最大值，`pivot[@name=X]`）· **条件格式** （cellIs/colorScale/dataBar/containsText）· **图片** （锚定，PNG/JPEG） | **流式读取** 用于大型工作簿（SAX 读取原始 XML — `read --view stats/text` 和单元格/范围 `get` 无需加载 DOM；41 MB / 33 万行工作簿在 ~2 秒内回答统计数据）· **散点图和面积图** · **定义名称** （`/name[@name=X]`，公式中使用 — `=SUM(SalesData)` 求值）· **冻结窗格** · **自动筛选** · **打印设置** （方向/纸张大小/缩放比例/打印区域） | **批量 2D 写入** （锚定 `set /Sheet1/A2 values:[[…]]` 或精确范围；公式随之而来并求值；>50k 个单元格流入空白工作表通过 SAX）· **行和列** （插入/删除带有公式重写，高度/宽度，隐藏，`col[C]` 字母寻址）· **单元格注释** （添加/读取/删除 + 作者）· **查找/替换** （文本单元格；`inFormulas:true` 进入公式文本） | **CSV 桥** （`create --from orders.csv`：RFC 4180，探测分隔符，类型单元格 — `007` 保留为文本，>50k 个单元格流式传输；`read --view csv [--sheet] [--range]` 导出回）· **数据验证** （从值或源范围的下拉列表；整数/小数/日期/文本长度规则带有运算符；错误样式）· **迷你图表** （线形/柱形/胜负，颜色，标记）· **评论线程** （真正的 `xl/threadedComments` + 通过 `/Sheet1/comment[@id=GUID]` 的回复，旧注释备用）· **单元格超链接** （`https://…` + 内部 `#Sheet!A1`，工具提示） | **就地流式写入** （`stream:true` 或任何 >20 MB 文件通过 SAX 编写器重写工作簿 — 在 50 MB+ 工作簿中设置深单元格和批量写入范围，几秒钟内；结果中 `streamed:true`）· **Excel 表格/列表对象** （在范围上添加 `type:table` — 名称，内置样式，带有求和/平均值/… 的汇总行，结构化引用 `=SUM(Sales[Amount])` 求值；`/Sheet1/table[@name=X]`）· **大纲分组** （在 `row[a]:row[b]` / `col[a]:col[b]` 跨度上添加 `type:group`，`collapsed`，嵌套级别） | **审计** （`audit metrics.xlsx [--fix]` — 公式错误 `#DIV/0!`/`#REF!`，合并数据单元格，图片替代文本，文档标题；替代文本/标题的安全自动修复）· **命名单元格样式** （`add type:cellStyle` 数字格式/粗体/填充/颜色/边框，一次，`set {cellStyle:"X"}` 到范围，`read --view styles`，`/style[@name=X]`）· **文档属性** （设置 `/properties`；`read --view properties`）· **图片替代文本** | **差异** （`diff new.xlsx old.xlsx` — 单元格更改，添加/删除工作表，定义名称，表格为修改/添加/删除）· **切片器** （在表格列或数据透视字段上添加 `type:slicer`，原始 OpenXml 编著；`/Sheet1/slicer[i]`，获取/删除/结构） | **转换** （`convert data.xlsx data.docx` / `.pptx` / `.csv` / `.md` / `.pdf` — 工作表通过中立模型转换为表格，xlsx↔csv 文本桥；图表/数据透视表/图片在 `data.dropped` 中命名 + `convert_lossy`） | **嵌入对象** （`add type:embed` 任意文件锚定在工作表上；`read --view embeds`；`extract` 字节相同；`/Sheet1/embed[i]`）· **统一属性形状** （`data.properties.{core,custom}`）· 方程不可用（Excel 有单元格公式，不是 OMML 数学 → `add type:equation` 返回 `unsupported_feature` 命名解决方法） | **扩展图表** （`doughnut`/`radar`/`bubble`/`stackedBar`/`percentStackedBar`/`stackedArea`/`combo`）· **图标集条件格式** （3/4/5-图标字形集，`reverse`/`showValue`） | | **.pptx** | 创建 (验证器清洁，PowerPoint/Keynote 中打开) · 添加/重新排序/删除幻灯片 · 定位文本形状 (厘米/EMU) · 查询/获取，稳定形状 ID · **每张幻灯片的 SVG 渲染** · 模板 · 验证 | 形状 **填充/字体/颜色/对齐属性** · **主布局读取寻址** · 每张幻灯片的 PNG 渲染 · 实时预览 | **幻灯片背景** （真正的 `p:bg` 实心填充）· **演讲者笔记** (`/slide[i]/notes` 设置/添加/删除/获取）· **图片** (PNG/JPEG，稳定 `shape[@id=N]` 路径) | **原生图表** （带有字面数据缓存的条形/线形/饼图，`/slide[i]/chart[k]`）· **`dataFrom` 跨文档数据** （图表系列直接从工作簿中拉取）· **幻灯片过渡** （淡入/推入/擦除 + 持续时间）· **预设几何形状** （椭圆/三角形/菱形/箭头/圆角矩形 + 线连接器，翻转）· **z 顺序** (`move` 到前面/后面/前面/后面） | **可编辑的图表数据** （新图表嵌入一个真实的工作簿 — 右键单击 → *编辑数据* 在 PowerPoint 中有效；使用 `set {embedData:true}` 改造旧图表）· **进入动画** （出现/淡入/飞入/擦除，方向，点击/与/后触发，`/slide[i]/animation[k]`）· **幻灯片评论** (`add type:comment`，`/slide[i]/comment[@id=N]`) · **查找/替换** （幻灯片范围包括演讲者笔记） | **原生表格** (`add type:table` 行×列，`headerRow`，浅/中/深外观，单元格 `mergeRight`/`mergeDown`，`/slide[i]/table[k]/tr[r]/tc[c]` 路径，SVG 中的真实网格）· **强调和退出动画** （脉冲/生长/旋转/颜色脉冲 · 淡出/飞出/擦除，结构视图中有序）· **评论回复** (`add type:reply` — p15 线程 PowerPoint 2013+ 显示）· **SmartArt 读取** (`/slide[i]/smartart[k]` 嵌套节点树；编辑保留为类型 `unsupported_feature`） | **主布局编辑** (`set /master[m]` 背景 + 主题颜色，`add type:layout` 克隆布局，编辑主/布局形状，使用克隆布局通过 `add type:slide props:{layout:N}`）· **幻灯片节** (`add type:section` 在 `/` 上，`afterSlide` 范围；`read --view outline` 分组幻灯片；生存重新排序）· **幻灯片大小/长宽比** (`set / {slideSize:"4:3"}` 或显式 `width`/`height`）· **动画时间线重新排序** (`move /slide[i]/animation[2] before …`) | **审计** (`audit deck.pptx [--fix]` — 图片替代文本，幻灯片标题，画布外形状，微小字体（<12pt 警告 / <8pt 错误）；安全自动修复替代文本/标题）· **显式替代文本/标题** (`set {altText}`/`{altTitle}` 在形状上；SVG 渲染 `<title>`) | **差异** (`diff new.pptx old.pptx` — 重新排序的幻灯片作为移动，编辑的形状/大小/节/背景作为修改）· **形状超链接/操作** (`set {hyperlink}` url / `#slide:N` 跳转 / `#first…#end` 显示操作， `{linkText}`；获取返回规范形式） | **转换** (`convert deck.pptx outline.docx` / `.xlsx` / `.md` / `.pdf` — 幻灯片内容通过中立模型每张幻灯片一个标题；动画/过渡/图表/SmartArt/嵌入在 `data.dropped` 中命名 + `convert_lossy`） | **嵌入对象** (`add type:embed` 任意文件作为 OLE 对象在幻灯片上；`read --view embeds`；`extract` 字节相同；`/slide[i]/embed[@id=N]`）· **等式** (`add type:equation` — 与 docx 相同的 LaTeX → OMML 转换器，在幻灯片文本框中原生渲染；`/slide[i]/shape[@id=N]/omath[k]`；`equation_partial` 警告；LaTeX 存储以便读取）· **统一属性形状** (`data.properties.{core,custom}`） | **扩展图表** (`doughnut`/`radar`/`bubble`/`stackedBar`/`percentStackedBar`/`stackedArea`/`combo`）· **嵌入媒体** (`add type:media` 音频/视频，沙盒解析 `src`/`poster`)· **形状效果** (`set {shadow,glow,reflection,outline}` → `a:effectLst`)· **新过渡** (`split`/`reveal`/`cut`/`zoom`) | 跨格式在 M3（功能第一） - **`渲染为 PDF`** — docx/xlsx 打印到分页 PDF，pptx 文件夹成为一个 PDF，每个幻灯片一页，通过与 PNG 相同的系统浏览器管道（无浏览器 → 类型 `unsupported_feature` 带有解决方法）。 - **跨文档 `dataFrom`** — `{"op":"add","type":"chart","props":{"dataFrom":"metrics.xlsx!Sheet1/A1:B5"}}` 从实时工作簿数据构建 pptx 图表：第一列 → 类别，标题行 → 序列名称，剩余列 → 序列。在 CLI 和 MCP 上沙盒解析，错误范围候选，相同。 跨格式在 M4 — **所有三种格式的查找/替换合同**: - `{"op":"replace","path":"<scope>","props":{"find","replace","regex?","matchCase?","wholeWord?"}}` 在任何容器路径上工作；路径 `/` 表示整个文档（docx 正文 + 每个标题/页脚，每个工作表，每个幻灯片包括备注）并且每个范围的结果聚合为一个 `{replacements, locations}` 对。 - 跨格式匹配分割成格式运行（docx/pptx）；重写的文本保留第一个受影响运行的格式。正则表达式是 .NET 语法，2 秒匹配预算（超时 → 类型 `invalid_args`）。零命中是 `ok:true` 加 `find_no_match` 警告 — 永远不是错误。 - CLI 糖：`aioffice edit report.docx --find 2025 --replace 2026 [--regex] [--match-case] [--whole-word]`；在 `office_edit` 上相同。 在 docx 上，`--track` 记录每个替换为 `w:del`+`w:ins` 修订对，用于后续接受/拒绝。 跨格式在 M9 — **用于所有格式转换的 `convert` 动词**: - **中立内容模型** — 跨格式对（`docx↔pptx`，`docx↔xlsx`，`pptx↔xlsx`，以及任意格式 `↔ md`）通过共享的 `NeutralDoc` 模型（标题，格式化运行，列表，表格，图像）：源处理器的 `ExportNeutral` 投影到它，目标处理器的 `ImportNeutral` 从它重建一个全新的文件。`INeutralConvertible` 接口存在于 Core（与 M7 `IAuditor` 和 M8 `IDiffer` 相同模式）；三个处理程序中的每一个都实现了它。 - **文本桥重用** — `docx↔md`（M5 markdown 桥）和 `xlsx↔csv`（M5 csv 桥）通过相同的 `convert` 入口实现，而 `xlsx→md` / `pptx→md` 通过中立模型 + 命令层 `NeutralMarkdown` 序列化器骑行。 - **渲染目标** — `any → pdf/png/svg/html/txt` 打开源并路由到渲染层。 - **诚实的损失** — 转换是内容传输并且固有地有损：`data.dropped` 和单个 `convert_lossy` 警告名称未存活的内容（动画，图表，SmartArt，确切样式，公式作为值，markdown 颜色）。目标被全新创建（覆盖 → `convert_overwrite`）；相同扩展名是 `invalid_args`，未知目标是 `unsupported_feature`。 - **自省** — `doctor`（和 `office_status`）现在携带一个 `capabilities` 块：动词计数，MCP 工具计数，支持的格式，转换源/目标，渲染目标和审计类别，以便代理可以通过一次调用了解整个表面。 跨格式在 M10 — **嵌入对象无处不在 + 方程超出 docx + 预 1.0 合同冻结**: - **嵌入对象（`embed` / `extract`）** — 在所有三种格式中嵌入任意文件（源 `.xlsx` 附加到报告，`.pdf`，`.zip`…）作为 OLE/包对象：`add type:embed src=…`（docx `/body`，xlsx `/Sheet1`，pptx `/slide[i]`），`read --view embeds` 列出 `{path,name,mediaType,size,container}`，新的 **`extract`** 操作以字节为单位写回 **（生成操作从不改变源）。** 源文件媒体类型被嗅探；源和提取目标都是沙盒解析的。 - **共享的 LaTeX → OMML 转换器** — M6 方程引擎移入 Core（`AIOffice.Core.Equations`）：纯 `System.Xml.Linq` OMML 生产者，无 `DocumentFormat.OpenXml` 依赖。Word（它加载到 SDK 数学模型）和 **pptx**（新的 — 方程在幻灯片文本框中原生渲染）都使用一个转换器，因此给定的 LaTeX 字符串在两者中渲染相同。xlsx 按设计不可用（单元格公式，不是数学对象）。未知命令仍然降级为 `equation_partial` 警告。 - **统一属性形状** — `read --view properties` 和 `get /properties` 现在在 docx/xlsx/pptx 中返回 `data.properties.{core,custom}` 相同（以前 docx 嵌套，xlsx/pptx 是扁平的）— 一个刻意的预 1.0 一致性修复。 - **合同冻结** — 稳定的 v1.0 AI 接口表面在 **[CONTRACT.md](CONTRACT.md)** 中记录，并通过 `surfaceVersion` 字段（`1.0`）在模式和 `doctor` 功能中声明：信封形状，冻结的错误代码集，寻址语法，退出代码和操作/视图/工具词汇。 ## 架构 ``` ┌─────────────────────────────────────────────┐ 代理/人类 → │ src/AIOffice.Cli (aioffice, 18 动词) │ MCP 客户端 → │ src/AIOffice.Mcp (标准输入输出, 17 工具, 1:1) │ ├─────────────────────────────────────────────┤ │ src/AIOffice.Render (通过浏览器生成 png/pdf) │ │ src/AIOffice.Preview (实时点击选择) │ └──────────────┬──────────────────────────────┘ │ 信封 · 地址 · 选择器 ┌──────────────▼──────────────────────────────┐ │ src/AIOffice.Core │ │ 信封/错误 · 文档路径 · 选择器 │ │ 工作空间沙箱 · 快照存储 · 版本 │ └───────┬──────────────┬──────────────┬───────┘ │ │ │ ┌───────▼─────┐ ┌──────▼───────┐ ┌────▼────────┐ │AIOffice.Word│ │AIOffice.Excel│ │AIOffice.Pptx│ │ OpenXml SDK │ │ ClosedXML │ │ OpenXml SDK │ └───────┬─────┘ └──────┬───────┘ └────┬────────┘ ▼ ▼ ▼ .docx .xlsx .pptx (无损 OOXML) ``` ## 质量 源于对一款优秀的办公 CLI 的研究，该 CLI 附带 **零自动化测试** — AIOffice 采取了相反的立场： - **2331 个测试**，跨越 7 个项目（Core 180 · Word 681 · Excel 619 · Pptx 709 · MCP 87 · Preview 24 · Render 31），每次提交都通过。 - **往返验证**: 打开 → 保存时不进行任何编辑，必须使每个 zip 部分在字节级别保持相同；记录的例外情况会被精确断言。 - **独立验证**: OpenXmlValidator 在每次变更测试后必须报告 0 个错误 — 该工具从不自我评分。 - **CI 矩阵**: macOS 14 + Windows，构建时将警告视为错误，运行黄金脚本，发布并测试单文件二进制。 - **发布自动化**: 推送 `v*` 标签时，会构建、测试、发布所有 6 个单文件二进制 + `SHA256SUMS`，并使用 `scripts/release-notes-template.md`（编辑标签前）中渲染的发布说明创建 GitHub 发布 — 参见 `.github/workflows/release.yml`。 - **人工检查**: 在 `fixtures/manual-check/` 中为真实 Office 打开生成的文档。 ## 路线图 - **M0** — 以上所有内容；单文件发布；macOS + Windows 上的 CI。 - **M1（已发布，v0.2.0）** — PNG 渲染（系统浏览器检测）· `preview_open`/`preview_selection`（实时预览，人类点击选择）· docx 页眉/页脚 · pptx 主布局读取寻址 · xlsx 图表（条形/线形/饼形）。 - **M2（已发布，v0.3.0）** — 跟踪更改（`--track`/`--author`，接受/拒绝）· 评论 · 样式管理 · 数据透视表 · 条件格式 · 图片（所有三种格式）· pptx 背景和演讲者备注 · 文件大小保护（`file_too_large`，`AIOFFICE_MAX_FILE_MB`）。大文件 *流式* 未发布：它需要一个专门的基准测试驱动的传递；M2 发布了一个大小保护 - 移至 M3。 - **M3（已发布，v0.4.0）** — 功能第一：docx 列表/链接/书签/脚注/页面设置/格式修订解决/评论回复 · xlsx 流式读取（SAX）/ 散点图 + 面积图 / 定义名称 / 冻结 / 自动筛选 / 打印设置 · pptx 原生图表/过渡/预设几何体/z-order · 跨文档 `dataFrom`（xlsx 数据 → pptx 图表，CLI 和 MCP）· `render --to pdf`（分页 docx/xlsx；pptx 每张幻灯片一页）· 大小上限翻转为选择加入（默认无限制）。 - **M4（已发布，v0.5.0）** — 所有三种格式的 **查找/替换** 合同（分段运行安全，带超时正则表达式，文档范围 `"/"` 作用域，CLI `--find/--replace` 糖果，docx 跟踪修订对）· docx **目录 / 水印 / 结尾注释 / 分节符** · xlsx **批量 2D 写入**（SAX 流式写入空白表格）/ **行和列操作** / **单元格注释** · pptx **可编辑图表数据**（嵌入式工作簿，PowerPoint 中的 Edit-Data，`embedData:true` 改造）/ **进入动画** / **幻灯片评论** · 标签驱动的 **发布自动化**。 - **M5（已发布，v0.6.0）** — **markdown/csv 桥**: `create --from`（`.md` → `.docx` 通过 Markdig，`.csv` → `.xlsx` 类型导入）+ `read --view markdown|csv` 导出可以循环 · docx **深度表格**（合并/边框/阴影/列宽/标题行）/ **字段**（PAGE/NUMPAGES/DATE/TITLE）/ **第一页和偶数页页眉/页脚变体** · xlsx **数据验证**（下拉菜单 + 规则）/ **迷你图** / **线程评论 + 回复** / **单元格超链接** · pptx **原生表格**（合并 + 外观）/ **强调和退出动画** / **评论回复** / **SmartArt 读取** · `IFormatHandler.CreateFrom` 导入钩子（累加，默认 `unsupported_feature`）。 - **M6（已发布，v0.7.0）** — **深水通道**: docx **方程式**（一个手工卷积 LaTeX → Office Math 转换器，内联/显示，矩阵，部分降级警告，LaTeX 存储以实现忠实回读）/ **从右到左和双向**（段落/运行/表格）/ **多列章节**（+ 分段符）· xlsx **就地流式写入**（重写一个 50 MB+ 工作簿通过 SAX 编写器）/ **Excel 表格**（ListObjects + 总计 + 结构化引用）/ **大纲分组**（行/列跨度）· pptx **主布局编辑**（背景，主题强调，克隆布局）/ **幻灯片章节** / **幻灯片大小和宽高比** / **动画时间线重新排序** · 新的寻址形式 `/`（演示文稿根），`/body/p[i]/omath[j]`，`/section[i]`，`row[a]:row[b]` 跨度，可编辑 `/master[1]/layout[i]`。 - **M7（已发布，v0.8.0）** — **发布前审计**: 一个共享的 `audit` 动词 + `office_audit` MCP 工具（第 15 个工具）跨所有三种格式 — 可访问性和质量检查，其中发现是 *数据*（`ok:true`，退出 0），带有仅安全的 `--fix`（占位符替代文本，表格标题行，文档/幻灯片标题，孤立书签）报告 `{fixed, remaining}` · docx **文档属性**（核心 + 类型自定义）/ **内容控件**（文本/下拉菜单/日期/复选框，`read --view fields`）/ 图片替代文本 · xlsx **命名单元格样式**（`add type:cellStyle`，`read --view styles`）/ 文档属性 / 公式错误 + 合并数据单元格 + 替代文本审计 · pptx 替代文本/标题/阅读顺序审计 + 显式 `altText`/`altTitle` / 文档属性 · 新的寻址形式 `/properties`，`/sdt[@tag=X]`，`/style[@name=X]`；`office_read` 视图枚举获得 `properties`/`fields`/`styles`。 - **M8（已发布，v0.9.0）** — **差异和评审**: 一个共享的 `diff` 动词 + `office_diff` MCP 工具（第 16 个工具）跨所有三种格式 — 语义比较另一个相同格式的文件 *或* 文档自己的编辑前快照，返回一个排序的，可确定的 `{changes:[added/removed/modified/moved], summary, baseline}`（更改是 *数据*，退出 0；LCS/内容哈希区分移动；`--view summary` 修剪到路径 + 类型）· docx **标题**（Figure/Table/Equation + SEQ）/ **交叉引用**（REF/PAGEREF，`labelAndNumber`/`numberOnly`/`text`/`page`）· xlsx **切片器**（表格列 / 数据透视字段，由原始 OpenXml 编写）· pptx **形状超链接 / 操作**（url / `#slide:N` 跳转 / `#first…#end` 显示操作 / `linkText`）· 新的寻址形式 `/caption[@label=Figure][i]`，`/Sheet1/slicer[i]`。 - **M9（已发布，v0.10.0 — pre-1.0 巅峰）** — **跨格式转换**: 一个共享的 `convert` 动词 + `office_convert` MCP 工具（第 17 个工具）— docx/xlsx/pptx ↔ 彼此通过内容中立模型（`NeutralDoc` + `INeutralConvertible`，与 `IAuditor`/`IDiffer` 相同的核心接口模式） ，`docx↔md` 和 `xlsx↔csv` 通过 M5 文本桥，任何格式 ↔ markdown 通过 `NeutralMarkdown` 序列化器，和 `any → pdf/png/svg/html` 通过渲染层；由于本质上是有损的，因此 `data.dropped` + 一个 `convert_lossy` 警告名称说明了什么没有存活下来 · **1.0 硬化**: 每个 CLI 动词都有一个帮助主题，并在 `schema` 中出现（新的 `convert` 帮助主题与 `(src→dest)` 矩阵），`doctor`/`office_status` 获得一个 `capabilities` 反思块（动词 + 工具计数，格式，转换源/目标，渲染目标，审计类别）。 - **M10（已发布，v0.11.0 — 1.0 之前最后一个功能里程碑）** — **文档智能 II**: **嵌入对象** 跨所有三种格式（`add type:embed` 任意文件作为 OLE/package 对象，`read --view embeds`，新的 **`extract`** 操作将有效载荷写回字节相同；`/embed[i]`，`/Sheet1/embed[i]`，`/slide[i]/embed[@id=N]`；源和目标沙盒解析）· **pptx 方程式** 通过一个共享的 LaTeX → OMML 转换器提取到 Core（`AIOffice.Core.Equations`，一个纯 `System.Xml.Linq` 生产者；Word 和 Pptx 消耗一个引擎；`/slide[i]/shape[@id=N]/omath[k]`；xlsx 由于设计原因不可用）· **1.0 合同准备**: `read --view properties` / `get /properties` 信封在所有三种格式上统一为 `data.properties.{core,custom}`，一个稳定的 **`surfaceVersion`**（`1.0-rc`）在 `schema` 和 `doctor` 功能中声明，并且冻结的 AI 接口合同在 **[CONTRACT.md](CONTRACT.md)** 中编写。嵌入和方程式依赖于 `office_edit`/`office_read` — 仍然 **17 个 MCP 工具**。 - **1.0.0（已发布 — API 稳定性版本）** — **稳定化，而不是新功能**: `surfaceVersion` 提升到 **`1.0`**； [CONTRACT.md](CONTRACT.md) 最终确定为冻结的 v1.0 表面，并具有 **稳定性承诺** 和 **已知限制** 部分； CLI 和 MCP 内省表面在共享词汇上锁定同步（一个 `SchemaConsistencyTests` 守护程序在漂移时变红）；`read --view` 枚举 + `edit` 操作列表现在在两个表面上公开 `embeds` / `extract`; xlsx 读取视图回声 `data.view`; xlsx 转换现在通过 `data.dropped` + `convert_lossy` 报告图表/数据透视/图像丢失（无更多静默丢失）；完整的 **警告代码词汇表** 被集中，记录并在 `schema` 中显示为 `data.warningCodes`; 寻址帮助文档 M8–M10 `embed` / `omath` 形式。 18 个动词 / 17 个 MCP 工具，**1590 测试** 在 macOS + Windows 上通过。 - **1.1.0（已发布 — 1.0 后的第一个功能版本，仅增加）** — `surfaceVersion` **保持 `1.0`**（每个更改都存在于冻结的 1.0 合同线内）：**扩展图表类型** 在 xlsx *和* pptx 上（`doughnut`/`radar`/`bubble`/`stackedBar`/`percentStackedBar`/`stackedArea`/`combo`，在 `bar`/`line`/`pie`/`scatter`/`area` 之上）· xlsx **`iconSet` 条件格式**（3/4/5 个图标字形集）· docx **引用和参考文献**（`add type:source`/`citation`/`bibliography`，`read --view sources`，`bibliography_cached` 警告）· pptx **嵌入媒体**（`add type:media` 音频/视频，沙盒解析的 `src`/`poster`）· docx 运行和 pptx 形状 **文本/形状效果**（`shadow`/`glow`/`reflection`/`outline`）· pptx **新过渡**（`split`/`reveal`/`cut`/`zoom`）。新的 `add` 类型，一个新的 `read --view`（`sources`），一个新警告 — 所有增加的，由 `SchemaConsistencyTests` 保护。 18 个动词 / 17 个 MCP 工具不变，**1692 测试** 在 macOS + Windows 上通过。 - **1.2.0（已发布 — 1.0 后的第二个功能版本，仅增加）** — `surfaceVersion` **保持 `1.0`**（操作类型不变 — `group`/`ungroup` 是 `add` **类型**）：pptx **SmartArt 创建**（`add type:smartart`，`list`/`process`/`hierarchy`/`orgChart`/`cycle`），**连接器**（`add type:connector`，直线/弯曲/直线 + 箭头），**分组**（`add type:group`/`ungroup`）· docx **图示**（`tableOfFigures` + `figures_cached`），**索引**（`indexEntry`/`index` + `index_cached`），**邮件合并字段**（`mergeField`，由 `template` 旁边填充 `{{key}}`）· xlsx **表单控件**（`formControl`: 复选框/选项按钮/旋转器/组合框/列表框/按钮），**轻保护**（单元格 `locked` + 工作表 `protected` + 工作簿 `protectStructure`），**数字格式预设**（`accounting-usd`/`percent`/`date-iso`/…）。新的 `add` 类型和属性键，两个新的警告 — 所有增加的，由 `SchemaConsistencyTests` 保护。 18 个动词 / 17 个 MCP 工具不变，**1807 测试** 在 macOS + Windows 上通过。 - **1.3.0（已发布 — 1.0 后的第三个功能版本，仅增加）** — `surfaceVersion` **保持 `1.0`**（操作类型不变）：xlsx + pptx **图表润色**（`dataLabels`/`legend`/`axisTitles`/`trendline`/`errorBars`/`gridlines`/`secondaryAxis`，在 `add` 和 `set /…/chart[k]`）· xlsx **高级条件格式**（`formula`/`topBottom`/`aboveBelowAverage`），**数据透视计算字段**（`calculatedFields`）· docx **形状和文本框**（`add type:shape`/`textBox`），**旧表单字段**（`add type:formField），**主题编辑**（`set /theme`）· pptx **3D 模型**（`add type:model3d`，`model3d_as_media` 警告），**运动路径动画**（`motionPath` 效果）。新的 `add` 类型（`shape`/`textBox`/`formField`/`model3d`），新的属性键，`/theme` 寻址表单，一个新的警告 — `office_help`,不使用工具模式）。 18 个动词 / 17 个 MCP 工具不变，**1924 测试** 在 macOS + Windows 上通过。 - **1.4.0（已发布 — 1.0 后的第四个功能版本，仅增加）** — `surfaceVersion` **保持 `1.0`**（操作类型不变）； **关闭动态数组差距**: xlsx **动态数组求值 + 溢出**（`=FILTER`/`UNIQUE`/`SORT`/`SORTBY`/`SEQUENCE`/`RANDARRAY`/`TRANSPOSE` 评估并溢出，锚点报告 `spillRange`，阻止溢出 → `spill_blocked`），**财务函数**（`RATE`/`IRR`/`XIRR`/`NPV`/`PV`/`FV`/`PMT`/`NPER` 评估并缓存 — 这些不再引发 `formula_not_evaluated`），**假设数据表**（`add type:dataTable`）· docx **邮件合并执行**（`template` 动词在 `--data` 是记录数组时运行合并； `--output` 模式每个记录或组合文档； `office_template` 增加了一个可选的 `output`），**IF 字段**（`add type:ifField`），**页面边框**（`set /section[i] {pageBorder}`）· pptx **幻灯片缩放**（`add type:zoom`），**点击触发动画**（`triggerOn:"@N"`），**表格样式**（`add type:table {style, firstRow/lastRow/bandRow/firstCol}`）。新的 `add` 类型（`dataTable`/`ifField`/`zoom`），新的属性键，新的寻址形式（`/Sheet1/dataTable[i]`，`/slide[i]/zoom[k]`），扩展的 `template` 行为，一个新的错误代码（`spill_blocked`） — 所有增加的，兼容并向后兼容，由 `SchemaConsistencyTests` 和 token-budget 测试保护（新表面在 `office_help` 中记录）。 18 个动词 / 17 个 MCP 工具不变，**2016 测试** 在 macOS + Windows 上通过。 - **1.5.0（已发布 — 1.0 后的第五个功能版本，仅增加）** — `surfaceVersion` **保持 `1.0`**（操作类型不变）； **关闭现代标量函数差距**: xlsx **标量求值**（`=XLOOKUP`/`IFS`/`SWITCH`/`LET`/`MAXIFS`/`MINIFS`/`AVERAGEIFS` 评估并缓存 — 无更多 `formula_not_evaluated`; `=TEXTSPLIT` 溢出），**场景管理器**（`add type:scenario` + `set {applyScenario}`，重新计算），**目标搜索**（`set {goalSeek:{targetCell,targetValue}}`，`goal_seek_no_solution` 警告）· docx **表格单元格公式**（`set {formula}` 在单元格上 → 缓存的 `w:fldSimple`，`table_formula_cached` 警告），**构建块**（`add type:buildingBlock`/`buildingBlockRef`），**行号**（`set /section[i] {lineNumbers}`）· pptx **嵌入字体**（`add type:font` 在 `/fonts` 上，`embedAll`），**动作按钮**（`add type:actionButton`），**自定义布局**（`add type:layout {placeholders}` + 幻灯片 `layoutName`）。新的 `add` 类型（`scenario`/`buildingBlock`/`buildingBlockRef`/`font`/`actionButton`），新的属性键（`applyScenario`/`goalSeek`/`formula`/`lineNumbers`/`embedAll`/`placeholders`），新的寻址形式（`/Sheet1/scenario[@name=…]`，`/buildingBlock[@name=…]`，`/fonts`），两个新的警告代码（`goal_seek_no_solution`，`table_formula_cached`） — 所有增加的，并兼容并向后兼容，由 `SchemaConsistencyTests` 和 token-budget 测试保护（新表面在 `office_help` 中记录）。 18 个动词 / 17 个 MCP 工具不变，**2125 测试** 在 macOS + Windows 上通过。 - **1.6.0（已发布 — 分发和部署，无功能变化）** — `surfaceVersion` **保持 `1.0`**；二进制文件在字节级别上与 1.5.0 相同。添加了二进制文件周围的打包/部署层（npm 包，Homebrew 公式，一键安装脚本，`SKILL.md` + 食谱/安装/MCP-设置/签名文档），几乎完全在 C#/.NET 源代码树之外。 18 个动词 / 17 个 MCP 工具不变，**2125 测试** 通过。 - **1.7.0（已发布 — 1.0 后的第六个功能版本，仅增加）** — `surfaceVersion` **保持 `1.0`**（操作类型不变；无新动词/工具）；完善 **打印就绪度**，**相机工具**，**计算模式** 和 **方程式深度**：xlsx **打印完整性**（`printTitleRows`/`printTitleCols`/`pageBreaks`/`fitToPage`/center/gridlines/headings/`printHeader`/`printFooter`），**链接图片 / 相机工具**（`add type:linkedPicture`，`linked_picture_static` 警告），**计算设置**（`set /` `calculationMode`/`iterativeCalc`/…）· docx **首字母缩略**（`set {dropCap,…}`），**图片水印**（`add type:watermark {image}`），**STYLEREF/SYMBOL/QUOTE 字段**，**编号显示方程式**（`number:…`，`/equation[@num=…]`）· **更深的 LaTeX→OMML** 由 docx+pptx 共享（`\begin{aligned|gathered|cases}`，`\binom`，`\overbrace`/`\underbrace`，`\iint`/`\iiint`，更多口音/关系 — 更少的 `equation_partial` 警告）· pptx **备注/讲义母版**（`/notesMaster`，`/handoutMaster`），**动画计时**（`repeat`/`rewind`/`autoReverse`），**表格单元格对齐**（`valign` / 边距 / `textDirection`）。新的 `add` 类型（`linkedPicture`），新的寻址路径（`/notesMaster`，`/handoutMaster`），新的寻址（`/SheetN/linkedPicture[i]`，`/equation[@num=…]`），新的属性键，两个新的警告代码（`linked_picture_static`，`equation_numbers_cached`） — 所有增加的，并兼容并向后兼容，由 `SchemaConsistencyTests` 和 token-budget 测试保护（新的 `office_help` 主题 `print-setup`/`masters`）。 18 个动词 / 17 个 MCP 工具不变，**2331 测试** 在 macOS + Windows 上通过。 ### 1.0 之后（候选想法，不做承诺） 1.0 是 API 稳定性线；这里的任何内容都是 **增加** 的，并受合同的仅增加承诺约束： - **插件机制** — 在运行时发现外部格式处理程序，以便第三方可以在不分叉的情况下添加格式。 - **更准确的转换保真度** — 更细致的 `data.dropped` 粒度；可选地，通过中立模型携带更多样式。 - **xlsx 润色** — sheetView RTL，现代线程评论优化。 - **pptx 动画深度** — 完整的上游强调/退出预设集，多效果链，重复/自动反转（运动路径已在 1.3 中发布）。 ## 设计声明 AIOffice 的表面 **故意不兼容** 现有的 office CLI：能力对齐是目标，但动词、标志和寻址语法是从头开始为代理设计的 — 更小、更可预测、可内省。一个思维模型，两种传输（CLI 和 MCP）。 ## 文档 **开始使用：** [docs/INSTALL.md](docs/INSTALL.md) — 所有四种安装路径 · [docs/MCP-SETUP.md](docs/MCP-SETUP.md) — 将其连接到 Claude / Cursor / 任意 MCP 主机 · [SKILL.md](SKILL.md) — 面向 AI 的入职指南 · [docs/COOKBOOK.md](docs/COOKBOOK.md) — 10 个复制粘贴的食谱 · [docs/SIGNING.md](docs/SIGNING.md) — 代码签名/公证路线图 **参考：** [docs/DESIGN.md](docs/DESIGN.md) — 架构和表面规范 · [docs/MCP.md](docs/MCP.md) — MCP 工具规范 · [docs/PARITY.md](docs/PARITY.md) — 能力对账单 · [CONTRACT.md](CONTRACT.md) — 冻结的 v1.0 面向 AI 的表面 · `aioffice help <topic>` — 内置渐进式文档 · [SMOKE_REPORT.md](SMOKE_REPORT.md) — 真实的端到端验证日志 ## 许可 [MIT](LICENSE)。请参阅 [THIRD-PARTY-NOTICES.md](THIRD-PARTY-NOTICES.md) — 所有依赖项都是许可的（MIT: DocumentFormat.OpenXml, ClosedXML, ModelContextProtocol C# SDK; BSD-2-Clause: Markdig); 没有捆绑的第三方二进制文件。