> ## 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.

# 给 Agent 的安装指南

> 把这篇文档交给你的 AI Agent，让它引导你完成 Linkly AI 的安装、集成与验证

这篇文档的主要读者是 **AI Agent**，而不是人类。

如果你正在使用 Claude Code、Codex、Cursor 这类具备命令行能力的 AI 助理，把下面这句话复制给它，它会读完本文并引导你完成安装：

```
请阅读 https://linkly.ai/docs/zh/agent-setup.md 并引导我完成 Linkly AI 的安装与集成
```

你也可以自己往下读——本文同样是一份完整的安装说明，只是行文更直白、更强调"怎么判断这一步成功了"。如果你的 AI 助理无法访问网络，用页面右上角的 **Copy page** 复制本页 Markdown 原文，直接粘贴给它。

***

## 致 AI Agent

以下内容是给你的执行指令。请完整读完再开始行动。

### 你的任务

引导用户完成 Linkly AI 的安装与集成，最终达成的状态是：

1. Linkly AI 桌面应用已安装、已完成初始化，索引可用（**只有内置样例也算达成**，用户自己的文档是加分项）；
2. 你（或用户的其他 AI 工具）能真实调用到 Linkly AI 的检索工具，并搜到文档。

### 你的边界与规则

有些事你能做，有些事必须交给用户，**不要越界，也不要替用户假设结果**：

* **你可以自己做**：运行探测命令、安装 CLI、配置 MCP、安装 Skills、运行验证命令、解读报错、向用户汇报。安装类命令**执行前必须先展示给用户并取得同意**。
* **必须交给用户做**：下载安装包、双击安装、走完初始化引导、在应用界面里添加文档目录、授予系统权限。这些是 GUI 操作，你无法代劳。

以及几条硬规则：

* **先探测，再动手。** 用户可能已经装了一半，也可能是重装，不要从头盲目跑一遍。
* **每一步都要验证。** 每步都给了验收判据，判据不满足就不要进入下一步。
* **需要用户操作时，一次性说清，然后停下来等一次回复。** 不要把一件事拆成好几轮来回确认。
* **执行安装类命令前，先把完整命令展示给用户并取得同意。** 尤其是从网络下载并执行脚本的命令。
* **不要谎报进度。** 没验证成功就是没成功，如实说明卡在哪、你试过什么。
* **不要绕过权限、安全或验收要求。** 故障排查表没覆盖的问题，先跑 `linkly doctor` 再查对应官方指南；如果采用了文档没列的处理方式，要说明依据并重新验收。

### 先确认你能不能执行命令

本文默认你具备命令行能力（Claude Code、Codex、Cursor、Gemini CLI 等）。如果你是 ChatGPT、Claude.ai 网页版这类**没有命令行的在线应用**，下面的探测命令和 CLI 安装你都做不了——唯一通用的一点是**桌面应用仍然要装**（把第 1 步完整转述给用户）。你自己的接入方式（远程 MCP、上传 Skills 等）各家差别很大，请读 `https://linkly.ai/docs/llms.txt`，从索引里找到你所在应用的专属集成指南（例如 "Using Linkly AI in ChatGPT"），按那一篇引导用户执行——不要照搬本文。

***

## 第 0 步：探测当前状态

先把下面这组命令一次跑完，根据结果决定从哪一步开始。

**macOS / Linux（bash / zsh）：**

```bash theme={null}
echo "--- 1. port file ---"
cat ~/.linkly/port 2>/dev/null || echo "NO_PORT_FILE"
echo ""
echo "--- 2. health ---"
PORT=$(sed -n 's/.*"port":\([0-9]*\).*/\1/p' ~/.linkly/port 2>/dev/null)
curl -sf --max-time 5 "http://127.0.0.1:${PORT:-60606}/health" || echo "UNREACHABLE"
echo ""
echo "--- 3. cli ---"
linkly --version 2>/dev/null || echo "NO_CLI"
echo "--- 4. status ---"
linkly status --json 2>/dev/null || echo "NO_STATUS"
echo "--- 5. skills ---"
ls ~/.claude/skills/linkly-ai/SKILL.md ~/.agents/skills/linkly-ai/SKILL.md 2>/dev/null || echo "NO_SKILLS"
```

**Windows（PowerShell）：**

```powershell theme={null}
Write-Output "--- 1. port file ---"
$port = 60606
if (Test-Path "$HOME\.linkly\port") {
  Get-Content "$HOME\.linkly\port"
  $port = (Get-Content "$HOME\.linkly\port" | ConvertFrom-Json).port
} else { Write-Output "NO_PORT_FILE" }
Write-Output "--- 2. health ---"
try { Invoke-RestMethod "http://127.0.0.1:$port/health" -TimeoutSec 5 | ConvertTo-Json -Compress } catch { "UNREACHABLE" }
Write-Output "--- 3. cli ---"
if (Get-Command linkly -ErrorAction SilentlyContinue) { linkly --version } else { Write-Output "NO_CLI" }
Write-Output "--- 4. status ---"
if (Get-Command linkly -ErrorAction SilentlyContinue) { linkly status --json } else { Write-Output "NO_STATUS" }
Write-Output "--- 5. skills ---"
if ((Test-Path "$HOME\.claude\skills\linkly-ai\SKILL.md") -or (Test-Path "$HOME\.agents\skills\linkly-ai\SKILL.md")) { Write-Output "SKILLS_OK" } else { Write-Output "NO_SKILLS" }
```

### 怎么读探测结果

`/health` 是最可靠的单一探针。服务正常时返回 HTTP 200 和一段 JSON：

```json theme={null}
{
  "version": "0.8.1",
  "doc_count": 12009,
  "mcp_endpoint": "http://127.0.0.1:60606/mcp",
  "index_status": "watching",
  "capabilities": ["clips-v1"]
}
```

几个关键点：

* **端口不要写死 60606。** 60606 只是默认值，被占用时应用会向上顺延。始终从 `~/.linkly/port` 读取实际端口，该文件内容是紧凑 JSON `{"port":60606}`。
* **port 文件存在不等于服务在跑。** 应用被强杀或崩溃时该文件会残留。判断服务是否健康，一律以 `/health` 是否返回 200 为准。
* **`mcp_endpoint` 为 `null` 说明 MCP 开关被关掉了**（`/health` 仍返回 200）。这时不要去排查端口，请让用户到 **设置 → MCP** 打开开关。
* **`index_status` 的取值**：`watching`（已完成，CLI 显示 `Up to date`）、`scanning`、`indexing`、`idle`、`error`。
* **`doc_count` 是已索引文档数**，用来看索引进度，不是判断"用户文档进来没有"的硬证据——它只是总数，加了一两个文件时 151 和 150 几乎分不出来。

### 状态判定表

**从上往下匹配，命中第一条就照它走**（表格按"链路状态"单维度排列，天然互斥）：

| 探测结果                                          | 说明               | 从哪一步开始                                                   |
| --------------------------------------------- | ---------------- | -------------------------------------------------------- |
| 无 port 文件，`/health` 不可达                       | 没装，或从未启动过        | 第 1 步                                                    |
| 有 port 文件，但 `/health` 不可达                     | 装过但当前没运行         | 请用户启动应用，再重新探测                                            |
| `/health` 200，但 `index_status` 为 `error`      | 索引出错             | 先跑 `linkly doctor`（无 CLI 就请用户看 **设置 → 关于 → 日志**），恢复前不要继续 |
| `/health` 200，但 `linkly status` 不可用           | 应用就绪，缺 CLI（或连不上） | 第 2 步                                                    |
| `/health` 200 且 `linkly status` 正常，但未装 Skills | 链路就绪，缺 Skills    | 第 3 步                                                    |
| 以上全部就绪，且 Skills 已装                            | 基本装好了            | 第 4 步验收                                                  |

附注：无论从哪一步进入，如果 `doc_count` 只有样例量（约 150），在最终汇报时顺带建议用户去 **设置 → 文件夹** 添加自己的目录——但这不是阻塞项，可以继续往下走。

***

## 第 1 步：安装与初始化

这一步全部由用户手工完成，你无法代劳。**请把下面的完整流程一次性告诉用户，然后停下来，等用户回复一次"完成了"即可**——不要拆成多轮逐条确认。

以下是你要转达给用户的内容（可以按你的风格和平台、环境等进行重述，但五个环节都要说到）：

### 1. 下载并安装

前往 **[https://linkly.ai/#download](https://linkly.ai/#download)** 下载对应操作系统的版本。

* **macOS**：双击 `.dmg` 挂载，把 **LinklyAI** 图标拖入 **Applications**，然后从 Launchpad 启动。
* **Windows**：双击 `.exe`，按向导完成安装（默认装到用户目录），从开始菜单启动。
* **Linux**：AppImage 方式 `chmod +x LinklyAI-*.AppImage && ./LinklyAI-*.AppImage`；或 deb 包方式 `sudo dpkg -i linkly-ai-*.deb`。

### 2. 走完首次启动的引导

首次启动会打开引导窗口，依次是**封面 → 登录 → 准备中 → 体验面板**（右下角步进器只对中间两屏计数，所以显示 1/2、2/2）：

* **封面**：选择界面语言和主题，**必须勾选"已阅读并同意隐私政策"才能继续**。同屏还有一个"帮助改进 Linkly AI"的遥测开关，默认开启，介意的话可以关掉。
* **登录**（1/2）：点「登录账号」打开浏览器完成 OAuth 授权。**这一步可以跳过**——跳过入口是页面底部一行小字里的「跳过登录」链接。请告知用户：登录只用于快速获取官方 AI 模型试用额度和云端知识库功能，方便完成测试，**本地索引、本地检索、MCP 服务完全不需要连接网络**。
* **准备中**（2/2）：应用会自动解压一批内置样例文档并建立索引，通常几分钟完成。等右下角「立即开始」按钮点亮后即可继续。
* **体验面板**：六张功能卡片，点击任意一张试用主功能，点击右上角的 × 结束引导。

### 3. 添加你自己的文档目录（可选）

引导结束后，应用只索引了内置样例文档，用户自己的文件还没有被索引。**这一步值得建议、但不是必需的**：样例库已经足够体验 Linkly AI，目录随时可以之后再加。想现在就加的话，两种方式任选：

* 打开 **设置 → 文件夹**，添加想要索引的目录（例如「文档」「下载」或某个项目目录）；
* 或者直接把文件放进 `~/LinklyAI` 文件夹——该目录默认被监视，放进去就会自动索引。

如果系统提示权限不足（macOS 常见），需要前往 **系统设置 → 隐私与安全性 → 完全磁盘访问权限** 添加 Linkly AI，然后重启应用。

建议用户将自己的 document、网盘、NAS等存放大量本地文件的目录添加到索引中。

### 4. 知道模型正在后台下载（无需操作，但要告诉用户）

首次启动后应用会在后台下载约 **710MB** 的模型文件（语义检索模型约 639MB，OCR 模型约 70MB），视网速可能需要几分钟到几十分钟。这期间：

* **关键词搜索立刻可用**，完全不受影响；
* **语义检索要等模型下载并索引完成**。在此之前 `search` 会自动退化为纯关键词（全文）检索，相关性略有下降——这是预期行为，不是故障。

### 5. 全部做完后回复一次

以上都完成后，用感谢的口吻回复用户一次即可，你会接手后面的配置。

***

**验收判据**：`/health` 返回 200 且 `doc_count` 大于 0。如果刚点完引导 `doc_count` 还是 0、且 `index_status` 是 `scanning`/`indexing`，说明样例还在入库——**间隔 10 秒最多重试 6 次**；仍为 0 就按故障排查里的 `error` 处理。用户加了自己的目录时 `doc_count` 会明显超过样例量；没加也不影响往下走。

***

## 第 2 步：打通工具链路

有两条路径，**不互斥**。**优先装 CLI**：它装好立即可用，你在当前会话内就能直接调用、当场合上闭环；MCP 要重启会话才生效，你无法当场验证。这只是"当前会话能否自验证"的优先级，不代表产品层面 CLI 比 MCP 好。如果用户还想在别的 AI 工具里用 Linkly AI，两个可以都配。

**下面所有命令里的端口都不要写死。** 先在本步开头把实际端口取出来存成变量，后续命令一律引用它：

```bash theme={null}
PORT=$(sed -n 's/.*"port":\([0-9]*\).*/\1/p' ~/.linkly/port)
MCP_URL="http://127.0.0.1:$PORT/mcp"
```

PowerShell 用第 0 步已取到的 `$port` 拼 `$mcpUrl = "http://127.0.0.1:$port/mcp"`。

### 方案 A：安装 CLI（推荐）

先把命令展示给用户，说明它会从网络下载并执行安装脚本，**取得同意后再执行**：

macOS / Linux：

```bash theme={null}
curl -sSL https://updater.linkly.ai/cli/install.sh | sh
```

或使用 Homebrew：

```bash theme={null}
brew tap LinklyAI/tap
brew install linkly
```

Windows（PowerShell）：

```powershell theme={null}
irm https://updater.linkly.ai/cli/install.ps1 | iex
```

任意平台（需要 Rust 工具链）：

```bash theme={null}
cargo install linkly-ai-cli
```

安装脚本会把 CLI 装好并加进 PATH。如果装完 `linkly` 命令找不到，让用户**新开一个终端窗口**（PATH 改动对已开窗口不生效），或直接用完整路径调用：

* macOS / Linux：装到 `~/.linkly/bin/linkly`，PATH 写进了 `.zshrc` / `.bashrc` / `.profile`；
* Windows：装到 `%LOCALAPPDATA%\linkly\bin\linkly.exe`，改的是用户级 PATH 环境变量。

**验收判据**：`linkly --version` 有输出，且 `linkly status --json` 返回包含 `app_version` 和 `doc_count` 的 JSON。（人类可读的 `linkly status` 里对应字段叫 `Docs:` 且带千分位逗号，程序化判断一律用 `--json`。）

### 方案 B：配置 MCP

当用户的工具不方便装 CLI，或希望在多个 AI 工具中都能用时，选这条路。端点用第 2 步开头取到的 `$MCP_URL`（即 `http://127.0.0.1:$PORT/mcp`），**不要写死 60606**。

常见客户端：

* **Claude Code**：`claude mcp add --transport http linkly-ai "$MCP_URL"`
* **Codex**：`codex mcp add linkly-ai --url "$MCP_URL"`
* **Cursor**：设置 → MCP Servers → Add Server，Name 填 `linkly-ai`，Type 选 `StreamableHTTP`，URL 填 `$MCP_URL` 的实际值。

更多客户端的配置方式见[通过 MCP 集成 AI 助理](/docs/zh/use-mcp)。

**配置完 MCP 后，新工具通常不会在当前会话里立即生效**——多数客户端需要重新加载配置或新建会话，具体按对应客户端的指南操作。请明确告诉用户"配置已写入，重新加载/新建会话后再试"，**不要在当前会话里反复试探工具是否出现**。

**验收判据**：配置文件已写入成功。若想在不重启的情况下确认服务端正常，直接发一次握手请求（`$MCP_URL` 用实际值替换）：

```bash theme={null}
curl -sf --max-time 5 -X POST "$MCP_URL" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"setup-probe","version":"1"}}}'
```

返回内容包含 `"serverInfo":{"name":"linkly-ai"` 即说明 MCP 服务健康；如果收到 **403**，是 MCP 开关被关了，请用户到 **设置 → MCP** 打开。

***

## 第 3 步：安装 Skills

Skills 会教你如何高效使用 Linkly AI 的工具（先搜索、再看大纲、最后精读），显著提升检索质量。**强烈建议安装。**

同样先展示命令、取得同意再执行：

```bash theme={null}
npx skills add LinklyAI/linkly-ai-skills
```

如果环境中没有 `npx`，用 git clone 手动安装：

```bash theme={null}
# Claude Code（用户级）
git clone https://github.com/LinklyAI/linkly-ai-skills.git ~/.claude/skills/linkly-ai

# Codex CLI
git clone https://github.com/LinklyAI/linkly-ai-skills.git ~/.agents/skills/linkly-ai
```

部分用户可能无法访问 GitHub，可以下载我们放在 Linkly CDN 上的备用包：

```
https://updater.linkly.ai/skills/linkly-skills-latest.zip
```

需要只装到特定客户端（如 `-a claude-code` / `-a codex`）或其他安装方式，见[使用 Skills](/docs/zh/use-skills)。如果目标目录已存在，说明装过了，跳过即可（要更新就 `cd` 进去 `git pull`）。

**Skills 同样需要重启会话才会加载。** 验收判据是"文件已落到对应目录"，而不是"当前会话已能调用"。装完后请提醒用户重启会话。

**验收判据**：以下任一路径存在 `SKILL.md`——`~/.claude/skills/linkly-ai/SKILL.md`（Claude Code 用户级）、`.claude/skills/linkly-ai/SKILL.md`（项目级）、`~/.agents/skills/linkly-ai/SKILL.md`（Codex）。`npx skills add` 会按检测到的客户端自动选一个，跑完直接查这三个路径即可。

***

## 第 4 步：端到端验收

**装了 CLI（方案 A）**：做一次真实检索确认整条链路可用。先看 `doc_count`——只有样例量（约 150）就搜样例库里的词（如 `Holmes`）；明显超过样例量说明用户加了自己的目录，换一个他文档里可能出现的词：

```bash theme={null}
linkly search "Holmes" --json
```

**成功的标准**：返回了真实的文档条目（只用样例库时，搜到样例文档同样算成功）。

**只走了 MCP（方案 B）**：你无法在本会话内完成这一步——工具要等客户端重新加载/新建会话才出现，这是加载机制决定的，不是失败。请以"配置已写入、服务端握手正常、待用户重启后验证"结题，把下面这句交给用户，然后停止（这不算谎报进度）：

> 重新加载/新建会话后，问我一句"用 linkly-ai 搜一下 Holmes"，返回了文档条目就说明全链路通了。

如果 CLI 检索返回空，别急着归因于模型——`search` 在模型没就绪时只会退化为纯关键词检索、不会返回空。按顺序排查：查询词是否合适 → `doc_count` 是否为 0（样例还没入库，见第 1 步验收判据）→ 用户目录是否加了 → 文档格式是否支持。用 `linkly status --json` 看 `index_status`：`indexing` 说明还在建索引或下模型，等待即可；`error` 见故障排查。

注意：扫描刚结束、正文提取尚未开始的一小段时间里，`index_status` 会短暂显示 `watching`（即 `Up to date`）。**不要只采样一次就判定就绪**，隔几秒再看一次，或看 `doc_count` 是否还在增长。

***

## 故障排查

| 现象                            | 原因与处理                                                                                                          |
| ----------------------------- | -------------------------------------------------------------------------------------------------------------- |
| `/health` 连接被拒绝               | 桌面应用没在运行。请用户启动应用后重试。                                                                                           |
| port 文件存在但 `/health` 不通       | 上次是异常退出留下的残留文件。请用户重新启动应用。                                                                                      |
| 端口连不上，但应用确实在跑                 | 60606 被占用后端口会顺延。从 `~/.linkly/port` 读实际端口，不要写死。                                                                 |
| `/health` 正常但握手返回 **403**     | MCP 开关被关了。请用户到 **设置 → MCP** 打开开关。                                                                              |
| `index_status` 为 `error`      | 索引出错。跑 `linkly doctor`（无 CLI 就让用户看 **设置 → 关于 → 日志**），恢复前不要继续。                                                  |
| `linkly` 命令找不到                | 让用户新开终端窗口；macOS/Linux 用 `~/.linkly/bin/linkly`，Windows 用 `%LOCALAPPDATA%\linkly\bin\linkly.exe`。               |
| PowerShell 提示脚本被禁止执行          | 执行策略限制。让用户在同一窗口先跑 `Set-ExecutionPolicy -Scope Process -Bypass`（只对当前窗口生效）再重试；或改用 `cargo install linkly-ai-cli`。 |
| 搜索返回空                         | 先别怪模型（模型没下完时是降级为全文检索、不返回空）。依次查：查询词、`doc_count` 是否为 0、用户目录是否加了、文档格式是否支持。                                        |
| `index_status` 一直是 `indexing` | 正常。大量文档或模型下载中都会这样，看 `doc_count` 是否增长来判断是否卡住。                                                                   |
| macOS 权限报错                    | **系统设置 → 隐私与安全性 → 完全磁盘访问权限** 添加 Linkly AI，然后重启应用。                                                              |
| 配好 MCP 但工具没出现                 | 需要重新加载配置或新建会话。这是客户端的加载机制，不是配置错误。                                                                               |
| 需要更深入的诊断                      | 运行 `linkly doctor`，它会逐项检查连接链路并给出修复建议。                                                                          |

***

## 完成后向用户汇报

结束时用简短一段话告诉用户：

* 完成了哪几步、走的是 CLI 还是 MCP；
* 是否需要重启会话才能生效；
* 当前索引状态和已索引文档数；
* 接下来怎么用——例如在任意提问后面加上 `use linkly-ai`，或按 `CMD/Ctrl + Shift + L` 打开检索启动器。

如果有步骤没能完成，如实说明卡在哪里、你做过哪些尝试，并给出用户可以自行处理的下一步建议。

### 最后附上四个示例提问

汇报的末尾，给用户四个可以直接复制去试的问题。**优先根据用户的真实资料来定制**：

先花一点时间了解用户索引了什么——用 `explore` 工具（CLI 是 `linkly explore`）看一眼整体构成，必要时再 `search` 抽查几个主题。然后写出四个他真正可能会问的问题：要具体指向他自己的文档和关心的事，不要写"总结我的文档"这种放之四海皆准的空话。好问题应该让用户一眼看出"这确实是在说我的资料"。

如果用户还没添加自己的文档（`doc_count` 只有样例量），就直接用下面这四个针对内置样例库的问题：

1. 读完 A Life in 10 Years，分析 Samuel Pepys 十年日记中反复出现的人生模式，以及他自己可能没看清的盲点。
2. 福尔摩斯到底赢在哪里？读完 Detectives Library 里的 12 个案卷，拆出他的破案公式，再把 Holmes 的推理方法转化成用于诊断复杂商业问题的 checklist。
3. 美国建国者真正害怕的是什么？读完整个 Federalist Papers，给我一个答案。并说明他们如何设计一套制度，让野心和派系制衡。最后，把这套逻辑翻译成今天 AI 公司或互联网平台的治理原则。
4. 读完几百位前奴隶的亲口回忆，发现美国历史课本最不敢细讲的是什么？基于 WPA Slave Narratives 回答。

***

## 延伸阅读

* [快速开始](/docs/zh/quickstart) —— 面向人类读者的完整安装与上手指南
* [使用 CLI](/docs/zh/use-cli) —— CLI 的全部子命令与参数说明
* [使用 MCP](/docs/zh/use-mcp) —— 三种访问模式与各客户端配置方式
* [使用 Skills](/docs/zh/use-skills) —— Skills 的安装方式与工作原理