title: 设计手记：为什么我们坚持"存储与转换分离" category: 技术 date: 2026-09-16 tags: [KMap, 设计, 文件, 转换]

设计手记：为什么我们坚持"存储与转换分离"

KMap 的知识库以 Markdown 为核心载体（检索、AI、图谱都建立在正文之上），但用户实际接触的文档却常常是 docx、pdf、xlsx。怎么处理这些"非原生"文件？我们最终选择了存储与转换分离，本文记录这个设计取舍。

问题：该不该"上传即转 Markdown"？

最省事的设计是：用户上传 docx/pdf，系统立刻转成 Markdown 入库，知识库里统一格式，一切顺畅。

但它有几个硬伤：

1. 破坏源文件。docx 里的批注、修订、嵌入对象、版式，转成 md 必然丢失。用户要的可能是"存一份原始合同"，而不是"一份转坏的 md"。
2. 转换不可逆。md 转不回原样 docx。用户想导出原始文件时，发现原文件已经被"处理"掉了。
3. 全局开关粗暴。有人想"都转"，有人想"都别转"，一个全局配置必然得罪一半人。
4. 转换有成本。大批量上传时，每份都转既慢又可能失败，失败还阻塞入库。

方案：源文件原样存放，正文按需生成

我们最终落地的是分离式设计：

• 挂载存储只存原文件。本地目录、WebDAV（网盘）挂载后，上传/拖拽的文件原样保留——docx 还是 docx，pdf 还是 pdf，一个字节都不动。文件库提供浏览、重命名、播放（音视频）、多标签阅读，完全以"文件管理器"的方式工作。
• 需要"正文"时再转换。两条路径按需触发：
  • 加入知识库（入档）：把文件导入知识库目录时，自动转出 Markdown 正文用于检索与 AI；
  • 右键"转换正文"：已入库文档也可随时按需重新转换。
• 原文件始终保留，转换只是"生成一份可用于检索的正文"，不移动、不删除、不覆盖源文件。

为什么这样更好

| 场景 | 上传即转 | 存储与转换分离 | |---|---|---| | 只想要原始文件 | ❌ 被转坏 | ✅ 原样保留 | | 需要检索/AI | ✅ | ✅ 入档时生成正文 | | 导出原始 docx | ❌ 已丢失 | ✅ 始终在 | | 批量上传大文件 | 慢、易失败 | ✅ 只存原文件，瞬时完成 | | 用户控制力 | 全局开关 | ✅ 按需/按操作触发 |

一点延伸

这个取舍也影响了后续功能：文件库（挂载存储）与知识库（Markdown 正文）从此是两个明确分层——前者管"文件资产"，后者管"知识资产"。音视频播放、WebDAV 流式读取、导入导出都建立在同一套存储抽象上，互不干扰。

好设计往往是"允许用户保持原样"的设计。 KMap 的哲学是：系统负责提供能力，选择权始终在用户手里。

本文是 KMap 设计手记系列第一篇，后续会继续分享语义检索、插件底座、协作区等模块的设计取舍。