Skip to content
yuhang234Public

About

基于 Tauri 2 + Rust + React 的本地优先 Markdown 桌面笔记软件。以 .md 文件为权威数据源,支持 SQLite FTS5 全文检索、多维时间线/日历/地图视图与完整离线运行。

Resources

Stars

0 stars

Watchers

0 watching

Forks

Repository files navigation

NoteFlow:本地优先 Markdown 桌面笔记系统

🚀 NoteFlow 是一款基于 Tauri 2 + Rust + React 19 + TypeScript 构建的本地优先(Local-First)桌面笔记软件。以纯本地 .md 文件为唯一权威数据源,支持完全离线运行、SQLite FTS5 全文索引、双栏实时渲染与多维知识管理。


📸 软件运行效果展示 (Screenshots)

1. 专注编辑与实时渲染(双栏模式)

支持 CodeMirror 6 源码编辑、Markdown 标题层级排版(H1~H6)、LaTeX 数学公式离线渲染、本地 Mermaid 图表、软换行支持、实时保存状态徽标与 Ctrl+S 快捷键即时持久化。

双栏 Markdown 编辑与实时渲染

2. 笔记列表与多维时间线

提供多列瀑布流与卡片阅读视图,支持固定笔记置顶、多层级标签过滤(如 #架构/本地优先、#技术/Rust)、日期分组与表情反应记录。

笔记列表与多维时间线

3. 本地附件媒体库

集中管理图片、PDF 文档与多媒体资源,支持外部文件拖拽上传、剪贴板截图直接按 Ctrl+V 粘贴上传、按格式类型分类过滤与一键复制 Markdown 引用。

本地附件媒体库

4. 月度日历与日期视图

按月直观呈现笔记发布分布,点击任意日期即时定位并回溯当日创建或编辑的笔记记录。

月度日历视图

5. 知识库数据统计看板与活跃度热力图

实时统计笔记总数、任务数、代码块、外链数及附件占用空间,内置近 120 天写作习惯与活跃度贡献热力图。

知识库统计看板与热力图


一、项目定位与总体目标

请从零开发一款名为 NoteFlow 的 Windows 桌面笔记软件。

这是一款以快速记录、Markdown 文件存储、全文检索、时间线浏览和个人知识整理为核心的本地优先笔记应用。

本项目不是简单的文本编辑器,也不是套上桌面外壳的网页,而是一款具备完整笔记管理能力、可靠本地存储能力和良好用户体验的独立桌面软件。

1.1 必须实现的核心目标

  1. 完全本地化运行。安装后无需部署服务器、安装 Docker、配置数据库或注册在线账号。
  2. 每条笔记必须对应一个真实的 .md 文件。文件内容可以直接使用 VS Code、Obsidian、记事本等外部工具打开和编辑。
  3. Markdown 文件是笔记内容的唯一权威数据源。数据库仅允许存储可以删除和重新生成的索引、缓存及派生信息。
  4. 保留完整的笔记管理、搜索、标签、时间线、日历、地图、附件、关联、统计、评论、视图和个性化设置能力。
  5. 支持断网使用。核心功能不得依赖在线 API、云数据库、远程服务器或 CDN。
  6. 充分利用 Windows 桌面能力,包括系统托盘、全局快捷键、文件拖放、剪贴板、原生文件对话框和开机启动选项。
  7. 所有个人数据均由用户控制,能够随时复制、备份、迁移和恢复。
  8. 界面使用简体中文作为默认语言,同时具备国际化基础架构。

1.2 强制执行的开发约束

必须在独立的 NoteFlow 项目目录中,从空白工程开始开发。

不得将任何其他现成笔记软件的代码仓库作为工作区、底层工程或改造起点;不得通过克隆、下载或修改已有项目来完成本任务。不得为了节省时间而直接复制其他软件的业务实现。

所有功能都应根据本需求重新设计数据结构、交互逻辑和实现代码。

不接受只有静态页面的 Demo,不接受用模拟数据代替文件读写,不接受通过隐藏按钮或删除功能降低工作量。必须交付能够实际运行、真实保存数据并通过验收测试的软件。

二、明确技术栈

采用以下技术方案,不要在没有充分理由的情况下随意更换核心架构。

2.1 桌面应用与后端

  • 桌面框架:Tauri 2。
  • 后端语言:Rust,负责文件系统、Markdown 读写、索引管理、文件监控、备份恢复、附件管理和本地系统集成。
  • 桌面平台:优先保证 Windows 10/11 环境。
  • 本地数据接口:通过 Tauri Commands 在前端与 Rust 后端之间通信,不需要单独部署 HTTP 服务器。
  • 文件监控:使用 Rust 文件系统监控能力,识别外部创建、修改、移动和删除的笔记。
  • 配置格式:使用 JSON 或 YAML 文件保存非笔记类应用配置。

2.2 前端界面

  • UI 框架:React。
  • 编程语言:TypeScript。
  • 构建工具:Vite。
  • 样式方案:Tailwind CSS。
  • 组件方案:shadcn/ui 与 Radix UI。
  • 图标:Lucide。
  • 状态管理:Zustand;异步本地命令可以使用 TanStack Query 管理缓存和加载状态。
  • 测试:Vitest、React Testing Library、Playwright。

界面需要统一设计规范,包括颜色、间距、字体、边框、阴影、弹窗、菜单、快捷键提示、加载状态、空状态和错误提示。

2.3 Markdown 编辑与渲染

  • 编辑器:CodeMirror 6,支持原始 Markdown 文本编辑、语法装饰、快捷键和代码高亮。
  • Markdown 解析:unified、remark、rehype 生态。
  • 扩展语法:remark-gfm、remark-math。
  • 数学公式:KaTeX。
  • 流程图与图表:Mermaid。
  • 代码高亮:Shiki 或同类本地化语法高亮方案。
  • HTML 安全处理:采用 HTML 清理和严格的内容安全策略,禁止笔记中的脚本直接执行。

所有必需资源应打包到应用内。不得在启动时从第三方 CDN 下载编辑器、图标、字体或渲染组件。

2.4 本地搜索与索引

使用 SQLite FTS5 实现全文检索和搜索加速。

严格区分两种数据:

  • 权威数据: 笔记 .md 文件及其本地附件。
  • 派生数据: SQLite 搜索索引、缓存、统计结果和可重新计算的辅助信息。

删除 SQLite 索引后,应用必须能够通过扫描 Markdown 文件和解析配置重新生成索引。不得把笔记正文、唯一版本的元数据或唯一的笔记关系只保存在数据库中。

2.5 Rust 组件建议

根据需要采用以下组件或功能等价的成熟依赖:

  • serde、serde_json、serde_yaml:数据序列化与 Front Matter 解析。
  • chrono 或 time:日期和时间处理。
  • uuid:生成稳定的笔记标识。
  • notify:文件变化监控。
  • walkdir:目录扫描。
  • rusqlite:SQLite 索引读写。
  • zip:归档导入与导出。
  • image:图片处理与缩略图。
  • EXIF 解析组件:可选媒体元数据读取。

具体依赖版本需要锁定,并确保 Windows 环境可以重复构建。

三、数据目录与存储规范

3.1 默认目录结构

首次启动时创建一个用户可见、可更改位置的数据目录。默认位置可以放在用户文档目录下,不应将主要笔记数据隐藏在程序安装目录中。

推荐结构:

NoteFlowVault/
├── notes/
│   ├── 550e8400-e29b-41d4-a716-446655440000.md
│   └── 7b5c72ce-4c6f-4cbe-918f-85f6c09eac10.md
├── attachments/
│   ├── 550e8400-e29b-41d4-a716-446655440000/
│   │   ├── screenshot.png
│   │   └── document.pdf
│   └── 7b5c72ce-4c6f-4cbe-918f-85f6c09eac10/
├── drafts/
├── trash/
├── backups/
└── .noteflow/
    ├── config.json
    ├── workspaces.json
    ├── views.json
    ├── tag-settings.json
    ├── index.sqlite
    └── logs/

目录名称可以在实现时调整,但不得改变核心原则:每条正式笔记均有独立的 .md 文件,附件存储在本地,索引能够重新生成。

3.2 笔记文件格式

每个 Markdown 文件采用标准 Markdown 正文,并使用 YAML Front Matter 保存必要的元数据。

例如:

---
id: "550e8400-e29b-41d4-a716-446655440000"
type: "note"
created_at: "2026-10-11T09:30:00+08:00"
updated_at: "2026-10-11T10:15:00+08:00"
pinned: false
archived: false
workspace_id: "default"
location: null
relations: []
parent_id: null
reactions: []
---

# 今天的学习记录

今天研究了 Agent 的工具调用机制。

## 需要完成的工作

- [x] 完成项目结构分析
- [ ] 实现本地 Markdown 存储
- [ ] 验证文件监控功能

继续记录正文。

#学习 #项目/开发

字段要求:

  • id:全局唯一且永久稳定的笔记 ID。
  • type:记录类型,至少支持普通笔记和评论。
  • created_at、updated_at:支持带时区的 ISO 8601 时间。
  • pinned:固定状态。
  • archived:归档状态。
  • workspace_id:所属工作区,可以为空。
  • location:可选位置元数据。
  • relations:关联笔记 ID 列表。
  • parent_id:评论等子记录的关联目标。
  • reactions:本地表情反应记录。

实际实现可增加版本号、来源 URL、媒体绑定信息等字段。

解析和保存 Front Matter 时,必须保留用户手工填写的未知字段,不能因为编辑器不认识某个字段就将其删除。

标签优先从正文中的 #标签 提取;搜索索引和标签树由正文重新计算。标签颜色、模糊显示规则和其他个人偏好保存在配置文件中。

3.3 文件命名与引用

  1. 创建笔记时生成 UUID。
  2. 默认文件名使用 UUID,避免标题重复、中文文件名转义和重命名导致的引用错误。
  3. 笔记可以在应用中显示标题,但不得要求文件名必须等于标题。
  4. 文件名发生变化时,依靠 Front Matter 中的 ID 识别同一笔记。
  5. 附件使用稳定的本地相对路径引用,整个数据目录移动到另一台电脑后仍能解析。
  6. 内部关联不得依赖数据库自增 ID 或电脑上的绝对路径。

默认附件路径可以采用 ../attachments/{note_id}/filename。所有移动操作都必须检查引用是否需要更新。

3.4 保存可靠性

每次新建笔记都必须真正创建 .md 文件。修改正文或元数据时,必须将最新版本写回磁盘。

保存机制必须具有以下特征:

  • 编辑器显示明确的保存中、已保存和保存失败状态。
  • 采用临时文件写入后原子替换的方式降低文件损坏风险。
  • 保存失败时保留编辑器内的内容,不允许静默丢弃。
  • 只有真实写入成功后,才能显示保存成功。
  • 自动保存应设置合理的防抖时间,但关闭窗口或退出应用时必须处理尚未完成的写入。
  • 错误信息应告诉用户如何恢复、重试或更换目录。

四、桌面主界面与导航

4.1 整体布局

采用清晰、安静、适合长时间使用的三层桌面布局:

  1. 左侧可调节宽度的导航栏。
  2. 中间笔记列表或工作区域。
  3. 需要时显示笔记详情、属性栏或关联面板。

允许根据页面自动调整布局,避免在小窗口中挤压编辑器。

整体视觉参考现代桌面生产力工具,强调排版、留白、清晰的层次和高效操作。不要使用过度渐变、大量卡片边框或无意义动画。

4.2 侧边栏模块

至少包含以下入口:

  • 时间线。
  • 日历。
  • 地图。
  • 收藏视图。
  • 标签树。
  • 快速查找。
  • 附件库。
  • 归档记录。
  • 统计面板。
  • 工作区切换。
  • 全局新建笔记按钮。
  • 设置。
  • 关于及版本信息。

支持收起侧边栏、调整宽度、记住布局,以及在不同页面之间切换时保留当前筛选状态。

4.3 全局操作

用户无论处于哪个页面,都应该可以快速创建笔记、搜索笔记和访问最近编辑内容。

提供:

  • 全局新建笔记。
  • 全局快速查找。
  • 最近访问记录。
  • 最近修改记录。
  • 快捷键帮助面板。
  • 系统托盘入口。
  • 基础操作的右键菜单。

五、快速记录与笔记管理

5.1 快速记录

笔记创建过程应尽可能轻量化,不强制用户首先填写标题、选择文件夹或配置模板。

要求:

  • 新建后即可输入 Markdown 正文。
  • 默认自动记录创建时间与修改时间。
  • 支持剪贴板粘贴图片和文本。
  • 支持拖放文件作为附件。
  • 支持标签自动补全。
  • 支持创建笔记时选择工作区和时间。
  • 支持将笔记创建时间设置为过去的某一天。
  • 支持快捷键保存。
  • 支持未完成草稿恢复。

5.2 草稿

草稿必须能够跨应用重启保留。

未提交的长文本应写入 drafts/ 中的 Markdown 文件,而不是只保存在内存或浏览器状态里。

草稿需要具备恢复、放弃、继续编辑、失败上传重试等基本能力。

草稿恢复时应一并恢复正文、选中的附件、标签输入、工作区和日期信息。

5.3 编辑、固定、归档和删除

每条笔记支持:

  • 查看完整内容。
  • 修改正文。
  • 修改时间元数据。
  • 固定和取消固定。
  • 归档和取消归档。
  • 移动工作区。
  • 关联其他笔记。
  • 添加评论和表情。
  • 管理附件。
  • 复制 Markdown。
  • 导出单条笔记。
  • 删除和恢复。

固定笔记可单独显示在时间线顶部。归档笔记从默认活动时间线移除,但仍可搜索、查看和恢复。

删除操作优先使用可恢复的本地回收站机制。永久删除必须经过确认,并清楚提示可能受影响的附件和关联记录。

5.4 笔记详情

打开一条笔记时显示完整正文和属性区域。

属性区域至少包括:

  • 创建时间。
  • 修改时间。
  • 标签。
  • 所属工作区。
  • 固定和归档状态。
  • 附件列表。
  • 关联笔记。
  • 评论与表情。
  • 位置。
  • 分享与导出操作。

如果笔记较长,自动生成标题大纲。点击大纲项目时定位到对应标题。

六、完整 Markdown 编辑与渲染

6.1 编辑模式

至少提供三种编辑体验:

  1. 源文本模式:直接编辑 Markdown 原文。
  2. 实时预览模式:将正文渲染为可阅读内容。
  3. 分栏模式:同时查看 Markdown 原文和渲染效果。

编辑器必须真正读写 Markdown 文本,不能把其他富文本数据结构作为唯一内容来源。

工具栏用于快速插入语法,但不得限制用户手写 Markdown。

6.2 必须支持的语法

  • 一级至六级标题。
  • 粗体、斜体、删除线。
  • 行内代码和代码块。
  • 有序列表、无序列表及嵌套列表。
  • 待办清单及已完成状态。
  • 引用块。
  • 水平分割线。
  • 表格。
  • 超链接及链接引用。
  • 图片和文件引用。
  • 自动链接。
  • 脚注。
  • 多语言文本。
  • 转义字符。
  • 数学公式。
  • Mermaid 图表。
  • 常见 GitHub Flavored Markdown 语法。

6.3 代码与图表

代码块支持语言标识、语法高亮、复制代码、合理的横向滚动和较长代码的折叠展示。

Mermaid 至少支持流程图、时序图、类图、状态图和甘特图等常见图表。

数学公式应支持行内公式与独立公式块。

所有代码高亮、数学公式和图表渲染都应在本地完成。不得要求访问外部资源才能正常显示。

6.4 编辑体验

  • 支持标题、粗体、斜体、链接、清单、引用和代码块等快捷操作。
  • 在列表中支持 Tab 缩进、Shift+Tab 取消缩进。
  • 支持撤销、重做。
  • 支持编辑器自动保存。
  • 支持专注写作模式。
  • 支持调整编辑字体和字号。
  • 支持自动换行。
  • 支持恢复上次编辑位置。
  • 支持 Markdown 原始内容复制。
  • 支持对清单项目进行勾选,并将变化写回原始 Markdown。

内部链接、图片和附件的相对路径必须兼容标准 Markdown 文件,不能仅使用应用私有格式而无法被外部编辑器识别。

七、标签系统

7.1 自动识别

用户在正文中输入 #标签 时,应用自动识别标签,无须单独填写标签表单。

支持层级标签,例如:

  • #工作
  • #学习
  • #项目/开发
  • #项目/测试
  • #研究/视觉理解

标签可以包含多语言字符、数字、下划线、连字符以及合理的 Unicode 字符和表情。

标签采用区分大小写的规则,例如 #Work 和 #work 默认视为不同标签。

解析器必须避免将代码块、行内代码、URL、图片地址及普通链接中的 # 错误识别为标签。

7.2 自动补全

用户输入 # 后展示标签建议列表。

建议列表支持:

  • 按最近使用排序。
  • 按使用频率排序。
  • 模糊匹配。
  • 搜索已有标签。
  • 继续输入创建新标签。
  • 键盘上下选择与回车确认。

7.3 标签树

左侧边栏支持树形标签导航。

每个标签显示笔记数量,层级标签可以展开、折叠。

点击父级标签时,可以选择只匹配该标签,或匹配该标签及其全部子标签。

标签页面提供按使用频率、字母顺序等方式排序的能力。

7.4 标签个性化

设置页面允许为标签配置:

  • 自定义背景颜色。
  • 文本显示样式。
  • 内容模糊显示规则。
  • 基于匹配模式的批量规则。
  • 清除颜色或恢复默认样式。

模糊显示功能用于保护界面上的敏感信息,不能宣称它能加密或保护磁盘中的原始 Markdown 文件。

所有标签设置保存到可迁移配置文件中,并可在索引重建后恢复。

八、全文搜索、高级筛选与自定义视图

8.1 全文搜索

提供独立的快速查找窗口,以及在时间线和附件库中的上下文搜索。

全文搜索至少覆盖:

  • Markdown 正文。
  • Front Matter 元数据。
  • 标签。
  • 文件名。
  • 笔记 ID。
  • 附件文件名。
  • 可计算的笔记属性。

搜索结果需要显示匹配片段和关键词高亮,并能快速打开对应笔记。

支持大小写不敏感的文本搜索、短语搜索、标签搜索和日期过滤。

8.2 筛选条件

支持以下筛选维度:

  • 创建时间。
  • 修改时间。
  • 标签。
  • 工作区。
  • 固定状态。
  • 归档状态。
  • 是否包含超链接。
  • 是否包含代码。
  • 是否包含待办清单。
  • 是否包含未完成任务。
  • 是否包含位置。
  • 是否包含附件。
  • 是否包含某种媒体类型。

筛选条件可组合使用,例如显示最近七天内带有 #学习 标签且仍有未完成任务的记录。

8.3 高级查询语言

提供可视化条件构建器,也可以使用高级表达式输入框。

表达式至少支持:

  • &&、||、! 逻辑操作。
  • ==、!=、>、>=、<、<= 比较操作。
  • 括号。
  • 标签集合匹配。
  • 字符串包含、前缀、后缀和正则表达式。
  • 日期时间比较。
  • 相对时间范围。
  • 布尔型笔记属性。

建议支持类似以下的表达式:

tag in ["work"] && pinned
has_incomplete_tasks && created_at >= now - duration("7d")
has_link && !archived

表达式解析必须采用安全、受限的解析器,不得使用 JavaScript eval 执行用户输入。

保存查询前提供语法验证和预览结果,给出具体的错误位置和错误原因。

8.4 自定义视图

用户可将筛选条件保存为命名视图。

每个视图支持:

  • 名称。
  • 图标或表情。
  • 过滤表达式。
  • 描述。
  • 排序规则。
  • 是否显示在侧边栏。
  • 编辑、复制、排序和删除。

视图保存后显示在侧边栏。点击视图即可显示当前符合条件的记录,而不是创建笔记副本。

视图定义存放在独立配置文件中。删除搜索索引后,视图仍然存在,并且在索引重建完成后可以继续使用。

九、时间线与卡片浏览

9.1 时间线

主页面按创建时间或修改时间组织笔记,默认最新记录在前。

支持:

  • 固定笔记区域。
  • 按日期分组。
  • 按创建时间或修改时间排序。
  • 单列、双列、三列和自动列数。
  • 紧凑模式。
  • 分页或滚动加载。
  • 按标签、工作区和视图筛选。
  • 显示笔记中的图片、附件和关键属性。
  • 从详情返回后恢复原来的滚动位置。

单列模式优先呈现完整正文;多列模式优先呈现便于快速扫描的内容预览。

9.2 卡片内容

卡片显示正文预览、时间、标签及附件提示。

对于包含大量代码或长文本的记录,应支持合理截断,并提供完整展开操作。

本地链接预览可显示链接地址、域名及笔记内已有的信息。禁止默认请求第三方网站补全标题或图片。需要访问外部网站获取元数据时,必须由用户主动启用。

十、日历与活动日历

10.1 日历页面

提供月视图和日期浏览功能。

用户能够:

  • 切换上一月、下一月。
  • 快速返回今天。
  • 选择月份和年份。
  • 查看某天的笔记数量。
  • 查看某天的内容摘要。
  • 点击某天打开对应记录。
  • 从指定日期直接创建笔记。

支持配置一周的起始日,并使用用户本地时区展示日期。

日历默认根据创建时间分组,也允许切换为修改时间。

10.2 活动日历

侧边栏可以显示类似贡献活动图的月度日历。

通过颜色区分当天记录数量或活动强度,支持点击某天进行筛选。

数据应从本地记录实时或增量计算,不要求额外的数据录入。

十一、地图与位置管理

11.1 笔记位置

每条笔记可以关联一个地理位置,包括:

  • 位置名称。
  • 纬度。
  • 经度。
  • 可选备注。

允许手动输入坐标、在地图中点选,或在用户明确授权后获取设备位置。

位置元数据存入 Markdown 文件的 Front Matter,不得只保存在 SQLite 数据库里。

11.2 地图页面

显示具有位置元数据的笔记。

支持:

  • 按坐标展示标记。
  • 点击标记查看关联笔记。
  • 查看当前筛选结果中的所有位置。
  • 按日期、标签和工作区筛选。
  • 从某个位置直接创建新笔记。
  • 清除筛选条件。
  • 标记位置缺失或坐标异常的记录。

11.3 离线地图

核心功能必须支持完全离线运行。

地图优先支持用户导入的离线地图数据,例如 MBTiles。如果没有地图底图,应当提供坐标网格、位置标记列表及基础位置查看能力,不得因为无法访问在线地图就导致页面不可用。

任何在线地图服务必须由用户显式配置,默认不开启网络请求。

十二、附件库与媒体管理

12.1 附件添加

支持通过以下方式添加文件:

  • 编辑器工具栏。
  • 文件选择对话框。
  • 文件拖放。
  • 剪贴板粘贴图片。
  • 从已有附件库选择文件。

至少支持:

  • PNG、JPEG、GIF、WebP、SVG 等图片格式。
  • MP4、WebM 等常见视频格式。
  • MP3、WAV、OGG 等常见音频格式。
  • PDF。
  • TXT、Markdown、代码文件。
  • DOCX、XLSX 等常见文档格式。
  • 其他普通文件。

对不支持内嵌预览的格式,提供文件类型、大小和打开方式,并允许使用 Windows 默认应用打开。

SVG、HTML 等可能含有活动内容的文件必须进行安全处理,不得直接信任并执行文件中的脚本。

12.2 附件存储

所有通过软件管理的附件都必须真实保存在本地。

附件目录与笔记 ID 保持稳定关联,Markdown 中的引用使用可迁移的相对路径。

复制或移动整个笔记数据目录后,附件引用仍应能够解析。

附件文件丢失时,应在界面显示缺失状态,并提供重新定位或重新关联功能。

12.3 附件库页面

附件库按类型分类:

  • 媒体。
  • 音频。
  • 文档。
  • 未使用附件。

各分类显示数量,并支持搜索、分页、按月份分组和预览。

图片以网格展示,文档以列表展示。点击附件可以查看详细信息,包括所属笔记、文件大小、路径和基本媒体属性。

12.4 媒体预览

图片支持:

  • 全屏预览。
  • 放大与缩小。
  • 拖动查看局部。
  • 在同一附件组中切换图片。
  • 使用键盘操作浏览。

视频支持常规播放控制。

音频支持播放、暂停、进度条和多档播放速度。

12.5 附件清理

自动识别没有被任何笔记引用或绑定的附件。

允许用户检查并删除未使用附件,但不得仅仅因为用户删除了 Markdown 正文中的一个图片引用,就直接删除其原始文件。

清理前展示附件列表、大小和可能影响,提供确认操作。

12.6 媒体元数据

提供可选的媒体元数据读取功能,包括:

  • 图片尺寸。
  • 拍摄时间。
  • 相机信息。
  • GPS 位置。
  • 视频时长。

此功能默认关闭。

打开后,也必须明确告知用户是否仅在本地读取元数据,以及相关元数据会以何种方式保存。

读取图片的 GPS 坐标不能自动等同于给笔记添加地图位置,用户应能确认和修改关联结果。

十三、笔记关联与双向引用

13.1 语义关联

提供独立于普通 Markdown 超链接的笔记关联功能。

用户可通过关联选择器搜索现有笔记并建立联系。

每条笔记详情中显示:

  • 当前笔记主动关联的记录。
  • 被其他笔记关联的记录。
  • 每条关联记录的摘要和标签。

13.2 数据保存

关联关系使用稳定的笔记 ID 保存到文件元数据中。

修改关联、删除关联或移动笔记时,必须保持两侧关系一致;索引重建后可以恢复完整的关联图。

删除一条笔记时,应明确提示其被哪些笔记引用。不得未经确认就级联删除其他正常笔记。

13.3 普通 Markdown 链接

正文中的普通 Markdown 链接与语义关联分别处理。

普通链接仅表示正文引用;通过关联面板创建的关系才算语义关联。

同时支持指向其他本地 Markdown 文件的相对链接,并尽可能提供从链接返回应用中对应笔记的能力。

十四、评论、表情与本地消息中心

14.1 评论

支持在笔记详情中添加多条评论。

评论使用 Markdown 格式,并支持:

  • 查看评论时间。
  • 编辑评论。
  • 删除评论。
  • 回复或组织评论线程。
  • 关联其他笔记。
  • 为评论添加附件。
  • 复制评论 Markdown。

评论也必须有对应的本地 Markdown 文件,通过稳定 ID 和 parent_id 与上下文笔记关联。

删除父笔记时,默认保留评论文件,并在界面提示评论的关联目标已经删除。用户可以选择保留为独立记录或手动删除。

14.2 表情反应

支持为笔记和评论添加常见表情反应,例如点赞、爱心、笑脸和鼓掌。

点击已有的反应可以取消。

表情数据应持久化在对应记录的 Front Matter 或可靠的可重建外部关联文件中,不得只保留于界面内存。

14.3 本地身份与工作区语义

软件默认作为单人本地应用使用。

允许用户配置本地显示名称和头像,也可以选择建立多个本地资料身份,用于区分评论作者和本地操作记录。

本地身份不依赖在线注册或 SSO。工作区与本地资料身份不得伪装成具有系统级安全隔离能力的账号权限。

14.4 消息中心

提供本地消息或活动中心,用于显示:

  • 评论与提及相关活动。
  • 导入导出结果。
  • 外部文件变化冲突。
  • 缺失附件。
  • 备份状态。
  • 可能需要用户处理的数据问题。

消息中心在完全离线状态下仍然能够工作。

十五、工作区与笔记组织

15.1 本地工作区

支持创建多个本地工作区,用于组织工作、学习、研究、生活等不同类型的记录。

每个工作区包含:

  • 名称。
  • 描述。
  • 图标或表情。
  • 可选颜色。
  • 工作区 ID。
  • 相关笔记集合。

笔记可以属于一个工作区,也可以保持未分配状态。

15.2 作用范围

切换工作区后,时间线、日历、地图、附件列表、标签筛选及保存视图应按工作区条件展示内容。

从一个页面切换至另一个页面时,应尽可能保留当前工作区、标签和筛选条件。

归档、全局设置和数据管理等页面应保持全局可用。

15.3 工作区生命周期

支持创建、重命名、修改图标、调整顺序、删除与切换工作区。

删除工作区不能未经确认就删除其中的笔记文件。默认先解除笔记归属,再允许用户单独选择是否删除内容。

工作区配置需要持久化,并能在重建笔记索引后恢复。

十六、隐私、分享与导出

16.1 隐私原则

软件默认不提供任何云端公开访问能力。

所有笔记初始为本地私有记录。用户需要分享内容时,必须主动选择导出操作。

界面可以提供“私有”“允许导出”等状态标签,但不得将这些标签宣传为对磁盘文件的加密保护或真正的服务器端权限隔离。

16.2 分享为图片

支持将单条笔记渲染成高质量图片。

图片可以包含:

  • 笔记正文。
  • 主要格式。
  • 标签。
  • 可选时间。
  • 可选应用标识。

需要正确处理长文本、代码块、表格及图片。导出前可以预览,避免表情、中文或代码出现错误换行。

16.3 导出为独立 HTML

支持把笔记导出为可离线打开的 HTML 文件。

导出结果应包含必要的样式和本地附件资源,尽可能生成自包含文件或配套资源目录。

导出的 HTML 不得包含需要在线加载才能工作的 JavaScript、字体或图标。

用户可以明确选择是否包含附件、评论、关联记录和元数据。

16.4 本地分享链接

默认不创建外部可访问的分享链接。

如果实现本地预览服务,必须默认关闭,且默认只绑定 127.0.0.1。只有用户主动启动后才能创建短期访问地址,并明确告知地址的访问范围。

不得在后台自动开启局域网或公网分享。

16.5 Markdown 与 ZIP 导出

支持:

  • 导出当前笔记。
  • 批量导出所选笔记。
  • 按视图或工作区导出笔记。
  • 导出全部 Markdown 文件。
  • 导出 Markdown 与附件的 ZIP。
  • 复制原始 Markdown 到剪贴板。

导出时维持文件编码为 UTF-8,保留元数据、标签及可恢复的内部关联。

十七、导入、备份与恢复

17.1 Markdown 导入

支持从用户选定的文件夹扫描 Markdown 文件,并导入笔记数据。

应兼容具有或不具有 YAML Front Matter 的 Markdown 文件。

导入时需要:

  • 解析正文。
  • 识别已有元数据。
  • 重新生成缺失的 ID。
  • 自动提取标签。
  • 识别附件相对路径。
  • 检查重复文件。
  • 保留未知元数据。
  • 报告损坏或不支持的文件。

17.2 冲突处理

遇到重复 ID、同名文件或同一来源文件重复导入时,不得静默覆盖。

用户可以选择跳过、创建副本或在确认后覆盖。

导入前展示预览,包括笔记数量、附件数量、预计新增记录和潜在冲突。

17.3 备份

提供一键备份和恢复。

备份可以包括:

  • 全部 Markdown 文件。
  • 附件。
  • 工作区配置。
  • 保存视图。
  • 标签设置。
  • 用户偏好。
  • 其他恢复所需的本地配置。

SQLite 索引可以选择备份,但恢复后即使删除索引,也必须能够从 Markdown 文件重建。

支持配置自动备份频率和保留份数,并在备份失败时显示错误。

17.4 恢复验证

恢复数据后,应自动检查:

  • Markdown 文件是否完整。
  • ID 是否重复。
  • 附件引用是否存在。
  • 关联笔记是否可以解析。
  • 标签是否能被重新提取。
  • 配置文件能否正常读取。

恢复报告需要列明成功、失败、跳过及需要人工处理的记录。

十八、统计面板

提供完全基于本地数据的统计功能。

至少包括:

  • 笔记总数。
  • 最近新增数量。
  • 最近修改数量。
  • 已固定数量。
  • 已归档数量。
  • 标签分布。
  • 高频标签。
  • 按日期或月份统计的记录数量。
  • 工作区记录数量。
  • 未完成待办数量。
  • 已完成与未完成任务分布。
  • 含附件、代码、链接和位置的记录数量。
  • 附件总数及磁盘空间占用。

可以使用柱状图、趋势图、环形图和活动日历呈现数据。

统计结果应由本地记录计算,不能因为缓存清空而丢失原始信息。

十九、系统托盘、全局快捷键与快速采集

19.1 系统托盘

提供系统托盘菜单,至少包含:

  • 打开主窗口。
  • 新建笔记。
  • 快速搜索。
  • 查看最近记录。
  • 退出软件。

允许用户将关闭窗口配置为隐藏到托盘,而不是退出。

托盘运行时,保存机制必须保持安全。退出前要处理未保存内容。

19.2 全局快捷键

支持用户自定义全局快捷键,例如:

  • 新建笔记。
  • 快速搜索。
  • 打开主窗口。
  • 启动快速捕获窗口。

快捷键冲突时提供明确提示,并支持恢复默认设置。

19.3 剪贴板和文件采集

支持在快速捕获窗口粘贴文本、截图、图片与链接。

从资源管理器拖入文件时,可以选择将其作为附件保存,或提取可读取的文本创建笔记。

采集完成后立即写入本地数据目录。

19.4 可选浏览器剪藏

可以提供独立的浏览器扩展,用于捕获当前页面标题、URL、选中文本和用户指定的图片。

扩展必须通过明确授权的本机通信机制与桌面应用交互。没有桌面应用或用户未启用扩展时,不应自动连接其他服务。

网页剪藏属于可选功能,不得阻碍核心桌面应用运行。

二十、音频记录与可选转写

编辑器可以支持录制音频并将音频作为本地附件保存。

要求:

  • 明确提示麦克风权限。
  • 支持录制、暂停、继续和停止。
  • 显示录制状态与时长。
  • 音频保存失败时保留恢复机会。
  • 音频文件始终保存在本地。

语音转写属于可选能力。优先支持用户安装或导入的本地语音识别模型。

如果允许用户手动配置远程 AI 服务,必须明确展示数据会发送到外部服务这一事实,默认为关闭,并且不得自动上传已有笔记或附件。

二十一、设置、偏好与系统管理

21.1 外观

支持:

  • 浅色主题。
  • 深色主题。
  • 纸张主题。
  • 跟随系统。
  • 界面语言切换。
  • 编辑器字体和字号。
  • 代码字体。
  • 侧边栏宽度。
  • 列表列数。
  • 紧凑模式。
  • 专注写作模式。

主题切换应即时生效,并保存到本地配置。

21.2 默认行为

支持配置:

  • 默认工作区。
  • 新笔记默认时间。
  • 时间线按创建时间还是修改时间排序。
  • 默认列表布局。
  • 默认编辑模式。
  • 保存时是否自动返回列表。
  • 关闭窗口是否隐藏到托盘。
  • 是否开机启动。
  • 一周的起始日。
  • 是否默认读取媒体元数据。
  • 是否启用外部文件监控。
  • 自动备份策略。

21.3 标签设置

单独提供标签颜色、模糊显示规则、匹配模式、清除自定义样式等功能。

21.4 数据管理

提供以下入口:

  • 查看当前笔记数据目录。
  • 修改数据目录。
  • 打开附件目录。
  • 打开备份目录。
  • 查看当前数据占用。
  • 检查缺失附件。
  • 重建搜索索引。
  • 检查笔记元数据。
  • 清理可安全删除的缓存。
  • 导出和恢复完整数据。

重建索引不能修改或重写原始 Markdown 文件,除非用户明确要求修复文件。

21.5 个性化与诊断

支持设置应用显示名称、窗口图标及可选自定义 CSS。

提供应用版本、日志查看、诊断信息导出及常见错误提示。

诊断日志应避免包含完整笔记正文和敏感附件内容。

二十二、本地自动化与扩展能力

22.1 本地 API

为后续集成预留可选的本地自动化接口,例如创建笔记、查询笔记和导入文件。

接口默认关闭。如果启用,只能默认绑定本机回环地址,不得默认暴露到局域网或公网。

如果提供访问令牌,应采用安全存储方式,允许撤销和重新生成。

22.2 文件事件与自动化

支持通过本地事件通知或用户主动配置的脚本触发某些操作,例如:

  • 新笔记创建后执行用户脚本。
  • 数据导入结束后写入结果日志。
  • 导出结束后打开目标目录。

外部进程执行必须经过明确配置和授权,不得执行笔记内容中的任意指令。

22.3 网络访问约束

默认禁止后台遥测、自动上传、远程数据库连接、外部资源加载和不必要的更新检查。

需要联网的扩展能力应与核心功能隔离。关闭联网功能后,笔记创建、编辑、索引、搜索、标签、日历、附件、导入和导出必须继续正常运行。

二十三、文件监控与外部编辑兼容

这是实现纯 Markdown 存储必须重点处理的部分。

23.1 外部修改

当用户通过外部编辑器修改 Markdown 文件时,应用需要检测变化、重新解析元数据、更新索引和刷新界面。

不能要求用户先在软件中操作,外部变化才会生效。

23.2 外部移动与删除

使用稳定的笔记 ID 识别移动后的文件。

发现文件被移动时,应更新内部路径映射并保持关联和附件引用有效。

发现文件被外部删除时,界面应显示缺失状态,而不是未经确认就将其从所有缓存中彻底抹除。

23.3 并发冲突

如果用户在应用中编辑笔记时,外部编辑器也修改了同一文件,应检测冲突。

必须保留用户的两份修改内容,并提供比较、选择版本或另存为副本的能力。

禁止将外部新内容静默覆盖,也禁止直接使用应用内旧缓存覆盖外部修改。

23.4 索引重建

首次启动、修改数据目录、索引损坏或用户主动触发时,可以扫描文件目录并重建 SQLite 索引。

索引重建应显示进度和结果,并对大量笔记采用增量处理以维持响应速度。

二十四、性能、安全与可靠性

24.1 性能要求

  • 应用启动时不必一次加载全部笔记正文。
  • 时间线采用分页或虚拟列表。
  • 搜索采用索引和增量更新。
  • 大图片使用缩略图,避免加载原图造成卡顿。
  • 长文本编辑不能因索引更新而冻结界面。
  • 批量导入和导出显示进度。
  • 长时间执行的文件任务可以取消,并正确清理临时状态。

24.2 安全要求

  • Markdown 渲染内容经过清理。
  • 本地路径操作限制在用户选择的数据目录及允许的资源范围内。
  • 不执行 Markdown 或附件中的任意脚本。
  • 不自动加载第三方网站的图片、脚本或其他远程资源。
  • 文件写入异常、磁盘空间不足及权限不足都要有可恢复的错误处理。
  • 不在日志中记录完整笔记正文或敏感信息。
  • 软件不得以模糊显示、私有标签等界面行为冒充文件加密。

24.3 数据完整性

  • 不能以 SQLite 作为笔记正文的唯一存储位置。
  • 不能在缓存清除时删除笔记或附件。
  • 不能在备份失败时仍提示成功。
  • 不能在导入发生冲突时未经确认覆盖用户文件。
  • 不能在修改文件格式时静默删除无法识别的元数据。
  • 所有破坏性操作必须具有明确的确认或恢复方式。

二十五、推荐实施阶段

按以下阶段顺序执行,逐步构建真实可用的产品。

第一阶段:基础工程与存储

建立 Tauri、React、TypeScript 和 Rust 工程,完成窗口启动、数据目录选择、Markdown 文件读写、Front Matter 解析、安全写入、基本设置和 SQLite FTS5 索引重建。

验收:能够创建、编辑、关闭、重启并重新读取真实 Markdown 文件。

第二阶段:笔记编辑与主界面

实现导航栏、时间线、快速记录窗口、编辑器、预览、草稿、固定、归档及删除恢复。

验收:核心写作流程可正常使用,所有修改真实保存。

第三阶段:标签、搜索与自定义视图

实现标签解析、标签树、搜索、筛选条件、查询验证和保存视图。

验收:删除搜索索引后可以重建,标签、视图和笔记内容保持一致。

第四阶段:附件与媒体

完成附件上传、相对路径、预览、附件库、媒体元数据及未使用附件管理。

验收:移动整个数据目录后笔记与附件仍能正常访问。

第五阶段:日历、地图、统计和关联

实现时间线扩展、日历、活动日历、离线地图、位置元数据、笔记关联、双向引用及统计面板。

验收:这些页面的数据均来自真实本地记录。

第六阶段:工作区、评论与导入导出

完成工作区、评论、表情、本地消息中心、Markdown 导入、ZIP 导出、备份和恢复。

验收:相关数据能够通过文件与配置可靠恢复。

第七阶段:系统托盘、集成与设置

完成快捷键、系统托盘、全局捕获、外部文件监控、偏好设置、诊断信息及可选扩展接口。

验收:无网络环境下核心功能仍可使用。

第八阶段:质量保障与 Windows 打包

完成自动化测试、运行测试、安装包和便携版构建,完善说明文档并验证全新环境的启动流程。

不允许在任何阶段以创建静态页面作为完成标准。

二十六、最终验收清单

以下条件必须逐项验证:

Windows 上可以独立启动桌面应用,不需要用户配置服务器。

新建笔记后,磁盘上立即出现对应的真实 .md 文件。

文件中包含正文和必要的可恢复元数据。

修改正文、标签、位置、关系、固定或归档状态后,数据能够持久化。

所有核心功能在完全断网状态下可用。

可以直接使用外部编辑器修改 Markdown,应用能够检测并同步变化。

外部编辑冲突不会导致静默数据丢失。

删除 SQLite 索引后可以从文件重新构建笔记列表及搜索索引。

标签、视图、归档、工作区和其他本地配置能够可靠恢复。

Markdown 编辑器支持规定的语法、公式、代码和图表。

图片、视频、音频和文档能够保存到本地并正确引用。

附件库可以管理已使用与未使用资源。

时间线、日历、地图与统计页面展示真实数据。

笔记关系、反向引用和评论能够在重启后恢复。

可以导入外部 Markdown 文件,并完整报告冲突。

能够导出可迁移的 Markdown 文件及附件。

备份恢复不会静默覆盖已有文件。

系统托盘、快捷键和退出逻辑符合桌面应用习惯。

联网扩展未启用时,不存在必需的外部服务依赖。

所有核心模块均有自动化测试及实际运行验证。

提供可运行的 Windows 构建产物和清晰的安装说明。

二十七、最终交付内容

交付的不只是代码,还应包含:

  1. 完整的独立项目源码。
  2. 可运行的 Windows 安装包或便携版。
  3. 开发环境配置与启动说明。
  4. 项目架构和模块划分文档。
  5. Markdown 文件格式与元数据规范。
  6. 数据备份、迁移、索引重建和恢复说明。
  7. 自动化测试及测试结果。
  8. 已知限制与后续优化清单。

最终目标是一个可以长期使用的桌面产品,而不是只为演示功能制作的原型。

最重要的原则:所有笔记真实落盘为独立 Markdown 文件,所有核心功能真正可用,整个应用默认完全本地运行。功能实现必须建立在稳定的数据架构之上,不得为了尽快完成界面而牺牲数据安全、文件可迁移性和完整功能。

二十八、代码审计与修复记录

对前端(约 3.7k 行)与后端(约 3.8k 行)做了一次完整通读,实测验证了 Tauri IPC 的 Option<T> 语义、SQLite FTS5 的中文分词行为、附件路径拼接等关键假设,共定位 26 个问题,按优先级分五批提交修复。

28.1 批次与提交

批次 提交 主题
1 c449590 安全:Markdown 预览沙箱化、附件路径校验、CSP
2 232c128 数据链路:工作区/排序/筛选、IPC 契约、标签可删
3 ccd9daf 搜索:中文全文检索改 trigram、搜索结果可打开
4 6e0eb78 UX:外部改动监听、布局折叠、字号、日历、预览
4b 1039d58 构建:清理死依赖、附件懒加载、后端验证桩
5 05f8f99 导航:笔记深链、配置项对齐、备份/导入导出、归档反馈

28.2 逐条对照

# 问题 修复要点 状态
1 预览未做 HTML 净化,存在 XSS rehype-sanitize 置于 rehype-katex 之前;mermaid securityLevel: strict 已修
2 工作区筛选永远为空 create_note 写入 workspace_id,list_notes 按工作区过滤 已修
3 中文搜索无结果 FTS5 改 tokenize='trigram',短词回退 LIKE;旧表自动迁移 已修
4 设置页改目录不生效 改调 set_data_dir(重开库 + 重建索引 + 迁移 watcher) 已修
5 外部修改会被静默覆盖 后端 watcher + vault:changed,前端仅在无未保存修改时重载 已修
6 标签只能加不能删 从正文正则删除被移除的标签 已修
7 字号设置不生效 CSS 变量 + CodeMirror Compartment 重配置 已修
8 排序菜单无效 后端 sort_notes(置顶优先)+ 前端接线 已修
9 日历归桶/归档/选中三处 bug 按本地日归桶、过滤归档、刷新保留选中 已修
10 搜索结果点不开 改走 getNote(id),<mark> 以 React 元素渲染 已修
11 IPC 契约与 Rust 不一致 NoteMetaPatch 全 Option、DraftInfo、NoteMeta.note_type 对齐 已修
12 后端能力缺 UI 入口 备份/恢复、导入 Markdown、导出 zip、导出 HTML、表情反应 部分(草稿、SavedView、标签设置仍无界面)
13 附件缓存只增不减、逐张读 共享 LRU(40) + inflight 去重 + IntersectionObserver 懒加载 已修
14 预览图片判定过窄 支持 data:/blob: 与库内相对路径 已修
15 7 个死依赖 移除 shiki/recharts/leaflet 等(-43 包) 已修
16 保存与列表全量扫描 保存按索引定位路径;启动索引改后台线程 部分(list_notes 仍读全文)
17 预览每按键全量重解析 120ms 去抖 已修
18 局部更新误清状态 元数据补丁全 Option 已修
19 正文无法选中 移除全局 user-select:none,编辑/预览区强制 text 已修
20 卡片摘要暴露源码、时间口径错 toPlainText 剥离语法,展示更新时间 已修
21 布局不可折叠、分栏不可拖、窗口过小 侧栏/列表折叠、拖拽分栏(双击复位)、1280×820 且限最小尺寸 已修
22 深色下 Mermaid 与标签色失配 Mermaid 跟随主题重渲染,标签色改 CSS 变量 已修
23 窗口标题为 noteflow-app、无最小尺寸 productName/标题/minWidth 修正 已修
24 路由形同虚设 /note/:id 成为当前笔记的唯一来源,深链/前进后退/新建/归档/删除均同步 已修
25 归档体验断裂、统计口径不一 归档/删除后 toast 并回时间线;归档页可取消归档并显示时间 已修
26 配置项与界面不符 language 改 zh-CN;周起始日、字号、自动保存延迟写入 config.json 已修

28.3 仍存在的已知限制

  • 运行环境缺少可用的 tauri 编译链(GNU 工具链下 build script 段错误,MSVC link.exe 被 MSYS 覆盖),后端通过 src-tauri/rscheck 桩 crate 做类型检查与单元测试;cargo test 中 7 个依赖 chrono::Local::now() 的用例在该桩环境下触发 0xc0000005,属链接组合问题而非业务缺陷。
  • list_notes 仍读取每篇笔记全文以生成摘要,笔记量很大时列表首屏偏慢,后续可拆成「元数据 + 摘要」两段式接口。
  • 草稿、SavedView(自定义视图)、标签个性化(颜色/模糊)、笔记评论与关联目前只有后端实现,尚未提供界面。

二十九、专注模式与自动换行

29.1 为什么需要

默认布局为「侧边栏 + 笔记列表 + 编辑/预览」,在 1280 宽的窗口下正文区只剩约三分之一宽度;同时长段落在编辑器中不换行,会一直向右延伸。两者叠加,写作和阅读都很吃力。

29.2 专注模式

  • 入口:笔记工具栏的「放大」按钮,或 Ctrl/⌘+Shift+F。
  • 效果:隐藏侧边栏与笔记列表,正文占满整个窗口;编辑/分栏/预览三种模式照常切换,因此可以「全屏写作」或「全屏阅读」。
  • 退出:Esc,或右下角常驻的「退出专注 (Esc)」按钮——该按钮挂在全局布局上,即使切到搜索、日历、设置页也不会被困住。
  • 侧边栏(Ctrl/⌘+B)与笔记列表可各自独立折叠,折叠后正文区自动补满。

29.3 自动换行

  • 编辑器保留 EditorView.lineWrapping,并在 index.css 中显式声明 .cm-content/.cm-line { white-space: pre-wrap; overflow-wrap: anywhere; word-break: break-word },避免 CodeMirror 基础主题的 white-space: pre 因样式注入顺序覆盖换行规则。
  • .cm-scroller 强制 overflow-x: hidden,从根上消除编辑器的横向滚动条。
  • 预览区对 .noteflow-markdown 追加 overflow-wrap: anywhere,超长 URL、哈希、连续英文串都会折行;代码块(pre)仍保留内部横向滚动,避免代码被强行折断。
  • 布局链路补齐 min-w-0/min-h-0:侧栏 224px + 列表 288px 为固定列,正文列作为 flex 子项可以真正收缩,不再被内容的最小宽度撑开。
  • 分栏比例的可调范围放宽到 15%–85%,拖动分隔条即可让编辑或预览占据绝大部分宽度,双击分隔条恢复 50/50。

三十、构建验证与工具链修复(v0.1.2)

30.1 之前为什么「编不出可运行的 exe」

本机 Rust 工具链为 x86_64-pc-windows-gnu,此前一直用 -C linker=C:/mingw64/bin/gcc.exe 链接。该组合产出的二进制重定位信息是坏的:加载后代码跳到一个「丢了镜像基址」的地址(例如 .idata 的 RVA 0x159ace4 而不是 0x140159ace4),于是表现为:

  • tauri v2.12.3 的 build script 在启动瞬间 STATUS_ACCESS_VIOLATION (0xc0000005);
  • chrono::Local::now() 崩在 TzInfo::for_year;
  • 崩溃栈都落在 std::rt::init → GetModuleHandleA,与业务代码无关。

这两处「玄学崩溃」其实是同一个链接器缺陷,而不是 chrono 或 tauri 的问题。

30.2 修复方式

改用 Rust 工具链自带的 rust-lld:

$env:PATH = "$(rustc --print sysroot)\lib\rustlib\x86_64-pc-windows-gnu\bin;$env:PATH"
$env:RUSTFLAGS = "-C linker=rust-lld"

换掉链接器后:

  • tauri 及其 build script 正常编译,generate_context! 把 dist/ 内嵌进 exe;
  • 之前被 rscheck 桩掩盖的 3 处真实编译错误暴露并修好(watcher.rs 缺 tauri::Emitter,lib.rs 缺 tauri::Manager,storage::mark_self_write / commands::sort_notes 可见性);
  • 全部 17 个测试通过(含此前 7 个必崩的 chrono 用例)。

30.3 一条命令构建

powershell -NoProfile -ExecutionPolicy Bypass -File scripts/build-portable.ps1

脚本会依次执行 pnpm build → cargo build --release --features custom-protocol → 校验前端是否已内嵌 → 刷新 dist-release/NoteFlow-Portable/ → 重新打包 dist-release/NoteFlow-Windows-x64-Portable.zip。

--features custom-protocol 不能省。 tauri 的 build script 用 let dev = !has_feature("custom-protocol") 决定 cfg(dev):未启用该 feature 时 exe 会当成开发版,去加载 http://localhost:1420,用户看到的就是 ERR_CONNECTION_REFUSED / localhost 拒绝连接。脚本第 3 步会检查二进制里是否存在 assets/index-*.js 这样的内嵌资源路径,缺失就直接报错,避免又打出一个「连不上 localhost」的包。

30.4 测试与验证

$env:RUSTFLAGS = "-C linker=rust-lld"
cargo test --manifest-path src-tauri/Cargo.toml --bin noteflow-app
# test result: ok. 17 passed; 0 failed

注意必须带 --bin noteflow-app。不带时会先跑 src/lib.rs 的空测试目标,而该目标拿不到 tauri-build 只发给 bin 的 manifest 资源,comctl32 会解析成 v5,TaskDialogIndirect 绑定失败,进程在 main 之前就以 STATUS_ENTRYPOINT_NOT_FOUND (0xc0000139) 退出。

30.5 本次构建产物

项目 值
版本 0.1.2(Cargo.toml / tauri.conf.json / package.json 同步)
可执行文件 dist-release/NoteFlow-Portable/noteflow-app.exe(11.8 MB,release + LTO + strip)
便携包 dist-release/NoteFlow-Windows-x64-Portable.zip(约 5.1 MB)
冒烟验证 直接运行与在便携目录内运行均可正常启动;WebView2 的 Code Cache 中出现内嵌 assets/index-*.js,确认界面是从内置资源加载而非 localhost

30.6 排查记录:ERR_CONNECTION_REFUSED

现象 原因 处理
打开 exe 显示「无法访问此页面 / localhost 拒绝连接」 打包时没带 custom-protocol feature,cfg(dev) 成立,窗口去连 http://localhost:1420 用 scripts/build-portable.ps1 构建,或手动 cargo build --release --features custom-protocol

判断手头的 exe 是开发版还是生产版,看两个特征:

  • 文件体积:生产版约 13.8 MB(内嵌前端),开发版约 11.8 MB;
  • 用 strings -a noteflow-app.exe | grep "assets/index-":生产版能匹配到 /assets/index-xxxx.js,开发版匹配不到。

About

基于 Tauri 2 + Rust + React 的本地优先 Markdown 桌面笔记软件。以 .md 文件为权威数据源,支持 SQLite FTS5 全文检索、多维时间线/日历/地图视图与完整离线运行。

Resources

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages