#浏览器编辑器架构

A3S Office 是一套可以嵌入业务应用的完整编辑器组件。它在产品边界采用 Headless 设计：组件库负责编辑模型、命令、渲染和编辑器界面；宿主负责文件保存、身份权限、 协作、应用导航和 AI 服务。

#总体结构

宿主应用
├── 文件、权限、协作、版本与 AI
└── A3S Office 公共接口
    ├── React / Vue / Web Component
    ├── 受控内容模型与宿主事件
    ├── 编辑器界面
    │   ├── Document：TipTap / ProseMirror
    │   ├── Markdown：源码 + TipTap
    │   ├── Spreadsheet：工作簿与计算模型
    │   ├── Presentation：场景图 + 按需文本编辑
    │   └── PDF：PDFium 渲染与批注
    └── 计算与文件能力
        ├── Web Worker
        ├── Rust / WebAssembly 内核
        └── DOCX、XLSX、PPTX、Markdown 与 PDF 导入导出

这条边界保证同一编辑器可以进入不同产品，而不把某一种后端、账号系统或 AI 模型 写死在组件中。

#单一内容来源

每种编辑器都保留与文件格式和交互方式匹配的主模型，而不是把所有格式压成一份 HTML。

HTML 只在兼容边界使用，不是所有 Office 文件的持久化真相。这样才能保留分页、公式、 母版、批注和对象几何等格式语义。

#文档排版管线

Document 的逻辑内容始终由同一个 TipTap 编辑器持有。排版流程读取结构化文档、页面 设置和字体清单，完成文本塑形、可视行测量、分页与页面元素定位，再把结果同时交给编辑、 只读预览和浏览器 PDF 导出。

受控文档
  → TipTap 事务与结构化模型
  → 字体解析、回退与文本塑形
  → 可视行测量
  → 分节、分页、表格续排与浮动对象约束
  → 页面栈
      ├── 编辑界面
      ├── 只读预览
      └── PDF 导出

耗时且可取消的计算放进 Worker。Rust / WebAssembly 内核负责需要确定性和跨界面一致的 部分；DOM 测量只用于浏览器特有或暂未进入内核的内容。新的计算结果带版本，过期任务 不会覆盖更新后的文档。

#Extension 边界

Document 与 Markdown 可以接收 TipTap Extension。宿主应保持 Extension 数组引用 稳定，并确保名称唯一。自定义 Node 或 Mark 如果需要经过 DOCX 或 Markdown 往返后 继续存在，还必须提供对应的解析和序列化语义。

Spreadsheet、Presentation 与 PDF 目前通过 fileActions、onAgentRequest、 loadSource、onSave 和放映事件等类型化接口扩展。内部命令上下文尚未承诺兼容性， 因此不会作为公共 API 暴露。

#文件与运行时资源

编辑器实现按类型拆包。打开某一种文件时才加载对应组件、Worker、字体或 PDFium 资源； 宿主也可以在可预期的导航前调用预加载 API。组件不要求 A3S 后端，资源地址可由宿主 覆盖，以适配 CDN、离线环境和内容安全策略。

#正确性原则

• 受控内容是宿主与编辑器之间的唯一状态协议。
• 编辑、预览与导出尽量复用同一排版结果，避免三套视觉逻辑。
• 不支持的文件语义要明确报告，不能静默丢弃或伪装成高保真结果。
• 异步命令必须检测过期选区和过期文档版本。
• 快捷键、弹窗、菜单与焦点行为属于编辑器公共质量，不由宿主重复实现。
• 大文档计算必须有边界、可取消，并避免随页数无上限挂载 DOM。

#当前边界

当前架构已经覆盖五类编辑器的公共组件、受控模型、按需加载和主要文件流程，但仍需继续 提高 DOCX 字体替代、段落与分页、复杂表格、浮动对象、母版继承、公式兼容性和可搜索 矢量 PDF 等能力。对 WPS / Word 的视觉一致性必须用真实 OOXML 文件、固定字体与 逐页截图证据验证，不能只用简单 HTML 示例判断。

需要逐模块实现清单、协议字段和性能门槛时，请切换到 English 完整工程参考。