e147209e77
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>
320 lines
11 KiB
Markdown
320 lines
11 KiB
Markdown
# 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:**
|
|
```go
|
|
// 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.
|
|
|
|
### 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.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:**
|
|
```go
|
|
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)
|
|
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
|
|
|
|
---
|
|
|
|
## 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
|
|
```bash
|
|
# 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
|
|
```bash
|
|
# 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/`
|
|
|