给 Agent 的安装指南

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

按 https://linkly.ai/docs/zh/agent-setup.md 完成设置

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

致 AI Agent

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

你的任务

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

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

你的边界与规则

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

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

以及几条硬规则：

先探测，再动手。 用户可能已经装了一半，也可能是重装，不要从头盲目跑一遍。
每一步都要验证。 每步都给了验收判据，判据不满足就不要进入下一步。
需要用户操作时，一次性说清，然后停下来等一次回复。 不要把一件事拆成好几轮来回确认。
执行安装类命令前，先把完整命令展示给用户并取得同意。 尤其是从网络下载并执行脚本的命令。
MCP 和 Skills 写入配置后，不要在当前会话里反复试探工具是否出现。 新工具要等客户端重新加载才会进来，这是加载机制，不是故障——写入成功就算这一步完成，剩下的验证留给用户重新加载之后做。
不要谎报进度。 没验证成功就是没成功，如实说明卡在哪、你试过什么。
不要向用户索要 API Key（lkai_ 开头）或局域网访问令牌，也不要替用户执行 linkly auth set-key。 它们等同于读取用户本机资料库的钥匙，经过对话就会发送给模型服务商、写进会话记录。需要登录时用 linkly auth login 的两步流程（见远程分支 R2–R4），用户只在浏览器里授权。如果用户把 Key 或令牌发给了你，不要使用，提醒他到控制台（https://linkly.ai/dashboard/integrations）撤销并重新生成；局域网令牌在桌面端「查看 MCP 接入配置」里重新生成。
不要绕过权限、安全或验收要求。 故障排查表没覆盖的问题，先跑 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–4 步默认桌面应用和你在同一台电脑上。如果它根本不会装在你这里——你是跑在远程服务器、容器或云主机上的机器人，而用户的桌面应用（如果有的话）在另一台电脑上——不要让用户在你这边安装桌面应用。跳过第 0–4 步，改按下文的远程分支：本机没有桌面应用执行。判断不了就问用户一次。

第 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": "1.1.0",
  "doc_count": 12009,
  "mcp_endpoint": "http://127.0.0.1:60606/mcp",
  "index_status": "watching",
  "capabilities": ["clips-v1", "reveal-v1", "clip-tags-v1"]
}

几个关键点：

端口不要写死 60606。 60606 只是默认值，被占用时应用会向上顺延。始终从 ~/.linkly/port 读取实际端口，该文件内容是紧凑 JSON {"port":60606}。
port 文件存在不等于服务在跑。 应用被强杀或崩溃时该文件会残留。/health 返回 200 可以证明服务健康；但在 AI Agent 网络沙箱中，/health 不可达只能说明链路失败，不能证明 Desktop 已退出，因为沙箱可能会阻断 localhost。
mcp_endpoint 为 null 说明 MCP 开关被关掉了（/health 仍返回 200）。这时不要去排查端口，请让用户点击主窗口左侧栏底部的 Agent 图标进入「Agent 使用」页，打开「管理」区的「允许本机访问」开关（或点「已停止」卡片上的「启动」按钮）。
index_status 的取值：watching（已完成，CLI 显示 Up to date）、scanning、indexing、idle、error。
doc_count 是已索引文档数，用来看索引进度，不是判断”用户文档进来没有”的硬证据——它只是总数，加了一两个文件时 151 和 150 几乎分不出来。

状态判定表

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

探测结果	说明	从哪一步开始
无 port 文件，`/health` 不可达	没装，或从未启动过	第 1 步
有 port 文件，但 `/health` 不可达	Desktop 已退出，或探测被沙箱阻断	有 MCP 就改用 MCP；否则批准在网络沙箱外重试。只有重试仍失败时才请用户启动 Desktop
`/health` 200，但 `index_status` 为 `error`	索引出错	先跑 `linkly doctor` 并看 Local 组（无 CLI 就请用户从设置 → 通用 → 应用数据 → 打开找到 `logs/app.log`），恢复前不要继续
`/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：x86_64 AppImage 方式 chmod +x LinklyAI-*.AppImage && ./LinklyAI-*.AppImage（需要 glibc 2.35 或更高版本，如 Ubuntu 22.04+ / Debian 12+；无法启动时按 Linux AppImage 排障说明处理）。

2. 走完首次启动的引导

首次启动会打开引导窗口，依次是封面 → 把资料放进来 → 接入 Agent → 一切就绪（步进器只对中间两屏计数，所以显示 1/2、2/2）。界面语言和外观在每一屏右下角都可以切换。

封面：必须勾选”已阅读并同意隐私政策”才能继续。同屏还有一个”帮助改进 Linkly AI（匿名）“的遥测选项，默认勾选，介意的话可以取消。
把资料放进来（1/2）：「示例资料」是必选的，应用会在后台为它建立索引，不需要等待。下面的「文稿」「桌面」「下载」默认不勾，可按需勾选；macOS 上勾选时会弹出系统授权框，需要点允许。
接入 Agent（2/2）：点「安装 Linkly CLI 与 Skills」右侧的「安装」，应用会在后台装好 CLI 和 Skills；「自动保持 CLI 和 Skills 最新」默认开启。不点「安装」就不会装，之后也可以在主窗口的「Agent 使用」页安装。
一切就绪：点「立即开始」结束引导，打开主窗口首页。

引导里没有登录这一步。请告知用户：登录只用于官方 AI 模型额度和云端知识库等功能，本地索引、本地检索、MCP 服务完全不需要登录，也不需要连接网络。

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

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

在主窗口左侧栏打开「资料库」，点「添加新目录」，添加想要索引的目录（例如「文档」「下载」或某个项目目录）；
或者直接把文件放进 ~/LinklyAI 文件夹——该目录默认被监视，放进去就会自动索引。

如果系统提示权限不足（macOS 常见），需要前往 系统设置 → 隐私与安全性 → 完全磁盘访问权限 添加 Linkly AI，然后重启应用。建议用户将自己的 document、网盘、NAS等存放大量本地文件的目录添加到索引中。

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

首次启动后应用会在后台下载约 890MB 的模型文件（语义检索模型约 639MB，OCR 模型约 249MB；之后开启音视频转写时，还会再下载约 161MB 的语音转写模型），视网速可能需要几分钟到几十分钟。这期间：

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

5. 全部做完后回复一次

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

验收判据：/health 返回 200 且 doc_count 大于 0。如果刚点完引导 doc_count 还是 0、且 index_status 是 scanning/indexing，说明样例还在入库——间隔 10 秒最多重试 6 次；仍为 0 就按故障排查里的 error 处理。用户加了自己的目录时 doc_count 会明显超过样例量；没加也不影响往下走。 用户回复之后：如果用户在「接入 Agent」这一屏点了「安装」，CLI 和 Skills 可能已经装好了。CLI 在 ~/.linkly/bin/linkly（Windows 为 %LOCALAPPDATA%\linkly\bin\linkly.exe），Skills 在 ~/.agents/skills/linkly-ai/。

先重跑第 0 步的探测。已装好的就跳过第 2 步方案 A 和第 3 步，不要重复安装。
linkly 命令找不到时，先让用户新开一个终端窗口。
例外：如果你是 Claude Code，而 ~/.claude/skills/linkly-ai 不存在，Skills 对你仍不可见（Claude Code 不读取 ~/.agents/skills）。这时仍要执行 linkly skills install，它会补上这个链接。

第 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。） 接下来每次调用都要报上自己的名字。 从这里开始，每条 linkly 命令都加上 --client <你的应用名>——--client claude-code、--client cursor，你叫什么就填什么。桌面端会在本地记录访问日志，让用户看得出是哪些 AI 应用读了自己的资料；不填的话，你的调用在那里只是一条没有名字的本机记录。它是标签不是凭证：不授予任何权限，也不会被拿去校验。

方案 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?client=claude-code"
Codex：codex mcp add linkly-ai --url "$MCP_URL?client=codex"
Cursor：设置 → MCP Servers → Add Server，Name 填 linkly-ai，Type 选 StreamableHTTP，URL 填 $MCP_URL 的实际值并在末尾加上 ?client=cursor。

关于 ?client=：桌面端会在本地记录访问日志，让用户看得出是哪些 AI 应用读了自己的资料，这个参数就是让调用在那里有个名字。填你自己应用的名字。它是标签不是凭证：不授予任何权限，也不会被拿去校验，所以不填也只是少个名字而已。（走远程隧道时不用加——那条路的名字来自 OAuth 登录。）更多客户端的配置方式见通过 MCP 集成 AI 助理。 配置完 MCP 后，新工具通常不会在当前会话里立即生效——绝大多数客户端只在会话启动的那一刻读一次工具列表。这是客户端的加载机制，不是配置出错，不要在当前会话里反复试探工具是否出现。 怎么重新加载：把下面两种做法转达给用户，让他先试第一种。

新建一个对话（命令行工具就是退出后重新开一个会话）。已经在进行中的对话会一直沿用它启动时的工具列表，新开一个就能拿到最新的。
完全退出客户端，再重新打开。 第一种不管用时用这个——注意关闭窗口不等于退出：macOS 要按 Cmd + Q 或从菜单栏选「退出」，Windows 要确认托盘图标里也退出了。

验收判据：配置文件已写入成功。若想在不重启的情况下确认服务端正常，直接发一次握手请求（$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 开关被关了，请用户到「Agent 使用」页打开「管理」区的「允许本机访问」开关（或点「已停止」卡片上的「启动」按钮）。

第 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 同样要重新加载才会生效，做法和第 2 步说的一样——先新建一个对话，不行就完全退出客户端再重新打开。验收判据是”文件已落到对应目录”，而不是”当前会话已能调用”。装完后请提醒用户重新加载。 验收判据：以下任一路径存在 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）：你无法在本会话内完成这一步——工具要等客户端重新加载才会出现，这是加载机制决定的，不是失败。请以”配置已写入、服务端握手正常、待用户重新加载后验证”结题，把第 2 步那两种重新加载的做法再说一遍，并把下面这句交给用户，然后停止（这不算谎报进度）：

重新加载之后，把这句话发给我：「用 linkly-ai 搜一下 Holmes」。返回了文档条目就说明全链路通了。

重新加载之后是一个全新的会话，那边的你拿不到现在这段上下文。所以这句交接话必须自带用得上的信息（server 名、要搜的词），不能写成”接着刚才的继续”。如果 CLI 检索返回空，别急着归因于模型——search 在模型没就绪时只会退化为纯关键词检索、不会返回空。按顺序排查：查询词是否合适 → doc_count 是否为 0（样例还没入库，见第 1 步验收判据）→ 用户目录是否加了 → 文档格式是否支持。用 linkly status --json 看 index_status：indexing 说明还在建索引或下模型，等待即可；error 见故障排查。注意：扫描刚结束、正文提取尚未开始的一小段时间里，index_status 会短暂显示 watching（即 Up to date）。不要只采样一次就判定就绪，隔几秒再看一次，或看 doc_count 是否还在增长。

远程分支：本机没有桌面应用

当你所在的机器上没有 Linkly AI 桌面应用（例如跑在远程服务器或容器里的机器人），而用户的桌面应用（如果有）在另一台电脑上时，用这一节代替第 0–4 步。你通过云端访问用户的内容。下面的登录流程由用户在浏览器里授权，CLI 自动保存 Key，Key 不经过对话，用户也不必复制。

R1：安装 CLI

使用第 2 步方案 A 里的安装命令，规则不变：先展示命令、征得同意再执行。 验收判据：linkly --version 能输出版本号。linkly status 在这里会失败——这台机器上没有桌面应用，这是预期之内的。

R1.5：检查是否已登录

linkly auth status --json

remote.valid 为 true 说明用户已登录，直接跳到 R5；为 null 说明暂时连不上网关，稍后重试，不要登出。

R2：发起登录

linkly auth login --no-wait --json

它会立即返回 {"status":"pending","url":…,"user_code":…,"expires_in":600}。如果失败，提示里会写明下一步该执行的命令——照着做。

R3：把链接交给用户，然后停下等待

一条消息把下面这些都发给用户，然后停下，等待一次回复：

url——可以在任意设备上打开，手机也行；
user_code——点击授权之前，请用户核对页面上显示的是同一个确认码；
链接 10 分钟内有效；页面会显示正在授权的是哪个账号，请用户确认没有选错。

R4：完成登录

linkly auth login --wait --json

成功时返回 {"status":"ok","account":…,"plan":…,"key_preview":…}。遇到 timeout 就再执行一次同样的命令——链接在过期前一直有效。遇到 expired 或 denied，从 R2 重新开始。 **用户说”好了”不算数。**只信 CLI 的输出：--wait 没有返回 "status":"ok" 之前，登录就没有完成。

**R2 和 R4 必须在同一个环境、同一个系统用户、同一个配置目录下执行。**等待中的登录就存在那个目录里；换一个新容器、换一个用户或换一个 LINKLY_CONFIG_DIR，都看不到它。
**同时为多个用户服务？**给每个用户分配各自的 LINKLY_CONFIG_DIR（一个目录只保存一个账号），并在替该用户执行的每条命令上都带上它，例如 LINKLY_CONFIG_DIR=~/.linkly-alice linkly auth login --no-wait --json。
环境被重建、凭据丢失时，从 R2 重新登录即可。

R5：分三层验收

逐层检查、逐层汇报——前一层通过不代表下一层也通过。

登录成功：linkly auth status --json 显示 "valid": true，并带有订阅方案。这只证明了账号，不证明任何内容可以访问。
云端检索可用（Free 方案即可）：选一个用户已连接的云端知识库（不知道的话问用户），执行：
linkly search "<query>" --remote --library cloud://<owner>/<slug>
返回真实结果即为通过。用户没有云端知识库时，要说明这一层是跳过了，而不是通过了。
本地检索可用（用户桌面上的文档）：需要 Pro，并且桌面应用在线、远程访问已连接（见远程访问）。先检查：
linkly doctor --remote
隧道已连接时，执行 linkly search "<query>" --remote，应返回真实结果。如果桌面应用离线或隧道未连接，如实汇报，并请用户打开桌面应用，在「Agent 使用」页的「管理」区打开「允许远程访问（公网）」开关，等状态显示「已连接」——不要宣称成功。

故障排查

现象	原因与处理
`/health` 连接被拒绝	桌面应用没在运行。请用户启动应用后重试。
port 文件存在但 `/health` 不通	上次是异常退出留下的残留文件。请用户重新启动应用。
端口连不上，但应用确实在跑	60606 被占用后端口会顺延。从 `~/.linkly/port` 读实际端口，不要写死。
`/health` 正常但握手返回 403	MCP 开关被关了。请用户到「Agent 使用」页打开「允许本机访问」开关（或点「已停止」卡片上的「启动」）。
`index_status` 为 `error`	索引出错。跑 `linkly doctor` 并看 Local 组（无 CLI 就让用户从设置 → 通用 → 应用数据 → 打开找到 `logs/app.log`），恢复前不要继续。
`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 + L 打开搜索启动器、Cmd/Ctrl + K 打开主窗口（从旧版升级的用户保留原来设置的快捷键）。

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

最后附上四个示例提问

汇报的末尾，给用户四个可以直接复制去试的问题。优先根据用户的真实资料来定制：先花一点时间了解用户索引了什么——用 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 回答。

快速开始

核心功能

接入 AI 工具

给 Agent 的指南

给 Agent 的安装指南

致 AI Agent

你的任务

你的边界与规则

先确认你能不能执行命令

再确认桌面应用该不该装在这台机器上

第 0 步：探测当前状态

怎么读探测结果

状态判定表

第 1 步：安装与初始化

1. 下载并安装

2. 走完首次启动的引导

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

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

5. 全部做完后回复一次

第 2 步：打通工具链路

方案 A：安装 CLI（推荐）

方案 B：配置 MCP

第 3 步：安装 Skills

第 4 步：端到端验收

远程分支：本机没有桌面应用

R1：安装 CLI

R1.5：检查是否已登录

R2：发起登录

R3：把链接交给用户，然后停下等待

R4：完成登录

R5：分三层验收

故障排查

完成后向用户汇报

最后附上四个示例提问

延伸阅读

​致 AI Agent

​你的任务

​你的边界与规则

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

​再确认桌面应用该不该装在这台机器上

​第 0 步：探测当前状态

​怎么读探测结果

​状态判定表

​第 1 步：安装与初始化

​1. 下载并安装

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

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

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

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

​第 2 步：打通工具链路

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

​方案 B：配置 MCP

​第 3 步：安装 Skills

​第 4 步：端到端验收

​远程分支：本机没有桌面应用

​R1：安装 CLI

​R1.5：检查是否已登录

​R2：发起登录

​R3：把链接交给用户，然后停下等待

​R4：完成登录

​R5：分三层验收

​故障排查

​完成后向用户汇报

​最后附上四个示例提问

​延伸阅读

致 AI Agent

你的任务

你的边界与规则

先确认你能不能执行命令

再确认桌面应用该不该装在这台机器上

第 0 步：探测当前状态

怎么读探测结果

状态判定表

第 1 步：安装与初始化

1. 下载并安装

2. 走完首次启动的引导

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

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

5. 全部做完后回复一次

第 2 步：打通工具链路

方案 A：安装 CLI（推荐）

方案 B：配置 MCP

第 3 步：安装 Skills

第 4 步：端到端验收

远程分支：本机没有桌面应用

R1：安装 CLI

R1.5：检查是否已登录

R2：发起登录

R3：把链接交给用户，然后停下等待

R4：完成登录

R5：分三层验收

故障排查

完成后向用户汇报

最后附上四个示例提问

延伸阅读