[Roadmap] MarginNote 4 connected learning workflow

[evan188199-tech]

Goal (中文): 把 MarginNote 4 做成可信的 Connected KB 学习闭环：先连得上、看得见、用得上，再把掌握度和摘要写回 MN4。

This is the tracking issue for the MarginNote 4 connected-learning workflow. The detailed plan lives in docs/roadmap/marginnote-4.md. Do not treat Realm live-read or marginnote4:// as shipped.

Do you need to file a feature request?

• I have searched the existing feature requests and this feature request is not already filed.
• I believe this is a legitimate feature request, not just a question or bug.

Feature Request Description

DeepTutor already has a v1 MN4 Connected KB: export-folder registration, 6 read tools, 3 write tools, a KnowledgeCapability, and a Create KB entry. The next user-facing work is a reliable connection loop, then Deep Research, writeback import, and large-notebook performance.

v1 is implemented and waiting merge verification. Realm is a stub only.

Related Module

Knowledge Base Management

Use Case

A learner should be able to export a notebook from MarginNote 4, verify that DeepTutor can read it, browse the notebook in a dedicated KB page, ask source-backed questions in Chat and Deep Research, and later import mastery/wrong-question summaries back into MN4.

Additional Context

Primary UX metrics

• Connection success rate
• Parse-warning rate
• Time to first useful sourced answer
• Writeback re-import success rate

Phases

• M0 implemented: Markdown/OPML Connected KB, 9 tools, mastery writeback fields
• M1 P0: real export compatibility, connection diagnostics, MN4 detail page, Deep Research
• M2 P1: writeback import loop, mind-map cross-links, end-to-end coverage
• M3 P2: incremental cache/index, Realm research

Child issues

• [MN4][P0] Validate real MarginNote 4 export formats and harden the parser #1 [MN4][P0] Validate real MarginNote 4 export formats and harden the parser
• [MN4][P0] Add connection diagnostics and export preview #2 [MN4][P0] Add connection diagnostics and export preview
• [MN4][P0] Build a dedicated connected-notebook detail experience #3 [MN4][P0] Build a dedicated connected-notebook detail experience
• [MN4][P0] Enable MarginNote evidence retrieval in Deep Research #4 [MN4][P0] Enable MarginNote evidence retrieval in Deep Research
• [MN4][P1] Complete the writeback and re-import workflow #5 [MN4][P1] Complete the writeback and re-import workflow
• [MN4][P1] Cross-link mind-map nodes, highlights, notes, and source documents #6 [MN4][P1] Cross-link mind-map nodes, highlights, notes, and source documents
• [MN4][P1] Add end-to-end coverage and integration hardening #7 [MN4][P1] Add end-to-end coverage and integration hardening
• [MN4][P2] Add per-file incremental parsing and search indexing #8 [MN4][P2] Add per-file incremental parsing and search indexing
• [MN4][P2] Research and implement a Realm live-data adapter #9 [MN4][P2] Research and implement a Realm live-data adapter

Dependencies

#1 parser
 ├─ #2 probe/preview
 │   └─ #3 dedicated detail page
 ├─ #4 Deep Research
 ├─ #5 writeback import  (also needs #3)
 ├─ #6 mind-map cross-links
 ├─ #7 e2e / CI  (tracks #1-#6 as they land)
 ├─ #8 incremental index
 └─ #9 Realm research (BLOCKED; UI hidden)

P0 done when
A user can validate a real MN4 export in the UI, see read stats, browse the notebook after connect, and get sourced answers in Chat and Deep Research.

P1 done when
Summaries can be downloaded and re-imported into MN4 without losing mastery/wrong-question context, and mind-map links are traceable.

Out of scope until validated

• Realm live database access
• marginnote4:// deep links
• Changing upstream HKUDS/DeepTutor#498

Local roadmap
docs/roadmap/marginnote-4.md