# 文献管理

本地优先的文献管理桌面应用：文献库、Markdown 笔记、收藏。数据全部存在自己的硬盘上，不联网、不注册、不上传。

笔记是纯 Markdown，文献保留原始文件，任何编辑器都能打开。数据目录放进云盘就自动备份，换工具也不用迁移。

## 快速开始

```bash
npm install
npm run dev
```

启动后把 PDF 拖进左侧文献区就能读；新建一篇笔记写读后感；`Ctrl+Shift+F` 全文搜索笔记正文，也能按文件名找文献。

系统要求：Windows 10+ / macOS 11+ / Ubuntu 20.04+。从源码运行需要 Node.js 20.16 – 24（仓库 `.nvmrc` 锁 22.11.0）。

`npm install` 会为 Electron 重编 better-sqlite3，需要联网下载预编译产物或本地有 MSVC 工具链。启动失败先跑 `npm run rebuild:native`；vite 缓存异常先跑 `npm run dev:clean`。

## 功能

- 文献：拖入任意文件即复制入库，内嵌阅读器直接看 PDF、图片、代码、Markdown、纯文本。文件夹可任意嵌套、拖拽移动，外部改动自动感知。
- 笔记：CodeMirror 编辑，带语法高亮、撤销重做、源码与预览切换。停止输入 1.5 秒自动保存，带冲突检测。自定义 frontmatter 字段原样保留。
- 双列工作台：左边读文献、右边写笔记，互不顶掉。分隔条可拖拽，宽度自动记住。左侧栏可折叠（`Ctrl+B`）。
- 搜索：SQLite FTS5 覆盖笔记正文全文，文献按文件名命中，命中处给高亮片段。内置中文分词，中英混排不用打空格也能命中。
- 收藏：文献一键收藏，列表可切「仅收藏」筛选。收藏就是一个 Markdown 文件，可以手写。
- 界面：明/暗/跟随系统三档，另有 15 套配色预设（每套自带明暗），3 族字体，中英文界面切换。

## 快捷键

| 快捷键                     | 作用                      |
| -------------------------- | ------------------------- |
| `Ctrl+1` / `Ctrl+2`        | 切换文献 / 笔记列表       |
| `Ctrl+B`                   | 折叠 / 展开左侧栏         |
| `Ctrl+Shift+S`             | 显示 / 隐藏状态栏         |
| `Ctrl+N`                   | 新建笔记                  |
| `Ctrl+S`                   | 保存当前笔记              |
| `Ctrl+Shift+F`             | 全文搜索                  |
| `Ctrl+Shift+N`             | 新建文件夹                |
| `Ctrl+,`                   | 设置                      |
| `F2`                       | 重命名（笔记、文件夹）    |
| `Ctrl+C` / `X` / `V` / `A` | 复制 / 剪切 / 粘贴 / 全选 |
| `Del`                      | 删除（移入系统回收站）    |
| `Esc`                      | 关闭弹窗 / 取消拖拽       |

列表相关快捷键（`Ctrl+Shift+N`、`F2`、`Del`、复制剪切粘贴）需要先点一下列表；文献文件的重命名用右键菜单。macOS 用 `⌘` 替代 `Ctrl`。

## 数据

默认数据目录：`<文档>/ResearchHub/data`。在设置页可以改位置，迁移是复制方式，目标目录须为空，旧目录保留。

```
<数据目录>/
├── settings.json                     应用设置
├── notes/                            笔记（.md + frontmatter，可嵌套子目录）
├── literature/                       文献副本（原始格式）
└── workspace/favorites/favorites.md  收藏
```

备份就是复制这个文件夹。全文搜索的 SQLite 索引单独放在系统用户目录，删掉重启会自动重建，备份不用带。

## 常见问题

**PDF 正文能搜到吗？** 不能。当前不做 PDF 文本抽取，文献只按文件名命中，与 PDF 有无文本层无关。

**有什么大小限制？** 入库单文件 500MB，内嵌阅读器 10MB，笔记正文 5MB。超过阅读器上限用阅读器里的「在系统应用打开」。接近上限的大段代码 / Markdown 会按渲染预算降级渲染（顶部有提示条），内容不丢，只是高亮和折叠从简。

**能同时开多篇文献吗？** 文献是单选阅读，双列的另一边是笔记。需要对照多篇就用系统应用另开。

**删掉的东西能找回吗？** 能。删除会移进系统回收站，还原后自动重新入库，收藏标记需要重新打。

**换电脑怎么搬？** 复制整个数据目录，在新机器上装好后到设置页指过去即可，索引会自动重建。

## 开发

技术栈：Electron 30 · React 18 · TypeScript 5 · Vite 5 · Tailwind 3 · Zustand 4 · CodeMirror 6 · better-sqlite3。

| 命令                    | 作用                        |
| ----------------------- | --------------------------- |
| `npm run dev`           | 开发模式，热重载            |
| `npm run test:run`      | 跑测试                      |
| `npm run test:coverage` | 覆盖率报告                  |
| `npm run typecheck`     | 类型检查                    |
| `npm run lint`          | ESLint                      |
| `npm run build`         | 编译，产出 `out/`，不含打包 |

打包安装包：`npm run build` 后跑 `npx electron-builder --win`（`--mac` / `--linux` 同理），产物在 `release/`。

代码分三层：主进程独占文件系统和原生模块，preload 只做桥，渲染进程只碰 DOM 和 `window.api`。所有 IPC 统一返回 `{ ok, data }` 或 `{ ok, code, message }`。写入统一走「临时文件 + fsync + rename」，断电不留半截文件。接受绝对路径的操作一律校验目标在数据目录内。

## 许可

MIT，见 [LICENSE](LICENSE)。