# 04. OnlyOffice Integration Boundary v0

更新时间：2026-04-11
适用范围：`/mnt/Data1T/mnote-rust`

---

## 1. 目标

本文件定义 `mnote-rust` 中 OnlyOffice 的正式边界。

它要解决的问题：

- OnlyOffice 在系统里到底是什么
- 可以接多深
- 哪些能力该放进插件/编辑器侧
- 哪些能力必须留在 Rust 内核
- 官方现状已经支持到哪一步，哪些不是猜想

---

## 2. 基于官方资料的确定事实

以下判断基于 ONLYOFFICE 官方文档与官方 API 文档，而不是推测。

### 2.1 ONLYOFFICE 已有官方 AI 插件能力

官方文档已明确：

- ONLYOFFICE 提供 **AI 插件**
- 可接入多种模型提供商，例如 **OpenAI、DeepSeek**
- 支持的能力包括但不限于：
  - 文本生成
  - 文本编辑
  - 总结
  - 自动创建宏
  - 面向编辑器的 AI 辅助操作

这说明：

> OnlyOffice 不是一个“完全不懂 AI 的富文档编辑器”，而是已经具备官方 AI 扩展体系。

### 2.2 ONLYOFFICE 已有插件系统

官方文档明确支持：

- 自定义插件
- 插件 UI 集成
- 插件调用外部服务
- 插件与编辑器文档内容交互
- 插件注册、安装、配置与运行

这说明后续你完全可以：

- 做自有 AI 插件
- 做面向 mnote-rust 的桥接插件
- 把系统命令面引入编辑器环境

### 2.3 Office JS API 已能做深度文档操作

官方 API 文档与样例表明，插件/脚本可进行：

- 获取文档对象 `Api.GetDocument()`
- 获取当前选区/范围
- 获取文本内容
- 插入文本
- 替换内容
- 创建段落
- 插入内容控件
- 处理表格、图片、表单等对象

这意味着：

> “AI 在 OnlyOffice 内获取当前选区并改写当前文档片段”这条能力链，官方已经支持。

### 2.4 ONLYOFFICE 支持自建部署与集成

官方文档明确把 ONLYOFFICE Docs 作为可集成到自有系统中的 office suite / Docs API / 插件宿主来提供。

结合你当前仓库里已有：

- Docker 自建 `onlyoffice/documentserver`
- callback / proxy / 外网地址改写
- 前端侧 OnlyOffice 工具桥

可以判断：

> 自建部署这条路是成立的，而且值得继续做。

---

## 3. 由这些事实推出的边界判断

## 3.1 能做深集成，但不能反客为主

结论：

- **OnlyOffice 适合深集成**
- **OnlyOffice 不适合做系统主内核**

原因不是它能力不够，而是职责不同。

OnlyOffice 擅长：

- 编辑 office 文档
- 处理复杂版式文档
- 承载编辑器插件与文档内 AI
- 管理编辑器态的操作命令

但它不擅长天然承担：

- 笔记块树真相
- 全局页面树真相
- 跨页面引用网络真相
- AI 全局任务编排
- 统一命令总线
- 全系统事件日志中心

## 3.2 在 mnote-rust 中的正式定位

OnlyOffice 应定位为：

> **Office Asset Editor Adapter + Office AI Subsystem**

而不是：

- 主页面编辑器内核
- 主数据模型
- 主命令入口
- 主任务系统

---

## 4. 正式职责划分

## 4.1 OnlyOffice 负责什么

### A. Office 资产编辑

负责编辑：

- `docx`
- `xlsx`
- `pptx`
- 部分 `pdf` 相关工作流

### B. 编辑器内局部 AI 能力

例如：

- 基于当前选区总结
- 重写/润色选区文本
- 插入生成内容
- 提取 action items
- 生成标题/批注/宏

### C. 编辑器上下文采集

例如：

- 当前文档 ID
- 当前资产版本 ID
- 当前选区
- 当前页/书签/活动对象
- 编辑器保存状态

### D. 将编辑结果回写主系统

例如：

- 保存为新 `AssetVersion`
- 产出书签/目录/片段锚点
- 触发提取文本与索引任务

## 4.2 Rust 内核负责什么

### A. 主事实层

- Workspace
- Page
- Block
- Asset
- AssetVersion
- Reference
- Task
- Event
- CommandLog

### B. 系统级命令与权限

- 谁可以编辑哪个资产
- 谁可以覆盖哪个版本
- 哪些操作需要确认
- 哪些任务需要后台执行

### C. 全局 AI 调度

- Agent Session
- Tool Registry
- CLI / MCP / Tool API
- 长任务编排
- 审计与回放

### D. 跨资产与跨页面知识组织

- 引用图
- 搜索索引
- 反链
- RAG
- 页面/块/资产统一导航

---

## 5. 最推荐的集成方式

## 5.1 推荐结构

```text
AI / CLI / Web / Desktop
          │
          ▼
Rust Command / Query / Tool API
          │
          ├─ Asset Service
          ├─ Agent Service
          ├─ Search / Reference Service
          └─ OnlyOffice Adapter Service
                     │
                     ├─ Docs API
                     ├─ Callback Handler
                     ├─ Plugin Bridge
                     └─ Selection / Save / Anchor Bridge
```

核心含义：

- 所有人和 AI 都先找 Rust 内核
- Rust 内核再协调 OnlyOffice
- OnlyOffice 不是上帝，只是一个能力域

## 5.2 不推荐结构

```text
AI -> OnlyOffice Plugin -> 直接改系统数据库/页面状态
```

或者：

```text
Web 页面逻辑 -> 直接控制 OnlyOffice -> 顺手写一部分业务真相
```

这种结构会再次回到胶水冲突。

---

## 6. 官方 AI 能力在新系统中的用法

## 6.1 可以直接利用的部分

可以利用官方插件/Office API 做：

- `office.get_selection`
- `office.get_document_text`
- `office.replace_selection`
- `office.insert_after_selection`
- `office.create_comment_from_ai`
- `office.generate_outline`
- `office.extract_action_items`

这些能力适合做成：

- 插件内命令
- 本地桥接命令
- Tool API 的 office 子域工具

## 6.2 不应依赖的部分

不应把以下能力外包给 OnlyOffice：

- 页面树管理
- 笔记块模型
- 全局知识链接
- Agent 全局工作记忆
- 系统统一任务编排
- 跨类型对象权限控制

---

## 7. 推荐的 Tool API 分工

## 7.1 Rust 内核对外工具

例如：

- `asset.open_in_office`
- `asset.list_versions`
- `asset.commit_new_version`
- `reference.resolve_anchor`
- `office.create_edit_session`
- `office.get_capabilities`

## 7.2 OnlyOffice 插件桥工具

例如：

- `office_plugin.get_selection`
- `office_plugin.get_document_text`
- `office_plugin.replace_selection`
- `office_plugin.insert_text`
- `office_plugin.get_outline`
- `office_plugin.list_bookmarks`

## 7.3 正确的调用链

```text
Agent / CLI
   -> note/asset/office Tool API
   -> Rust 内核
   -> OnlyOffice Adapter / Plugin Bridge
   -> Office JS API / Docs API
   -> 返回结构化结果
```

而不是：

```text
Agent 直接知道 OnlyOffice 内部细节并自行编排保存流程
```

---

## 8. 版本回写策略

这是边界里最关键的一块。

### 8.1 正确做法

OnlyOffice 编辑完成后：

- 生成新的 `AssetVersion`
- 更新 `assets.current_version_id`
- 写 `command_log` / `event`
- 触发：
  - 文本提取
  - 大纲提取
  - 锚点更新
  - 索引更新

### 8.2 不正确做法

- 只在编辑器里“看起来改了”但系统无版本记录
- callback 到了就直接覆盖文件，不产生日志
- 直接把插件临时状态写成业务真相

---

## 9. Anchor / 选区 / 书签策略

OnlyOffice 的一个真正价值，是它能提供相对更强的文档内部定位。

建议区分两类定位：

### 9.1 短期编辑上下文

例如：

- 当前选区
- 当前光标
- 当前页
- 当前激活对象

这类只作为：

- `SelectionAnchor`
- AgentSession 上下文
- Tool 输入

### 9.2 长期可引用锚点

例如：

- bookmark
- 标题路径
- 批注 id
- 内容控件 id
- 提取片段 hash

这类才适合进正式 `Reference.anchor`。

原则：

- 选区是瞬时上下文
- 书签/内容控件/稳定片段才是长期引用对象

---

## 10. 插件开发建议

## 10.1 建议做自有插件桥

理由：

- 官方插件体系已经成熟到可用
- 你需要的是“把 OnlyOffice 接进自己的命令系统”
- 自有桥插件比零散页面 hack 更稳

## 10.2 插件职责建议

插件只做：

- 获取编辑器上下文
- 执行局部编辑命令
- 请求 mnote-rust Tool API
- 接收结构化结果并落到文档
- 回传选择/书签/状态

插件不要做：

- 自己维护主业务状态
- 自己做全局权限判断
- 自己做全局任务调度
- 自己缓存长期知识图谱

---

## 11. 源码部署 / 自建部署的实际建议

## 11.1 结论

**值得继续推进自建部署。**

## 11.2 原因

- 网络、callback、鉴权策略可控
- 便于把插件、配置、回调、存储策略收归自己管理
- 更方便未来与桌面版、本地模式、离线模式衔接
- 减少外部部署差异导致的集成复杂度

## 11.3 但不建议的误区

- 不要把“自建部署”误解为“去重写编辑器引擎”
- 不要把“插件可改内容”误解为“OnlyOffice 可以替代整个笔记内核”
- 不要把“官方已有 AI 插件”误解为“你的 Agent 架构可以省掉”

---

## 12. 对 mnote-rust 的直接影响

这份结论会直接影响后续架构文档：

1. `office.*` 作为独立工具域存在
2. `AssetVersion` 必须是一等对象
3. `Reference.anchor` 必须支持 office bookmark / content control / text quote
4. `SelectionAnchor` 只做短期上下文，不升格为主事实
5. Agent 与 OnlyOffice 的关系必须经由 Rust Tool API，而不是页面硬连

---

## 13. 最小落地路线

### Phase A

- 自建 ONLYOFFICE Docs 持续使用
- 补正式 adapter 文档
- 补 `AssetVersion` / callback / save 流程

### Phase B

- 做自有桥插件
- 打通选区读取、文本替换、结构化命令执行
- 统一插件与系统鉴权

### Phase C

- 把 office 工具域接入统一 Tool API / CLI / Agent Runtime
- 让 AI 通过系统命令操作 Office 资产
- 建立锚点、版本、索引、审计闭环

### Phase D

- 再评估是否要更深度定制 UI / 插件体验
- 但不进入“重写 OnlyOffice 内核”路线

---

## 14. 一句话结论

基于 ONLYOFFICE 官方当前能力，最合理的路线不是回避它，也不是围绕它建系统，而是：

> **把 ONLYOFFICE 作为可自建、可插件化、可 AI 深接入的 Office 资产编辑子系统；同时把主事实层、命令层、日志层、任务层牢牢放在 Rust 内核里。**