用户指南¶

本文面向使用随手记 Sui 的用户：从安装客户端、连接服务端，到日常记笔记、多端同步与 版本恢复。服务端部署见部署指南，网页剪藏见网页剪藏。

1. 整体概念¶

随手记 Sui 采用「本地优先 + 自托管服务端」架构：

• 本地优先：所有笔记保存在设备本地（SQLite），不联网也能正常查看、编辑、搜索。
• 自托管：同步服务端跑在你自己控制的机器上（家里的电脑、NAS 或云服务器），数据完全归你所有。
• 多端：手机、平板、电脑、浏览器（Web）使用同一套笔记，通过服务端同步保持一致。

关键术语：

2. 安装客户端¶

2.1 运行 Flutter 客户端¶

客户端不预设服务端地址，地址在应用内的「同步设置」里填写（见 §2.3）。

cd clients/flutter_app
flutter run -d chrome    # 浏览器（Web，本机已验证可运行）
flutter run -d windows   # Windows 桌面（需在 Windows 宿主构建）
flutter run -d linux     # Linux 桌面（需 clang / ninja-build / pkg-config / libgtk-3-dev）
flutter run -d android   # Android 手机 / 平板（需 Android SDK + 连接设备）

六个平台目录（web + 桌面/移动五端）均已随仓库提供，无需再执行 flutter create； 能否运行只取决于本机是否装了对应工具链。Web 端最省事，适合先跑起来体验。

2.2 客户端界面¶

桌面 / 平板宽屏下为三栏布局：

┌─────────────┬──────────────┬──────────────────────┐
│ 笔记本树     │ 笔记列表      │ 编辑区（Markdown 三态） │
│ ├ 全部笔记   │ · 笔记 A     │                      │
│ ├ 收件箱     │ · 笔记 B     │  格式 / 源码 / 预览    │
│ ├ 工作       │              │  历史 / 导出 / 删除    │
│ │ └ 项目A    │              │                      │
│ └ 生活       │              │                      │
│ 标签: #xxx   │              │                      │
└─────────────┴──────────────┴──────────────────────┘

手机窄屏自动切换为抽屉式导航，点击左上角菜单展开笔记本树。

桌面端专属（v0.8.0 / M7）：

• 折叠面板：顶栏左上角的折叠图标按钮可分别收起 / 展开左栏（笔记本树）与中栏（笔记列表）， 折叠后该面板与其分隔线一并消失，得到纯编辑区沉浸写作；折叠状态是本机视图偏好，重启后保持且不同步。
• 菜单栏：顶栏「文件 / 编辑 / 视图 / 同步 / 帮助」五个菜单（「同步」为 v0.12.0 新增）， 菜单项与顶栏图标按钮、编辑快捷键同源——不可用命令置灰，有状态命令（如面板显示）显示 勾选，快捷键以右侧提示呈现。「文件 → 退出」会先落库再退出，避免丢失未保存内容； 「同步 → 全部重新同步」见 §4.5。
• 查看版本号：菜单「帮助 → 关于随手记 Sui」会显示当前版本号（反馈问题时请一并提供）； 窄屏移动端与 Web 端在顶栏「更多」菜单里可打开同一份「关于」（v0.12.1 / FR-56）。
• 编辑三态：编辑区提供「格式 / 源码 / 预览」三态切换，编辑模式同样重启后保持。

以上折叠开关与菜单栏仅在桌面端（Windows / macOS / Linux）渲染，窄屏移动端与 Web 不显示，行为不回归。

桌面端专属（v0.9.0 / M8）：独立笔记窗口

• 在独立窗口打开：选中一篇笔记后，从菜单「文件 → 在独立窗口打开」或笔记列表项的右键菜单 选择「在独立窗口打开」，该笔记会在一个独立 OS 窗口中打开。主窗口照常保留这篇笔记的编辑面， 两处指向同一条笔记、共享同一份 Markdown 正本，两边编辑实时互相同步，不会各写各的。
• 一笔记一窗口：同一篇笔记只会有一个独立窗口，列表项上会标出「独立窗口」标识；再次打开同一篇笔记 只是聚焦已开的窗口（若已最小化会先还原），不会重复弹窗。
• 窗口各记各的编辑模式：每个窗口的「格式 / 源码 / 预览」模式互相独立、各自记住并在重启后 保持；而当前选中的笔记本、搜索关键字、标签筛选等仍为全局，独立窗口不会打乱主窗口的浏览位置。
• 关闭与退出：关闭某个独立窗口即释放它；当所有窗口（含主窗口）都关闭时会退出应用；菜单 「文件 → 退出应用」会先落库、再尽力推送后关闭全部窗口退出，避免丢内容。

独立窗口仅在桌面端（Windows / macOS / Linux）可用；移动端与 Web 不显示该入口，行为不回归。

2.3 连接服务端（首次配置）¶

客户端开箱即用（纯本地也能写），要同步才需要连服务端。点顶栏的云图标 /「同步设置」 打开对话框：

配置会存入本机数据库，重启后仍在，之后编辑自动防抖推送。若地址为空或未建立登录会话， 状态会停在「未连接」（v0.12.2 起判据由「Token 为空」改为「无有效会话」）。

3. 日常使用¶

3.1 新建笔记¶

1. 点击笔记本树右上角「＋」→ 选择笔记本（或留空放「全部笔记」）。
2. 输入标题与正文，正文使用 Markdown 语法。
3. 内容自动保存（无需手动点保存）。

3.2 Markdown 三态编辑¶

Markdown 是笔记的唯一正本，编辑区提供「格式 / 源码 / 预览」三态切换（窄屏下三态以图标呈现）：

• 格式：所见即所得的格式化编辑，改动即时回写 Markdown。Markdown 记号本身不可见—— **加粗** 只显示加粗文字、## 标题 只显示放大标题、- 项 显示为「• 项」、任务项显示为勾选框、 > 引用 显示为左侧竖条、--- 显示为水平线、链接只显示文字；未识别的记号（如落单的 **）仍原样显示。
• 源码：直接编辑原始 Markdown 文本（记号可见、可逐字符改）。
• 预览：查看渲染后的最终效果。
• 支持：标题 #、列表（无序 / 有序自动编号）、链接、图片、粗斜体、删除线、高亮、引用、代码块、表格、任务列表、附件胶囊等常见语法。
• 格式单元是「整体」：光标不会停在记号内部（自动跨过）；退格 / 删除落在记号上时一次取消整处格式 而内容保留（**粗** → 粗、## 标题 → 标题），空勾选框行按退格即退出列表；表格行永不与相邻 文字合并——删除紧贴表格的勾选框时表格逐字不动、仍以表格呈现。
• 缩进只产出合法结构：孤立勾选框行最多缩进到 3 个空格（再缩进不变），有父列表项时缩进为嵌套； 不会再出现「右缩进后预览显示成字面量 [ ]（缩进代码块）」。

格式工具栏（格式模式下可用）按使用频度从左到右排列：加粗 / 勾选框 / 撤销 / 重做 / 斜体 / 删除线 / 高亮 / 列表 / 缩进 / 引用 / 代码块 / 表格 / 链接 / 插入图片 / 附件 / 分割线 / 简化格式 / 标题一~三。 把鼠标停在按钮上即可看到它对应的快捷键（如「加粗 (Ctrl+B)」「表格 (Ctrl+Shift+T)」）；没有快捷键的按钮（插入图片 / 附件）只显示名称。 常用操作均有快捷键（Ctrl+B 加粗、Ctrl+K 链接、Ctrl+V 富粘贴、Ctrl+Shift+V 纯粘贴、Ctrl+Shift+T 插入表格等）。

插入超链接：选中要作为链接的文字（可留空）→ 点工具栏「链接」或按 Ctrl+K → 在弹框里填「显示文字」与「网址」→「插入」。 网址不写协议会自动补 https://（mailto:、#锚点、/相对路径 等写法保持原样）；网址留空时「插入」不可用，不会改动笔记。 表格单元格里也能插链接：单元格上下文栏有「链接」按钮；若光标正在某个单元格里，直接点工具栏「链接」也会写进那个单元格（以软换行追加，其余单元格不动）。

3.3 管理笔记本与标签¶

• 新建笔记本：笔记本树底部「＋ 新建笔记本」。
• 嵌套：在笔记本上右键 / 长按 → 新建子笔记本。
• 标签：编辑器中输入标签回车即可添加，点标签可在全局过滤。

3.4 搜索¶

顶部搜索框输入关键字，即时匹配标题与正文，全局范围（也可先选中某个笔记本再搜索）。

当前为 LIKE 子串匹配，FTS5 全文搜索仅架构预留、未启用。

3.5 置顶 / 归档 / 删除¶

• 置顶：列表项右上角图钉，置顶笔记排在最前。
• 删除：编辑器右上角垃圾桶；删除为软删除（墓碑），多端同步后保持一致。

3.6 附件¶

添加：打开笔记 → 格式工具栏的回形针图标（「附件」）→ 弹出附件面板 → 点「添加附件」 选择文件（可多选）。附件会挂到这篇笔记上，并在正文中以独占段落自动插入一行 ![文件名](sui://<sha256>)——图片作为块级内容插入，其下方文字整体下移、光标可正常越过； 图片类附件在「格式」/「预览」模式下会直接渲染出来。

查看：点格式工具栏的「附件」按钮打开附件面板，面板内列出该笔记的全部附件，点击卡片即可 打开（本机没有字节时会自动从服务端下载并缓存）。

移除：卡片右侧的 ✕。移除只是解除这篇笔记的引用，不会影响其他笔记对同一附件的引用。

每张卡片会标出该附件当前的可用性：

关于存储占用：附件字节不会全部下载到每台设备，只有你真正打开过的才会缓存到本地， 且总量受「缓存上限」约束（默认 512MB，可在同步设置里调整）。超出上限时，最久没打开、 且没有被任何笔记引用的附件会被自动清理，再次打开会重新下载。

因此同一附件在多篇笔记中被引用时，本地只会存一份（按内容去重）。

预览与外部编辑回写：

• 在附件面板点击附件卡片，弹出预览弹窗——文本文件可直接阅读（长文截断）、图片可缩放查看、PDF 与其他类型显示文件元信息。
• 预览弹窗中「用系统默认应用打开」会调用本机默认程序打开附件。外部编辑保存后，Sui 会自动检测文件变更并回写：生成新的 sha256 → 更新正文里的 sui:// 引用 → 上传同步到服务端，换台设备打开即可看到最新版本。

3.7 表格编辑¶

格式模式下，点格式工具栏的表格图标（或按快捷键 Ctrl+Shift+T），弹出「插入表格」对话框：

• 输入行 / 列数（默认 3×3，上限 20×20），点「插入」即可在光标处插入一张 GFM 管道表。
• 表格呈现为独占块，直接点击单元格即可编辑内容，按 Tab 键跳到下一个单元格。
• 鼠标悬停在表格上时，行 / 列头部会出现「+」「−」按钮，可就地增删行列。
• 源码模式下可直接编辑原始 Markdown 表格文本，格式模式与预览模式会同步渲染。

表格以 GFM 管道表（| 列1 | 列2 | + | --- | --- |）形式存入 Markdown 正本， 与任何支持标准 Markdown 表格的工具完全兼容。

3.8 粘贴与简化格式¶

粘贴保留格式（Ctrl+V）：从网页 / Word / 其他富文本应用复制内容后，在 Sui 格式模式下直接 Ctrl+V 粘贴， 会自动将 HTML 富文本转换为 Markdown（保留表格、列表、引用、粗斜体、链接、代码块等结构）。 无法识别的格式会降级为纯文本，绝不丢字。

纯文本粘贴（Ctrl+Shift+V）：只粘贴纯文本，且会自动转义 Markdown 特殊字符 （* _ ` # [ ] ( ) 等），避免意外触发格式渲染。

简化格式：选中一段文字后，点工具栏的「简化格式」按钮（或按 Ctrl+Space）， 会剥离全部行内格式（加粗、斜体、删除线、高亮、行内代码），但保留块级结构 （列表、引用、代码块、表格）。可用于清理从别处复制来的杂乱样式，快速统一为纯文本内容。

3.9 有序列表自动编号¶

在 Markdown 正本里，有序列表统一写 1.（「懒编号」风格）——格式模式与预览模式会自动按 DOM 顺序 渲染为 1. / 2. / 3. 的连续编号。这样做的好处：

• 增删条目不用手动改编号：在中间插入或删除一行，后续编号自动重排。
• 空行隔断编号重启：两个有序列表之间隔了空行或其他内容，编号会从 1 重新开始。
• 源码模式不受影响：你仍然可以在源码模式里手动写 1. 2. 3.，格式模式同样能正确渲染。

快捷键：Ctrl+Shift+O 切换有序列表。

3.10 加密笔记本（锁定密码保护）¶

把某个笔记本设为加密笔记本后，其中笔记的标题与正文在本机加密后才落库、才上传—— 服务端全程只见密文、无法解密（这也是「服务端搜不到加密笔记本内容」的原因）。

• 设置：对笔记本启用加密 → 设置锁定密码（独立于登录密码，只在本机校验，不会上传）。
• 解锁：打开加密笔记本内的笔记时要求输入锁定密码；解锁后查看与编辑体验与普通笔记一致。
• 回锁：顶栏「立即锁定」手动回锁；15 分钟无操作也会自动回锁（之后需重新输入密码）。
• 未解锁时：列表显示「🔒 加密笔记」占位，不进编辑、不纳入搜索；笔记本树上有锁标记。
• 跨端：密钥不随同步——在另一台设备上首次查看同样要输入锁定密码（各端各自解锁）。
• 多端同步：加密笔记照常参与同步与冲突合并；未解锁的设备不会就地合并（保持排队， 由已解锁的一端完成合并），绝不丢字。

⚠️ 锁定密码无法找回：服务端没有它，也没有任何后门。忘记密码意味着该笔记本内的内容 永久不可读——请在设置后立即妥善保存（例如写进密码管理器）。

3.11 本地存储位置（桌面端，v0.12.2 / FR-58）¶

「同步设置 → 本地存储」显示当前数据目录与占用（库 / 附件），并可：

• 打开所在文件夹：在系统文件管理器里定位数据目录；
• 更改位置…：把本地库与附件缓存迁移到其它目录（例如大容量数据盘）。

迁移流程：选目录 → 前置校验（同路径 / 已含数据会被拒；非空目录需确认）→ 确认（列明将迁移的 内容与占用）→ 进度（落盘 → 复制库 → 复制附件 → 校验 → 切换）→ 完成后提示重启生效。

要点：

• 旧数据会保留在旧目录，确认新位置一切正常后再手动删除；
• 迁移失败时仍使用旧位置（指针不切换），界面给出失败原因与重试入口；
• 迁移不改变服务端数据、登录会话与同步状态，不会触发换库流程；
• 若数据目录放在外置盘 / 网络盘，未挂载时启动会整屏阻断并让你三选一 （重试 / 改回默认目录 / 重新指定路径）——不会静默换目录，也不会删你的数据。

4. 多端同步¶

4.1 同步时机¶

• 客户端本地变更（新建 / 编辑 / 删除）立即在本地库中记成「待上传」——上行队列就是库里的 状态本身，所以重启应用、甚至换了服务端，未上传的意图都不会丢；停止输入约 0.7 秒后自动推送。
• 服务端有变更时通过 WebSocket 通知各客户端，触发增量拉取。
• 另有 30 秒周期兜底同步：断网期间积压的改动、或 WS 断开时的变更，恢复网络后 无需你再动一次手也会自动补上；空闲时几乎无网络开销。

4.2 冲突处理（无需用户干预）¶

当两个设备同时编辑同一篇笔记时：

1. 服务端以 base_version 判定冲突。
2. 后提交的一方收到冲突响应，本地自动启发式合并：
3. 标题：取较新的一方。
4. 正文：合并双方内容，冲突段落以标记分隔，绝不丢字。
5. 合并结果自动重发，最终各端一致。

4.3 离线使用¶

离线时一切功能正常（查看、编辑、搜索），改动都会记账在本机（状态显示「待上传」；若从未连过 服务端则是「仅本地」）；恢复网络后自动推送，服务端会以服务器时间线对齐合并。

附件有两点例外：

• 未缓存到本机的附件离线打不开（卡片显示「未下载」），联网后点击即可下载。
• 离线时新添加的附件仍会成功挂到笔记上（卡片显示「待上传」），联网后自动补传。

4.4 同步状态怎么看¶

每篇笔记、每个笔记本的条目上都带一个同步状态图标，「哪些还没到云端」一眼可辨：

把鼠标停在图标上（手机窄屏长按）就能看到具体缘由，例如「仅本地：云端没有该实体（该笔记本只 存在于本机）」「同步失败：Connection refused（10-09 21:14）」。窄屏下图标收缩为一个小圆点， 颜色含义不变。

还没在「同步设置」里连上服务端时，本机条目一律显示为仅本地的弱化样式：此时「已同步」 没有意义，界面不会假装已同步。

4.5 单个重新同步与「全部重新同步」¶

• 单项重试：某一条笔记 / 笔记本卡住时，用它的「立即上传 / 重试」——笔记列表的行尾菜单 （或右键菜单）里就有这一项，笔记本节点菜单里也有同一项（已是冲突的项，入口显示为 「查看冲突 / 合并」）。它只影响这一项，不动其它数据、也不打断你正在编辑的内容。
• 全部重新同步：对云端与本机的全部数据做一次「核对 → 补齐」——云端没有的本机条目补传 上去，云端更新的条目拉下来，两边都改过的走既有自动合并（绝不丢字）。入口有两处、同一实现： 桌面端菜单「同步 → 全部重新同步」，以及「同步设置」对话框里的「全部重新同步」面板 （未连接服务端时置灰）。过程可取消、可重复执行（幂等），并给出进度、逐项结果与失败原因； 失败项可以单独重试，也可以「重试全部失败项」。
• 什么时候用：换了电脑 / 重装客户端后数据对不上、怀疑有内容没同步、或从「仅本地」的提示中 恢复时。
• 首轮核对会从云端拉一遍完整数据（含正文），笔记很多时会慢一些；这是一次性的。

4.6 更换服务端 / 服务端重建后（换库提示）¶

客户端会记住「原来那份云端数据」的身份（云端实例标识）。当你换了服务端地址、换了数据目录， 或服务端被重建 / 回滚时，它会发现「云端已经不是原来那一份」，弹出标题为 「云端数据已更换 / 重建」的对话框，列出「本机记录」与「云端」两边的实例标识， 让你决定怎么办。在你做出选择之前，客户端不会上传、也不会清空任何一端的数据：

⚠️ 「以云端为准」不等于删数据——本机独有的笔记 / 笔记本仍完整保留在本机，只是状态变成 「仅本地」，界面会一直提示你它们还没到云端。

5. 版本历史与恢复¶

5.1 查看历史¶

1. 打开一篇笔记，点击编辑区右上角「历史」图标。
2. 弹出「版本历史」面板：列出该笔记的所有修订（时间、来源设备）。桌面宽屏在右侧栏呈现， 手机等窄屏（Android / iOS）整页推入，能力一致。
3. 点击任意版本，下方展示该版本的 Markdown 内容。
4. 看完后按返回键回到编辑页（先关闭历史面板，再按才退出编辑返回笔记列表）。

5.2 恢复历史版本¶

1. 在版本历史面板选中目标版本。
2. 点击「恢复此版本」，确认。
3. 恢复以新修订形式追加（不重写历史），当前内容变为所选版本内容，原历史完整保留。

说明：历史记录以服务端合并记录为准，所有端看到的历史一致；本地未同步的编辑在同步后 并入服务端时间线。

6. 数据导出¶

1. 打开笔记，点击编辑区右上角「导出」图标。
2. 弹窗预览完整 Markdown（含标题），点击「复制全部」。
3. 粘贴到任意 Markdown 编辑器 / 文件即可。

7. 遇到问题？¶

见故障排查。