5d0326f987
Weak LLMs routinely mangle high-entropy wiki slugs (especially UUID-based summary/<id> slugs), producing dead cross-links and cross-item dedup hallucinations. This tightens integrity end to end: - Ingest dedup now groups each new item with only its own trigram candidates and validates merges against that per-item scope, rejecting cross-item mispairings; candidate top-K narrowed 20 -> 5. - Editor path aliases out-link slugs behind low-entropy ref-N tokens and translates them back after generation, removing the chance to mangle. - Agent write tool normalizes/validates slugs, blocks manual creation of system-owned summary pages, and auto-repairs dead [[slug]] links (rewrite-only, never strips) via bigram/display-text resolution. - llmresource registry aliases summary/<uuid> slugs the same way as storage handles so they round-trip safely through chat. Adds unit tests for slug validation, aliasing round-trip, dead-link repair, and dedup rejection rules.
234 lines
8.3 KiB
Go
234 lines
8.3 KiB
Go
package tools
|
|
|
|
import (
|
|
"context"
|
|
"encoding/json"
|
|
"errors"
|
|
"fmt"
|
|
"strings"
|
|
|
|
"github.com/Tencent/WeKnora/internal/application/repository"
|
|
"github.com/Tencent/WeKnora/internal/types"
|
|
"github.com/Tencent/WeKnora/internal/types/interfaces"
|
|
)
|
|
|
|
type wikiWritePageTool struct {
|
|
BaseTool
|
|
wikiPageService interfaces.WikiPageService
|
|
knowledgeService interfaces.KnowledgeService
|
|
kbIDs []string
|
|
}
|
|
|
|
// NewWikiWritePageTool creates a new wiki_write_page tool
|
|
func NewWikiWritePageTool(wikiPageService interfaces.WikiPageService, kbIDs []string, knowledgeService interfaces.KnowledgeService) types.Tool {
|
|
return &wikiWritePageTool{
|
|
BaseTool: NewBaseTool(
|
|
ToolWikiWritePage,
|
|
"Create a new Wiki page or completely overwrite an existing one. Automatically handles outbound links.",
|
|
json.RawMessage(`{
|
|
"type": "object",
|
|
"properties": {
|
|
"slug": {
|
|
"type": "string",
|
|
"description": "The slug of the Wiki page (e.g. 'entity/hunyuan-damoxing')"
|
|
},
|
|
"title": {
|
|
"type": "string",
|
|
"description": "The title of the page"
|
|
},
|
|
"summary": {
|
|
"type": "string",
|
|
"description": "A one-sentence summary for the index listing"
|
|
},
|
|
"content": {
|
|
"type": "string",
|
|
"description": "The FULL, complete Markdown content of the page. Do NOT use placeholders."
|
|
},
|
|
"page_type": {
|
|
"type": "string",
|
|
"description": "The page type, e.g., 'summary', 'entity', 'concept', 'synthesis', 'comparison'"
|
|
},
|
|
"aliases": {
|
|
"type": "array",
|
|
"items": {"type": "string"},
|
|
"description": "A list of aliases for the page (optional)"
|
|
},
|
|
"source_refs": {
|
|
"type": "array",
|
|
"items": {"type": "string"},
|
|
"description": "A list of short dN source document IDs that contributed to this page. If provided, these will COMPLETELY REPLACE the existing source_refs of the page."
|
|
}
|
|
},
|
|
"required": ["slug", "title", "summary", "content", "page_type"]
|
|
}`),
|
|
),
|
|
wikiPageService: wikiPageService,
|
|
knowledgeService: knowledgeService,
|
|
kbIDs: kbIDs,
|
|
}
|
|
}
|
|
|
|
func (t *wikiWritePageTool) Execute(ctx context.Context, args json.RawMessage) (*types.ToolResult, error) {
|
|
var params struct {
|
|
Slug string `json:"slug"`
|
|
Title string `json:"title"`
|
|
Summary string `json:"summary"`
|
|
Content string `json:"content"`
|
|
PageType string `json:"page_type"`
|
|
Aliases []string `json:"aliases"`
|
|
SourceRefs []string `json:"source_refs"`
|
|
}
|
|
|
|
if err := json.Unmarshal(args, ¶ms); err != nil {
|
|
return &types.ToolResult{Success: false, Error: "Failed to parse arguments: " + err.Error()}, nil
|
|
}
|
|
|
|
if len(t.kbIDs) == 0 {
|
|
return &types.ToolResult{Success: false, Error: "No knowledge bases available for editing"}, nil
|
|
}
|
|
kbID := t.kbIDs[0]
|
|
|
|
if params.Title == "" || params.PageType == "" || params.Content == "" || params.Summary == "" {
|
|
return &types.ToolResult{Success: false, Error: "title, summary, content, and page_type are required for write action"}, nil
|
|
}
|
|
|
|
// Validate + normalize the slug up front. The model routinely emits
|
|
// malformed slugs (stray characters, mangled UUIDs); persisting them
|
|
// verbatim creates unreachable pages and dead cross-links.
|
|
normalizedSlug, slugErr := normalizeAndValidateWikiSlug(params.Slug)
|
|
if slugErr != nil {
|
|
return &types.ToolResult{Success: false, Error: slugErr.Error()}, nil
|
|
}
|
|
params.Slug = normalizedSlug
|
|
|
|
// Try to get the existing page
|
|
existingPage, err := t.wikiPageService.GetPageBySlug(ctx, kbID, params.Slug)
|
|
if err != nil && !errors.Is(err, repository.ErrWikiPageNotFound) {
|
|
return &types.ToolResult{Success: false, Error: "Failed to check existing page: " + err.Error()}, nil
|
|
}
|
|
|
|
// Summary pages are system-owned: they are generated deterministically
|
|
// from a source document and keyed by its knowledge ID
|
|
// (summary/<knowledgeID>). Letting the agent CREATE one with an
|
|
// arbitrary/hand-typed slug is precisely how mangled-UUID ghost summary
|
|
// pages (e.g. summary/…b171c…) get into the KB. Allow updating an
|
|
// existing summary page, but never fabricating a new one.
|
|
if existingPage == nil &&
|
|
(isSummaryNamespace(params.Slug) || strings.EqualFold(params.PageType, types.WikiPageTypeSummary)) {
|
|
return &types.ToolResult{
|
|
Success: false,
|
|
Error: "summary pages are generated automatically from source documents and cannot be created manually. " +
|
|
"Use page_type 'synthesis'/'comparison'/'entity'/'concept' for authored pages, " +
|
|
"or target an existing summary page to update it.",
|
|
}, nil
|
|
}
|
|
|
|
// Auto-repair dead [[slug]] references in the body before persisting.
|
|
// This rewrites LLM-mangled links (most importantly UUID-based summary
|
|
// slugs) back to their real target when a confident match exists, and
|
|
// leaves everything else untouched. Best-effort — never block the write.
|
|
if repaired, changed, rerr := t.wikiPageService.RepairContentLinks(ctx, kbID, params.Slug, params.Content); rerr == nil && changed {
|
|
params.Content = repaired
|
|
}
|
|
|
|
resolvedRefs := resolveSourceRefs(ctx, t.knowledgeService, params.SourceRefs)
|
|
|
|
var action string
|
|
if existingPage != nil {
|
|
// Update
|
|
existingPage.Title = params.Title
|
|
existingPage.Summary = params.Summary
|
|
existingPage.Content = params.Content
|
|
existingPage.PageType = params.PageType
|
|
existingPage.Aliases = params.Aliases
|
|
|
|
if len(resolvedRefs) > 0 {
|
|
existingPage.SourceRefs = resolvedRefs
|
|
}
|
|
|
|
_, err = t.wikiPageService.UpdatePage(ctx, existingPage)
|
|
if err != nil {
|
|
return &types.ToolResult{Success: false, Error: "Failed to update page: " + err.Error()}, nil
|
|
}
|
|
action = "updated"
|
|
} else {
|
|
// Create
|
|
newPage := &types.WikiPage{
|
|
KnowledgeBaseID: kbID,
|
|
Slug: params.Slug,
|
|
Title: params.Title,
|
|
Summary: params.Summary,
|
|
Content: params.Content,
|
|
PageType: params.PageType,
|
|
Aliases: params.Aliases,
|
|
SourceRefs: resolvedRefs,
|
|
}
|
|
_, err = t.wikiPageService.CreatePage(ctx, newPage)
|
|
if err != nil {
|
|
return &types.ToolResult{Success: false, Error: "Failed to create page: " + err.Error()}, nil
|
|
}
|
|
action = "created"
|
|
}
|
|
|
|
// Inject cross-links so other pages know about this new/updated entity
|
|
t.wikiPageService.InjectCrossLinks(ctx, kbID, []string{params.Slug})
|
|
|
|
// Rebuild the index page to reflect the new/updated summary
|
|
_ = t.wikiPageService.RebuildIndexPage(ctx, kbID)
|
|
|
|
output := fmt.Sprintf("Successfully %s page [[%s]].\n- Title: %s\n- Type: %s\n- Summary: %s\n- Content length: %d chars", action, params.Slug, params.Title, params.PageType, params.Summary, len(params.Content))
|
|
if len(params.Aliases) > 0 {
|
|
output += fmt.Sprintf("\n- Aliases: %s", strings.Join(params.Aliases, ", "))
|
|
}
|
|
if len(resolvedRefs) > 0 {
|
|
output += fmt.Sprintf("\n- Source refs: %d document(s)", len(resolvedRefs))
|
|
}
|
|
|
|
return &types.ToolResult{
|
|
Success: true,
|
|
Output: output,
|
|
Data: map[string]interface{}{
|
|
"display_type": "wiki_write_page",
|
|
"action": action,
|
|
"slug": params.Slug,
|
|
"title": params.Title,
|
|
"page_type": params.PageType,
|
|
"summary": params.Summary,
|
|
},
|
|
}, nil
|
|
}
|
|
|
|
// normalizeAndValidateWikiSlug lowercases + trims a model-supplied slug and
|
|
// rejects malformed ones. A valid slug contains only lowercase ASCII letters,
|
|
// digits, '-', '/', or CJK characters, has no leading/trailing/duplicate '/',
|
|
// and is non-empty. Keeping this strict stops the agent from persisting
|
|
// unreachable pages built from stray characters or garbled identifiers.
|
|
func normalizeAndValidateWikiSlug(raw string) (string, error) {
|
|
s := strings.ToLower(strings.TrimSpace(raw))
|
|
s = strings.ReplaceAll(s, " ", "-")
|
|
if s == "" {
|
|
return "", errors.New("slug is required and must be non-empty")
|
|
}
|
|
if strings.Contains(s, "//") || strings.HasPrefix(s, "/") || strings.HasSuffix(s, "/") {
|
|
return "", fmt.Errorf("invalid slug %q: '/' separators are malformed", raw)
|
|
}
|
|
for _, r := range s {
|
|
switch {
|
|
case r >= 'a' && r <= 'z', r >= '0' && r <= '9', r == '-', r == '/':
|
|
case r >= 0x4E00 && r <= 0x9FFF: // keep CJK characters
|
|
default:
|
|
return "", fmt.Errorf(
|
|
"invalid slug %q: character %q is not allowed (use lowercase letters, digits, '-', '/', or CJK)",
|
|
raw, string(r),
|
|
)
|
|
}
|
|
}
|
|
return s, nil
|
|
}
|
|
|
|
// isSummaryNamespace reports whether a slug lives in the system-owned summary
|
|
// namespace (summary/…).
|
|
func isSummaryNamespace(slug string) bool {
|
|
return strings.HasPrefix(slug, types.WikiPageTypeSummary+"/")
|
|
}
|