Notes
本地优先的 Markdown 阅读 / 编辑工具。.md 文件即笔记，文件即数据 —— 看到和磁盘上一字不差，复制走就是备份。
特点
- 所见即所得 —— 保存时原样写回，不会重排 Markdown 格式
- 默认离线 —— 不配 AI 就永不联网；API Key 走系统密钥库（Windows DPAPI / macOS Keychain / Linux libsecret）
- 桌面级体验 —— CodeMirror 6 编辑器 + 实时预览双栏，键盘快捷键齐全
- 抗意外 —— 原子写盘、外部修改检测、退出保护，断电不留半截
- 托盘常驻 —— 关窗不等于退出，单击托盘图标恢复
5 分钟上手
需要 Node.js 20.18 或更高（下载）。
git clone <仓库地址> notes
cd notes
npm install
npm start
首次启动会在主目录创建 Notes 文件夹（Windows 是 C:\Users\<你>\Notes，macOS / Linux 是 ~/Notes），并把欢迎页复制进去。把任意 .md 文件丢进那个文件夹，左侧栏立刻出现。
按 Ctrl + , 打开设置。工具栏已经有「主题 / 视图 / 自动保存」等按钮，设置里不会出现重复入口。
阅读与编辑
Ctrl + E在「预览 / 编辑 / 双栏」之间循环Ctrl + F按文件名实时过滤侧栏Ctrl + N新建笔记，Ctrl + S保存（IME 拼音合成中不会误触发），Ctrl + W关闭当前文件Ctrl + Shift + F聚焦模式 —— 隐藏工具栏 / 侧栏 / 状态栏，纯净阅读- 状态栏实时显示当前章节标题
- 外链走系统浏览器；同目录
.md相对链接在 Notes 内打开；#标题锚点文内跳转 相对路径图片直接渲染
AI 改稿
Ctrl + Shift + A 打开底部 AI 面板。输入你想怎么改（润色 / 翻译 / 总结 / 续写），AI 给出行级 + 词级 diff，逐段应用或一键应用全部，不满意随时取消。
| 协议 | 适用服务 | Base URL 要点 |
|---|---|---|
| OpenAI 兼容 | OpenAI / DeepSeek / Moonshot / 自部署 | 必须含 /v1 |
| Anthropic 兼容 | Claude 系列 / 第三方中转 | 不含 /v1 |
API Key 默认脱敏显示，点眼睛图标露出明文。不配 AI 不影响其它功能。
整理侧栏
- 拖到文件夹上 = 移动。拖拽时按住
Ctrl（macOS 是Cmd）= 复制，文件夹会递归复制，软链接会被跳过 - 侧栏聚焦时：
Ctrl + X剪切，Ctrl + C复制，Ctrl + V粘贴到当前正在浏览的目录 - 右键菜单功能同上。侧栏空白区域右键也能粘贴到当前目录（剪贴板为空时该菜单项禁用）
- 目标文件夹已有同名项时自动加
(2)/(3)... 改名避免覆盖 - 不能把文件夹拖进自己或子孙目录（会被拦下）
数据安全
- API Key 加密 —— 写盘前加密，运行时主进程栈上才解出明文
- 外部修改检测 —— 其他编辑器改了文件会提示重新加载（正在打字时不打断）
- 退出保护 —— 有未保存改动关窗 / 退托盘，先问「保存 / 丢弃 / 取消」
- 原子写盘 —— 写到临时文件再 rename
- 数据目录自动回退 —— U 盘拔了 / 网盘断连自动切回默认目录
- 云盘友好 —— OneDrive / 坚果云 / iCloud 做过专门适配
数据文件夹
| 系统 | 默认路径 |
|---|---|
| Windows | C:\Users\<你>\Notes |
| macOS | ~/Notes |
| Linux | $HOME/Notes |
设置里可以改成任意目录。状态栏最左段（紧贴当前路径）有三个 icon-only 按钮：打开、切换、回到默认。
快捷键
Mac 把
Ctrl换成Cmd，下表通用。
| 快捷键 | 作用 |
|---|---|
Ctrl + F |
聚焦文件搜索 |
Ctrl + N |
新建笔记 |
Ctrl + S |
保存（IME 合成中不触发写盘） |
Ctrl + W |
关闭当前文件 |
Ctrl + E |
预览 / 编辑 / 双栏切换 |
Ctrl + Shift + F |
切换聚焦模式 |
Ctrl + Shift + T |
切换主题 |
Ctrl + Shift + A |
切换 AI 面板 |
Ctrl + , |
打开设置 |
Ctrl + R |
重新加载界面 |
Ctrl + X / C / V |
剪切 / 复制 / 粘贴（侧栏聚焦时） |
Esc（搜索框内） |
清空搜索 |
F12 |
打开 DevTools |
窗口是无边框自绘标题栏，Windows / Linux 上看不到菜单栏，但上表所有快捷键全部生效。
常见问题
搜索文件没反应？
看设置里的「数据文件夹」对不对。某些云盘实时监听不可靠，按 Ctrl + R 手动刷新。
AI 提示「无法连接到服务」？
OpenAI 兼容协议 Base URL 必须含 /v1，Anthropic 不含。点眼睛图标露出 API Key 明文，确认没多余空格 / 换行。按 F12 看完整错误码。
中文 Windows 启动报错？ Electron 在中文路径下启动会报错。两种办法：
- 推荐：把项目挪到纯英文路径，如
D:\Projects\notes - 用管理员 cmd 建符号链接：
然后在
mklink /D C:\dev\notes "C:\当前\中文路径\Notes"C:\dev\notes跑npm install && npm start
控制台中文乱码？
用 npm start，别用 npm run start:raw。前者自动把控制台切到 UTF-8。
笔记文件会被改动吗？ 不会。读什么就显示什么，保存时原样写回 —— 不会偷偷重排 Markdown 格式。
怎么更新到新版本？
git pull
npm install
npm start
你的 ~/Notes 笔记文件夹完全独立，更新代码不影响数据。
给开发者
npm start # 启动（自动处理中文 Windows 编码）
npm test # 全部单测（1217 用例 / 59 文件）
npm run test:watch # watch 模式
npm run check # 语法 + IPC 通道配对
npm run lint # ESLint
npm run build:win # 打包 Windows 安装包 → dist/
npm run build:mac # 打包 macOS → dist/
npm run build:linux # 打包 Linux AppImage → dist/
Notes/
├── main.js # Electron 主进程入口
├── preload.js # IPC 桥（contextBridge）
├── index.html # UI 框架 + CSP + importmap
├── main/ # 主进程：ai / config-store / file-ops / fs-watcher / secret-store
├── src/ # 渲染端：UI 组件 + CSS 分片（01-12）+ AI 面板
├── shared/ # 主 / preload / 渲染端共享：schema / diff / sanitize
├── data/ # 首次启动种子化的欢迎页（1 篇）
├── scripts/ # 启动包装 / 语法检查 / IPC 校验
└── tests/
├── unit/ # vitest 单测（59 文件 / 1217 用例）
└── manual/ # 手工视觉验证产物（不进版本库）
License
MIT