功能文档
从快捷键到 MCP 配置——Lattice 的全部使用面。
Lattice 是什么
Lattice 是一个 AI 原生的 macOS 命令中心：菜单栏常驻，⌥Space（可改键）呼出命令面板，用键盘完成启动应用、搜索文件、管理剪贴板、运行快捷指令与调用 AI 工具。原生 Swift 6 + SwiftUI + AppKit，没有 Electron、没有账号体系、没有云同步。
它同时是四样东西：Spotlight 的升级版、Mac 版 Everything、带 AI 工具循环的助手面板、以及应用快捷指令入口。
三分钟上手
- 安装后按 ⌥Space 呼出面板（菜单栏格子图标 → Open Settings → General 可重录快捷键）
- 输入 saf 回车——Safari 已启动；输入 12*(3+4) ——计算器置顶出 84，回车复制
- 进入 Search Files（输入 files 回车），输入任意文件名片段，回车打开
- 复制一段文字后再进 Clipboard History（输入 clipboard），⌘Y 预览，回车回写
- 想用 AI：Open Settings → AI，填入 API Key 并启用 AI Requests，回到面板进 Ask AI
快捷键总表
| 按键 | 行为 |
|---|---|
| ⌥Space | 显示 / 隐藏 Command Palette（跨应用，可自定义） |
| ↑ / ↓ | 选择结果；Actions 打开时选择 Action |
| ↵ | 执行选中结果或 Action |
| ⌘K | 打开 / 关闭当前结果的 Actions |
| ⇥ Tab | 选中应用时进入 Arguments 参数模式 |
| Esc | 关闭 Actions → 退出 Arguments → 返回 Commands → 隐藏面板；AI 运行中先取消 |
| ⌘Y | 剪贴板 / 文件结果预览 |
| 点击面板外部 | 隐藏面板（弹窗打开时不生效） |
四种模式
- Commands：应用、系统命令、Quicklinks、快捷指令、Agents、计算器——统一排序（精确 > 前缀 > 子串 > 关键词，使用频率有限加权）
- Search Files：全盘文件名搜索，支持目录范围过滤（Choose Folder）
- Clipboard History：文本与 URL 历史，搜索、预览、回写
- Ask AI：AI 对话 + 工具循环，Esc 取消
搜索语法
文件搜索支持词法运算符组合，带引号的词组按原样匹配：
# 名词 + 扩展名过滤 report ext:pdf # 路径限定 + 类型 + 排序 path:Downloads kind:file sort:size # 引号词组 + 多扩展名 "meeting notes" ext:md,tex # 只搜文件夹 kind:folder config
| 运算符 | 含义 |
|---|---|
| ext: | 按扩展名过滤，逗号分隔多个 |
| path: | 路径包含指定片段 |
| kind:file / kind:folder | 只搜文件或只搜文件夹 |
| sort:size / sort:modified / sort:name | 按大小 / 修改时间 / 名称排序（默认按相关度） |
索引机制
- 自建 SQLite 索引：默认覆盖用户 Home、/Applications、/System/Applications、/Library；Settings → File Index 可增删目录或重建
- FTS5 trigram 子串索引承担 ≥3 字符查询，1–2 字符走前缀索引
- FSEvents 实时增量：文件变化 2 秒内同步，重启从断点续传不重扫
- 刻意不索引 ~/Library/CloudStorage 与 iCloud 目录，避免文件供应商占位文件阻塞
- 无完全磁盘访问权限时部分系统目录静默跳过（Settings 有引导）
应用专属操作与参数模式
选中应用按 ⌘K 展开专属操作；按 ⇥ 进入 Arguments 模式直接输入启动参数（支持引号包裹含空格的值），每个应用自动记忆最近参数，空输入时即可挑选。
| 应用 | 专属操作 |
|---|---|
| Chrome / Edge / Brave / Arc | New Window；Chrome 与 Edge 另有无痕 / InPrivate 窗口 |
| VSCode / VSCodium | New Window；VSCode 另有 Diff Two Files |
| Slack | Reset App State |
参数经 NSWorkspace 的 argv 传递，不经过 shell，不触发额外的系统授权弹窗。
运行 macOS 快捷指令
命令模式直接输入快捷指令名称即可搜索并运行。调用走固定的 /usr/bin/shortcuts 命令行（argv 方式、无 shell 参与），AI 通过 shortcuts.list / shortcuts.run 工具也能查询与运行，运行前需确认。
剪贴板历史
- 650ms 轮询 changeCount，内容去重，默认 500 条，可配置 1–10,000，单条上限 1MB
- ⌘Y 富文本预览，回车回写剪贴板，清空历史需要确认
- 默认忽略 Concealed / Transient / AutoGenerated 类型（密码库等），但未标记的敏感文字仍会被记录——介意可在 Settings 关闭
Quicklinks 与计算器
Quicklinks 在 Settings 中添加，支持 http/https/file 与 {query} 占位符，保存后立即出现在面板。计算器无需进入任何模式——命令面板直接输入算式即出结果，回车复制。
Agents 与 Skills
Settings → Agents 创建 Agent：命名、选择可用工具白名单、保存后按名称搜索进入对话。Skills 从 ~/.config/lattice/skills 等目录扫描定义文件，Examples/Skills 内附带示例。
Ask AI 与工具审批
AI 默认关闭。Settings → AI 中填入 OpenAI 兼容 API Key（只进 Keychain）并启用后，Ask AI 模式可用。模型最多 8 轮工具循环，每轮最多 8 个调用，单次工具输出上限 256KB。
| 权限 | 行为 |
|---|---|
| read | 直接执行（clipboard.read 例外：另行确认，防提示注入） |
| write | 弹窗确认（可设置放行） |
| destructive | 始终确认（含所有远程 MCP 调用） |
配置 MCP 服务器
Settings → MCP 添加 stdio 服务器配置，连接前展示程序与参数并确认：
{ "name": "Lattice local fixture", "transport": "stdio", "command": "/usr/bin/python3", "args": ["/Users/you/LatticeMCPFixture.py"], "env": {} }
凭据写入 Keychain 后以 secretEnvironment 引用，不会持久化到配置 JSON。第三方服务器进程拥有你的用户权限，Tool 审批不是操作系统沙箱——只连接可信的服务器。
隐私与数据
- 所有本地数据位于 ~/Library/Application Support/Lattice/lattice.sqlite（目录权限 0700，内容为本地明文）
- API Key 与 MCP 凭据只存 Keychain（WhenUnlockedThisDeviceOnly）
- AI 关闭时零网络请求；开启后请求只发往你配置的 Provider
- 日志不记录 Prompt、剪贴板内容、凭据与服务器 stderr
- 全局快捷键用 Carbon RegisterEventHotKey，不做全局键盘监听，无需辅助功能权限（Lock Screen 事件除外）
常见问题
- 为什么 Dock 里没有图标？—— Lattice 是菜单栏应用（LSUIElement），只在菜单栏常驻。
- 首次索引要多久？—— 取决于文件数量，本机 548 万文件约 14 分钟；之后 FSEvents 增量维护。
- 和 Spotlight 冲突吗？—— 完全独立，Lattice 自建索引，不读取也不干扰 Spotlight。
- 支持 Intel Mac 吗？ —— 当前安装包为 arm64；源码包可自行编译，未在 Intel 硬件验证。
- 怎么卸载？ —— 关闭 Launch at Login、删除 API Key，Quit 后移除 App；数据目录与 Keychain 项按需手动清理。