For AI agents: the complete documentation index is available at https://a3s-lab.github.io/Office/docs/0.38.0/llms.txt, the full documentation bundle is available at https://a3s-lab.github.io/Office/docs/0.38.0/llms-full.txt, and this page is available as Markdown at https://a3s-lab.github.io/Office/docs/0.38.0/native-office-engine.md.
A3S Office
  • 简体中文
  • 0.38.0

      • 本地 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，并带有足够的文件与协议信息用于后续断言。

      修改协议

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

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

      原生实时协作

      Rust 核心使用 Yrs，并与浏览器共享 a3s.office.collaboration 协议和标准 Yjs v1 更新。每个持久副本绑定文件、参与者、模式、命名空间与 53 位客户端 ID。更新日志、 checkpoint 和操作回执原子发布；乱序依赖到达后会通过有界规范重放收敛，重复操作保持 幂等。

      类型化修改覆盖 Markdown、受范围约束的 Document 文本/段落/选项、选区评论及文字建议、 Spreadsheet 单元格、Presentation 场景对象，以及 PDF 表单值、批注、脱敏与页面操作审核。 Document 投影版本 3 返回评论、回复、解决/脱离锚点状态、实时建议、不可变最终决定， 以及段落内精确的 UTF-16 锚点或建议位置。 document-comment-create、document-comment-reply、 document-comment-set-resolved 与 document-comment-delete 使用与浏览器一致的记录、 不可变声明和选区 Mark；它们接受 edit 或 Document comment，并限制评论模式只能 删除当前副本 Actor 自己的记录。 Yrs 传输授权路径还会在持久化前把经过认证的 Document suggest 更新作为候选状态校验。 带身份的文字建议可以变化，但规范内容和所有非建议 Root 必须保持等价。 document-suggestion-create 会匹配投影中的稳定段落、当前文字 ID、精确 UTF-16 选区和 原文，并由 suggest 副本创建带认证 Actor 的插入、删除或原子替换建议。 document-suggestion-decide 允许 edit 副本原子匹配一批完整建议身份，接受或拒绝修订， 并追加与浏览器兼容、带 Actor 的不可变审核记录。CLI、MCP 和 A3S Code 共享这组封闭修改。 Spreadsheet 修改保留浏览器的字段寻址与密集/稀疏投影。Presentation 可在幻灯片、 母版或版式中创建、按顶层字段乐观更新、移动或写墓碑删除一个稳定对象；规范创建声明会 拒绝同 ID 的不同对象，移动通过稳定的观察前驱与目标前驱修改该对象自己的顺序项，精确 删除后 ID 不可复用。目标位置已满足时移动保持幂等；源位置过期或锚点失效时不会产生 持久更新。对象字段、其他对象和整个容器不会因移动被覆盖。PDF 批注使用真实 EmbedPDF 数据结构， 支持创建、按 JSON 叶子进行乐观更新和不可逆删除；脱敏、旋转、删除、重排及最终决定 采用只追加记录，并从副本身份派生参与者归属。PDF 源文件和签名字节不会进入 Yjs。

      公开的 documentStateSha256 使用排序状态向量和规范逻辑根计算，因此包含对象数组的 批注在重启或乱序投递后仍得到一致摘要。内部提交判断继续覆盖原始 Yjs 待处理结构，避免 把尚缺因果依赖的更新误判为无变化。

      PDF 提供器

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

      安全与资源边界

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

      与浏览器编辑器的关系

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

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