lix/mnote
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
2f5902e3e72e8f6aa05408a6dc08502a44cf24e9
mnote/recycle/20260712-pi-ts-openhub-retirement/design/07-ai/process/7-68-openhub-weknora-mnote-deep-fusion-v1.md
T

56 KiB
Raw Blame History

[stale] 7-68 OpenHub + WeKnora + MNote Page AI 嵌入式集成设计 v1

状态：stale / reference-only（不再作为当前 process 主线） Owner：07-ai / mnote-web / control-plane / knowledge-provider 日期：2026-06-25

2026-07-03 stale 说明：本文仍保留 Page AI / OpenHub / WeKnora 融合的历史设计上下文，但当前 runtime 口径已改为 OpenHub / native agent + LightRAG + Turso/libSQL。本文中将 WeKnora 定义为默认知识库 provider、LightRAG 退为 legacy 的内容不再作为当前主线执行；当前知识库主路径以 LightRAG provider 和 MNote provider-neutral mnote.knowledge_rag.* facade 为准。WeKnora 仅保留为历史设计、参考实现或备用 provider 边界。

执行说明：本文不再是当前主设计，仅作为 WeKnora 方向历史方案和 OpenHub 集成参考。当前实现与后续新增能力不得从本文推导出“WeKnora 是默认 provider”或“LightRAG 已退出主线”的口径。

0. 结论先行

MNote Page AI 不应再沿“官方 opencode WebUI iframe”或“自研简陋聊天框”继续堆功能。新的主路线是：

MNote 当前文档页 / workspace / auth / resource truth
  ├─ Page AI UI：嵌入 OpenHub AI 界面（只暴露 AI 面板能力）
  ├─ 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、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/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/tool permission/FastAPI/Redis 可以作为 Page AI 运行真相，但必须受 MNote 派生的用户与 workspace scope 隔离；WeKnora 保持知识库底座真相，MNote 只做展示、授权和回跳映射。

1. 背景与当前状态

1.1 已知事实

  • OpenHub 是一个基于 opencode 的多用户 AI 平台参考实现，前端 React/AntD 组件较完整，包含 Chat、History、ToolCall、Diff、FileManager、KnowledgeManager 等。
  • OpenHub 多用户主要是应用层隔离：后端带 directory=<user workspace> 调 opencode，自己用 SQLite 管用户、session、message、权限、技能/工具权限，并可能对 workspace 执行 Git snapshot / restore。
  • OpenHub 自带知识库是轻量 knowledge_bases + knowledge_sources + 本地全文 content + SQLite LIKE 候选 + Python BM25/TF-IDF rerank + prompt stuffing，不是完整 RAG 底座；默认注入上下文约 1200 字符。
  • WeKnora 已部署在本机 /mnt/Data1T/Mnote_data/weknora/WeKnora，并提供知识库、知识文件、chunk、/api/v1/knowledge-search、knowledge-chat、agent-chat、tenant/RBAC、共享空间、CLI/MCP 等能力。
  • MNote 当前 active 代码仍大量使用 knowledge_rag / LightRAG 命名；用户已明确当前放弃 LightRAG，因此需要 provider-neutral 化并切到 WeKnora。
  • MNote 当前已有 /api/page-ai/opencode/* 反代/绑定雏形和 ai_external_conversation_bindings；在本路线下应转为 OpenHub host/proxy/session binding 与 artifact/open-reference index，而不是重写 OpenHub FastAPI 的 opencode client。

1.2 本设计覆盖范围

本设计替代 7-65 的官方 opencode iframe 产品主线，并收敛 7-67 的 OpenHub 初步融合设想。核心不是重写三套系统，而是保留各自已有能力，只对冲突点做最小胶水：

  1. 登录/用户/权限冲突。
  2. WeKnora 知识库底座、MNote 展示层、MNote 注册给 OpenHub/opencode 的 CLI/MCP/skill/tool 调用边界。
  3. 页面/文件打开、changed files、citation 回跳边界。

2. 三方职责边界

能力 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 / 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 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 MNote 不存 Page AI 消息真相 OpenHub Redis 主要用于 token/rate-limit/cache/临时态；消息真相在 SQLite WeKnora Redis/Asynq/Langfuse 由 WeKnora stack 管理 Redis 归各自服务栈；不作为 MNote 权限/文件/知识库真相

3. 登录、OpenHub 隔离与 WeKnora 授权融合

3.1 核心更正

这里不能简单写成“只使用 MNote 单一用户认证，然后 OpenHub/WeKnora 都完全无用户”。更准确的模型是保留各自用户/权限机制中有价值的部分，并由 MNote 在边界上做最小嫁接：

MNote 登录态 / user_id / workspace grants
  ├─ 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、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 登录体系。

3.2 冲突

OpenHub 和 WeKnora 的用户模型对 MNote 的影响不同：

  • OpenHub 前端会使用 auth_token / JWT / localStorage，并在 401 后跳转到 /login。
  • 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、工具审批、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、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 内部防线。

3.4 映射建议

短期本机/local-first：

MNote user_id + workspace_id/rootUri
  -> OpenHub runtime identity: mnote:{user_id}:{workspace_id}:{root_hash}
  -> OpenHub scopes:
       session_scope = user_id + workspace_id + rootUri + page_resource_id
       skill_scope = user_id + workspace_id + rootUri
       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 映射

中期多用户/局域网：

MNote user_id + workspace membership
  -> OpenHub runtime identity 按 user/workspace 派生或映射到受控 OpenHub user
  -> MNote credential vault 选择 WeKnora service profile/API key
  -> WeKnora 默认按 workspace/profile/KB 隔离，不强制每个 MNote 用户对应 WeKnora 用户
  -> 所有 OpenHub 可见性仍由 MNote 登录态 + OpenHub scope 校验
  -> 所有 WeKnora 结果仍由 MNote source registry / allowed roots 二次过滤

不要在第一阶段为每个 MNote 用户强行同步 WeKnora RBAC；这会放大生命周期与权限同步复杂度。相反，第一阶段应优先保证 OpenHub 派生上下文隔离，因为 Page AI 的 session、skill、tool permission、WeKnora tool scope 和文件变更都直接依赖 MNote 登录态。

4. OpenHub Session / Message 真相

4.1 核心更正

这里不应设计“三方 session 融合”，也不应新增一套 MNote page_ai_messages 作为 AI 面板消息真相。应保留 OpenHub 已做好的 session/message 能力，只做 MNote ownership binding：

MNote Page AI 面板
  -> MNote 自有 Page AI 映射 OpenHub session/conversation
  -> OpenHub session / conversation 是唯一 AI 面板会话真相
  -> MNote control-plane 只保存绑定、索引和打开/权限映射
  -> WeKnora 不参与 Page AI 会话真相
  • 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。

4.2 冲突

真正的冲突不是“三套消息历史融合”，而是：

  • OpenHub session/message 本来就是 AI 面板的产品模型，MNote 自建 page_ai_messages 会变成第二份聊天真相。
  • MNote 仍需要知道某个 OpenHub session 属于哪个 mnote_user_id + workspace_id/rootUri + page_resource_id，否则无法做跨浏览器恢复、权限过滤和打开文件回跳。
  • WeKnora 的 agent-chat / knowledge-chat 若混入主链，会引入第二套 provider chat session；当前应明确弃用。

4.3 决策

MNote control-plane 只新增或复用绑定/索引层，不新增消息全文主表。表名可复用现有 ai_external_conversation_bindings 并扩展 metadata，不要求一定新建下列物理表：

page_ai_openhub_bindings
  id
  mnote_user_id
  workspace_id
  root_uri
  page_resource_id
  page_absolute_path
  openhub_user_key
  openhub_session_id
  opencode_session_id nullable
  status = active | archived | stale
  metadata_json
  created_at / updated_at / archived_at

page_ai_artifact_index
  id
  binding_id
  openhub_session_id
  kind = changed_file | diff | citation | tool_call_ref | attachment_ref
  provider = openhub | opencode | weknora
  provider_id
  payload_json
  mnote_resource_id nullable
  mnote_open_reference_json nullable
  created_at

page_ai_artifact_index 不是消息真相，只是为了 MNote sidebar/document pane 能打开 changed files、diff、citation、attachment。消息正文、历史列表、tool card 展示、retry/隐藏状态仍从 OpenHub session/conversation 读取。

4.4 OpenHub session scope

OpenHub session 必须绑定 MNote 登录态派生的 scope：

openhub_session_scope = hash(mnote_user_id, workspace_id, root_uri, page_resource_id)
openhub_user_key = stable_hash(mnote_user_id)
openhub_workspace_key = stable_hash(workspace_id, root_uri)
  • 同一用户同一页面可恢复最近 active OpenHub session。
  • 切换 rootUri 或 workspace 必须新开 OpenHub session；旧 session 标记 stale 或 archived。
  • 不同 MNote 用户不得共享同一个 OpenHub session、skill scope、tool permission scope 或 WeKnora tool scope。
  • MNote boundary 对 OpenHub session 的读写必须先校验 mnote_session 与 binding ownership。

4.5 WeKnora session policy

第一阶段不使用 WeKnora knowledge-chat / agent-chat 作为 Page AI 会话层：

  • WeKnora 通过 MCP/CLI/API 暴露知识库能力给 OpenHub/opencode 工具链。
  • WeKnora 检索结果返回 chunk/reference，MNote 负责 source registry 映射和 citation 回跳。
  • 如果未来启用 WeKnora agent-chat，只能作为 OpenHub tool call 的内部 provider call，不能成为 Page AI 历史会话真相。

5. Knowledge 融合

5.1 OpenHub 知识库定位

OpenHub KnowledgeManager 第一阶段不复用；其后端知识库也不应成为主线：

  • 数据模型只有 base/source，没有持久 chunk/citation/embedding。
  • 检索是 SQLite LIKE 候选 + BM25/TF-IDF 重排。
  • 注入是 prompt stuffing，总上下文默认约 1200 字符。

适合：作为 OpenHub 源码理解和对照材料。

不适合：MNote 知识库主线、fallback 知识库、KnowledgeManager 页面复用、长期资料库、复杂 PDF/图片/OCR、可点击 citation、跨文档图谱、长期 RAG。

5.2 WeKnora 能力定位

WeKnora 应承担 MNote 知识库 provider：

  • 知识库类型：以 WeKnora KnowledgeBase.Type 和 FAQ 配置为准；Wiki/图谱属于 WeKnora Wiki mode / graph 能力，不能未经接口枚举直接当作 KB type 写死。
  • 导入：文件、URL、Markdown/手工知识、外部数据源。
  • 文档处理：chunk、OCR/VLM/ASR、图谱抽取、问题生成、reparse。
  • 检索：多 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 作内部防线。

MNote 侧不要把 WeKnora RBAC 当唯一隔离边界：WeKnora RBAC 可能受配置开关影响，关闭时 guard 可能记录但放行；MNote 必须始终按 mnote_session + workspace/rootUri + source registry + allowed roots 二次过滤。

5.3 MNote Knowledge Adapter / Search Replacement

保留 MNote 对外 canonical API：

/api/knowledge-rag/status
/api/knowledge-rag/ingest
/api/knowledge-rag/search
/api/knowledge-rag/query
/api/knowledge-rag/section-context
/api/knowledge-rag/open-reference
/api/knowledge-rag/delete-source
/api/knowledge-rag/prune-registry

但内部主链从 LightRAG 聚合检索切到 WeKnora。当前 knowledge_rag.rs 的 /api/knowledge-rag/search、/api/knowledge-rag/query、/api/knowledge-rag/section-context 仍围绕 LightRAG /query/search、/query/data、sidecar block、reference mapper、rank/dedupe 展开；替换时不能只改 endpoint，需要把 provider 调用、结果模型、locator 映射和排序语义一起替换。

目标 adapter：

trait KnowledgeProvider {
  fn status(root_uri, workspace_id) -> ProviderStatus;
  fn ensure_kb(scope) -> ProviderKbRef;
  fn ingest(source) -> ProviderKnowledgeRef;
  fn search(query, scope, filters) -> Vec<ProviderReference>;
  fn query(question, scope, filters) -> ProviderQueryResult;
  fn section_context(provider_ref, query, scope) -> ProviderSectionContext;
  fn open_reference(provider_ref) -> MnoteOpenReference;
  fn delete_source(provider_ref) -> DeleteResult;
}

新增 weknora provider 实现；旧 LightRAG provider 标记 legacy，不再作为默认。第一阶段 query 可以由 WeKnora search results + citations 组成 answer envelope，不启用 WeKnora knowledge-chat / agent-chat 会话。

检索替换原则：

  • /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 是 provider 排序/融合分，不能沿用 LightRAG 相似度阈值、百分比相似度或旧 rank 解释。
  • 引用映射：WeKnora knowledge_id / chunk_id / knowledge_base_id 只用于回查 registry，不能直接作为 MNote 文件路径。

WeKnora search result 到 MNote registry 的最低字段映射：

WeKnora 字段 MNote 派生字段 说明
id providerChunkId WeKnora chunk id
knowledge_id providerKnowledgeId 回查 registry 的主键之一
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 / KnowledgeBaseEditorModal.vue / 上传与 processing timeline 组件体验，作为 MNote 知识库展示层的实现。当前边界是：

MNote Knowledge UI（复用 WeKnora KB list/detail/upload/status 体验）
  -> MNote source set / source registry / allowed roots
  -> WeKnora ingest / search / status / open-reference

MNote Page AI / OpenHub-style session
  -> opencode 按 skill/tool/MCP 规范自行决定 tool call；MNote 只提供受限工具配置和 open-reference bridge
  -> 已注册的 `mnote.weknora.*` MCP/CLI/API tool
  -> WeKnora search/query
  -> tool result 回 OpenHub session

决策：

  • 知识库不是新的文件真相：真相永远是 MNote 授权 rootUri 下的本地文件/文件夹/page resource；知识库是这些 source 的命名集合、索引状态和检索配置。
  • 唯一知识库底座是 WeKnora：OpenHub 自带 knowledge tables、KnowledgeManager 页面和 prompt stuffing 知识库第一阶段全部不使用。
  • 知识库页面选择 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，而是三类接口：

MNote UI canonical API:
  /api/knowledge-rag/status
  /api/knowledge-rag/ingest
  /api/knowledge-rag/search
  /api/knowledge-rag/open-reference
  /api/knowledge-rag/delete-source
  /api/knowledge-rag/prune-registry

WeKnora-page-in-MNote adapter:
  list_kbs / create_kb / update_kb / delete_kb
  list_sources / add_source_set / upload_or_link_source / reparse_source / delete_source
  get_processing_status / get_citation_open_reference

OpenHub/opencode tool facade:
  mnote.weknora.search
  mnote.weknora.open_reference
  mnote.weknora.list_sources
  mnote.weknora.get_source_status

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 两层：

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 字段应迁移为 provider-neutral registry；当前 JSON 文件 lightrag-source-registry.json 中的 lightRagDocId/lightRagStatus/lightRagFilePath/symlinkPath 等字段必须兼容读取并迁移或双写一段时间。目标结构为：

mnote_knowledge_sources
  id
  user_id
  workspace_id
  root_uri
  resource_id nullable
  source_uri
  source_path
  source_hash
  provider = weknora | lightrag_legacy | local_fallback
  provider_kb_id
  provider_knowledge_id
  provider_doc_id nullable
  provider_status
  index_status = queued | parsing | indexed | failed | stale | deleted
  title
  source_type
  tags_json
  citation_locator_json
  metadata_json
  created_at / updated_at / deleted_at

关键原则：provider 返回的 knowledge_filename / chunk_id 不能直接当 MNote 文件真相，必须回查 registry 映射到 resource_id/source_uri/open_reference。

6. 页面打开 / 文件打开 / 引用回跳融合

6.1 冲突

  • MNote 自己就是 FileManager：resource tree / file tree / document pane / resource tab 是唯一页面/文件打开入口。
  • 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 页面。注意：这里的“不使用 WeKnora Web UI”只针对 Page AI 对话壳、引用打开链路和文件打开链路；知识库管理页面仍按 5.4 复用 WeKnora KB 页面体验，但必须运行在 MNote shell 与 MNote 权限/source registry 后面。

6.2 决策

所有打开动作只发生在 MNote Page AI / document pane 内：

  • changed file chip 点击：window.__mnoteDocumentPaneRuntime.openResourceInActiveTab()。
  • 当前页被修改：window.__mnoteDocumentPaneRuntime.refreshPrimaryDocument() 或 watcher 链路。
  • 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 作为页面读写入口。
  • 不在 Page AI / 引用打开链路嵌入 WeKnora 全量 Web UI，不让 WeKnora 决定打开哪个 MNote 页面。

6.3 MNote Page AI open reference payload

{
  "provider": "weknora",
  "providerKbId": "kb-...",
  "providerKnowledgeId": "...",
  "providerChunkId": "...",
  "sourceId": "mnote-source-...",
  "rootUri": "file:///...",
  "sourcePath": "docs/a.md",
  "locator": {
    "kind": "markdown-range",
    "heading": "...",
    "lineStart": 12,
    "lineEnd": 20,
    "quote": "..."
  }
}

后端必须二次校验：当前用户、rootUri、workspace、source ownership、allowed read scope。这个 payload 只服务 MNote Page AI 中的点击打开，不是 OpenHub FileManager 或 WeKnora 前端合同。

7. OpenHub FastAPI / Redis / opencode Runtime 安排

7.1 核心边界

这里不应让 MNote 重写 OpenHub FastAPI 的 opencode client。最小干扰路径是运行 OpenHub AI 后端栈，让 MNote 只做宿主、scope 注入、入口裁剪和回跳桥：

MNote Page AI host
  -> MNote 校验登录态、workspace、rootUri、allowed roots
  -> 注入/映射 OpenHub user workspace + session/skill/tool scope
  -> OpenHub AI UI
  -> 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、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 对应页面。

7.2 FastAPI 的具体作用

OpenHub FastAPI 在本设计中保留以下作用：

  • 管理 OpenHub conversation/session/message/history。
  • 管理 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 CLI/MCP/API tool 配置。

OpenHub FastAPI 不保留以下作用：

  • 不作为 MNote 登录入口。
  • 不接管 MNote resource tree / FileTree / document pane。
  • 不启用 OpenHub 自带 KnowledgeManager 作为知识库 UI。
  • 不启用 OpenHub 自带轻量 knowledge tables 作为 RAG 底座。
  • 不执行 Git snapshot / restore / revert，除非未来另开设计并经 MNote 显式确认。

7.3 Redis 安排

  • 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

MNote 注入给 OpenHub / opencode 的 context：

- 当前 MNote 用户/匿名显示名，不含敏感 cookie/token
- 当前 workspace/rootUri
- 当前页面标题、真实 Markdown path、resource id
- selection 摘要
- allowed roots / write constraints
- OpenHub session scope / skill scope / tool permission scope
- WeKnora tool scope：允许查询的 kb ids/source ids/citation policy
- MNote 文件打开/刷新 bridge usage

不要注入整篇正文；路径与 allowed roots 足够让 opencode 在本地读取文件。正文只在 selection 或用户明确需要时作为有限上下文传入。

8. UI 边界：嵌入 OpenHub AI 面板，保留 AI 原能力

8.1 Page AI Shell

MNote sidebar host 的职责应尽量薄：承载 OpenHub AI 面板、注入 MNote context、处理 MNote 回跳，不重新设计一套顶部/侧边栏产品结构。

  • 顶部：第一阶段可以不要 MNote 自定义顶部；如需状态，只做极简 host 状态条或错误提示，避免覆盖 OpenHub AI 面板原有布局。
  • 主体：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 打开页面。

8.2 OpenHub 前端裁剪策略

第一阶段不是“大面积禁用 OpenHub 前端”，而是保留 AI 面板相关能力，只掐断与 MNote 真相冲突的入口：

保留：

  • AI chat 主界面。
  • history / session 抽屉。
  • skill / agent 设置。
  • WeKnora CLI/MCP tool 的连接状态；若 OpenHub 无原生 MCP 设置 UI，则通过 MNote host 或 OpenHub 最小扩展显示，不阻塞 AI 主界面。
  • tool/model permission UI。
  • tool card、diff、changed files、运行日志等 AI 运行态 UI。

裁剪或转接：

  • OpenHub Login：禁用，改由 MNote 登录态注入 OpenHub 派生用户。
  • OpenHub workspace selector：禁用或固定为 MNote 授权 rootUri 派生 workspace。
  • OpenHub FileManager：不作为文件真相；若 AI 面板内出现文件入口，转接到 MNote document pane / FileTree。
  • OpenHub KnowledgeManager：不作为知识库 UI；如入口存在，转接到 MNote 知识库展示层或隐藏。
  • OpenHub Admin / Team / Scheduler / SmartEntity：默认隐藏或不可达，除非后续明确纳入 Page AI 管理面。
  • OpenHub Git snapshot / restore：默认关闭，避免改写 MNote local-first workspace 版本语义。

8.3 MNote 暴露给 OpenHub 的边界能力

MNote 不替 OpenHub 判断何时调用知识库、何时用 skill/tool/MCP 工具、如何组织 tool call；这些交给 OpenHub/opencode 已有 skill/tool/agent 规范处理，并由 MNote 注册的 WeKnora CLI/MCP/API tool 提供知识能力。MNote 只提供最小边界能力：

- 当前页面 context：page path / title / selection / rootUri / allowed roots
- 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 打开/刷新

也就是说，MNote 是宿主、授权边界和回跳桥，不是 OpenHub agent 的 planner，也不是 OpenHub AI 面板的重写者。

9. 数据流：OpenHub 原生执行，MNote 注入边界

9.1 发送 Page AI 消息

用户输入
  -> MNote Page AI host 中的 OpenHub AI 面板
  -> OpenHub 前端调用 OpenHub FastAPI
  -> OpenHub FastAPI 使用 OpenHub session/message/skill/tool permission 与 MNote 注册的 WeKnora tool scope
  -> OpenHub FastAPI 调 opencode serve
  -> opencode 读写 MNote 授权 rootUri 内文件
  -> OpenHub session/message/tool history 持久化
  -> OpenHub AI UI 渲染回复、tool card、diff、changed files
  -> MNote bridge 只处理文件打开、刷新、citation 回跳

MNote 不在消息主链里重写 OpenHub planner，也不解析知识需求后替 OpenHub 决定调用 WeKnora。MNote 只负责登录态、workspace 授权、scope 注入和结果回跳。

9.2 知识检索

OpenHub/opencode 判断需要知识
  -> 按 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 CLI/MCP/skill/tool 时由 MNote 根据当前用户、workspace、allowed roots 预先约束。

9.3 知识库生成与展示

MNote 知识库展示层上传/添加资料
  -> MNote canonical knowledge API
  -> MNote 校验 user/workspace/rootUri/write permission
  -> WeKnora file/manual/url ingest
  -> 写 mnote_knowledge_sources registry
  -> FileTree/Knowledge UI 显示 indexing 状态
  -> 生成/更新可供 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 嵌入式集成主设计。
  • 在本轮授权写入范围内统一术语：WeKnora 是唯一知识库底座，MNote 是知识库展示和文件真相层，OpenHub KnowledgeManager 不作为知识库页；bugs/testing 文档未在本任务授权写入范围内修改。
  • 在本轮授权写入范围内搜索并标记仍把 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 的真实用途：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 进程。
  • 明确 OpenHub Git snapshot / restore / revert 默认关闭，并在启动环境或配置中落实。
  • 写 smoke：OpenHub FastAPI 可列 session，Redis 可达，opencode serve 可达。

10.3 MNote 登录态到 OpenHub Scope

  • 定义 openhub_user_key = stable_hash(mnote_user_id)。
  • 定义 openhub_workspace_key = stable_hash(workspace_id, root_uri)。
  • 定义 session scope：mnote_user_id + workspace_id + root_uri + page_resource_id。
  • 在 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、tool permission scope 或 WeKnora tool scope。
  • 写 control-plane 测试：binding 受 user/workspace/rootUri 隔离，跨用户查询失败。

10.4 OpenHub AI 面板嵌入

  • 在 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、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。
  • 写浏览器 smoke：Page AI 显示 OpenHub AI 面板，刷新后 session/history 仍可恢复。
  • 写浏览器 smoke：访问 OpenHub Login/Admin/FileManager/KnowledgeManager 非 AI 入口不会接管 MNote。

10.5 OpenHub 原生 opencode 链路

  • 保持 OpenHub FastAPI 调用 opencode serve，MNote 不重写 prompt/event/diff client。
  • 确认 OpenHub 创建 session 时 directory 固定为 MNote 授权 rootUri。
  • 确认 OpenHub 发送 prompt 后可监听 /global/event 并渲染 tool card / assistant message。
  • 确认 OpenHub 可读取 /session/{id}/diff 或等价 changed files。
  • MNote 只读取 changed file / diff artifact 的 path 和 session id，用于 open/refresh。
  • changed file 点击调用 window.__mnoteDocumentPaneRuntime.openResourceInActiveTab()。
  • 当前打开页面被修改后走 watcher 或 refreshPrimaryDocument() 刷新。
  • 写真实 smoke：让 OpenHub AI 修改 rootUri 内 Markdown，MNote 当前页面可看到变更。

10.6 WeKnora 知识库页面替换

  • 盘点 WeKnora KnowledgeBaseList.vue、KnowledgeBase.vue、KnowledgeBaseEditorModal.vue、knowledge-processing-timeline.vue 的依赖。
  • 决定复用方式：优先 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 自己的独立文件真相。
  • 入库时 MNote 先校验 allowed roots，再调用 WeKnora file/manual/url ingest。
  • WeKnora processing / reparse / failed / indexed 状态同步到 MNote registry 与 FileTree 灯号。
  • 删除 source 时只删除知识库索引和 registry 映射，不删除本地原文件。
  • 写浏览器 smoke：创建 KB、添加本地文件夹、看到 indexing 状态、完成后可检索。

10.7 WeKnora 检索替换 LightRAG

  • 抽出 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 调试/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；保留 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。
  • 写单元测试：WeKnora SearchResult 映射为 MNote search result / citation / open-reference。

10.8 WeKnora MCP/CLI Tool Bridge

  • 第一阶段 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。
  • tool result 返回 provider ids、quote、chunk metadata、MNote open-reference token。
  • citation 点击由 MNote bridge 打开，不由 OpenHub 或 WeKnora 决定本地路径。
  • 写真实 smoke：OpenHub AI 通过 MCP/CLI tool 查询 WeKnora，回答中出现可回跳 citation。

10.9 dev-hot 与真实验收

  • 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/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 可刷新并显示变更。
  • 在 WeKnora 知识库页用本地文件/文件夹集合建库，完成 ingest/index。
  • OpenHub AI 通过 WeKnora MCP/CLI/API tool 检索该 KB，并返回 citation。
  • 点击 citation 打开 MNote 对应页面或资源 tab。
  • 保存 smoke 输出和关键截图；失败时标明 OpenHub FastAPI、Redis、opencode、WeKnora、MNote bridge 中哪一层失败。

11. 取舍矩阵

冲突点 直接用 OpenHub 直接用 WeKnora MNote 边界方案 决策
登录 第二套 JWT/localStorage 第二套 tenant login/API key MNote cookie -> scope/binding 选 MNote 登录入口 + OpenHub 派生 scope
消息历史 OpenHub conversation/session WeKnora chat session 暂弃用 MNote binding + artifact index 选 OpenHub session 为真相，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 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 边界控制

12. 风险与防线

12.1 风险：三套权限漂移

防线：MNote 是浏览器入口和授权边界；OpenHub/opencode 只能拿到 MNote 派生 scope、allowed roots、tool/CLI/MCP 配置，不直接获得未过滤 workspace/rootUri。

补充：WeKnora RBAC 只能作为 provider 防线，不作为 MNote 授权来源；RBAC 关闭、API key 复用或共享空间变化时，MNote 过滤结果仍必须保持一致。

12.2 风险：WeKnora citation 无法定位到本地文件

防线：ingest 时必须写 source_uri/source_hash/provider_knowledge_id；检索返回后以 provider id 回查 registry，失败时 UI 标记“定位降级”，不能伪造路径。

12.3 风险：OpenHub UI 迁移成本变成 fork

防线：第一阶段嵌入 OpenHub AI 面板，尽量保持 OpenHub 已有 AI 功能不动；只对非 AI 入口通过隐藏、404、反代拦截或跳转 MNote 做最小裁剪。后期如需精简或替换组件，再单独做 UI 迁移设计。

12.4 风险：opencode 工作目录过大导致找不到文件

防线：工作目录固定为当前打开 rootUri；context 中传相对 path、allowed roots、当前页面 path；切换 rootUri 新开 session；不把大仓根或 recycle 目录作为默认工作目录。

12.5 风险：旧 LightRAG 残留误导

防线：UI 文案和配置改 provider-neutral；默认 provider 改 WeKnora；旧 LightRAG tools/manifest 标记 legacy 或隐藏。

12.6 风险：OpenHub 自动 Git snapshot 污染 workspace

防线：只参考 OpenHub AI 页面与 event/diff 解析思路；不迁移 Git snapshot / restore 后端路径。若以后需要版本恢复，必须走 MNote DocumentBuffer / watcher / 显式用户确认的版本策略。

12.7 风险：MCP/CLI 写权限边界不清

防线：WeKnora 有 Go CLI weknora mcp serve 与 Python mcp-server 两套 surface，读写能力不同。MNote 接入前必须指定采用哪一套、默认只读还是允许 create/delete，并把写操作纳入 MNote 权限审批。

13. 验收标准

MVP 通过必须同时满足：

  • 浏览器中 Page AI 嵌入 OpenHub AI 面板，并能显示 OpenHub 原生消息/tool/diff/history。
  • MNote 登录态是唯一登录入口；无 OpenHub/WeKnora 登录跳转。
  • 同一 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（当前无 .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/

Reference in New Issue View Git Blame Copy Permalink