MemoFlow · Repository 模块开发笔记

按版本记录数据库资源、Local Vault、GitHub 同步与知识投影的方案。

#blog #growing #dev

Repository 模块目标

我想在 MemoFlow 里做一个个人知识资源库，主要管理 Markdown、图片和附件，也希望以后能扩展音视频。界面想借鉴 Obsidian：左边是文件与目录，右边打开文档、编辑或预览。

Repository 负责“有哪些资源、它们放在哪里、如何关联”；Editor 则负责具体的 Markdown 编辑交互。

第一版先按照数据库资源管理器的思路设计。Repository 有 Folder / Resource，保存资源名称、类型、路径、元数据和关联信息，配合文件树、搜索与不同资源类型的预览。

这样做的好处是业务查询比较直接：可以按资源类型或文件夹筛选，也方便把图片、Markdown 和其他附件放到统一的列表中。缺点是要不断回答“数据库记录和实际文件怎样对应”，尤其是移动、重命名或删除资源的时候。

先实现创建与选择资源、打开 Markdown、预览图片等基础流程，并与 Editor 的保存接口配合，形成从资源列表到文档编辑的操作路径。

现在开始考虑资源的引用关系。在 Markdown 中插入一张图片，既可以放 Base64，也可以引用 Repository 中的独立文件；文档里写了 WikiLink，目标文件被移动后又该怎样处理？

Base64 方便单文件携带，却会放大正文；独立文件更适合复用，但路径管理不能依赖用户手工维护。准备提供资源选择、链接建议、反向链接和无效引用诊断，减少用户自己处理 Markdown 路径的次数。

此时 Repository 同时管理数据库资源和文档正文，虽然容易接入业务表单，但本地文件、编辑器和数据库之间的一致性需要特别注意。

现在决定以 Local Obsidian Vault 作为本地知识的内容来源，不再让数据库中的 Resource 成为另一份可以任意编辑的 Markdown 正文。

原因很实际：用户可能直接在 Obsidian 里修改文件，也可能从 Git 拉取变化。如果 MemoFlow 再独立保存一份正文，就必须做大量双向同步与冲突合并，才能保证不会覆盖用户已有笔记。

因此 Desktop 先支持选择一个真实目录，扫描 Markdown 与附件、提供搜索和安全预览；编辑已有笔记时交给 Obsidian。即使没有登录或连接远端仓库，本地 Vault 也应该能够继续使用。

需要跨设备访问时，再允许用户主动连接 GitHub 私有仓库。MemoFlow 登录与 GitHub 仓库授权应分开：登录产品不代表允许读取用户所有代码仓库。

同步方案以 Git 文件为准。Desktop 可以提交本地变化，并与远端 fetch、rebase、push；如果发生冲突，就暂停自动推进并保留本地内容，不能为了“同步成功”强制覆盖远端历史。

Web 不直接修改数据库正文。它读取服务端根据 GitHub 内容生成的知识投影，可以浏览、搜索和预览；创建新 Markdown 时先确认文件名、路径和内容，再由 GitHub App 提交一个真实 Git Commit。

现在要整理 Vault、GitHub 仓库和知识投影的长期身份。文件路径不是稳定标识：重命名一篇笔记，不应该让 Goal/Task 里引用它的关系都失效。

因此引入 KnowledgeSpace 与稳定 KnowledgeDocumentId，让“这篇文档是谁”与“它目前存在哪个路径”分开。

同时把绑定和实时观察状态拆开：

这样即使某次网络检查失败，也不应该自动断开用户的长期绑定，更不能删除 Vault 中的文件。

继续把知识库和 AI 的写入边界打通。AI 可以先查询已有笔记，建议标题、路径和 Markdown 草稿；真正写入必须由用户确认，并通过 Repository 的受控入口落盘或提交 Git。

知识索引、链接图和搜索结果只是根据内容生成的可重建投影。文件还是内容真值，AI 的检索索引也不应该再变成一份独立的可编辑正文。

这一版重点是让 KnowledgeSpace 在 Desktop、Web 和业务引用中保持一致，而不是继续扩展一个自包含的编辑器。