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>
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:
- Agent ReAct Engine Architecture - Understanding how tools are dispatched
- System Prompts - How the agent learns about available tools
- Wiki Tool Registration - Dynamic tool availability based on KB type
- 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 contexttypes.DefaultLanguage()- Get configured default languagetypes.EnvLanguage()- Read WEKNORA_LANGUAGE env varmiddleware.Language()- HTTP middleware for language extractionmiddleware.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 basesGetProgressiveRAGSystemPrompt()- For knowledge bases
- Placeholders:
{{knowledge_bases}},{{web_search_status}},{{current_time}},{{language}} - Wiki-specific prompts are in
prompts_wiki.gobut 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.
Q4: Is there a dedicated wiki-related system prompt for the Agent?
Answer: NO. There is no such prompt.
Evidence:
- Searched
prompts.go- no wiki-specific system prompt - Wiki prompts in
prompts_wiki.goare for ingest pipeline only, not Agent loop - Tool description is minimal (lines 91-92 in
wiki_tools.go) - Agent decides to use
wiki_write_pagebased 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.golines 135-141 contain hardcoded language mapping (2 languages only)types.LanguageLocaleName()(lines 85-112 incontext_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
Recommended Actions
Immediate (Next Sprint)
- ✅ Review
AGENT_WIKI_ANALYSIS.mdfor understanding Agent architecture - ✅ Review
LANGUAGE_MIDDLEWARE_ANALYSIS.mdfor language infrastructure - 🔄 Plan refactoring sprint using
REFACTORING_PLAN.md
Short-term (1-2 weeks)
- 🔄 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)
- Add support for context-aware language fallback (use context language if KB language empty)
- Normalize
WikiLanguagestorage format from short codes to full locales - Audit codebase for other hardcoded language mappings
Long-term (Architectural)
- Document language handling best practices
- Consider similar refactorings for other duplicated logic
- Expand language support based on user demand
File Locations & Quick Links
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)
- Create wiki KB with WikiLanguage: "zh" → Verify Chinese output
- Create wiki KB with WikiLanguage: "en" → Verify English output
- Create wiki KB with WikiLanguage: "ko" → Verify Korean output (new!)
- 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/