171 lines
8.2 KiB
Markdown
171 lines
8.2 KiB
Markdown
> 状态补充（2026-06-25）：本稿为 OpenHub 初步融合稿；更完整的 OpenHub + WeKnora + MNote 取舍与实施主线由 `7-68-openhub-weknora-mnote-deep-fusion-v1.md` 接管。
|
||
|
||
# 7-67 OpenHub Page AI 深度融合设计 v1
|
||
|
||
状态：process
|
||
Owner：07-ai / mnote-web / control-plane
|
||
日期：2026-06-25
|
||
|
||
## 1. 背景
|
||
|
||
`7-65` 的 opencode 官方 WebUI iframe 路线验证了 opencode runtime、同源反代、session binding、文件打开/刷新等接缝，但 UI 深度融合受 iframe 与官方 WebUI 结构限制。用户目标已经调整为：尽量复用成熟社区项目 OpenHub 的前端、消息库、权限、知识库 UI 和 opencode 接入模式，把 MNote Page AI 做成类似 VSCode + Cline 的一体化侧边栏，而不是 MNote 自研一个简陋聊天框。
|
||
|
||
当前 Page AI 新主路径：
|
||
|
||
```text
|
||
MNote Rust SSR / control-plane / local workspace
|
||
-> OpenHub Chat 子系统 UI（裁剪融合）
|
||
-> MNote Rust adapter（兼容 OpenHub API 形状）
|
||
-> opencode serve runtime
|
||
-> WeKnora knowledge provider（长期知识库底座）
|
||
```
|
||
|
||
`7-65` 降级为 opencode runtime spike / fallback；不再把官方 opencode WebUI iframe 作为默认产品 UI。
|
||
|
||
## 2. 硬边界
|
||
|
||
- 不恢复 Reasonix / ZCode / Hermes / Board / CodexMobile 为 Page AI 默认后端。
|
||
- 不新增 Page AI Leptos island；Page AI 仍属于 `mnote-web` host runtime 与普通前端资源。
|
||
- 不直接引入 OpenHub 登录、用户管理、admin 整站后端；用户、权限、workspace 真相归 MNote control-plane。
|
||
- 不把 OpenHub 自带 SQLite 文本知识库当作 MNote 长期知识库底座；长期知识库 provider 是 WeKnora。
|
||
- 不使用 `--dangerously-skip-permissions` 作为默认路径。
|
||
- 不把 opencode 原生 session 列表裸露给前端；所有 session 必须绑定 MNote 用户、rootUri、page path。
|
||
- 不通过高频轮询刷新消息或 changed files；优先使用 opencode event stream、MNote watcher、programmatic refresh。
|
||
|
||
## 3. OpenHub 可复用资产
|
||
|
||
### 3.1 前端组件
|
||
|
||
第一阶段优先复用并裁剪：
|
||
|
||
- `SmartQueryPage.jsx`：聊天 shell、消息流、状态管理、移动端布局参考。
|
||
- `ChatInput.jsx`：输入框、附件、快捷操作、发送体验。
|
||
- `AssistantMessage.jsx`：Markdown、代码块、tool result、reasoning 展示基础。
|
||
- `ToolCall.jsx`：工具调用卡片与权限提示参考。
|
||
- `HistoryDrawer.jsx`：历史会话抽屉。
|
||
- `DiffViewer.jsx`：变更展示，但文件打开必须接 MNote open-resource。
|
||
- `FileManager.jsx`：映射 MNote local workspace / file tree。
|
||
- `KnowledgeManager.jsx`：知识库 UI 参考，后端改接 MNote/WeKnora adapter。
|
||
|
||
暂缓融合：
|
||
|
||
- OpenHub Login/Admin 整页。
|
||
- SmartEntity / Team / Scheduler。
|
||
- GitTimeMachine 的 restore 写入能力；可先只显示 diff / changed files。
|
||
|
||
### 3.2 后端模式
|
||
|
||
可复用其 API contract 和 opencode 调用模式：
|
||
|
||
- `/api/query/stream`
|
||
- `/api/sessions`
|
||
- `/api/sessions/{sessionId}/messages`
|
||
- `/api/knowledge/*`
|
||
- `/api/files/*`
|
||
- opencode `/session?directory=<workspace>`、`/session/{id}/prompt_async?directory=<workspace>`、`/global/event?directory=<workspace>`
|
||
|
||
但实现落在 Rust `mnote-web` / control-plane，不新增常驻 FastAPI 后端。
|
||
|
||
## 4. MNote 目标架构
|
||
|
||
### 4.1 UI 层
|
||
|
||
`sidebar-page-ai-runtime.js` 不再维护自研聊天消息渲染主链，而是挂载 OpenHub-derived Page AI micro frontend：
|
||
|
||
- MNote-native host chrome：当前页、selection、workspace、授权状态、runtime 状态、changed file chips。
|
||
- OpenHub-derived chat area：消息、tool call、diff、history、input、附件。
|
||
- Bridge：只处理 MNote 专属动作：`open-file`、`refresh-file`、`insert-context`、`session-ready`、`changed-files`。
|
||
|
||
### 4.2 Rust adapter 层
|
||
|
||
新增或重构 Page AI API：
|
||
|
||
- `page_ai_sessions`：MNote 用户维度的跨浏览器 session binding。
|
||
- `page_ai_messages`：用户消息、assistant 消息、tool call、opencode ids、状态。
|
||
- `page_ai_context_snapshots`：当前页标题、真实 Markdown 路径、selection、rootUri、allowed roots、知识摘要。
|
||
- `page_ai_changed_files`：opencode event/diff 得到的 changed files 与 MNote resource mapping。
|
||
|
||
所有 API 必须读取 MNote 登录态，禁止由前端自由传入 user id 或任意 directory。
|
||
|
||
### 4.3 opencode runtime 层
|
||
|
||
短期：单 opencode server + 当前打开 rootUri + MNote 用户级 binding。
|
||
|
||
中期：按 MNote user/profile 隔离 XDG profile，按需启动、空闲回收。
|
||
|
||
多用户强隔离不由 OpenHub 原生保证，必须由 MNote 反代与 profile manager 实现。
|
||
|
||
### 4.4 知识库层
|
||
|
||
OpenHub 知识库结论：其自带实现是 `knowledge_bases + knowledge_sources + LIKE/BM25/TF-IDF + prompt stuffing`，不是完整 RAG。
|
||
|
||
MNote 采用：
|
||
|
||
- UI：复用 OpenHub `KnowledgeManager` 交互。
|
||
- API：提供 OpenHub-compatible `/api/knowledge/*`。
|
||
- Provider：默认走 WeKnora。
|
||
- Fallback：未配置 WeKnora 时，可临时用 OpenHub-like SQLite 文本知识源做短知识。
|
||
- Citation：WeKnora 结果必须保留 source/resource/open-reference 映射，方便点击回 MNote 文件或资源页。
|
||
|
||
## 5. 实施阶段
|
||
|
||
### Phase A：源码裁剪 spike
|
||
|
||
- [ ] 抽取 OpenHub Chat 组件依赖图，确认最小可运行组件集。
|
||
- [ ] 在 `mnote-web` 静态资源中引入 OpenHub-derived bundle 或独立构建产物。
|
||
- [ ] 去除 OpenHub 登录/admin 路由依赖，改用 MNote 当前登录态。
|
||
- [ ] 用静态 fixture 跑出接近 OpenHub 原始体验的 Page AI sidebar。
|
||
|
||
### Phase B：OpenHub-compatible session/message API
|
||
|
||
- [ ] 增加 MNote control-plane session/message 表。
|
||
- [ ] 实现 `/api/page-ai/openhub/sessions` 与 `/messages` adapter。
|
||
- [ ] 绑定 `mnote_user_id + rootUri + pageAbsolutePath + opencode_session_id`。
|
||
- [ ] 支持跨浏览器恢复同一 MNote 用户的会话。
|
||
|
||
### Phase C：真实 opencode streaming
|
||
|
||
- [ ] adapter 创建/恢复 opencode session，directory 固定为当前打开 rootUri。
|
||
- [ ] `/query/stream` 转发到 opencode prompt_async + global event。
|
||
- [ ] 保存 user/assistant/tool/diff 消息。
|
||
- [ ] 解析 changed files 并驱动 MNote changed file chips。
|
||
|
||
### Phase D：MNote 文件与刷新融合
|
||
|
||
- [ ] changed file chip 点击走 `openResourceInActiveTab()`。
|
||
- [ ] 当前页被修改后调用 `refreshPrimaryDocument()` 或 watcher 刷新链路。
|
||
- [ ] DiffViewer 中所有 file path 点击都映射到 MNote resource/file open。
|
||
- [ ] 文件路径必须限制在当前 rootUri / allowed roots 内。
|
||
|
||
### Phase E：Knowledge / WeKnora adapter
|
||
|
||
- [ ] 兼容 OpenHub `knowledgeService` 的 list/create/upload/search/stats API。
|
||
- [ ] 后端默认调用 WeKnora ingestion/search。
|
||
- [ ] 将 WeKnora 命中结果转成 OpenHub UI 可展示的 source/citation。
|
||
- [ ] 未配置 WeKnora 时启用 SQLite fallback，并在 UI 明确标注 fallback。
|
||
|
||
### Phase F：浏览器真实验证
|
||
|
||
- [ ] `npm run dev:hot` 一键拉起 MNote + opencode runtime + Page AI UI。
|
||
- [ ] 登录测试账号后打开真实 Markdown 页面。
|
||
- [ ] Page AI 看到 OpenHub-derived UI，而不是旧简陋聊天框或官方 iframe。
|
||
- [ ] 发送真实消息，模型能识别当前 rootUri 内文件。
|
||
- [ ] 让 opencode 修改测试 Markdown，MNote changed chip 可打开，当前页可刷新。
|
||
- [ ] Knowledge UI 可上传/检索，WeKnora provider 有真实命中与引用。
|
||
- [ ] 保存截图与 smoke 输出。
|
||
|
||
## 6. 验收标准
|
||
|
||
MVP 完成条件：
|
||
|
||
- Page AI 主要视觉与交互来自 OpenHub Chat 子系统。
|
||
- 会话和消息持久化在 MNote control-plane，支持同用户跨浏览器恢复。
|
||
- opencode 真实流式回复可用，工作目录固定为当前打开 rootUri。
|
||
- changed files 与 MNote open/refresh 打通。
|
||
- Knowledge UI 至少能展示 WeKnora-backed 搜索结果；未接 WeKnora 时必须标注 fallback，不得声称知识库主线已完成。
|
||
- `npm run dev:hot` 后可用真实浏览器截图证明。
|
||
|
||
## 7. 当前结论
|
||
|
||
OpenHub 是目前最适合 MNote Page AI 深度融合的参考实现。它不解决 opencode 内核级多用户隔离，也不提供完整知识库底座，但它提供了 MNote 当前最缺的成熟 Chat/UI/message/session/diff/file/knowledge 管理壳。正确路线不是整站照搬 OpenHub，而是把 OpenHub Page AI 子系统移植为 MNote 原生 Page AI UI，后端由 MNote Rust adapter 接 opencode 与 WeKnora。
|