格物 Lattice 操作说明书

版本 0.1.3 · Windows 桌面发行版

一个本地优先的双链笔记知识库。所有笔记都存放在你自己的电脑上，不注册、不云同步； 不配置外部模型时完全离线，AI 功能只有在你主动填写并使用模型时才会联网（详见附录：关于隐私）。

---

一、安装与启动

1.1 两个版本怎么选

建议：日常使用选安装版；需要随身携带或想「一份文件夹 = 一套运行环境」选绿色版。

1.2 安装版

1. 双击 Lattice-0.1.3-setup.exe。
2. 安装向导可自选安装目录；默认装在当前用户目录下，因此不会弹 UAC 提权框。
3. 安装向导会提供创建桌面快捷方式与开始菜单项的选项（默认勾选）。
4. 完成后从桌面或开始菜单启动「格物 Lattice」。

1.3 绿色版

1. 把 Lattice-0.1.3-portable.exe 放到一个你有写权限的文件夹里（例如 D:\Tools\Lattice\）。
2. 双击运行。首次启动会在同级目录自动建出 LatticeData\。

不要把绿色版直接放进 C:\Program Files\ 这类只读位置——写不进去时它会自动把数据回退到 %APPDATA%\Lattice\，这样就不再「便携」了。真遇到这种情况，日志里会有记录。

1.4 首次启动会发生什么

• 会弹出系统文件夹选择框，让你指定一个文件夹作为知识库（Vault）。可以选一个空文件夹， 也可以选一个已经存放 Markdown 的文件夹。此后每次启动都直接打开这个库。
• 选定后自动建库并执行数据库初始化，无需任何其他手动配置。
• 不会自动写入示例知识库。Vault 为空时保持为空，避免应用擅自修改你选择的文件夹。
• 可以直接把已有 Markdown 文件复制进 Vault，应用会在启动和文件变化后自动建立索引； 单文件改动只做增量同步，不会每次都全库重建。

启动时窗口会短暂延迟出现（先起本地服务、加载页面，再显示窗口，避免白屏闪烁）。 正常情况下 1–3 秒内完成。

想更换知识库文件夹：在「设置 → 知识库位置」中重新选择，应用会自动重启加载新目录。

1.5 启动时的几个行为约定

• 单实例：软件同时只允许开一个。重复双击不会开第二个，而是把已有的窗口拉到最前面。
• 关窗即退出：没有托盘常驻，关闭窗口等于完全退出，本地服务同时停止。
• 本地端口：内部服务优先绑定 127.0.0.1:5188；若被占用会自动改用系统分配的随机端口， 不需要你干预，也不会和别的东西抢端口。
• 不对外暴露：服务只监听 127.0.0.1，局域网内其他机器访问不到。
• 关联打开 .md：在资源管理器中双击 Markdown 文件，可以选择用 Lattice 打开 （详见 3.12）。

---

二、界面导览

窗口默认 1280×820，最小可缩到 940×600；窄屏下侧边栏会自动改为抽屉式，功能不会丢失。

┌───────────────────────────────────────────────────────────────────────────────┐
│ ⬚ Lattice │ ➕新建  📥收集  📁笔记  ⌗图谱  ▦画布 │ ⬜新白板  🔍快速切换  ✦AI │ ↻ ◧ ◐ ⚙ │
├───────────┴───────────────┬───────────────┬───────────────────────────────────┤
│ 侧边栏                    │ 笔记列表      │ 标签页栏（打开的笔记 / 画布）       │
│                          │               ├───────────────┬───────────────────┤
│ 全部笔记                 │ 🔍 全文检索…  │ 标题           │ 状态  工具         │
│ Inbox                    │ 标题 + 摘要   │ 编辑 / 分栏 / 预览                 │
│ 目录树（含画布 / 附件）   │ 标签 / 反链数 │ 属性 / 大纲 / AI 写作              │
│ 标签云                   │ 置顶标记      ├───────────────┴───────────────────┤
│ 统计                     │               │ 关系面板（可收起）                  │
│ 🗀 仓库切换器             │               │ 出链 / 反向链接 / 悬空              │
├──────────────────────────┴───────────────┴───────────────────────────────────┤
│ 状态栏  N 篇笔记 · M 条链接          当前：xxx          ● 已连接              │
└───────────────────────────────────────────────────────────────────────────────┘

2.1 顶部功能区

窗口最顶部是一条水平 Ribbon，从左到右依次为：

2.2 侧边栏

侧边栏顶部有一排小工具：新建笔记、新建目录、切换排序、刷新、收起侧边栏。

下方依次是：

• 全部笔记：取消一切筛选，回到完整列表，右侧显示笔记总数。
• Inbox：收集箱入口，右侧徽章显示待整理数量（见 3.17）。
• 目录树：任意层级嵌套，其中同时显示 Markdown 笔记与 .canvas 画布文件 （打开「附件显示」后还包括非笔记文件）。悬停或右键可以就地重命名、新建子目录与笔记、 移动、复制（创建副本）、收藏目录、复制相对 / 完整路径、用系统默认应用打开、在资源管理器中显示等。
• 标签云：点标签即筛选出所有带该标签的笔记；区块可折叠。
• 统计：笔记、目录、标签、链接数量与总字数；底部还会列出「待补全的引用」（悬空链接）。
• 底部仓库切换器：常驻显示，点击可在「最近打开」的仓库间切换，或选择「管理仓库…」 查看、打开、新建其他仓库；切换 / 打开仓库后应用自动重启。

侧边栏收起后，最左缘会保留一条细轨，点一下（或按 Ctrl + B）即可展开。

2.3 笔记列表与全文检索

• 列表顶部是全文检索框，输入即搜（有防抖），右侧 × 一键清空；检索时列表切换为 「检索结果」模式，命中片段带关键词高亮，右上还会标明本次走的是 FTS5 全文索引 还是 LIKE 匹配。
• 非检索状态下可在右上角切换排序：最近更新 / 创建时间 / 标题。
• 每行显示标题、正文摘要、更新时间、字数、标签，以及出链 / 反链数量；置顶笔记排在最前并带 ★。
• 右键笔记卡片可以：打开、置顶 / 取消置顶、创建副本、复制路径、复制双链、删除。
• 笔记很多时列表底部分页，不会一次性渲染全部内容。

2.4 标签页栏

功能区右侧、内容区上方是标签页栏。打开笔记、切换笔记、新建标签页都在这里完成。

• 点击标签切换；× 关闭；标签过多时可横向滚动。
• 右键标签提供完整操作（详见 3.16 标签页右键菜单）： 关闭左侧 / 右侧 / 其他、锁定 / 解锁、收藏、重命名、移动到目录、 复制相对路径 / 完整路径 / 双链、用默认应用打开、在资源管理器中显示、删除文件等。
• 关闭正在编辑、尚有未保存内容的标签前，会先弹出确认。
• 通过系统关联打开的 Vault 之外的 Markdown 文件，也会以独立标签出现（标注为只读或可写）。

2.5 编辑区

• 标题框：直接改，改完自动保存。
• 模式切换：编辑（纯文本）/ 分栏（左写右看，默认）/ 预览（只读渲染）。 分栏模式下两侧滚动位置按比例同步，中间分界条可以拖动调整宽窄（见 2.9）。
• 状态提示：依次显示「已同步 → 有未保存修改 → 保存中 → 已保存」；保存失败会出现明确的 错误条和「重试保存」按钮，而不是静默吞掉。
• 工具按钮：置顶 ★、所属目录移动、插入附件 ↑、导出 HTML ↓、版本历史 ◷、删除。
• 属性：标题下方可折叠的属性区，可以添加、改名、删除笔记的自定义属性（随笔记保存）。
• 文档大纲：正文中的标题会自动生成大纲，点击直接跳到对应位置。
• AI 写作条：编辑 / 分栏模式下常驻正文上方（详见 3.14）。
• 底部字数统计：字数、行数、字符数，以及创建 / 更新时间。

2.6 关系面板

展示当前笔记与其他笔记的关系：

• 出链：本篇正文里 [[引用]] 了谁。
• 反向链接：谁引用了本篇（自动维护，不需要手工登记）。
• 悬空链接：你引用了但还不存在的笔记，点一下就能补建。

2.7 图谱视图

把所有笔记和引用关系画成一张网：

• 节点大小按连接数（度数）缩放，一眼看出哪些是枢纽笔记。
• 鼠标拖拽节点、滚轮缩放、点击节点直接跳到那篇笔记。
• 适合发现「孤岛笔记」（没有任何连接的）和意料之外的关联。

2.8 画布视图

点击功能区的 ▧，或在侧边栏打开任意 .canvas 文件，即进入画布视图。顶部工具栏显示当前画布的 对象数、连接数和选中状态。知识库中可以同时存在多个画布文件，各自独立保存。

画布的完整操作见 3.15 画布（白板）。

2.9 可拖拽分栏布局

目录树、笔记列表、关系面板以及编辑 / 预览分栏之间都有一条细细的分隔条：

• 按住拖动：连续调整宽度，宽度自动限制在合理区间内。
• 双击分隔条：立即恢复默认宽度。
• 键盘微调：先用 Tab 把焦点移到分隔条上，按 ← / → 每次微调 16 px。
• 自动记忆：调整结果会防抖保存在本机，下次打开保持不变。

2.10 底部状态栏

窗口最底部常驻一条状态栏：左侧是全库笔记数、链接数；中间显示当前打开的笔记标题； 右侧是本地服务连接状态（已连接 / 连接中断）。

---

三、日常操作

3.1 新建与保存

• Ctrl + N 新建，或点功能区 / 侧边栏的 ✎。新建笔记默认落进当前正在浏览的目录。
• 自动保存：停止输入约 0.9 秒后静默存盘，不需要手动保存。延迟时长可在 「设置 → 编辑器」中改为 500 ms / 900 ms / 1500 ms，也可以整体关闭自动保存。
• Ctrl + S 可立即保存（比如写完最后一句就想马上落盘）。
• 标题留空时不会提交标题（服务端拒绝空标题），正文照常保存。
• 多窗口同改一篇不会再静默覆盖：每次保存都带版本校验，如果笔记已在其他窗口（或被外部程序）改过，顶部会出现「笔记已在其他窗口被修改」横幅，普通「重试保存」仍带版本校验；只有你明确点「仍要保存（覆盖磁盘版本）」才会强制覆盖。
• 每次成功保存都会自动产生一个版本快照，可随时查看或恢复（见 3.10）。

3.2 双向链接（核心功能）

在正文里用双方括号引用其他笔记：

• 目标笔记不存在时，这条链接会被标成悬空链接，在关系面板里可一键创建。
• 链接是从正文自动解析的，不需要手动维护任何关系表。改了正文，链接就跟着变。
• 被引用的笔记删掉后，指向它的链接会退回悬空状态而不是消失——引用关系不会凭空断掉。
• 在预览或关系列表里点击双链即可跳转；想把链接发给别处，可右键笔记选择「复制双链」。

3.3 嵌入引用

独占一行的 ![[笔记标题]] 会把那篇笔记的内容内嵌显示进来，而不是只给一个链接。

• 支持两级嵌套。
• 会自动检测循环引用（A 嵌 B、B 又嵌 A），不会无限递归。

3.4 标签

在正文里直接写 #标签 即自动归类。支持嵌套写法 #工程/前端、#工程/后端， 侧栏标签云里按层级展示。标签同样是正文派生数据，删掉正文里的标签，归类自动消失。

3.5 快速切换

按 Ctrl + K（或 Ctrl + O）打开快速切换面板，输入标题片段模糊匹配、回车跳转。

目标笔记不存在时可以直接创建——这是最常用的写笔记姿势：想到一个概念， Ctrl+K 输入名字、回车，边写边把新笔记链上。

如果在「设置 → 关于」里关闭了「快捷切换」开关，Ctrl + K 将不再唤起面板。

3.6 全文检索

笔记列表顶部的检索框输入即搜，检索范围是标题 + 正文，结果带关键词高亮， 并标注本次使用的检索策略（FTS5 / LIKE）。

关于中文检索的一个说明：

• 中文采用 SQLite FTS5 + trigram 分词，支持子串匹配——搜「知识」能命中「知识管理」。
• 两个字的短查询会自动改用模糊匹配兜底（trigram 需要至少 3 个字符才能建索引）。 所以「笔记」这种两字词也能搜到，只是走的是另一条路径。
• 搜不到时不要怀疑软件：先试试把关键词写长一点。

3.7 目录与整理

• 目录可任意层级嵌套，可就地重命名、删除、创建副本、整体移动。
• 删除目录不会删除里面的笔记——笔记会自动回到「未分类」，不会丢。
• 在侧边栏目录上右键，可以把常用目录收藏、复制它的相对 / 完整路径、 「在此目录中查找」（自动带筛选并聚焦检索框），或直接在资源管理器中打开。

3.8 主题与外观

点功能区的 ◐ / ☼ 切换浅色 / 深色。选择会记住，下次打开直接生效， 并且首屏渲染前就定好主题，不会出现先白后黑的闪烁。

在「设置 → 外观」中还可以：

• 选择一张 PNG、JPG、WebP、GIF 或 AVIF 图片作为工作区背景，单张图片最大 2 MB。 背景图片只以本机 data URI 形式保存，不会出现在网络请求里。
• 导入 JSON 或 CSS 颜色令牌作为自定义主题，导入时会按 WCAG 规则校验对比度 （正文文本至少 4.5:1、辅助文字至少 3:1），不达标会被拦下；也可以一键恢复默认主题。
• 调整界面密度（紧凑 / 舒适）。

3.9 附件

0.1.1 起，笔记正文支持插入附件。

• 点编辑区工具栏的 ↑ 按钮选择本地文件；图片会以 ![名称](路径) 插入， 其他文件以 [名称](路径) 链接形式插入，插入位置就是当前光标处。
• 支持常见图片，以及 PDF、TXT、CSV、JSON、Word / Excel 文档、常见音视频 （mp3 / mp4 / wav / webm），单个文件最大 25 MB。
• 附件统一保存在 Vault 根目录的 attachments/ 文件夹中，笔记里只保存相对引用， 不会把文件塞进数据库。图片在分栏 / 预览中直接显示。
• 粘贴图片按笔记归组（0.1.3 起）：在笔记里直接粘贴或拖入的图片，自动存到 attachments/<笔记标题>/ 子目录（上传接口带 folder 参数，层级最多 4 层、 路径总长 200 字符内）；用工具栏 ↑ 手动选择的文件仍存 attachments/ 根目录。
• 点击图片放大（灯箱）（0.1.3 起）：分栏或预览中点击任意图片进入全屏查看， 滚轮缩放（20%~800%）、按住拖动平移、双击在适配与原始尺寸间切换，Esc 或单击空白关闭。
• 显示附件开关（0.1.3 起）：「设置 → 知识库位置 → 附件显示」默认关闭， 文件树只显示 Markdown 笔记与画布。打开后，知识库里任意文件夹中的图片、PDF、 Word / Excel、音视频等非笔记文件会立即出现在目录树（带扩展名标签，按所在文件夹归位） 和快速切换器（带「附件」标记）中，关闭即隐藏。树中的附件点击用系统默认应用打开， 右键可复制路径或在资源管理器中显示；外部新增 / 删除这类文件时列表自动刷新。
• 备份或迁移知识库时，连同 attachments/ 一起复制即可（见第五章）。

3.10 版本历史

• 编辑区工具栏点 ◷ 打开「版本历史」。
• 左侧是每次保存产生的快照列表（时间 + 大小），点选后右侧预览该版本的完整内容。
• 确认无误后点「恢复此版本」，笔记立即回到当时的标题与正文；恢复操作本身也会保存， 不会覆盖掉快照记录。
• 快照不是数据库里的二进制，而是 Vault 内 .lattice/history/ 目录下的 Markdown 原文副本， 所以即使索引损坏，历史也还在。
• 每篇笔记最多保留最近 200 个快照，超出自动从最旧删除；内容与最新快照完全相同时 不会重复写快照（自动保存不会再把磁盘写爆，见第九章）。

3.11 模板、每日笔记与每日摘要

这三类文件都直接落在 Vault 里，是普通 Markdown（下表为默认位置，三个目录都可在 Vault profile 中自定义，见 6.1）：

Vault 目录可配置（0.1.3 起）：在「设置 → 知识库位置 → Vault 配置」可修改 Inbox / Daily / Journal 三个目录的 Vault 相对路径，保存在 .lattice/profile.json， GET /api/vault/info 返回当前生效值；viewer 角色无权修改。

3.12 导出 HTML、静态站点与打开外部 Markdown

• 导出单篇 HTML：编辑区工具栏点 ↓，会把当前笔记下载为一个独立的 .html 文件， 图片会内联、双链可点击、嵌入内容会展开，适合单篇分享。
• 导出整库静态站点（0.1.3 起）：「设置 → 备份与迁移 → 导出静态站点」批量生成 一个可直接部署到任意静态托管的站点：
  • 带全文搜索框的 index.html 目录页（按标题 / 正文检索，匹配片段高亮）；
  • 按 Vault 相对目录组织的每篇笔记 HTML，双链互相可点击、嵌入引用自动展开；
  • assets/ 保存图片等资源（不再全部内联，避免体积膨胀）。
  • Windows 桌面版与支持 File System Access API 的浏览器可直接选择目标目录写入； 其他浏览器走桌面目录选择器下载；都不支持时自动平铺下载全部文件。
• 打开 Vault 之外的 Markdown：在资源管理器里双击 .md 文件并选择用 Lattice 打开， 文件会以独立标签出现，默认只读，不进入知识库索引。需要修改时点标签内的 「获取写权限」，授权后即可直接编辑并保存回原文件；关闭标签不影响原文件。

3.13 AI 知识库助手

点功能区的 ✦ 或按 Ctrl + J，界面右侧滑出 AI 知识库助手。

两种工作状态（面板标题旁有指示灯）：

• 本地模式：没有配置任何外部模型。助手仍可响应搜索、文件整理建议等本地即时请求， 但不会生成模型回答。
• 已配置 / 已连接：已在模型管理中保存模型配置；通过连通性测试后显示「已连接」。 模型的配置方法见 6.2。

能做什么：

• 知识库问答：直接提问，助手会先检索全库（关键词 + 语义混合检索），再给出带来源引用的 流式回答。回答下方的引用卡片可点击直接跳到原笔记。
• 相关笔记：配置了语义索引后，打开笔记时面板会自动浮现语义相关的笔记与相关度百分比。
• 搜索 / 检查 / 整理文件：底部快捷按钮提供「知识问答」「搜索文件」「整理建议」 「检查内容」「每日摘要」；也可以直接输入自然语言指令。
• 写操作先预览、后执行：让 AI 改文件时，它不会直接动手，而是先给出「确认文件操作」清单， 逐项标明只读 / 需确认 / 危险（删除不可逆）。核对后点「确认执行」才会真正写入 Vault。
• 任务模式（输入框左下开关）：开启后 AI 可以自主多轮执行「检索 → 读取 → 写入」， 适合「把全库文件按主题整理到目录里」这类任务；所有动作仍会逐条记录。 单个动作失败时会把错误回填给模型自行换路重试，连续 6 轮无法推进则停下并提示你输入 「继续」接续；一次读取超过 5 个文件时会提示并降级为直接执行。
• 文件操作可一键撤销（0.1.3 起）：AI 执行过的写入都带 operationId，与 fc 快照 贯通；「操作历史」里点「撤销」即可还原（后执行的先撤销），批量任务可逐笔回退。
• 模型优先（另一个开关）：默认搜索、检查等轻请求走本地快路径；开启后这些请求也优先 调用外部模型。
• 会话与审计：对话在服务端持久化，可通过顶部下拉切换历史会话、新建或删除； 「操作历史」标签页列出 AI 执行过的每一次文件操作（类型、路径、时间、成功 / 失败）。
• 输入框支持 Enter 发送、Shift + Enter 换行；生成过程中可以点 ■ 随时停止，失败会显示 上游原因并提供「重试」。

AI 只会访问当前 Vault。配置模型后，提问与命中的笔记片段会按你的配置发送给对应模型服务商； 完整隐私边界见附录。

3.14 AI 写作助手

编辑 / 分栏模式下，正文上方常驻一条「✦ AI 写作」工具条（预览模式下隐藏）：

• 选中一段文字后，出现四个加工动作：润色、摘要、译成中文、译成英文。
• 没有选区时，可以：从标题写全文（围绕标题生成结构完整的草稿）、 头脑风暴（列出创意 / 大纲方向）、续写（接着光标前的内容往下写）。
• 也可以在输入框里填写自定义指令（如「改成清单格式」「写一条产品发布文案」）后运行。
• 结果以流式方式在下方预览，生成中可停止；满意后：
  • 加工类结果点「接受并写入」替换选区，或「丢弃」；
  • 创作类结果可「替换全文」或「追加到末尾」（正文非空时替换会再次确认）。
• AI 写作助手需要先在模型管理中配置可用的对话模型，本地模式下这些按钮不产生模型结果。

3.15 画布（白板）

画布以 .canvas 文件保存在 Vault 中，与 Markdown 笔记一样是可复制、可备份的本地文件； 一个知识库可以有多个画布。入口：功能区 ▦ 新建、文件夹右键「新建画布」、侧边栏点击已有画布。

三类卡片：

• 文本卡片：自由记录，直接在卡片里编辑。
• 笔记卡片：引用知识库中的笔记，单击 / 双击卡片即打开原文；卡片上标注文件路径与字数。
• 图片卡片：引用 Vault 中已有的图片，不复制、不修改原图；图片缺失时显示占位提示。

添加方式：工具栏「＋ 文本卡片 / 添加笔记 / 添加图片 / 新建笔记」，或在画布空白处右键； 双击空白处可快速新建文本卡片。添加笔记 / 图片时弹出选择器，可搜索后点选。

布局与连接：

• 拖动卡片移动位置，右下角手柄调整大小；拖动时显示对齐辅助线。
• 从卡片四边的连接点按住拖到目标卡片的任意连接点松开，即建立带箭头的方向连接； 拖到空白处会直接生成一张新卡片并连好线。在连接上右键可「反转方向」或删除连接。
• 在空白处按住拖出选框可批量选择；卡片底部可切换多种预设颜色。
• 按住空格或鼠标中键拖动画布，滚轮缩放。

撤销重做与视图：画布操作支持撤销 / 重做；工具栏提供缩放控制、适配全部节点、 聚焦选中节点和重置视图。容器大小变化不会覆盖你手动调整过的视图。

导入 Obsidian 画布（0.1.3 起）：Obsidian 生成的 .canvas 可直接打开，读取时自动 归一化：fromNode / toNode 边端点、"1"~`"6"` 与 hex 颜色映射到 6 个命名色、 group 虚线卡片、file / image 节点都会转换为 Lattice 等价对象；保存后仍是标准 JSON， 两边可继续互开。Markdown 导入时标题与颜色值不再被误识别成标签；Windows 上改名统一走 「写旧路径 → rename 到新路径」，避免跨卷移动丢数据。

画布内容停止操作 0.5 秒后自动保存，右下角状态点会显示 加载 / 保存中 / 已保存 / 保存失败， 并显示当前对象数与连接数。

3.16 标签页右键菜单

标签页栏的完整右键菜单：

• 关闭类：关闭、关闭左侧、关闭右侧、关闭其他——已锁定标签一律保留。
• 锁定 / 解锁：保护常用标签，批量关闭与 Ctrl + W 都不会关掉它。
• 收藏 / 取消收藏：即置顶这篇笔记，列表中排到最前。
• 重命名：直接修改笔记文件名（等价于改标题）。
• 将文件移动到…：在子菜单里选择目标目录或根目录。
• 复制路径：相对路径、完整路径，或复制 [[双链]]。
• 使用默认应用打开、在系统资源管理器中显示、在文件列表中显示当前文件。
• 打开当前笔记的…：按出链快速跳到相关笔记。
• 删除文件（有确认）。

菜单中灰色项（如分屏、多窗口、导出图片）是为后续版本预留的，当前版本暂不可用。

3.17 Inbox 收集箱（快速收集）

Inbox 是一个「先收下、后整理」的临时收件区，适合一闪而过的碎片想法。

• 收集入口：顶部功能区的 ⬛、编辑区空状态页入口，或快捷键 Ctrl / Cmd + Shift + I。 在弹窗里写下内容即存入 Inbox/（笔记属性自动标记 type=inbox、status=captured）。
• 查看：侧边栏有独立的「Inbox」导航项，右侧徽章显示待整理数量；列表顶部可按 全部 Inbox / 待整理 / 整理中 / 已处理四种状态筛选。
• 整理：笔记卡片可手动切换状态或归档；也可点列表顶部的 AI 按钮让 AI 助手读取待整理内容， 自动判断最合适的项目目录并生成可确认的归档方案，归档即移除 Inbox 标记； 「已处理」的内容不会被重复整理（详见 3.13）。

3.18 PWA：安装到桌面与离线边界

浏览器打开 Lattice Web 版时，它也是一个可安装的 PWA（0.1.3 起）。

• 安装：Chrome / Edge 地址栏右侧的安装图标，或菜单里「安装 Lattice / 将此站点作为应用安装」；安装后以独立窗口启动，带自己的任务栏图标。
• 更新：每次打开会检查新版本，资源更新后提示「发现新版本，刷新即可更新」；无需手动清缓存。
• 缓存边界：Service Worker 只缓存应用壳（页面、脚本、样式与字体）。API 请求、SSE 流式回复与所有写入操作一律绕过缓存——离线时可以查看已缓存的界面，但不能搜索、问答或修改笔记。
• 桌面安装版（Electron）不受此影响，也不需要安装 PWA。

---

四、快捷键

全局

编辑区

画布

---

五、数据、备份与迁移

5.1 数据放在哪

Lattice 与 Obsidian 一样使用本地 Vault 文件夹。笔记正文、目录结构、附件、画布与版本快照 都是 Vault 里的普通文件；SQLite 只用于搜索、标签、双链、图谱与 AI 语义索引，可以随时从 文件重新生成。

首次启动时通过系统对话框选择 Vault，之后可以在「设置 → 知识库位置」查看路径、打开目录、 复制路径，或重新选择（应用会自动重启）。

%APPDATA% 的完整路径通常是 C:\Users\<你的用户名>\AppData\Roaming。 快速定位：在资源管理器地址栏直接粘贴 %APPDATA%\Lattice 回车即可。

Vault 与数据目录的典型内容：

Vault/
├── 工程笔记/                  真实目录
│   └── 架构设计.md             真实 Markdown 笔记（带 frontmatter）
├── 根级笔记.md
├── attachments/              通过编辑器上传的附件（单文件 ≤ 25 MB）
├── _templates/               笔记模板（可选，自己放 .md）
├── Daily/                    每日笔记 YYYY-MM-DD.md
├── Journal/                  AI 每日摘要
├── 画板.canvas                画布文件（可以有多个）
└── .lattice/
    └── history/              笔记历史快照（Markdown 原文，按笔记 id 分目录）

Lattice/
├── data/lattice.db           可重建的 SQLite 索引（含 FTS 与语义向量索引）
└── logs/lattice.log          运行日志

.lattice/ 以点开头，部分资源管理器中默认不显示，需要开启「显示隐藏的项目」。

5.2 备份

桌面版可以通过「设置 → 备份与迁移 → 备份知识库」选择一个备份位置，Lattice 会创建一个带时间戳的新目录并复制整个 Vault：

• Markdown、.canvas 画布、attachments/ 附件、_templates/ 模板、 .lattice/history/ 历史快照会一起保留。
• Markdown 文件可以直接用 Obsidian 或其他编辑器打开。
• 备份只包含 Vault 内容，不包含 AI API Key、SQLite 索引或运行日志。
• 如果备份目标与当前 Vault 在同一个 Vault 内，Lattice 会拒绝操作，避免递归复制。

也可以在软件关闭后手动复制整个 Vault 文件夹；这适合复制到移动硬盘或网盘同步目录。

SQLite 文件只保存索引。即使索引损坏，也可以重新扫描 Vault 目录恢复； AI 语义索引在重新配置 embedding 模型后可一键重建。

一键备份只复制 Vault 文件，不依赖 SQLite 的 WAL 状态；备份期间仍建议暂时停止大批量编辑， 以免把正在写入的单个文件复制在中间状态。

5.3 换机器

绿色版：把整个文件夹（exe + LatticeData\）连同你的 Vault 一起拷到新机器即可。 安装版：在新机器上装好，首次启动时选择原来的 Vault 文件夹即可。

5.4 恢复

把备份的 Vault 文件夹重新选择为知识库即可。应用启动后会根据其中的文件自动建立索引， 不需要手动编辑 SQLite 文件。

「设置 → 备份与迁移」中的「从 SQLite 导出为 Markdown」仅用于旧版数据库迁移， 不是日常备份功能；原数据库不会被删除。

---

六、设置、模型与集成

设置窗口左侧是分组导航，顶部可搜索设置项；修改大多立即生效并保存在本机。

6.1 设置项总览

背景图片支持 PNG、JPG、WebP、GIF 和 AVIF，单张最大 2 MB。 自定义主题支持 JSON 或 CSS 颜色令牌，导入后可随时恢复默认。

6.2 模型管理中心

在「设置 → AI 助手 → 模型」中管理 AI 使用的外部模型。不配模型不影响笔记功能，软件照常 离线使用；配置后 AI 助手与 AI 写作才会产生模型回答。

添加对话模型：

1. 点「＋ 添加模型」，从服务商预设中选择（智谱、DeepSeek、Kimi、硅基流动、火山引擎、 腾讯云、阿里云、AWS、OpenRouter、PPIO、MiniMax、字节豆包、MiMo、ModelForce、Z.ai 等）， 或选「自定义模型」填写任意 OpenAI Chat Completions 兼容接口。
2. 填写模型 ID 与 API Key（密钥以密文框显示，可切换显示 / 隐藏）。高级配置里可改请求地址 与认证方式（Bearer / x-api-key）。
3. 保存前会强制进行一次连通性测试：测试不通过（Key 错误、模型 ID 不存在、无网络等） 会直接拦下，不写入列表。测试会发起一次真实请求，可能消耗极少量 Token。
4. 可以添加多个模型，点列表行即可切换「当前使用」，下一条消息立即生效；也可以停用 / 删除。 API Key 只保存在本机，不会出现在界面与操作审计记录中。

语义索引（Embedding）：

• 在同一页面下方填写 embedding 接口（如硅基流动的 BAAI/bge-m3）、模型 ID 与 Key 并启用。
• 启用后笔记会自动按标题分块、计算向量并增量入库，解锁三样能力： 语义搜索路（与关键词路融合）、相关笔记推荐、知识库问答的语义召回。
• 「语义索引状态」实时显示 已索引 x/y 篇 · 共 z 个分块、待处理与失败数量； 需要时可手动「重建索引」。
• 「检索调试」：输入一句话，直接看到关键词路 / 语义路各自命中了哪些分块、 融合后最终注入模型的是哪些——当你觉得「问答为什么没引用某篇笔记」时，用它排查。

隐私提示：启用云端 embedding 后，笔记的分块文本会发送给你填写的 embedding 服务商； 不启用则只使用本地关键词检索。

6.3 MCP Server（进阶 / 可选）

「设置 → 集成 → MCP Server」面向希望让外部 Agent（如 Claude Desktop）读写本知识库的用户。

• 内置的 Lattice MCP Server 通过标准输入输出（stdio）暴露 10 个工具。 默认只读，提供 7 个读取工具：list_notes、search_notes、read_note、 get_note_links、list_tags、get_vault_statistics、list_note_history； 仅在配置中显式设置 LATTICE_MCP_ALLOW_WRITES=true 后才额外注册 3 个写入工具： create_note、update_note（追加 / 前置）、restore_note_version，写入动作会进 MCP 审计。
• 页面会生成一份现成的 JSON 配置（含 server 路径以及 DB_FILE / VAULT_DIR 两个环境变量， 指向与当前应用相同的数据目录和 Vault），点「复制 JSON」粘贴到 MCP 客户端的配置中即可； 需要外部 Agent 写入时，在该配置的 env 中加上 LATTICE_MCP_ALLOW_WRITES； 也支持导入、新建、启停其他 stdio / SSE Server。
• 注意：界面里的开关只管理本机配置，真正拉起进程的是 Claude Desktop 等 MCP 客户端； 运行 server 脚本需要本机安装 Node.js。普通日常使用完全用不到这一页，忽略即可。

6.4 日志文件

• 位置：数据目录下的 logs\lattice.log
• 内容：启动步骤、数据库迁移、每一次页面请求、界面里发生的错误，全部按行记录
• 超过 2 MB 自动轮转为 lattice.log.1，不会无限增长

日志是排查问题的重要线索（桌面软件没有控制台），反馈问题时附上这个文件即可。

---

七、升级与卸载

7.1 升级

• 检查更新：「设置 → 关于 → 检查更新」会访问 GitHub Releases（仅在点击时联网）。 有新版本时会显示版本名，并提供 Windows 安装包的下载链接；没有新版本则提示当前已是最新。
• 安装版：下载新版 setup.exe 覆盖安装即可，笔记数据不受影响。
• 绿色版：用新版 exe 替换旧的 exe，保留 LatticeData\ 目录与你的 Vault 不动。
• 数据库结构升级（包括 AI 语义表、任务表等新迁移）在启动时自动完成，不需要手动操作。

7.2 卸载

安装版：设置 → 应用 → 找到「格物 Lattice」→ 卸载。 也可以从开始菜单里的卸载快捷方式进入。

卸载时你的笔记会被保留。这是刻意的设计——避免手滑卸载把笔记库一起删掉。 如果确实要彻底清除，卸载后手动删除 %APPDATA%\Lattice\ 目录（以及你的 Vault，如不再需要）。

绿色版：直接删掉文件夹就卸载完了。删之前记得把 Vault 和 LatticeData\ 挪走或备份。

---

八、故障排查

8.1 双击没反应 / 闪一下就没了

最常见的原因是当前系统环境拦截了 Chromium 的 GPU 子进程沙箱， 多见于：受限的虚拟机、远程桌面会话、安全软件的深度防护模式。

软件内置了自愈机制：

1. 第一次启动若 GPU 进程反复崩溃，会在数据目录落下标记并退出。
2. 再启动一次即可——检测到标记后会自动关闭 GPU 沙箱（仅影响 GPU 进程， 笔记功能完全不受影响），窗口正常打开。

所以遇到这种情况：再双击一次。若第二次仍然打不开，请继续看下一条。

8.2 窗口一片空白，或弹出「界面无法渲染」

如果界面进程连续崩溃 3 次，软件会弹出明确提示并告知日志位置，而不是让你对着白屏发呆。

处理办法：

1. 把本程序加入安全软件的信任 / 白名单（重点检查主动防御、沙箱类功能）。
2. 尽量在本机物理桌面会话下运行，而不是远程桌面或受限虚拟机。
3. 弹出提示时，按提示路径取 logs\lattice.log，里面会记录崩溃原因。

8.3 提示「页面加载失败」

说明本地服务没能正常起来。按顺序排查：

1. 是否有另一个实例已经在运行？软件是单实例，重复启动只会聚焦已有窗口。
2. 端口 5188 被别的程序占用了？正常情况下会自动改用随机端口， 若仍失败，关掉可疑程序后重试。
3. 检查 logs\lattice.log 里有没有数据库相关报错。

8.4 提示「启动失败」

启动时会集中校验全部配置，任何一项非法都立即报错并退出，而不是带病运行。 弹窗里会写明确原因和日志路径。

8.5 数据找不到了

先确认用的是哪个版本——安装版和绿色版的索引数据不在同一个地方（见 5.1）。 绿色版如果被放在了只读目录里，数据会自动回退到 %APPDATA%\Lattice\，去那里找找。 笔记本体始终在你首次启动时选择的 Vault 文件夹里。

8.6 中文搜索搜不到

• 两个字的短词走模糊匹配，能搜到但结果可能不如长词精准。
• 尝试把关键词加长（3 个字以上会走全文索引，匹配质量更好）。
• 检索范围是标题 + 正文，确认关键词确实出现在笔记里。
• 若刚从外部拷入大量文件，等索引同步完成后再搜；仍异常可点功能区 ↻ 手动刷新。

8.7 AI 助手不能用 / 一直显示「本地模式」

• 「本地模式」表示还没有配置外部对话模型，到「设置 → AI 助手 → 模型」里添加一个。
• 显示「已配置」但不回答：配置保存前需要通过连通性测试；网络代理、API Key 余额、 模型 ID 填写错误都会导致失败，点模型的「编辑 → 测试连接」看具体报错。
• 问答没有引用到某篇笔记：先用「检索调试」看命中情况；如果没配 embedding， 检索只有关键词一路，换个关键词或补上语义索引再试。
• 语义索引一直显示「索引中 / 有失败」：点「重建索引」；仍失败时查看 logs\lattice.log，多数情况是 embedding 服务商临时不可用或额度不足。
• AI 写作条没有反应：它只在编辑 / 分栏模式下出现，并且同样需要可用的对话模型。

8.8 杀毒软件报警

Electron 打包的桌面程序偶尔会被误报，尤其是新发布的、没有数字签名的版本。 把程序目录加入信任列表即可，不影响功能。

8.9 菜单栏不见了

菜单栏默认自动隐藏（避免占版面）。按一下 Alt 键就会显示出来，里面有 文件 / 编辑 / 视图三组菜单，以及「开发者工具」和「全屏」等入口。

8.10 需要提交问题时请附上这些

1. 你用的是安装版还是绿色版，以及具体版本号（设置 → 关于 中可见）
2. logs\lattice.log（如果有 lattice.log.1 也一起）
3. 具体现象：什么时候出现、窗口上显示了什么；AI 相关问题请注明使用的服务商与模型 ID （不要附上 API Key）

---

九、已知限制

当前版本的边界，都是刻意划定的：

最后一条值得强调：这不是 Obsidian 的兼容替代品。它借鉴了双链笔记的交互体验， 但以自己的 Markdown Vault 与 .canvas 画布格式保存内容；SQLite 只保存可重建的索引。

---

附录：关于隐私

• 默认完全离线：不注册、无账号、无遥测、无云同步。本地服务只监听 127.0.0.1， 局域网内其他设备无法访问。
• 仅有两处会在你主动操作后联网：
  1. AI 功能：配置外部对话 / embedding 模型后，你的提问、对话上下文以及检索命中的 笔记片段会发送给所选模型服务商；启用云端 embedding 时，笔记分块会用于生成向量。 使用哪家服务商、发送到哪个地址，完全由你在模型管理中的配置决定；不配置就不发送。
  2. 检查更新：只有手动点击「设置 → 关于 → 检查更新」时，才会访问 GitHub Releases 查询版本，不会后台自动检查。
• API Key 只保存在本机（界面本地设置与本机服务端），不会写入日志或 AI 操作审计记录。
• AI 文件操作全程留痕：所有由 AI（含 CLI / MCP）执行的文件读写都记录在 「操作历史」中；默认写操作必须先经你在预览清单上确认，只有手动开启「任务模式」后 才允许自动执行，且同样逐条审计。
• 笔记正文、目录、附件、画布与版本快照都在 Vault 文件夹中；标签、链接、语义向量由 索引自动生成。备份时复制整个 Vault 文件夹即可全部带走。
• 笔记正文里的外部链接点击后会交给系统默认浏览器打开，笔记界面本身不会被导航走。

---

格物 Lattice 0.1.3 · 本地优先的双链笔记知识库