详细文档（docs-mynoet-client）

• 项目总览 README
• 功能说明（含快捷键）FEATURES
• 技术架构 tech-arch
• 同步流程与代码位置 sync-flow
• 阶段 0 工程基线
• 阶段 1 可靠性设计与验证
• 阶段 2 桌面笔记库设计与验证
• 阶段 5 托管同步 Beta

dev

28qq qwer0987qw

misc

ipconfig getifaddr en0 mkcert install mkcert 192.168.0.223 daaijinxiaodeMacBook-Pro-2.local localhost 127.0.0.1 daaijinxiaodeMacBook-Pro-2.local

unset MYNOTE_SYNC_ENCRYPTION_KEY unset MYNOTE_SYNC_TLS_KEY MYNOTE_SYNC_TLS_CERT unset MYNOTE_SYNC_DATA MYNOTE_SYNC_HOST

MYNOTE_SYNC_DEV=1
MYNOTE_SYNC_DATA="$PWD/.sync-data"
MYNOTE_SYNC_HOST="0.0.0.0"
MYNOTE_SYNC_PORT="8787"
MYNOTE_SYNC_TLS_KEY="$PWD/192.168.0.223+3-key.pem"
MYNOTE_SYNC_TLS_CERT="$PWD/192.168.0.223+3.pem"
npm run sync-server

https://192.168.0.223:8787/health

mkcert -CAROOT

sudo security add-trusted-cert -d -r trustRoot -k /Library/Keychains/System.keychain "/Users/daaijinxiao/Library/Application Support/mkcert/rootca.pem"

dev ai log

加一个环境变量控制是否需要强制 HTTPS，默认为 true，可以改为 false。 MYNOTE_SYNC_FORCE_HTTPS=false # 允许非回环 HTTP 局域网联调时，服务端和客户端都需要设置为 false： MYNOTE_SYNC_FORCE_HTTPS=false npm run dev

快捷键 & 热键

详细说明：功能说明 FEATURES keyboard-mvp settings-keyboard

• 快捷键要精确判断，比如 cmd + f 是搜索，但 shift 再加上就不要触发了

快捷键配置

• 平台覆盖 默认留空，点击“禁用此平台”，应该是切换 checkbox

  • fix: apply input mode to platform shortcuts df17ca0

• 按 ESC 或者 Enter 都应该保持上一级页面的聚焦的元素，现在 Esc 会保持，但 Enter 没有保持。

• 配置对话框保持固定高度

• 配置快捷键默认采用按键录制方式，但可以切换为手动输入

• 取消重新录制的按钮，超时或者用户已经输入了两段快捷键，则自动启动重新录制

• Enter 可作为快捷键，但仅限于第二段；第一段时直接保存当前配置，关闭对话框

编辑 JSON 旁边增加一个按钮：默认 JSon，弹出显示所有的默认快捷键 Json 配置，供用户查看、复制

• 将中文描述文案也带上
• 支持定位文件（系统自带的 explorer/finder 打开）

热键也支持可配置。

• 查看平台旁边加一个checkbox：启用热键，取消选择后注销所有的热键
• 快捷键、热键分开配置，通过一个radio box切换，再在 快捷键设置 旁边加一个 热键设置 入口

编辑 & 预览 & 大纲

详细说明：功能说明 FEATURES §3

预览页面的搜索框，当焦点没有在搜索框时， Esc 也要能够关闭搜索框。

编辑器：支持 tab 输入

ctrl + g: 跳转行号

没有修改时，修改标记应该清除？ 不是简单的看 undo buffer

ctrl + ↑↓ 滚动视图，但不移动caret

• 每次滚动一行，长按连续滚动，光标和选区保持不变。
• scroll with ctrl arrows without moving caret 0382c88

基础编辑

• 剪切复制等要可撤销
• ctrl + x 没有任何选择时，剪切当前行；ctrl + c 复制行
• 包含图片的文本要跟随调整路径

编辑高亮

• 当前行高亮 Commit: 5584087e48a9726b8d1b66c12a07a84dff715e53 feat: highlight active editor line

• 高亮 caret 归属的文档范围：比如当 caret 在 aaaa 上时，先找到其所归属的大纲 #a，然后将整个这一范围全部高亮。再比如，当 caret 在 b1 上时，先找到其归属的大纲节点 ##b1(而不是 #b),再把整个范围高亮 bb93164

# a
aaaa
# b
bbb
## b1
b1b1

选择操作

选中文本块处理，一， Tab 键缩进两空格， Shift Tab 键反向缩进两空格，2，转换为列表，在每一行的前面添加'- '。

列表切换 toggle list

• 在edit菜单中加一个入口、显示快捷键
• 如果没有选择，则将当前行切换；cmd palette 总是展示

宽度调整、比列记录

当编辑和预览任意只显示其中一个界面时，则宽度调整为占据另外一个隐藏的界面。

• expand lone editor or preview panel bcfdcc83
• 恢复双界面时保留原分栏比例。

编辑、预览记录比列；侧栏、大纲记录绝对值

样式

编辑器：鼠标放滚动条时，没有变成常规的形状，还是编辑的插入形状 3e5e1d3

同步滚动

• 编辑器和预览页面的同步滚动相差较大，当关闭编辑器后，预览界面的定位就正常了

仅显示预览页面时也支持大纲定位

Commit: 400e1ce06761978756425c717aff477cde31b691 fix: align editor and preview scrolling

Commit: 810013527b342b716b932fa40759e0a3335a9122 fix: keep outline jumps aligned

大纲高亮，同步滚动

当大纲的高亮不在视图内时，滚动到视图内 71e1729

大纲跟随，双向，根据焦点区分编辑或者预览 6af2a92

页面内搜索 && 高亮

编辑、预览：搜索匹配要全部高亮，当前匹配独立高亮

• blur 保持高亮

类似 vscode 的 Commit: 5a2432aa687c76fc36923408b487b65c89894835

• zoom
• 同时支持水平、垂直滚动
• 原生 textarea 在焦点移到查找框后不会清晰绘制选区。在编辑内容上方绘制一个不拦截鼠标的当前命中标记。
• esc 关闭；焦点在编辑器内即可

当预览页搜索框显示并有搜索结果时，在编辑界面任意修改，编辑页和预览页都会滚动到顶部。 3b06672

• 所搜结果实时刷新不要滚动

页面内替换

实现：replace in current file b7b0be1

• 支持替换当前匹配及全部匹配
• 复用大小写、全字匹配选项
• 替换内容按字面量处理
• Windows/Linux：Ctrl+H
• macOS：Cmd+Option+F
• 预览模式触发时自动显示编辑区

other

• tab order 调整：从 src 直接跳转到 替换内容，再按 tab，才跳转到 查找选项
• 焦点在替换为输入框时，回车执行一次替换后焦点要保持在此输入框。
• 全部替换快捷键：win：ctrl alt enter，mac：cmd enter

显示行号

Commit: 8a8353f617ec397f8bb1f147492da1372cce2569

链接跳转

• 编辑器内部跳转
• 预览页面跳转

链接跳转失败，弹出对话框，点击确定后， caret 丢失。无法继续编辑。

• see window.alert window.confirm 等全部用替换

大纲搜索

see quick open & 搜索匹配算法

cache and search document outlines e5f2dd8

大纲数据缓存 & 搜索

• 保存到 .mynote
• 修改时更新
• 同时需要记录索引数据对应的文件的修改时间，因为文件可以在外部被修改。每次启动 APP 后，检查是否有外部修改，如果有则更新索引数据。
• 可以手动触发全部更新
• 同时需要记录索引数据对应的文件的修改时间，因为文件可以在外部被修改。每次启动 APP 后，检查是否有外部修改，如果有，则更新索引数据。
• 大纲查询，复用 Quick Open 界面，如果以 @ 开头则在全部的索引数据中搜索；如果以 @@ 开头则在当前文件的大纲数据中搜索。
• 拼音搜索支持
• 搜索时匹配的字符高亮

在大纲搜索的过程当中，后台会刷新索引？导致当前选择的项被重置到第一个。

搜索（全文、当前文件）支持全字匹配、大小写敏感选项

大纲的条目带上大纲的级别。比如一级大纲不加空格，二级大纲加两个空格。以此类推 d4791cc

与 .git 共存

先 clone 再移动 .mynote 到 .git 同级目录

相关：阶段 2 桌面笔记库设计与验证

同步

详细文档：同步流程与代码位置、托管同步 Beta

• 同步过程输出进度
• 重新登录后不会全部重新拉取，状态要能够全部立即从本地恢复
• 与上一版本相比，正文内容无变化。这种应该忽略，不要增加一个版本 9915d64

同步中心

• 打开同步中心 alt + s

状态简要

待处理：1 这个改为 待推送/待拉取：x/y，当x/y 任意一个不为0时，高亮显示

• 蓝色高亮条目表示待拉取（同步到本地）的版本 - 从这里就能得到待拉取的数量

auto-merge 自动合并

f684639c88b3a0f039da4b2f0ca5cd2f62971a99

就在当前文件旁边生成，如 a.md.base, a.md.local, ..., 如果成功合并，则删除这些临时文件；否则保留这些临时文件。其中任何一个特殊文件存在，则在文件树中以特定标记提示用户，用户手动解决完冲突之后可以在右键菜单中选择解决完成，自动帮用户删除这些临时文件。其他按此计划执行

只合并最终版本

保持 protocolVersion: 1，但不兼容旧分页 v1。
服务端一次返回 cursor 后每个 fileId 的最终版本。
中间版本仍保留在版本历史中。
客户端基于共同基线只执行一次三方合并。
整批成功后一次性推进 cursor，支持中断重试和路径互换。
新客户端会拒绝旧分页 v1 响应。
.mynoteignore 继续遵循“只影响新文件”的规则。

Commit: 4c14c9af63ec0adaaa151a525329015bd2574a55 feat: compact v1 sync pull snapshots

外部工具解决冲突：beyond compare

增加一个右键菜单：外部工具解决冲突，在设置界面设置外部工具路径以及参数, 如：/Applications/Beyond Compare.app/Contents/MacOS/BCompare %local %remote %base %merged，其中 %是占位符，分别传入对应的文件路径，启动外部程序合并

参数例子："/Applications/Beyond Compare.app/Contents/MacOS/BCompare" /Users/daaijinxiao/Desktop/cyb/r1/2.md.local /Users/daaijinxiao/Desktop/cyb/r1/2.md.remote /Users/daaijinxiao/Desktop/cyb/r1/2.md.base /Users/daaijinxiao/Desktop/cyb/r1/2.md

beyond compare 启动了，但并没有进入合并界面，而是起始页面：要用 bcomp

冲突

当前文件如果处于冲突状态，同时在标签栏标记出来；

有任何文件处理冲突状态，阻止后续同步；

• 点击同步按钮，提示冲突
• 左上角仓库名显示冲突标记

模块点击滚动到顶部

点击远端仓库等任何一个模块，就将这个模块滚动到顶部，便于查看内容。诊断日志模块因此不再需要折叠展开

Commit: 6e465b8e7a5bfc540dc7cf0ede824705e0e1cac3 feat: scroll sync modules into view

后台自动同步

再增加一个选项，当前仓库是否后台自动同步，默认为 false，当勾选时，不管此仓库是否为当前仓库都会自动同步，前提是全局的自动同步开关是开启状态。

• 全局的自动同步开关是开启状态时，当前仓库一定自动同步

待同步(推送)内容

查看待同步的内容，包含文件列表和diff，可以考虑和最近版本的复用

Commit: 2f14da7aa9cdbc571a56ddb6db0a7ae8fdd59d8b feat: preview pending sync changes

安全的自动同步(无需合并时)

切换仓库后仍自动同步 开启时，才可选择（有效），如果选择了，当仅有推送或者拉取的内容时才自动同步（一定不会有冲突）。

改为独立选项，因为 切换仓库后仍自动同步 即使没开启，全局开启了并且为当前仓库时，也会自动同步，此时 安全的自动同步 就有意义

Commit: b7c568a9b8b0a76110056e0546686972d3b511bc fix: make safe auto sync repository independent

版本列表

最近版本列表，点击显示这个版本的详细信息，包括但不限于修改时间，动作（删除、新增、修改。。。），diff内容，修改设备名等

• 当展开细节时，头部固定不跟随滚动，考虑sticky样式
• 最近版本 旁边增加一个选项，显示简洁差异，默认勾选，只显示变化附近的行
• 再增加一个选项：自动换行，控制差异文本框的自动换行
• 待拉取（同步到本地）的条目高亮

Commit: 9ffb68f7b13ecea1a0875bc89ea2a9f64a30e431 feat: add compact sync diff option

Commit: e52e62ac53ec7711a6d7672d9d907202db6ac520 feat: show detailed sync version history

增加一个“整体恢复”，点击后将本地所有文件恢复到某个版本（类似 git reset hard）。

• 建议在关闭自动同步的情况下使用

详细日志

诊断日志旁边加一个选项：详细输出，默认false，启用后输出更多详细信息 支持“粘底”特性

仓库管理

详细说明：阶段 2 桌面笔记库设计与验证

open in vscode 2647943

• new window

远端仓库列表

新增一个列表界面，展示当前用户所有的仓库，然后可以克隆指定的仓库到本地。

• clone到本地，当选择的文件夹不为空时，新建一个 repo name or repo-id 的文件夹
• 文件数仅统计markdown文件

用户可以手动修改仓库名

• 用户手动改名后，显示为 name(repo-id) 这个形式；否则显示为 repo-id 远端仓库可以删除，默认的名字为本地显示的名字

本地仓库详情

可以修改本地名称，但不要实际修改文件夹名

84b00cd6c3e1dd2696931c16e92eb80735585953 fix: keep local repository names separate from folders

移除仓库：仓库详情按钮后面增加一个按钮：从仓库列表中移除当前仓库。需要用户二次确认，同时删除根目录下的 .mynote 文件夹

批量检查当前仓库的 broken links

• feat: reveal files in system explorer 12f1e9c

see 多文件搜索/替换

• 功能实现类似

文件管理

详细说明：阶段 2 桌面笔记库设计与验证

.app 这种文件不需要解析内部的结构和同步内部内容；左侧文件树结构也不需要解析

MAX_TREE_FILES 这个控制的应该是实际需要同步的文件数量（包含图片等），而不是已经访问过的文件数量。比如有的项目文件非常多，但是 Markdown 文件却很少，是需要要支持的

文件搜索: quick open

实现类似vscode 的快捷打开文件面板，快捷键为 ctrl/cmd + p

中文等输入法正在组合文字时，Enter 和方向键由输入法处理，不会误选并打开文件。

Commit: 429b7cae611c2bff2a76a3eec5ab7c1cfd52dfdd fix quick open IME enter handling

find/search/replace in files 多文件搜索/替换

see 搜索 common

search open in editor: alt + enter 快捷键 7c38307

search open in editor: 高亮全部的匹配结果 d1b07ef

add workspace search editor a595c95

顶部修改查询条件：support dynamic search editor queries 4bad5d

• feat: add replace in files e0dd68a

标签管理

• 已打开的文件当前打开的仓库关联，切换仓库后切换已打开的文件。如果没有打开任何仓库，则不记录已打开文件。
• 全部关闭、关闭其他等常规操作。
• ctrl + tab 切换标签
• 切换到上下一个标签：mac：cmd shift + [/]， win: ctrl pagedown/up
  • mac: 当出现切换界面之后，上下键可以用来选择，而不是触发系统的窗口管理功能。 - 无法截获系统快捷键

Commit: 0eddea1f321d58f812335ebea7e16eaaa98dac27 feat: add tab management interactions

标签隔离、独立，不共享

编辑页面在多标签中不要共享，这样会造成切换标签后位置滚动到了底部，并且undo、redo buffer 被清空

Commit: ee8d0ffa043783487f3c6bd16d322c1d37a29c4a fix: isolate editor state per tab

pinned/normal/preview tab/editor

preview-editor.md

• 转换
• pinned：不被全部关闭
• normal：不会降级
• require repeat close for pinned editors

复制（相对）路径 copy (relative) path

dc22331

• 左侧文件树、tab 菜单同时支持

左侧文件树

• 关联当前页面 30218e5
• 操作菜单
• 冲突标记、解决、外部工具
• 路径复制

定位文件 reveal in file explorer

shift + alt + R；同时在左侧文件树和tab上下文菜单中加入 12f1e9c

• 定位文件（系统自带的 explorer/finder 打开）

.mynoteignore

详细说明：阶段 2 桌面笔记库设计与验证

支持 ignore，类似于 .gitignore 配置文件用 也需要同步 改为：已经加入管理的文件不受其影响，只影响新文件是否加入同步管理和在左侧文件树中显式

Commit: 02b97d5b8738ee675203742f1551609ac0017d90 fix: preserve managed files across ignore rules

mermaid 流程图

• 长文本能够正常显示

Commit: af56c6d9c28e29d533eb4cdb37bf25c90cbdbc66 fix: preserve full Mermaid node labels

server export tool

相关：托管同步 Beta（原始库导出）

script 文件夹下实现一个小的 Node js 工具，这个工具接收第一个参数是用户 ID， 第二个参数是仓库的名字或者 ID， 第三个参数是输出路径 这个工具直接在服务器端执行，可以不需要密码直接访问仓库数据。 如果已经clone了，则同步数据到最新

export MYNOTE_SYNC_DATA='/srv/mynote-sync'
export MYNOTE_SYNC_ENCRYPTION_KEY='<与同步服务相同的密钥>'
npm run sync-export -- '<用户 ID>' '<仓库名称或 ID>' '/srv/exports/target-repository'

export MYNOTE_SYNC_DATA='/Users/daaijinxiao/Desktop/prjs/mynote-client/.sync-data'
export MYNOTE_SYNC_ENCRYPTION_KEY='f9aCPmdePImx1gLHliyofK605qTqnOMOZ/lKQqp6xHk='
npm run sync-export -- '81b412e1-ff41-4e1e-9aa6-ba6adced2d54' 'dcd91689-6d5e-4626-8174-f050b09227db' '/Users/daaijinxiao/Desktop/cyb/export-r1'

问题记录

windows, 移除当前仓库，或者新 clone 后，仓库下拉框不能点击展开

这个发现确认了真正根因：Windows 下关闭 window.confirm / window.alert 后，Chromium 会暂时抑制原生下拉弹窗，应用失焦再聚焦才恢复。

• 移除仓库改用应用内确认框，不再调用 window.confirm。
• clone 成功改用非阻塞通知，不再调用 window.alert。
• Electron 完整流程已通过，移除后无需切换焦点即可命中仓库选择器。
• Lint、仓库测试和 Windows 打包通过。

40c0d8f8f2f4758e46a30de559b5535575469a26

Commit: 1b5e274ce87f24595b7a2a7e633b4351d4fd20ac

Commit: 8bcca53ba05078de566ffaf2f318f765483abbe5

搜索 common

匹配算法，拼音支持

see 3.4 编辑、预览与大纲面板

匹配高亮，可以不连续

大小写敏感、全字匹配

搜索（全文、当前文件）支持全字匹配、大小写敏感选项 991cc15

大纲搜索，@pinned 为什么匹配 “在预览旁边再增加一个大纲按钮，选中的时候显示大纲面板，大纲面板的内容从笔记的内容当中自动提取大纲节点。”？

Commit: d99945e857d31ed4d556fb092fd3e33bac6400e5 by 豆包 fix: drop subsequence fallback on full-pinyin quick-open aliases

原因是大纲搜索支持拼音模糊匹配，而且允许字母不连续。我用这条原文复现了命中。

• @ 只表示“搜索整个笔记库的大纲”，实际搜索词是 pinned，不是“已固定”筛选条件。

• 标题会转换成全拼和拼音首字母参与搜索。

• “旁边再增加一个大……”的全拼中，恰好能依次找到 p i n n e d：

  【p】angb【i】a【n】zaize【n】gjiayig【e】【d】a…

当前算法只要求字母顺序一致，间隔再远也只扣分，不排除结果，因此长中文标题容易出现这种意外命中。

对应逻辑在 quick-open-search.js。这次只定位原因，未修改代码。

文档链接

给这份精炼文档(/Users/daaijinxiao/Desktop/cyb/cyb/docs-mac/mynote-client.md)添加链接指向细节文档，位置在 /Users/daaijinxiao/Desktop/cyb/cyb/docs-mynoet-client 下面

窗口管理

Ctrl/Command+Shift+S 系统级热键切换主窗口显示状态：当主窗口处于显示状态并且不是激活状态时，要bring to top，而不是隐藏 改为最小化而非隐藏

ctrl + shift + alt + s（win/mac 相同）: 在当前已打开的窗口中切换

• mac 原生可以用 cmd + `, windows 可以用 ctrl + 点击窗口图标实现

支持新建窗口，打开不同的笔记库

• • s 变为控制最后题词激活的窗口

实现 vscode 类似的 file - open recent 功能

• 统一 ctrl + r
• 数量无限制

新打开（或切换）窗口后，如果当前标签是编辑器，则聚焦 d92545

window.alert window.confirm 等全部用替换

Commit: c3becb391d440028bfd75eb738a7805366b88dbb fix: replace native confirmations with application dialogs

这个会导致点击后编辑器失去焦点，无法编辑。必须切换其他窗口再切换来才可以（windows）

Command Palette 命令面板

• feat: add searchable command palette with keyboard navigation 23e899
• 显示快捷键
• Command Palette 显示后再关闭，textarea或者 input的caret要恢复 55ffa92
  • quick open 面板同样处理 6eb7747

查找哪些命令没有包含在 command pallete 中？

• vscode open

menu-view

zoom in/out

• fix: route zoom shortcuts through application keybindings a8be378