> ## Documentation Index
> Fetch the complete documentation index at: https://linkly.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.
# 常见问题
> Linkly AI 常见问题解答。
本页汇总 Linkly AI 用户最常问到的一些问题。
## Linkly AI 如何保护用户数据隐私？
Linkly AI 采用 **本地优先（local-first）** 架构。文档原文、全文索引、向量索引以及向量化模型推理都在你的设备上完成，默认不会上传到任何服务器。
### 哪些数据存在本地
* **文档原文**：保留在你原本的文件夹中，Linkly AI 只读取，不复制、不搬运。
* **全文索引（BM25）**：使用 Tantivy 在本地构建。
* **向量索引**：嵌入向量保存在本地数据库中。
* **Embedding 模型**：本地嵌入模型完全在你的设备上运行；macOS Apple Silicon 自动启用 Metal GPU 加速。
* **应用日志**：仅写入本地文件，不会自动上传。
### AI 对话的数据走向
Chatbot 调用大语言模型时，数据流向取决于你选择的 provider：
Ollama、LM Studio 等 OpenAI 兼容的本地服务。数据完全留在本机，不出设备。
通过 `api.linkly.ai` 转发到第三方模型供应商。请求会经过 Linkly 服务器。
直接连接 OpenAI、Anthropic 等 API。请求不经过 Linkly 服务器。
你可以在 **设置 → AI 模型** 中自由添加、切换、禁用各个 provider。
### 用户体验改进计划（遥测）
为了了解哪些功能被使用、运行环境的分布，Linkly AI 默认启用一份**匿名**的使用数据上报：
| 上报内容 | 不上报内容 |
| ------------- | ------------- |
| 功能使用计数（按动作汇总） | 文档内容、文件名、路径 |
| 应用版本、操作系统、架构 | 对话内容、查询语句 |
| 本地随机生成的设备 ID | API key、自定义域名 |
随时可以在 **设置 → 数据隐私 → 用户体验改进计划** 中关闭。关闭后内存中尚未发送的事件也会一并丢弃。
设置中的「数据隐私」面板用三张卡片可视化地展示了每项功能的数据流向（**本机 / 官方云 / 第三方**），可以一目了然地看到当前哪些数据会离开你的设备。
### 隐私承诺
* 不接入 Google Analytics 等第三方分析 SDK。
* 不读取浏览历史与剪贴板。
* 不强制账号登录，核心功能离线可用。
* 应用日志只写在本机，需要你主动分享才会发送给我们。
## Linkly AI 的索引需要多久可以完成？
索引耗时取决于**文件数量、文件类型、机器性能**和**索引模式**。Linkly AI 的索引分三个阶段进行：
扫描到文件后立即把路径、文件名写入全文索引，让你在等待完整索引时也能用文件名搜索定位。
解析文档内容（txt、md、html、docx、pptx、epub、pdf、图片，以及开启转写后的音视频），提取大纲与元数据后写入 Tantivy。可同时使用多个 worker 并行处理。
调用本地嵌入模型为每个文档块生成向量，写入向量索引。
### 影响速度的关键因素
* **文件数量**：与总耗时近似线性相关。
* **文件格式**：纯文本最快；PDF 需要解析页面结构。
* **机器性能**：Apple Silicon（M 系列）启用 Metal GPU 加速嵌入，速度明显优于纯 CPU 推理；Windows / Linux 当前为 CPU 推理。
* **索引模式**：在 **设置 → 索引** 中可选 `性能 / 平衡 / 自动`。性能模式并发更高、占用更多 CPU；自动模式会在系统空闲时自动切到性能模式。
### 大致预期
下面只是粗略量级，实际耗时因机器与文件构成差异较大：
| 场景 | 大致耗时 |
| ------------------------------- | -------- |
| 千级纯文本（txt / md），M 系列 Mac | 数分钟 |
| 万级混合格式（含少量 PDF），M 系列 Mac | 数十分钟到数小时 |
| 含大量 图片（需 OCR） | 显著更长 |
| 同样规模在 Windows / Linux 纯 CPU 机器上 | 比 Mac 慢 |
你可以在 launcher 顶部的索引进度条实时查看当前进度（已索引 / 待索引）。索引在后台进行，不影响搜索使用——文件名索引完成后即可立刻搜索。
如果你只是想试用 Linkly AI，建议从一个**小规模知识库**（百级到千级文件）开始，等熟悉后再加入更大的目录。
## 为什么有个文件搜不到？
先做一步分诊——**用文件名去搜它**，三种结果对应三类完全不同的问题：
| 搜文件名的结果 | 说明 | 往下看 |
| ---------------------- | ------------------ | ------------------------ |
| 搜得到，**带灰色「未索引 · ⋯」徽章** | 文件进了索引，但正文被跳过了 | 本节下面的[四种原因](#四种原因) |
| 搜得到，**没有徽章**，但正文搜不到 | 正文还没轮到、或者对应的提取开关关着 | [下一节](#搜得到文件名没有徽章正文却搜不到) |
| **连文件名都搜不到** | 这个文件压根没进索引 | [再下一节](#连文件名都搜不到) |
这一步很关键：三类问题的处理方式完全不同，跳过分诊很容易在错误的方向上折腾很久。
被跳过的文件**不会**在设置页里单独列出来。**搜索结果里的徽章是唯一的发现途径**——所以上面这一步分诊必须自己做一次。
### 四种原因
| 徽章 | 到底发生了什么 |
| ---------------- | ------------------------------------------- |
| **未索引 · 云端占位文件** | 文件在云盘里存在，但**还没有真正下载到这台机器**——磁盘上只有一个占位符 |
| **未索引 · 文件签名异常** | 文件的实际内容和扩展名对不上（比如一个叫 `.pdf` 的文件，内容根本不是 PDF） |
| **未索引 · 无音轨** | 这个视频没有音轨，没有可转写的内容 |
| **未索引 · 转写失败** | 音视频转写没能完成（无法解码，或音频格式不支持） |
鼠标悬停在徽章上会给出同样的说明。这类文件仍然留在搜索结果里，只是没有正文可搜。
### 云端占位文件是怎么回事
iCloud Drive、OneDrive、Dropbox、群晖 Drive 这类云盘都有「**按需下载**」（也叫「仅在线」「智能同步」）功能：文件在访达/资源管理器里看得见，但内容其实还在云端，只有你双击打开时才真正下载下来。
Linkly AI **刻意不去打开这类文件**——一旦打开就会触发下载，那意味着一次索引就可能把你几百 GB 的云盘全拉到本地，撑爆磁盘、跑满带宽。所以它只做属性判断，认出是占位文件就跳过正文，保留文件名索引。
**怎么办**：在云盘客户端里把你真正需要检索的目录设为「始终保留在此设备上」（各家叫法不同，OneDrive 叫「始终保留在此设备上」，Dropbox 叫「设为本地」，iCloud 是右键「立即下载」）。文件落到本地之后，Linkly AI 会在下一次扫描时发现它已经可用，**自动补做正文索引**——不需要你重建索引，也不需要重新添加文件夹。
扫描会在应用启动、配置变更（比如增删文件夹）以及监听到大量文件变化时自动触发。想立刻促成一次，重启应用是最省事的办法。
### 文件签名异常怎么办
这说明文件头部的特征字节和扩展名不匹配。常见于：从某些同步工具里拿到的替身/存根文件、下载中断留下的半截文件、或者被人手工改过扩展名的文件。
用对应的软件打开确认一下——如果它本来就打不开，那 Linkly AI 跳过它是对的；如果是扩展名写错了，改成正确的扩展名即可。
Linkly AI 在这件事上的取舍是**宁可漏判，不可错杀**：读取文件头如果遇到临时的 IO 错误或权限抖动，一律按「内容可用」处理，绝不会因为一次瞬时失败就把真文件永久标记成替身。
## 搜得到文件名、没有徽章，正文却搜不到
没有徽章说明文件本身没问题，是**正文提取那一步还没做或者做不了**。按可能性从大到小：
1. \*\*对应的提取开关关着。\*\*图片和扫描版 PDF 靠「图片文字识别（OCR）」，音视频靠「音频解析」「视频解析」——**后两个默认就是关的**。去 **设置 → 索引** 确认。
2. \*\*还没轮到它。\*\*OCR 和音视频转写是最重的任务，排队慢是正常的。设置页的状态明细里能看到它们当前在处理什么。
3. \*\*这个文件解析失败了。\*\*比如文件损坏、或者是加密的 PDF。这种情况不会有徽章，直接跳过不再重试。
每个开关的作用、默认值，以及状态明细里每一行的含义，都在这一页。
## 连文件名都搜不到
这说明文件**根本没有进入索引**。常见原因有三个：
\*\*一、这个文件夹没有被监听。\*\*去 **设置 → 文件夹** 确认它的父目录在列表里。首次启动的引导流程只索引内置样例，你自己的目录需要自己加。
\*\*二、这个格式不在支持列表里。\*\*Linkly AI 采用白名单：只有 PDF、DOCX、PPTX、EPUB、Markdown、TXT、HTML、图片、音频、视频这些扩展名会被收录。**xlsx、csv、doc、rtf、htm、avi 目前都不在其中**——不在白名单的文件连文件名都不会被登记。完整清单见[工具介绍](/docs/zh/tools-intro)。
\*\*三、它在被忽略的目录里。\*\*下面这些目录及其全部子目录会被整体跳过：
* **以点开头的隐藏目录**（`.git`、`.cache`、`.dropbox.cache` 等）
* **`node_modules`、`__pycache__`** 这类构建/依赖缓存
* **NAS 的同步元数据目录**：`#recycle`、`#SynoRecycle`、`@eaDir`（群晖）、`@Recycle`（QNAP）
* **系统目录**：`$RECYCLE.BIN`、`System Volume Information`
在 Git 仓库里，被 `.gitignore` 排除的文件同样不会被索引。如果你的笔记正好放在某个仓库的忽略目录下，把它挪出来，或者单独把那个目录加进 **设置 → 文件夹**。
## 音频和视频搜不到里面说了什么？
因为**音频解析和视频解析默认是关闭的**。关闭时媒体文件照常被登记进索引（所以文件名搜得到），但里面说了什么没有被转写。
去 **设置 → 索引** 打开「音频解析」和「视频解析」，应用会下载语音识别模型，然后自动把已有的媒体文件全部补做完——不需要重新扫描，也不需要重建索引。
这一页讲清楚了 **设置 → 索引** 里每一个开关的作用、默认值，以及索引出问题时的完整排查路径。
## 常用设置都在哪里？
设置窗口按功能分页。下面这几页是最常被找的：
* **语言**：界面显示语言
* **开机启动**：登录系统时自动启动 Linkly AI
* **静默启动**：开机启动时只驻留后台、不弹出主窗口，**默认开启**——这样索引和 MCP 服务都在跑，但不会打扰你
* **搜索快捷键**：唤起/隐藏[启动器](/docs/zh/use-launcher)的全局快捷键，点一下就能重新录制，也可以「恢复默认」。如果提示该组合已被占用或被系统保留，换一个即可
* **Linkly AI 空间**：默认被索引的那个目录，可以打开或改到别处，详见 [Linkly AI 空间](/docs/zh/linkly-space)
* **主题**：浅色 / 深色 / 跟随系统
* **字体大小**：小 / 标准 / 大，同时作用于界面和聊天内容
* **显示 Dock 图标**（macOS）：关掉之后应用只留在菜单栏托盘里，不占 Dock 位置
* **检查更新**：手动检查并下载新版本，下载完点「重启以更新」即可
* **加入开发版体验计划**：打开后会收到开发版（beta）更新，能提前用到新功能，但可能遇到未完全测试的改动
* **数据目录**：索引、设置和日志的存放位置，点「打开」直达（[取日志](#如何获取-linkly-ai-的应用运行日志)就在这里）
* 还能从这里跳到更新日志、隐私政策、用户协议，以及 CLI 和 Skills 的说明
列出应用内全部快捷键。在启动器里按 `⌘ + /`（Windows/Linux 是 `Ctrl + /`）可以直接打开这一页。
「**暂停索引**」不在设置里——它只在**系统托盘菜单**中，需要**右键**点击托盘的 L 图标才能调出（左键打开的是 AI 对话窗口）。详见[索引设置](/docs/zh/indexing)。
## 如何获取 Linkly AI 的应用运行日志？
应用启动后会将运行日志自动写入本地的 `app.log` 文件（单文件最高 2 MB，滚动覆盖）。当你向我们反馈问题或自行排查问题时，附上这份日志能极大加速定位。日志已经对敏感数据进行了脱敏。
获取日志有两种方式：
### 方式一：从应用内打开（推荐）
这是最简单的方式：
在 Linkly AI 中进入 **设置 → 关于**。
找到「**数据目录**」一行，点击右侧的「**打开**」按钮。系统会弹出存放应用数据的文件夹。
在该文件夹中进入 `logs/` 子目录，将 `app.log` 发送给我们即可。
### 方式二：手工打开数据目录
如果应用已经崩溃或无法启动，可以直接打开磁盘上的目录：
1. 打开 Finder。
2. 顶部菜单选择 **前往 → 前往文件夹…**（或按 ⌘ + ⇧ + G）。
3. 粘贴下面的路径并回车：
```
~/Library/Application Support/ai.linkly.desktop/logs
```
4. 在打开的文件夹中找到 `app.log`，发送给我们即可。
1. 按下 Win + R 打开「运行」窗口。
2. 粘贴下面的路径并回车：
```
%APPDATA%\ai.linkly.desktop\logs
```
3. 在打开的文件夹中找到 `app.log`，发送给我们即可。
在终端中执行：
```bash theme={null}
xdg-open ~/.local/share/ai.linkly.desktop/logs
```
或直接复制 `app.log`：
```bash theme={null}
cp ~/.local/share/ai.linkly.desktop/logs/app.log ~/Desktop/
```
### 应用启动时就崩溃怎么办？
如果应用启动后立刻闪退，`app.log` 可能还来不及写入。这种情况下我们会把崩溃信息单独保存到一份**启动崩溃日志** `linkly-ai-startup-panic.log`，请按下面的路径查找。
1. 打开 Finder。
2. 顶部菜单选择 **前往 → 前往文件夹…**（或按 ⌘ + ⇧ + G）。
3. 粘贴下面的路径并回车：
```
~/Library/Application Support
```
4. 在打开的文件夹中找到 `linkly-ai-startup-panic.log`，发送给我们即可。
1. 按下 Win + R 打开「运行」窗口。
2. 粘贴下面的路径并回车：
```
%LOCALAPPDATA%
```
3. 在打开的文件夹中找到 `linkly-ai-startup-panic.log`，发送给我们即可。
注意这里是 `%LOCALAPPDATA%`（本地数据），不是 `app.log` 所在的 `%APPDATA%`（漫游数据）。
在终端中执行：
```bash theme={null}
cp ~/.local/share/linkly-ai-startup-panic.log ~/Desktop/
```
这份日志只在启动期间崩溃时才会生成，每次崩溃会覆盖上一次的内容。如果连这份日志都没有，请截图记录闪退瞬间的画面或弹窗，并附上系统版本发送给我们。
在 GitHub Issues 提交，或通过社区页面上的任意渠道联系我们。