94 lines
5.4 KiB
Markdown
94 lines
5.4 KiB
Markdown
# 文献管理
|
||
|
||
本地优先的文献管理桌面应用：文献库、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)。
|