工具概览
Linkly AI 通过 MCP(Model Context Protocol)向 AI 助理暴露四个工具,构成一个渐进式的文档访问工作流:search
搜索文档,找到相关结果
outline
查看文档大纲,了解结构
grep
正则匹配,精确定位文本模式
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 输出 |
何时使用大纲
| 场景 | 建议 |
|---|---|
| 文档 > 50 行且有大纲 | 先查看大纲,再读取目标章节 |
| 短文档(< 50 行) | 跳过大纲,直接 read 全文 |
has_outline: false 的文档 | 使用 grep 定位模式或 read 逐页浏览 |
大纲功能对有书签的 PDF、 Markdown 和 DOCX
文档效果最好,在阅读大部头的文档、书籍的时候会获得事半功倍的效果。
纯文本和无书签的 PDF 将在后续迭代中提供大纲支持。
使用示例
正则匹配(grep)
在单个文档内通过正则表达式定位具体行。最适合has_outline=false 的文档(无法使用 outline 浏览结构时)。在 search 之后使用,用于精确定位特定文本(人名、日期、术语、标识符等),然后用 read 跳转到匹配位置深入阅读。适用于所有文档类型(PDF、Markdown、DOCX、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 正则 |
使用示例
阅读(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过滤特定文档类型,缩小搜索范围

