给 Agent 的安装指南

这篇文档的主要读者是 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 的安装与集成，最终达成的状态是：

Linkly AI 桌面应用已安装、已完成初始化，索引可用（只有内置样例也算达成，用户自己的文档是加分项）；
你（或用户的其他 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）：

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）：

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：

{
  "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 下载对应操作系统的版本。

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，两个可以都配。 下面所有命令里的端口都不要写死。 先在本步开头把实际端口取出来存成变量，后续命令一律引用它：

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：

curl -sSL https://updater.linkly.ai/cli/install.sh | sh

或使用 Homebrew：

brew tap LinklyAI/tap
brew install linkly

Windows（PowerShell）：

irm https://updater.linkly.ai/cli/install.ps1 | iex

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

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 助理。 配置完 MCP 后，新工具通常不会在当前会话里立即生效——多数客户端需要重新加载配置或新建会话，具体按对应客户端的指南操作。请明确告诉用户”配置已写入，重新加载/新建会话后再试”，不要在当前会话里反复试探工具是否出现。 验收判据：配置文件已写入成功。若想在不重启的情况下确认服务端正常，直接发一次握手请求（$MCP_URL 用实际值替换）：

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 的工具（先搜索、再看大纲、最后精读），显著提升检索质量。强烈建议安装。 同样先展示命令、取得同意再执行：

npx skills add LinklyAI/linkly-ai-skills

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

# 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。如果目标目录已存在，说明装过了，跳过即可（要更新就 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）；明显超过样例量说明用户加了自己的目录，换一个他文档里可能出现的词：

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 只有样例量），就直接用下面这四个针对内置样例库的问题：

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

快速开始

进阶使用

给 Agent 的安装指南

致 AI Agent

你的任务

你的边界与规则

先确认你能不能执行命令

第 0 步：探测当前状态

怎么读探测结果

状态判定表

第 1 步：安装与初始化

1. 下载并安装

2. 走完首次启动的引导

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

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

5. 全部做完后回复一次

第 2 步：打通工具链路

方案 A：安装 CLI（推荐）

方案 B：配置 MCP

第 3 步：安装 Skills

第 4 步：端到端验收

故障排查

完成后向用户汇报

最后附上四个示例提问

延伸阅读

​致 AI Agent

​你的任务

​你的边界与规则

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

​第 0 步：探测当前状态

​怎么读探测结果

​状态判定表

​第 1 步：安装与初始化

​1. 下载并安装

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

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

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

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

​第 2 步：打通工具链路

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

​方案 B：配置 MCP

​第 3 步：安装 Skills

​第 4 步：端到端验收

​故障排查

​完成后向用户汇报

​最后附上四个示例提问

​延伸阅读

致 AI Agent

你的任务

你的边界与规则

先确认你能不能执行命令

第 0 步：探测当前状态

怎么读探测结果

状态判定表

第 1 步：安装与初始化

1. 下载并安装

2. 走完首次启动的引导

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

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

5. 全部做完后回复一次

第 2 步：打通工具链路

方案 A：安装 CLI（推荐）

方案 B：配置 MCP

第 3 步：安装 Skills

第 4 步：端到端验收

故障排查

完成后向用户汇报

最后附上四个示例提问

延伸阅读