NoteGen：一款本地优先、以 Markdown 为核心、用 AI 串联“记录—整理—写作“全流程的跨平台笔记应用

• AI 应用
• RAG
• 桌面应用
• 前端

NoteGen 是 codexu/note-gen 仓库所实现的一款跨平台笔记应用：它以"先记录，再整理"（Capture first. Organize later.）为核心设计哲学，将零散素材（文字、录音、截图、链接、文件、待办）先无摩擦地沉淀为"记录"（Record/Mark），再借助你自行配置的 AI 模型将它们组织成结构化的 Markdown 笔记。本文将从项目定位、核心工作流、Markdown 编辑能力、AI 能力矩阵、知识库检索、画布工作区、同步方案、下载与上手等维度，结合仓库源码与配置逐层展开，帮助你快速判断它是否适合你的记录与写作工作流。

一、项目定位：把"记录"和"整理"分成两个阶段

NoteGen 在 README.zh-CN.md 中给出的定位是"本地优先、以 Markdown 为核心，帮助你收集碎片信息，并借助 AI 将它们整理成清晰笔记的跨平台应用"。它的设计有一个很明确的出发点：

一个想法刚出现时，可能只有一句话、一段录音、一张截图，或者一个暂时没时间阅读的链接。保存它们之前，你不必先想好标题、目录和文章结构。

因此在 NoteGen 中，**记录（Capture）与整理（Organize）**是明确分开的两个阶段：

• 记录阶段：任何素材出现时，先以最低成本把它保存下来，不打断当下的思路；
• 整理阶段：当素材积累到一定程度，按标签、时间、类型筛选出属于同一主题的记录，再通过模板或自然语言描述生成结构化的 Markdown 笔记；
• 写作阶段：AI 生成的只是草稿，你可以在编辑器中继续修改、补充、调整结构，最终产物是一篇完全可编辑的 Markdown 文档。

官方对 AI 的角色定义得很克制："AI 不是来替你写完一切，而是帮助那些零散但有价值的内容，在被遗忘之前变成一篇完整的笔记"、"AI 是写作过程中的工具，不是最终作者"。

二、NoteGen 如何工作：四条核心工作流

README 给出了从记录到成稿的完整工作流，这也是理解整个项目结构的主线：

1. 先把内容记录下来：随手记下一句话、录一段声音、保存截图、图片、链接、文件或待办事项；
2. 挑选真正相关的材料：按标签、时间或类型筛选记录，把属于同一主题的内容选出来；
3. 把记录整理成笔记：选择模板，或直接描述你想写什么，NoteGen 根据选中的材料生成总结、报告、文章或其他结构化内容；
4. 继续完成自己的写作：在编辑器中检查、修改和补充，最终文件是自由编辑的 Markdown 文档。

2.1 记录类型：源码中的 Mark 数据模型

"记录"在源码中的核心类型为Mark，定义在 src/db/marks.ts，其type字段明确支持七种记录形态：

MARK_TYPE_OPTIONS常量（src/app/core/main/mark/mark-type-meta.ts）完整枚举了这七种类型，Mark接口还带有tagId、tagIds、content、desc、url、deleted、createdAt、sourceId等字段，说明每条记录天然携带标签、内容描述、创建时间和来源信息——这些字段正是后续"按标签/时间/类型筛选"的基础。在界面上，记录入口也一一对应：control-text.tsx（文字）、control-recording.tsx（录音）、control-scan.tsx（扫描/OCR）、control-image.tsx（图片）、control-link.tsx（链接）、control-file.tsx（文件）、control-todo.tsx（待办），源码目录位于 src/app/core/main/mark。

2.2 筛选逻辑：标签、时间、类型的组合过滤

README 强调"按标签、时间或类型筛选记录"。这套筛选逻辑在 src/app/core/main/mark/mark-filters.ts 中有完整实现：

• 类型筛选：selectedTypes对七种记录类型做白名单过滤（VALID_TYPES）；
• 时间预设：timePreset支持all（全部）、today（今天）、last7Days（最近 7 天）、last30Days（最近 30 天）四种时间范围，通过matchesTimePreset按记录的createdAt判断；
• 搜索：在content、desc、url三个字段上做大小写不敏感的包含匹配（matchesSearch）；
• 标签：支持精确标签与标签规则（tagRules）组合过滤，recordMatchesTag与matchesTagRules来自 src/lib/record-tags.ts。

此外sortMarks支持按最新、最旧、类型三种排序方式。这些能力共同支撑了"过滤最近一周的记录、按标签准备周报"等真实使用场景。

2.3 整理成笔记：模板与自由描述

"选择模板，或直接描述你想写什么"对应的是整理笔记对话框（Organize Notes）。其核心实现位于 src/app/core/main/mark/organize-notes.tsx，流程拆为template→records→settings三步：

• 支持选择 GenTemplate 模板或指定整理范围（GenTemplateRange，常量定义见 src/stores/setting.ts）；
• 标题会经过sanitizeMarkdownTitle清洗（将\/\\:*?"<>|替换为下划线，长度限制 50 字符），输出路径通过buildOutputPath拼接，避免生成非法文件名；
• ensurePreferredHeading会确保生成文档以所选标题作为一级标题开头；
• 整理结果最终调用fetchAiStream（src/lib/ai/chat.ts）以流式方式从你配置的 AI 模型获取生成内容，再写入工作区中的 Markdown 文件。

三、以普通 Markdown 文件为基础：不锁死任何数据

NoteGen 的一个核心承诺是"你的笔记以普通 Markdown 文件保存在自己选择的工作区中"。这意味着：你可以用 NoteGen 编辑，也可以用任何其他 Markdown 编辑器打开；可以放进 Git 管理版本，可以自由复制、迁移和备份，不需要从专有格式导出。

编辑器能力清单（README 原文）包括：

• 表格、任务列表、代码块、数学公式、图表和文章大纲
• Markdown 源码模式与可视化编辑
• 文本查找与替换
• 图片、附件、链接和文件引用
• 导出与打印
• 文件历史和工作区管理

从源码看，这些能力有扎实的实现支撑：编辑器基于 TipTap 3.19 构建（package.json 中包含了@tiptap/extension-table、@tiptap/extension-task-list、@tiptap/extension-code-block、@tiptap/extension-highlight、@tiptap/markdown等一整套扩展），数学公式与图表分别由katex、mermaid支持，代码高亮由shiki、lowlight支持，还引入了yjs与@tiptap/extension-collaboration（协作编辑基础设施）。编辑器的具体界面代码位于 src/app/core/main/editor，共包含 47 个.tsx与 29 个.ts文件，覆盖编辑器的完整功能面。

四、在需要时使用 AI：可自由配置的模型体系

NoteGen 不绑定任何单一 AI 服务商，而是"连接你自己配置的 AI 服务与模型"。README 明确列出了可按需分别指定模型的六类任务：

• 聊天（Chat）：围绕笔记、记录、图片和知识库进行对话；
• 写作（Writing）：续写、缩写、扩写、润色或翻译已有内容；
• 嵌入（Embedding）：为知识库建立向量索引；
• 图片识别（VLM）：视觉理解与图片问答；
• OCR：扫描记录的文字识别；
• 音频（Audio）：录音转写、语音识别与语音合成。

4.1 模型配置的源码实现

模型配置的核心链路在 src/lib/ai/utils.ts：getAISettings(modelType)从本地存储store.json读取对应任务类型的模型 ID，再通过getAISettingsByModelId在aiModelList配置列表中解析出model、temperature、topP、maxTokens、contextWindow、enableStream等运行时参数。请求层使用 OpenAI SDK 兼容协议（src/lib/ai/chat.ts 中的fetchAi/fetchAiStream），因此任何兼容 OpenAI 接口的厂商服务都能接入，同时通过tauri-client.ts提供统一的客户端创建与容错逻辑。

4.2 默认模型与远端策略

仓库 config/notegen-default-models.json 给出了内置默认模型示例：

{ "models": [ { "id": "note-gen-chat", "model": "Qwen/Qwen3-8B", "modelType": "chat", "temperature": 0.7, "topP": 1, "enableStream": true }, { "id": "note-gen-embedding", "model": "BAAI/bge-m3", "modelType": "embedding" }, { "id": "note-gen-vlm", "model": "Qwen/Qwen3.5-4B", "modelType": "chat" } ] }

可以看到默认配置按"聊天、嵌入、视觉"三类任务分别指定模型。这些内置默认值、厂商模板与模型策略会通过 config/config-manifest.json 中登记的远端清单定期更新（provider-templates、provider-templates-cn、notegen-model-policy、notegen-default-models 四个配置源），客户端从download.notegen.top/config/v1/拉取并本地缓存，运行时逻辑见 src/lib/ai/provider-templates-runtime.ts 与 src/lib/ai/notegen-default-models-runtime.ts。

4.3 AI 在 NoteGen 中的具体用途

README 列出的 AI 应用场景包括：把选中的记录整理成结构化笔记；续写、缩写、扩写、润色或翻译已有内容；围绕笔记、记录、图片和知识库进行对话；回答问题前先检索本地材料；根据笔记内容生成图表和画布；使用 Agent 模式处理更长的任务。

其中"Agent 模式"在仓库中有完整的基础设施：src/lib/agent/目录下包含会话管理（agent-session.ts）、权限引擎（permission-engine.ts）、工具注册表（tool-registry.ts）、提示词组装（prompt-assembler.ts）以及一系列面向笔记、记录、标签、文件夹、画布、知识库、图片的工具定义（见 src/lib/agent/tools），说明 Agent 可以基于本地内容执行多步骤的长任务。

五、让写过的内容重新派上用场：本地知识库与混合检索

README 提出的理念是"很多笔记完成后，就再也没有被打开过"，因此 NoteGen 可以为工作区中的文件建立可搜索的知识库，把语义检索和本地文本搜索结合起来。发起对话时，可以引用一篇笔记、一组记录或整个知识库，不必反复复制原文。

5.1 知识库检索的源码实现

知识库的语义检索链路集中在 src/lib/knowledge-search.ts：

• mode支持rag（混合检索）与keyword（纯关键词）两种模式；
• 检索来源（KnowledgeSourceType）包括文章（article）、记录（record）、画布（canvas）三类，默认权重配比为article: 0.6 / record: 0.25 / canvas: 0.15；
• 通过fetchEmbedding计算查询向量、getSimilarDocuments做向量相似检索、BM25 做关键词检索，最后用rerankDocuments重排序，实现真正的混合检索；
• 检索后会按权重混合多种来源的结果，供对话上下文使用。

对应的向量数据层在 src/db/vector.ts，本地文本索引（BM25）在 src/lib/bm25.ts，知识库设置项见 src/lib/knowledge-settings.ts，RAG 检索策略可在 src/lib/rag-retrieval-policy.ts 中看到详细的策略实现。

5.2 进阶能力清单

README 明确列出的进阶工作流能力包括：

• 向量索引与混合检索
• 自定义嵌入和重排序模型
• 长期记忆与可复用提示词
• MCP 服务
• 可安装的 Skills
• 用于处理笔记和文件的 Agent 工具

这些能力在仓库中均有对应实现：MCP 客户端与服务器管理见 src/lib/mcp（含 client.ts、server-manager.ts、tools.ts），Skills 的创建、校验、运行与卸载见 src/lib/skills，长期记忆见 src/lib/memory/auto-memory.ts，可复用提示词通过promptList存储在本地store.json中（见 src/lib/ai/utils.ts）。

六、不只适合线性文档：画布工作区

"有些内容用文章表达很清楚，有些内容更适合画出来。"NoteGen 提供独立的画布工作区，可创建和编辑：流程图、思维导图、时间线、自由绘制内容、数据图表、以及根据笔记生成的可视化结构。关键设计是：AI 生成的画布不会变成一张无法修改的图片，其中的节点、文字和连线仍然可以继续编辑。

画布模板在 src/lib/canvas/templates.ts 中有具体定义：流程图（FLOWCHART）、思维导图（MINDMAP）、时间线（TIMELINE）、四象限（QUADRANT）等模板以CanvasDocument结构描述节点（nodes）、连线（edges）与视口（viewport），例如思维导图模板定义了"中心主题 + 分支一/二/三"的节点布局。画布的其余能力分散在 src/lib/canvas 下的 operations、shapes、chart-data、mermaid、freehand 等模块中，画布页面入口位于 src/app/core/main/canvas。

七、按自己的方式同步：本地优先 + 多服务商

笔记默认保存在本地。需要跨设备使用时，可以自选信任的服务同步。README 列出的支持范围包括：

以上六种服务在 src/lib/sync 目录下均有独立实现模块：github.ts、gitlab.ts、gitee.ts、gitea.ts、s3.ts、webdav.ts，并配有各自的类型定义（如 github.types.ts、gitlab.types.ts、gitea.types.ts）。同步调度由 sync-manager.ts 与 sync-push-queue.ts 负责，文件夹级同步与冲突处理见 folder-sync.ts 与 conflict-resolution.ts。不使用云同步时，也可以关闭云同步、仅依靠本地备份保存数据（备份实现见 src/lib/backup/managed-backup.ts 与 src-tauri/src/backup_manager.rs）。

另外，项目还提供了自托管同步服务相关代码（src/lib/self-hosted-sync），对应仓库生态中的 note-gen-server（同步服务与账号管理，支持自行部署）。

八、下载与平台支持

README 给出的平台支持状态如下：

应用本体基于 Tauri 2 构建，桌面端配置见 src-tauri/tauri.conf.json：应用标识为com.codexu.NoteGen，主窗口默认尺寸 1360×720，支持md/markdown文件关联（可直接用 NoteGen 打开 Markdown 文档），内置 deep-link（notegen://协议）与自动更新通道。前端基于 Next.js 15 与 React 19，开发模式通过pnpm dev在http://localhost:3456启动（见 package.json）。

以上"当前状态"（Beta/Alpha）以 README 表格原文为准，具体下载入口请以 notegen.top 官网的 download 页面为准。

九、开始使用：五分钟上手

README 给出了最简单的上手路径，你不需要先完成所有配置才能开始写第一篇笔记：

1. 根据你的系统下载 NoteGen；
2. 选择一个目录作为 Markdown 工作区；
3. 添加第一条记录，或者直接创建一篇笔记；
4. 需要使用 AI 功能时，再配置相应的模型服务；
5. 需要更多能力时，再阅读官方文档了解同步、知识库、MCP、Skills 和其他设置。

想从源码构建时，项目根目录提供了完整的前后端工程：package.json（前端依赖与脚本）、src-tauri/Cargo.toml（桌面端 Rust 后端）、src-tauri/tauri.conf.json（Tauri 应用配置）。安装依赖后依次执行pnpm dev即可进入开发模式。

十、一些真实的使用方式

README 描述了几种典型的落地场景，可作为你配置工作流的起点：

• 开会时记录几句话、录一段音、截两张图，会后统一整理成会议纪要；
• 阅读时先保存链接和零散摘录，周末再把它们整理成一篇主题笔记；
• 按标签筛选最近一周的记录，快速准备周报或工作总结；
• 围绕一个主题收集图片和文档，再基于这些材料提问和写作。

正如官方总结的那样："记录不是一篇没写完的笔记。它更像写作之前的原材料。"

十一、开源协议与仓库生态

NoteGen 采用 GNU General Public License v3.0 开源。围绕主仓库还形成了完整的周边生态，README 中列出的关联仓库包括：note-gen-docs（官网与双语文档）、note-gen-server（同步服务与账号管理，支持自行部署）、note-gen-clipper（浏览器剪藏扩展，可将选中文字、图片和网页链接保存到 NoteGen）、note-gen-plugin-sdk（插件开发的 TypeScript API、脚手架、CLI 与测试工具）、note-gen-plugins（官方插件源码与插件市场发布工具）。

项目本身对插件与扩展体系也有深厚的源码支撑：插件运行时（src/lib/plugins/runtime）基于 QuickJS 沙箱（@jitl/quickjs-singlefile-browser-release-sync，见 package.json），插件宿主 API 与 UI 注册见 src/lib/plugins 及 src/components/plugins，从编辑器工具栏、文件菜单、状态栏到命令面板都有对应的插件扩展点。

结语

NoteGen 的价值主张并不复杂：用最低的摩擦收集素材，用 AI 把它们组织成可编辑的 Markdown，然后用普通文件格式保住你对数据的长期所有权。从仓库源码看，"本地优先 + 开放格式 + 可插拔 AI + 自选同步"是一条贯穿始终的主线——记录模型（Mark）、整理流程（Organize）、知识库检索（RAG）、画布、MCP 与 Skills 生态，每一环都有独立的模块化实现，适合作为研究"AI 笔记工具"架构的参考项目，也适合作为日常记录与写作的实际工具上手体验。

• AI 应用
• RAG
• 桌面应用
• 前端