工具概览
Linkly AI 通过 MCP(Model Context Protocol)向 AI 助理暴露三个工具,构成一个渐进式的文档访问工作流:search
搜索文档,找到相关结果
outline
查看文档大纲,了解结构
read
阅读文档内容,获取详情
检索(search)
搜索已索引的本地文档,返回最相关的结果列表。参数
| 参数 | 类型 | 必填 | 默认值 | 说明 |
|---|---|---|---|---|
query | string | 是 | — | 搜索关键词或短语 |
limit | number | 否 | 20 | 最大返回结果数(1-50) |
doc_types | string[] | 否 | 全部 | 按文档类型过滤,如 ["pdf", "md", "docx"] |
output_format | string | 否 | markdown | 设为 json 可获得结构化 JSON 输出 |
返回字段
每条搜索结果包含以下信息:| 字段 | 说明 |
|---|---|
doc_id | 文档唯一标识,用于后续 outline/read 调用 |
title | 文档标题 |
path | 文件路径 |
relevance | 相关度分数(0-1) |
word_count | 文档字数 |
total_lines | 文档总行数 |
has_outline | 是否有可用大纲 |
modified_at | 最后修改时间 |
keywords | 提取的关键词列表 |
snippet | 匹配的内容摘要片段 |
使用示例
大纲(outline)
获取一个或多个文档的结构化大纲和元数据,帮助快速了解文档结构并定位目标章节。参数
| 参数 | 类型 | 必填 | 默认值 | 说明 |
|---|---|---|---|---|
doc_ids | string[] | 是 | — | 文档 ID 列表(来自搜索结果) |
expand | string[] | 否 | 自动 | 要展开的节点 ID(如 ["2", "3.1"]),省略则自动展示所有层级 |
output_format | string | 否 | markdown | 设为 json 可获得结构化 JSON 输出 |
何时使用大纲
| 场景 | 建议 |
|---|---|
| 长文档(> 200 行)且有大纲 | 先查看大纲,再读取目标章节 |
| 短文档(< 100 行) | 跳过大纲,直接 read 全文 |
has_outline: false 的文档 | 跳过大纲,直接 read 逐页浏览 |
大纲功能对有书签的 PDF、 Markdown 和 DOCX
文档效果最好,在阅读大部头的文档、书籍的时候会获得事半功倍的效果。
纯文本和无书签的 PDF 将在后续迭代中提供大纲支持。
使用示例
阅读(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 工具将返回带有行号的内容,方便引用和定位:
分页策略
对于长文档,建议分块读取:read 精确读取该区间的内容。
使用示例
调用示例
完整工作流:CLI 方式
以下示例演示如何通过 CLI 完成一次完整的文档检索:完整工作流:MCP 方式
AI 助理通过 MCP 协议调用工具时,请求格式如下:常见问题
支持哪些文档格式?
支持哪些文档格式?
Linkly AI 目前支持以下格式:
| 格式 | 扩展名 | 大纲支持 |
|---|---|---|
| Markdown | .md, .mdx | ✅ |
| Word | .docx | ✅ |
.pdf | 部分支持 | |
| 纯文本 | .txt | ❌ |
| HTML | .html, .htm | 部分支持 |
大纲不可用怎么办?
大纲不可用怎么办?
如果文档没有可用的大纲(
has_outline: false),你可以:- 直接使用
read工具分页浏览文档内容 - 先读取文档开头(默认 200 行),了解大致内容后再决定是否继续阅读
如何处理长文档?
如何处理长文档?
推荐流程:
- 先通过
outline了解文档结构(如果有大纲) - 根据大纲中的行范围,使用
read的offset和limit参数精确读取目标章节 - 每次最多读取 500 行,通过调整
offset分页读取
MCP 服务的默认端口是多少?
MCP 服务的默认端口是多少?
默认端口为 60606。如果该端口被占用,应用会自动尝试其他端口。你可以在 Linkly AI Desktop 的设置中查看实际使用的端口。
搜索结果不准确怎么办?
搜索结果不准确怎么办?
你可以尝试:
- 使用更精确的关键词
- 使用自然语言描述(利用向量语义匹配)
- 混合使用关键词和同义词,如
"认证 auth 登录 sign-in" - 使用
--type过滤特定文档类型,缩小搜索范围

