From 177f5e44b43b124e5fd9ee62ab2afc5277cb00ab Mon Sep 17 00:00:00 2001 From: wizardchen Date: Fri, 10 Apr 2026 00:08:23 +0800 Subject: [PATCH] feat: Introduce `wiki_read_source_doc` tool for enhanced document retrieval - Added a new tool, `wiki_read_source_doc`, allowing agents to access specific source documents for detailed information retrieval when wiki page content is insufficient. - Updated the agent system prompt and tool definitions to incorporate the new tool, enhancing the agent's capabilities for in-depth knowledge extraction. - Modified existing tools to support the new functionality, ensuring seamless integration within the agent's workflow. These changes significantly improve the agent's ability to provide accurate and detailed responses by leveraging source documents alongside wiki content. --- config/builtin_agents.yaml | 1 + .../prompt_templates/agent_system_prompt.yaml | 4 +- internal/agent/observe.go | 1 + internal/agent/tools/definitions.go | 6 +- internal/agent/tools/wiki_read_source_doc.go | 280 ++++++++++++++++++ internal/agent/tools/wiki_tools.go | 75 ++++- internal/application/service/agent_service.go | 3 + 7 files changed, 365 insertions(+), 5 deletions(-) create mode 100644 internal/agent/tools/wiki_read_source_doc.go diff --git a/config/builtin_agents.yaml b/config/builtin_agents.yaml index 2c6de91b..3b500ffd 100644 --- a/config/builtin_agents.yaml +++ b/config/builtin_agents.yaml @@ -173,6 +173,7 @@ builtin_agents: - "todo_write" - "wiki_search" - "wiki_read_page" + - "wiki_read_source_doc" web_search_enabled: false web_search_max_results: 0 reflection_enabled: false diff --git a/config/prompt_templates/agent_system_prompt.yaml b/config/prompt_templates/agent_system_prompt.yaml index 9e3a016c..77841410 100644 --- a/config/prompt_templates/agent_system_prompt.yaml +++ b/config/prompt_templates/agent_system_prompt.yaml @@ -253,7 +253,8 @@ templates: - **Outgoing links (`Links to`):** Use these to dive deeper into specific concepts, people, or items mentioned in the current page's text. - **Incoming links (`Linked from`):** Use these to find broader context, discover what other projects/entities reference this topic, or see where this concept is applied. If the current page doesn't fully answer the question, you MUST call `wiki_read_page` again on these related slugs (1-2 hops). - 4. **Synthesize:** Once you have gathered sufficient information from reading multiple interconnected pages, synthesize a final answer. + 4. **Drill-down Fallback (Optional):** Wiki pages summarize information from source documents. If the user asks for highly specific details (e.g. exact quotes, raw data, or specific code snippets) that are not present in the wiki page, check the `` section of that wiki page. Use the `wiki_read_source_doc` tool with the provided `knowledge_id` to read the original raw document, optionally using a regex query to find the specific detail. + 5. **Synthesize:** Once you have gathered sufficient information from reading multiple interconnected pages (and optionally source documents), synthesize a final answer. If you encountered images (e.g. ``) in the source documents that are relevant to the user's query, be sure to output them in your final response using Markdown format (`![alt](url)`). @@ -267,6 +268,7 @@ templates: * **wiki_search:** Use this to find entry points. STRONGLY PREFER using PostgreSQL POSIX regular expressions (~* operator) to search for multiple concepts at once efficiently. Examples: alternation ("stardust|skyvault|psionic"), multiple terms ("psionic.*engine"), prefix ("^entity/.*"). Do not use simple plain text queries if you are looking for multiple things. You can provide multiple queries at once to search in parallel. * **wiki_read_page:** Your primary tool. Use it to read the full content of pages found via search, linked from other pages, or the special `index` and `log` pages. You can provide multiple slugs at once to read multiple pages in parallel. + * **wiki_read_source_doc:** Use this ONLY as a fallback when a wiki page's content is insufficient and you need to dive into the raw source document listed in the page's `` section. Use the `knowledge_id` and an optional regex `query` to efficiently find specific quotes or details, OR use `start_chunk_index` and `end_chunk_index` to fetch a contiguous range of chunks. diff --git a/internal/agent/observe.go b/internal/agent/observe.go index 811b07d9..6e44d0aa 100644 --- a/internal/agent/observe.go +++ b/internal/agent/observe.go @@ -335,6 +335,7 @@ var kbToolNames = map[string]bool{ agenttools.ToolGetDocumentInfo: true, agenttools.ToolWikiSearch: true, agenttools.ToolWikiReadPage: true, + agenttools.ToolWikiReadSourceDoc: true, } // redactHistoryKBResults replaces full KB tool results in historical context diff --git a/internal/agent/tools/definitions.go b/internal/agent/tools/definitions.go index 8283ba99..28cdb7de 100644 --- a/internal/agent/tools/definitions.go +++ b/internal/agent/tools/definitions.go @@ -23,8 +23,9 @@ const ( ToolExecuteSkillScript = "execute_skill_script" ToolReadSkill = "read_skill" // Wiki-related tools (only available when wiki KBs are in scope) - ToolWikiReadPage = "wiki_read_page" - ToolWikiSearch = "wiki_search" + ToolWikiReadPage = "wiki_read_page" + ToolWikiSearch = "wiki_search" + ToolWikiReadSourceDoc = "wiki_read_source_doc" ) // AvailableTool defines a simple tool metadata used by settings APIs. @@ -53,6 +54,7 @@ func AvailableToolDefinitions() []AvailableTool { {Name: ToolFinalAnswer, Label: "提交最终回答", Description: "提交最终回答给用户"}, {Name: ToolWikiReadPage, Label: "读取Wiki页面", Description: "读取指定的Wiki页面内容"}, {Name: ToolWikiSearch, Label: "搜索Wiki", Description: "在Wiki中搜索页面"}, + {Name: ToolWikiReadSourceDoc, Label: "精读源文档", Description: "使用知识点深入阅读特定原始文档"}, } } diff --git a/internal/agent/tools/wiki_read_source_doc.go b/internal/agent/tools/wiki_read_source_doc.go new file mode 100644 index 00000000..343a1ec0 --- /dev/null +++ b/internal/agent/tools/wiki_read_source_doc.go @@ -0,0 +1,280 @@ +package tools + +import ( + "context" + "encoding/json" + "fmt" + "regexp" + "strings" + + "github.com/Tencent/WeKnora/internal/types" + "github.com/Tencent/WeKnora/internal/types/interfaces" +) + +type wikiReadSourceDocTool struct { + BaseTool + knowledgeService interfaces.KnowledgeService + chunkService interfaces.ChunkService +} + +func NewWikiReadSourceDocTool(knowledgeService interfaces.KnowledgeService, chunkService interfaces.ChunkService) types.Tool { + return &wikiReadSourceDocTool{ + BaseTool: NewBaseTool( + ToolWikiReadSourceDoc, + `Read or search within a specific source document to drill down for details omitted from the wiki. +Provide the knowledge_id from the block. +You can EITHER search using a regex query OR fetch a specific contiguous range of chunks using start_chunk_index and end_chunk_index (useful for expanding context around a known chunk). +If neither query nor range is provided, it returns the beginning of the document.`, + json.RawMessage(`{ + "type": "object", + "properties": { + "knowledge_id": { + "type": "string", + "description": "The ID of the source document to read" + }, + "query": { + "type": "string", + "description": "Optional: A regex query to filter the document chunks. Use this to find specific quotes or details efficiently." + }, + "start_chunk_index": { + "type": "integer", + "description": "Optional: The starting chunk index (1-based) to read a specific range." + }, + "end_chunk_index": { + "type": "integer", + "description": "Optional: The ending chunk index (1-based) to read a specific range. Must be >= start_chunk_index." + } + }, + "required": ["knowledge_id"] +}`), + ), + knowledgeService: knowledgeService, + chunkService: chunkService, + } +} + +func enrichChunkContent(c *types.Chunk) string { + content := c.Content + if c.ImageInfo != "" { + var imgInfos []types.ImageInfo + if err := json.Unmarshal([]byte(c.ImageInfo), &imgInfos); err == nil && len(imgInfos) > 0 { + var imgBuilder strings.Builder + for _, img := range imgInfos { + if img.URL != "" { + imgBuilder.WriteString(fmt.Sprintf("\n\n", img.URL)) + if img.Caption != "" { + imgBuilder.WriteString(fmt.Sprintf("%s\n", img.Caption)) + } + if img.OCRText != "" { + imgBuilder.WriteString(fmt.Sprintf("%s\n", img.OCRText)) + } + imgBuilder.WriteString("") + } + } + content += imgBuilder.String() + } + } + return content +} + +func (t *wikiReadSourceDocTool) Execute(ctx context.Context, args json.RawMessage) (*types.ToolResult, error) { + var params struct { + KnowledgeID string `json:"knowledge_id"` + Query string `json:"query"` + StartChunkIndex int `json:"start_chunk_index"` + EndChunkIndex int `json:"end_chunk_index"` + } + if err := json.Unmarshal(args, ¶ms); err != nil { + return &types.ToolResult{Success: false, Error: "Invalid parameters: " + err.Error()}, nil + } + + knowledgeID := strings.TrimSpace(params.KnowledgeID) + if knowledgeID == "" { + return &types.ToolResult{Success: false, Error: "knowledge_id is required"}, nil + } + + knowledge, err := t.knowledgeService.GetKnowledgeByIDOnly(ctx, knowledgeID) + if err != nil { + return &types.ToolResult{Success: false, Error: fmt.Sprintf("Document not found: %v", err)}, nil + } + + var sb strings.Builder + sb.WriteString("\n\n") + sb.WriteString(fmt.Sprintf("%s\n", knowledge.Title)) + sb.WriteString(fmt.Sprintf("%s\n", knowledgeID)) + + hasRange := params.StartChunkIndex > 0 + var re *regexp.Regexp + + if hasRange { + if params.EndChunkIndex < params.StartChunkIndex { + params.EndChunkIndex = params.StartChunkIndex + 10 // Default window + } + if params.EndChunkIndex-params.StartChunkIndex > 50 { + params.EndChunkIndex = params.StartChunkIndex + 50 // Max 50 chunks to prevent bloat + } + sb.WriteString(fmt.Sprintf("\n", params.StartChunkIndex, params.EndChunkIndex)) + } else if params.Query != "" { + compiled, err := regexp.Compile("(?i)" + params.Query) + if err != nil { + return &types.ToolResult{Success: false, Error: fmt.Sprintf("Invalid regex query '%s': %v", params.Query, err)}, nil + } + re = compiled + sb.WriteString(fmt.Sprintf("%s\n", params.Query)) + } + + matchCount := 0 + pageSize := 100 + page := 1 + if hasRange { + page = (params.StartChunkIndex - 1) / pageSize + 1 + } + + var chunksOutput strings.Builder + totalChunks := int64(0) + reachedMax := false + + var prevChunk *types.Chunk + var forceOutputNext bool + outputtedIndices := make(map[int]bool) + + for { + pagination := &types.Pagination{ + Page: page, + PageSize: pageSize, + } + + chunks, total, err := t.chunkService.GetRepository().ListPagedChunksByKnowledgeID( + ctx, + knowledge.TenantID, + knowledgeID, + pagination, + []types.ChunkType{types.ChunkTypeText, types.ChunkTypeFAQ}, + "", "", "", "", "", + ) + if err != nil { + return &types.ToolResult{Success: false, Error: fmt.Sprintf("Failed to list chunks: %v", err)}, nil + } + + if page == 1 { + totalChunks = total + } + + if len(chunks) == 0 { + break + } + + for _, c := range chunks { + chunkNum := c.ChunkIndex + 1 + chunkContent := enrichChunkContent(c) + + if hasRange { + if chunkNum < params.StartChunkIndex { + continue + } + if chunkNum > params.EndChunkIndex { + reachedMax = true + break + } + fmt.Fprintf(&chunksOutput, "\n%s\n\n", chunkNum, chunkContent) + matchCount++ + continue + } + + isMatch := false + if re != nil { + isMatch = re.MatchString(chunkContent) + } else { + isMatch = true + } + + if isMatch { + matchCount++ + + if re != nil { + // Output previous chunk for context + if prevChunk != nil && !outputtedIndices[prevChunk.ChunkIndex] { + prevContent := enrichChunkContent(prevChunk) + fmt.Fprintf(&chunksOutput, "\n%s\n\n", prevChunk.ChunkIndex+1, prevContent) + outputtedIndices[prevChunk.ChunkIndex] = true + } + } + + if !outputtedIndices[c.ChunkIndex] { + matchAttr := "" + if re != nil { + matchAttr = ` type="match"` + } + fmt.Fprintf(&chunksOutput, "\n%s\n\n", c.ChunkIndex+1, matchAttr, chunkContent) + outputtedIndices[c.ChunkIndex] = true + } + + if re != nil { + forceOutputNext = true + } + } else if forceOutputNext { + if !outputtedIndices[c.ChunkIndex] { + fmt.Fprintf(&chunksOutput, "\n%s\n\n", c.ChunkIndex+1, chunkContent) + outputtedIndices[c.ChunkIndex] = true + } + forceOutputNext = false + } + + prevChunk = c + + if re == nil && matchCount >= 10 { + break + } + if re != nil && matchCount >= 20 { + break + } + } + + if hasRange && reachedMax { + break + } + + if !hasRange { + if re == nil && matchCount >= 10 { + break + } + if re != nil && matchCount >= 20 { + reachedMax = true + break + } + } + + if int64(page*pageSize) >= total { + break + } + page++ + } + + sb.WriteString(fmt.Sprintf("%d\n\n", totalChunks)) + + if matchCount > 0 { + sb.WriteString(fmt.Sprintf("\n", matchCount)) + sb.WriteString(chunksOutput.String()) + sb.WriteString("\n") + } else { + sb.WriteString("\n") + } + + if reachedMax { + sb.WriteString("Reached maximum limit for fetching chunks in a single call. Please refine your query or range if needed.\n") + } else if matchCount == 0 { + if hasRange { + sb.WriteString("No chunks found in the specified range.\n") + } else if re != nil { + sb.WriteString("No chunks matched your query in this document.\n") + } else { + sb.WriteString("Document has no text chunks available.\n") + } + } else if !hasRange && re == nil { + sb.WriteString("No query or range provided. Showing the first 10 chunks as a preview.\n") + } + + sb.WriteString("") + + return &types.ToolResult{Success: true, Output: sb.String()}, nil +} diff --git a/internal/agent/tools/wiki_tools.go b/internal/agent/tools/wiki_tools.go index 15c56ec0..de8332f4 100644 --- a/internal/agent/tools/wiki_tools.go +++ b/internal/agent/tools/wiki_tools.go @@ -4,6 +4,7 @@ import ( "context" "encoding/json" "fmt" + "regexp" "strings" "sync" @@ -112,6 +113,25 @@ func (t *wikiReadPageTool) Execute(ctx context.Context, args json.RawMessage) (* outLinksDesc := formatLinks(page.OutLinks, kbID) inLinksDesc := formatLinks(page.InLinks, kbID) + // Render source refs + var sourcesDesc []string + if len(page.SourceRefs) > 0 { + for _, ref := range page.SourceRefs { + // SourceRefs might be "knowledgeID" or "knowledgeID|Title" + kid := ref + title := "" + if pipeIdx := strings.Index(ref, "|"); pipeIdx > 0 { + kid = ref[:pipeIdx] + title = ref[pipeIdx+1:] + } + if title != "" { + sourcesDesc = append(sourcesDesc, fmt.Sprintf(`%s`, kid, title)) + } else { + sourcesDesc = append(sourcesDesc, fmt.Sprintf(``, kid)) + } + } + } + output := fmt.Sprintf(` %s @@ -122,6 +142,9 @@ func (t *wikiReadPageTool) Execute(ctx context.Context, args json.RawMessage) (* %s %s + +%s + %s @@ -129,6 +152,7 @@ func (t *wikiReadPageTool) Execute(ctx context.Context, args json.RawMessage) (* page.Title, page.Slug, page.PageType, strings.Join(outLinksDesc, ", "), strings.Join(inLinksDesc, ", "), + strings.Join(sourcesDesc, "\n"), page.Content, ) outputs = append(outputs, output) @@ -244,10 +268,16 @@ func (t *wikiSearchTool) Execute(ctx context.Context, args json.RawMessage) (*ty t.seenSlugs[p.Slug] = true t.mu.Unlock() + snippet := extractSnippet(p.Content, query) + snippetTag := "" + if snippet != "" { + snippetTag = fmt.Sprintf("\n%s", snippet) + } + if seen { - fmt.Fprintf(&sb, "\n%s\n%s\n%s\n(summary omitted, already seen in previous search)\n\n", p.Title, p.Slug, p.PageType) + fmt.Fprintf(&sb, "\n%s\n%s\n%s\n(summary omitted, already seen in previous search)%s\n\n", p.Title, p.Slug, p.PageType, snippetTag) } else { - fmt.Fprintf(&sb, "\n%s\n%s\n%s\n%s\n\n", p.Title, p.Slug, p.PageType, p.Summary) + fmt.Fprintf(&sb, "\n%s\n%s\n%s\n%s%s\n\n", p.Title, p.Slug, p.PageType, p.Summary, snippetTag) } } sb.WriteString("") @@ -292,3 +322,44 @@ func parseStringOrArray(val any) []string { } return nil } + +func extractSnippet(content string, query string) string { + if content == "" || query == "" { + return "" + } + re, err := regexp.Compile("(?i)" + query) + if err != nil { + return "" + } + loc := re.FindStringIndex(content) + if loc == nil { + return "" + } + + matchStr := content[loc[0]:loc[1]] + before := content[:loc[0]] + after := content[loc[1]:] + + beforeRunes := []rune(before) + if len(beforeRunes) > 60 { + beforeRunes = beforeRunes[len(beforeRunes)-60:] + } + + afterRunes := []rune(after) + if len(afterRunes) > 60 { + afterRunes = afterRunes[:60] + } + + matchRunes := []rune(matchStr) + if len(matchRunes) > 100 { + matchRunes = append(matchRunes[:100], []rune("...")...) + } + + snippet := string(beforeRunes) + string(matchRunes) + string(afterRunes) + snippet = strings.ReplaceAll(snippet, "\n", " ") + for strings.Contains(snippet, " ") { + snippet = strings.ReplaceAll(snippet, " ", " ") + } + + return "... " + strings.TrimSpace(snippet) + " ..." +} diff --git a/internal/application/service/agent_service.go b/internal/application/service/agent_service.go index 8ce9c046..efec93e2 100644 --- a/internal/application/service/agent_service.go +++ b/internal/application/service/agent_service.go @@ -381,6 +381,7 @@ func (s *agentService) registerTools( allowedTools = append(allowedTools, tools.ToolWikiReadPage, tools.ToolWikiSearch, + tools.ToolWikiReadSourceDoc, ) logger.Infof(ctx, "Wiki KBs detected (%d), wiki tools added", len(wikiKBIDs)) } @@ -450,6 +451,8 @@ func (s *agentService) registerTools( toolToRegister = tools.NewWikiReadPageTool(s.wikiPageService, wikiKBIDs) case tools.ToolWikiSearch: toolToRegister = tools.NewWikiSearchTool(s.wikiPageService, wikiKBIDs) + case tools.ToolWikiReadSourceDoc: + toolToRegister = tools.NewWikiReadSourceDocTool(s.knowledgeService, s.chunkService) default: logger.Warnf(ctx, "Unknown tool: %s", toolName)