项目复盘 / 进行中

文枢 Wenshu · 本地 Markdown 知识库

本地 Markdown 知识库:点开即编辑、搜得懂人话、AI 回答每句话能点回原文,数据全部留在本机。

2026.10 – 2026.11 独立开发 更新于 2026.11.17 Python / pywebview / BM25 / bge-m3 / Ollama 仓库
本文目录

这是我给自己做的一个"第二大脑":笔记还是文件夹里实实在在的 .md,但搜得懂人话,AI 回答里的每句话都能点回原文。数据全部留在本机,索引删了就能重建。

它是什么

文枢是一个 Windows 桌面应用,把一堆 Markdown 笔记变成可检索、可问答的知识库。四条不妥协的原则贯穿始终:

原则做法
数据不被格式绑架文档永远是资料库里的 .md,任何编辑器可打开;索引只是可重建的派生数据
AI 零强依赖统一 OpenAI 兼容协议,本机 Ollama、DeepSeek、GLM、Kimi 都能接;一个都不配也能用关键词搜索
回答必须可验证先检索自己的资料再作答,每个论断带 [n] 引用,点击直达原文并高亮;没依据就明说"资料中没有"
桌面应用零端口界面与处理层走 pywebview 原生桥直调,运行时不监听端口,没有"本地服务被别的程序访问"的攻击面

文枢分层架构:桌面层、处理层、检索引擎、AI 层与数据层

整体是五层:桌面层负责交互,处理层管库、导入、历史和问答,检索引擎做分块、双路召回与融合,AI 层统一协议接各种模型,数据层全是纯文本。前端 api() 按协议自动分流——桌面态走原生桥,浏览器调试态走 HTTP,两者调同一批处理函数。

搜得懂人话

Markdown 笔记一多,找东西就变难:想找"怎么让电脑自己学会玩游戏",答案明明写在《强化学习》那篇里,可文件名和字面都对不上。文枢用 BM25 关键词加语义向量双路召回,口语化提问也能命中术语完全不同的段落;融合权重还会随语料规模自动调整。

双路召回与 RRF 融合:权重随语料规模自适应

分块沿文档自然边界走:按标题层级切,代码围栏里的 # 不误判;每块拼上"[来源 > 章节路径]"前缀,给 BM25 提供精确词、给向量提供语义锚点。每块记录自己的真实起止行号——这是引用和前端高亮能定位准的前提。

内部基准 1,188 块 / 111 查询上,BM25 89.19%、语义 95.50%、RRF 融合 98.20% recall@5。外部基准是 10,027 篇中文维基 / 10.5 万块、从未参与调参:dense 94.12%,而等权 hybrid 只有 88.24%——正是它暴露了"融合配比是语料规模的函数"。

AI 问答可溯源

右上"AI 问答"基于检索到的原文作答,回答里的 [n] 可点击直达原文块并高亮;没用到的资料不会被假装引用。

AI 问答链路:检索、组装上下文、生成、引用回跳

本机 Ollama 走原生接口并关掉思考,避免思考型模型把推理算进输出预算、正文写不出来;云端模型则走流式逐块渲染。可选增强 query 改写 / 重排在思考型模型上不稳定,默认关闭、失败自动降级,不影响主链路。

能做什么

  • 点开即编辑:点任意段落原地变编辑框,Ctrl+S 保存并立即渲染;任务清单可勾选并回写源码,表格在网格里直接编辑。编辑器之外任何文本工具改了文件,应用会自动重建索引。
  • PDF / 截图转 Markdown:拖入即用视觉模型转写,标题层级、表格、公式保留;原件归档到 attachments/,文档里留链接可回看,单页失败不阻塞整篇。
  • 表达不止纯文字:Mermaid 流程图、KaTeX 公式、代码高亮、任务清单、图片灯箱都在渲染管线里。
  • 版本与回收站:每次保存自动留快照(每文件 50 版),可预览、一键恢复;删除先进回收站。

数据在你手里

数据布局:程序只读,资料库是全部用户数据,索引可重建

资料库位置随时可在"设置 → 资料库"切换,原库不动、可换回;文档相对路径按路径组件校验越界,同前缀的兄弟目录不会被误放行。向量是 L2 归一化后的 float32 矩阵,查询期只读映射(mmap);换嵌入源时指纹不匹配才整份重建,中断可续跑。

质量如何

关键路径都有实测,不是"能跑就行":

项结果
检索(内部基准 1188 块 / 111 查询)RRF 双路 recall@5 98.20%,MRR 0.887
检索(外部基准 10.5 万块中文维基,未参与调参)dense 94.12%
生成质量(159 题,含域外不可答与对抗题)总体通过率 98.7%,零空回答
功能回归44/44 PASS,纯函数自检 11/11 PASS
向量库 mmap(10.5 万块)打开 0.83 ms,热查询 9.2 ms/次,常驻内存几乎不涨

生成评测还给出一个反直觉的结论:模型大小不是瓶颈,端点是。4b 与 9.7B 质量基本持平,0.6b 则不可用(大量零引用和域外编造)。

当前状态与已知边界

诚实起见,几件还没做的事:

  • 可选增强 query 改写 / 重排在思考型模型上不稳定,默认关闭、失败自动降级
  • 向量库块集合变化时仍重写整份矩阵,"原地改行"留作二期;当前真实库很小,无感
  • OCR 转写只验证了机制和样例正确,没有精度百分比
  • 安装器静默安装测过,向导交互模式未在全新虚拟机逐步走查

开始使用

  • 绿色版 dist/文枢.exe:解压即用,内含离线语义模型
  • 安装包 dist/文枢安装包.exe:开始菜单 / 桌面快捷方式 / 卸载器,离线模型为可选组件

从源码跑:pip install -r requirements-dev.txt && python app.py。

仓库: https://github.com/bugisGod/wenshu

如果你也在意"笔记是自己的、答案能验证",欢迎去看看,或直接提 issue。