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>
428 lines
13 KiB
Markdown
428 lines
13 KiB
Markdown
# WeKnora Analysis & Refactoring Documentation
|
|
|
|
**Complete Analysis Date:** April 7, 2026
|
|
**Total Documentation:** 1,475 lines across 5 documents
|
|
**Status:** ✅ Complete and Ready for Implementation
|
|
|
|
---
|
|
|
|
## 📚 Documentation Index
|
|
|
|
Start here to understand what's been analyzed and what to do next.
|
|
|
|
### 🎯 Quick Navigation
|
|
|
|
**Just want the main findings?** → Read [`ANALYSIS_SUMMARY.md`](#analysissummarymd) (5 min read)
|
|
|
|
**Want implementation details?** → Read [`LANGUAGE_REFACTORING_QUICK_REFERENCE.md`](#language-refactoring-quick-referencemd) (2 min read)
|
|
|
|
**Need deep technical understanding?** → Read [`AGENT_WIKI_ANALYSIS.md`](#agent-wiki-analysismd) (20 min read)
|
|
|
|
**Planning full refactoring?** → Read [`REFACTORING_PLAN.md`](#refactoring-planmd) (10 min read)
|
|
|
|
**Want complete language infrastructure map?** → Read [`LANGUAGE_MIDDLEWARE_ANALYSIS.md`](#language-middleware-analysismd) (15 min read)
|
|
|
|
---
|
|
|
|
## 📖 Documents
|
|
|
|
### 1. **ANALYSIS_SUMMARY.md**
|
|
**Size:** 11 KB | **Lines:** 319 | **Read Time:** 5-10 minutes
|
|
|
|
**Overview:** Executive summary answering all four key questions about the WeKnora Agent and language infrastructure.
|
|
|
|
**Contains:**
|
|
- Executive summary with key findings
|
|
- Document overview (purpose of each analysis doc)
|
|
- Five key questions answered:
|
|
- How does the Agent's ReAct engine dispatch tools?
|
|
- What system prompts does the Agent use?
|
|
- How does the Agent know about wiki tools?
|
|
- Is there a dedicated wiki-specific system prompt for the Agent?
|
|
- Can the wiki language logic be refactored?
|
|
- Recommended actions (immediate, short-term, medium-term, long-term)
|
|
- File locations and quick links
|
|
- Testing recommendations
|
|
- Glossary
|
|
|
|
**Best for:** Project managers, decision makers, technical leads needing quick overview
|
|
|
|
**Start here first if:** You need the high-level picture
|
|
|
|
---
|
|
|
|
### 2. **AGENT_WIKI_ANALYSIS.md**
|
|
**Size:** 16 KB | **Lines:** 492 | **Read Time:** 15-20 minutes
|
|
|
|
**Overview:** Complete technical deep-dive into the Agent ReAct engine architecture and wiki tool integration.
|
|
|
|
**Sections:**
|
|
1. Agent ReAct Engine - Main Loop Architecture
|
|
2. Tool Dispatch Mechanism - Automatic, Not User-Triggered
|
|
3. System Prompts - Where Tools Are Described
|
|
4. Wiki Tool Registration - Conditional Based on KB Type
|
|
5. Wiki Tools Implementation (5 tools overview)
|
|
6. How the Agent Knows About Wiki Tools
|
|
7. Is There a Dedicated Wiki-Specific System Prompt? (NO!)
|
|
8. Synthesis Detection - Where It Actually Happens
|
|
9. Complete Tool List and Filter Logic
|
|
10. Event-Driven Architecture
|
|
11. Summary Table
|
|
|
|
**Key Code Files:**
|
|
- `/internal/agent/engine.go` - Core ReAct engine
|
|
- `/internal/agent/act.go` - Tool execution
|
|
- `/internal/application/service/agent_service.go` - Tool registration
|
|
- `/internal/application/service/wiki_ingest.go` - Wiki ingest
|
|
|
|
**Best for:** Developers implementing Agent features, architecture understanding
|
|
|
|
**Start here if:** You need to understand how the Agent works internally
|
|
|
|
---
|
|
|
|
### 3. **LANGUAGE_MIDDLEWARE_ANALYSIS.md**
|
|
**Size:** 11 KB | **Lines:** 349 | **Read Time:** 10-15 minutes
|
|
|
|
**Overview:** Identifies and documents the complete language infrastructure and refactoring opportunity.
|
|
|
|
**Sections:**
|
|
1. Existing Language Middleware Infrastructure
|
|
- HTTP middleware for language extraction
|
|
- HTTP header parsing
|
|
- Environment variable support
|
|
2. Current Wiki Ingest Language Logic (NEEDS REFACTORING)
|
|
- Shows the 6 lines of hardcoded language mapping
|
|
- Identifies problems
|
|
3. Refactoring Recommendations
|
|
- One-line solution using existing infrastructure
|
|
4. Integration Points
|
|
5. Implementation Checklist
|
|
6. Additional Observations
|
|
7. Code Migration Path
|
|
8. Files Modified Summary
|
|
|
|
**Key Functions Identified:**
|
|
- `types.LanguageLocaleName()` - THE SOLUTION (supports 9+ languages)
|
|
- `types.LanguageFromContext()`
|
|
- `types.DefaultLanguage()`
|
|
- `types.EnvLanguage()`
|
|
- `middleware.Language()`
|
|
- `middleware.parseFirstLanguageTag()`
|
|
|
|
**Best for:** Developers implementing language refactoring
|
|
|
|
**Start here if:** You want to understand language handling
|
|
|
|
---
|
|
|
|
### 4. **REFACTORING_PLAN.md**
|
|
**Size:** 6.3 KB | **Lines:** 204 | **Read Time:** 8-12 minutes
|
|
|
|
**Overview:** Detailed implementation plan with code diffs, impact analysis, and testing strategy.
|
|
|
|
**Sections:**
|
|
1. Problem Statement
|
|
2. Solution Overview
|
|
3. Implementation Details
|
|
- Change location (exact file and lines)
|
|
- Before/after code with diffs
|
|
- Verification checklist
|
|
4. Impact Analysis
|
|
- Benefits summary
|
|
- Supported languages table (9+)
|
|
- Backward compatibility
|
|
5. Testing Recommendations
|
|
- Test cases
|
|
- Integration testing
|
|
6. Future Enhancements
|
|
- Option 1: Full locale code normalization
|
|
- Option 2: Context-aware language selection
|
|
7. Implementation Steps (5 steps)
|
|
8. Rollback Plan
|
|
|
|
**The Core Change:**
|
|
```go
|
|
// Before: 6 lines of hardcoded logic
|
|
lang := "the same language as the source document"
|
|
if kb.WikiConfig.WikiLanguage == "zh" {
|
|
lang = "Chinese (中文)"
|
|
} else if kb.WikiConfig.WikiLanguage == "en" {
|
|
lang = "English"
|
|
}
|
|
|
|
// After: 1 line using existing infrastructure
|
|
lang := types.LanguageLocaleName(kb.WikiConfig.WikiLanguage)
|
|
```
|
|
|
|
**Best for:** Project leads planning the implementation
|
|
|
|
**Start here if:** You're planning the refactoring sprint
|
|
|
|
---
|
|
|
|
### 5. **LANGUAGE_REFACTORING_QUICK_REFERENCE.md**
|
|
**Size:** 3.0 KB | **Lines:** 111 | **Read Time:** 2-3 minutes
|
|
|
|
**Overview:** Quick copy-paste implementation guide for developers.
|
|
|
|
**Sections:**
|
|
1. TL;DR Summary
|
|
2. What to Change (exact location + code)
|
|
3. Key Benefits Table
|
|
4. No Breaking Changes
|
|
5. Function Reference
|
|
- Function signature
|
|
- Location
|
|
- All supported inputs
|
|
6. Testing Instructions
|
|
7. Related Documentation
|
|
8. Files Involved Table
|
|
9. Implementation Checklist (6 steps)
|
|
|
|
**Perfect for:** Developers ready to implement now
|
|
|
|
**Start here if:** You want to implement immediately and don't want to read long docs
|
|
|
|
---
|
|
|
|
## 🚀 Implementation Roadmap
|
|
|
|
### Phase 1: Understanding (Completed ✅)
|
|
- [x] Agent ReAct engine architecture documented
|
|
- [x] Tool registration and dispatch mechanism documented
|
|
- [x] System prompts analyzed
|
|
- [x] Language infrastructure identified
|
|
- [x] Refactoring opportunity identified
|
|
|
|
### Phase 2: Planning (Ready for Decision)
|
|
- [ ] Review ANALYSIS_SUMMARY.md
|
|
- [ ] Review REFACTORING_PLAN.md
|
|
- [ ] Decide on quick fix vs full refactoring
|
|
- [ ] Schedule implementation sprint
|
|
|
|
### Phase 3: Implementation (Ready to Start)
|
|
- [ ] Use LANGUAGE_REFACTORING_QUICK_REFERENCE.md
|
|
- [ ] Make one-line change in wiki_ingest.go
|
|
- [ ] Run tests
|
|
- [ ] Verify backward compatibility
|
|
- [ ] Commit and merge
|
|
|
|
### Phase 4: Enhancement (Optional)
|
|
- [ ] Consider full locale code normalization
|
|
- [ ] Add context-aware language fallback
|
|
- [ ] Audit for other hardcoded language mappings
|
|
|
|
---
|
|
|
|
## ✅ Key Findings Summary
|
|
|
|
### Agent Architecture
|
|
✅ **Automatic Tool Dispatch** - LLM decides tool usage, not user-driven
|
|
✅ **Conditional Registration** - Wiki tools only visible if wiki KBs detected
|
|
✅ **Event-Driven** - All actions emit events for UI feedback
|
|
✅ **Configurable** - Max iterations, knowledge bases, web search all configurable
|
|
|
|
### System Prompts
|
|
✅ **Generic Templates** - RAG and Pure Agent modes
|
|
❌ **No Dedicated Wiki Prompt** - Wiki tools described minimally in tool definitions
|
|
❌ **wiki_write_page Not Guaranteed** - LLM must independently decide
|
|
|
|
### Language Infrastructure
|
|
✅ **Middleware Exists** - Language extraction from HTTP headers
|
|
✅ **Reusable Functions** - `LanguageLocaleName()` supports 9+ languages
|
|
❌ **Duplicated Logic** - wiki_ingest.go has hardcoded language mapping
|
|
❌ **Limited Coverage** - Current code only supports 2 languages
|
|
|
|
### Refactoring Opportunity
|
|
✅ **Low Risk** - Fully backward compatible
|
|
✅ **High Impact** - 6 lines → 1 line, 2 languages → 9+
|
|
✅ **Easy Implementation** - Single one-line change
|
|
✅ **Quick Testing** - Reuses existing test infrastructure
|
|
|
|
---
|
|
|
|
## 🔧 Implementation Quick Start
|
|
|
|
### If You Have 2 Minutes
|
|
1. Read `LANGUAGE_REFACTORING_QUICK_REFERENCE.md`
|
|
2. Make the one-line change
|
|
3. Run tests
|
|
4. Done ✅
|
|
|
|
### If You Have 30 Minutes
|
|
1. Skim `ANALYSIS_SUMMARY.md`
|
|
2. Read `LANGUAGE_REFACTORING_QUICK_REFERENCE.md`
|
|
3. Review `REFACTORING_PLAN.md` implementation section
|
|
4. Implement change
|
|
5. Run full test suite
|
|
6. Commit with reference to documentation
|
|
7. Done ✅
|
|
|
|
### If You Have 1 Hour
|
|
1. Read `ANALYSIS_SUMMARY.md` (10 min)
|
|
2. Read `LANGUAGE_MIDDLEWARE_ANALYSIS.md` (15 min)
|
|
3. Read `REFACTORING_PLAN.md` (10 min)
|
|
4. Implement change (5 min)
|
|
5. Run tests and verify (15 min)
|
|
6. Document any learnings (5 min)
|
|
7. Done ✅
|
|
|
|
### If You Have 2+ Hours
|
|
1. Read all documents in order
|
|
2. Review source code references
|
|
3. Run tests with different configurations
|
|
4. Plan future enhancements
|
|
5. Document best practices for similar refactorings
|
|
6. Create internal wiki page on language handling
|
|
7. Done ✅
|
|
|
|
---
|
|
|
|
## 📝 Code Location Reference
|
|
|
|
### Where to Make Changes
|
|
- **File:** `/internal/application/service/wiki_ingest.go`
|
|
- **Method:** `ProcessWikiIngest()`
|
|
- **Lines:** 135-141
|
|
|
|
### Where Functions Are Defined
|
|
- **Function:** `/internal/types/context_helpers.go` lines 85-112
|
|
- **Middleware:** `/internal/middleware/language.go` lines 21-54
|
|
- **Constants:** `/internal/types/const.go` line 25
|
|
|
|
### Related Files (for context)
|
|
- `/internal/agent/engine.go` - ReAct engine
|
|
- `/internal/agent/tools/wiki_tools.go` - Wiki tools
|
|
- `/internal/application/service/agent_service.go` - Tool registration
|
|
|
|
---
|
|
|
|
## 🧪 Testing Strategy
|
|
|
|
### Before Implementation
|
|
```bash
|
|
cd /Users/wizard/code/go/src/git.woa.com/wxg-prc/WeKnora
|
|
go test -v ./internal/types
|
|
go test -v ./internal/application/service
|
|
```
|
|
|
|
### After Implementation
|
|
```bash
|
|
# Same tests should pass
|
|
go test -v ./internal/types
|
|
go test -v ./internal/application/service
|
|
|
|
# Optionally run full suite
|
|
go test -v ./internal/...
|
|
```
|
|
|
|
### Manual Verification
|
|
```go
|
|
// Should print: "Chinese (Simplified)"
|
|
fmt.Println(types.LanguageLocaleName("zh"))
|
|
|
|
// Should print: "English"
|
|
fmt.Println(types.LanguageLocaleName("en"))
|
|
|
|
// Should print: "Korean"
|
|
fmt.Println(types.LanguageLocaleName("ko"))
|
|
```
|
|
|
|
---
|
|
|
|
## 💡 Why This Matters
|
|
|
|
### Before Refactoring
|
|
- **Code Duplication** - Language logic repeated in multiple places
|
|
- **Limited Coverage** - Only 2 languages supported
|
|
- **Inconsistent Naming** - Different format than middleware
|
|
- **Hard to Extend** - Adding languages requires code changes
|
|
- **Maintenance Burden** - Changes needed in multiple places
|
|
|
|
### After Refactoring
|
|
- **Single Source of Truth** - Centralized language mapping
|
|
- **Full Coverage** - 9+ languages supported
|
|
- **Consistent Naming** - Aligns with middleware conventions
|
|
- **Easy Extension** - Add languages in one place
|
|
- **Lower Maintenance** - Changes benefit all components
|
|
|
|
---
|
|
|
|
## 📞 Questions & Answers
|
|
|
|
**Q: Will this break existing code?**
|
|
A: No. The refactoring is 100% backward compatible. Existing KB configs with "zh" and "en" continue to work exactly as before.
|
|
|
|
**Q: How long will implementation take?**
|
|
A: 2-30 minutes depending on thoroughness. The actual code change is 1 line, but testing and verification may take longer.
|
|
|
|
**Q: Do I need to migrate the database?**
|
|
A: No. The function handles both short codes ("zh", "en") and full locales ("zh-CN", "en-US") seamlessly.
|
|
|
|
**Q: What about new languages I might add later?**
|
|
A: Just add them to `LanguageLocaleName()` in `context_helpers.go`. No other changes needed.
|
|
|
|
**Q: Is this high priority?**
|
|
A: Medium priority. It's a quality improvement that reduces technical debt, but doesn't block any features.
|
|
|
|
---
|
|
|
|
## 📚 Related Documentation
|
|
|
|
Additional documentation in the repository:
|
|
- `AGENT_WIKI_ANALYSIS.md` - Full Agent architecture
|
|
- `ANALYSIS_SUMMARY.md` - Executive summary
|
|
- `LANGUAGE_MIDDLEWARE_ANALYSIS.md` - Language infrastructure
|
|
- `REFACTORING_PLAN.md` - Detailed implementation plan
|
|
- `LANGUAGE_REFACTORING_QUICK_REFERENCE.md` - Quick start guide
|
|
|
|
---
|
|
|
|
## ✨ Next Steps
|
|
|
|
### Immediately
|
|
1. Review `ANALYSIS_SUMMARY.md` (executive summary)
|
|
2. Decide on quick refactoring vs full enhancement
|
|
|
|
### Next Sprint
|
|
1. Assign implementation task
|
|
2. Use `LANGUAGE_REFACTORING_QUICK_REFERENCE.md`
|
|
3. Implement one-line change
|
|
4. Run tests
|
|
5. Merge and deploy
|
|
|
|
### Future Enhancements
|
|
1. Consider full locale code normalization
|
|
2. Add context-aware language fallback
|
|
3. Document language handling best practices
|
|
4. Audit for other duplicate logic
|
|
|
|
---
|
|
|
|
## 📄 Document Statistics
|
|
|
|
| Document | Lines | KB | Purpose |
|
|
|----------|-------|----|---------|
|
|
| AGENT_WIKI_ANALYSIS.md | 492 | 16 | Complete Agent architecture |
|
|
| LANGUAGE_MIDDLEWARE_ANALYSIS.md | 349 | 11 | Language infrastructure |
|
|
| REFACTORING_PLAN.md | 204 | 6.3 | Implementation plan |
|
|
| LANGUAGE_REFACTORING_QUICK_REFERENCE.md | 111 | 3 | Quick start guide |
|
|
| ANALYSIS_SUMMARY.md | 319 | 11 | Executive summary |
|
|
| **README_ANALYSIS.md** | **This file** | - | Index & navigation |
|
|
| **TOTAL** | **~1,475** | **~47** | **Complete documentation** |
|
|
|
|
---
|
|
|
|
**Status:** ✅ All analysis complete and documentation ready
|
|
|
|
**Location:** `/Users/wizard/code/go/src/git.woa.com/wxg-prc/WeKnora/`
|
|
|
|
**Ready to implement:** Yes, all documents in place with clear implementation path
|
|
|
|
---
|
|
|
|
**Last Updated:** April 7, 2026
|
|
**Next Review:** After implementation sprint
|
|
**Maintained By:** Analysis System
|