c5494f612b
- Introduced UpdateAutoLinkedContent method to persist changes from machine-only link decorators without incrementing the version number, ensuring user-facing revisions remain consistent. - Updated existing methods to utilize the new auto-linked content update logic, enhancing the handling of cross-link injection and dead-link cleanup. - Enhanced the KnowledgeBase and WikiBrowser components to improve user experience during wiki operations, including status tracking and indexing indicators. - Added scheduling for wiki status probes to provide timely feedback on indexing processes after user-triggered actions.
399 lines
11 KiB
Go
399 lines
11 KiB
Go
package service
|
|
|
|
import (
|
|
"context"
|
|
"fmt"
|
|
"strings"
|
|
|
|
"github.com/Tencent/WeKnora/internal/logger"
|
|
"github.com/Tencent/WeKnora/internal/types"
|
|
"github.com/Tencent/WeKnora/internal/types/interfaces"
|
|
)
|
|
|
|
// WikiLintIssueType defines the type of lint issue
|
|
type WikiLintIssueType string
|
|
|
|
const (
|
|
LintIssueOrphanPage WikiLintIssueType = "orphan_page"
|
|
LintIssueBrokenLink WikiLintIssueType = "broken_link"
|
|
LintIssueStaleRef WikiLintIssueType = "stale_ref"
|
|
LintIssueMissingCrossRef WikiLintIssueType = "missing_cross_ref"
|
|
LintIssueEmptyContent WikiLintIssueType = "empty_content"
|
|
LintIssueDuplicateSlug WikiLintIssueType = "duplicate_slug"
|
|
)
|
|
|
|
// WikiLintIssueSeverity defines the severity of a lint issue
|
|
type WikiLintIssueSeverity string
|
|
|
|
const (
|
|
SeverityInfo WikiLintIssueSeverity = "info"
|
|
SeverityWarning WikiLintIssueSeverity = "warning"
|
|
SeverityError WikiLintIssueSeverity = "error"
|
|
)
|
|
|
|
// WikiLintIssue represents a single lint finding
|
|
type WikiLintIssue struct {
|
|
Type WikiLintIssueType `json:"type"`
|
|
Severity WikiLintIssueSeverity `json:"severity"`
|
|
PageSlug string `json:"page_slug"`
|
|
// TargetSlug identifies the other page involved in the issue (e.g. the
|
|
// broken link target, or the entity slug for a missing cross-ref). It is
|
|
// the structured field used by AutoFix instead of parsing Description.
|
|
TargetSlug string `json:"target_slug,omitempty"`
|
|
Description string `json:"description"`
|
|
AutoFixable bool `json:"auto_fixable"`
|
|
}
|
|
|
|
// WikiLintReport is the complete lint report for a wiki KB
|
|
type WikiLintReport struct {
|
|
KnowledgeBaseID string `json:"knowledge_base_id"`
|
|
Issues []WikiLintIssue `json:"issues"`
|
|
HealthScore int `json:"health_score"` // 0-100
|
|
Stats *types.WikiStats `json:"stats"`
|
|
Summary string `json:"summary"`
|
|
}
|
|
|
|
// WikiLintService provides wiki health checking capabilities
|
|
type WikiLintService struct {
|
|
wikiService interfaces.WikiPageService
|
|
kbService interfaces.KnowledgeBaseService
|
|
knowledgeService interfaces.KnowledgeService
|
|
}
|
|
|
|
// NewWikiLintService creates a new wiki lint service
|
|
func NewWikiLintService(
|
|
wikiService interfaces.WikiPageService,
|
|
kbService interfaces.KnowledgeBaseService,
|
|
knowledgeService interfaces.KnowledgeService,
|
|
) *WikiLintService {
|
|
return &WikiLintService{
|
|
wikiService: wikiService,
|
|
kbService: kbService,
|
|
knowledgeService: knowledgeService,
|
|
}
|
|
}
|
|
|
|
// RunLint performs a comprehensive health check on a wiki knowledge base
|
|
func (s *WikiLintService) RunLint(ctx context.Context, kbID string) (*WikiLintReport, error) {
|
|
// Validate KB
|
|
kb, err := s.kbService.GetKnowledgeBaseByIDOnly(ctx, kbID)
|
|
if err != nil {
|
|
return nil, fmt.Errorf("get KB: %w", err)
|
|
}
|
|
if !kb.IsWikiEnabled() {
|
|
return nil, fmt.Errorf("KB %s is not a wiki type", kbID)
|
|
}
|
|
|
|
// Get stats
|
|
stats, err := s.wikiService.GetStats(ctx, kbID)
|
|
if err != nil {
|
|
return nil, fmt.Errorf("get stats: %w", err)
|
|
}
|
|
|
|
// Get graph for link analysis
|
|
graph, err := s.wikiService.GetGraph(ctx, kbID)
|
|
if err != nil {
|
|
return nil, fmt.Errorf("get graph: %w", err)
|
|
}
|
|
|
|
// Get all pages for detailed analysis
|
|
resp, err := s.wikiService.ListPages(ctx, &types.WikiPageListRequest{
|
|
KnowledgeBaseID: kbID,
|
|
PageSize: 500,
|
|
})
|
|
if err != nil {
|
|
return nil, fmt.Errorf("list pages: %w", err)
|
|
}
|
|
|
|
var issues []WikiLintIssue
|
|
healthScore := 100
|
|
|
|
// Build slug set for link validation
|
|
slugSet := make(map[string]bool)
|
|
for _, node := range graph.Nodes {
|
|
slugSet[node.Slug] = true
|
|
}
|
|
|
|
// Check 1: Orphan pages (no inbound links, excluding index/log)
|
|
for _, page := range resp.Pages {
|
|
if page.PageType == types.WikiPageTypeIndex || page.PageType == types.WikiPageTypeLog {
|
|
continue
|
|
}
|
|
if len(page.InLinks) == 0 {
|
|
issues = append(issues, WikiLintIssue{
|
|
Type: LintIssueOrphanPage,
|
|
Severity: SeverityWarning,
|
|
PageSlug: page.Slug,
|
|
Description: fmt.Sprintf("Page '%s' has no inbound links — it's disconnected from the wiki", page.Title),
|
|
AutoFixable: false,
|
|
})
|
|
}
|
|
}
|
|
|
|
// Check 2: Broken links
|
|
for _, page := range resp.Pages {
|
|
for _, outLink := range page.OutLinks {
|
|
if !slugSet[outLink] {
|
|
issues = append(issues, WikiLintIssue{
|
|
Type: LintIssueBrokenLink,
|
|
Severity: SeverityError,
|
|
PageSlug: page.Slug,
|
|
TargetSlug: outLink,
|
|
Description: fmt.Sprintf("Page '%s' links to [[%s]] which does not exist", page.Title, outLink),
|
|
AutoFixable: true,
|
|
})
|
|
}
|
|
}
|
|
}
|
|
|
|
// Check 3: Empty content
|
|
for _, page := range resp.Pages {
|
|
content := strings.TrimSpace(page.Content)
|
|
if len(content) < 50 {
|
|
issues = append(issues, WikiLintIssue{
|
|
Type: LintIssueEmptyContent,
|
|
Severity: SeverityWarning,
|
|
PageSlug: page.Slug,
|
|
Description: fmt.Sprintf("Page '%s' has very little content (%d chars)", page.Title, len(content)),
|
|
AutoFixable: true,
|
|
})
|
|
}
|
|
}
|
|
|
|
// Check 4: Stale source refs — source_refs pointing at soft-deleted
|
|
// knowledge. This is the primary self-heal for the ingest/delete race
|
|
// condition: if a wiki_ingest task managed to slip past the in-flight
|
|
// guards and wrote a page for a knowledge that has since been deleted,
|
|
// the page becomes a dead-end (wiki_read_source_doc returns "knowledge
|
|
// not found"). Flag it so AutoFix can strip the ref, and delete the
|
|
// page if no live refs remain.
|
|
if s.knowledgeService != nil {
|
|
knowledgeLive := make(map[string]bool) // kid -> exists
|
|
for _, page := range resp.Pages {
|
|
// Skip wiki-intrinsic pages: index/log never carry SourceRefs
|
|
// anyway, and accidentally flagging them would risk AutoFix
|
|
// deleting system pages.
|
|
if page.PageType == types.WikiPageTypeIndex || page.PageType == types.WikiPageTypeLog {
|
|
continue
|
|
}
|
|
for _, ref := range page.SourceRefs {
|
|
kid := ref
|
|
if i := strings.Index(ref, "|"); i > 0 {
|
|
kid = ref[:i]
|
|
}
|
|
if kid == "" {
|
|
continue
|
|
}
|
|
live, seen := knowledgeLive[kid]
|
|
if !seen {
|
|
kn, err := s.knowledgeService.GetKnowledgeByIDOnly(ctx, kid)
|
|
live = err == nil && kn != nil
|
|
knowledgeLive[kid] = live
|
|
}
|
|
if !live {
|
|
issues = append(issues, WikiLintIssue{
|
|
Type: LintIssueStaleRef,
|
|
Severity: SeverityError,
|
|
PageSlug: page.Slug,
|
|
TargetSlug: kid,
|
|
Description: fmt.Sprintf("Page '%s' references deleted knowledge %s", page.Title, kid),
|
|
AutoFixable: true,
|
|
})
|
|
}
|
|
}
|
|
}
|
|
}
|
|
|
|
// Check 5: Missing cross-references (entities mentioned in content but not linked)
|
|
entitySlugs := make(map[string]string) // slug -> title
|
|
for _, page := range resp.Pages {
|
|
if page.PageType == types.WikiPageTypeEntity || page.PageType == types.WikiPageTypeConcept {
|
|
entitySlugs[page.Slug] = page.Title
|
|
}
|
|
}
|
|
for _, page := range resp.Pages {
|
|
for slug, title := range entitySlugs {
|
|
if slug == page.Slug {
|
|
continue
|
|
}
|
|
// Check if title is mentioned in content but not linked
|
|
if strings.Contains(strings.ToLower(page.Content), strings.ToLower(title)) {
|
|
linked := false
|
|
for _, l := range page.OutLinks {
|
|
if l == slug {
|
|
linked = true
|
|
break
|
|
}
|
|
}
|
|
if !linked {
|
|
issues = append(issues, WikiLintIssue{
|
|
Type: LintIssueMissingCrossRef,
|
|
Severity: SeverityInfo,
|
|
PageSlug: page.Slug,
|
|
TargetSlug: slug,
|
|
Description: fmt.Sprintf("Page '%s' mentions '%s' but doesn't link to [[%s]]", page.Title, title, slug),
|
|
AutoFixable: false,
|
|
})
|
|
}
|
|
}
|
|
}
|
|
}
|
|
|
|
// Calculate health score
|
|
if stats.TotalPages > 0 {
|
|
// Penalize for orphans
|
|
orphanPct := float64(stats.OrphanCount) / float64(stats.TotalPages) * 100
|
|
if orphanPct > 50 {
|
|
healthScore -= 25
|
|
} else if orphanPct > 25 {
|
|
healthScore -= 10
|
|
}
|
|
|
|
// Penalize for broken links
|
|
brokenCount := 0
|
|
for _, issue := range issues {
|
|
if issue.Type == LintIssueBrokenLink {
|
|
brokenCount++
|
|
}
|
|
}
|
|
healthScore -= brokenCount * 5
|
|
|
|
// Penalize for no links at all
|
|
if stats.TotalLinks == 0 && stats.TotalPages > 2 {
|
|
healthScore -= 15
|
|
}
|
|
|
|
// Penalize for empty pages
|
|
emptyCount := 0
|
|
for _, issue := range issues {
|
|
if issue.Type == LintIssueEmptyContent {
|
|
emptyCount++
|
|
}
|
|
}
|
|
healthScore -= emptyCount * 3
|
|
}
|
|
|
|
if healthScore < 0 {
|
|
healthScore = 0
|
|
}
|
|
|
|
// Generate summary
|
|
var summary strings.Builder
|
|
errorCount := 0
|
|
warningCount := 0
|
|
infoCount := 0
|
|
for _, issue := range issues {
|
|
switch issue.Severity {
|
|
case SeverityError:
|
|
errorCount++
|
|
case SeverityWarning:
|
|
warningCount++
|
|
case SeverityInfo:
|
|
infoCount++
|
|
}
|
|
}
|
|
|
|
if len(issues) == 0 {
|
|
summary.WriteString("Wiki is healthy! No issues found.")
|
|
} else {
|
|
fmt.Fprintf(&summary, "Found %d issues: %d errors, %d warnings, %d suggestions.",
|
|
len(issues), errorCount, warningCount, infoCount)
|
|
}
|
|
|
|
report := &WikiLintReport{
|
|
KnowledgeBaseID: kbID,
|
|
Issues: issues,
|
|
HealthScore: healthScore,
|
|
Stats: stats,
|
|
Summary: summary.String(),
|
|
}
|
|
|
|
logger.Infof(ctx, "wiki lint: KB %s — health score %d/100, %d issues", kbID, healthScore, len(issues))
|
|
|
|
return report, nil
|
|
}
|
|
|
|
// AutoFix attempts to automatically fix fixable issues
|
|
func (s *WikiLintService) AutoFix(ctx context.Context, kbID string) (int, error) {
|
|
report, err := s.RunLint(ctx, kbID)
|
|
if err != nil {
|
|
return 0, err
|
|
}
|
|
|
|
fixed := 0
|
|
for _, issue := range report.Issues {
|
|
if !issue.AutoFixable {
|
|
continue
|
|
}
|
|
|
|
switch issue.Type {
|
|
case LintIssueBrokenLink:
|
|
// Replace [[broken-slug]] with plain text so the reference text is
|
|
// preserved but no longer renders as a dangling wiki link.
|
|
if issue.TargetSlug == "" {
|
|
continue
|
|
}
|
|
page, err := s.wikiService.GetPageBySlug(ctx, kbID, issue.PageSlug)
|
|
if err != nil {
|
|
continue
|
|
}
|
|
target := issue.TargetSlug
|
|
page.Content = strings.ReplaceAll(page.Content, "[["+target+"]]", target)
|
|
if err := s.wikiService.UpdateAutoLinkedContent(ctx, page); err == nil {
|
|
fixed++
|
|
}
|
|
|
|
case LintIssueEmptyContent:
|
|
// Archive pages with very little content instead of deleting
|
|
page, err := s.wikiService.GetPageBySlug(ctx, kbID, issue.PageSlug)
|
|
if err != nil {
|
|
continue
|
|
}
|
|
// Don't archive index or log pages
|
|
if page.PageType == types.WikiPageTypeIndex || page.PageType == types.WikiPageTypeLog {
|
|
continue
|
|
}
|
|
page.Status = types.WikiPageStatusArchived
|
|
if _, err := s.wikiService.UpdatePage(ctx, page); err == nil {
|
|
fixed++
|
|
}
|
|
|
|
case LintIssueStaleRef:
|
|
// Strip source_refs that point at soft-deleted knowledge. If the
|
|
// page has no other live sources, delete it outright — leaving
|
|
// an orphan summary page is worse than removing it, because the
|
|
// model would still link to it from other pages and the
|
|
// wiki_read_source_doc drill-down would always fail.
|
|
if issue.TargetSlug == "" {
|
|
continue
|
|
}
|
|
page, err := s.wikiService.GetPageBySlug(ctx, kbID, issue.PageSlug)
|
|
if err != nil || page == nil {
|
|
continue
|
|
}
|
|
if page.PageType == types.WikiPageTypeIndex || page.PageType == types.WikiPageTypeLog {
|
|
continue
|
|
}
|
|
remaining := removeSourceRef(page.SourceRefs, issue.TargetSlug)
|
|
if len(remaining) == 0 {
|
|
if err := s.wikiService.DeletePage(ctx, kbID, page.Slug); err == nil {
|
|
fixed++
|
|
}
|
|
} else if len(remaining) != len(page.SourceRefs) {
|
|
page.SourceRefs = remaining
|
|
if err := s.wikiService.UpdatePageMeta(ctx, page); err == nil {
|
|
fixed++
|
|
}
|
|
}
|
|
}
|
|
}
|
|
|
|
// Rebuild links after fixes
|
|
if fixed > 0 {
|
|
_ = s.wikiService.RebuildLinks(ctx, kbID)
|
|
}
|
|
|
|
logger.Infof(ctx, "wiki auto-fix: KB %s — fixed %d issues", kbID, fixed)
|
|
return fixed, nil
|
|
}
|