mnote/design/07-ai/process/7-67-openhub-page-ai-fusion-v1.md

状态补充（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 新主路径：

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。