fix(mcp): clarify read_document query and pagination semantics (#4403)

main
Jarvis 2026-10-17 22:48:21 +08:00 committed by GitHub
parent 340b72f141
commit 8ddb245d1b
No known key found for this signature in database
GPG Key ID: B5690EEEBB952194
2 changed files with 13 additions and 6 deletions

View File

@ -87,13 +87,18 @@ func listDocumentsTool() mcp.Tool {
func readDocumentTool() mcp.Tool {
return mcp.NewTool(types.MCPEndpointToolReadDocument,
mcp.WithDescription("Read a document's metadata and its text chunks in order. Page through long documents "+
"with offset and limit, or pass query to return only the chunks containing a phrase (with one chunk "+
"of context on each side)."),
"with offset and limit, or pass query to find chunks containing every whitespace-separated word, "+
"case-insensitively and in any order. Query mode returns at most 20 matches plus one chunk of "+
"context on each side, subject to the output size budget; limit does not apply. If truncated, "+
"continue with offset=next_offset from the response."),
mcp.WithString("knowledge_id", mcp.Required(),
mcp.Description("Document id from search results or list_documents")),
mcp.WithNumber("offset", mcp.Description("Chunk offset to start from, default 0")),
mcp.WithNumber("limit", mcp.Description("Number of chunks to return, default 20, max 100")),
mcp.WithString("query", mcp.Description("Optional case-insensitive phrase to find inside the document")),
mcp.WithNumber("offset", mcp.Description("0-based position in document reading order, default 0; "+
"use returned next_offset to continue")),
mcp.WithNumber("limit", mcp.Description("Chunks per page without query, default 20, max 100; "+
"ignored in query mode; output size budget may reduce the page")),
mcp.WithString("query", mcp.Description("Optional case-insensitive keywords split on whitespace; "+
"every word must occur in the chunk, in any order (not an exact phrase)")),
readOnlyEndpointAnnotations(),
)
}

View File

@ -48,7 +48,7 @@ MCP 管理页支持按服务名称和卡片显示的用途说明搜索。搜索
| 组 | 工具 | 说明 |
|---|---|---|
| 检索与阅读 | `list_knowledge_bases`、`search_knowledge`、`grep_chunks`、`list_documents`、`read_document` | 知识库参数同时接受 ID 或名称;`search_knowledge` 用 `mode`(hybrid / semantic / keyword)选择检索方式并可设 `limit`(默认 10,上限 30);`grep_chunks` 保持大小写不敏感的正则语义:从模式里提取字面词作为关键词索引的检索词(没有关键词索引的库改用语义索引取候选),再逐条用正则校验,返回的分块都匹配该模式;不含任何字面词的模式(如 `^\d+$`)会被拒绝;`read_document` 按 `offset` / `limit` 翻页,或用 `query` 在文档内查找短语 |
| 检索与阅读 | `list_knowledge_bases`、`search_knowledge`、`grep_chunks`、`list_documents`、`read_document` | 知识库参数同时接受 ID 或名称;`search_knowledge` 用 `mode`(hybrid / semantic / keyword)选择检索方式并可设 `limit`(默认 10,上限 30);`grep_chunks` 保持大小写不敏感的正则语义:从模式里提取字面词作为关键词索引的检索词(没有关键词索引的库改用语义索引取候选),再逐条用正则校验,返回的分块都匹配该模式;不含任何字面词的模式(如 `^\d+$`)会被拒绝;`read_document` 无 `query` 时按 `offset` / `limit` 翻页;传入 `query` 时按空白分词,不区分大小写,同一分块必须包含所有词,顺序不限 |
| 问答 | `ask` | 只运行端点配置的默认 Agent(客户端不能自选 Agent;未配置时使用内置快速问答),服务端自动建会话,返回带引用的完整回答和 `session_id`,续聊时传回即可;不开启联网搜索 |
| Wiki | `wiki_search`、`wiki_read_page`、`wiki_index` | 只对开启了 Wiki 的知识库生效;`wiki_search` 的 `query` 保持原有的正则语义(大小写不敏感),不是合法正则的文本按字面匹配;`regex=false` 强制字面匹配,`regex=true` 要求合法正则 |
| 写入 | `add_document`、`update_document`、`delete_document` | 默认关闭;支持 Markdown 文本或 URL 导入 |
@ -59,6 +59,8 @@ MCP 管理页支持按服务名称和卡片显示的用途说明搜索。搜索
生成链接前会重新检查端点知识库范围、共享权限、资源所属空间和有效文档绑定,沿用知识库图片预览的权限规则;未限定知识库的端点按调用者可查看的知识库判断,因此 `ask` 通过智能体检索到的共享知识库图片同样可以转换;原始上传文件不会因为出现在结果文本中就获得下载链接。已有绑定的历史存储路径可以转换。对于缺少图片绑定的历史文档,需要由有权限的管理员重新解析文档,完成后重新检索;不能仅凭可编辑的正文或 `image_info` 自动补授文件权限。
`read_document` 的 `offset` 是文档阅读顺序中从 0 开始的位置,不是 chunk index。无 `query` 时,`limit` 默认 20、最多 100,输出预算可能减少每页片段数。`query` 模式不使用 `limit`,每次最多返回 20 个匹配,并附加每个匹配前后各一个分块作为上下文,重叠上下文会去重,且受输出预算限制。返回 `truncated=true` 时,用响应中的 `next_offset` 作为下一次的 `offset`,并保留原 `query` 继续读取。
> **`grep_chunks` 的召回有上限。** 它基于索引取候选,每次最多 30 条,再用正则筛选,所以返回的每条都匹配模式,但不保证穷尽:库里存在的匹配也可能没进候选池。容易漏的情况有三类:`foo.*bar` 这类组合模式,候选按 foo、bar 的相关度排序,真正相邻出现的分块可能排不进前 30;`C++` 这类几乎只剩符号的模式,抽出的字面词只有 `C`,在索引里几乎没有区分度;没有关键词索引的库改用语义索引取候选,字面匹配更依赖运气。旧实现对 chunks 表做全表正则扫描,能保证"有就能找到",但数据量大时代价过高,已经移除。需要在某篇文档里穷尽查找时,用 `read_document` 的 `query`,它会顺序扫完整篇文档。
工具实现直接复用 Agent 的原生工具(`internal/agent/tools/`),鉴权复用 API Key 的作用域模型:端点被换算成一把仅含 retrieve / chat / ingest 等能力、限定知识库范围的作用域,所以后端各服务对它的检查与对受限 API Key 完全一致。实现细节见下方内置 MCP Server 参考。