贡献指南

NoteGen 是开源社区项目。修复问题或开发功能前，请先搜索 Issues 和 Discussions。较大的行为变化建议先创建 Issue 讨论范围。

技术栈

Tauri 2：Windows、macOS、Linux、Android、iOS 容器与原生能力；
Next.js 15、React 19、TypeScript；
Tiptap 3 Markdown 编辑器；
Zustand、SQLite、Tauri Store；
Tailwind CSS 4、shadcn/ui；
OpenAI 兼容模型、RAG、MCP、Skills 与本地 OCR。

准备环境

先完成 Tauri 2 前置要求，并安装 Node.js 与 pnpm。

git clone https://github.com/your-username/note-gen.git
cd note-gen
git switch dev
pnpm install
pnpm tauri dev

前端开发服务器使用 http://localhost:3456。如果窗口白屏，先查看启动终端和开发者工具中的错误，再尝试重新加载。

目录结构

src/
├── app/core/             桌面端主界面、编辑器、记录、对话与设置
├── app/mobile/           移动端记录、写作、对话与设置
├── components/           通用组件和 shadcn/ui
├── config/               快捷键、同步排除项等配置
├── db/                   SQLite 数据访问
├── hooks/                React Hooks
├── i18n/                 国际化运行配置
├── lib/                  AI、Agent、MCP、Skills、同步、OCR 等核心逻辑
├── stores/               Zustand 状态模块
└── types/                公共类型
src-tauri/                Rust 命令、平台能力、权限与打包配置
messages/                 各语言界面文案
.github/workflows/        发布流程

常用命令

pnpm dev                  # 仅启动 Next.js
pnpm tauri dev            # 启动桌面应用
pnpm build                # 静态导出前端
pnpm tauri build          # 构建当前桌面平台安装包
pnpm tauri android dev    # Android 开发
pnpm tauri android build  # Android 构建
pnpm tauri ios dev        # iOS 开发（需要 macOS/Xcode）
pnpm tauri ios build      # iOS 构建
pnpm sync-version         # 将 Tauri 版本同步到 iOS 工程

仓库中的部分模块使用 Node 内置测试或同目录规格文件。修改相关逻辑时，先查找附近的 *.test.*、*.spec.* 和项目脚本，并运行对应测试。

开发约定

从 dev 创建 fix/... 或 feat/... 分支，不直接在 dev 上开发。
客户端组件需要 'use client'；TypeScript 保持严格类型。
添加界面文案时同步更新 messages/ 下所有语言文件的键。
修改模型、同步、隐私或用户操作路径时，同时更新官网文档。
不提交 API Key、Token、签名文件、个人路径或真实用户数据。

Pull Request

PR 标题采用 fix(#issue): 描述 或 feat(#issue): 描述。正文应说明问题、方案、影响平台、验证方式和界面截图。提交前至少确认相关构建、类型检查或测试通过。

项目从 dev 开发，推送 release 分支会触发 GitHub Actions 构建和发布桌面及 Android 产物。不要在普通功能 PR 中修改发布版本或签名配置，除非 Issue 明确要求。

移动端

Android 和 iOS 需要各自的 Tauri、SDK、签名与设备环境。签名密钥和 keystore.properties 等本地文件不得提交。移动端不支持所有桌面能力，例如 stdio MCP 和系统托盘，新增功能时需要同时检查桌面与移动路由。