mnote/recycle/20260712-pi-ts-openhub-retirement/design/07-ai/process/7-67-openhub-page-ai-fusion-v1.md

> 状态补充（2026-07-03）：本稿为 OpenHub 初步融合稿，OpenHub AI 面板 / FastAPI / Redis / opencode client 方向仍保留参考价值；其中 WeKnora 默认知识库底座口径已被当前 OpenHub / native agent + LightRAG + Turso/libSQL 主线覆盖。`7-68-openhub-weknora-mnote-deep-fusion-v1.md` 已标记 stale，不再作为当前默认 provider 依据。

# 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 主路径已回正为 OpenHub / native agent + LightRAG + Turso/libSQL：

```text
MNote Rust SSR / control-plane / local workspace
  -> OpenHub AI 面板（只暴露 AI 能力，裁剪非 AI 入口）
  -> OpenHub FastAPI + Redis + OpenHub SQLite session/skill/tool permission；MCP/tool 由 MNote/LightRAG/opencode 工具配置承接
  -> OpenHub opencode client / opencode serve runtime
  -> LightRAG knowledge provider（默认知识库底座）
```

`7-65` 降级为 opencode runtime / 官方 iframe fallback；`7-66` 降级为 native UI fallback；本稿的 Rust adapter / 自建 message store 路线也冻结为参考，不再作为执行主线。

## 2. 硬边界

- 不恢复 Reasonix / ZCode / Hermes / Board / CodexMobile 为 Page AI 默认后端。
- 不新增 Page AI Leptos island；Page AI 仍属于 `mnote-web` host runtime 与普通前端资源。
- 不直接引入 OpenHub 登录、admin、FileManager、KnowledgeManager 等非 AI 入口；用户、权限、workspace 真相归 MNote control-plane。
- 不把 OpenHub 自带 SQLite 文本知识库当作 MNote 长期知识库底座；当前默认长期知识库 provider 是 LightRAG。
- 不使用 `--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 后端模式（已由 7-68 覆盖）

可复用其 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 后端”。`7-68` 已更正：第一阶段保留 OpenHub FastAPI + Redis + opencode client 作为 AI 运行栈，MNote 只做登录态、scope 注入、入口裁剪、文件打开和 citation 回跳桥。

## 4. MNote 目标架构

### 4.1 UI 层

`sidebar-page-ai-runtime.js` 不再维护自研聊天消息渲染主链，而是承载 `7-68` 的 OpenHub AI 面板嵌入：

- MNote-native host chrome：当前页、selection、workspace、授权状态、runtime 状态、changed file chips。
- OpenHub AI 面板：消息、tool call、diff、history、input、skill/permission、WeKnora CLI/MCP tool 状态、运行日志。
- Bridge：只处理 MNote 专属动作：`open-file`、`refresh-file`、`insert-context`、`session-ready`、`changed-files`。

### 4.2 Rust adapter 层（冻结为旧设想）

以下自建 session/message 表路线已被 `7-68` 覆盖，不作为当前执行主线：

- `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。

当前主线是：OpenHub session/message 是 Page AI 会话真相；MNote control-plane 只保存 binding、scope、artifact/open-reference 索引，禁止复制消息全文主存储。

### 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：默认走 LightRAG。
- 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 / LightRAG adapter

- [ ] 兼容 OpenHub `knowledgeService` 的 list/create/upload/search/stats API。
- [ ] 后端默认调用 LightRAG ingestion/search。
- [ ] 将 LightRAG 命中结果转成 OpenHub UI 可展示的 source/citation。
- [ ] 未配置 LightRAG 时启用 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 可上传/检索，LightRAG 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 深度融合的参考实现，但本文已被 `7-68` 覆盖。正确路线不是把 OpenHub Page AI 子系统重写成 MNote 原生 UI，也不是由 MNote Rust adapter 重写 opencode client，而是在 MNote 侧嵌入 OpenHub AI 面板，保留 OpenHub FastAPI/Redis/opencode client，由 MNote 提供登录态、workspace scope、文件打开、citation 回跳和 WeKnora 工具/知识底座边界。