lix/mnote

Fork 0

Files

T

lix-2026 afb2a5b8a0 对齐 Wolai 侧栏体验并收拢设计入库

2026-04-30 16:18:54 +08:00

10 KiB

Raw Blame History

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 推荐结构

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 不推荐结构

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

或者：

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 正确的调用链

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

而不是：

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 的直接影响

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

office.* 作为独立工具域存在
AssetVersion 必须是一等对象
Reference.anchor 必须支持 office bookmark / content control / text quote
SelectionAnchor 只做短期上下文，不升格为主事实
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 内核里。

10 KiB Raw Blame History