> ## 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**，而不是人类。

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

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

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

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

***

## 致 AI Agent

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

### 你的任务

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

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

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

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

```
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                              | 什么都不用配，见下方捷径                       |

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

***

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

先判断链路已经到了哪一步，再决定从哪里开始。三件事：

**1. 你当前会话里有没有 Linkly 的检索工具？来自哪个 server？**

云端网关会自报名字 `linkly-ai-cloud`，本地桌面应用自报 `linkly-ai`。多数客户端会把 server 名体现在工具名里（如 `mcp__linkly-ai-cloud__search`）。

**2. 如果你有命令行，直接列一下已配置的 server：**

```bash theme={null}
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](https://linkly.ai)** 注册或登录，支持 Google / GitHub / Notion 账号。免费账户即可完成全部接入。

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

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

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

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

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

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

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

* **你的 AI 助理有命令行 / 能改配置文件**：前往 **[https://linkly.ai/dashboard/integrations\*\*，在「\*\*API](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：**

```bash theme={null}
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`，字段名以各家文档为准）：

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

各客户端的字段差异（`url` / `httpUrl` / `serverUrl`）见[各 AI 客户端集成指南](/docs/zh/integration)。部分客户端支持 `${env:LINKLY_API_KEY}` 语法从环境变量读取，可以避免把密钥明文写进配置文件。

**验收判据**：直接发一次握手请求确认服务端正常：

```bash theme={null}
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**：

<Steps>
  <Step title="添加 MCP 连接器">
    在应用的连接器 / MCP 设置里新增一个服务器，名称填 `linkly-ai-cloud`，URL 填
    `https://mcp.linkly.ai/mcp`。
  </Step>

  <Step title="完成浏览器授权">
    保存后应用会自动跳转到 linkly.ai
    的授权页。用户登录并确认授权后，应用即拿到访问令牌，后续请求自动携带，不需要再次授权。
  </Step>
</Steps>

各应用的具体入口位置见 [在 ChatGPT 中使用](/docs/zh/integration/use-in-chatgpt) 和 [在 Claude 中使用](/docs/zh/integration/use-in-claude)。

### 方案 C：CLI（可选）

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

```bash theme={null}
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")
```

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

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

如果第一次检索返回空，不要立刻归因于配置错误。按顺序排查：查询词是否太窄 → `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` 抽查几个主题，然后写出四个真正指向这个库内容的问题。不要写"总结这个知识库"这种放之四海皆准的空话——好问题应该让用户一眼看出"这确实是在说这个库里的东西"。

***

## 延伸阅读

* [使用云端知识库](/docs/zh/use-cloud-library) —— 面向人类读者的完整说明：创建、推送、分享、配额
* [给 Agent 的安装指南](/docs/zh/agent-setup) —— 想索引自己电脑上的文件时走这一篇
* [工具介绍](/docs/zh/tools-intro) —— 七个检索工具的完整参数说明
* [使用 Skills](/docs/zh/use-skills) —— 让 AI 助理更懂得如何组合这些工具