企业官网建设流程全解析

• AI 应用
• 桌面应用
• 移动开发
• 知识管理

导读

NoteGen 是一款本地优先、以 Markdown 文件为核心的跨平台笔记应用，核心设计理念是"先记录，再整理"（Capture first. Organize later.）：有内容时先以最轻量的方式留下来，需要时再借助 AI 把零散记录整理成结构清晰的笔记。本文以仓库中的 README.zh-CN.md 为骨架，结合 src/、config/ 等目录下的真实源码实现，从记录体系、编辑器、AI 与模型配置、知识库检索、画布工作区、多端同步六个维度展开，读者将掌握 NoteGen 的设计思路、功能边界与源码级工作原理，并可直接上手安装、配置与日常使用。

NoteGen 的技术栈以 Next.js 15 + React 19 + Tauri 2 构建桌面与移动端（见 package.json），编辑器基于 TipTap 3.19 与 CodeMirror，画布基于 @xyflow/react，AI 层通过 OpenAI 兼容协议连接可自配模型。以下内容均以当前仓库实际代码为准。

核心理念：把"记录"和"整理"拆成两个阶段

README 开篇就点明了产品哲学：一个想法刚出现时，往往只有一句话、一段录音、一张截图，或者一个暂时没时间读的链接。此时要求用户先想好标题、目录和文章结构，是对创作冲动最大的损耗。

因此 NoteGen 将写作过程拆为两个独立阶段：

• 记录阶段：有内容时先把它留下来，不需要任何结构设计；
• 整理阶段：需要时选出属于同一主题的记录，组织成一篇结构清楚的 Markdown 笔记，再继续修改、补充。

在源码中，记录与整理是两套独立的模块。记录侧位于 src/app/core/main/mark/，其中control-*.tsx系列组件分别对应文本（control-text.tsx）、链接（control-link.tsx）、图片（control-image.tsx）、录音（control-recording.tsx）、扫描（control-scan.tsx）、待办（control-todo.tsx）和剪贴板（clipboard.tsx）等记录入口；整理侧则通过organize-notes.tsx组件把选中的记录送入 AI 生成结构化笔记。这与 README 中"记录不是一篇没写完的笔记，它更像是写作之前的原材料"的表述完全一致。

NoteGen 如何工作：四步工作流

README 给出了完整的工作流程，从仓库代码可以逐条印证其落地形态：

1. 先把内容记录下来：随手记一句话、录一段音、保存截图、图片、链接、文件或待办事项。对应mark目录下control-*系列记录控件，以及 src/lib/web-capture/ 中的网页内容提取服务。
2. 挑选真正相关的材料：按标签、时间或类型筛选记录。筛选逻辑实现在 src/app/core/main/mark/mark-filters.ts，标签管理在 src/app/core/main/mark/tag-manage.tsx，记录类型元数据定义在 src/app/core/main/mark/mark-type-meta.ts。
3. 把记录整理成笔记：选择模板，或直接描述想写什么，AI 基于选中材料生成总结、报告、文章等结构化内容。入口为 src/app/core/main/mark/organize-notes.tsx。
4. 继续完成自己的写作：在编辑器里检查、修改、补充。AI 生成的是草稿，最终产物仍是一篇可自由编辑的 Markdown 文档（编辑器实现见下文）。

四个步骤共同支撑起 README 中的真实使用场景：开会时记录几句话、录一段音、截两张图，会后统一整理成会议纪要；阅读时先保存链接和摘录，周末整理成主题笔记；按标签筛选最近一周的记录快速准备周报；围绕一个主题收集图片和文档，再基于这些材料提问和写作。

以普通 Markdown 文件为基础：编辑器与工作区

README 强调"完成的笔记会以普通 Markdown 文件保存在自己选择的工作区中"，可以继续用 NoteGen 编辑，也可以用其他 Markdown 编辑器打开，放进 Git、复制、迁移和备份，无需从专有格式导出。这正是 src/lib/markdown.ts、src/lib/markdown-file-link.ts 与 src/lib/files.ts 等文件管理模块存在的意义：NoteGen 是在文件之外补充记录、AI、搜索和整理能力，而不是把笔记锁进某个平台。

编辑器支持的能力在源码中均有对应实现，核心模块位于 src/app/core/main/editor/：

值得一提的细节：工作区主界面采用可拖拽的三栏布局（左侧记录/标签栏、中间编辑器、右侧扩展栏），默认尺寸与各面板最小宽度定义在 src/app/core/main/page.tsx，包括左栏最小 320px、右栏最小 280px、编辑器最小 400px 的约束，布局记忆通过react-resizable-panels持久化。

在需要时使用 AI：模型体系与配置

README 说明 NoteGen "可以连接你自己配置的 AI 服务与模型。聊天、写作、嵌入、图片识别、OCR 和音频任务可以分别选择模型"。这一点在源码中体现得相当完整。

按任务类型拆分模型

从 src/app/model-config.ts 可以看到，模型的modelType字段区分了chat（对话/写作）、embedding（向量嵌入）、stt（语音转文字）等类型；配置样例中甚至出现了note-gen-vlm（视觉语言模型）的键名。这意味着：

• 主对话、快速补全、写作、知识库嵌入、图片识别、OCR、语音任务都可以指向不同的模型服务；
• AI 能力调用集中在 src/lib/ai/ 目录，其中 chat.ts、completion.ts、embedding.ts、translate.ts、rewrite.ts、description.ts、image-recognition.ts 与 src/lib/ocr.ts 分别对应各类任务。

内置默认模型配置

仓库config目录提供了开箱即用的模型清单，也是理解模型配置格式的最佳样例：

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/notegen-model-policy.json 则定义了 NoteGen 内置免费/限量模型的策略：limited档使用gpt-6-luna（每日请求上限 200 次），free档使用Qwen/Qwen3-8B。这些配置文件通过 config/config-manifest.json 声明版本号与远端下载地址，由 src/lib/ai/notegen-default-models-runtime.ts 和 src/lib/ai/notegen-model-policy.ts 在运行时加载，实现配置热更新。若想接入自己的服务，只需在设置中按同样的apiKey / baseURL / models[]结构添加自定义 Provider 即可。

AI 能做什么

README 列出的 AI 能力在源码中均可找到落点：

• 把选中的记录整理成结构化笔记：src/app/core/main/mark/organize-notes.tsx；
• 续写、缩写、扩写、润色或翻译：src/lib/ai/rewrite.ts、src/lib/ai/translate.ts、src/lib/ai/condense.ts；
• 围绕笔记、记录、图片和知识库对话：src/lib/ai/chat.ts、src/lib/chat-attachments.ts、src/lib/chat-image-context.ts；
• 回答问题前先检索本地材料：见下一节知识库；
• 根据笔记生成图表和画布：src/lib/canvas/ 下的chart-data.ts、mermaid.ts与 AI 输出解析逻辑；
• 使用 Agent 模式处理更长任务：src/lib/agent/ 目录。

README 特别强调："AI 是写作过程中的工具，不是最终作者。"生成结果可以继续修改，不满意的内容可以直接删掉——这与"普通 Markdown 文件为基础"的定位互为表里。

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

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

知识库检索的主入口是 src/lib/knowledge-search.ts 的searchKnowledge函数，底层依赖 src/lib/knowledge-index.ts、src/lib/knowledge-content.ts、src/lib/bm25.ts 与 src/lib/vector.ts 组成的索引体系。README 提到的高级工作流，在仓库中对应如下模块：

值得一提的是，MCP 还提供了本地桥接实现（src/components/local-mcp-bridge.tsx），Skills 则带有独立运行时（src/lib/skills/runtime.ts），可以按需扩展检索与自动化能力。

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

有些内容用文章表达清楚，有些则更适合画出来。NoteGen 提供独立的画布工作区，支持流程图、思维导图、时间线、自由绘制、数据图表，以及由笔记生成的可视化结构。画布模块位于 src/lib/canvas/：

• 流程图 / 思维导图：底层为 @xyflow/react 节点编辑器（见 package.json 中@xyflow/react依赖），并提供 mermaid.ts 在 Mermaid 文本与画布结构之间转换；
• 时间线 / 自由绘制：freehand.ts（基于 perfect-freehand 实现手绘笔迹）；
• 数据图表：chart-data.ts 定义 AI 生成图表的 schema（最多 8 个图表），chart-appearance.ts 负责配色等外观；
• 由笔记生成：AI 产出结构化描述后，通过 templates.ts 与operations.ts落成画布节点。

README 强调"AI 生成的画布不会变成一张无法修改的图片，其中的节点、文字和连线仍然可以继续编辑"，这是因为画布本身就是结构化节点数据（file-format.ts 定义了持久化格式），而非位图。

按自己的方式同步：多端多平台

笔记默认保存在本地，需要跨设备时可以选择自己信任的服务。README 列出六种同步后端，源码中均有独立实现：

以 GitHub 为例，src/lib/sync/github.ts 提供了uploadFile、getFiles、deleteFile、getFileCommits、checkSyncRepoState、createSyncRepo等完整 API，覆盖了从鉴权、建仓到文件增删改查的完整链路；src/lib/sync/provider-status.ts 则统一封装了各平台（github / gitee / gitlab / gitea）的连接检测与仓库状态检查，配合 src/lib/sync/sync-manager.ts、src/lib/sync/auto-sync.ts 实现自动同步、冲突解决与提交信息生成（src/lib/sync/commit-message.ts）。

不使用云同步时，本地备份同样可行：src/lib/backup/managed-backup.ts 与 src-tauri/src/backup.rs、src-tauri/src/backup_manager.rs 构成了备份体系。此外，同步面板还支持 OneDrive 工作区（src/lib/sync/onedrive.ts）与自托管同步服务（src/lib/self-hosted-sync/），README 中的"相关仓库"也提到独立的 note-gen-server 同步服务仓库支持自行部署。

下载与平台状态

README 给出的各平台当前状态如下（具体安装包请前往项目官网下载页获取）：

从仓库看，多端构建均有对应配置：src-tauri/tauri.conf.json（桌面主配置）、src-tauri/tauri.ios.conf.json（iOS）、src-tauri/ios-project.yml（iOS 工程）、src-tauri/tauri.macos-app-store.conf.json（macOS App Store），且 src-tauri 目录同时包含 Android（native-android/）与 iOS（native-ocr/ios-vision/）的原生代码，印证了 README 中 Windows/macOS/Linux/Android/iOS 五端并进的规划。Rust 工具链版本由 rust-toolchain.toml 锁定。

开始使用

README 给出的上手路径非常轻量，无需先完成所有配置就能写第一篇笔记：

1. 根据自己的系统下载安装 NoteGen；
2. 选择一个目录作为 Markdown 工作区；
3. 添加第一条记录，或者直接创建一篇笔记；
4. 需要使用 AI 功能时，再配置相应的模型服务（可在设置中接入自己的 OpenAI 兼容服务，或使用内置默认模型）；
5. 按需了解同步、知识库、MCP、Skills 等高级设置。

如需从源码构建，仓库 package.json 提供了完整的脚本：pnpm dev以 Turbopack 在 3456 端口启动前端开发服务器，pnpm build执行生产构建（构建前会自动打包插件运行时plugin-runtime:build并清理 sourcemap），pnpm tauri进入 Tauri 命令。克隆仓库后依次执行pnpm install、pnpm dev即可在本机运行。需要注意的是，前端构建依赖pnpm包管理器与 Node 环境，桌面端打包依赖 Rust/Tauri 工具链。

延伸阅读：仓库生态

README 的"相关仓库"一节介绍了围绕 NoteGen 的完整生态，均可在对应的开源仓库中进一步研究：

此外，本仓库以 GPL v3.0 协议开源（见 LICENSE），贡献前可参考 scripts/ 中的插件契约与插件市场公钥检查脚本，了解项目对插件生态的规范化管理。

结语

NoteGen 的全部核心能力——四步记录整理工作流、Markdown 文件本位、按任务拆分的 AI 模型体系、知识库混合检索、可编辑画布、六种以上同步后端——都能在仓库源码中找到一一对应的实现模块。它把"记录"与"整理"明确分层：记录侧追求零摩擦，整理侧借助 AI 和模板高效产出，最终成果始终是可自由迁移的普通 Markdown 文件。对于希望研究本地优先 + AI 笔记应用架构的开发者，src/app/core/main（界面层）、src/lib（业务层）与 src-tauri/src（原生层）三层结构是清晰的学习范本。

• AI 应用
• 桌面应用
• 移动开发
• 知识管理