Files
Enterprise-Knowledge-Base/ANALYSIS_SUMMARY.md
T
wizardchen e147209e77 feat: Implement comprehensive wiki feature for knowledge bases
This commit introduces the complete wiki feature for WeKnora, enabling AI-powered wiki page generation and management. The implementation includes:

**Backend Changes:**
- Wiki data model: WikiPage type with support for multiple page types (Summary, Entity, Concept, Index, Log)
- Database schema: wiki_pages table with full migration support
- WikiPageService: CRUD operations and page management
- WikiPageRepository: GORM-based persistence layer
- Wiki ingest pipeline: Automated generation of wiki pages from knowledge documents
  * Summary page generation using LLM
  * Entity and concept extraction in a single LLM call
  * Synthesis opportunity detection
  * Index page rebuilding
  * Log page maintenance
- Wiki boost feature: Enhance chat retrieval with wiki context
- Wiki linting: Maintenance and validation utilities
- Agent wiki tools: Enable agents to query and interact with wiki pages
- Wiki prompts: Comprehensive LLM prompt templates for all wiki generation tasks
- Language support: Reuse existing middleware language infrastructure for LLM prompts

**Frontend Changes:**
- Wiki browser UI: View all wiki pages with filtering and search
- Wiki API client: Knowledge base wiki management endpoints
- Knowledge base editor: Configure wiki settings (language, auto-ingest, synthesis model)
- i18n updates: Support for English, Korean, Russian, and Chinese interfaces

**Configuration:**
- Container DI: Wire up all wiki services
- Router: Register wiki API endpoints
- Task handling: Support async wiki ingest tasks

**Testing:**
- Unit tests for wiki page types
- Service layer tests
- Endpoint tests for wiki operations
- Integration tests with LLM mocking

**Documentation:**
- Language refactoring analysis and guides
- Implementation completion reports
- Quick reference guides for developers

**Key Features:**
✅ LLM-powered wiki page generation from documents
✅ Multi-language support (9+ languages)
✅ Automatic extraction of entities and concepts
✅ Synthesis opportunity detection
✅ Index and log page maintenance
✅ Progressive wiki building across multiple documents
✅ Agent-based wiki interaction
✅ Chat retrieval enhancement with wiki context
✅ Full frontend UI for wiki browsing

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
2026-04-22 21:17:18 +08:00

11 KiB

WeKnora Agent & Language Infrastructure - Complete Analysis Summary

Generated: April 7, 2026 Status: Complete ✅


Executive Summary

This analysis addresses four key areas of the WeKnora codebase:

  1. Agent ReAct Engine Architecture - Understanding how tools are dispatched
  2. System Prompts - How the agent learns about available tools
  3. Wiki Tool Registration - Dynamic tool availability based on KB type
  4. Language Infrastructure Refactoring - Eliminating duplicate language logic

Key Findings

✅ Agent uses automatic tool dispatch - No user intervention needed, LLM decides tool usage ✅ Wiki tools conditionally registered - Only visible when wiki KBs are detected ✅ System prompts are generic - No dedicated wiki-specific prompt for the Agent ✅ Language infrastructure exists - Middleware contains reusable language mapping ❌ wiki_write_page not guaranteed - LLM must independently decide to use it ❌ Synthesis detection is heuristic - In ingest pipeline, not Agent loop


Document Overview

1. AGENT_WIKI_ANALYSIS.md (16 KB)

Purpose: Complete technical analysis of the Agent ReAct engine

Sections:

  • Agent ReAct Engine - Main Loop Architecture
  • Tool Dispatch Mechanism - Automatic, Not User-Triggered
  • System Prompts - Where Tools Are Described
  • Wiki Tool Registration - Conditional Based on KB Type
  • Wiki Tools Implementation - 5 Tools Overview
  • How the Agent Knows About Wiki Tools
  • Is There a Dedicated Wiki-Specific System Prompt? (Answer: NO)
  • Synthesis Detection - Where It Actually Happens
  • Complete Tool List and Filter Logic
  • Event-Driven Architecture
  • Summary Table

Key Code Files Referenced:

  • /internal/agent/engine.go - Core ReAct engine
  • /internal/agent/act.go - Tool dispatch
  • /internal/agent/prompts.go - System prompt building
  • /internal/agent/tools/wiki_tools.go - Wiki tool implementations
  • /internal/application/service/agent_service.go - Tool registration
  • /internal/application/service/wiki_ingest.go - Wiki ingest pipeline

2. LANGUAGE_MIDDLEWARE_ANALYSIS.md (11 KB)

Purpose: Identify and document existing language infrastructure

Sections:

  • Existing Language Middleware Infrastructure
  • Current Wiki Ingest Language Logic (NEEDS REFACTORING)
  • Refactoring Recommendations
  • Integration Points
  • Implementation Checklist
  • Additional Observations
  • Code Migration Path
  • Files Modified Summary

Key Functions Identified:

  • types.LanguageLocaleName() - 9+ language mapping (the solution!)
  • types.LanguageFromContext() - Extract language from context
  • types.DefaultLanguage() - Get configured default language
  • types.EnvLanguage() - Read WEKNORA_LANGUAGE env var
  • middleware.Language() - HTTP middleware for language extraction
  • middleware.parseFirstLanguageTag() - Parse Accept-Language header

3. REFACTORING_PLAN.md (6.3 KB)

Purpose: Detailed implementation plan for language refactoring

Sections:

  • Problem Statement
  • Solution Overview
  • Implementation Details (with code diffs)
  • Impact Analysis
  • Supported Languages (9+)
  • Backward Compatibility Analysis
  • Testing Recommendations
  • Future Enhancement Options
  • Implementation Steps (5 steps)
  • Rollback Plan

The One-Line Fix:

// Replace lines 135-141 in wiki_ingest.go with:
lang := types.LanguageLocaleName(kb.WikiConfig.WikiLanguage)

Benefits:

  • Reduces code from 6 lines to 1 line
  • Supports 9+ languages instead of 2
  • Eliminates code duplication
  • Improves maintainability
  • Fully backward compatible

4. LANGUAGE_REFACTORING_QUICK_REFERENCE.md (3.0 KB)

Purpose: Quick copy-paste guide for implementation

Sections:

  • TL;DR Summary
  • What to Change (exact location + code)
  • Key Benefits Table
  • Function Reference
  • Testing Instructions
  • Implementation Checklist

Perfect for: Developers implementing the refactoring quickly


Key Questions Answered

Q1: How does the Agent's ReAct engine dispatch tools?

Answer: Automatic and LLM-driven.

Evidence:

  • File: /internal/agent/engine.go - executeLoop() method (lines 260-394)
  • File: /internal/agent/act.go - executeToolCalls() function (lines 68-89)
  • Tools are called automatically after LLM response without user intervention
  • Max 5 iterations per query, each iteration: Think → Analyze → Act → Observe

Key Detail: Tool execution is triggered by LLM decision, not user action.

Q2: What system prompts does the Agent use?

Answer: Generic RAG or Pure Agent templates, no dedicated wiki prompt.

Evidence:

  • File: /internal/agent/prompts.go - BuildSystemPromptWithOptions() (lines 315-360)
  • Two templates:
    • GetPureAgentSystemPrompt() - For no knowledge bases
    • GetProgressiveRAGSystemPrompt() - For knowledge bases
  • Placeholders: {{knowledge_bases}}, {{web_search_status}}, {{current_time}}, {{language}}
  • Wiki-specific prompts are in prompts_wiki.go but used only by ingest pipeline, not Agent

Q3: How does the Agent know about wiki tools?

Answer: Via conditional registration based on KB type detection.

Evidence:

  • File: /internal/application/service/agent_service.go - registerTools() (lines 316-477)
  • Lines 370-389: Iterate search targets, detect wiki KBs by type
  • If wiki KBs found → automatically add 5 wiki tools to allowed tools list
  • Tools then passed to LLM via buildToolsForLLM() in /internal/agent/observe.go

Key Detail: Wiki tools only visible if wiki KBs are in search targets.

Answer: NO. There is no such prompt.

Evidence:

  • Searched prompts.go - no wiki-specific system prompt
  • Wiki prompts in prompts_wiki.go are for ingest pipeline only, not Agent loop
  • Tool description is minimal (lines 91-92 in wiki_tools.go)
  • Agent decides to use wiki_write_page based on general reasoning, not explicit instruction

Implication: wiki_write_page is NOT guaranteed to be called - LLM must independently decide it's appropriate.

Q5: Can the wiki language logic be refactored?

Answer: YES, completely. Reuse types.LanguageLocaleName().

Current Issue:

  • wiki_ingest.go lines 135-141 contain hardcoded language mapping (2 languages only)
  • types.LanguageLocaleName() (lines 85-112 in context_helpers.go) already does this (9+ languages)
  • Duplicated logic, inconsistent naming, hard to extend

Solution:

lang := types.LanguageLocaleName(kb.WikiConfig.WikiLanguage)

Benefits:

  • 6 lines → 1 line (83% reduction)
  • 2 languages → 9+ languages
  • Consistent with middleware naming
  • Centralized maintenance
  • Fully backward compatible

Immediate (Next Sprint)

  1. ✅ Review AGENT_WIKI_ANALYSIS.md for understanding Agent architecture
  2. ✅ Review LANGUAGE_MIDDLEWARE_ANALYSIS.md for language infrastructure
  3. 🔄 Plan refactoring sprint using REFACTORING_PLAN.md

Short-term (1-2 weeks)

  1. 🔄 Implement language refactoring using LANGUAGE_REFACTORING_QUICK_REFERENCE.md
    • Edit 1 file, 6 lines → 1 line
    • Run existing tests
    • Commit and merge
    • Time estimate: 30 minutes

Medium-term (Optional Enhancements)

  1. Add support for context-aware language fallback (use context language if KB language empty)
  2. Normalize WikiLanguage storage format from short codes to full locales
  3. Audit codebase for other hardcoded language mappings

Long-term (Architectural)

  1. Document language handling best practices
  2. Consider similar refactorings for other duplicated logic
  3. Expand language support based on user demand

Analysis Documents

Document Size Purpose
AGENT_WIKI_ANALYSIS.md 16 KB Complete Agent architecture analysis
LANGUAGE_MIDDLEWARE_ANALYSIS.md 11 KB Language infrastructure deep dive
REFACTORING_PLAN.md 6.3 KB Detailed implementation plan
LANGUAGE_REFACTORING_QUICK_REFERENCE.md 3 KB Quick copy-paste guide
ANALYSIS_SUMMARY.md This file Executive overview

Code Files Referenced

Agent Engine:

  • /internal/agent/engine.go - ReAct loop implementation
  • /internal/agent/act.go - Tool execution
  • /internal/agent/observe.go - Tool visibility
  • /internal/agent/think.go - LLM invocation
  • /internal/agent/prompts.go - System prompt building

Tools:

  • /internal/agent/tools/wiki_tools.go - 5 wiki tool implementations
  • /internal/agent/tools/definitions.go - Tool metadata

Services:

  • /internal/application/service/agent_service.go - Tool registration
  • /internal/application/service/wiki_ingest.go - Wiki ingest pipeline (to be refactored)

Infrastructure:

  • /internal/middleware/language.go - Language extraction middleware
  • /internal/types/context_helpers.go - Language helpers (LanguageLocaleName function)
  • /internal/types/const.go - Context key definitions

Testing Recommendations

Unit Tests

# Test language mapping
go test -v ./internal/types -run TestLanguageLocaleName

# Test agent engine
go test -v ./internal/agent -run TestEngine

# Test wiki ingest (after refactoring)
go test -v ./internal/application/service -run TestWikiIngest

Integration Tests

# Full test suite
go test -v ./internal/...

Manual Testing (After Refactoring)

  1. Create wiki KB with WikiLanguage: "zh" → Verify Chinese output
  2. Create wiki KB with WikiLanguage: "en" → Verify English output
  3. Create wiki KB with WikiLanguage: "ko" → Verify Korean output (new!)
  4. Create wiki KB with WikiLanguage: "unknown" → Verify graceful fallback

Glossary

ReAct: Reasoning + Acting - LLM loop that reasons about problems and invokes tools Progressive RAG: Retrieval-Augmented Generation mode with knowledge bases Pure Agent: Mode with no knowledge bases Tool Registry: Central registry holding all available tools Automatic Tool Dispatch: Tools are executed by engine when LLM decides, without user confirmation Synthesis Detection: Heuristic that counts page types and suggests synthesis opportunities EventBus: Event-driven system for UI feedback


Contact & Follow-up

Questions about analysis? Review the specific document sections above.

Ready to implement? Start with LANGUAGE_REFACTORING_QUICK_REFERENCE.md.

Need more details? Each major document section has code snippets and file references.


Version History

Version Date Changes
1.0 2026-04-07 Initial analysis and documentation

End of Summary

All documents are located in /Users/wizard/code/go/src/git.woa.com/wxg-prc/WeKnora/