给 Agent 的云端知识库接入指南

这篇文档的主要读者是 AI Agent，而不是人类。在任意一个云端知识库页面上点击「在 AI 中使用」，把弹窗里的那句话复制给你的 AI 助理即可。也可以手动发起——把下面这句话里的知识库网址换成你要用的那个：

请阅读 https://linkly.ai/docs/zh/library-setup.md 并引导我接入这个知识库：https://linkly.ai/blueeon/linkly-init-example

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

**这条路不需要安装 Linkly AI 桌面应用。**云端知识库托管在服务端，24 小时在线，任何支持 MCP 的 AI 工具都能直接检索。如果你想索引的是自己电脑上的文件，那是另一件事，见给 Agent 的安装指南。

致 AI Agent

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

你的任务

让用户能用某个指定的云端知识库问答。最终达成的状态是：

你所在的客户端已经接上 Linkly AI 云端网关（mcp.linkly.ai）；
你能用 library="cloud://<owner>/<slug>" 真实检索到这个库里的内容；
你已经带用户问出了第一个真实问题，并给出了基于真实文档的回答。

第一件事：把网址换算成库标识

用户交给你的是这个知识库的网页地址，形如：

https://linkly.ai/blueeon/linkly-init-example

而检索工具的 library 参数要的是库标识。两者是同一个东西的两种写法——把域名前缀 https://linkly.ai/ 换成 cloud:// 即可，后面的 <owner>/<slug> 两段原样保留：

用户给你的（网页地址）	你传给工具的（库标识）
`https://linkly.ai/blueeon/linkly-init-example`	`cloud://blueeon/linkly-init-example`
`linkly.ai/7running/basedge`	`cloud://7running/basedge`

不要把网页地址原样传给 library 参数，会被拒绝。本文后面所有例子里的 cloud://… 都是换算之后的结果。如果用户给的网址后面还带了别的路径段（如 /settings）或查询参数，只取 <owner>/<slug> 这两段。拿不准的时候，接上 MCP 后调一次 list_libraries，返回结果里就是准确的库标识。

你的边界与规则

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

你可以自己做：探测当前连接状态、写入 MCP 配置、发握手请求、调用检索工具、解读报错、向用户汇报。写入配置类命令执行前必须先展示给用户并取得同意。
必须交给用户做：注册 / 登录 linkly.ai、设置用户名、在库页面点击「连接」、在控制台生成 API 密钥、在网页里完成 OAuth 授权。这些都是浏览器里的操作，你无法代劳。

以及几条硬规则，每一条都对应一个真实会失败的场景：

不要覆盖用户已有的本地 MCP 配置。 装过桌面应用的用户，客户端里通常已有一个名为 linkly-ai 的 server 指向 http://127.0.0.1:60606/mcp。云端是另加一条，名字必须用 linkly-ai-cloud。同名写入会静默替换掉本地那条，用户会突然搜不到自己电脑上的文档，且不会收到任何报错。
本地连接访问不到云端库。 linkly-ai（本地 / 局域网）这条路上的 cloud:// 引用每次都会被拒绝。不要在本地连接上重试云端库，那是链路边界，不是偶发故障。
每次检索都必须显式传 library。 省略 library 参数时，网关默认路由到用户本机（走桌面隧道），而隧道是 Pro 功能——免费用户会直接收到报错。云端库永远不会被隐式包含进来。
一个库一次调用。 云端库之间不会自动合并检索，要查两个库就调两次。
先探测，再动手。 用户可能已经配好了一半，不要从头盲目跑一遍。
需要用户操作时，一次性说清，然后停下来等一次回复。 不要把一件事拆成好几轮来回确认。
不要谎报进度。 没验证成功就是没成功，如实说明卡在哪、你试过什么。

先确认你是哪一类客户端

接下来走哪条路，取决于你能不能写配置、能不能执行命令：

你是	走哪条路
有命令行 / 能改配置文件（Claude Code、Codex、Cursor、Gemini CLI…）	API 密钥路线（第 2 步方案 A）
无命令行的在线应用（ChatGPT、Claude.ai…）	OAuth 路线（第 2 步方案 B），只需要填一个 URL
Linkly AI 桌面应用自带的 Chat	什么都不用配，见下方捷径

捷径：如果用户已经装了 Linkly AI 桌面应用，他可以直接在应用内的 Chat 里用 @ 提及已连接的云端知识库，不需要配置任何 MCP。这条路只需要完成第 1 步。

第 0 步：探测当前状态

先判断链路已经到了哪一步，再决定从哪里开始。三件事： 1. 你当前会话里有没有 Linkly 的检索工具？来自哪个 server？ 云端网关会自报名字 linkly-ai-cloud，本地桌面应用自报 linkly-ai。多数客户端会把 server 名体现在工具名里（如 mcp__linkly-ai-cloud__search）。 2. 如果你有命令行，直接列一下已配置的 server：

claude mcp list        # Claude Code
codex mcp list         # Codex

看每条的 URL：127.0.0.1 开头是本地，mcp.linkly.ai 是云端。 3. 用户有没有 linkly.ai 账号、有没有连接过这个库？ 这个你查不了，直接问用户。

状态判定表

从上往下匹配，命中第一条就照它走：

探测结果	说明	从哪一步开始
已有 `linkly-ai-cloud` 且能列出库	云端链路已通	直接做第 3 步验收
已有 `linkly-ai-cloud`，但列不出目标库	链路通了，库还没被连接	第 1 步（只做”连接知识库”那一项）
只有 `linkly-ai`（本地）	装了桌面端，但没配云端	第 1 步。注意保留本地那条，不要覆盖
完全没有 Linkly 相关的 server	全新用户	第 1 步

第 1 步：请用户准备账号并连接知识库

这一步全部在浏览器里完成，你无法代劳。请把下面的内容一次性告诉用户，然后停下来等一次回复——不要拆成多轮逐条确认。以下是你要转达给用户的内容（可以按你的风格重述，但四个环节都要说到）：

1. 注册并登录

前往 https://linkly.ai 注册或登录，支持 Google / GitHub / Notion 账号。免费账户即可完成全部接入。

2. 设置用户名（首次登录才需要）

云端知识库的地址形如 linkly.ai/<username>/<slug>，所以账号需要一个唯一用户名。在 Dashboard 里按提示设置一次即可，之后不用再管。

3. 打开目标库页面，点击「连接」

访问这个库的网页地址（例如 https://linkly.ai/blueeon/linkly-init-example），点击页面右上角的「连接」按钮（英文界面是 Link）。按钮变成「已连接」、状态徽章显示”已连接”就算成功。

**即使是用户自己创建的库，也必须点一次「连接」。**MCP 的可检索范围以”连接关系”为准，不以”所有权”为准——没连接的库，哪怕是自己的，在 list_libraries 里也看不到。

免费账户有 1 个连接位（Slot）。如果已经连了别的库，需要先断开那一个，或者升级 Pro（99 个连接位）。库页面上的配额弹窗里有升级入口。

4. 拿到凭证（二选一）

你的 AI 助理有命令行 / 能改配置文件：前往 https://linkly.ai/dashboard/integrations**，在「**API 密钥」区点击新建，复制生成的密钥（以 lkai_ 开头）。这个密钥等同于账号凭证，只给自己的 AI 工具用，不要分享。
你用的是 ChatGPT、Claude.ai 这类在线应用：不需要 API 密钥，跳过这一项，后面会在浏览器里完成一次授权。

验收判据：用户回复库页面上的按钮已经变成「已连接」。如果用户走的是 API 密钥路线，同时确认他拿到了 lkai_ 开头的密钥。

第 2 步：接入云端 MCP

端点是固定的：

https://mcp.linkly.ai/mcp

server 名一律用 linkly-ai-cloud，不要用 linkly-ai——后者是本地桌面应用的名字，同名会覆盖用户已有的本地配置，而且装了 Linkly Skills 的 Agent 会把这条连接误判成本地连接，进而拒绝所有 cloud:// 请求。

方案 A：API 密钥（有命令行的客户端，推荐）

先把命令展示给用户、说明它会把密钥写入本地配置文件，取得同意后再执行。 Claude Code：

claude mcp add --transport http linkly-ai-cloud https://mcp.linkly.ai/mcp \
  --header "Authorization: Bearer lkai_你的密钥"

其他支持 HTTP MCP 的客户端，在各自的配置文件里加一段（Cursor 是 mcp.json，Gemini CLI 是 ~/.gemini/settings.json，字段名以各家文档为准）：

{
  "mcpServers": {
    "linkly-ai-cloud": {
      "url": "https://mcp.linkly.ai/mcp",
      "headers": {
        "Authorization": "Bearer lkai_你的密钥"
      }
    }
  }
}

各客户端的字段差异（url / httpUrl / serverUrl）见各 AI 客户端集成指南。部分客户端支持 ${env:LINKLY_API_KEY} 语法从环境变量读取，可以避免把密钥明文写进配置文件。 验收判据：直接发一次握手请求确认服务端正常：

curl -sf --max-time 10 -X POST https://mcp.linkly.ai/mcp \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -H "Authorization: Bearer lkai_你的密钥" \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"setup-probe","version":"1"}}}'

返回内容包含 "serverInfo":{"name":"linkly-ai-cloud" 即说明凭证有效、链路健康。如果返回 401，密钥不对或已被吊销，让用户回控制台重新生成。

方案 B：OAuth（ChatGPT、Claude.ai 等在线应用）

这类应用不能填自定义请求头，走 OAuth 授权，反而更简单——只需要填一个 URL：

添加 MCP 连接器

在应用的连接器 / MCP 设置里新增一个服务器，名称填 linkly-ai-cloud，URL 填 https://mcp.linkly.ai/mcp。

完成浏览器授权

保存后应用会自动跳转到 linkly.ai 的授权页。用户登录并确认授权后，应用即拿到访问令牌，后续请求自动携带，不需要再次授权。

各应用的具体入口位置见在 ChatGPT 中使用和在 Claude 中使用。

方案 C：CLI（可选）

如果用户装了 Linkly AI CLI，也可以走命令行：

linkly auth set-key lkai_你的密钥
linkly search "关键词" --remote --library "cloud://blueeon/linkly-init-example"

--remote 是 CLI 唯一能触达云端库的模式，省略它就只查本地。

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

第 3 步：端到端验收

工具可用之后（可能需要用户重启会话），做两件事确认整条链路真的通了。 1. 确认库在列表里： 调用 list_libraries，返回的列表里应该能看到目标库，形如：

- **cloud://blueeon/linkly-init-example** (305 docs) [yours]: Linkly AI 安装包初始化的文档

看不到就是没连接成功，回第 1 步第 3 项。 2. 做一次真实检索：

search(query="…", library="cloud://blueeon/linkly-init-example")

成功的标准：返回了真实的文档条目。

library 参数每次都要带，而且必须是完整的 cloud://<owner>/<slug> 两段式——只写一段（如 cloud://linkly-init-example）会被拒绝。省略 library 时网关会默认去查用户本机，免费账户在这条路上会直接报错。

如果第一次检索返回空，不要立刻归因于配置错误。按顺序排查：查询词是否太窄 → list_libraries 里这个库的文档数是不是 0（库主还没推送内容）→ 换 explore 看一眼这个库整体有什么，再针对性地搜。

故障排查

现象	原因与处理
握手返回 401	密钥无效或已吊销。让用户到控制台重新生成，注意复制完整（以 `lkai_` 开头）。
握手返回 403	凭证缺少 `mcp` 权限。重新生成一个 API 密钥即可。
`list_libraries` 里没有目标库	库还没被连接。让用户去库页面点「连接」；自己的库同样要点。
点「连接」提示配额已满	免费账户只有 1 个连接位。先断开另一个库，或升级 Pro（99 个）。
报错提到 Desktop 不可达 / 需要 Pro	你漏传了 `library` 参数，请求被默认路由到了用户本机。补上 `library="cloud://owner/slug"` 重试。
`cloud://` 被拒绝，提示不支持	你连的是本地 server（`linkly-ai`），不是云端网关。这条路径上云端库不可达，必须新增 `linkly-ai-cloud` 连接。
提示 `library must be in 'owner/slug' format`	多半是把网页地址原样传进 `library` 了。按开头的换算规则改成 `cloud://<owner>/<slug>` 两段式；单段同样会被拒绝。拿不准就用 `list_libraries` 取准确值。
配好了但工具没出现	需要重新加载配置或新建会话。这是客户端的加载机制，不是配置错误。
用户原来的本地搜索突然搜不到东西了	云端配置用了 `linkly-ai` 这个名字，覆盖掉了本地那条。改用 `linkly-ai-cloud`，并重新添加指向本机的那条配置。
库里文档数是 0	库主还没把内容推送到云端。这不是你能修的，如实告知用户。

完成后向用户汇报

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

接入走的是哪条路（API 密钥还是 OAuth）、server 名是什么；
是否需要重启会话才能生效；
这个库里有多少文档、大致是什么内容；
后续怎么用——提醒他每次想查这个库时说清楚库名即可，你会自动带上 library 参数。

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

最后附上四个示例提问

汇报的末尾，给用户四个可以直接复制去试的问题。必须基于这个库的真实内容来定制：先用 explore 看一眼这个库的整体构成，必要时再 search 抽查几个主题，然后写出四个真正指向这个库内容的问题。不要写”总结这个知识库”这种放之四海皆准的空话——好问题应该让用户一眼看出”这确实是在说这个库里的东西”。

快速开始

核心功能

接入 AI 工具

给 Agent 的指南

给 Agent 的云端知识库接入指南

致 AI Agent

你的任务

第一件事：把网址换算成库标识

你的边界与规则

先确认你是哪一类客户端

第 0 步：探测当前状态

状态判定表

第 1 步：请用户准备账号并连接知识库

1. 注册并登录

2. 设置用户名（首次登录才需要）

3. 打开目标库页面，点击「连接」

4. 拿到凭证（二选一）

第 2 步：接入云端 MCP

方案 A：API 密钥（有命令行的客户端，推荐）

方案 B：OAuth（ChatGPT、Claude.ai 等在线应用）

方案 C：CLI（可选）

第 3 步：端到端验收

故障排查

完成后向用户汇报

最后附上四个示例提问

延伸阅读

​致 AI Agent

​你的任务

​第一件事：把网址换算成库标识

​你的边界与规则

​先确认你是哪一类客户端

​第 0 步：探测当前状态

​状态判定表

​第 1 步：请用户准备账号并连接知识库

​1. 注册并登录

​2. 设置用户名（首次登录才需要）

​3. 打开目标库页面，点击「连接」

​4. 拿到凭证（二选一）

​第 2 步：接入云端 MCP

​方案 A：API 密钥（有命令行的客户端，推荐）

​方案 B：OAuth（ChatGPT、Claude.ai 等在线应用）

​方案 C：CLI（可选）

​第 3 步：端到端验收

​故障排查

​完成后向用户汇报

​最后附上四个示例提问

​延伸阅读

致 AI Agent

你的任务

第一件事：把网址换算成库标识

你的边界与规则

先确认你是哪一类客户端

第 0 步：探测当前状态

状态判定表

第 1 步：请用户准备账号并连接知识库

1. 注册并登录

2. 设置用户名（首次登录才需要）

3. 打开目标库页面，点击「连接」

4. 拿到凭证（二选一）

第 2 步：接入云端 MCP

方案 A：API 密钥（有命令行的客户端，推荐）

方案 B：OAuth（ChatGPT、Claude.ai 等在线应用）

方案 C：CLI（可选）

第 3 步：端到端验收

故障排查

完成后向用户汇报

最后附上四个示例提问

延伸阅读