#本地 Office 引擎

本地 Office 引擎用于在不启动桌面 Office 的情况下读取、校验和修改 DOCX、XLSX、 PPTX 与 PDF。CLI、MCP、Rust API 和 Office Skill 使用同一套类型化协议，不通过 浏览器界面录制操作。

#组件关系

编码智能体 / 人工终端 / MCP 客户端
                 │
                 ▼
          a3s-office CLI / MCP
                 │
                 ▼
       类型化命令、选择器与批处理协议
                 │
                 ▼
        Rust Office 核心与格式适配器
        ├── OOXML 包读取与写回
        ├── 语义视图和校验
        ├── 原子修改与精确回放
        ├── 文件监听和证据输出
        └── 可选的宿主 PDFium 提供器

引擎只处理用户指定的本地文件。它不会自动上传文档、下载运行时或调用 AI 服务。

#典型流程

先检查文件，再读取目标结构，执行边界明确的修改，最后重新读取或校验。

a3s-office validate report.docx --json
a3s-office view report.docx outline --json

a3s-office set report.docx /body \
  --find Draft \
  --replace Final \
  --json

a3s-office validate report.docx --json
a3s-office view report.docx outline --json

修改命令使用临时输出和原子替换，失败时不应发布部分写入。批处理包含协议版本、限制和 明确操作集合，便于智能体重放与审计。

#语义读取

view 返回面向决策的结构，而不是压缩包内部 XML。常用视图包括文档目录、段落与表格， 工作簿工作表和区域，演示文稿幻灯片与对象，以及 PDF 页清单、文本层和目录。所有结果 都可以使用 --json，并带有足够的文件与协议信息用于后续断言。

#修改协议

选择器定位文件中的结构化目标，类型化参数描述具体变化。执行前会检查格式、目标、限制 和属性组合；不支持或有歧义的操作返回明确错误，不会靠关键词推断用户意图。

一次批处理可以包含多项修改，并以同一版本边界进行校验、应用和提交。需要可重复执行时， 使用精确回放产物，而不是重新解析终端自然语言。

#PDF 提供器

PDF 页面渲染、文本层与目录读取使用显式传入的 PDFium 动态库。引擎不会联网下载 PDFium。读取首先建立完整、经过校验的页面清单，再在同一不可变源文件上执行有范围的 页面操作；源文件或渲染配置变化时，旧清单不能继续授权结果。

#安全与资源边界

• 输入大小、页数、节点数、修改数和输出证据都有上限。
• 路径、压缩包条目和关系目标在读取前校验，避免目录穿越与压缩炸弹。
• 写入先在内存或临时文件完成，通过全部校验后再原子发布。
• JSON 错误区分无效请求、不支持能力、资源限制和运行失败。
• CLI 与 MCP 不把终端描述文字当作稳定协议。
• 文件监听只持有本次命令创建的资源，并在退出时有界清理。

#与浏览器编辑器的关系

浏览器组件面向实时交互，本地引擎面向确定性文件自动化。两者共享类型化边界和格式 语义，但不会让 CLI 去操作浏览器 DOM，也不会让浏览器组件直接取得本地文件系统权限。

完整格式矩阵、选择器、批处理协议与 PDF 证据字段见 English 完整工程参考。