mynote-client 特色功能总结（按标题大纲）

以下仅依据 docs-mac/mynote-client.md 中明确出现的标题/条目整理，未做额外推断；涉及具体实现细节的部分，若文中未给出事实则标注为“未在文中说明”。

一、快捷键 & 热键

• 快捷键精确判断（如 cmd + f 搜索，加 shift 不触发）
• Tooltip 按平台显示 Command/Control
• 快捷键配置（keyboard settings）
  • 精确命令定位配置
  • 平台覆盖（默认留空、禁用此平台为 checkbox）
  • ESC/Enter 保持上一级页面聚焦元素
  • 配置对话框固定高度
  • 按键录制 ↔ 手动输入切换
  • 取消重新录制按钮，超时或输入两段后自动重新录制
  • Enter 仅限第二段；第一段时保存并关闭
  • 编辑 JSON 旁按钮：显示默认快捷键 JSON（含中文描述、支持定位文件）
• 热键可配置
  • 查看平台旁 checkbox：启用热键，取消后注销所有热键
  • 快捷键、热键分开配置，radio box 切换
• 过滤："" 包裹则只匹配快捷键（如 "ctrl d"）
• 过滤支持拼音搜索
• chord 单字符输入法问题（cmd + k t 第二部分被输入法拦截）
  • win/mac 合并版本
  • alt + pagedown/up 连续会输出字符到编辑器

二、编辑 & 预览 & 大纲

• 预览搜索框在焦点不在时 Esc 也能关闭
• 编辑器支持 tab 输入
• ctrl + g 跳转行号
• 修改标记清除（非简单看 undo buffer）
• ctrl + ↑↓ 滚动视图但不移动 caret（每次一行、长按连续、光标选区不变）
• 基础编辑
  • 剪切复制可撤销
  • ctrl + x 无选择剪切当前行；ctrl + c 复制行
  • 包含图片的文本跟随调整路径
• 编辑高亮
  • 当前行高亮
  • 高亮 caret 归属的文档范围（按大纲节点）
• 语法高亮：围栏代码块（fenced code block）
  • 1–6 级标题、各种语法高亮
  • 预览也支持，展示语言类型并提供复制按钮
• Mermaid 流程图（长文本正常显示；渲染失败问题记录）
• 选择操作
  • Tab 缩进两空格，Shift Tab 反向缩进
  • 转换为列表（每行前加 - ）
• 列表切换 toggle list（edit 菜单入口、无选择切换当前行、cmd palette 总展示）
• fenced code 围栏包裹（菜单支持）
• 悬浮工具条 float toolbar（常用编辑操作、链接解析与编辑回显）
• 视图切换：编辑-预览 三态切换、三段式控件
• 宽度调整、比例记录
  • 只显示一个界面时宽度占满另一个隐藏界面
  • 恢复双界面保留原分栏比例
  • 编辑/预览记录比例；侧栏/大纲记录绝对值
• 样式：编辑器鼠标放滚动条未变常规形状
• 同步滚动（编辑器与预览同步；仅预览时也支持大纲定位）
• 大纲高亮、同步滚动（高亮不在视图内时滚动到视图内；双向跟随，按焦点区分）
• 页面内搜索 && 高亮
  • 全部匹配高亮 + 当前匹配独立高亮
  • blur 保持高亮
  • 类似 vscode：zoom、水平/垂直滚动、Esc 关闭
  • 预览有搜索结果时编辑修改会滚动到顶部（实时刷新不滚动）
  • F3 未打开搜索框也响应；caret 变化后按最新位置计算下一个
  • 匹配已在视图中则不滚动
• 页面内替换
  • 替换当前/全部匹配，复用大小写、全字匹配选项
  • 替换按字面量处理
  • Windows/Linux Ctrl+H；macOS Cmd+Option+F
  • 预览模式触发自动显示编辑区
  • tab order、焦点保持、全部替换快捷键（win ctrl alt enter，mac cmd enter）
• 显示行号
• 链接跳转
  • 编辑器内部/预览页面跳转
  • Ctrl+鼠标 hover 时 cursor 设置
  • Alt + E 打开 caret 处链接
  • 链接跳转失败对话框会导致 caret 丢失（window.alert/confirm 全部替换）
  • 预览链接跳转未跳到对应标题
• codex:// 链接跳转（类似 Windows 运行中执行）
• chrome:// 识别（chrome 限制，不行）
• Link to mirror 链接本地映射
  • 默认存在本地文件则跳转本地文件
  • host 配置到 .mynote 下 config（格式参考 .git config）
  • 映射算法参考 doc-crawler
  • 可不配置，走老逻辑
  • 编辑和预览下 Shift 抑制映射（如 Ctrl + Shift + 点击 直接原始跳转）
  • 快捷键情况下需新增快捷键
• back/forward navigation 前后导航
  • 主菜单加 go，两个命令放入
  • 点击大纲跳转也加入历史
  • 收藏、前后导航 location 的行号动态计算
  • quick open 大纲跳转 alt + ← 返回位置问题
• caret 位置下方显示输入法状态，跟随 caret（可配置，默认 false；TODO 兼容其他平台）

三、大纲

• 大纲搜索
  • 仅收藏中搜索 @!
  • 大纲数据缓存 & 搜索（保存到 .mynote、修改时更新、记录对应文件修改时间、启动检查外部修改、可手动触发全部更新）
  • @ 全部索引搜索；@@ 当前文件大纲搜索
  • 拼音搜索支持、匹配字符高亮
• 大纲条目带级别（一级不加空格，二级加两空格，以此类推）
• 整体提升、降低级别
  • 处理整行（非整行扩展为整行）
  • 保持原有嵌套关系，遇一级/六级整批阻止
  • 支持 ATX、Setext，忽略代码围栏
  • editor.promoteHeadingLevels、editor.demoteHeadingLevels
  • 编辑菜单入口
• 大纲面板功能
  • 顶部：全部折叠/展开、过滤框（拼音过滤、支持历史、支持命令面板）
  • 复制大纲：Markdown 格式 / 纯文本格式（缩进表示级别）
  • 大纲树操作：手动折叠展开；焦点在大纲时 ctrl/cmd + f 定位过滤框
  • 双击文本切换折叠展开
  • 文件名作为根节点
  • 递归折叠、展开
  • 折叠展开后大纲不滚动到底部
  • 支持命令面板
• cross reference 交叉引用 & 复制引用（大纲）
  • 标题失效也检查（批量检查 broken links）
  • 快捷键 ctrl/cmd alt c
  • 左侧树菜单页上下文菜单也加入（未打开文件则退化为只复制文件引用）
  • 复制引用：仅复制文件引用不带大纲
  • 中文大纲不用 URL 编码转义
• 引用查找
  • Shift+F12 查找光标所属标题引用；无标题或文件未打开回退为文件引用查找
  • workspace.findFileReferences、workspace.findHeadingReferences
  • 未保存新文档、仓库外文件、文件夹、搜索结果不提供目标查找命令

四、收藏

• 扩展收藏：文件收藏 + 大纲收藏（A 文件下展示 A1/A2/A3，记录收藏时间）
• 默认按文件组织，可切换按时间排序（第一次降序，第二次升序，再次恢复按文件组织）
• 大纲收藏：命令面板、大纲右键菜单，快捷键 alt f，触发后切换收藏
• 收藏按时间展示时，文件路径和修改时间显示到第二行
• 收藏整理
  • 失效后点击 fallback to 行号
  • 给出全部失效列表，重新计算大纲 title，提供“更新 title/取消收藏”，可全选批量操作
  • 每次点击整理，精确匹配的更新最新行号并存储
  • 列表支持双击跳转；整理按钮支持命令面板

五、与 .git 共存

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

六、同步

• 同步过程输出进度
• 重新登录后不全部重新拉取，状态立即从本地恢复
• 正文内容无变化则忽略，不增加版本
• 同步中心
  • 打开同步中心 alt + s
  • 状态简要：待推送/待拉取 x/y，任一不为 0 高亮；蓝色高亮条目表示待拉取
  • 远端游标等状态刷新
  • 再次打开恢复上次滚动位置
• auto-merge 自动合并
  • 在当前文件旁生成 a.md.base、a.md.local 等临时文件
  • 成功合并则删除临时文件，否则保留
  • 特殊文件存在时文件树标记，用户手动解决后右键“解决完成”删除临时文件
• 只合并最终版本
  • 保持 protocolVersion: 1，不兼容旧分页 v1
  • 服务端一次返回 cursor 后每 fileId 的最终版本
  • 中间版本保留在版本历史
  • 客户端基于共同基线只执行一次三方合并
  • 整批成功后一次性推进 cursor，支持中断重试和路径互换
  • 新客户端拒绝旧分页 v1 响应
  • .mynoteignore 继续“只影响新文件”
• 外部工具解决冲突：Beyond Compare
  • 右键菜单“外部工具解决冲突”，设置界面设置路径和参数
  • 占位符 %local %remote %base %merged
  • 需使用 bcomp
• 冲突
  • 冲突文件在标签栏标记
  • 有冲突文件阻止后续同步；点击同步提示冲突；左上角仓库名显示冲突标记
• 模块点击滚动到顶部（诊断日志模块不再折叠展开）
• 后台自动同步
  • 当前仓库是否后台自动同步，默认 false；全局开关开启时当前仓库一定自动同步
  • 因安全自动同步无法自动同步时，左侧仓库区展示警告状态，tooltip 显示原因
• 安全的自动同步（无需合并时）
  • 切换仓库后仍自动同步开启时才可选择
  • 改为独立选项
• 待同步（推送）内容：查看待同步内容（文件列表和 diff）
• 最近版本列表
  • 点击显示版本详细信息（修改时间、动作、diff、修改设备名等）
  • 展开细节时头部固定（sticky）
  • “显示简洁差异”默认勾选，只显示变化附近行
  • “自动换行”控制差异文本框
  • 待拉取条目高亮
• 整体恢复：点击后本地所有文件恢复到某个版本（类似 git reset hard），建议关闭自动同步时使用
• 定位到文件：自动关闭同步中心、显示侧栏、展开父目录并选中/聚焦文件；删除或本地不存在不显示
• 详细日志
  • 诊断日志旁“详细输出”默认 false，支持“粘底”
  • 详细同步日志（触发时间、本地版本、远端版本、冲突详情）
  • 日志存独立 logs 文件夹，每天一个文件（如 2026/09/19.log），不存 state.json
• 同步速度优化
• 同步正在编辑的文件
  • 简单方案：跳过、toast 提示 & 仓库警告、save 后再同步
  • 竞态、后台三方合并冲突处理问题
• merge-bases 需要清理
  • 复用 history-v1 版本正文作为三方合并基线，缺失时仅在真正冲突时按需取一次
  • 停止写入 merge-bases

七、仓库管理

• 打开笔记库：第一次打开本地库时不在远端立即创建对应仓库
• open in vscode（new window、暴露 VS Code open 命令）
• 远端仓库列表
  • 展示当前用户所有仓库，可克隆指定仓库到本地
  • 选择的文件夹不为空时新建 repo name or repo-id 文件夹
  • 文件数仅统计 markdown 文件
  • 用户可手动修改仓库名（显示 name(repo-id)；否则 repo-id）
  • 远端仓库可删除，默认名字为本地显示名字
• 本地仓库详情
  • 可修改本地名称但不实际修改文件夹名
  • 移除仓库：详情按钮后“从仓库列表中移除当前仓库”，二次确认并删除根目录 .mynote
• 批量检查当前仓库的 broken links 失效链接（reveal files in system explorer）

八、文件管理

• .app 文件不解析内部结构和同步内部内容，左侧文件树也不解析
• MAX_TREE_FILES 控制实际需要同步的文件数量（含图片等），而非已访问文件数量
• 文件搜索 quick open
  • 类似 vscode 快捷打开文件面板，快捷键 ctrl/cmd + p
  • 中文输入法组合文字时 Enter 和方向键由输入法处理，不误选
  • 支持限定项，冒号识别特征（p: 完整路径、f: 文件名，@、@!、@@）
  • 空格用引号包裹表示“与”关系（p:"abc efg"）
• find/search/replace in files 多文件搜索/替换
  • alt + enter 在编辑器中打开搜索
  • 高亮全部匹配结果
  • workspace search editor、动态查询、replace in files
• 标签管理
  • 已打开文件与当前仓库关联，切换仓库切换已打开文件
  • 全部关闭、关闭其他
  • ctrl + tab 切换标签（↑↓ 不传递到编辑器/预览造成滚动）
  • 上下一个标签：mac cmd shift + [/]，win ctrl pagedown/up
  • 标签隔离、独立不共享（编辑页面多标签不共享，避免滚动到底部、undo/redo buffer 清空）
  • pinned/normal/preview tab/editor（转换、pinned 不被全部关闭、normal 不降级、pinned 需重复关闭）
  • alt + 数字 跳转对应 tab（1-based）
• 复制（相对）路径：左侧文件树、tab 菜单同时支持
• 左侧文件树
  • 关联当前页面、操作菜单、冲突标记/解决/外部工具、路径复制、tooltip 显示快捷键
  • 标题栏增加全部展开/折叠、新建文件/文件夹/刷新、显示空文件夹选项
  • 文件树遍历：右键前后遍历（时间过滤掉的不参与），通过 preview 打开，快捷键 alt + page up/down，支持折返
  • 支持拖拽移动文件，加 ctrl/cmd 为复制（可拖到文件上取 parent 为目标文件夹）
  • 定位文件 reveal in file explorer：shift + alt + R
• 单文件历史：从同步中心“最近版本”抽取公共代码，命令面板支持；处理删除后重新创建
• 打包文件
  • 左侧文件树工具条时间过滤按钮旁加打包按钮，弹出对话框展示文件数
  • 每个文件/文件夹复选框，默认全部勾选；点击文件夹切换自身及递归子孙
  • 按钮旁复选框默认选择，选择则在每个文件头部插入相对路径，prefix 为 // =======
  • 支持命令面板、全选/取消全选/全部折叠展开/点击文件夹折叠/刷新
  • 每行加入行号
  • 用于给 deepseek 等 AI 提问
• 文件过滤器
  • 配置写入 repository-ui-state-v1.json，按笔记库隔离
  • 构建时将 ignore 单文件模块包装为浏览器 ESM
  • TODO：筛选逻辑复杂需优化

九、.mynoteignore

• 支持 ignore（类似 .gitignore），也需要同步
• 改为：已加入管理的文件不受影响，只影响新文件是否加入同步管理和左侧文件树显示

十、mermaid 流程图

• 长文本正常显示
• 渲染失败问题：Could not find a suitable point for the given distance
• 点击 tab 预览页重绘晃动

十一、server export tool

• script 文件夹下 Node.js 小工具，参数：用户 ID、仓库名/ID、输出路径
• 服务器端执行，无需密码直接访问仓库数据
• 已 clone 则同步到最新
• 提供环境变量与命令示例

十二、问题记录

• 退出差异模式后大纲未更新
• 其他设备修改时，文件历史和同步中心版本详情未加载最新，但编辑器内容最新
• 同步中心最近版本差异框复制（mac 下不行）
• 按修改时间过滤弹窗“比较整个文件树”需记录状态
• Windows 移除仓库或新 clone 后仓库下拉框不能点击展开（根因：window.confirm/window.alert 抑制原生下拉）
• 几个滚动到顶部的问题（quick open 定位、切换标签、回车等）
• alt + pagedown/up 连续输出字符
• 编辑器 alt + n 跳转下一处差异失效（中文输入法）
• 编辑时连续切换视图再回编辑界面 caret 丢失
• 搜索匹配算法与拼音支持
• 大小写敏感、全字匹配（搜索全文/当前文件支持）
• 大纲搜索 @pinned 命中原因（拼音模糊匹配、字母不连续；全拼可依次找到 p-i-n-n-e-d）
• 搜索历史（存储位置 mynote.page-find-history.v1、mynote.workspace-search-history.v1；quick open 和命令面板也支持历史，ctrl/cmd + ↑↓ 选择）
• 快捷键带入选择文本（页内、in files 有选择则带入输入框）

十三、文档链接

• 给精炼文档添加链接指向细节文档（位置在 docs-mynote-client 下）

十四、窗口管理

• Ctrl/Command+Shift+S 系统级热键切换主窗口显示状态（显示且非激活时 bring to top，而非隐藏；改为最小化而非隐藏）
• ctrl + shift + alt + s（win/mac 相同）：在当前已打开窗口中切换
  • mac 原生可用 cmd + \``，win 可用 ctrl + 点击窗口图标`
  • 注意是快捷键不是热键，只有一个窗口时功能同 alt+Shift+S
• 支持新建窗口，打开不同笔记库
• 实现 vscode 类似 file - open recent（统一 ctrl + r，数量无限制）
• 新打开（或切换）窗口后，当前标签是编辑器则聚焦
• 启动时恢复上次关闭时打开的多个仓库（窗口）
  • 需要 exit 方式退出，一次性关闭多个窗口不行

十五、window.alert / window.confirm 全部替换

• 用应用对话框替换（点击后编辑器失去焦点问题，Windows 需切换窗口再切回）

十六、Command Palette 命令面板

• 搜索历史
• 显示快捷键
• 面板关闭后 textarea/input 的 caret 恢复（quick open 面板同样处理）
• 每条目最右侧设置图标，点击打开快捷键设置并定位当前条目（ctrl/cmd + enter）
• 查找哪些命令未包含在 command palette（vscode open）
• 命令面板支持拼音搜索
• 底部 Checkbox 隐藏不可用命令，默认关闭；不可用命令置灰，选择时提示原因
• 命令面板历史记录工具条
  • 每次访问命令形成历史记录工具条，插入到第一条
  • 自动生成 emoji 图标，用户可自定义
  • 每条记录可 PIN 到最左边
  • alt+shift+h 后紧跟数字按键对应历史命令
  • 工具条跟随鼠标，停止移动一秒后出现在鼠标正上方居中；可关闭，再通过菜单栏或命令面板显示
  • 存储到 appdata
  • 关闭按钮旁 pin 按钮，默认选择，固定位置始终显示（初始顶部正中，可拖动）

十七、menu 菜单

• 工具栏增加对应菜单并添加快捷键（参考 vscode 惯用快捷键）
• menu-file：exit（ctrl/cmd + q，加入命令面板）
• menu-view：zoom in/out、自动换行 word wrap（参考 VS Code）

十八、状态栏

• 显示 caret 所处行列，有选择则加选择长度

十九、侧栏 sidebar

• 侧栏分区优化：每个分区可折叠展开，分区标题字体加大（参考第一个分区样式）

二十、repo ui state data 仓库界面状态数据

• 存 appdata 下而非 localStorage
• 时间排序、文件组织记录
• 文件树关联当前页面从设置中迁移

二十一、tooltip 300ms 原生替换

• 全局覆盖现有及动态 Tooltip
• 键盘聚焦时立即显示
• 自动避开窗口边缘
• 避免与原生 title 提示重复

二十二、设置 settings

• 设置广播：任一窗口保存普通设置后主进程立即广播所有窗口，其他窗口无需打开设置即生效；之后打开加载最新值；已打开且正在编辑的草稿不被覆盖（后续云同步改为按修改单元粒度合并）；保留“显示空文件夹”等仓库级设置不受全局广播影响
• MAX_TREE_FILES 改为可配置

二十三、云同步（条目存在，内容为空 ==）

二十四、时间过滤 & 差异 diff

• 时间过滤：默认不过滤，点击弹界面输入日期，下拉最近一天/七天/一个月/两个月/三个月/半年，日历指定日期，重置按钮
• 文件修改时间从仓库查询 + 文件实际修改时间，二者选最老
• 过滤面板文件差异选项：默认“不显示差异”；“同上”用淡绿色高亮最近指定天数改动行；“其他”另展一套时间选择
• 截止时间早于首个历史版本时以空内容为基线，差异为整篇
• 时间格式化从 2026/9/12 8:19:56 调整为 2026-09-12 08:19:56
• 误差 1 秒以内版本视为“在截止时间之前”
• 文件修改时间统一规则（mynote 仓库历史最近修改时间与文件实际修改时间取最老；提取为函数）
• 时间、时间差解析
  • 纯数字按天：0.5、.5、1e1
  • 单位间隔：ms、s、m、h、d、w
  • 支持组合：1d 12h、2h30m
  • 支持 ISO 8601：PT1H30M
  • 支持本地时间点：2025-3-1 12:0（按当前系统时区转换）
  • 文件过滤和文件差异过滤均支持
• 修改时间不依赖 git，用 mynote 仓库历史版本时间
  • 边界：无可用 mynote 历史时间时真正回退到文件时间；目标时间之前没有历史版本时差异基线视为当前内容（零差异块）
  • 日历控件无法显示，点击无效果
  • 用户可手动指定时间段，输入可为小数
• 上、下一处差异定位
  • 过滤选择记录并恢复
  • 快捷键 alt + n/p
  • 所有相邻差异算一处，跳过相邻差异
  • 不要循环折返
  • go 菜单加入入口
• 切换差异模式
  • 进入时关闭预览、大纲，最大化编辑器，进入只读；仅当前文件；状态持久化
  • 修改行紧邻显示（老版本行 + 新版本行；逐行显示，删除行无新行，增加行无老行）；同步中心也改为这种显示
  • 快捷键 alt + shift + d
  • alt + n/p 失效问题修复
  • 隐藏编辑器光标位置，退出差异模式后位置保持一致
  • Ctrl/Command 加双击切换回编辑页面并定位到双击行号
  • 只有一处差异时也能滚动到视图
• 相似度匹配：对应行未对应上的情况（a/b vs a'/c/b'）应正确匹配并计算差异
• 差异行分块差异 highlight inline diff changes（匹配行标识增删部分，删除红色块、增加绿色块）
• 大文件差异算法优化
• 与 git HEAD 版本比较（文件差异选项加入 Git HEAD，作为默认值；git commit 更新后基线跟随变化；支持老版本 git）
• 单文件历史和版本详情都加入与当前版本比较
  • 与上一版本比较 / 与当前版本比较
  • 按文件 ID 跟踪重命名后的当前路径
  • 当前文件已删除时显示完整删除差异
  • 每次切换到当前版本重新读取
• 文件树比较
  • 时间过滤对话框底部按钮，按指定时间计算版本与当前版本针对整个文件树差异
  • 新对话框类似文件历史，标题行展示相对路径，展开显示差异
  • 顶部全部折叠/展开，默认全部展开
  • 每个标题栏“跳转到对应文件”按钮
  • View 中入口，对话框关闭/跳转只是隐藏，再次打开显示上次内容；快捷键 ctrl/cmd + alt + d
  • 可在对话框中重新设置时间
  • 也支持 git HEAD
• 历史版本本地保存：每次同步将所有历史版本记录同步到本地，差异比较从本地获取，不做服务器请求
• log（终端和开发者工具）
  • [mynote:file-diff:renderer]：请求、缓存命中、差异行数、差异块数及耗时
  • [mynote:file-diff:main]：目标时间、历史 revision、基线来源及内容长度
  • [mynote:file-diff:history]：仓库 ID、文件 ID 和历史版本查询结果
  • 不输出笔记正文
• 差异参数便捷切换
  • 按钮依次切换选项，支持命令面板触发和快捷键配置
  • 每次切换加载上次状态（如“其他-自定义时间-3天”）
  • 不弹窗直接应用，更新编辑器视图
  • 状态栏显示当前选项
  • workspace.cycleFileDifferenceMode
• other：文件差异选其他、差异时间选指定时间时输入框超出范围看不到

二十五、CodeMirror 迁移（codemirror-migration.md，2026-9-13）

二十六、misc

• json 保存时统一格式化（如 repository-ui-state-v1.json）
• createElement 改造（缩进表示嵌套、innerHTML 方式未处理、TODO 数据驱动重构）
• userData 路径（mac / win）

二十七、export/save as html & txt

• 支持嵌套、继承 parent 配置
• 同步时的修改也自动导出
• 配置项：html_root、css_root、txt_root、publish_root、extra_js、extra_css
• html 版本：html_root 配置则每次保存另存 HTML 版本；publish_root 发布到服务器根目录，链接加根目录；HTML 内容与预览一致（除链接调整）
• txt 版本：txt_root 配置则每次保存另存 txt（innerText，不是 md 文本）
• 支持 extra_js/extra_css 配置（多个用 : 分隔）
• 支持 extra_js_content/extra_css_content 配置（直接以内容注入）

以上为 docs-mac/mynote-client.md 文件中以标题/条目形式出现的 mynote-client 功能点。部分条目（如“云同步”）在文件内仅有标题，正文内容未在文中给出，因此未展开。