Open-source LLM knowledge platform: turn raw documents into a queryable RAG, an autonomous reasoning agent, and a self-maintaining Wiki.
Go agentagenticaichatbotdsh-pluginembeddingsevaluationgenerative-aigolangknowledge-basellmmulti-tenantollamaopenaiquestion-answeringragrerankingsemantic-searchvector-searchwiki
feat(mcp): support document-scoped knowledge search (#4463)
Jarvis7438142cf808
diff --git a/internal/mcpserver/scope.go b/internal/mcpserver/scope.goindex 1c7b7f7b1..d48aa7c4f 100644--- a/internal/mcpserver/scope.go+++ b/internal/mcpserver/scope.go@@ -172,6 +172,51 @@ func searchTargetsFor(kbs []*types.KnowledgeBase) types.SearchTargets {return targets}+// maxSearchKnowledgeDocuments bounds validation lookups and backend filter size.+const maxSearchKnowledgeDocuments = 100++// documentSearchTargets narrows an already authorized KB selection to explicit+// documents. Never leave whole-KB targets for bases with no selected documents.+func (s *Server) documentSearchTargets(+ ctx context.Context, kbs []*types.KnowledgeBase, knowledgeIDs []string,+) (types.SearchTargets, error) {+ if len(knowledgeIDs) == 0 {+ return nil, fmt.Errorf("knowledge_ids must contain at least one document id; " ++ "omit it to search whole knowledge bases")+ }+ if len(knowledgeIDs) > maxSearchKnowledgeDocuments {+ return nil, fmt.Errorf("knowledge_ids must contain at most %d document ids", maxSearchKnowledgeDocuments)+ }+ targets := make(types.SearchTargets, 0)+ byKB := make(map[string]*types.SearchTarget)+ seen := make(map[string]bool, len(knowledgeIDs))+ for _, id := range knowledgeIDs {+ id = strings.TrimSpace(id)+ if id == "" {+ return nil, fmt.Errorf("knowledge_ids must not contain blank document ids")+ }+ if seen[id] {+ continue+ }+ k, kb, err := s.knowledgeInKnowledgeBases(ctx, kbs, id)+ if err != nil {+ return nil, err+ }+ target := byKB[kb.ID]+ if target == nil {+ target = &types.SearchTarget{+ Type: types.SearchTargetTypeKnowledge, KnowledgeBaseID: kb.ID, TenantID: kb.TenantID,+ DisableRecallThresholds: true,+ }+ byKB[kb.ID] = target+ targets = append(targets, target)+ }+ target.KnowledgeIDs = append(target.KnowledgeIDs, k.ID)+ seen[id] = true+ }+ return targets, nil+}+func knowledgeBaseIDs(kbs []*types.KnowledgeBase) []string {ids := make([]string, 0, len(kbs))for _, kb := range kbs {@@ -213,6 +258,18 @@ func wikiScopesFor(kbs []*types.KnowledgeBase) []tools.WikiScope {// then match an allowed knowledge base and that knowledge base's tenant.func (s *Server) knowledgeInScope(ctx context.Context, ep *types.MCPEndpoint, knowledgeID string,+) (*types.Knowledge, *types.KnowledgeBase, error) {+ allowed, err := s.allowedKnowledgeBases(ctx, ep)+ if err != nil {+ return nil, nil, err+ }+ return s.knowledgeInKnowledgeBases(ctx, allowed, knowledgeID)+}++// knowledgeInKnowledgeBases applies the same document/owner checks to either+// the full endpoint scope or a narrower, already authorized KB selection.+func (s *Server) knowledgeInKnowledgeBases(+ ctx context.Context, kbs []*types.KnowledgeBase, knowledgeID string,) (*types.Knowledge, *types.KnowledgeBase, error) {knowledgeID = strings.TrimSpace(knowledgeID)if knowledgeID == "" {@@ -222,13 +279,16 @@ func (s *Server) knowledgeInScope(if err != nil || k == nil {return nil, nil, fmt.Errorf("document %q was not found", knowledgeID)}- allowed, err := s.allowedKnowledgeBases(ctx, ep)- if err != nil {- return nil, nil, err+ var kb *types.KnowledgeBase+ for _, candidate := range kbs {+ if candidate.ID == k.KnowledgeBaseID {+ kb = candidate+ break+ }}- kb := matchKnowledgeBase(allowed, k.KnowledgeBaseID)if kb == nil || kb.TenantID != k.TenantID {- return nil, nil, fmt.Errorf("document %q is outside this endpoint's scope", knowledgeID)+ return nil, nil, fmt.Errorf("document %q is outside this endpoint's scope or the selected knowledge bases",+ knowledgeID)}return k, kb, nil}diff --git a/internal/mcpserver/tools_retrieve.go b/internal/mcpserver/tools_retrieve.goindex 4b8228486..074e324f2 100644--- a/internal/mcpserver/tools_retrieve.go+++ b/internal/mcpserver/tools_retrieve.go@@ -53,6 +53,11 @@ func searchKnowledgeTool() mcp.Tool {mcp.WithArray("knowledge_base_ids", mcp.WithStringItems(),mcp.Description("Optional knowledge base ids or names to restrict the search; defaults to every "+"knowledge base in scope")),+ mcp.WithArray("knowledge_ids",+ mcp.MinItems(1), mcp.MaxItems(maxSearchKnowledgeDocuments), mcp.WithStringItems(mcp.MinLength(1)),+ mcp.Description("Optional list of 1 to 100 document ids from list_documents or search results. "++ "Restricts retrieval before ranking; every document must be in scope and belong to the selected "++ "knowledge bases. Omit to search whole knowledge bases; invalid or conflicting ids return an error.")),readOnlyEndpointAnnotations(),)}@@ -165,23 +170,28 @@ func (s *Server) handleSearchKnowledge(ctx context.Context, req mcp.CallToolRequreturn mcp.NewToolResultError("none of the selected knowledge bases supports semantic or keyword retrieval"), nil}- return s.runSearchKnowledge(ctx, kbs, strings.TrimSpace(query),- req.GetString("mode", tools.SearchModeHybrid), req.GetInt("limit", 0))+ targets := searchTargetsFor(kbs)+ if _, supplied := req.GetArguments()["knowledge_ids"]; supplied {+ ids, err := req.RequireStringSlice("knowledge_ids")+ if err != nil {+ return mcp.NewToolResultError(err.Error()), nil+ }+ targets, err = s.documentSearchTargets(ctx, kbs, ids)+ if err != nil {+ return mcp.NewToolResultError(err.Error()), nil+ }+ }+ return s.runSearchKnowledgeWithFilter(ctx, targets, strings.TrimSpace(query),+ req.GetString("mode", tools.SearchModeHybrid), req.GetInt("limit", 0), nil)}-// runSearchKnowledge executes the shared search_knowledge agent tool for+// runSearchKnowledgeWithFilter executes the shared search_knowledge agent tool for// both the search_knowledge and grep_chunks endpoint tools.-func (s *Server) runSearchKnowledge(- ctx context.Context, kbs []*types.KnowledgeBase, query, mode string, limit int,-) (*mcp.CallToolResult, error) {- return s.runSearchKnowledgeWithFilter(ctx, kbs, query, mode, limit, nil)-}-func (s *Server) runSearchKnowledgeWithFilter(- ctx context.Context, kbs []*types.KnowledgeBase, query, mode string, limit int, pattern *regexp.Regexp,+ ctx context.Context, targets types.SearchTargets, query, mode string, limit int, pattern *regexp.Regexp,) (*mcp.CallToolResult, error) {tool := tools.NewSearchKnowledgeTool(- s.kbService, s.knowledgeService, s.chunkService, searchTargetsFor(kbs), nil, s.cfg,+ s.kbService, s.knowledgeService, s.chunkService, targets, nil, s.cfg,)if pattern != nil {tool.WithPatternFilter(pattern)@@ -189,7 +199,7 @@ func (s *Server) runSearchKnowledgeWithFilter(callArgs := map[string]any{"query": query,"mode": mode,- "knowledge_base_ids": knowledgeBaseIDs(kbs),+ "knowledge_base_ids": targets.GetAllKnowledgeBaseIDs(),}if limit > 0 {callArgs["limit"] = limit@@ -223,7 +233,7 @@ func (s *Server) handleGrepChunks(ctx context.Context, req mcp.CallToolRequest)"word, identifier or phrase (for example \"timeout|deadline\" instead of \"^\\d+$\")"), nil}return s.runSearchKnowledgeWithFilter(- ctx, kbs, terms, tools.SearchModeKeyword, req.GetInt("limit", 0), pattern,+ ctx, searchTargetsFor(kbs), terms, tools.SearchModeKeyword, req.GetInt("limit", 0), pattern,)}diff --git a/internal/mcpserver/tools_search_documents_test.go b/internal/mcpserver/tools_search_documents_test.gonew file mode 100644index 000000000..5ca03c406--- /dev/null+++ b/internal/mcpserver/tools_search_documents_test.go@@ -0,0 +1,338 @@+package mcpserver++import (+ "context"+ "encoding/json"+ "fmt"+ "slices"+ "sync"+ "testing"++ "github.com/Tencent/WeKnora/internal/config"+ "github.com/Tencent/WeKnora/internal/types"+ "github.com/gin-gonic/gin"+ "github.com/mark3labs/mcp-go/mcp"+ "github.com/stretchr/testify/require"+)++type documentSearchCall struct {+ kbID string+ params types.SearchParams+}++type documentSearchKBService struct {+ *stubKBService+ mu sync.Mutex+ calls []documentSearchCall+ rows []*types.SearchResult+}++func (s *documentSearchKBService) GetKnowledgeBasesByIDsOnly(+ _ context.Context, ids []string,+) ([]*types.KnowledgeBase, error) {+ var kbs []*types.KnowledgeBase+ for _, id := range ids {+ kbs = append(kbs, s.kbs[id])+ }+ return kbs, nil+}++func (s *documentSearchKBService) ResolveEmbeddingModelKeys(+ _ context.Context, kbs []*types.KnowledgeBase,+) map[string]string {+ keys := make(map[string]string, len(kbs))+ for _, kb := range kbs {+ keys[kb.ID] = "fixture-model"+ }+ return keys+}++func (s *documentSearchKBService) GetQueryEmbedding(context.Context, string, string) ([]float32, error) {+ return []float32{1, 0}, nil+}++func (s *documentSearchKBService) HybridSearch(+ _ context.Context, kbID string, params types.SearchParams,+) ([]*types.SearchResult, error) {+ s.mu.Lock()+ defer s.mu.Unlock()+ s.calls = append(s.calls, documentSearchCall{kbID: kbID, params: params})+ var rows []*types.SearchResult+ for _, row := range s.rows {+ inKB := row.KnowledgeBaseID == kbID+ if len(params.KnowledgeBaseIDs) > 0 {+ inKB = slices.Contains(params.KnowledgeBaseIDs, row.KnowledgeBaseID)+ }+ passesThreshold := (!params.DisableVectorMatch && row.Score >= params.VectorThreshold) ||+ (!params.DisableKeywordsMatch && row.Score >= params.KeywordThreshold)+ inDocumentScope := len(params.KnowledgeIDs) == 0 || slices.Contains(params.KnowledgeIDs, row.KnowledgeID)+ if inKB && passesThreshold && inDocumentScope {+ rows = append(rows, row)+ }+ }+ // Model the storage boundary: document filtering must precede candidate truncation.+ return rows[:min(len(rows), params.MatchCount)], nil+}++func newDocumentSearchFixture(t *testing.T) (*Server, *gin.Engine, *documentSearchKBService, *types.MCPEndpoint) {+ t.Helper()+ kbs := map[string]*types.KnowledgeBase{}+ for _, kb := range []*types.KnowledgeBase{+ {ID: "kb-own", Name: "Own", TenantID: 1},+ {ID: "kb-other", Name: "Other", TenantID: 1},+ {ID: "kb-shared", Name: "Shared", TenantID: 2},+ {ID: "kb-foreign", TenantID: 3},+ {ID: "kb-wiki", TenantID: 1},+ } {+ kb.IndexingStrategy.VectorEnabled = kb.ID != "kb-wiki"+ kb.IndexingStrategy.KeywordEnabled = kb.ID != "kb-wiki"+ kbs[kb.ID] = kb+ }+ docs := map[string]*types.Knowledge{}+ for id, kbID := range map[string]string{+ "doc-a": "kb-own", "doc-b": "kb-own", "doc-other": "kb-other",+ "doc-shared": "kb-shared", "doc-foreign": "kb-foreign", "doc-wiki": "kb-wiki",+ } {+ docs[id] = &types.Knowledge{ID: id, KnowledgeBaseID: kbID, TenantID: kbs[kbID].TenantID}+ }+ docs["doc-spoof"] = &types.Knowledge{ID: "doc-spoof", KnowledgeBaseID: "kb-shared", TenantID: 1}+ kbService := &documentSearchKBService{stubKBService: &stubKBService{kbs: kbs}}+ // A newer, higher-ranked same-topic document must not crowd doc-a out of the result limit.+ for i, id := range []string{"doc-b", "doc-a", "doc-other", "doc-shared"} {+ kbService.rows = append(kbService.rows, &types.SearchResult{+ ID: "chunk-" + id, KnowledgeID: id, KnowledgeBaseID: docs[id].KnowledgeBaseID,+ KnowledgeTitle: id, Content: id + " contract price", Score: 1 - float64(i)*0.1,+ ChunkType: string(types.ChunkTypeText),+ })+ }+ srv := NewServer(kbService, &stubKnowledgeService{docs: docs}, nil, nil, nil, nil, nil,+ &stubKBShareService{shared: map[string]types.OrgMemberRole{"kb-shared": types.OrgRoleViewer}},+ nil, nil, nil, &config.Config{Conversation: &config.ConversationConfig{+ EmbeddingTopK: 1, VectorThreshold: 0.95, KeywordThreshold: 0.95,+ }},+ nil, nil, nil, nil)+ ep := &types.MCPEndpoint{+ ID: "ep-1", TenantID: 1, Enabled: true,+ KnowledgeBaseIDs: types.StringArray{"kb-own", "kb-other", "kb-shared", "kb-wiki"},+ Tools: types.StringArray{types.MCPEndpointToolSearchKnowledge, types.MCPEndpointToolGrepChunks},+ }+ r := gin.New()+ r.POST("/mcp/:endpoint_id", func(c *gin.Context) {+ c.Request = c.Request.WithContext(mcpCallContext(1, ep))+ c.Next()+ }, gin.WrapH(srv.Handler()))+ return srv, r, kbService, ep+}++func TestMCPSearchKnowledgeDocumentScopeBeforeRetrieval(t *testing.T) {+ for _, mode := range []string{"hybrid", "semantic", "keyword"} {+ t.Run(mode, func(t *testing.T) {+ _, r, kbService, _ := newDocumentSearchFixture(t)+ response := rpc(t, r, "tools/call", map[string]any{+ "name": types.MCPEndpointToolSearchKnowledge,+ "arguments": map[string]any{+ "query": "contract price", "mode": mode, "limit": 1,+ "knowledge_ids": []string{" doc-a ", "doc-a"},+ },+ })+ require.NotContains(t, response, "error")+ raw, err := json.Marshal(response["result"])+ require.NoError(t, err)+ var result struct {+ IsError bool `json:"isError"`+ Content []struct{ Text string } `json:"content"`+ Data struct {+ Results []struct {+ KnowledgeID string `json:"knowledge_id"`+ } `json:"results"`+ } `json:"structuredContent"`+ }+ require.NoError(t, json.Unmarshal(raw, &result))+ require.False(t, result.IsError, "%s", raw)+ require.Len(t, result.Data.Results, 1)+ require.Equal(t, "doc-a", result.Data.Results[0].KnowledgeID)+ require.Contains(t, result.Content[0].Text, `knowledge_id="doc-a"`)+ require.NotContains(t, result.Content[0].Text, `knowledge_id="doc-b"`)+ require.Len(t, kbService.calls, 1)+ call := kbService.calls[0]+ require.Equal(t, "kb-own", call.kbID)+ require.Equal(t, []string{"doc-a"}, call.params.KnowledgeIDs)+ require.Empty(t, call.params.KnowledgeBaseIDs)+ require.Equal(t, 1, call.params.MatchCount)+ require.Equal(t, mode == "keyword", call.params.DisableVectorMatch)+ require.Equal(t, mode == "semantic", call.params.DisableKeywordsMatch)+ require.Zero(t, call.params.VectorThreshold)+ require.Zero(t, call.params.KeywordThreshold)+ })+ }+}++func TestMCPSearchKnowledgeMultipleDocumentsAndSharedScope(t *testing.T) {+ _, r, kbService, _ := newDocumentSearchFixture(t)+ response := rpc(t, r, "tools/call", map[string]any{+ "name": types.MCPEndpointToolSearchKnowledge,+ "arguments": map[string]any{+ "query": "contract", "knowledge_base_ids": []string{"Own", "Shared", "Other"},+ "knowledge_ids": []string{"doc-a", "doc-b", "doc-shared", "doc-a"},+ },+ })+ require.NotContains(t, response, "error")+ result := response["result"].(map[string]any)+ require.NotEqual(t, true, result["isError"], "%+v", result)+ var ids []string+ for _, raw := range result["structuredContent"].(map[string]any)["results"].([]any) {+ ids = append(ids, raw.(map[string]any)["knowledge_id"].(string))+ }+ require.ElementsMatch(t, []string{"doc-a", "doc-b", "doc-shared"}, ids)+ require.Len(t, kbService.calls, 2)+ byKB := map[string][]string{}+ for _, call := range kbService.calls {+ byKB[call.kbID] = call.params.KnowledgeIDs+ }+ require.Equal(t, map[string][]string{+ "kb-own": {"doc-a", "doc-b"}, "kb-shared": {"doc-shared"},+ }, byKB)+}++func TestMCPSearchKnowledgeRejectsInvalidDocumentScope(t *testing.T) {+ for _, tc := range []struct {+ name string+ ids any+ kbs []string+ }{+ {name: "missing document", ids: []string{"missing"}},+ {name: "foreign document", ids: []string{"doc-foreign"}},+ {name: "tenant mismatch", ids: []string{"doc-spoof"}},+ {name: "empty intersection", ids: []string{"doc-a"}, kbs: []string{"Shared"}},+ {name: "partial conflict", ids: []string{"doc-a", "doc-shared"}, kbs: []string{"Own"}},+ {name: "non-retrievable document", ids: []string{"doc-wiki"}},+ {name: "empty array", ids: []string{}},+ {name: "null", ids: nil},+ {name: "string", ids: "doc-a"},+ {name: "mixed types", ids: []any{"doc-a", 42}},+ {name: "null entry", ids: []any{"doc-a", nil}},+ {name: "blank entry", ids: []string{"doc-a", " "}},+ } {+ t.Run(tc.name, func(t *testing.T) {+ srv, _, kbService, ep := newDocumentSearchFixture(t)+ args := map[string]any{"query": "contract", "knowledge_ids": tc.ids}+ if tc.kbs != nil {+ args["knowledge_base_ids"] = tc.kbs+ }+ result, err := srv.handleSearchKnowledge(mcpCallContext(1, ep), mcp.CallToolRequest{+ Params: mcp.CallToolParams{Arguments: args},+ })+ require.NoError(t, err)+ require.True(t, result.IsError, "%+v", result)+ require.Empty(t, kbService.calls, "invalid scope must never fall back to whole-KB retrieval")+ })+ }+}++func TestMCPSearchKnowledgeOmittedDocumentScopeAndGrepKeepWholeKBTargets(t *testing.T) {+ for _, tool := range []string{types.MCPEndpointToolSearchKnowledge, types.MCPEndpointToolGrepChunks} {+ t.Run(tool, func(t *testing.T) {+ _, r, kbService, _ := newDocumentSearchFixture(t)+ response := rpc(t, r, "tools/call", map[string]any{+ "name": tool, "arguments": map[string]any{+ "query": "contract", "knowledge_base_ids": []string{"Own"},+ },+ })+ require.NotContains(t, response, "error")+ require.Len(t, kbService.calls, 1)+ require.Empty(t, kbService.calls[0].params.KnowledgeIDs)+ require.Equal(t, []string{"kb-own"}, kbService.calls[0].params.KnowledgeBaseIDs)+ require.Equal(t, 0.95, kbService.calls[0].params.VectorThreshold)+ require.Equal(t, 0.95, kbService.calls[0].params.KeywordThreshold)+ })+ }+}++func TestMCPSearchKnowledgeDocumentScopeSchema(t *testing.T) {+ _, r, _, _ := newDocumentSearchFixture(t)+ response := rpc(t, r, "tools/list", map[string]any{})+ result := response["result"].(map[string]any)+ for _, raw := range result["tools"].([]any) {+ tool := raw.(map[string]any)+ if tool["name"] != types.MCPEndpointToolSearchKnowledge {+ continue+ }+ schema := tool["inputSchema"].(map[string]any)+ property := schema["properties"].(map[string]any)["knowledge_ids"].(map[string]any)+ require.Equal(t, "array", property["type"])+ require.EqualValues(t, 1, property["minItems"])+ require.EqualValues(t, 100, property["maxItems"])+ require.Equal(t, "string", property["items"].(map[string]any)["type"])+ require.NotContains(t, schema["required"], "knowledge_ids")+ return+ }+ t.Fatal("search_knowledge is missing from tools/list")+}++func TestMCPSearchKnowledgeRechecksEndpointAndShareRestrictions(t *testing.T) {+ for _, tc := range []struct {+ name string+ shared bool+ }{+ {name: "endpoint restriction"},+ {name: "revoked share", shared: true},+ } {+ t.Run(tc.name, func(t *testing.T) {+ srv, r, kbService, ep := newDocumentSearchFixture(t)+ id := "doc-other"+ if tc.shared {+ id = "doc-shared"+ srv.kbShareService = &stubKBShareService{shared: map[string]types.OrgMemberRole{}}+ } else {+ ep.KnowledgeBaseIDs = types.StringArray{"kb-own"}+ }+ response := rpc(t, r, "tools/call", map[string]any{+ "name": types.MCPEndpointToolSearchKnowledge,+ "arguments": map[string]any{"query": "contract", "knowledge_ids": []string{id}},+ })+ require.NotContains(t, response, "error")+ require.Equal(t, true, response["result"].(map[string]any)["isError"])+ require.Empty(t, kbService.calls)+ })+ }+}++// Count lookups to ensure oversized requests are rejected before any document I/O.+type countingDocumentService struct {+ *stubKnowledgeService+ lookups int+}++func (s *countingDocumentService) GetKnowledgeByIDOnly(ctx context.Context, id string) (*types.Knowledge, error) {+ s.lookups+++ return s.stubKnowledgeService.GetKnowledgeByIDOnly(ctx, id)+}++func TestMCPSearchKnowledgeDocumentScopeSizeLimit(t *testing.T) {+ for _, count := range []int{100, 101} {+ t.Run(fmt.Sprint(count), func(t *testing.T) {+ srv, _, kbService, ep := newDocumentSearchFixture(t)+ service := &countingDocumentService{stubKnowledgeService: srv.knowledgeService.(*stubKnowledgeService)}+ srv.knowledgeService = service+ ids := make([]string, count)+ for i := range ids {+ ids[i] = fmt.Sprintf("selected-%d", i)+ service.docs[ids[i]] = &types.Knowledge{ID: ids[i], KnowledgeBaseID: "kb-own", TenantID: 1}+ }+ result, err := srv.handleSearchKnowledge(mcpCallContext(1, ep), mcp.CallToolRequest{+ Params: mcp.CallToolParams{Arguments: map[string]any{"query": "contract", "knowledge_ids": ids}},+ })+ require.NoError(t, err)+ if count == 100 {+ require.False(t, result.IsError)+ require.Equal(t, count, service.lookups)+ require.Len(t, kbService.calls, 1)+ require.Len(t, kbService.calls[0].params.KnowledgeIDs, count)+ } else {+ require.True(t, result.IsError)+ require.Zero(t, service.lookups)+ require.Empty(t, kbService.calls)+ }+ })+ }+}diff --git a/website-docs/03-features/08-mcp.md b/website-docs/03-features/08-mcp.mdindex b52a5320e..7cd9f7e9d 100644--- a/website-docs/03-features/08-mcp.md+++ b/website-docs/03-features/08-mcp.md@@ -55,6 +55,24 @@ MCP 管理页支持按服务名称和卡片显示的用途说明搜索。搜索| Wiki | `wiki_search`、`wiki_read_page`、`wiki_index` | 只对开启了 Wiki 的知识库生效;`wiki_search` 的 `query` 保持原有的正则语义(大小写不敏感),不是合法正则的文本按字面匹配;`regex=false` 强制字面匹配,`regex=true` 要求合法正则 || 写入 | `add_document`、`update_document`、`delete_document` | 默认关闭;支持 Markdown 文本或 URL 导入 |+`search_knowledge` 可通过可选的 `knowledge_ids` 字符串数组限定文档范围,三种 `mode` 均支持。先用 `list_documents` 或搜索结果取得真实文档 ID,再传入这些 ID;文档过滤在召回和候选数截断之前生效,同库其他文档不会参与此次检索。省略该参数时沿用整库检索。传入时数组必须非空,且不能包含空白 ID;ID 两端空白会被去除,重复 ID 自动去重。++若同时传入 `knowledge_base_ids`,每个文档都必须属于所选知识库;仅检索这些文档,不会额外搜索所选库里的其他文档。不存在的文档、越权文档、与知识库选择冲突的文档或没有向量/关键词索引的文档都会返回错误,整次调用不会退回整库检索。共享知识库沿用端点授权和所属空间校验。++例如,假设 `list_documents` 已返回 `doc-a` 和 `doc-b`,`tools/call` 的参数可以写为:++```json+{+ "name": "search_knowledge",+ "arguments": {+ "query": "合同价格",+ "mode": "hybrid",+ "knowledge_ids": ["doc-a", "doc-b"],+ "limit": 10+ }+}+```+`search_knowledge` 的结构化结果 `results[].chunk_type` 和文本结果的 `chunk_type` 属性保留命中片段的原始类型,例如 `text`、`summary`、`image_ocr`、`image_caption` 或 `image_vector`。空字符串表示类型未知,不能据此认定为原文;客户端可据类型决定是否补读文档正文。现有 MCP 工具的返回结果会复用 REST/IM 的资源链接转换:正文、Wiki 内容以及结构化数据中的图片引用,都会在权限校验后转换为可直接访问的 HTTP(S) 链接,不需要新增工具或修改端点工具清单。`ask` 的 `references[].images` 保留图片 URL、caption 和 OCR 文本,文本引用列表也包含图片链接,避免正文摘要截断后丢失图片信息。