跳转到主要内容

工具概览

Linkly AI 通过 MCP(Model Context Protocol)向 AI 助理暴露三个工具,构成一个渐进式的文档访问工作流:
search → outline → read
搜索      大纲      阅读

search

搜索文档,找到相关结果

outline

查看文档大纲,了解结构

read

阅读文档内容,获取详情
这三个工具配合使用,让 AI 助理能够高效地从你的本地文档中获取上下文信息。

检索(search)

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

参数

参数类型必填默认值说明
querystring搜索关键词或短语
limitnumber20最大返回结果数(1-50)
doc_typesstring[]全部按文档类型过滤,如 ["pdf", "md", "docx"]
output_formatstringmarkdown设为 json 可获得结构化 JSON 输出
如果向量模型尚在下载中,搜索会自动降级为纯关键词模式,不影响使用。

返回字段

每条搜索结果包含以下信息:
字段说明
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

大纲(outline)

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

参数

参数类型必填默认值说明
doc_idsstring[]文档 ID 列表(来自搜索结果)
expandstring[]自动要展开的节点 ID(如 ["2", "3.1"]),省略则自动展示所有层级
output_formatstringmarkdown设为 json 可获得结构化 JSON 输出

何时使用大纲

场景建议
长文档(> 200 行)且有大纲先查看大纲,再读取目标章节
短文档(< 100 行)跳过大纲,直接 read 全文
has_outline: false 的文档跳过大纲,直接 read 逐页浏览
大纲功能对有书签的 PDFMarkdownDOCX 文档效果最好,在阅读大部头的文档、书籍的时候会获得事半功倍的效果。 纯文本和无书签的 PDF 将在后续迭代中提供大纲支持。

使用示例

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

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

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

阅读(read)

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

参数

参数类型必填默认值说明
doc_idstring文档 ID(来自搜索结果)
offsetnumber1起始行号(从 1 开始)
limitnumber200读取行数(最多 500)
output_formatstringmarkdown设为 json 可获得结构化 JSON 输出

内容格式

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

调用示例

完整工作流: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
PDF.pdf部分支持
纯文本.txt
HTML.html, .htm部分支持
如果文档没有可用的大纲(has_outline: false),你可以:
  1. 直接使用 read 工具分页浏览文档内容
  2. 先读取文档开头(默认 200 行),了解大致内容后再决定是否继续阅读
推荐流程:
  1. 先通过 outline 了解文档结构(如果有大纲)
  2. 根据大纲中的行范围,使用 readoffsetlimit 参数精确读取目标章节
  3. 每次最多读取 500 行,通过调整 offset 分页读取
默认端口为 60606。如果该端口被占用,应用会自动尝试其他端口。你可以在 Linkly AI Desktop 的设置中查看实际使用的端口。
你可以尝试:
  • 使用更精确的关键词
  • 使用自然语言描述(利用向量语义匹配)
  • 混合使用关键词和同义词,如 "认证 auth 登录 sign-in"
  • 使用 --type 过滤特定文档类型,缩小搜索范围