> ## 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. # Linkly AI MCP 工具介绍 > 介绍 Linkly AI 给 AI 助理使用的工具 ## 工具概览 Linkly AI 通过 MCP（Model Context Protocol）向 AI 助理暴露七个工具，构成一个渐进式的文档访问工作流： ``` search → grep 或 outline → read 搜索 正则匹配/大纲 阅读 ``` 另有三个辅助工具：`list_libraries`（列出知识库）、`explore`（概览文档集合）和 `find_paths`（按关键词定位文件夹路径，配合 `search` 的 `path_glob` 使用）。 搜索文档，找到相关结果 查看文档大纲，了解结构 正则匹配，精确定位文本模式 阅读文档内容，获取详情 列出知识库及其文档数量 概览文档集合的主题和结构 按关键词定位文件夹路径，给 `search` 的 `path_glob` 提供候选 这七个工具配合使用，让 AI 助理能够高效地从你的本地文档中获取上下文信息。 ## 检索（search） 搜索已索引的本地文档，返回最相关的结果列表。 ### 参数 | 参数 | 类型 | 必填 | 默认值 | 说明 | | ----------------- | --------- | -- | ---------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- | | `query` | string | 是 | — | 搜索关键词或短语 | | `limit` | number | 否 | 20 | 最大返回结果数（1-50） | | `doc_types` | string\[] | 否 | 全部 | 按文档类型过滤，如 `["pdf", "md", "docx", "pptx", "epub"]` | | `library` | string | 否 | — | 限定在某个知识库内。本地库用名称或 `local://`；云端库用 `cloud:///`（仅 `--remote`）。使用 `list_libraries` 查看可用知识库 | | `path_glob` | string | 否 | — | 按文件路径过滤，对路径做**子串匹配**——模式可出现在路径任意位置，无需在两端加 `*`。`*` 匹配任意字符（含 `/`），`?` 匹配单个字符，区分大小写。传入完整目录路径（如 `/Users/me/notes/`）即可限定在该目录内。当真实路径未知时，先调 `find_paths` 获取 | | `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 时间，再做日期推算（详见下方[响应元数据](#响应元数据response-metadata)）。 ### 返回字段 每条搜索结果包含以下信息： | 字段 | 说明 | | ------------- | --------------------------- | | `doc_id` | 文档唯一标识，用于后续 outline/read 调用 | | `title` | 文档标题 | | `path` | 文件路径 | | `relevance` | 相关度分数（0-1） | | `word_count` | 文档字数 | | `total_lines` | 文档总行数 | | `has_outline` | 是否有可用大纲 | | `modified_at` | 最后修改时间 | | `keywords` | 提取的关键词列表 | | `snippet` | 匹配的内容摘要片段 | ### 使用示例 ```bash theme={null} # 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 将在后续迭代中提供大纲支持。 ### 使用示例 ```bash theme={null} # 查看单个文档大纲 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 条匹配（分页用） | | `output_format` | string | 否 | `markdown` | 设为 `json` 可获得结构化 JSON 输出 | ### 何时使用 grep 而非 outline | 场景 | 建议 | | --------------- | ------------ | | 需要查找特定术语、人名或日期 | 使用 `grep` | | 需要了解文档整体结构 | 使用 `outline` | | 文档没有大纲 | 使用 `grep` 定位 | | 查找模式（邮箱、编号、数字等） | 使用 `grep` 正则 | ### 使用示例 ```bash theme={null} # 在文档中查找特定术语 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） | | `output_format` | string | 否 | `markdown` | 设为 `json` 可获得结构化 JSON 输出 | ### 内容格式 `Read` 工具将返回带有行号的内容，方便引用和定位： ``` 1 # 项目需求文档 2 3 ## 一、项目背景 4 5 本项目旨在构建一个高效的知识管理系统... 6 目标用户为企业研发团队和个人知识工作者。 ``` ### 分页策略 对于长文档，建议分块读取： ```bash theme={null} # 第一页：第 1-200 行 linkly read --offset 1 --limit 200 # 第二页：第 201-400 行 linkly read --offset 201 --limit 200 # 第三页：第 401-600 行 linkly read --offset 401 --limit 200 ``` 结合大纲使用效果更佳 — 通过大纲定位到目标章节的行范围，然后用 `read` 精确读取该区间的内容。 ### 使用示例 ```bash theme={null} # 读取文档开头 linkly read abc123 # 读取特定范围 linkly read abc123 --offset 120 --limit 80 # JSON 格式（适合程序处理） linkly read abc123 --json ``` ## 知识库列表（list\_libraries） 列出用户配置的所有知识库及其描述和文档数量。 ### 参数 无需参数。 ### 使用场景 * 用户询问"我有哪些知识库"时调用 * 在使用 `search` 的 `library` 参数前，确认知识库名称 ```bash theme={null} linkly list-libraries ``` ## 概览（explore） 获取全部已索引文档或特定知识库的鸟瞰概览。返回文档类型分布、目录结构（含文件数和中位字数）以及高频关键词（标注集中来源）。 ### 参数 | 参数 | 类型 | 必填 | 默认值 | 说明 | | --------- | ------ | -- | --- | ------------------------------------------------------------------------------------------- | | `library` | string | 否 | — | 限定在某个知识库内。本地库用名称或 `local://`；云端库用 `cloud:///`（仅 `--remote`）。省略则概览全部本地已索引文档 | ### 使用场景 * 用户想了解知识库或文档集合中大概有什么内容 * 用户没有明确的搜索主题，想先发现可用的主题和方向 * AI 助理需要了解文档集合的规模和主题分布，以便制定有效的搜索策略 概览返回后，可利用其中的关键词和目录名称作为后续 `search` 查询的线索。 ```bash theme={null} # 概览全部文档 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://`；云端库用 `cloud:///`（仅 `--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` ### 使用示例 ```bash theme={null} # 用户："找我微信里的购物订单" # 第 1 步：定位真实路径 linkly find-paths --patterns WeChat,微信,wxid --limit 5 # 假设返回 .../com.tencent.xinWeChat/Data/Documents/xwechat_files (940 文件) # 第 2 步：在该容器下按内容搜索 linkly search "购物订单" --path-glob "*xinWeChat*" ``` ## 响应元数据（Response Metadata） 每次成功的工具响应都会附带一个当前 UTC 时间字段，方便调用方推算"上个月"、"今年"、"过去 30 天"等相对日期，避免依赖模型训练截止时间瞎猜。 * **Markdown 输出**：响应末尾追加一行分隔块，形如： ``` --- [meta] now=2026-05-08T14:43:14Z ``` * **JSON 输出**：在响应顶层添加 `_meta` 对象： ```json theme={null} { ..., "_meta": { "now": "2026-05-08T14:43:14Z" } } ``` 错误响应（`isError: true`）**不**附加这个元数据 —— 错误体本身已经传达了失败原因，再附加时间戳反而会稀释信号。 当用户使用相对日期（"上个月"、"近三个月"）时，应当从最近一次工具响应中读取 `now` 字段，以此为基准换算出具体的 ISO 8601 日期，再传给 `search` 的 `modified_after` / `modified_before`。 ## 调用示例 ### 完整工作流：CLI 方式 以下示例演示如何通过 CLI 完成一次完整的文档检索： ```bash theme={null} # 第 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 协议调用工具时，请求格式如下： ```json theme={null} // 第 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` | ✅ | | EPUB | `.epub` | ✅ | | PDF | `.pdf` | 部分支持 | | 纯文本 | `.txt` | ❌ | | HTML | `.html`, `.htm` | 部分支持 | | 图片 (OCR) | `.png`, `.jpg`, `.jpeg`, `.bmp`, `.webp` | ❌ | 如果文档没有可用的大纲（`has_outline: false`），你可以： 1. 直接使用 `read` 工具分页浏览文档内容 2. 先读取文档开头（默认 200 行），了解大致内容后再决定是否继续阅读 推荐流程： 1. 先通过 `outline` 了解文档结构（如果有大纲） 2. 根据大纲中的行范围，使用 `read` 的 `offset` 和 `limit` 参数精确读取目标章节 3. 每次最多读取 500 行，通过调整 `offset` 分页读取 默认端口为 **60606**。如果该端口被占用，应用会自动尝试其他端口。你可以在 Linkly AI Desktop 的设置中查看实际使用的端口。 你可以尝试： * 使用更精确的关键词 * 使用自然语言描述（利用向量语义匹配） * 混合使用关键词和同义词，如 `"认证 auth 登录 sign-in"` * 使用 `--type` 过滤特定文档类型，缩小搜索范围