492 lines
10 KiB
Markdown
492 lines
10 KiB
Markdown
# 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 内核里。**
|