集成 OpenHub 与 WeKnora Page AI

design/07-ai/process/7-68-openhub-weknora-mnote-deep-fusion-v1.md

@@ -4,6 +4,8 @@
 Owner：07-ai / mnote-web / control-plane / knowledge-provider
 日期：2026-06-25
 
+执行说明：本文是 Page AI / OpenHub / WeKnora 深度融合的当前主设计，不表示代码已完成。具体落地按本文第 10 节与配套清单 `design/07-ai/process/7-68-openhub-weknora-mnote-deep-fusion-checklist-v1.md` 执行；若实现中发现源码能力与本文假设不一致，优先遵循“保留原系统已完成能力，只在产品真相冲突处做最小胶水/嫁接/裁剪”的总原则。
+
 ## 0. 结论先行
 
 MNote Page AI 不应再沿“官方 opencode WebUI iframe”或“自研简陋聊天框”继续堆功能。新的主路线是：
@@ -11,22 +13,22 @@ MNote Page AI 不应再沿“官方 opencode WebUI iframe”或“自研简陋
 ```text
 MNote 当前文档页 / workspace / auth / resource truth
   ├─ Page AI UI：嵌入 OpenHub AI 界面（只暴露 AI 面板能力）
-  ├─ OpenHub backend：运行 OpenHub FastAPI + Redis + OpenHub session/skill/MCP/permission
-  ├─ Agent runtime：OpenHub FastAPI 调用 opencode serve / opencodego provider
-  ├─ Knowledge provider：WeKnora，通过 OpenHub MCP/CLI/skill 工具调用
+  ├─ OpenHub backend：运行 OpenHub FastAPI + Redis + OpenHub SQLite session/skill/tool permission
+  ├─ Agent runtime：OpenHub FastAPI 调用 opencode serve / opencode provider
+  ├─ Knowledge provider：WeKnora，通过 MNote 注册给 OpenHub/opencode 的 MCP/CLI/skill 工具调用
   └─ MNote boundary：统一登录授权、workspace/rootUri scope、文件打开、citation 回跳
 ```
 
 核心取舍：
 
-总原则：**各部分尽量保持原有已完成能力，只有发生产品真相冲突时才做最小胶水/嫁接/裁剪**。OpenHub 保持 AI 面板、FastAPI、Redis、session、skill/MCP、opencode client；WeKnora 保持知识库底座、MCP/CLI/API；MNote 保持 workspace/auth/resource tree/document pane/source registry。MNote 不重写 OpenHub/WeKnora 已有能力，只在登录态、workspace scope、文件打开、citation 回跳、禁用无关入口这些冲突点上做最小移植。
+总原则：**各部分尽量保持原有已完成能力，只有发生产品真相冲突时才做最小胶水/嫁接/裁剪**。OpenHub 保持 AI 面板、FastAPI、Redis、SQLite session/message、skill/tool permission、opencode client；WeKnora 保持知识库底座、MCP/CLI/API；MNote 保持 workspace/auth/resource tree/document pane/source registry。MNote 不重写 OpenHub/WeKnora 已有能力，只在登录态、workspace scope、文件打开、citation 回跳、禁用无关入口这些冲突点上做最小移植。
 
-- **OpenHub 负责 Page AI 界面与多用户 AI 运行栈**：嵌入 OpenHub AI 面板，运行 FastAPI/Redis，使用 OpenHub 的用户隔离、session、skill、agent/MCP、tool permission、opencode 调用链；FileManager/KnowledgeManager/Admin/Login 等非 AI 入口掐断或转接。
+- **OpenHub 负责 Page AI 界面与多用户 AI 运行栈**：嵌入 OpenHub AI 面板，运行 FastAPI/Redis，使用 OpenHub 的用户隔离、session、skill、agent/tool permission、opencode 调用链；MCP 由 MNote/WeKnora/opencode 工具配置承接，不把“OpenHub 已有完整 MCP 管理面”当成已确认事实；FileManager/KnowledgeManager/Admin/Login 等非 AI 入口掐断或转接。
 - **WeKnora 负责知识库底座、知识库页面参考实现和 MCP/CLI/API 工具能力**：解析、chunk、混合检索、RAG 引用、Wiki/图谱、知识库管理 API；知识库页面优先复用 WeKnora 的 KB list/detail/upload/status 体验，但不让 WeKnora 接管 MNote 文件真相。
 - **MNote 负责宿主真相与冲突胶水**：登录、用户、workspace/rootUri、resource tree、页面打开、allowed roots、session binding、source registry、citation/open-reference；不重写 OpenHub/WeKnora 已有主功能。
 - **opencode 负责 agent 执行**：文件编辑、diff、工具审批、模型调用。
 
-不得把 OpenHub 登录入口、OpenHub FileManager、OpenHub KnowledgeManager、WeKnora RBAC/前端变成 MNote 的用户/文件/知识库真相。OpenHub AI session/message/skill/MCP/permission/FastAPI/Redis 可以作为 Page AI 运行真相，但必须受 MNote 派生的用户与 workspace scope 隔离；WeKnora 保持知识库底座真相，MNote 只做展示、授权和回跳映射。
+不得把 OpenHub 登录入口、OpenHub FileManager、OpenHub KnowledgeManager、WeKnora RBAC/前端变成 MNote 的用户/文件/知识库真相。OpenHub AI session/message/skill/tool permission/FastAPI/Redis 可以作为 Page AI 运行真相，但必须受 MNote 派生的用户与 workspace scope 隔离；WeKnora 保持知识库底座真相，MNote 只做展示、授权和回跳映射。
 
 ## 1. 背景与当前状态
 
@@ -44,7 +46,7 @@ MNote 当前文档页 / workspace / auth / resource truth
 本设计替代 `7-65` 的官方 opencode iframe 产品主线，并收敛 `7-67` 的 OpenHub 初步融合设想。核心不是重写三套系统，而是保留各自已有能力，只对冲突点做最小胶水：
 
 1. 登录/用户/权限冲突。
-2. WeKnora 知识库底座、MNote 展示层、OpenHub MCP/skill/tool 调用边界。
+2. WeKnora 知识库底座、MNote 展示层、MNote 注册给 OpenHub/opencode 的 CLI/MCP/skill/tool 调用边界。
 3. 页面/文件打开、changed files、citation 回跳边界。
 
 ## 2. 三方职责边界
@@ -52,16 +54,16 @@ MNote 当前文档页 / workspace / auth / resource truth
 | 能力 | MNote | OpenHub | WeKnora | 取舍 |
 |---|---|---|---|---|
 | 登录/用户 | MNote SQLite control-plane、`mnote_session` | OpenHub JWT/localStorage 禁用或后端注入；使用 MNote 派生 user/workspace | WeKnora tenant/RBAC/API key | MNote 是唯一登录入口；OpenHub 运行态按 MNote 用户/工作区派生 |
-| workspace/rootUri | MNote local workspace、rootUri 授权 | OpenHub user workspace path / session scope / skill scope / MCP scope | WeKnora tenant/KB | rootUri 归 MNote；OpenHub 的 workspace directory 由 MNote 授权 rootUri 派生 |
-| Page AI UI | MNote sidebar host / iframe/proxy shell | OpenHub AI 界面 | WeKnora Web UI 不嵌入 | 嵌入 OpenHub AI 面板；隐藏或掐断非 AI 页面入口 |
-| session/message | MNote 只做 host binding / ownership index | OpenHub conversation/session tables + Redis/cache | WeKnora chat sessions 暂弃用 | OpenHub session/message 是 Page AI 真相；MNote 不复制消息全文 |
-| agent runtime | MNote 启停/健康检查/反代边界 | OpenHub FastAPI + Redis + opencode client | WeKnora MCP/CLI/API，agent-chat 暂弃用 | 运行 OpenHub 后端；由 OpenHub 调 opencode；MNote 不重写 opencode client |
-| 知识库 UI | MNote shell / FileTree 灯号 / citation 回跳 | OpenHub KnowledgeManager 掐断或跳转 MNote | 复用 WeKnora KB list/detail/upload/status 页面能力 | 用 WeKnora 知识库页面替换 MNote 简陋页，但本地文件和授权仍归 MNote |
-| 检索/RAG | MNote source registry / citation 回跳 / scope 集合定义 | OpenHub AI 通过 MCP/skill/tool 调 WeKnora | WeKnora hybrid/vector/graph/chunk | 知识库是 MNote 授权文件/文件夹集合的索引视图；WeKnora 是唯一索引与查询 provider |
+| workspace/rootUri | MNote local workspace、rootUri 授权 | OpenHub user workspace path / session scope / skill scope / tool scope | WeKnora tenant/KB | rootUri 归 MNote；OpenHub 的 workspace directory 由 MNote 授权 rootUri 派生 |
+| Page AI UI | MNote sidebar host / iframe/proxy shell | OpenHub AI 界面 | WeKnora 不进入 Page AI 对话壳 | 嵌入 OpenHub AI 面板；隐藏或掐断非 AI 页面入口 |
+| session/message | MNote 只做 host binding / ownership index | OpenHub SQLite conversation/session/message tables；Redis 只作缓存/临时态 | WeKnora chat sessions 暂弃用 | OpenHub session/message 是 Page AI 真相；MNote 不复制消息全文 |
+| agent runtime | MNote 启停/健康检查/反代边界 | OpenHub FastAPI + Redis + opencode client | WeKnora CLI/MCP/API，agent-chat 暂弃用 | 运行 OpenHub 后端；由 OpenHub 调 opencode；MNote 不重写 opencode client |
+| 知识库 UI | MNote shell / FileTree 灯号 / citation 回跳 | OpenHub KnowledgeManager 掐断或跳转 MNote | 复用 WeKnora KB list/detail/upload/status 页面体验 | 用 MNote shell + WeKnora KB adapter 替换 MNote 简陋页，但本地文件和授权仍归 MNote |
+| 检索/RAG | MNote source registry / citation 回跳 / scope 集合定义 | OpenHub AI 通过 MNote 注册的 CLI/MCP/skill/tool 调 WeKnora | WeKnora hybrid/vector/graph/chunk | 知识库是 MNote 授权文件/文件夹集合的索引视图；WeKnora 是唯一索引与查询 provider |
 | 文件打开 | MNote document pane/resource tab/FileTree，相当于 FileManager | OpenHub FileManager 掐断或跳转 MNote | WeKnora 不负责页面打开 | OpenHub AI 回复中的 path/citation 点击回 MNote 打开页面 |
-| 权限审批 | MNote allowed roots + workspace grants + scope 注入 | OpenHub tool/model/skill/MCP permissions | WeKnora RBAC | MNote 提供授权边界；OpenHub 按原生权限规范执行；WeKnora RBAC 作 provider 防线 |
+| 权限审批 | MNote allowed roots + workspace grants + scope 注入 | OpenHub tool/model/skill permissions；MCP 走 opencode/WeKnora 工具配置 | WeKnora RBAC | MNote 提供授权边界；OpenHub 按原生权限规范执行；WeKnora RBAC 作 provider 防线 |
 | Git / snapshot / restore | MNote watcher、buffer、用户显式保存/版本策略 | OpenHub Git snapshot 默认关闭 | 无关 | 第一阶段禁用 Git snapshot/restore，避免污染 local-first workspace |
-| Redis/cache/queue | MNote 不存 Page AI 消息真相 | OpenHub Redis/cache/queue 由 OpenHub stack 管理 | WeKnora 如有内部 Redis 由 WeKnora stack 管理 | Redis 归各自服务栈；不作为 MNote 权限/文件/知识库真相 |
+| Redis/cache | MNote 不存 Page AI 消息真相 | OpenHub Redis 主要用于 token/rate-limit/cache/临时态；消息真相在 SQLite | WeKnora Redis/Asynq/Langfuse 由 WeKnora stack 管理 | Redis 归各自服务栈；不作为 MNote 权限/文件/知识库真相 |
 
 ## 3. 登录、OpenHub 隔离与 WeKnora 授权融合
 
@@ -71,12 +73,12 @@ MNote 当前文档页 / workspace / auth / resource truth
 
 ```text
 MNote 登录态 / user_id / workspace grants
-  ├─ OpenHub 派生隔离上下文：openhub_user_key + workspace/runtime/session/skill/MCP scope
+  ├─ OpenHub 派生隔离上下文：openhub_user_key + workspace/runtime/session/skill/tool scope
   └─ WeKnora 派生知识库上下文：已授权 workspace/rootUri -> provider tenant/profile/KB/source registry
 ```
 
 - **MNote 负责入口认证与授权判断**：当前用户是谁、能访问哪些 workspace/rootUri、能读写哪些 source。
-- **OpenHub 需要 per-user / per-workspace 隔离**：session、message、skill、MCP、tool permission、opencode directory、changed files 都必须绑定 MNote 用户与 workspace；不能所有 MNote 用户共用一个 OpenHub runtime identity。
+- **OpenHub 需要 per-user / per-workspace 隔离**：session、message、skill、tool permission、opencode directory、changed files 都必须绑定 MNote 用户与 workspace；MCP/tool scope 由 MNote 注册的 WeKnora/opencode 工具配置体现；不能所有 MNote 用户共用一个 OpenHub runtime identity。
 - **WeKnora 是唯一知识库底座，并通过 MCP / CLI / API 暴露给 OpenHub/opencode**：它只接收 MNote 已授权 workspace 的文件/文件夹集合 ingest/search/query 或工具调用；知识库可见性本身依赖 MNote 的 source registry 和 allowed roots，WeKnora 用户认证可以保持简单。
 - **WeKnora RBAC/API key 是 provider 防线**：不承担 MNote 产品层用户隔离，不把 WeKnora tenant/user 反向暴露成 MNote 登录体系。
 
@@ -85,18 +87,18 @@ MNote 登录态 / user_id / workspace grants
 OpenHub 和 WeKnora 的用户模型对 MNote 的影响不同：
 
 - OpenHub 前端会使用 `auth_token` / JWT / localStorage，并在 401 后跳转到 `/login`。
-- OpenHub 后端还有会话、消息、skill、MCP、tool/model permission、workspace path 和 Git snapshot 等用户相关状态。
+- OpenHub 后端还有会话、消息、skill、tool/model permission、workspace path 和 Git snapshot 等用户相关状态；MCP 工具面由 MNote/WeKnora/opencode 配置承接。
 - WeKnora 有 tenant RBAC、Owner/Admin/Contributor/Viewer、共享空间与 API Key，但 MNote 的知识库使用场景主要来自“用户已授权 workspace/rootUri”。
 - MNote 已有 SQLite control-plane auth、`mnote_session` cookie、测试账号与 local workspace 授权。
 
-如果直接嵌入 OpenHub 或 WeKnora Web UI，会出现三套登录入口、三套用户 id、三套权限判断；但如果把 OpenHub 也降成“无用户共享 runtime”，又会让 session、skill、MCP、工具审批和文件变更串用户。
+如果直接嵌入 OpenHub 或 WeKnora Web UI，会出现三套登录入口、三套用户 id、三套权限判断；但如果把 OpenHub 也降成“无用户共享 runtime”，又会让 session、skill、工具审批、WeKnora tool scope 和文件变更串用户。
 
 ### 3.3 决策
 
 - MNote 是唯一**前端登录入口**和产品层授权入口。
 - OpenHub 不保留自己的 Login 页面、JWT/localStorage 登录跳转，但 MNote boundary 必须为每个 MNote 用户派生 OpenHub runtime identity。
-- OpenHub 派生 identity 至少包含：`mnote_user_id`、`workspace_id`、`root_uri`、`openhub_user_key`、`opencode_session_scope`、`skill_scope`、`mcp_scope`、`tool_permission_scope`。
-- OpenHub session/message/skill/MCP/tool permission 不得跨 `mnote_user_id + workspace_id/root_uri` 共享。
+- OpenHub 派生 identity 至少包含：`mnote_user_id`、`workspace_id`、`root_uri`、`openhub_user_key`、`opencode_session_scope`、`skill_scope`、`tool_permission_scope`、`weknora_tool_scope`。
+- OpenHub session/message/skill/tool permission 不得跨 `mnote_user_id + workspace_id/root_uri` 共享；MCP/tool 配置不得绕过 MNote 注入的 KB/source allowlist。
 - WeKnora 使用 MNote 后端服务 API key 或受控 profile 调用；前端不直接持有 WeKnora API key。
 - WeKnora KB/source 由 MNote 的 workspace grants、source registry、allowed roots 决定；WeKnora tenant/RBAC 只作为 provider 内部防线。
 
@@ -110,8 +112,8 @@ MNote user_id + workspace_id/rootUri
   -> OpenHub scopes:
        session_scope = user_id + workspace_id + rootUri + page_resource_id
        skill_scope = user_id + workspace_id + rootUri
-       mcp_scope = user_id + workspace_id + allowed_roots
        tool_permission_scope = user_id + workspace_id + rootUri
+       weknora_tool_scope = user_id + workspace_id + allowed_kb_ids/source_ids
   -> WeKnora provider profile: mnote-local 服务 API key
   -> WeKnora KB: mnote-{workspace_id}-{purpose}
   -> MNote source registry 记录 provider KB / knowledge / chunk 映射
@@ -128,7 +130,7 @@ MNote user_id + workspace membership
   -> 所有 WeKnora 结果仍由 MNote source registry / allowed roots 二次过滤
 ```
 
-不要在第一阶段为每个 MNote 用户强行同步 WeKnora RBAC；这会放大生命周期与权限同步复杂度。相反，第一阶段应优先保证 OpenHub 派生上下文隔离，因为 Page AI 的 session、skill、MCP、工具审批和文件变更都直接依赖 MNote 登录态。
+不要在第一阶段为每个 MNote 用户强行同步 WeKnora RBAC；这会放大生命周期与权限同步复杂度。相反，第一阶段应优先保证 OpenHub 派生上下文隔离，因为 Page AI 的 session、skill、tool permission、WeKnora tool scope 和文件变更都直接依赖 MNote 登录态。
 
 ## 4. OpenHub Session / Message 真相
 
@@ -144,7 +146,7 @@ MNote Page AI 面板
   -> WeKnora 不参与 Page AI 会话真相
 ```
 
-- **OpenHub session 是 Page AI session 真相**：消息、turn、tool call、skill/MCP 状态、history、retry、visible/hidden 等语义以 OpenHub conversation/session 模型为准。
+- **OpenHub session 是 Page AI session 真相**：消息、turn、tool call、skill/tool 状态、WeKnora tool call 状态、history、retry、visible/hidden 等语义以 OpenHub conversation/session 模型为准。
 - **MNote 不复制消息主存储**：MNote 只需要保存 `mnote_user/workspace/rootUri/page_resource_id -> openhub_session_id/opencode_session_id` 的绑定，以及 changed file / citation 回跳所需的轻量索引。
 - **WeKnora 不产生会话冲突**：当前 WeKnora 主要作为 MCP/CLI/知识库工具 provider；`knowledge-chat` / `agent-chat` 暂时弃用，不纳入 Page AI 主链，因此不设计 `knowledge_session_id`。
 
@@ -202,7 +204,7 @@ openhub_workspace_key = stable_hash(workspace_id, root_uri)
 
 - 同一用户同一页面可恢复最近 active OpenHub session。
 - 切换 rootUri 或 workspace 必须新开 OpenHub session；旧 session 标记 stale 或 archived。
-- 不同 MNote 用户不得共享同一个 OpenHub session、skill scope、MCP scope 或 tool permission scope。
+- 不同 MNote 用户不得共享同一个 OpenHub session、skill scope、tool permission scope 或 WeKnora tool scope。
 - MNote boundary 对 OpenHub session 的读写必须先校验 `mnote_session` 与 binding ownership。
 
 ### 4.5 WeKnora session policy
@@ -234,7 +236,7 @@ WeKnora 应承担 MNote 知识库 provider：
 - 知识库类型：以 WeKnora `KnowledgeBase.Type` 和 FAQ 配置为准；Wiki/图谱属于 WeKnora Wiki mode / graph 能力，不能未经接口枚举直接当作 KB type 写死。
 - 导入：文件、URL、Markdown/手工知识、外部数据源。
 - 文档处理：chunk、OCR/VLM/ASR、图谱抽取、问题生成、reparse。
-- 检索：优先对接 `POST /api/v1/knowledge-search`，或按 KB 维度对接 hybrid-search；返回分数为融合排序分（如 RRF），不能当原始相似度解释。
+- 检索：多 KB / 指定 knowledge 检索优先对接 `POST /api/v1/knowledge-search`；单 KB 调试或 CLI/MCP 可走 `POST /api/v1/knowledge-bases/:id/hybrid-search`；返回分数按排序分处理，不能按百分比或原始相似度解释。
 - 问答：`POST /api/v1/knowledge-chat/:session_id`、`POST /api/v1/agent-chat/:session_id` SSE 作为后续可选 provider 能力；第一阶段 Page AI 主链暂弃用，不产生主会话真相。
 - 权限：tenant RBAC / shared organization 作内部防线。
 
@@ -279,7 +281,7 @@ trait KnowledgeProvider {
 - `/api/knowledge-rag/search`：调用 WeKnora `/api/v1/knowledge-search` 或 KB 级 hybrid-search，返回 MNote `search_results.v1` 兼容结构。
 - `/api/knowledge-rag/query`：不再调用 LightRAG `/query/data`；第一阶段用 WeKnora search result 生成带 citations/references 的 query result。
 - `/api/knowledge-rag/section-context`：不再读 LightRAG sidecar blocks；改为基于 WeKnora chunk / source registry / 本地文件 locator 构造上下文。
-- 排序与阈值：WeKnora score 是 RRF 融合分，不能沿用 LightRAG 相似度阈值和旧 rank 解释。
+- 排序与阈值：WeKnora score 是 provider 排序/融合分，不能沿用 LightRAG 相似度阈值、百分比相似度或旧 rank 解释。
 - 引用映射：WeKnora `knowledge_id` / `chunk_id` / `knowledge_base_id` 只用于回查 registry，不能直接作为 MNote 文件路径。
 
 WeKnora search result 到 MNote registry 的最低字段映射：
@@ -288,17 +290,21 @@ WeKnora search result 到 MNote registry 的最低字段映射：
 |---|---|---|
 | `id` | `providerChunkId` | WeKnora chunk id |
 | `knowledge_id` | `providerKnowledgeId` | 回查 registry 的主键之一 |
-| `knowledge_base_id` | `providerKnowledgeBaseId` | provider KB 映射 |
+| `knowledge_base_id` | `providerKnowledgeBaseId` | provider KB 映射；`knowledge-search` 与部分 CLI 输出字段覆盖不完全时从请求 scope/registry 补齐 |
+| `content` / `matched_content` | `quote` / `matchedText` | citation 文本来源；FAQ/相似问命中优先保留 matched_content |
 | `chunk_index` | `chunkIndex` | 可用于同一 knowledge 内排序/定位 |
 | `start_at` / `end_at` | `providerOffsets` | 只能作为 provider 内偏移，不能直接当 Markdown 行号 |
 | `knowledge_filename` | `providerDisplayName` | 只用于显示，不能当本地路径真相 |
 | `knowledge_source` / `knowledge_channel` | `providerSourceMeta` | 用于辅助映射和审计 |
+| `match_type` | `providerMatchType` | 区分 vector/keyword/hybrid/enrichment/direct 等命中渠道 |
+| `parent_chunk_id` / `sub_chunk_id` | `providerChunkHierarchy` | 父子 chunk 与上下文扩展 |
+| `metadata` / `chunk_metadata` / `image_info` | `providerMetadata` | 图片/VLM、FAQ、自定义元数据与定位诊断 |
 
 `sourcePath`、`lineStart`、`lineEnd`、`mnoteResourceId`、`openReference` 必须由 MNote registry / locator 派生；WeKnora 未返回时不能伪造。
 
 ### 5.4 知识库定义、页面选择与 WeKnora Tool Bridge
 
-这里不应设计 `OpenHub-compatible /knowledge/*`，也不应把 OpenHub `KnowledgeManager.jsx` 作为第一阶段知识库页。知识库页面建议复用 WeKnora 的 `KnowledgeBaseList.vue` / `KnowledgeBase.vue` / 上传与 processing timeline 组件，作为 MNote 知识库展示层的实现。当前边界是：
+这里不应设计 `OpenHub-compatible /knowledge/*`，也不应把 OpenHub `KnowledgeManager.jsx` 作为第一阶段知识库页。知识库页面建议复用 WeKnora 的 `KnowledgeBaseList.vue` / `KnowledgeBase.vue` / `KnowledgeBaseEditorModal.vue` / 上传与 processing timeline 组件体验，作为 MNote 知识库展示层的实现。当前边界是：
 
 ```text
 MNote Knowledge UI（复用 WeKnora KB list/detail/upload/status 体验）
@@ -306,7 +312,7 @@ MNote Knowledge UI（复用 WeKnora KB list/detail/upload/status 体验）
   -> WeKnora ingest / search / status / open-reference
 
 MNote Page AI / OpenHub-style session
-  -> opencode 按 MCP/skill/tool 规范自行决定 tool call
+  -> opencode 按 skill/tool/MCP 规范自行决定 tool call；MNote 只提供受限工具配置和 open-reference bridge
   -> 已注册的 `mnote.weknora.*` MCP/CLI/API tool
   -> WeKnora search/query
   -> tool result 回 OpenHub session
@@ -316,9 +322,10 @@ MNote Page AI / OpenHub-style session
 
 - **知识库不是新的文件真相**：真相永远是 MNote 授权 rootUri 下的本地文件/文件夹/page resource；知识库是这些 source 的命名集合、索引状态和检索配置。
 - **唯一知识库底座是 WeKnora**：OpenHub 自带 knowledge tables、KnowledgeManager 页面和 prompt stuffing 知识库第一阶段全部不使用。
-- **知识库页面选择 WeKnora**：复用 WeKnora 的 KB list/detail/upload/status/reparse/processing timeline 体验来替换 MNote 简陋知识库页；MNote 外壳负责登录、workspace、source registry、FileTree 灯号和 citation 回跳。
+- **知识库页面选择 WeKnora 体验，但不直接接管 MNote shell**：第一阶段采用 `MNote shell + WeKnora KB adapter`。优先抽取或复刻 WeKnora `KnowledgeBaseList.vue`、`KnowledgeBase.vue`、`KnowledgeBaseEditorModal.vue`、`knowledge-processing-timeline.vue` 的交互和数据模型；不 iframe WeKnora 全量产品前端，不暴露 WeKnora 登录/租户切换/独立文件真相。
 - **OpenHub 不管理知识库页面**：OpenHub 只在对话过程中通过 MCP/CLI/API tool 调用 WeKnora，tool result 进入 OpenHub session。
 - **MNote tool facade 是注册与权限边界**：OpenHub/opencode 不能直接持有 WeKnora API key，也不能绕过 MNote allowed roots / source registry；是否调用工具、如何组织 tool call 由 OpenHub/opencode 自己判断。
+- **WeKnora MCP surface 第一阶段选择 Go CLI `weknora mcp serve` 或 MNote facade 包装后的等价只读工具面**：该 surface 当前是手工维护的只读工具集，更适合先挂给 OpenHub/opencode。Python `mcp-server` 暴露 create/delete/chunk mutation 等更宽能力，第一阶段只作为参考，不默认接入。
 
 第一阶段需要的接口不是 OpenHub-compatible knowledge API，而是三类接口：
 
@@ -345,9 +352,34 @@ OpenHub/opencode tool facade:
 
 WeKnora 页面 adapter 可以复用 WeKnora 前端组件/交互，但数据入口必须先经过 MNote source registry 与 allowed roots；`mnote.weknora.*` 可以底层走 WeKnora MCP、CLI 或 HTTP API，但对 OpenHub 暴露的合同必须是 MNote 权限过滤后的 tool contract。
 
+推荐页面复用方式：
+
+1. **首选：MNote adapter 页面复刻 WeKnora 知识库体验**。在 MNote 前端保留统一路由、auth、workspace 和 FileTree/resource picker；后端通过 MNote canonical API 转接 WeKnora KB/doc/status/search。成本高于 iframe，但冲突最少。
+2. **可选：抽取 WeKnora Vue 组件进入独立 adapter bundle**。仅抽知识库列表、详情、上传、状态时间线组件；替换其 auth/client/router/store，数据仍走 MNote 后端。
+3. **不选：iframe WeKnora 全量前端**。会带来 WeKnora 登录、租户切换、独立上传文件真相和打开页面冲突，只能作为调试入口，不作为产品主线。
+
+知识库最小数据模型应分成 `mnote_knowledge_bases` 与 `mnote_knowledge_sources` 两层：
+
+```text
+mnote_knowledge_bases
+  id
+  user_id
+  workspace_id
+  root_uri
+  name
+  description
+  provider = weknora
+  provider_kb_id
+  default_tool_enabled
+  metadata_json
+  created_at / updated_at / archived_at
+```
+
+`mnote_knowledge_bases` 是用户可见的知识库集合；`mnote_knowledge_sources` 是 source 到 provider knowledge/chunk 的映射。删除 source 只删除索引和映射，不删除本地原文件；删除 KB 默认只归档 MNote KB 与删除/禁用对应 WeKnora provider KB，不能批量删除 MNote 本地文件。
+
 ### 5.5 Source Registry provider-neutral 化
 
-旧 LightRAG 字段应迁移为：
+旧 LightRAG 字段应迁移为 provider-neutral registry；当前 JSON 文件 `lightrag-source-registry.json` 中的 `lightRagDocId/lightRagStatus/lightRagFilePath/symlinkPath` 等字段必须兼容读取并迁移或双写一段时间。目标结构为：
 
 ```text
 mnote_knowledge_sources
@@ -383,7 +415,7 @@ mnote_knowledge_sources
 - OpenHub 第一阶段只借用多用户 AI 能力和 AI 页面产品参考，不使用 OpenHub FileManager 或完整前端。
 - WeKnora 只暴露 MCP/CLI/API 知识工具，返回 knowledge/chunk/reference，不参与页面打开。
 
-因此这里不需要做 OpenHub FileManager、WeKnora Web UI 或 provider path 的打开融合；只需要保证 MNote Page AI 回复中的 changed file、diff、citation、tool result 能映射回 MNote 页面。
+因此这里不需要做 OpenHub FileManager、WeKnora 全量 Web UI 或 provider path 的打开融合；只需要保证 MNote Page AI 回复中的 changed file、diff、citation、tool result 能映射回 MNote 页面。注意：这里的“不使用 WeKnora Web UI”只针对 Page AI 对话壳、引用打开链路和文件打开链路；知识库管理页面仍按 5.4 复用 WeKnora KB 页面体验，但必须运行在 MNote shell 与 MNote 权限/source registry 后面。
 
 ### 6.2 决策
 
@@ -394,7 +426,7 @@ mnote_knowledge_sources
 - WeKnora citation / MCP/CLI tool result 点击：`/api/knowledge-rag/open-reference` 返回 MNote locator，再由 MNote 前端打开。
 - OpenHub session 中出现的 path/diff/tool reference 只作为数据来源，渲染和点击由 MNote Page AI 处理。
 - 不接 OpenHub FileManager，不使用 OpenHub `/api/files` 作为页面读写入口。
-- 不嵌 WeKnora Web UI，不让 WeKnora 决定打开哪个 MNote 页面。
+- 不在 Page AI / 引用打开链路嵌入 WeKnora 全量 Web UI，不让 WeKnora 决定打开哪个 MNote 页面。
 
 ### 6.3 MNote Page AI open reference payload
 
@@ -428,15 +460,16 @@ mnote_knowledge_sources
 ```text
 MNote Page AI host
   -> MNote 校验登录态、workspace、rootUri、allowed roots
-  -> 注入/映射 OpenHub user workspace + session/skill/MCP scope
+  -> 注入/映射 OpenHub user workspace + session/skill/tool scope
   -> OpenHub AI UI
-  -> OpenHub FastAPI + Redis/session/cache
+  -> OpenHub FastAPI + SQLite session/message + Redis cache
   -> OpenHub opencode client
   -> opencode serve /global/event /session/{id}/prompt_async /diff
 ```
 
-- **OpenHub FastAPI 继续运行**：负责 AI session/message、skill/MCP、tool permission、opencode client、event stream、diff/changed files 等 OpenHub 原生能力。
-- **Redis 跟随 OpenHub stack**：如果 OpenHub 用 Redis 做 cache/queue/session 辅助，就由 OpenHub stack 管理；MNote 不把 Redis 当自己的消息、权限、文件或知识库真相。
+- **OpenHub FastAPI 继续运行**：负责 AI session/message、skill、tool permission、opencode client、event stream、diff/changed files 等 OpenHub 原生能力。
+- **不要把待补能力写成已存在能力**：OpenHub 源码已确认有 session/message、skill、tool/model permission、SmartEntity、Git snapshot、FileManager、KnowledgeManager 和 opencode event/diff 链路；未确认独立 MCP 管理 API/UI。MCP 第一阶段应由 MNote 注册 WeKnora CLI/MCP/API tool 到 OpenHub/opencode，而不是假设 OpenHub 已有完整 MCP 管理面。
+- **Redis 跟随 OpenHub stack**：OpenHub Redis 主要用于 token/rate-limit/cache/临时态；OpenHub session/message 真相仍在 SQLite。MNote 不把 Redis 当自己的消息、权限、文件或知识库真相。
 - **MNote 不重写 planner/client**：MNote 不替 OpenHub 判断何时调用 WeKnora，也不重写 opencode prompt/event/diff 流程。
 - **MNote 只裁剪不用入口**：OpenHub Login、FileManager、KnowledgeManager、Admin 等页面不暴露；必要时在 proxy 层 404、隐藏菜单或跳转到 MNote 对应页面。
 
@@ -445,10 +478,10 @@ MNote Page AI host
 OpenHub FastAPI 在本设计中保留以下作用：
 
 - 管理 OpenHub conversation/session/message/history。
-- 管理 skill、agent/MCP、tool/model permission。
+- 管理 skill、agent/SmartEntity、tool/model permission。
 - 调用 `opencode serve`，包括创建 session、发送 prompt、监听 `/global/event`、读取 diff。
 - 向 OpenHub AI 前端提供消息流、tool card、diff、changed files、history 等 API。
-- 读取由 MNote 注入的 workspace directory、user scope、allowed roots、WeKnora MCP/CLI/skill 配置。
+- 读取由 MNote 注入的 workspace directory、user scope、allowed roots、WeKnora CLI/MCP/API tool 配置。
 
 OpenHub FastAPI 不保留以下作用：
 
@@ -460,10 +493,11 @@ OpenHub FastAPI 不保留以下作用：
 
 ### 7.3 Redis 安排
 
-- OpenHub 需要的 Redis/cache/queue 由 OpenHub deployment 管理，随 OpenHub FastAPI 启停和 health check。
-- WeKnora 如果有内部 Redis/队列依赖，由 WeKnora stack 管理，MNote 只检查 WeKnora health。
+- OpenHub 需要的 Redis/cache/临时态由 OpenHub deployment 管理，随 OpenHub FastAPI 启停和 health check；OpenHub `REDIS_HOST/REDIS_PORT/REDIS_DB` 应独立配置，避免误连 WeKnora Redis DB。
+- WeKnora 有自己的 Redis/Asynq/Langfuse 相关依赖，由 WeKnora stack 管理；MNote 只检查 WeKnora health、必要 API 与 `weknora mcp serve`/CLI profile 是否可用。
 - MNote control-plane 不依赖 Redis 保存登录授权、workspace grants、source registry、open-reference 或文件真相。
 - Redis 中只允许放可重建状态：缓存、队列、临时流状态；不能成为用户权限、文件内容、知识库 source registry 或 Page AI 消息的唯一持久真相。
+- 本机开发阶段允许共用一个 Redis 进程，但必须使用独立 DB/前缀：OpenHub、WeKnora、Langfuse/worker queue 不得混用 keyspace；`dev-hot` health 输出应显示各自 Redis 连接目标。
 
 ### 7.4 Page AI context
 
@@ -475,7 +509,7 @@ MNote 注入给 OpenHub / opencode 的 context：
 - 当前页面标题、真实 Markdown path、resource id
 - selection 摘要
 - allowed roots / write constraints
-- OpenHub session scope / skill scope / MCP scope / tool permission scope
+- OpenHub session scope / skill scope / tool permission scope
 - WeKnora tool scope：允许查询的 kb ids/source ids/citation policy
 - MNote 文件打开/刷新 bridge usage
 ```
@@ -489,8 +523,8 @@ MNote 注入给 OpenHub / opencode 的 context：
 MNote sidebar host 的职责应尽量薄：承载 OpenHub AI 面板、注入 MNote context、处理 MNote 回跳，不重新设计一套顶部/侧边栏产品结构。
 
 - 顶部：第一阶段可以不要 MNote 自定义顶部；如需状态，只做极简 host 状态条或错误提示，避免覆盖 OpenHub AI 面板原有布局。
-- 主体：OpenHub AI 面板，由 OpenHub 前端/后端处理消息、tool card、diff、history、agent/MCP/skill 状态。
-- 侧边：优先保留 OpenHub AI 相关侧边能力，包括历史 session、MCP、skill、agent、tool/model permission 等设置。
+- 主体：OpenHub AI 面板，由 OpenHub 前端/后端处理消息、tool card、diff、history、agent/skill/tool 状态。
+- 侧边：优先保留 OpenHub AI 相关侧边能力，包括历史 session、skill、agent/SmartEntity、tool/model permission 等设置；MCP 若当前 OpenHub 前端没有原生管理页，第一阶段显示 WeKnora MCP/CLI tool 连接状态与 MNote scope，而不是重写完整 MCP 管理器。
 - MNote context：以 context pills / hidden bootstrap / postMessage / proxy header 方式注入当前 page path、rootUri、selection、allowed roots，不强行改 OpenHub UI 主结构。
 - 回跳：changed file、citation、reference 点击时走 MNote bridge 打开页面。
 
@@ -502,8 +536,8 @@ MNote sidebar host 的职责应尽量薄：承载 OpenHub AI 面板、注入 MNo
 
 - AI chat 主界面。
 - history / session 抽屉。
-- MCP 设置与连接状态。
 - skill / agent 设置。
+- WeKnora CLI/MCP tool 的连接状态；若 OpenHub 无原生 MCP 设置 UI，则通过 MNote host 或 OpenHub 最小扩展显示，不阻塞 AI 主界面。
 - tool/model permission UI。
 - tool card、diff、changed files、运行日志等 AI 运行态 UI。
 
@@ -518,12 +552,12 @@ MNote sidebar host 的职责应尽量薄：承载 OpenHub AI 面板、注入 MNo
 
 ### 8.3 MNote 暴露给 OpenHub 的边界能力
 
-MNote 不替 OpenHub 判断何时调用知识库、何时用 skill/MCP、如何组织 tool call；这些交给 OpenHub/opencode 已有 MCP/skill/agent 规范处理。MNote 只提供最小边界能力：
+MNote 不替 OpenHub 判断何时调用知识库、何时用 skill/tool/MCP 工具、如何组织 tool call；这些交给 OpenHub/opencode 已有 skill/tool/agent 规范处理，并由 MNote 注册的 WeKnora CLI/MCP/API tool 提供知识能力。MNote 只提供最小边界能力：
 
 ```text
 - 当前页面 context：page path / title / selection / rootUri / allowed roots
-- OpenHub scope：user/workspace/rootUri 派生的 session/skill/MCP/tool permission scope
-- WeKnora MCP/CLI/API 配置：以 skill/MCP/tool 形式注册给 OpenHub/opencode
+- OpenHub scope：user/workspace/rootUri 派生的 session/skill/tool permission scope
+- WeKnora CLI/MCP/API 配置：以 skill/tool/MCP 工具形式注册给 OpenHub/opencode
 - open-reference bridge：把 provider citation/chunk/source 映射成 MNote 页面打开动作
 - changed-file bridge：把 OpenHub/opencode 返回的 path 映射成 MNote document pane 打开/刷新
 ```
@@ -538,7 +572,7 @@ MNote 不替 OpenHub 判断何时调用知识库、何时用 skill/MCP、如何
 用户输入
   -> MNote Page AI host 中的 OpenHub AI 面板
   -> OpenHub 前端调用 OpenHub FastAPI
-  -> OpenHub FastAPI 使用 OpenHub session/message/skill/MCP/tool permission
+  -> OpenHub FastAPI 使用 OpenHub session/message/skill/tool permission 与 MNote 注册的 WeKnora tool scope
   -> OpenHub FastAPI 调 opencode serve
   -> opencode 读写 MNote 授权 rootUri 内文件
   -> OpenHub session/message/tool history 持久化
@@ -552,14 +586,14 @@ MNote 不在消息主链里重写 OpenHub planner，也不解析知识需求后
 
 ```text
 OpenHub/opencode 判断需要知识
-  -> 按 MCP/skill/tool 规范调用已注册的 WeKnora 工具
+  -> 按 skill/tool/MCP 规范调用已注册的 WeKnora 工具
   -> WeKnora MCP/CLI/API 返回 chunks/references
   -> OpenHub/opencode 把结果纳入当前 session/tool result
   -> 用户点击 citation/reference 时
   -> MNote open-reference bridge 按 source registry / allowed roots 映射并打开对应页面
 ```
 
-MNote 不负责替 OpenHub 判断 knowledge scope；scope 在注册 WeKnora MCP/skill/tool 时由 MNote 根据当前用户、workspace、allowed roots 预先约束。
+MNote 不负责替 OpenHub 判断 knowledge scope；scope 在注册 WeKnora CLI/MCP/skill/tool 时由 MNote 根据当前用户、workspace、allowed roots 预先约束。
 
 ### 9.3 知识库生成与展示
 
@@ -570,27 +604,38 @@ MNote 知识库展示层上传/添加资料
   -> WeKnora file/manual/url ingest
   -> 写 mnote_knowledge_sources registry
   -> FileTree/Knowledge UI 显示 indexing 状态
-  -> 生成/更新可供 OpenHub/opencode 使用的 WeKnora MCP/skill/tool 配置
+  -> 生成/更新可供 OpenHub/opencode 使用的 WeKnora CLI/MCP/skill/tool 配置
 ```
 
 OpenHub 不管理知识库生成页面；它只消费已经按 MNote 授权边界配置好的 WeKnora 工具。知识库生成页面复用 WeKnora KB 页面体验，但 source 选择应以 MNote 本地文件/文件夹集合为入口。
 
 ## 10. 可执行 Checklist
 
+本节保留主线阶段清单；逐文件、逐接口、逐 smoke 的细化执行项见 `design/07-ai/process/7-68-openhub-weknora-mnote-deep-fusion-checklist-v1.md`。实施时先完成配套清单 P0/P1，再回填本文状态；不要把 P2/P3 优化提前混入 MVP。
+
+
 ### 10.1 设计与旧路径冻结
 
-- [ ] 在 `7-65` 标注官方 opencode iframe 只保留为 fallback，不再作为 Page AI 产品主线。
-- [ ] 在 `7-66` 标注自研 native UI 只保留为 fallback，不再继续扩自研聊天框。
-- [ ] 在 `7-67` 标注已被本文覆盖：OpenHub 路线从“参考/重写”改为“嵌入 AI 面板 + 保留 FastAPI/Redis/opencode client”。
-- [ ] 将本文保留在 `design/07-ai/process/`，作为当前 Page AI 嵌入式集成主设计。
-- [ ] 在相关 design / bugs / testing 文档中统一术语：WeKnora 是唯一知识库底座，MNote 是知识库展示和文件真相层，OpenHub KnowledgeManager 不作为知识库页。
-- [ ] 搜索并标记仍把 LightRAG 描述为默认知识库 provider 的文案，改成 legacy/fallback。
+- [x] 在 `7-65` 标注官方 opencode iframe 只保留为 fallback，不再作为 Page AI 产品主线。
+- [x] 在 `7-66` 标注自研 native UI 只保留为 fallback，不再继续扩自研聊天框。
+- [x] 在 `7-67` 标注已被本文覆盖：OpenHub 路线从“参考/重写”改为“嵌入 AI 面板 + 保留 FastAPI/Redis/opencode client”。
+- [x] 将本文保留在 `design/07-ai/process/`，作为当前 Page AI 嵌入式集成主设计。
+- [x] 在本轮授权写入范围内统一术语：WeKnora 是唯一知识库底座，MNote 是知识库展示和文件真相层，OpenHub KnowledgeManager 不作为知识库页；bugs/testing 文档未在本任务授权写入范围内修改。
+- [x] 在本轮授权写入范围内搜索并标记仍把 LightRAG 描述为默认知识库 provider 的文案，改成 legacy/fallback。
+
+#### 10.1 证据
+
+- `design/07-ai/process/7-65-opencode-webui-embed-page-ai-v1.md`：已冻结为官方 opencode WebUI iframe fallback；上下文口径从 LightRAG 引用改为 WeKnora 引用，旧 LightRAG 仅 legacy/fallback。
+- `design/07-ai/process/7-66-opencode-native-page-ai-ui-v1.md`：已冻结为 native UI fallback / debug receipt，不再扩写自研聊天框。
+- `design/07-ai/process/7-67-openhub-page-ai-fusion-v1.md`：已标注被本文覆盖，路线改为嵌入 OpenHub AI 面板并保留 OpenHub FastAPI/Redis/opencode client。
+- `design/07-ai/process/7-68-openhub-weknora-mnote-deep-fusion-v1.md`：保留在 `process/`，作为当前 Page AI 嵌入式集成主设计；10.2-10.9 后续执行细化到 `design/07-ai/process/7-68-openhub-weknora-mnote-deep-fusion-checklist-v1.md`。
 
 ### 10.2 OpenHub 服务栈接入
 
 - [ ] 确认 OpenHub 本机源码路径、启动命令、依赖文件和默认端口。
-- [ ] 确认 OpenHub FastAPI 是否真实依赖 Redis；记录 Redis host/port/env 和启动顺序。
+- [ ] 确认 OpenHub FastAPI Redis 的真实用途：token/rate-limit/cache/临时态；记录 Redis host/port/db/env 和启动顺序，避免写成消息真相或队列主链。
 - [ ] 确认 OpenHub FastAPI 调 opencode 的配置项：opencode base URL、directory 参数、BasicAuth、模型/provider env。
+- [ ] 确认 OpenHub 自动 Git snapshot 的触发点，并通过配置/补丁关闭 `stream.py`、`task_executor.py` 中的自动 snapshot 写链。
 - [ ] 在 `scripts/desktop-hot.js` 或等价 dev-hot 链路中增加 OpenHub FastAPI、Redis、opencode serve 的启动/跳过/health check。
 - [ ] 增加 OpenHub health endpoint 探针；失败时错误信息区分 FastAPI、Redis、opencode。
 - [ ] 禁用 OpenHub launcher 的 kill-port 或 destructive workspace 行为，避免影响 MNote dev 进程。
@@ -605,7 +650,7 @@ OpenHub 不管理知识库生成页面；它只消费已经按 MNote 授权边
 - [ ] 在 MNote 后端实现或扩展 OpenHub host/proxy bootstrap endpoint，输出 user/workspace/session/tool scope。
 - [ ] 禁止前端持有 OpenHub JWT/localStorage 登录真相；OpenHub 用户态由 MNote 后端注入或代理。
 - [ ] rootUri / workspace 切换时新建或切换 OpenHub session，旧 session 标记 stale/archived。
-- [ ] 不同 MNote 用户访问同一页面时不得复用同一 OpenHub session、skill scope、MCP scope、tool permission scope。
+- [ ] 不同 MNote 用户访问同一页面时不得复用同一 OpenHub session、skill scope、tool permission scope 或 WeKnora tool scope。
 - [ ] 写 control-plane 测试：binding 受 user/workspace/rootUri 隔离，跨用户查询失败。
 
 ### 10.4 OpenHub AI 面板嵌入
@@ -613,7 +658,7 @@ OpenHub 不管理知识库生成页面；它只消费已经按 MNote 授权边
 - [ ] 在 MNote Page AI sidebar host 中选择 iframe 或 reverse proxy 嵌入方式。
 - [ ] 只暴露 OpenHub AI 页面路由；Login/Admin/Team/Scheduler/SmartEntity 默认不可达。
 - [ ] OpenHub workspace selector 固定到 MNote 授权 rootUri 派生 workspace。
-- [ ] 保留 OpenHub AI 主界面、history/session、MCP 设置、skill/agent 设置、tool/model permission、tool card、diff、changed files、运行日志。
+- [ ] 保留 OpenHub AI 主界面、history/session、skill/agent 设置、tool/model permission、tool card、diff、changed files、运行日志；MCP 管理面如源码不存在，不把它作为已完成 OpenHub UI 依赖。
 - [ ] FileManager 入口若出现在 AI 面板内，跳转 MNote document pane / FileTree 或禁用。
 - [ ] KnowledgeManager 入口若出现在 AI 面板内，跳转 MNote WeKnora 知识库页或隐藏。
 - [ ] MNote context 通过 postMessage、proxy header 或 bootstrap JSON 注入 page path、title、selection、rootUri、allowed roots。
@@ -634,7 +679,7 @@ OpenHub 不管理知识库生成页面；它只消费已经按 MNote 授权边
 ### 10.6 WeKnora 知识库页面替换
 
 - [ ] 盘点 WeKnora `KnowledgeBaseList.vue`、`KnowledgeBase.vue`、`KnowledgeBaseEditorModal.vue`、`knowledge-processing-timeline.vue` 的依赖。
-- [ ] 决定复用方式：嵌 WeKnora frontend route、抽组件、或做 MNote adapter 页面复刻 WeKnora 交互。
+- [ ] 决定复用方式：优先 MNote adapter 页面复刻 WeKnora 交互；可选抽组件；不采用 iframe WeKnora 全量 frontend route 作为产品主线。
 - [ ] 知识库定义为 MNote 授权文件/文件夹/page resource 集合，不创建新的文件内容真相。
 - [ ] 建立 source set 模型：kb id、workspace id、rootUri、source path/resource id、provider kb id、provider knowledge id、source hash。
 - [ ] source 选择 UI 接 MNote FileTree / resource picker，而不是 WeKnora 自己的独立文件真相。
@@ -648,10 +693,10 @@ OpenHub 不管理知识库生成页面；它只消费已经按 MNote 授权边
 - [ ] 抽出 `KnowledgeProvider` 或等价 provider boundary，新增 `weknora` 实现。
 - [ ] `/api/knowledge-rag/status` 改为检查 WeKnora health、KB 映射、source registry 状态。
 - [ ] `/api/knowledge-rag/ingest` 改为 WeKnora ingest，并写入 provider KB / knowledge / source hash。
-- [ ] `/api/knowledge-rag/search` 改为 WeKnora `/api/v1/knowledge-search` 或 KB 级 hybrid-search。
+- [ ] `/api/knowledge-rag/search` 改为 WeKnora `/api/v1/knowledge-search`；单 KB 调试/CLI/MCP 可走 `/api/v1/knowledge-bases/:id/hybrid-search`。
 - [ ] `/api/knowledge-rag/query` 第一阶段由 WeKnora search results + citations 组成 query result，不启用 WeKnora chat session。
 - [ ] `/api/knowledge-rag/section-context` 改为基于 WeKnora chunk + MNote 本地 locator，不读 LightRAG sidecar。
-- [ ] `open-reference` 从 WeKnora `knowledge_id/chunk_id/knowledge_base_id` 回查 MNote registry，再生成 MNote locator。
+- [ ] `open-reference` 从 WeKnora `knowledge_id/chunk_id/knowledge_base_id` 回查 MNote registry，再生成 MNote locator；保留 `content/matched_content/match_type/metadata/chunk_metadata/image_info/parent_chunk_id/sub_chunk_id` 供 citation 与诊断。
 - [ ] WeKnora RRF score 不沿用 LightRAG 阈值；UI 只显示排序分或弱化分值解释。
 - [ ] 保留旧 LightRAG provider 为 legacy fallback，但默认隐藏且不作为 smoke 基线。
 - [ ] 更新现有 knowledge-rag smoke，把 provider 断言从 `lightrag` 改为 `weknora`。
@@ -659,7 +704,7 @@ OpenHub 不管理知识库生成页面；它只消费已经按 MNote 授权边
 
 ### 10.8 WeKnora MCP/CLI Tool Bridge
 
-- [ ] 选定第一阶段 MCP surface：Go CLI `weknora mcp serve` 或 Python `mcp-server`，记录读写能力差异。
+- [ ] 第一阶段 MCP surface 选定 Go CLI `weknora mcp serve` 或 MNote facade 包装后的等价只读工具面；Python `mcp-server` 只作为后续写能力参考，不默认暴露给 OpenHub/opencode。
 - [ ] 默认暴露只读工具：`mnote.weknora.search`、`mnote.weknora.list_sources`、`mnote.weknora.get_source_status`、`mnote.weknora.open_reference`。
 - [ ] 写工具 manifest / skill，使 OpenHub/opencode 能在当前 session scope 内调用 WeKnora。
 - [ ] tool 调用前注入 KB/source allowlist，不让 OpenHub/opencode 查询未授权 source。
@@ -672,7 +717,7 @@ OpenHub 不管理知识库生成页面；它只消费已经按 MNote 授权边
 - [ ] `npm run dev:hot` 启动或检查 MNote、OpenHub FastAPI、Redis、opencode、WeKnora。
 - [ ] 登录 `mnote.e2e@example.com`，确认没有 OpenHub/WeKnora 登录跳转。
 - [ ] 打开真实 Markdown 页面并打开 Page AI。
-- [ ] Page AI 嵌入 OpenHub AI 面板，history/session/MCP/skill/agent/tool permission 入口仍可用。
+- [ ] Page AI 嵌入 OpenHub AI 面板，history/session/skill/agent/tool permission 入口仍可用；WeKnora MCP/CLI tool 状态可见。
 - [ ] OpenHub Login/Admin/FileManager/KnowledgeManager 非 AI 入口被隐藏、404 或跳转 MNote。
 - [ ] 发送消息后 OpenHub session/message/history 持久化，刷新浏览器可恢复。
 - [ ] 让 AI 修改当前 rootUri 内 Markdown，MNote document pane 可刷新并显示变更。
@@ -690,8 +735,8 @@ OpenHub 不管理知识库生成页面；它只消费已经按 MNote 授权边
 | 知识库 UI | OpenHub KnowledgeManager 暂不使用 | WeKnora KB list/detail/upload/status 体验可复用 | MNote shell + WeKnora KB UI adapter | 选 WeKnora 知识库页面体验，嵌入 MNote 外壳 |
 | 知识库底座 | OpenHub 自带知识库暂不用 | 强 RAG/Wiki/Graph | MNote registry + WeKnora | 选 WeKnora |
 | 文件打开 | workspace path | knowledge filename | MNote resource/open-reference | 选 MNote |
-| 权限 | 模型/工具/skill/MCP | tenant RBAC | MNote scope + OpenHub/opencode 权限规范 + provider 防线 | 组合，以 MNote scope 为边界 |
-| Agent 编辑 | opencode | WeKnora agent-chat 暂弃用 | opencode 编辑 + WeKnora MCP/CLI/API 知识工具 | 组合 |
+| 权限 | 模型/工具/skill；MCP 由工具配置承接 | tenant RBAC | MNote scope + OpenHub/opencode 权限规范 + provider 防线 | 组合，以 MNote scope 为边界 |
+| Agent 编辑 | opencode | WeKnora agent-chat 暂弃用 | opencode 编辑 + WeKnora CLI/MCP/API 知识工具 | 组合 |
 | UI 成本 | 嵌入 AI 面板，裁剪非 AI 入口 | 不适合 Page AI 编辑侧栏 | MNote host + OpenHub AI 面板 | 选 OpenHub AI 面板嵌入 |
 | 运维 | OpenHub FastAPI + Redis + opencode 运行 | WeKnora 服务 | MNote 启动/检查 OpenHub/opencode/Redis/WeKnora，提供 binding/tool 配置 | 选 OpenHub 栈运行 + MNote 边界控制 |
 
@@ -699,7 +744,7 @@ OpenHub 不管理知识库生成页面；它只消费已经按 MNote 授权边
 
 ### 12.1 风险：三套权限漂移
 
-防线：MNote 是浏览器入口和授权边界；OpenHub/opencode 只能拿到 MNote 派生 scope、allowed roots、tool/MCP 配置，不直接获得未过滤 workspace/rootUri。
+防线：MNote 是浏览器入口和授权边界；OpenHub/opencode 只能拿到 MNote 派生 scope、allowed roots、tool/CLI/MCP 配置，不直接获得未过滤 workspace/rootUri。
 
 补充：WeKnora RBAC 只能作为 provider 防线，不作为 MNote 授权来源；RBAC 关闭、API key 复用或共享空间变化时，MNote 过滤结果仍必须保持一致。
 
@@ -736,16 +781,27 @@ MVP 通过必须同时满足：
 - 同一 MNote 用户跨浏览器可恢复绑定到当前页面/rootUri 的 OpenHub session。
 - opencode 在当前 rootUri 下能真实读取/修改 Markdown。
 - changed file chips 与 DiffViewer path 能用 MNote 打开。
+- MNote 知识库页面已由 `MNote shell + WeKnora KB adapter` 替换简陋页：可创建/列出/查看 KB，可从 MNote FileTree/resource picker 添加本地文件或文件夹，可显示 WeKnora processing/indexed/failed 状态。
+- `/api/knowledge-rag/status/search/query/section-context/open-reference/delete-source` 默认 provider 为 `weknora`；旧 LightRAG 只作为 `lightrag_legacy` 隐藏 fallback，不再作为默认 smoke 基线。
 - WeKnora search/MCP/CLI 工具返回真实引用，citation 经 registry 映射后可回跳 MNote 文件；失败时明确定位降级，且不能把 `knowledge_filename` 伪装成本地路径。
+- OpenHub/opencode 通过 MNote 注册的 WeKnora tool scope 调用知识库；MNote 不替 OpenHub 做 planner 判断，只限制 KB/source allowlist 与 open-reference。
 - `npm run dev:hot` 能拉起并检查必要 runtime；失败时错误页给出 OpenHub FastAPI、Redis、opencode、WeKnora 或 OpenHub session binding 哪个不可达。
 - MNote Page AI 路径不触发 OpenHub 登录跳转；OpenHub FileManager/KnowledgeManager/Admin 等非 AI 入口被隐藏、404 或跳转 MNote；消息真相保留在受 MNote scope 隔离的 OpenHub session 中，不触发 Git snapshot/restore 自动写链。
 
 ## 14. 本轮源码依据
 
-- OpenHub 源码：`/tmp/mnote-openhub-research/OpenHub`
+- OpenHub 源码：`/tmp/mnote-openhub-research/OpenHub`（当前无 `.codegraph/`，本轮以 targeted `find/rg/sed` 复核）
 - WeKnora 本机部署：`/mnt/Data1T/Mnote_data/weknora/WeKnora`
 - MNote Page AI runtime：`rust/crates/mnote-web/browser/sidebar-page-ai-runtime.js`
 - MNote document pane bridge：`rust/crates/mnote-web/browser/document-editor-adapter-runtime.js`
 - MNote opencode route：`rust/crates/mnote-web/src/routes/page_ai_opencode.rs`
 - MNote knowledge route：`rust/crates/mnote-web/src/routes/knowledge_rag.rs`
 - MNote auth/session route：`rust/crates/mnote-web/src/routes/session.rs`、`rust/crates/mnote-web/src/routes/gateway.rs`
+
+- OpenHub FastAPI 入口：`/tmp/mnote-openhub-research/OpenHub/smart-query-backend/app/main.py`
+- OpenHub opencode client / launcher：`/tmp/mnote-openhub-research/OpenHub/smart-query-backend/app/services/opencode_client.py`、`/tmp/mnote-openhub-research/OpenHub/smart-query-backend/app/services/opencode_launcher.py`
+- OpenHub streaming / Git snapshot 触发：`/tmp/mnote-openhub-research/OpenHub/smart-query-backend/app/services/stream.py`、`/tmp/mnote-openhub-research/OpenHub/smart-query-backend/app/services/task_executor.py`
+- OpenHub session/auth/files/knowledge/admin：`/tmp/mnote-openhub-research/OpenHub/smart-query-backend/app/api/session.py`、`auth.py`、`files.py`、`knowledge.py`、`admin.py`
+- WeKnora SearchResult / hybrid-search client：`/mnt/Data1T/Mnote_data/weknora/WeKnora/client/knowledgebase.go`
+- WeKnora MCP CLI：`/mnt/Data1T/Mnote_data/weknora/WeKnora/cli/internal/mcp/tools.go`、`/mnt/Data1T/Mnote_data/weknora/WeKnora/cli/cmd/mcp/serve.go`
+- WeKnora KB UI：`/mnt/Data1T/Mnote_data/weknora/WeKnora/frontend/src/views/knowledge/`