所写即所得 · Live Markdown |
公式、图表、代码高亮就地渲染 · Rich rendering |
正文与 Markdown 源码互切 · Source toggle |
斜杠菜单插入块 · Slash menu |
[[ 双链]] 输入补全 · Wikilink suggest |
单击图表就地出源码 · Edit diagram inline |
表格右键插行插列 · Table editing |
正文图片拖拽缩放 · Image resize |
外部复制内容粘贴即净 · Paste cleaning |
Quarkdown 模板快照预览 · Quarkdown snapshot |
命令面板：搜文档、跑命令 · Command palette |
大纲按层级折叠 · Outline folding |
双栏对照与多窗格 · Split panes |
专注模式与打字机模式 · Focus & typewriter |
检查器：标签、属性、双向链接、历史 · Inspector |
今日速记浮层 · Daily capture |
全库搜索：标题、正文、标签 · Vault search |
全局标签：计数与含该标签的文档 · Global tags |
双向链接：谁引用了这篇 · Backlinks |
知识图谱：⌘G 就地铺开 · Graph layout |
Canvas 便签板拖拽 · Canvas board |
知识图谱：拖节点、跳文档 · Knowledge graph |
Word 导入：左预览右源码，校对后落库 · Word import |
拖入文件即打开，拖入文件夹即开库 · Drag & drop |
三套主题轮换 · Themes |
外观：主题即时切换 · Appearance |
快捷键设置：键位一张表 · Shortcuts |
五语言界面即时切换 · Five languages |
文件树与正文右键菜单 · Context menus |
Git：暂存、提交、历史 · Git panel |
系统原生菜单 · Native menus |
菜单栏托盘快捷入口（mac） · Tray menu |
---
## 中文
### 简介
Typora 编辑舒服，但一篇就是一篇，文件多了没组织；Obsidian 有组织，但双栏源码、插件、图谱一层套一层，重。NoteLume（中文名「文溯」）走的是两头都没占的那条路：像 Typora 一样单文档 WYSIWYG 直接写，像 Obsidian 一样把本地文件夹当知识库——\[\[双链\]\]、标签、反链、全文搜索、Git 同步都是内置的，不背插件生态和全量图谱的重量。
**适合谁用**：想要 Typora 的手感、又需要文件一多时找得回来的人。要插件生态、重型图谱、或 Obsidian 默认双栏源码的，请直接用 Obsidian，这里没有。
### 功能亮点
* ✍️ **所写即所得**：Markdown 与富文本双向无损往返；KaTeX 公式、Mermaid 图表、callout 卡片、合并单元格表格、块级裸 HTML、脚注、代码块子语言高亮，全都在渲染态直接编辑
* ✂️ **粘贴自动清理**：从 AI 对话框、飞书、公众号复制的内容直接粘——代码块头部的「复制」按钮、行号装订线、空段落串联在进编辑器前就摘掉，不用粘完再手修第二次
* 🗂 **文件夹即知识库**：`[[wikilink]]` 输入补全与悬浮预览、`#tag` 全局视图、双向链接面板、Canvas 便签板与力导向知识图谱、全库搜索、版本快照一键回滚；文件树右键直接在系统文件管理器里显示
* 🔒 **本地优先、零锁定**：纯 GFM 文件，Typora / Obsidian 可直接打开同一份库；整库可一键导出为标准 Markdown 副本（callout、`![[嵌入]]`、`[[双链]]` 写出时降级），任何编辑器能开；删除进系统回收站。默认不联网——只有你在「AI 设置」里接入服务商时，请求才会把当前文档片段、检索命中的笔记与会话历史发到该地址（本机 Ollama 不出机），发什么在设置页「数据流向」逐项列清
* 🤖 **AI 可选接入，不配也能用**：选区润色 / 续写 / 中英互译 / 摘要 / 自定义提示词，侧栏对话可带当前文档与全库检索；Agent 模式能查库、读笔记、提议改写，自动写入可整轮撤销。任意 OpenAI 兼容服务与本地 Ollama 共用一套设置，模型名自动检测；不配置时应用完全离线
* 📥 **Word 导入不坏版式**：`.docx` 拖进来，纯 Rust 离线直读 OOXML——标题、列表、超链接、合并单元格表、脚注、图片、公式尽量保真；落库前可视化校对（左预览右源码、降级项列清），图片按内容全库去重，反向还能导出 .docx
* ⚡ **Quarkdown 引擎（对官方 stdlib 差集清零）**：`.var` / `.function` / `.if` / `.foreach` 这套 Turing-complete 语法直接写进 md，快照式预览不碰源文件；约 200 个内置函数——正则替换、表格计算、CSV/JSON 读取、Mermaid 与 xychart 图表、交叉引用与编号系统（`.numbering` 格式串）、BibTeX 参考文献、多语言本地化、emoji 短代码、Bootstrap 图标、`Libraries/` 库目录、atoms 包安装、`.extend` 函数扩展。不用 Quarkdown 语法的文档仍是纯 GFM，Typora / Obsidian 照常打开
* 🎬 **导出一族**：单篇 / 整库幻灯片（自包含 reveal.js HTML，整库按文档分章）、整站静态站、打印排版（Paged.js 预分页：目录页、页码与页眉、H1 分页、封面）、Word .docx、标准 Markdown 副本（Obsidian 私有语法降级）
* 🔄 **Git 内置**：状态 / 历史 / 单文件 diff / 提交 / 推送 / 合并冲突解决全部内建（系统 git 与内嵌 libgit2 双引擎，没装 git 也能 fetch/pull）
* 🌐 **网页剪藏**：浏览器扩展（`extension/`，MV3）把网页正文 POST 给本机服务，Rust 按模板落盘、图片可选本地化进 `assets/`，并自动在文末关联库内相关笔记；只绑 127.0.0.1，只收扩展来源的请求
* 🧩 **功能开关与五语言**：`[[toc]]` 目录块、CSV 表格渲染、emoji 短代码、标题自动编号都是设置里的开关项，全关即标准模式；界面内置简体中文 / 繁體中文 / English / Français / Deutsch
* 📦 **轻**：macOS DMG 与 Windows 安装包都在 8–9 MB；插件系统（`.notelume-plugins/`）内建
### 快速开始
**安装**：到 [Releases](https://github.com/HackerSnail/NoteLume/releases) 下载对应平台的安装包；国内网络改走 [Gitee 发行版](https://gitee.com/hackerSnail/note-lume/releases)（同一批安装包）——
| 平台 | 文件 | 安装方式 |
| ------- | ------------------------------- | --------------- |
| Windows 10+ | `NoteLume_x.y.z_x64-setup.exe` | 双击安装 |
| macOS | `NoteLume_x.y.z_aarch64.dmg`（Apple Silicon） | 拖入 Applications |
| macOS | `NoteLume_x.y.z_x64.dmg`（Intel） | 拖入 Applications |
| Linux | `NoteLume_x.y.z_amd64.AppImage` | `chmod +x` 后运行 |
| Linux | `NoteLume_x.y.z_amd64.deb` | `sudo apt install ./NoteLume_x.y.z_amd64.deb` |
| Linux | `NoteLume-x.y.z-1.x86_64.rpm` | `sudo dnf install NoteLume-x.y.z-1.x86_64.rpm` |
Windows 版只支持 Windows 10 及以上，Win7 / Win8 装不上也起不来：Tauri v2 与 Rust 1.78 起的官方最低要求都是 Windows 10，WebView2 运行时也不再给 Win7 发新版本（最后一个可用的是 109，2023 年已停止支持），三层缺一层都打不开。
Linux 的 deb / rpm 依赖发行版自带的 **webkit2gtk-4.1**（包只声明依赖、运行时从系统取）：Ubuntu 22.04+ / Debian 12+ / Fedora / openSUSE 可直接装；**RHEL / Rocky 9 默认只有 webkit 4.0**，装 deb/rpm 会报依赖缺失，这类系统请改用 AppImage（自带全套运行库，不依赖系统 webkit）。
macOS 包只做了 ad-hoc 签名，没走开发者公证。首次打开被系统拦下时，右键应用选「打开」；或先执行 `xattr -dr com.apple.quarantine /Applications/NoteLume.app` 再启动。同一个卷宗里附了 `打开说明.txt`，三种办法都写在里面（源文件 `docs/macOS打开说明.txt`）。
**使用**：打开后 `Ctrl+Shift+O` 选一个存着 `.md` 的文件夹作为知识库，开写；只想改单个文件就 `Ctrl+O`。全部键位可在命令面板（`Ctrl+Shift+P`）和快捷键设置里查看、重绑；界面语言在工具条「更多 → 界面语言」切换。
**从源码构建**：需要 Rust 1.80+ 与 Node 18+。
```bash
cd src && npm install && cd ..
npm run dev # 开发模式（首次约 5–10 分钟编译 Rust 依赖）
npm run build # 生产打包（产物在 src-tauri/target/release/bundle/）
```
**mac 打包并签名**：`npm run build` 的 `postbuild` 已经挂在收尾脚本 `scripts/wrap-mac-dmg.mjs` 上——先给 `.app` 补 ad-hoc 签名（Tauri 直接出的是 linker-signed，拿去分发报「已损坏」），再带着一份 `打开说明.txt` 重卷成 dmg。手动走这一趟只要两条命令：
```bash
node src/node_modules/@tauri-apps/cli/tauri.js build --bundles app,dmg # 必须带 app：只要 dmg 时组完卷会把 .app 删掉，收尾脚本没得重卷
node scripts/wrap-mac-dmg.mjs # 补 ad-hoc 签名，重卷出带 .app 与「打开说明.txt」的 dmg
```
卷宗里的 `打开说明.txt` 源文件是 `docs/macOS打开说明.txt`，收尾脚本在补签之后把它放进卷宗根、不参与签名校验，要改收件人看到的内容就改这个文件；改完重跑一次 `node scripts/wrap-mac-dmg.mjs` 即按新内容重卷。卷宗根另有 `NoteLume.app` 与 `Applications` 软链两项，`.DS_Store` 会被脚本清掉。
卷宗名里的架构段由收尾脚本读二进制得出，Apple Silicon 落 `_aarch64`、Intel 落 `_x64`。Intel 包默认由 CI 在 Intel runner 上原生打；要在 Apple Silicon 上交叉打，先 `rustup target add x86_64-apple-darwin`，构建加 `--target x86_64-apple-darwin`，产物落在 `src-tauri/target/x86_64-apple-darwin/release/bundle`，收尾脚本把该目录整体作为参数传进去。补签后的包仍未公证，`spctl -a -t exec` 照旧 rejected，收件人侧的处理办法见上面的「打开说明」。
### 进阶：用 Quarkdown 让笔记可编程
这是 NoteLume 区别于 Typora / Obsidian 的一张王牌：md 里可以直接写 `.var` / `.foreach` / `.if` 这类指令，编辑器出求值结果——快照式预览，光标移出指令区即渲染，源文件一个字节不动；导出 HTML / 幻灯片 / 整站 / PDF 时同样展开。
注意：**用了 Quarkdown 指令的文档不再是标准 GFM**——Typora / Obsidian 打开时指令部分显示为普通文本（不含指令的文档不受影响，仍是纯 GFM）。
```markdown
.var {author} {你的名字}
.var {week} {第 42 周}
# 周报 · .week
作者：.author
.foreach {1..3}
- 条目 .1：一句话说清做了什么
```
编号与交叉引用也能编排：
```markdown
.numbering
- headings: 1.1
- figures: (1)
## 背景 {#intro}
见 .ref {intro}。
```
约 200 个内置函数：正则替换、CSV / JSON 读取、表格计算、BibTeX 参考文献、多语言本地化、emoji 短代码、`.extend` 自定义扩展。**不用学语法也能上手**：斜杠菜单（`/`）里搜 Quarkdown 有即插即出的片段；工具条「模板」菜单带三个开箱即跑的内置模板（周报、变量化文档头、编号与交叉引用）。完整函数清单见 [`docs/FEATURES.md`](docs/FEATURES.md)。
### 网页剪藏
把浏览器里的网页正文存进知识库：按模板落盘成标准 md，图片进 `assets/`，文末自动关联库内相关笔记。
1. **装扩展**：Edge 地址栏输 `edge://extensions`，打开左下角「开发人员模式」，点「加载已解压缩的扩展」选仓库里的 `extension/` 目录（Chrome 是 `chrome://extensions` → 右上角「开发者模式」→「加载已解压的扩展程序」）。加载后建议在工具栏拼图菜单里把「NoteLume 剪藏」固定出来。
2. **NoteLume 里开服务**：mac 从菜单栏「NoteLume → 网页剪藏设置」进入，Windows / Linux 走工具条「更多 → 网页剪藏设置」；勾选「启用剪藏服务」后保存，设置面板底部显示「剪藏服务已启动：127.0.0.1:<端口>」。同一个设置里还能选模板（库内 `Templates/` 下的 md）、目标目录（默认 `Clippings/`）、文件名模式（默认 `{{date}}-{{title}}`）、自动关联的篇数，以及图片本地化与整页兜底两个开关。
3. **扩展里填地址**：右键扩展图标 →「选项」，服务器地址填设置里显示的地址（默认 `http://127.0.0.1:3210`），「测试连接」应回「连接正常 · 已打开知识库」。填这一项就够了。
4. **剪**：点固定出来的扩展图标剪整页；或先在页面上选中文字，右键「剪藏选中内容到 NoteLume」只剪片段（用内置 highlight 模板落盘，来源行进引用块）。
正文提取按优先级降级：Defuddle → Readability + Turndown →（设置里打开「整页兜底」才有）整页 HTML。剪藏落在 `Clippings/<日期>-<标题>.md`，frontmatter 记 `title / source / author / published_at / clipped_at / tags / template`，文末「\#\# 相关笔记」列出打分最高的相关文档，点开即跳；被关联文档的反链面板里也能看到这篇剪藏。
图片本地化默认关：正文保留网页原链接，剪藏快，但外链图在离线 / 防盗链场景会裂图。在剪藏设置里勾选「图片本地化」后，扩展才把图取成 data URI 落 `Clippings/assets/`（按内容去重，md 里是 `./assets/` 相对链接）。
服务只绑 `127.0.0.1`，且只收扩展来源的请求（网页的 fetch 到不了）。NoteLume 没开、没开知识库、内容超过 8MB 时，扩展会弹对应的失败通知。详细错误对照见 `extension/README.md`。
### 快捷键
mac 上 `Ctrl` 即 `⌘`。以下键位按 Typora / Obsidian 主流习惯预置，全部可在「快捷键设置…」里重绑（mac 在菜单栏 NoteLume 下，Windows / Linux 在工具条「更多」里；冲突会硬阻止保存）。
**文件与导航**
| 键位 | 作用 |
| ----------------------------- | ---------------------- |
| `Ctrl+N` | 新建文件（先落系统临时目录，不要求开库） |
| `Ctrl+O` | 打开单个 Markdown 文件 |
| `Ctrl+Shift+O` | 打开文件夹作为知识库 |
| `Ctrl+Tab` / `Ctrl+Shift+Tab` | 切换下一个 / 上一个标签页 |
| `Ctrl+W` | 关闭当前标签页 |
| `F2` | 重命名当前文件（可顺带移动） |
| `Ctrl+S` | 保存（临时文件 = 另存为，选正式位置） |
| `Ctrl+P` | 打印 / 另存 PDF |
| `Ctrl+Shift+P` | 命令面板（模糊搜命令 / 文档） |
| `Ctrl+E` | 正文与 Markdown 源码整篇互切 |
| `Ctrl+F` | 本篇文档内查找 |
| `Ctrl+H`（mac：`⌥⌘F`） | 本篇文档内查找替换（mac 的 ⌘H 归系统「隐藏」） |
| `Ctrl+Shift+F` | 聚焦侧栏全局搜索 |
| `Ctrl+Shift+V` | 粘贴为纯文本 |
| `Ctrl+Shift+I` | 插入图片（自动入库 `assets/`） |
| `Ctrl+K` | 插入 / 编辑链接（地址留空 = 解除链接） |
**格式与段落**
| 键位 | 作用 |
| ------------------------------- | ---------------- |
| `Ctrl+B` / `Ctrl+I` | 粗体 / 斜体 |
| `` Ctrl+` `` | 行内代码 |
| `Ctrl+Shift+K` | 代码块 |
| `Ctrl+Shift+X` | 删除线 |
| `Ctrl+1` \~ `Ctrl+6` | 设为一级 \~ 六级标题 |
| `Ctrl+]` / `Ctrl+[` | 提升 / 降低标题级别 |
| `Ctrl+Shift+Q` | 引用块 |
| `Ctrl+Shift+L` | 任务列表 |
| `Ctrl+Shift+[` / `Ctrl+Shift+]` | 无序 / 有序列表 |
| `Ctrl+T` | 插入表格 |
| `Ctrl+D` | 删除当前行 / 段落 |
| `Ctrl+M` | 插入行内公式（有选区则包裹） |
| `Ctrl+Shift+M` | 插入块级公式 |
| `Ctrl+Z` / `Ctrl+Y` | 撤销 / 重做 |
| `Shift+Enter` | 硬换行 |
| `Tab` / `Shift+Tab` | 表格单元格间跳转（末行自动补行） |
**视图**
| 键位 | 作用 |
| ------------------ | ----------------- |
| `Ctrl+G` | 打开 / 关闭知识图谱 |
| `Ctrl+Shift+D` | 今日速记（全局浮层，独立于知识库） |
| `` Ctrl+Shift+` `` | 专注模式（当前块高亮） |
| `Ctrl+Shift+T` | 打字机模式（当前块居中） |
| `Ctrl+Shift+S` | 隐藏 / 显示侧栏 |
| `Ctrl+Shift+B` | 隐藏 / 显示右侧检查器栏 |
| `Ctrl+Shift+H` | 折叠 / 展开当前节 |
### 技术栈
| 层 | 选型 |
| ---- | ------------------------------------------------------------ |
| 桌面外壳 | Tauri v2 + Rust（文件 I/O、索引、docx 解析、Git、Quarkdown 引擎全在 Rust 侧） |
| 编辑器 | ProseMirror（WYSIWYG）+ CodeMirror 6（源码模式），无 Vue/React 框架 |
| 前端构建 | Vite |
| 存储 | 本地文件夹 + 标准 GFM `.md`，无数据库、无私有格式 |
### 贡献指南
1. Fork 仓库，基于 `master` 切出自己的分支（网页版开发隔离在 `web` 分支，请勿向上合并）
2. 改动后跑离线回归：`npm run test:roundtrip`，或逐个执行 `src/tests/*.test.mjs`
3. 提交 PR，CI（GitHub Actions）会自动跑前端测试、Rust check/test 与三平台构建
4. 设计文档与迭代规划见 [`docs/CLAUDE.MD`](docs/CLAUDE.MD)、[`docs/ROADMAP.md`](docs/ROADMAP.md)；逐项功能细节与已知边界见 [`docs/FEATURES.md`](docs/FEATURES.md)
Issue 和 PR 都欢迎，也欢迎任何形式的功能建议。
### 交流群
