# GeniusNote

**Repository Path**: narcijie/genius-note

## Basic Information

- **Project Name**: GeniusNote
- **Description**: Genius Note — 个人 Markdown 记事本，基于 Git 与本地文件，可选远端同步。
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-04-03
- **Last Updated**: 2026-07-20

## Categories & Tags

**Categories**: Uncategorized

**Tags**: AI-Coding

## README

# GeniusNote

## v1.2.0 更新要点

- 同步前强制保存最新正文并等待已开始的仓库写入，避免第一次只同步到旧工作区；本地领先会直接提交并推送。
- 桌面端落实 30 秒 Git HTTP 超时，桌面与 Android 对常见瞬时网络错误自动重试；文件选择同步会分别安全重试 fetch 与 push。
- Android 显式校验 JGit fetch、pull、push 的原生返回状态，避免失败被误报为成功。
- 同步日志新增阶段耗时、重试次数、决策和最终结果；失败摘要默认保留，并自动移除正文、凭据和本地路径。
- 正文落盘与列表刷新分开判定；连续改标题、撤销、移动、删除或切换上下文时会保护未落盘草稿，避免旧路径重建和假保存失败。
- 根版本与 Android `versionName` 已同步到 `1.2.0`，Android `versionCode` 更新为 `28`。

个人 Markdown 记事本桌面应用：**每个记事本对应一个 Git 仓库**，笔记为仓库内的 `.md` 文件，支持通过 Git 与远端（如 GitHub、Gitee）同步。数据以本地文件为准，离线可编辑。

**当前发行版本**：v1.2.0（以根目录 `package.json` 的 `version` 与 Android `app/build.gradle` 的 `versionName` 为准）。

详细产品说明见 [PRD.md](./PRD.md)。

## 功能概览

- 多记事本：支持本地记事本与云端同步记事本；云端记事本绑定本地目录与独立 Git 远程配置
- 新建同步记事本可选择「在 Gitee 新建并同步」：填写 Gitee 用户名、仓库名和私人令牌后，应用会创建空仓库、初始化本地 `master` 分支并首次推送
- Markdown 编辑与预览、笔记目录树、文件夹组织、搜索（标题与正文）、文件/文件夹导入
- Mermaid 图表：支持 `mermaid` 代码块渲染，工具栏 / 右键菜单可插入图表模板，帮助页内置可复制示例库
- 数学公式：支持行内 `$E=mc^2$`、块级 `$$...$$` 与 `math` 代码块，工具栏可插入公式模板，导出与历史预览会渲染公式
- Markdown 导入会按正文第一条非空行重命名目标笔记文件，保持仓库内文件名和正文标题更一致
- 当前笔记查找与替换：支持关键词、大小写敏感、全字匹配、正则、逐条跳转和替换，并内置正则帮助弹窗
- 重点笔记：本机星标标记、侧栏“只看重点”筛选、笔记行重点标识
- 文档历史：按当前笔记的 Git 时间线查看历史 Markdown 预览，可恢复到本地草稿
- Git：提交、拉取、推送；凭证可由系统安全存储（keytar）  
- 同步差异处理：当本地与云端分叉时，会优先尝试自动线性合并；无法自动合并时可逐文件选择保留本地或云端版本
- 笔记与云端存在文件级差异时，侧栏右键菜单可对单篇执行「撤回本地修改」，移动端长按菜单也提供 `移动到… / 撤回本地修改 / 删除笔记`
- 全局设置增强：主题、字号、自动保存、会话恢复、应用日志开关  
- 配置迁移：支持记事本配置 YAML 导出/导入（导入后展示跳过明细）  
- 导出增强：支持导出 Markdown / PNG / PDF / Word，导出设置可控制页面宽度、纸张尺寸、方向与页边距，并渲染 Mermaid 图表、公式与图表资源；所有格式导出都会在底部状态栏显示进度，PDF 保留文字层
- 桌面端云端同步仅支持 HTTPS 远端  
- 图片等资源随仓库保存，相对路径引用  
- 新建记事本默认分支为 `master`；导入或克隆已有仓库时会沿用仓库实际分支

**同步与状态栏（简要）**

- 底部状态栏展示同步结果、相对远端的云端关系（一致 / 本地领先 / 云端领先 / 已分叉等）以及笔记文件级差异统计；打开记事本时若自动拉取远端更新，界面会在拉取完成后刷新上述信息。  
- 本地记事本不会要求远端 URL，并会禁用同步相关操作；记事本栏用图标区分本地与云端类型。
- 首次同步空远端时会直接推送创建远端分支；如果远端已在网页端生成 README 等独立历史，会进入同步策略选择，避免“没有共同提交”后卡住。
- **Android**：笔记较多时单次保存会触发目录遍历与 Git 差异计算；实现上对连续保存做了串行化，降低并发重入导致的卡顿风险。详见 [CHANGELOG.md](./CHANGELOG.md) 与 [docs/android/02-storage-and-git.md](./docs/android/02-storage-and-git.md)。

## 常用快捷键

| 按键 | 作用 |
|------|------|
| `F1` | 展开 / 关闭侧边栏；窄屏下打开 / 关闭导航抽屉 |
| `F2` | 切换当前笔记阅读模式 |
| `F3` | 打开 / 关闭当前笔记文档历史 |
| `F4` | 标记或取消当前笔记重点 |
| `F5` | 同步当前云端记事本 |
| `F6` | 打开 / 关闭当前笔记目录 |
| `Ctrl/Cmd+F` | 打开当前笔记查找 |
| `Ctrl+H` / `Cmd+Alt+F` | 打开当前笔记替换 |
| `Ctrl/Cmd+Shift+F` | 聚焦侧栏跨笔记搜索 |

## 技术栈

- **Electron** + **TypeScript**  
- **React** + **Vite**（渲染进程）  
- **isomorphic-git**（纯 JS Git 实现）  
- 编辑器：**Vditor**（IR 即时渲染）；静态资源经 `scripts/copy-vditor-assets.cjs` 打入应用，**不依赖外网 CDN，可完全离线使用**（Git 同步远端仍为可选在线能力）  

## 环境要求

- **Node.js**（建议 LTS，与团队一致即可）  
- **npm**  

## 开发与调试

```powershell
npm install
npm run dev
```

`predev` 会生成应用图标所需的 `build/icons/app-icon.png`（由 `assets/brand/logo.svg` 栅格化）。若单独更新矢量 LOGO，可执行：

```powershell
npm run icons
```

## 构建与打包

类型检查与单元测试：

```powershell
npm run typecheck
npm test
```

编译主进程与渲染进程（会执行 `prebuild`：生成构建信息并刷新图标）：

```powershell
npm run build
```

使用 **electron-builder** 输出安装包（Windows 默认 NSIS 与 portable；macOS / Linux 配置见 `package.json` 的 `build` 字段）：

```powershell
npm run pack    # 仅解包目录，便于快速验证
npm run dist    # 完整产物输出到 release/
```

未设置 `ELECTRON_BUILDER_BINARIES_MIRROR` 时，[`scripts/electron-dist.cjs`](./scripts/electron-dist.cjs) 会默认使用 npmmirror 镜像，减轻国内网络拉取构建工具失败的情况。Android 相关脚本会自动探测 SDK / JBR，并在找到 SDK 时补齐 [`android/local.properties`](./android/local.properties)。

## 脚本用法速查

### npm scripts

| 命令 | 用途 | 说明 |
|------|------|------|
| `npm run dev` | 启动桌面端开发环境 | 并行启动 `Vite`、主进程 `tsc --watch` 和 Electron |
| `npm run dev:watch` | 启动带 Electron 自动重启的开发环境 | 适合频繁改主进程代码 |
| `npm run dev:renderer` | 仅启动渲染进程开发服务器 | 默认监听 `5173` |
| `npm run dev:main` | 仅监听编译主进程 | 输出到 `dist-electron/main` |
| `npm run build` | 编译前后端 | 会先执行 `prebuild`，刷新图标和构建信息 |
| `npm run build:renderer` | 仅构建渲染进程 | 包含 Vditor 离线资源复制与离线校验 |
| `npm run build:main` | 仅构建主进程 | 使用 `tsconfig.main.json` |
| `npm run typecheck` | TypeScript 类型检查 | 检查渲染进程和主进程 |
| `npm test` | 运行单元测试 | 使用 `vitest run` |
| `npm run pack` | 生成桌面端解包目录 | 便于快速验包，不出安装程序 |
| `npm run dist` | 生成桌面端正式产物 | 输出到 `release/` |
| `npm run cap:sync` | 同步 Web 产物到 Android 工程 | 等价于 `npx cap sync android` |
| `npm run cap:open` | 用 Android Studio 打开原生工程 | 等价于 `npx cap open android` |
| `npm run android:prepare` | 构建前端并同步到 Android | 等价于 `node scripts/android-tools.cjs prepare` |
| `npm run android:sync` | 仅同步 Android 工程 | 等价于 `node scripts/android-tools.cjs sync` |
| `npm run android:build:debug` | 构建 Android Debug APK | 会先构建前端并同步 |
| `npm run android:build:release` | 构建 Android Release APK | 会先构建前端并同步 |
| `npm run android:build:all` | 同时构建 Android Debug / Release APK | 会先构建前端并同步 |
| `npm run android:install:debug` | 构建并通过 adb 安装 Debug APK | 要求本机可用 `adb` |
| `npm run android:install:release` | 构建并通过 adb 安装 Release APK | 若产物未签名，adb 安装可能失败 |
| `npm run release:build` | 一次性编译双端并收集产物 | 会生成桌面安装包、Android APK，并汇总到 `release/artifacts/v<version>/` |

### scripts 目录中的入口

| 脚本 | 用法 | 说明 |
|------|------|------|
| [`scripts/android-tools.cjs`](./scripts/android-tools.cjs) | `node scripts/android-tools.cjs help` | Android 构建、同步、安装统一入口；优先调用仓库内 Capacitor CLI，并自动补齐 SDK / JBR 环境 |
| [`scripts/electron-dist.cjs`](./scripts/electron-dist.cjs) | `node scripts/electron-dist.cjs --win nsis` | Electron Builder 包装脚本，直接走仓库内 CLI 并自动注入镜像变量 |
| [`scripts/electron-install-app-deps.cjs`](./scripts/electron-install-app-deps.cjs) | `node scripts/electron-install-app-deps.cjs` | 安装依赖后补跑 Electron 原生依赖准备，减少不同机器上 `postinstall` 的环境差异 |
| [`scripts/release-build.cjs`](./scripts/release-build.cjs) | `node scripts/release-build.cjs` | 双端发布构建入口，供 `npm run release:build` 调用 |
| [`scripts/copy-vditor-assets.cjs`](./scripts/copy-vditor-assets.cjs) | `node scripts/copy-vditor-assets.cjs` | 复制编辑器离线资源到构建输出 |
| [`scripts/verify-dist-renderer-offline.cjs`](./scripts/verify-dist-renderer-offline.cjs) | `node scripts/verify-dist-renderer-offline.cjs` | 校验渲染产物不依赖外网静态资源 |
| [`scripts/rasterize-app-icon.cjs`](./scripts/rasterize-app-icon.cjs) | `node scripts/rasterize-app-icon.cjs` | 从矢量 LOGO 生成应用图标 |
| [`scripts/generate-build-info.cjs`](./scripts/generate-build-info.cjs) | `node scripts/generate-build-info.cjs` | 生成构建信息，供关于页和帮助页读取 |
| [`scripts/ensure-keytar.cjs`](./scripts/ensure-keytar.cjs) | 安装依赖时自动调用 | 检查并准备 `keytar` 依赖 |

### Android 脚本常用环境变量

| 变量 | 用途 | 优先级 / 说明 |
|------|------|------|
| `GENIUSNOTE_ADB_PATH` | 指定 `adb` 可执行文件 | 优先级最高，适合多 SDK 并存 |
| `ADB` | 指定 `adb` 可执行文件 | 次于 `GENIUSNOTE_ADB_PATH` |
| `GENIUSNOTE_ANDROID_SDK_ROOT` | 指定 Android SDK 根目录 | 高于 `ANDROID_SDK_ROOT` / `ANDROID_HOME` |
| `ANDROID_SDK_ROOT` | 指定 Android SDK 根目录 | 常规 Android 环境变量 |
| `ANDROID_HOME` | 指定 Android SDK 根目录 | 兼容旧环境变量 |
| `GENIUSNOTE_JAVA_HOME` | 指定 Java / JBR 根目录 | 高于系统 `JAVA_HOME` |
| `JAVA_HOME` | 指定 Java / JBR 根目录 | 脚本会优先选择满足 Java 21 要求的 JDK |

Android 脚本还会读取 [`android/local.properties`](./android/local.properties) 中的 `sdk.dir`。若未显式设置 SDK 路径，脚本会自动回退到它。

### 常见用法示例

开发桌面端：

```powershell
npm install
npm run dev
```

仅打桌面安装包：

```powershell
npm run dist
```

构建并安装 Android Debug APK：

```powershell
$env:GENIUSNOTE_ADB_PATH = "C:\Users\Administrator\AppData\Local\Android\Sdk\platform-tools\adb.exe"
npm run android:install:debug
```

一次性编译双端并收集产物：

```powershell
npm run release:build
```

## Android（Capacitor 预览）

说明与 `window.api` 契约见 [docs/android/README.md](./docs/android/README.md)。构建前端并同步到原生工程：

```powershell
npm run build
npm run cap:sync
npm run cap:open   # 用 Android Studio 打开 android/
```

`android/.gitignore` 会忽略由 `cap sync` 拷贝的 Web 资源目录；克隆仓库后需本地执行上述 `build` + `cap:sync`。

## 同步策略（分叉场景）

- 当同一记事本出现「本地已提交」与「云端已提交」并且二者不一致时，应用会弹出同步策略对话框。  
- 对话框会展示本地与云端最近提交时间，帮助判断应保留哪一侧版本。  
- 可选策略：  
  - `本地为准`：以当前设备内容覆盖远端（适合本地改动为主的场景）。  
  - `云端为准`：丢弃本地未同步差异并对齐远端（适合远端最新为准的场景）。  
- 单篇「撤回本地修改」仅影响当前 `.md` 文件，与整库的「云端为准」不同，不移动 `HEAD`。  
- 该操作会影响当前记事本仓库，请先确认关键改动已备份。

## 配置与日志

- 全局设置支持开启详细应用日志。日志文件位于 `userData/logs/genius-note-app.log`（结构化单行文本）；详细日志关闭时仍保留同步失败和崩溃摘要。
- 日志会自动移除笔记正文、访问凭据和本地路径；反馈同步问题时可在设置页复制日志路径。
- 也可通过环境变量 `GENIUSNOTE_APP_LOG=1` 在启动前启用日志。  
- 设置页支持导出/导入记事本配置 YAML。请注意导出内容可能包含 HTTP 明文凭据，仅用于受控环境下的可编辑备份。

## 仓库结构（节选）

| 路径 | 说明 |
|------|------|
| `src/main/` | Electron 主进程、IPC |
| `src/renderer/` | 界面与前端逻辑 |
| `src/core/`、`src/infra/` | 领域服务与文件/Git 等基础设施 |
| `src/shared/` | 主进程与渲染进程共享类型与工具（含 `windowApiTypes`） |
| `src/renderer/host/` | Capacitor 宿主注入与 Android 侧文件实现 |
| `docs/android/` | Android 路径说明、存储/Git、同步与保存行为 |
| `CHANGELOG.md` | 版本变更记录 |
| `PRD.md` | 产品需求说明 |
| `android/` | Capacitor 生成的 Android 工程（需配合 `cap:sync`） |
| `assets/brand/logo.svg` | 应用矢量 LOGO 源稿 |
| `public/favicon.svg` | 页面 favicon |
| `scripts/` | 构建、打包辅助脚本 |

## 许可证

MIT（见 [package.json](./package.json) 中的 `license` 字段）。