Add English documentation

Co-Authored-By: Junyan Qin <Chin> <[email protected]>
2026-11-04 23:03:55 +08:00 · 2025-05-13 15:25:41 +00:00
parent cca2067b88
commit dd93920369
17 changed files with 2952 additions and 215 deletions
@@ -0,0 +1,96 @@
+# Component Architecture
+
+This document describes the component architecture of LangBot, which is designed to be modular and extensible.
+
+## Overview
+
+LangBot is built around a component-based architecture that allows for easy extension and customization. The main components are:
+
+1. **Bots**: Interface with messaging platforms
+2. **Pipelines**: Process messages and generate responses
+3. **Models**: Connect to LLM providers
+4. **Plugins**: Extend functionality
+
+![architecture](/assets/image/zh/deploy/bots/arch.png)
+
+## Bots
+
+Bots are responsible for connecting to messaging platforms and handling message events. Each bot implements a specific platform adapter that translates between the platform's API and LangBot's internal event system.
+
+Key classes:
+- `MessageSourceAdapter`: Base class for all platform adapters
+- `EventConverter`: Converts platform-specific events to LangBot events
+- `MessageConverter`: Converts platform-specific messages to LangBot messages
+
+## Pipelines
+
+Pipelines process messages through a series of components:
+
+1. **Trigger**: Determines whether to process a message
+2. **Moderation**: Filters and processes messages before sending to the model
+3. **AI**: Sends the message to the LLM and receives a response
+4. **Output**: Processes the model's response before sending it back to the user
+
+Each component in the pipeline can be configured and customized.
+
+## Models
+
+The Models component manages connections to various LLM providers, such as OpenAI, Anthropic, and others. It provides a unified interface for sending requests to these providers and handling their responses.
+
+Key classes:
+- `ModelProvider`: Base class for all model providers
+- `ModelRequest`: Represents a request to a model
+- `ModelResponse`: Represents a response from a model
+
+## Plugins
+
+The plugin system allows for extending LangBot's functionality without modifying the core code. Plugins can:
+
+- Register event handlers
+- Add new commands
+- Provide functions that can be called by the LLM
+- Extend core components
+
+Key concepts:
+- `@handler`: Decorator for registering event handlers
+- `@llm_func`: Decorator for registering functions that can be called by the LLM
+- `APIHost`: Provides access to LangBot's API from plugins
+- `manifest.yaml`: Configuration file for plugins
+
+## Event System
+
+LangBot uses an event-driven architecture where different components communicate through events. Events include:
+
+- Message events (received, sent)
+- Group events (joined, left, invited)
+- System events (startup, shutdown)
+- Custom events defined by plugins
+
+## Configuration System
+
+The configuration system uses a YAML-based approach with the main configuration file at `data/config.yaml`. The configuration is structured around the component architecture:
+
+```yaml
+bots:
+  # Bot configurations
+pipelines:
+  # Pipeline configurations
+providers:
+  # Model provider configurations
+plugins:
+  # Plugin configurations
+system:
+  # System configurations
+```
+
+## Development Workflow
+
+When developing for LangBot, follow these steps:
+
+1. Understand the component you want to modify or extend
+2. Create a plugin if you're adding new functionality
+3. Implement the necessary classes and methods
+4. Test your changes
+5. Submit a pull request
+
+For more detailed information on development, see the [Development Configuration](/en/develop/dev-config) page.
@@ -0,0 +1,160 @@
+# Development Configuration
+
+This guide explains how to set up a development environment for LangBot and contribute to the project.
+
+## Prerequisites
+
+Before you start, make sure you have the following installed:
+
+- Python 3.10 or higher
+- Git
+- Node.js 16 or higher (for WebUI development)
+- A code editor (VS Code recommended)
+
+## Setting Up the Development Environment
+
+1. Fork the LangBot repository on GitHub
+2. Clone your fork:
+
+```bash
+git clone https://github.com/your-username/LangBot.git
+cd LangBot
+```
+
+3. Create a virtual environment:
+
+```bash
+python -m venv venv
+source venv/bin/activate  # On Windows: venv\Scripts\activate
+```
+
+4. Install dependencies:
+
+```bash
+pip install -r requirements.txt
+pip install -r requirements-dev.txt
+```
+
+5. Set up pre-commit hooks:
+
+```bash
+pre-commit install
+```
+
+## Project Structure
+
+The LangBot project is organized as follows:
+
+```
+LangBot/
+├── data/                  # Data directory (configs, plugins, etc.)
+├── langbot/               # Core package
+│   ├── bot/               # Bot implementations
+│   ├── pipeline/          # Pipeline components
+│   ├── model/             # Model providers
+│   ├── plugin/            # Plugin system
+│   ├── webui/             # WebUI backend
+│   └── utils/             # Utility functions
+├── tests/                 # Test cases
+├── web/                   # WebUI frontend
+├── main.py                # Entry point
+└── requirements.txt       # Dependencies
+```
+
+## Running LangBot in Development Mode
+
+To run LangBot in development mode:
+
+```bash
+python main.py --debug
+```
+
+This will start LangBot with debug logging enabled.
+
+## WebUI Development
+
+To develop the WebUI:
+
+1. Navigate to the web directory:
+
+```bash
+cd web
+```
+
+2. Install dependencies:
+
+```bash
+npm install
+```
+
+3. Start the development server:
+
+```bash
+npm run dev
+```
+
+4. In another terminal, start LangBot with the WebUI enabled:
+
+```bash
+python main.py --webui
+```
+
+## Testing
+
+LangBot uses pytest for testing. To run the tests:
+
+```bash
+pytest
+```
+
+To run a specific test:
+
+```bash
+pytest tests/test_file.py::test_function
+```
+
+## Code Style
+
+LangBot follows the PEP 8 style guide with some modifications. We use black for code formatting and isort for import sorting.
+
+To format your code:
+
+```bash
+black langbot tests
+isort langbot tests
+```
+
+## Creating a Pull Request
+
+1. Create a new branch for your feature or bugfix:
+
+```bash
+git checkout -b feature/your-feature-name
+```
+
+2. Make your changes and commit them:
+
+```bash
+git add .
+git commit -m "Add your feature or fix"
+```
+
+3. Push your branch to GitHub:
+
+```bash
+git push origin feature/your-feature-name
+```
+
+4. Create a pull request on GitHub
+
+## Documentation
+
+When adding new features, make sure to update the documentation. The documentation is written in Markdown and is located in the [QChatGPT-Wiki](https://github.com/RockChinQ/QChatGPT-Wiki) repository.
+
+## Getting Help
+
+If you need help with development, you can:
+
+- Join the [community chat](https://qm.qq.com/q/Nnz7Vbj8OU)
+- Open an issue on [GitHub](https://github.com/RockChinQ/LangBot/issues)
+- Check the existing documentation and code for examples