lix/mnote
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
a40fa25ae6889df560e3f72f9a90a312b5d9ed14
mnote/design/07-ai/process/7-75-knowledge-rag-ui-panel-optimization-v1.md
T

16 KiB
Raw Blame History

7-75 [process] Knowledge RAG UI 面板优化 v1

创建时间：2026-07-13

状态：PROCESS

Owner：07-ai

范围：3000 主壳中的知识库 / RAG / OCR 状态面板、FileTree 知识库状态灯、当前页面附件索引入口、Page AI 对知识库状态的可见性。

上位依据：

  • /mnt/Data1T/mnote/ARCHITECTURE.md（CURRENT_ARCHITECTURE.md 为兼容指针）
  • /mnt/Data1T/mnote/design/07-ai/done/7-50-lightrag-knowledge-rag-provider-v1.md
  • /mnt/Data1T/mnote/design/07-ai/done/7-51-lightrag-post-commit-hardening-v1.md
  • /mnt/Data1T/mnote/design/07-ai/done/7-52-lightrag-image-ocr-search-chain-hardening-v1.md
  • /mnt/Data1T/mnote/design/10-review/done/20-post-lightrag-runtime-hardening-checklist-v1.md

1. 第一结论

当前更高优先级不是先恢复旧本地 OCR sidecar，而是把 Knowledge RAG UI 面板 做成用户能理解和操作的资料库控制面。

原因：

  • 旧 /api/local-folder/ocr/* 已退役，当前图片 / PDF / Office OCR 与资料库问答主线统一走 Knowledge RAG provider。
  • LightRAG 本地服务已具备图片 VLM / MinerU 路由能力，但用户在 MNote 里看不到“这张图是否已索引 / 是否已有 OCR 文本 / 是否失败 / 是否过期”。
  • FileTree 目前只有 indexed / indexing / failed 三态，缺少 not_indexed / stale / ocr_text_exposed / provider_unavailable 等用户可行动状态。
  • Page AI 能直接看本地图片，但长期知识库和非多模态模型仍需要 OCR / sidecar / index；UI 必须先让用户知道当前资源处于哪种状态。

因此，本设计把“图片插入后 OCR 能力增强”拆成 Knowledge RAG 面板的一部分，而不是重开旧 OCR 入口。

2. 当前证据

2.1 已存在能力

  • Knowledge RAG source 支持 md / pdf / docx / pptx / xlsx / csv / png / jpg / jpeg / webp / gif / bmp / tif / tiff 等文件。
  • /api/knowledge-rag/ingest 已能接收 rootUri + sources[]，注册 source，创建 LightRAG input symlink，并触发 provider scan。
  • FileTree 行模型已带 indexStatus，前端可渲染 indexed / indexing / failed。
  • 旧 OCR sidecar frontmatter 读取 helper 仍在，可作为历史兼容读取，不作为新任务入口。
  • LightRAG health 能返回 provider 配置、pipeline 状态、VLM 是否启用、MinerU / parser routing 等诊断信息。

2.2 已确认缺口

  • 新插入图片只写为 Markdown 图片引用和本地文件，不会自动登记为 Knowledge RAG source。
  • 未索引图片没有明确 UI 状态，用户只能看到文件存在，无法知道是否可被文本模型/RAG 检索。
  • Knowledge RAG registry 中存在大量 stale / provider_missing / failed 历史记录，但 UI 缺少 doctor 视图解释和引导。
  • 当前“索引到默认知识库”入口藏在 FileTree 右键菜单，缺少当前页面级的“索引本页附件”入口。
  • 失败原因没有被产品化展示，例如 provider API key 不一致、provider missing、chunk 超时、parser 失败。
  • OCR 结果没有在图片资源 tab 或页面侧栏中形成可读 preview；用户不知道 OCR 文本是否真正暴露给 AI。
  • Page AI target package 不应恢复旧 ocrContext，但需要一个轻量 resourceOcrStatus 告诉 agent 当前资源是否已有可查 OCR / 是否应调用 Knowledge RAG / 是否需要多模态兜底。

3. 目标体验

Knowledge RAG 面板应回答用户四个问题：

  1. 资料库是否可用：provider 是否在线、当前默认 provider 是谁、队列是否忙。
  2. 哪些资源已进入知识库：当前 workspace / 当前页面 / 当前文件夹下的 source 状态。
  3. 图片/PDF/Office 是否已 OCR/解析：是否已索引、是否有真实 OCR 文本、是否只是图片占位符。
  4. 下一步能做什么：索引、重试、强制重建、打开引用、查看 OCR 摘要、查看失败原因。

目标 UI 不是 debug 面板，而是资料库操作面板。Raw provider payload 只放到折叠诊断区。

4. 非目标

  • 不恢复 /api/local-folder/ocr/* 作为主动 OCR API。
  • 不把旧 .ocr sidecar 重新变成页面正文真相。
  • 不让 MNote 复制 LightRAG 的 chunk / vector / graph 真相。
  • 不在普通页面打开、FileTree 渲染、Markdown 编辑保存中硬依赖 LightRAG 可用性。
  • 不自动清理 registry / 删除 provider 索引；任何清理、删除、强制重建都必须用户确认。

5. 信息架构

5.1 面板入口

保留当前知识库入口，但改成四区布局：

知识库
  Provider 状态
  当前页面资源
  Workspace Sources
  诊断与修复

入口位置：

  • Sidebar 顶部资料库 / 搜索附近保留主入口。
  • FileTree 右键保留“索引到知识库”，但成功后跳转或高亮 Knowledge RAG 面板对应 source。
  • 文档页资源 tab 对图片/PDF/Office 显示“资料库状态”轻量按钮。

5.2 Provider 状态区

显示：

  • provider 名称：LightRAG / RAGFlow / legacy fallback。
  • health：在线、不可达、API key 错误、pipeline busy。
  • dashboard 链接。
  • VLM/OCR 能力：图片解析是否启用、MinerU/Docling/native 路由摘要。
  • 队列状态：queued/running/failed/retry required。

对用户文案：

  • 在线：知识库服务可用
  • 不可达：知识库服务不可用，页面仍可编辑；AI 将只能读取本地文件或多模态图片
  • API key 错误：MNote 与 provider 的 API key 不一致，请检查配置
  • 队列忙：正在解析资料，稍后会自动刷新状态

5.3 当前页面资源区

针对当前 Markdown 页面解析图片、PDF、Office、mindmap、附件引用，展示：

列 含义
资源 文件名、类型、路径
状态 未索引 / 排队中 / 索引中 / 已索引 / 失败 / 已过期
OCR 不适用 / 待解析 / 已有文本 / 只有占位 / 失败
操作 索引、重试、强制重建、打开资源、查看 OCR

当前页面区必须提供批量动作：

  • 索引本页附件
  • 重试失败项
  • 重建已过期项

5.4 Workspace Sources 区

展示 registry 中当前 actor 可见的 sources：

列 含义
Source root-relative path
类型 markdown / image / pdf / office
Provider LightRAG / RAGFlow
状态 registry + provider status 合并结果
更新时间 registry updatedAt / provider updatedAt
引用 open_reference 可否定位

默认过滤：

  • 隐藏已删除完成项。
  • stale / failed 单独汇总到顶部。
  • 测试 fixture 或历史 provider_missing 只在诊断区展开显示。

5.5 OCR / 解析预览区

点击图片 source 后，右侧或下方展示：

  • 原图预览。
  • OCR / parsed text preview。
  • ocrTextExposed：是否返回了真实文本，而不是 Markdown 图片占位符。
  • sidecar / blocks 路径只在诊断展开时显示。
  • 复制 OCR 文本、用 OCR 问 AI、打开引用位置。

如果没有 OCR 文本：

这张图片尚未解析成文本。多模态模型可以临时读图，但文本模型和知识库检索需要先索引。

如果只有图片占位：

provider 只返回了图片占位符，未暴露 OCR 正文。建议重试解析或改用 MinerU/VLM parser。

6. 状态模型

6.1 Source index status

后端和前端统一使用以下状态：

  • not_indexed：本地资源存在，但 registry 无有效 entry。
  • queued：已提交，但 provider 尚未开始。
  • indexing：provider processing / parsing / submitted。
  • indexed：provider doc id 存在且 indexedAt 有效。
  • failed：provider failed / provider_missing / delete_retry_required。
  • stale：source hash/mtime 变化，已有索引过期。
  • deleting：delete submitted。
  • deleted：delete completed。

FileTree 可以继续只显示少量灯号，但 tooltip / 面板必须展示完整状态。

6.2 OCR status

图片、扫描 PDF、Office 附件需要额外 OCR/解析状态：

  • not_applicable：纯文本 Markdown 等无需 OCR。
  • not_started：未提交解析。
  • processing：解析中。
  • text_exposed：引用/sidecar 中已有真实文本。
  • placeholder_only：只返回图片占位符，没有 OCR 正文。
  • failed：解析失败。
  • stale：源文件变化后 OCR 过期。

text_exposed 的判断不得只看 provider “成功”，必须看 contentDiagnostics.ocrTextExposed 或 sidecar meaningful block 数。

7. 后端合同调整

7.1 Status API

扩展 /api/knowledge-rag/status?rootUri=... 返回：

{
  "sourceSummary": {
    "total": 0,
    "notIndexed": 0,
    "indexing": 0,
    "indexed": 0,
    "failed": 0,
    "stale": 0,
    "ocrTextExposed": 0,
    "placeholderOnly": 0
  },
  "sources": [
    {
      "sourceRootRelativePath": "docs/photo.jpg",
      "resourceType": "image",
      "indexStatus": "indexed",
      "ocrStatus": "text_exposed",
      "ocrTextPreview": "前 300 字...",
      "failureMessage": null,
      "actions": ["open", "reindex", "view_ocr"]
    }
  ]
}

7.2 Current page assets API

新增或复用 Page Aggregate 输出当前页资源引用，面板拿到：

{
  "pageId": "local-md:...",
  "sourceRootRelativePath": "docs/Page.md",
  "assets": [
    {
      "href": "photo.jpg",
      "sourceRootRelativePath": "docs/photo.jpg",
      "resourceType": "image",
      "exists": true,
      "indexStatus": "not_indexed"
    }
  ]
}

这一步不要让前端重复解析 Markdown 真相；优先从 Page Aggregate / kernel projection 输出。

7.3 Ingest response

/api/knowledge-rag/ingest 当前返回 configured / scan 等信息，面板需要稳定字段：

  • submittedSources[]
  • skippedSources[]
  • retryRequired
  • providerErrorCode
  • userMessage
  • nextPollAfterMs

7.4 Registry doctor

增加只读 doctor endpoint 或 status 子对象：

{
  "doctor": {
    "staleEntries": 58,
    "providerMissingEntries": 58,
    "failedEntries": 1,
    "apiKeyMismatchSuspected": true,
    "suggestedActions": ["check_provider_config", "retry_failed", "archive_stale_test_entries"]
  }
}

清理动作必须单独确认，不在 status 读取时自动执行。

8. 前端交互

8.1 FileTree 灯号

灯号含义：

  • 无灯：不支持索引或用户未开启显示。
  • 空心灰点：支持索引但未索引。
  • 黄点：排队/索引中。
  • 绿点：已索引且 OCR 文本暴露。
  • 蓝点：已索引但该资源不需要 OCR。
  • 红点：失败。
  • 橙点：过期。

FileTree 行已有 data-index-status，需要扩展为 data-index-status + data-ocr-status，tooltip 显示完整原因。

8.2 图片插入后

图片插入完成后：

  1. 保存图片文件。
  2. Markdown 写入图片引用。
  3. UI 立刻把该资源标记为 not_indexed。
  4. 如果用户开启“自动索引新图片”，后台提交 /api/knowledge-rag/ingest。
  5. 默认不开启自动索引时，显示轻量提示：图片已插入，可索引后用于文本检索和非多模态 AI。

自动索引应是 workspace/user preference，不是硬编码默认。

8.3 Page AI 协同

Page AI 不恢复旧 ocrContext，改用轻量状态：

{
  "resourceOcrStatus": {
    "currentPageAssets": [
      {
        "sourceRootRelativePath": "docs/photo.jpg",
        "resourceType": "image",
        "indexStatus": "not_indexed",
        "ocrStatus": "not_started",
        "recommendedReadMode": "multimodal_fallback"
      }
    ]
  }
}

AI 行为：

  • 多模态模型：可以临时读图，但应提示“未索引，无法长期检索”。
  • 文本模型：如果未 OCR，应建议用户索引图片；不要假装已读图。
  • 已 OCR：优先调用 mnote.knowledge_rag.query / section_context，必要时再多模态核验。

9. 实施步骤

Phase 1：只读状态面板

  • 统一 Knowledge RAG provider 文案，避免 LightRAG / RAGFlow legacy fallback 在用户界面混乱。
  • 扩展 /api/knowledge-rag/status 的 source summary 与 registry doctor。
  • 新建 Knowledge RAG 面板基础 UI，显示 provider health、source summary、失败/stale 汇总。
  • FileTree tooltip 展示当前 indexStatus，不改变索引行为。

Phase 2：当前页面资源闭环

  • 从 Page Aggregate / projection 输出当前页附件清单。
  • 面板展示“当前页面资源”列表。
  • 支持“索引本页附件”“重试失败项”。
  • 图片插入后刷新当前页面资源区并标记 not_indexed。

Phase 3：OCR 预览与诊断

  • 后端为 image/PDF/Office source 暴露 ocrStatus 与 ocrTextPreview。
  • 图片资源 tab 增加 OCR/资料库状态按钮。
  • 面板支持 OCR preview、placeholder-only 诊断、失败原因展示。
  • Page AI target package 增加轻量 resourceOcrStatus。

Phase 4：Doctor 与配置修复

  • 增加 registry doctor UI。
  • 检测 MNote 读取的 LightRAG API key 与 provider 实际认证失败时的差异，给出明确配置建议。
  • 对 stale/provider_missing 历史记录提供“归档测试记录”建议，但执行前必须确认。
  • 增加失败重试与强制重建的确认流程。

10. 验收标准

  • 插入一张图片后，当前页面资源区能立即显示该图片为 未索引。
  • 对该图片点击“索引”后，UI 进入 索引中，并能在 provider 完成后转成 已索引 或 失败。
  • 图片如果 provider 只返回 Markdown 图片占位，UI 必须显示 未暴露 OCR 正文，不能显示成 OCR 成功。
  • 图片 OCR 成功后，用户能在面板看到 OCR 预览，并能让 Page AI 基于 Knowledge RAG 查询引用。
  • provider 不可达或 API key 错误时，页面编辑不受影响，面板显示明确诊断。
  • 旧 .ocr sidecar 不作为普通页面进入 PageTree；历史 sidecar 只作为兼容资源打开。
  • 非多模态模型面对未 OCR 图片时，不声称已读取图片内容。

11. 测试计划

Rust

  • cargo test -p mnote-web knowledge_rag -- --test-threads=1
  • 增加 knowledge_rag_status_reports_not_indexed_page_assets
  • 增加 knowledge_rag_status_reports_ocr_text_exposed_only_for_meaningful_sidecar
  • 增加 knowledge_rag_registry_doctor_reports_provider_missing_without_cleanup
  • 增加 page_ai_target_package_includes_resource_ocr_status_without_ocr_context

Browser smoke

  • 新增 scripts/task8xx-knowledge-rag-panel-status-smoke.js
    • 登录 mnote-e2e
    • 打开含图片页面
    • 验证面板显示 provider health、当前页面图片、未索引状态
  • 新增 scripts/task8xx-knowledge-rag-image-index-flow-smoke.js
    • 用测试图片触发索引
    • 验证 FileTree 状态灯从未索引到索引中
    • provider 可用时验证 OCR preview；provider 不可用时验证失败诊断
  • 更新 Page AI smoke：
    • 文本模型未 OCR 图片：提示需要索引
    • 多模态模型可临时读图，但回答标记未长期索引

12. 风险

  • LightRAG provider 解析大文件可能慢或超时；UI 必须将失败原因产品化，不能只显示“索引失败”。
  • 自动索引新图片可能消耗 VLM / MinerU 成本；默认建议关闭，由 workspace preference 控制。
  • registry 历史测试数据较多，doctor 只能提示，不应自动删除。
  • provider 名称当前存在历史口径漂移；面板第一阶段必须先统一用户可见命名。

13. Definition of Done

  • 用户在 MNote 内不用打开终端，就能判断当前图片/PDF/Office 是否已进入知识库、是否有 OCR 文本、是否失败、是否过期。
  • 用户可以从当前页面一键索引本页附件，并看到可追踪状态。
  • Page AI 能基于状态选择：直接读本地文件、多模态临时读图、或调用 Knowledge RAG。
  • 旧 OCR sidecar 仍可兼容打开，但不会重新成为主路径。
Reference in New Issue View Git Blame Copy Permalink