Linkly AI MCP 工具介绍

工具概览

Linkly AI 通过 MCP（Model Context Protocol）向 AI 助理暴露九个工具。核心是一条渐进式的文档访问工作流：

search → grep 或 outline → read
搜索      正则匹配/大纲      阅读

围绕它另有三个发现类辅助工具——list_libraries（列出知识库）、explore（概览文档集合）、find_paths（按关键词定位文件夹路径，配合 search 的 path_glob 使用），加上 list（列举一个容器：某个目录下的文件、某个知识库，或你的笔记），以及唯一的笔记写入工具 note_save（创建 / 编辑笔记）。

search

搜索文档，找到相关结果

outline

查看文档大纲，了解结构

grep

正则匹配，精确定位文本模式

read

阅读文档内容，获取详情

list_libraries

列出知识库及其文档数量

explore

概览文档集合的主题和结构

find_paths

按关键词定位文件夹路径，给 search 的 path_glob 提供候选

list

列举容器内的条目——目录、知识库，或你的笔记

note_save

创建或编辑笔记，唯一的写入工具

除 note_save 外全部是只读工具——它们只读取你的文档，不会修改任何内容。note_save 只能写入笔记目录，且没有删除工具，删笔记只能你自己在应用里做。

检索（search）

搜索已索引的本地文档，返回最相关的结果列表。

参数

参数	类型	必填	默认值	说明
`query`	string	是	—	搜索关键词或短语
`limit`	number	否	20	最大返回结果数（1-50）
`doc_types`	string[]	否	全部	按文档类型过滤。可用取值：`pdf`、`docx`、`pptx`、`epub`、`md`、`txt`、`html`、`image`、`audio`、`video`
`library`	string	否	—	限定在某个知识库内。本地库用名称或 `local://<id>`；云端库用 `cloud://<owner>/<slug>`（仅 `--remote`）。使用 `list_libraries` 查看可用知识库
`path_glob`	string	否	—	按文件路径过滤，对路径做子串匹配——模式可出现在路径任意位置，无需在两端加 ``。`` 匹配任意字符（含 `/`），`?` 匹配单个字符，区分大小写。传入完整目录路径（如 `/Users/me/notes/`）即可限定在该目录内。当真实路径未知时，先调 `find_paths` 获取
`scope`	string	否	`folder`	检索范围。`folder`（默认）按上面的 `library` / `path_glob` 语义检索全部已索引内容；`notes` 只在本地笔记里检索，会忽略 `path_glob` 和本地 `library`；若同时传入 `cloud://` 云端库则会被拒绝——笔记没有云端对应物。传入未知取值会被拒绝
`tags`	string[]	否	—	按笔记标签过滤，AND 语义（必须同时带有列出的全部标签）。标签会被规范化（去掉开头的 `#`、ASCII 转小写）。需要 OR 就每个标签各调一次再合并。通常配合 `scope="notes"` 使用
`modified_after`	string	否	—	修改时间下界（含），ISO 8601 UTC 格式：日期 `2024-01-01`（视为 `00:00:00Z`）或完整 RFC 3339 `2024-01-01T00:00:00Z`
`modified_before`	string	否	—	修改时间上界（含），格式同 `modified_after`
`time_sort`	string	否	`default`	时间排序模式：`default`（保留相关度排序）/ `newest`（最新优先）/ `oldest`（最旧优先）。命中候选集去重之后才重排
`output_format`	string	否	`markdown`	设为 `json` 可获得结构化 JSON 输出

如果向量模型尚在下载中，搜索会自动降级为纯关键词模式，不影响使用。

关于时间过滤和排序：

当用户给出明确的时间窗口（「上个月」、「在 2024 年」、「近三个月」）时，用 modified_after / modified_before。
当用户只是说「最近的」、「最新的」、「最早的」，没有具体范围时，用 time_sort=newest 或 oldest。
两者可以组合：「2024 年里最早的」等于 modified_after=2024-01-01 + modified_before=2024-12-31 + time_sort=oldest。
计算「上个月」等相对时间时，先从任何工具响应末尾的 [meta] now=... 字段读取当前 UTC 时间，再做日期推算（详见下方响应元数据）。

返回字段

每条搜索结果包含以下信息：

字段	说明
`doc_id`	文档唯一标识，用于后续 outline/read 调用
`title`	文档标题
`path`	文件路径
`relevance`	相关度分数（0-1）
`word_count`	文档字数
`total_lines`	文档总行数
`has_outline`	是否有可用大纲
`modified_at`	最后修改时间
`keywords`	提取的关键词列表
`snippet`	匹配的内容摘要片段

使用示例

# CLI 方式
linkly search "项目管理最佳实践" --limit 10

# 过滤文档类型
linkly search "季度报告" --type pdf,docx --json

# 在指定知识库中搜索
linkly search "深度学习" --library my-research --limit 10

# 按路径过滤
linkly search "报告" --path-glob "*2024*"

# 限定时间窗口（2024 年 Q3 的季度报告）
linkly search "季度报告" --modified-after 2024-07-01 --modified-before 2024-09-30

# "最新的周会纪要" — 没有具体窗口时，按时间倒序
linkly search "周会纪要" --time-sort newest --limit 5

大纲（outline）

获取一个或多个文档的结构化大纲和元数据，帮助快速了解文档结构并定位目标章节。

参数

参数	类型	必填	默认值	说明
`doc_ids`	string[]	是	—	文档 ID 列表（来自搜索结果）
`expand`	string[]	否	自动	要展开的节点 ID（如 `["2", "3.1"]`），省略则自动展示所有层级
`output_format`	string	否	`markdown`	设为 `json` 可获得结构化 JSON 输出

何时使用大纲

场景	建议
文档 > 50 行且有大纲	先查看大纲，再读取目标章节
短文档（< 50 行）	跳过大纲，直接 `read` 全文
`has_outline: false` 的文档	使用 `grep` 定位模式或 `read` 逐页浏览

大纲功能对有书签的 PDF、 Markdown、DOCX、PowerPoint (PPTX) 和 EPUB 文档效果最好，在阅读大部头的文档、书籍的时候会获得事半功倍的效果。纯文本和无书签的 PDF 将在后续迭代中提供大纲支持。

使用示例

# 查看单个文档大纲
linkly outline abc123

# 批量查看多个文档
linkly outline id1 id2 id3

# JSON 格式输出
linkly outline abc123 --json

正则匹配（grep）

在单个文档内通过正则表达式定位具体行。最适合 has_outline=false 的文档（无法使用 outline 浏览结构时）。在 search 之后使用，用于精确定位特定文本（人名、日期、术语、标识符等），然后用 read 跳转到匹配位置深入阅读。适用于所有文档类型（PDF、Markdown、DOCX、PPTX、EPUB、TXT、HTML）。如需跨多个文档搜索，请对每个文档分别调用 grep。

参数

参数	类型	必填	默认值	说明
`pattern`	string	是	—	要搜索的正则表达式模式
`doc_id`	string	是	—	要搜索的文档 ID（来自搜索结果）
`context`	number	否	3	每个匹配行前后各 N 行上下文
`before`	number	否	—	匹配行前 N 行上下文（覆盖 `context`）
`after`	number	否	—	匹配行后 N 行上下文（覆盖 `context`）
`case_insensitive`	boolean	否	false	大小写不敏感匹配
`output_mode`	string	否	`content`	`content`（匹配行及上下文）或 `count`（仅统计匹配数，用于预览总量）
`limit`	number	否	20	最大返回匹配行数（最多 100）
`offset`	number	否	0	跳过前 N 条匹配（分页用）
`fuzzy_whitespace`	boolean	否	自动	容忍空白噪声的模糊匹配，用于对付 PDF 提取出来的文本里到处是多余空格和断行的情况。省略时自动判断（PDF 打开、其他格式关闭），也可以传 `true` / `false` 强制
`output_format`	string	否	`markdown`	设为 `json` 可获得结构化 JSON 输出

何时使用 grep 而非 outline

场景	建议
需要查找特定术语、人名或日期	使用 `grep`
需要了解文档整体结构	使用 `outline`
文档没有大纲	使用 `grep` 定位
查找模式（邮箱、编号、数字等）	使用 `grep` 正则

使用示例

# 在文档中查找特定术语
linkly grep "季度营收" 456

# 大小写不敏感搜索，带上下文
linkly grep "error|warning" 1044 -C 3 -i

# 先预览匹配数量再分页阅读
linkly grep "TODO" 591 --mode count

阅读（read）

读取文档内容，支持行号定位和分页，适合阅读长文档的特定部分。Read 工具行为与 Claude AI SDK 的行为一致，因此能够在各种 Agentic AI 模型中获得最佳效果。

参数

参数	类型	必填	默认值	说明
`doc_id`	string	是	—	文档 ID（来自搜索结果）
`offset`	number	否	1	起始行号（从 1 开始）
`limit`	number	否	200	读取行数（最多 500）
`image_text`	string	否	`abstract`	正文里引用的图片要附带多少信息，见下方读取图文混排文档
`output_format`	string	否	`markdown`	设为 `json` 可获得结构化 JSON 输出

读取图文混排文档

很多文档（尤其是 Markdown 笔记和技术文档）的关键信息在插图里。read 会把你正在读的这段行范围内出现的图片引用，解析成对应的已索引图片文档，附在结果末尾。image_text 控制附多少：

取值	附带的内容
`none`	只给映射关系：行号、文件、`doc_id`
`abstract`（默认）	再加每张图的一行文字摘录和字数
`full`	再加内联的完整 OCR 文本

full 有预算限制：单张图最多 2000 字符，整次调用总计 20000 字符。超预算的图片会自动降级成 abstract，并给出可以单独读取它的指引。

先用默认的 abstract 判断哪张图有用，再对那一张单独 read 它的 doc_id，比一上来就 full 省得多。

内容格式

Read 工具将返回带有行号的内容，方便引用和定位：

  1	# 项目需求文档
  2
  3	## 一、项目背景
  4
  5	本项目旨在构建一个高效的知识管理系统...
  6	目标用户为企业研发团队和个人知识工作者。

分页策略

对于长文档，建议分块读取：

# 第一页：第 1-200 行
linkly read <DOC_ID> --offset 1 --limit 200

# 第二页：第 201-400 行
linkly read <DOC_ID> --offset 201 --limit 200

# 第三页：第 401-600 行
linkly read <DOC_ID> --offset 401 --limit 200

结合大纲使用效果更佳 — 通过大纲定位到目标章节的行范围，然后用 read 精确读取该区间的内容。

使用示例

# 读取文档开头
linkly read abc123

# 读取特定范围
linkly read abc123 --offset 120 --limit 80

# JSON 格式（适合程序处理）
linkly read abc123 --json

知识库列表（list_libraries）

列出用户配置的所有知识库及其描述和文档数量。

参数

无需参数。

使用场景

用户询问「我有哪些知识库」时调用
在使用 search 的 library 参数前，确认知识库名称

linkly list-libraries

概览（explore）

获取全部已索引文档或特定知识库的鸟瞰概览。返回文档类型分布、目录结构（含文件数和中位字数）以及高频关键词（标注集中来源）。

参数

参数	类型	必填	默认值	说明
`library`	string	否	—	限定在某个知识库内。本地库用名称或 `local://<id>`；云端库用 `cloud://<owner>/<slug>`（仅 `--remote`）。省略则概览全部本地已索引文档

使用场景

用户想了解知识库或文档集合中大概有什么内容
用户没有明确的搜索主题，想先发现可用的主题和方向
AI 助理需要了解文档集合的规模和主题分布，以便制定有效的搜索策略

概览返回后，可利用其中的关键词和目录名称作为后续 search 查询的线索。

# 概览全部文档
linkly explore

# 概览特定知识库
linkly explore --library my-research

路径定位（find_paths）

按关键词在已索引文档的文件路径上做模糊匹配，聚合到文件夹粒度，返回最匹配的若干候选目录。其定位是 search 的辅助工具：当用户描述容器名（如「在我的微信里」、「在 Notion 笔记里」）但你不知道这个容器在磁盘上的真实路径时，先用 find_paths 探测真实路径，再把它作为 search 的 path_glob 参数。实际目录名往往和用户的口语不一致（「微信」对应 xinWeChat、「Notion 笔记」对应 notion 笔记 等），盲填 path_glob 容易失败。

参数

参数	类型	必填	默认值	说明
`patterns`	string[]	是	—	关键词数组，对每个元素在路径上做子串匹配（内部包装为 SQL `LIKE %关键词%`）。多个关键词之间是 OR 关系，鼓励一次传入多个变体（中英对照、大小写、应用真实命名等），如 `["WeChat", "微信", "wxid", "xinWeChat"]`。ASCII 大小写不敏感；CJK 字面匹配
`library`	string	否	—	限定在某个知识库内。本地库用名称或 `local://<id>`；云端库用 `cloud://<owner>/<slug>`（仅 `--remote`）。使用 `list_libraries` 查看可用知识库
`limit`	number	否	10	最大候选目录数（最多 50）
`output_format`	string	否	`markdown`	设为 `json` 可获得结构化 JSON 输出

返回字段（JSON 模式）

字段	说明
`total_files`	命中并被聚合到候选目录的文件总数（在 `limit` 截断之前）
`truncated`	是否因 `limit` 截断（`true` 表示候选目录还有更多）
`directories`	候选目录数组，按 `file_count` 降序排列。每项含 `path`（完整绝对路径）、`path_glob`（把 `path` 转成可直接填入 `search` 的 `path_glob` 模式：目录名里的 glob 元字符 `* ? [` 会被转义，从而字面匹配该目录；目录名无元字符时与 `path` 相同——可原样复制到后续 `search` 以限定到整个目录）和 `file_count`（该目录下的命中文件数）

聚合行为

关键词只匹配到文件名段（不是任何目录段）的文件会被静默丢弃 —— 这是「找文件夹」工具，不是「找文件」工具。如果某个查询返回 0 个候选目录但你确认有匹配文件，应回退到直接用 search。
每条匹配按其路径中最浅的关键词出现位置做截断聚合：例如 local:///Users/me/Library/.../com.tencent.xinWeChat/Data/... 被关键词 WeChat 命中后，聚合 key 是 .../com.tencent.xinWeChat，无论文件本身嵌得多深。

何时使用

用户用模糊或跨语言词描述容器（「在我微信里」、「在 Notion 笔记里」、「在我的工作备份里」），且你不知道真实路径
在调用 search 之前先确定 path_glob 的值

何时不使用

单纯按内容/主题搜索（「找简历」、「找 AI 论文」）—— 直接调 search，其混合检索本身已覆盖标题、文件名、内容、路径
仅按文件类型过滤（「所有 PDF」）—— 直接调 search 加 path_glob="*.pdf"
没有容器意图的笼统查询（「找最近的东西」）—— 直接调 search

使用示例

# 用户："找我微信里的购物订单"
# 第 1 步：定位真实路径
linkly find-paths --patterns WeChat,微信,wxid --limit 5
# 假设返回 .../com.tencent.xinWeChat/Data/Documents/xwechat_files (940 文件)

# 第 2 步：在该容器下按内容搜索
linkly search "购物订单" --path-glob "*xinWeChat*"

列举（list）

列举某个容器里的条目，不做全文匹配——要按关键词或语义找内容请用 search。支持三种容器：folder（某个磁盘目录下的已索引文件）、library（某个知识库的文件）、notes（本地的卡片笔记）。工具边界：explore = 全局概览 → find_paths = 找到目录 → list = 列出已知容器里的文件 → outline / read = 读内容。列举是对整个子树的扁平递归扫描——不返回目录树；要下钻就沿着条目里的绝对路径走，或用 find_paths。

参数

参数	类型	必填	默认值	说明
`scope`	string	是	—	要列举的容器。`folder`：某个磁盘目录下的已索引文件（省略 `path` 则扫全部监控根目录）；`library`：某个知识库的文件（必须配 `library`）；`notes`：本地卡片笔记。未知取值会被拒绝。注意：`search.scope` 也有一个写作 `folder` 的取值，含义是「全部已索引内容」——两者概念不同，取值不通用
`library`	string	`scope="library"` 必填	—	要列举哪个库。本地：库名或 `local://<id>`（见 `list_libraries`）；云端：`cloud://<owner>/<slug>`（仅 `--remote`）
`path`	string	否	—	要列举的目录——是地址，不是模式：不支持通配符；只知道模糊名字时先调 `find_paths`，抄它返回的 `path` 字段（不是 `path_glob`——后者带转义，抄过来会静默匹配不到任何东西）。本地（`folder` / 本地 `library`）：绝对路径——磁盘上不存在、或在监控目录之外的路径会直接报错。若该知识库为笔记或剪藏配置了标签筛选，其 `Notes/`、`Clips/` 目录下的路径同样可用——只会列出被筛选命中的文档。云端库：相对目录前缀（即云端 `find_paths` 返回的形态），传绝对路径会被拒绝
`doc_types`	string[]	否	全部	按文档类型过滤（仅 `folder` / `library`）：`pdf`、`docx`、`pptx`、`epub`、`md`、`txt`、`html`、`image`、`audio`、`video`
`tags`	string[]	否	—	按标签过滤，AND 语义（仅 `notes`——其他 scope 会拒绝）。开头的 `#` 会被去掉，ASCII 转小写，规则同 `search.tags`
`modified_after`	string	否	—	文件修改时间的下界，含端点（仅 `folder` / `library`）。ISO 8601 UTC：裸日期 `2024-01-01` 或完整 RFC 3339
`modified_before`	string	否	—	修改时间的上界，含端点。格式同上
`sort`	string	否	`recent`	`recent`（最新优先——`notes` 锚定创建时间，`folder` / `library` 锚定修改时间，所以被截断的页面看到的是最新的那一片）/ `oldest`（同一锚点，最早优先）/ `name`（按文件名 A→Z）。每种排序都有确定的路径决胜规则，分页结果稳定
`snippet`	boolean	否	按 scope	`notes`：`true`（正文前约 200 字符）；`folder` / `library`：`false`（开启时摘录取自索引摘要，不读磁盘）。开启期间 `limit` 上限收紧为 50
`limit`	number	否	50	最大返回条数，上限 200；`snippet` 开启期间上限收紧为 50
`offset`	number	否	0	按排序顺序跳过前 N 条（分页用）；用 `has_more` 判断要不要取下一页
`output_format`	string	否	按 scope	`notes`：`json`（每条是 `note_save` 用的 CAS 凭证，塞不进紧凑的行式排版）；`folder` / `library`：`markdown`。两种都可以显式指定

返回字段

folder / library 条目带：doc_id、title、绝对 path、doc_type、word_count、total_lines、has_outline、modified_at（Unix 毫秒，即文件系统 mtime）、keywords、snippet（未开启摘录时为 null），以及 skip_reason——skip_reason 非空表示内容不可读，别再对它 read / grep。用 total_lines + has_outline 决定走 outline 还是 read。本地 scope 的 total 统计的是整个过滤后集合；云端库在总数未知时可能返回 total: null——无论哪种，都配合 offset + has_more 分页。 notes 条目带：doc_id（可交给 read / grep / outline）、note_id 与实时的 version（这两个是 note_save 编辑时的乐观锁凭证）、title、绝对路径、created_at / modified_at（Unix 毫秒）、tags、来源信息，以及默认附带的 snippet。响应还会带一个 available_tags——当前全部笔记标签中按使用频次排前 50 的，可以直接拿来做下一次的 tags 过滤。

README 指针：只有显式传了 path（scope 为 folder 或本地 library）、且 README 类文件直接位于该目录下（不在子目录里）时，响应才会带一个顶层 readme 指针。云端库不会返回它。它存在、且你需要弄清这个文件夹是干什么的时，先读它。

文件系统优先（notes）：刚写下的笔记会立刻出现在列表里，但此时 doc_id 是 null、indexed 是 false（字数、行数也还是空），要等索引跑完才补齐。所以「刚记的笔记列得出来但搜不到」是正常现象，不是丢了。title 也可能是 null——文件名是机器生成的那种笔记没有可用标题，这时靠摘录、标签和时间来辨认。

云端知识库

folder 只认本地磁盘路径。要列举云端库，用 scope="library" 配 library="cloud://<owner>/<slug>"（--remote 下可用），path 传相对目录前缀——正是云端 find_paths 返回的形态。前缀作用于该库全部来源的并集；「前缀不存在」和「目录为空」无法区分——在首页（offset=0）两者都返回 total: 0，传了 path 时还会附一条提示。云端列举和本地有几处不同：不支持 sort="name"；skip_reason 恒为 null；摘录截断在约 120 字符；首页之后 total 可能是 null——用 has_more 分页。

使用示例

# 全部监控根目录下最近的文件
linkly list --scope folder --limit 10

# 某个目录下今年改过的 PDF
linkly list --scope folder --path /Users/me/Papers --type pdf --modified-after 2026-01-01

# 某个知识库的文件
linkly list --scope library --library my-research

# 按标签过滤笔记（默认输出：带 CAS 凭证的 JSON）
linkly list --scope notes --tags project

保存笔记（note_save）

创建或编辑一条本地 Markdown 卡片笔记。这是唯一会写入的工具，只能写到笔记目录；YAML 元数据全部由服务端生成，调用方不用管。

参数

参数	类型	必填	说明
`mode`	string	是	`create` 或 `edit`
`content`	string	是	Markdown 正文，不含 YAML front matter。编辑时传的是修改后的全文
`note_id`	string	`edit` 必填	笔记 UUID，从 `list` 拿
`base_version`	string	`edit` 必填	读到的 `version`，用于乐观锁校验
`tags`	string[]	否	要追加的标签（服务端会把缺的 `#标签` 补进正文）。不能删标签——删除要从 `content` 里删掉对应的 `#标签`。需要 Desktop 0.11.0+；更旧的版本编辑时必填且按全量替换处理
`app_name`	string	否	承载这场对话的应用显示名（如 `ChatGPT`、`Cursor`），会显示为笔记的来源徽章。是应用名而非模型名——只知道模型名时就省略。通过云端网关的 OAuth 连接时，服务端会自动填上。最长 64 字符

两条必须知道的规则

正文格式是白名单，不是随便写

这条路径只接受界面工具栏能做到的那部分 Markdown：段落与换行、加粗、删除线、有序/无序列表、纯文本。标题、斜体、引用、代码、链接、表格、任务列表、图片和裸 HTML 会被拒绝，返回 NOTE_INVALID_INPUT。你自己在应用界面里手写不受这个限制。正文里（代码之外）的 #标签 就是笔记的标签——正文是标签的唯一事实来源，和你在应用编辑器里手写完全一致。删标签就删掉对应的 #标签；tags 参数只能追加。旧版本写的、标签只存在 YAML 里的笔记会自愈：AI 第一次编辑时会自动把缺的 #标签 补进正文。

编辑必须走乐观锁（CAS）循环

正确的编辑顺序是：

list（scope="notes"）拿到 note_id 和 version
用 read(doc_id) 读到当前完整正文
note_save 传 mode="edit"、note_id、base_version=<刚才那个 version>，以及修改后的完整正文——想保留的 #标签 留着，想删的删掉

如果 base_version 过期（期间笔记被改过），会返回 NOTE_VERSION_CONFLICT 并附上真实版本号——应当重读、合并、重试，不要盲目覆盖。每次成功响应都会回传笔记的有效 content（服务端可能补写了 #标签）和新的 version——后续编辑一律以返回的 content 为基础，不要用你自己发出去的那份。还没被索引的笔记 doc_id 是 null，编辑自己刚建的笔记靠的正是这份返回值。绝不要只凭摘录就重写整条笔记。

**没有删除工具。**删除笔记只能由用户在应用界面里操作。

响应元数据（Response Metadata）

每次成功的工具响应都会附带一个当前 UTC 时间字段，方便调用方推算「上个月」、「今年」、「过去 30 天」等相对日期，避免依赖模型训练截止时间瞎猜。

Markdown 输出：响应末尾追加一行分隔块，形如：
--- [meta] now=2026-05-08T14:43:14Z

JSON 输出：在响应顶层添加 _meta 对象：

{ ..., "_meta": { "now": "2026-05-08T14:43:14Z" } }

错误响应（isError: true）不附加这个元数据 —— 错误体本身已经传达了失败原因，再附加时间戳反而会稀释信号。当用户使用相对日期（「上个月」、「近三个月」）时，应当从最近一次工具响应中读取 now 字段，以此为基准换算出具体的 ISO 8601 日期，再传给 search 的 modified_after / modified_before。

调用示例

完整工作流：CLI 方式

以下示例演示如何通过 CLI 完成一次完整的文档检索：

# 第 1 步：搜索相关文档
linkly search "微服务架构设计" --limit 5

# 第 2 步：查看目标文档的大纲（假设 doc_id 为 abc123）
linkly outline abc123

# 第 3 步：阅读感兴趣的章节（假设目标在第 80-150 行）
linkly read abc123 --offset 80 --limit 70

完整工作流：MCP 方式

AI 助理通过 MCP 协议调用工具时，请求格式如下：

// 第 1 步：搜索
{
  "method": "tools/call",
  "params": {
    "name": "search",
    "arguments": {
      "query": "微服务架构设计",
      "limit": 5
    }
  }
}

// 第 2 步：查看大纲
{
  "method": "tools/call",
  "params": {
    "name": "outline",
    "arguments": {
      "doc_ids": ["abc123"]
    }
  }
}

// 第 3 步：阅读内容
{
  "method": "tools/call",
  "params": {
    "name": "read",
    "arguments": {
      "doc_id": "abc123",
      "offset": 80,
      "limit": 70
    }
  }
}

常见问题

支持哪些文档格式？

Linkly AI 目前支持以下格式：

格式	扩展名	大纲支持
Markdown	`.md`, `.mdx`	✅
Word	`.docx`	✅
PowerPoint	`.pptx`	✅
EPUB	`.epub`	✅
PDF	`.pdf`	部分支持
纯文本	`.txt`	❌
HTML	`.html`	部分支持
图片（OCR）	`.png`, `.jpg`, `.jpeg`, `.bmp`, `.webp`	❌
音频（转写）	`.mp3`, `.wav`, `.m4a`, `.flac`, `.aac`, `.ogg`	❌
视频（转写）	`.mp4`, `.mov`, `.mkv`, `.webm`	❌

音视频的语音转写默认是关闭的——这类文件仍会被登记进索引、能按文件名搜到，但要搜到「里面说了什么」，需要先去 设置 → 索引 打开「音频解析」和「视频解析」。详见索引设置。

大纲不可用怎么办？

如果文档没有可用的大纲（has_outline: false），你可以：

直接使用 read 工具分页浏览文档内容
先读取文档开头（默认 200 行），了解大致内容后再决定是否继续阅读

如何处理长文档？

推荐流程：

先通过 outline 了解文档结构（如果有大纲）
根据大纲中的行范围，使用 read 的 offset 和 limit 参数精确读取目标章节
每次最多读取 500 行，通过调整 offset 分页读取

MCP 服务的默认端口是多少？

默认端口为 60606。如果该端口被占用，应用会自动尝试其他端口。你可以在 Linkly AI Desktop 的设置中查看实际使用的端口。

搜索结果不准确怎么办？

你可以尝试：

使用更精确的关键词
使用自然语言描述（利用向量语义匹配）
混合使用关键词和同义词，如 "认证 auth 登录 sign-in"
使用 --type 过滤特定文档类型，缩小搜索范围

​工具概览

search

outline

grep

read

list_libraries

explore

find_paths

list

note_save

​检索（search）

​参数

​返回字段

​使用示例

​大纲（outline）

​参数

​何时使用大纲

​使用示例

​正则匹配（grep）

​参数

​何时使用 grep 而非 outline

​使用示例

​阅读（read）

​参数

​读取图文混排文档

​内容格式

​分页策略

​使用示例

​知识库列表（list_libraries）

​参数

​使用场景

​概览（explore）

​参数

​使用场景

​路径定位（find_paths）

​参数

​返回字段（JSON 模式）

​聚合行为

​何时使用

​何时不使用

​使用示例

​列举（list）

​参数

​返回字段

​云端知识库

​使用示例

​保存笔记（note_save）

​参数

​两条必须知道的规则

​响应元数据（Response Metadata）

​调用示例

​完整工作流：CLI 方式

​完整工作流：MCP 方式

​常见问题

工具概览

检索（search）

参数

返回字段

使用示例

大纲（outline）

参数

何时使用大纲

使用示例

正则匹配（grep）

参数

何时使用 grep 而非 outline

使用示例

阅读（read）

参数

读取图文混排文档

内容格式

分页策略

使用示例

知识库列表（list_libraries）

参数

使用场景

概览（explore）

参数

使用场景

路径定位（find_paths）

参数

返回字段（JSON 模式）

聚合行为

何时使用

何时不使用

使用示例

列举（list）

参数

返回字段

云端知识库

使用示例

保存笔记（note_save）

参数

两条必须知道的规则

响应元数据（Response Metadata）

调用示例

完整工作流：CLI 方式

完整工作流：MCP 方式

常见问题