Project Structure

N.E.K.O/
├── launcher.py                 # Desktop launcher (Steam/exe)
│
├── app/                        # Server entry points
│   ├── main_server/           # Main server entry point (port 48911)
│   ├── memory_server.py        # Memory server entry point (port 48912)
│   ├── agent_server/           # Agent server package (port 48915)
│   └── monitor.py              # Monitor service
│
├── brain/                      # Agent & task execution
│   ├── task_executor.py        # Main task execution engine
│   ├── computer_use.py         # Computer vision/interaction
│   ├── browser_use_adapter.py  # Browser automation adapter
│   ├── openclaw_adapter.py     # OpenClaw agent adapter
│   ├── openfang_adapter.py     # OpenFang agent adapter
│   ├── plugin_filter.py        # Plugin filtering for agent tools
│   ├── deduper.py              # Duplicate detection
│   ├── agent_session.py        # Agent session management
│   └── cua/                    # Computer-use agent subpackage
│
├── config/                     # Configuration
│   ├── __init__.py             # Constants, defaults, port definitions
│   ├── api_providers.json      # API provider profiles
│   └── prompts/                # Character, system, and feature prompts
│       ├── prompts_sys.py      # System prompts (emotion, proactive chat)
│       └── prompts_chara.py    # Character system prompts
│
├── main_logic/                 # Core business logic
│   ├── core/                   # LLMSessionManager package (manager.py + domain mixins)
│   ├── omni_realtime_client.py # Realtime API WebSocket client
│   ├── omni_offline_client.py  # Text/Response API client (offline fallback)
│   ├── tts_client/             # TTS engine adapters package (CosyVoice, GPT-SoVITS, ElevenLabs, ...)
│   ├── cross_server.py         # Inter-server communication
│   └── agent_event_bus.py      # ZeroMQ event bridge (main ↔ agent)
│
├── main_routers/               # FastAPI route handlers
│   ├── websocket_router.py     # WebSocket /ws/{lanlan_name}
│   ├── characters_router.py    # /api/characters/*
│   ├── config_router.py        # /api/config/*
│   ├── live2d_router.py        # /api/live2d/*
│   ├── vrm_router.py           # /api/model/vrm/*
│   ├── memory_router.py        # /api/memory/*
│   ├── agent_router.py         # /api/agent/*
│   ├── workshop_router.py      # /api/steam/workshop/*
│   ├── system_router.py        # /api/* (misc system endpoints)
│   ├── pages_router.py         # HTML page serving
│   └── shared_state.py         # Global state shared across routers
│
├── memory/                     # Memory management
│   └── store/                  # Memory data storage (SQLite)
│
├── frontend/                   # Modern frontend projects
│   ├── react-neko-chat/        # React chat window (builds → static/react/neko-chat/)
│   └── plugin-manager/         # Vue plugin manager (builds → frontend/plugin-manager/dist/)
│
├── plugin/                     # Plugin system
│   ├── sdk/                    # Plugin SDK (base class, decorators)
│   │   ├── base.py             # NekoPluginBase
│   │   └── decorators.py       # @neko_plugin, @plugin_entry, etc.
│   └── plugins/                # User plugin directory
│
├── utils/                      # Utility modules
│   ├── config_manager.py       # Centralized config management (1500+ lines)
│   ├── language_utils.py       # i18n, language detection, translation
│   ├── audio_processor.py      # Audio resampling, noise reduction
│   ├── frontend_utils.py       # Model discovery, text utilities
│   ├── api_config_loader.py    # API provider resolution
│   ├── logger_config.py        # Logging setup with rate limiting
│   ├── workshop_utils.py       # Steam Workshop helpers
│   ├── web_scraper.py          # Web content scraping & filtering
│   └── screenshot_utils.py     # Screenshot processing for vision APIs
│
├── static/                     # Frontend assets
│   ├── app.js                  # Main application JS
│   ├── theme-manager.js        # Dark/light mode
│   ├── css/                    # Stylesheets
│   ├── js/                     # Feature-specific JS modules
│   ├── locales/                # i18n JSON files (en, zh-CN, zh-TW, ja, ko, ru, es, pt)
│   └── live2d-ui-*.js          # Live2D UI components
│
├── templates/                  # Jinja2 HTML templates
│   ├── index.html              # Main interface
│   ├── chara_manager.html      # Character management
│   ├── api_key_settings.html   # API key config
│   └── ...                     # Other page templates
│
├── docker/                     # Docker deployment files
│   ├── Dockerfile
│   ├── docker-compose.yml
│   ├── entrypoint.sh
│   └── CONFIG_REFERENCE.md     # Configuration reference
│
├── tests/                      # Test suite
│   ├── unit/                   # Unit tests
│   ├── frontend/               # Frontend integration tests (Playwright)
│   ├── e2e/                    # End-to-end tests
│   └── utils/                  # Test utilities
│
├── pyproject.toml              # Project metadata & dependencies
└── requirements.txt            # Pinned dependency list

Key files

File	Lines	Role
main_logic/core/	~10600	Central session manager package — the heart of the system
utils/config_manager.py	~1500	Configuration loading, validation, persistence
main_logic/tts_client/	~1300	TTS synthesis package with multi-provider support
brain/task_executor.py	~1600	Agent task planning and execution
utils/web_scraper.py	~1900	Web content scraping for proactive chat