Markdown Editor

Markdown Editor 是一款基于 Electron 的本地优先 Markdown 笔记应用，支持多标签编辑、实时预览和普通文件夹笔记库。

• 应用使用 Electron 主进程、受限预加载 API 和原生 Web 渲染进程。
• 笔记正文始终保存在用户可直接访问的普通文件中。

功能概览

• 可靠编辑：原子保存、另存为、未保存内容恢复，以及外部文件修改冲突保护。
• 笔记库管理：目录树、全文搜索、批量失效链接检查、最近文件、带时间排序的文件/大纲收藏、可恢复的文件操作，以及同时打开不同笔记库的多窗口。
• Markdown 体验：GitHub Flavored Markdown、Mermaid、标题大纲、双向滚动同步、页内查找，以及包含常用 Markdown 格式操作的编辑器右键菜单。大纲以文件名为根节点；双击节点文字可切换折叠状态，右键节点或使用命令面板可递归折叠、展开其子标题，操作后保留当前滚动位置。
• Codex 深层链接：源码和预览中的 codex:// 链接可通过系统协议处理器打开 Codex，在 Windows 上等同于在“运行”中输入并执行该链接。
• 图片管理：本地与剪贴板图片落盘、相对路径插入，以及跨目录引用调整。
• 片段管理器：独立窗口管理 .cfg 集合，支持编码自动识别、拼音和模糊搜索、复制或插入片段，以及打开来源文件。
• 托管同步 Beta：账号、自动同步、保守三方合并、冲突处理、远端仓库、设备、配额、版本历史、文件或仓库恢复和原始库导出。
• 文件问答：在“打包文件”中选择范围，由 DeepSeek 生成查询命令筛选文件，再根据打包内容回答问题。配置方法见DeepSeek 文件问答。

完整能力与快捷键参阅功能说明。

托管同步 Beta

账号、仓库与历史

• 同步中心提供账号、全局自动同步设置、设备管理、配额查看、远程登出和原始库导出。
• 远端仓库支持命名、列表查看和克隆；当前仓库可以查看本地与远端详情。
• 版本历史支持展开逐行 diff、将历史版本与当前工作区文件比较、恢复单个文件，以及按全局 revision 恢复整个本地仓库。

同步与冲突处理

• 当前仓库的手动同步入口位于侧边栏仓库操作区；手动同步仓库时也会同步账号级设置。
• Markdown 冲突使用保守三方合并；无法安全合并时保留冲突现场。
• 文件树会标记待处理冲突，并支持调用配置的外部合并工具。
• 侧边栏“同步”、同步中心“立即同步”和定时自动同步都保护未保存文件。
  • 远端更新命中已打开且未保存的文件时，本轮同步暂缓，保留磁盘正文与编辑器草稿。
  • 显示 Toast 和仓库标题警示图标，悬停可查看原因；刷新文件树不会清除警示。
  • 保存后再次同步，成功后清除警示；点击同步不会被视为允许覆盖未保存内容。

自动同步

• 登录后，通用编辑设置、笔记库 Markdown 文件上限、快捷键 JSON、热键 JSON 和热键启用状态自动与账号同步；完整字段清单见功能说明。本机路径、外部工具命令、窗口布局及登录凭据不上传。

• 文件和大纲收藏按稳定仓库 ID 独立同步；仓库尚未上云时先保存在本机，首次文件同步后自动上传。

• 设置保存后立即尝试上传，并每 60 秒独立检查其他设备的修改。关闭笔记库自动同步不会关闭设置同步。

• 首次登录以云端已有值为准，覆盖前会把本机可同步设置备份到应用数据目录的 preference-backups。离线修改会在连接恢复后重试；设置同步错误显示在同步中心。

• 不同设置字段分别同步；同一字段以服务端最后成功提交的版本为准。快捷键 JSON 和热键 JSON 分别作为独立字段处理。

• 同步中心分别展示笔记库、用户设置与收藏云同步状态、最近成功时间和待重试数量；诊断日志不记录设置值或收藏正文。

• 全局自动同步在同步中心配置，启用后默认每 60 秒运行一次。

• 自动同步开关与间隔修改后会自动保存，无需额外确认。

• 关闭自动同步不会重置已填写的同步间隔，重新打开应用后仍会保留。

• 当前仓库始终参与全局自动同步。

• 两个仓库级开关均位于侧边栏仓库操作区，并且彼此独立。

• “切换仓库后仍自动同步”是独立的仓库级开关，决定切换到其他仓库后是否继续在后台同步。

• “安全的自动同步”是另一个独立的仓库级开关，决定该仓库参与自动同步时是否只允许单向待推送或单向待拉取。

• 安全模式检测到双向变化或请求竞态时会保留现场并跳过，不会自动进入冲突解决。

• 任一自动同步模式检测到远端更新涉及已打开且未保存的文件时，会暂缓本次同步，不覆盖磁盘或弹出版本选择框；界面通过一次 Toast 和持续的仓库警示图标提示，保存后由后续同步重试。

  • 重复定时检查不会重复弹出 Toast；手动点击同步时会再次说明暂缓原因。

整体恢复

整体恢复会像 git reset --hard 一样，使用所选全局 revision 覆盖本地同步文件与编辑器内容。

• 全局自动同步关闭时，恢复只改变本地仓库，远端保持不变。

• 全局自动同步开启时，恢复结果会立即按照该仓库的普通或安全自动同步策略处理。

• 端到端调用链、模块职责、持久化模型和排障指南参阅同步流程与代码位置。

• 部署与安全说明参阅托管同步 Beta 专题文档。

快速开始

开发环境使用 Node.js 24 LTS（自带 npm）。安装或升级后重新打开终端，确认版本：

node --version
npm --version

• node --version 应显示 v24.x.x。
• Windows 使用用户目录安装版时，需确保其路径在终端的 PATH 中排在旧版 Node.js 前面。
• 若测试提示 node: bad option: --test，说明终端仍在使用不支持内置测试运行器的旧版 Node.js；在 Git Bash 中运行 type -a node 检查实际路径。

安装依赖并启动开发版本：

npm ci
npm run typecheck
npm run dev

• 客户端、同步服务、工程脚本和测试使用严格 TypeScript；应用运行编译后的 JavaScript。
• npm run build 清理并重建 .build/，随后构建编辑器依赖、复制静态资源和测试夹具。
• npm start 复用上次成功构建；缺少完整产物时自动构建。npm run dev 增量构建并启动 Vite renderer 热更新。
• npm run build:dev 只执行增量构建；测试、基准和同步管理命令仍先完整构建。
• 开发模式下 renderer 修改自动更新；主进程、preload 或开发配置修改后重新运行 npm run dev。部署同步服务的新产物后重启同步服务。

文档

阶段设计、验证基线和其余专题入口统一收录在文档导航中。

开发验证

运行完整验证：

npm run validate

• 该命令依次执行严格类型检查、ESLint、构建回归、单元测试、Electron 冒烟测试、Vite 热更新测试和当前平台目录打包。
• 详细验证范围与人工回归清单参阅阶段 0 工程基线。

也可以按需单独运行：

npm run typecheck
npm run build
npm run lint
npm run test
npm run test:smoke
npm run test:dev
npm run test:smoke -- --tree-drag-live-only
npm run test:smoke:broken-links
npm run benchmark
npm run benchmark:workspace
npm run benchmark:hosted-sync -- 250

• benchmark:hosted-sync 使用隔离临时数据库和内存验证码邮箱，无需配置 SMTP；结束后清理数据。
• test:smoke 默认执行全部冒烟分支及独立测试；参数选择方式见冒烟测试范围。

构建

• 正文编辑器使用 CodeMirror 6；npm run build:editor 是完整构建别名，包含 TypeScript 编译、资源复制以及 Rollup 生成的编辑器 ESM 和第三方许可证文件。
• 拉取包含依赖变更的代码后先运行 npm ci；编辑器依赖缺失时构建会直接失败，不会生成启动后无法加载的安装包。
• dev 启动时在编辑器输入变化后重新打包，再由 Vite 按需转译 renderer；start 复用已有产物。Electron 测试及各打包命令仍完整构建编辑器。
• 同一构建命令也将已安装的 ignore 单文件模块包装为浏览器 ESM，并复制其许可证，供文件筛选使用。
• .build/src/renderer/editor/generated/ 为忽略的生成物目录，安装包包含该目录，离线运行无需 CDN。
• 开发模式直接加载编辑器源码，修改适配器会安全刷新页面；修改依赖后重新运行 npm run dev。具体热更新边界见 Vite renderer 开发。
• npm run test:smoke:editor 验证独立编辑器的真实输入、历史、只读、定位和销毁。
• npm run benchmark:editor 测量 100 KiB 的五种文本及 20/50 标签；加 -- --stress 扩展到 1/5 MiB。
• 实施记录、已知验收缺口和回退方法见 CodeMirror 迁移。

npm run pack       # 当前平台未签名测试应用
npm run dist:win   # Windows 安装包
npm run dist:mac   # macOS 安装包

应用运行配置

• 设置界面可调整单个笔记库可扫描并纳入大纲索引的 Markdown 文件上限，默认为 10000。目录项上限为该值的两倍。

托管同步 Beta 开发服务

启动本地开发服务：

MYNOTE_SYNC_DEV=1 npm run sync-server

开发服务默认监听 http://127.0.0.1:8787。

局域网 HTTP 联调时，在服务端和客户端启动命令前同时设置：

MYNOTE_SYNC_FORCE_HTTPS=false

• 该开关默认启用 HTTPS 强制策略，只能在受控开发网络中关闭。
• 生产环境必须使用 TLS，并配置外置 AES 主密钥、备份目录和指标管理令牌。

完整的环境变量、部署步骤、安全边界和恢复流程参阅托管同步 Beta。

管理后台

独立前端位于相邻的 mynote-admin 项目。同步服务可通过管理员凭据开启 /admin/v1 管理 API，提供概览、账号和笔记库查询。配置、部署和权限边界见 管理后台 API。