对齐 Wolai 侧栏体验并收拢设计入库

2026-04-30 16:18:54 +08:00
parent 8c895b3dc0
commit afb2a5b8a0
89 changed files with 23188 additions and 84 deletions
@@ -0,0 +1,491 @@
+# 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 内核里。**