Linkly AI MCP 工具介绍

工具概览

Linkly AI 通过 MCP（Model Context Protocol）向 AI 助理暴露九个工具；云端网关（mcp.linkly.ai，以及 linkly mcp --remote）另外多出两个仅云端的工具——library_search 与 library_link——在那里共十一个。核心是一条渐进式的文档访问工作流：

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

创建或编辑笔记，会写入（本地连接上唯一的写入工具）

library_search

搜索云端知识库目录，包括你还没连接的库——仅云端网关

library_link

连接一个云端知识库让它可检索，或断开你点名的库（action: "unlink"）——仅云端网关，会写入

library_search 与 library_link 只存在于云端网关。library_link 是那里会写入的工具：把云端库加入你账号的已连接集合，或用 action: "unlink" 移除你点名的那一个。下面其余工具全部只读。

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

检索（search）

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

参数

参数	类型	必填	默认值	说明
`query`	string	是	—	搜索关键词或短语
`limit`	number	否	20	最大返回结果数（1-50）
`doc_types`	string[]	否	全部	按文档类型过滤。可用取值：`pdf`、`docx`、`doc`、`pptx`、`xlsx`、`csv`、`epub`、`rtf`、`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`	文档词数（中日韩文字每字计一词）
`char_count`	当前可用提取正文的字符数，含空格、标点和 Markdown 标记（不计 `\r`）
`total_lines`	文档总行数
`has_outline`	是否有可用大纲
`modified_at`	最后修改时间
`keywords`	提取的关键词列表
`snippet`	匹配的内容摘要片段

word_count 不是字符数，它和 char_count 差多少取决于内容（标点、空格、Markdown 的占比）。char_count 统计的是当前已提取出的正文：OCR 或转写尚未完成、或提取被截断时，它只代表部分内容。各编辑器对换行、组合字符、emoji 的计法不一，和编辑器字数比较前，先确认比的是同一份文本、同一种口径，再判断是否缺了内容。char_count 需要 Linkly AI Desktop v0.14.1 及以上：旧版本索引过的文档在重新提取或重建索引之前返回 null（read 总会现算），云端库的文档暂不返回该字段。

使用示例

# 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、DOC、PowerPoint (PPTX)、XLSX、CSV、EPUB 和 RTF 文档效果最好，在阅读大部头的文档、书籍的时候会获得事半功倍的效果。表格类文件的大纲列的是表而不是标题：XLSX 每张工作表一个条目（带行列数、表头和几行预览），CSV 是一个整表摘要条目。纯文本和无书签的 PDF 将在后续迭代中提供大纲支持。

使用示例

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

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

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

正则匹配（grep）

在单个文档内通过正则表达式定位具体行。最适合 has_outline=false 的文档（无法使用 outline 浏览结构时）。在 search 之后使用，用于精确定位特定文本（人名、日期、术语、标识符等），然后用 read 跳转到匹配位置深入阅读。适用于所有文档类型（PDF、Markdown、DOCX、DOC、PPTX、XLSX、CSV、EPUB、RTF、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

搜索知识库（library_search）

仅云端网关——linkly-ai-cloud MCP server 与 linkly mcp --remote 提供；本地与局域网连接没有这个工具。

按标题、描述或库主用户名搜索云端知识库目录，包括你还没连接的库。它找的是知识库；要搜文档用 search；要看当前已可检索的库用 list_libraries。

参数

参数	类型	必填	默认值	说明
`query`	string	否	—	关键词，按标题、描述、库主用户名做不区分大小写的子串匹配。省略则浏览整个目录
`category`	string	否	全部	`ai-ml`、`programming`、`design`、`science`、`business`、`lifestyle`、`education`、`other` 之一
`owner`	string	否	全部	库主用户名（精确匹配）。响应首行会写「You are signed in as @…」，把这个名字传进来即可列出你自己的库，含私有库
`limit`	number	否	10	每页最多条数（1–50）
`offset`	number	否	0	分页偏移；`has_more` 为 true 时继续翻页
`output_format`	string	否	`markdown`	`markdown` 或 `json`

响应

每条结果带可直接传给其他工具的 cloud://<owner>/<slug>，以及标题、描述、库主、分类、可见性、文档 / Star / 连接数、is_owner、is_linked（已可检索，不必再连接）和 can_link（对未受邀的 Showcase 库为 cannot_link_reason: invite_required）。Public 与 Showcase 库总会列出；Private 库只对库主和已受邀的读者可见。结果按最近更新时间倒序。此工具不会连接、收藏或修改任何东西。

使用场景

「找一个 Rust 相关的知识库并用它」→ library_search(query="Rust") → 选一条 → library_link → search(query=…, library="cloud://…")
「我自己有哪些云端库？」→ library_search(owner="<你的用户名>")

连接知识库（library_link）

仅云端网关；两个会写入的工具之一（另一个是 note_save）。同一个工具用 action: "unlink" 断开，见下。

把一个云端知识库连接到你的账号，让它可以通过 MCP 检索：它会立即出现在 list_libraries 里，search / explore / list 也立即接受它的 cloud://<owner>/<slug>。规则与网站上的「连接」按钮完全一致。

参数

参数	类型	必填	说明
`library`	string	是	完整的 `cloud://<owner>/<slug>` 标识，与 `library_search` 返回的一字不差
`action`	string	否	`"link"`（默认）或 `"unlink"`；不传或传 null 即连接

规则

Public 库：任何已登录用户都能连接。Showcase 与 Private 库：只有库主和已受邀的读者能连（工具会返回 invite_required；对你看不到的私有库返回「not found」）。
重复连接同一个库无副作用——返回 already_linked，不多占 Slot。
每次连接占一个 Slot（Free 1 个，Pro 99 个）。配额满时工具返回 slot_exhausted，附当前数量、上限和升级链接。AI 助理不会自作主张挑一个库断开：它会列出你已连接的库、问你释放哪一个，再用 action: "unlink" 调 library_link，然后重新连接。你也可以到网站上腾位置。

断开（`action: "unlink"`）

把一个云端知识库从你账号的已连接集合里移除：它从 list_libraries 里消失，通过 MCP 不再可检索（你账号的所有客户端都一样），占的 Slot 随之释放。其他都不变——你的 reader 身份、邀请和 star 都保留，之后可以再连回来。library 参数同上，与 list_libraries 列出的一致。

AI 助理只会断开你点名的库——典型场景是 Slot 满时你说「把 A 换成 B」。你没点名时，它会列出已连接的库来问你，绝不自己挑。
断开一个本来就没连接的库无副作用——返回 already_unlinked。not_found 表示你的账号看不到这个库。
响应里会写明还占着多少 Slot，助理可以紧接着连上你真正想要的那个库。

概览（explore）

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

参数

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

使用场景

用户想了解知识库或文档集合中大概有什么内容
用户没有明确的搜索主题，想先发现可用的主题和方向
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`、`doc`、`pptx`、`xlsx`、`csv`、`epub`、`rtf`、`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、char_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 卡片笔记。这与 library_link（仅云端网关）是仅有的两个会写入的工具，且它只能写到笔记目录；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`	✅
Word 97-2003	`.doc`	✅
RTF	`.rtf`	✅
PowerPoint	`.pptx`	✅
EPUB	`.epub`	✅
Excel	`.xlsx`	✅
CSV	`.csv`	✅
PDF	`.pdf`	部分支持
纯文本	`.txt`	❌
HTML	`.html`	部分支持
图片（OCR）	`.png`, `.jpg`, `.jpeg`, `.bmp`, `.webp`	❌
音频（转写）	`.mp3`, `.wav`, `.m4a`, `.flac`, `.aac`, `.ogg`	❌
视频（转写）	`.mp4`, `.mov`, `.mkv`, `.webm`	❌

Excel 和 CSV 会被解析成 GitHub 风格的 Markdown 表格，并按单元格文本建立索引——所以 search 和 grep 能命中单元格里的字。大纲形态因格式而异：.xlsx 每张工作表一个条目（带行列数、表头和几行预览），.csv 则是一个整表摘要条目。只支持 .xlsx 和 .csv，旧版 .xls 以及 .xlsm、.xlsb、.ods 都不支持。非 UTF-8 编码的 CSV，只有能从文件自身或同目录的相邻文件判定出编码时才会解码；判定不出来的会直接跳过，而不是索引成乱码。两种格式的单文件上限都是 16 MiB。音视频的语音转写默认是关闭的——这类文件仍会被登记进索引、能按文件名搜到，但要搜到「里面说了什么」，需要先在主窗口「索引管理」页「管理」区的「解析增强」里打开「音频转写」和「视频转写」。详见索引设置。

大纲不可用怎么办？

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

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

如何处理长文档？

推荐流程：

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

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

默认端口为 60606。如果该端口被占用，应用会自动尝试其他端口。你可以在 Linkly AI Desktop 主窗口的「Agent 使用」页点「查看 MCP 接入配置」，查看实际使用的地址和端口。

搜索结果不准确怎么办？

你可以尝试：

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

​工具概览

search

outline

grep

read

list_libraries

explore

find_paths

list

note_save

library_search

library_link

​检索（search）

​参数

​返回字段

​使用示例

​大纲（outline）

​参数

​何时使用大纲

​使用示例

​正则匹配（grep）

​参数

​何时使用 grep 而非 outline

​使用示例

​阅读（read）

​参数

​读取图文混排文档

​内容格式

​分页策略

​使用示例

​知识库列表（list_libraries）

​参数

​使用场景

​搜索知识库（library_search）

​参数

​响应

​使用场景

​连接知识库（library_link）

​参数

​规则

​断开（action: "unlink"）

​概览（explore）

​参数

​使用场景

​路径定位（find_paths）

​参数

​返回字段（JSON 模式）

​聚合行为

​何时使用

​何时不使用

​使用示例

​列举（list）

​参数

​返回字段

​云端知识库

​使用示例

​保存笔记（note_save）

​参数

​两条必须知道的规则

​响应元数据（Response Metadata）

​调用示例

​完整工作流：CLI 方式

​完整工作流：MCP 方式

​常见问题

工具概览

检索（search）

参数

返回字段

使用示例

大纲（outline）

参数

何时使用大纲

使用示例

正则匹配（grep）

参数

何时使用 grep 而非 outline

使用示例

阅读（read）

参数

读取图文混排文档

内容格式

分页策略

使用示例

知识库列表（list_libraries）

参数

使用场景

搜索知识库（library_search）

参数

响应

使用场景

连接知识库（library_link）

参数

规则

断开（`action: "unlink"`）

概览（explore）

参数

使用场景

路径定位（find_paths）

参数

返回字段（JSON 模式）

聚合行为

何时使用

何时不使用

使用示例

列举（list）

参数

返回字段

云端知识库

使用示例

保存笔记（note_save）

参数

两条必须知道的规则

响应元数据（Response Metadata）

调用示例

完整工作流：CLI 方式

完整工作流：MCP 方式

常见问题