Plugin Directory Structure

This document introduces the standard directory structure and file organization specifications for LangBot plugins, helping developers create compliant plugins.

Basic Directory Structure

A standard LangBot plugin should follow this directory structure:

MyPlugin/
├── manifest.yaml          # Plugin manifest file (required)
├── main.py               # Plugin main entry file (required)
├── README.md             # English plugin documentation (required)
├── readme/               # Multilingual README directory (optional)
│   ├── README_zh_Hans.md # Simplified Chinese documentation
│   ├── README_ja_JP.md   # Japanese documentation
│   └── README_zh_Hant.md # Traditional Chinese documentation (optional)
├── assets/               # Resource files directory
│   ├── icon.svg         # Plugin icon (recommended)
│   └── ...              # Other resource files
├── components/           # Components directory
│   ├── event_listener/  # Event listener components
│   ├── commands/        # Command components
│   └── tools/           # Tool components
├── requirements.txt      # Python dependencies (optional)
└── config/              # Configuration directory (optional)

Multilingual README Specification

File Location Specification

LangBot plugins support multilingual README documentation to provide localized plugin descriptions for users in different languages. Important Specifications:

Root README.md (Required)
- Must be written in English
- Serves as the plugin’s default documentation
- Used as fallback when requested language version doesn’t exist
readme/ Directory (Optional)
- Used to store non-English README documents
- File naming format: README_{language_code}.md

Supported Language Codes

According to RFC 4646 standard, LangBot currently supports the following language codes:

Language	Language Code	Filename	Location
English	`en` or `en_US`	`README.md`	Plugin root directory
Simplified Chinese	`zh_Hans`	`README_zh_Hans.md`	`readme/` directory
Traditional Chinese	`zh_Hant`	`README_zh_Hant.md`	`readme/` directory
Japanese	`ja_JP`	`README_ja_JP.md`	`readme/` directory
Vietnamese	`vi_VN`	`README_vi_VN.md`	`readme/` directory
Thai	`th_TH`	`README_th_TH.md`	`readme/` directory
Spanish	`es_ES`	`README_es_ES.md`	`readme/` directory

Example Directory Structure

MyPlugin/
├── README.md                    # ✅ English version (required, in root)
└── readme/                      # ✅ Multilingual directory
    ├── README_zh_Hans.md       # ✅ Simplified Chinese
    ├── README_ja_JP.md         # ✅ Japanese
    └── README_zh_Hant.md       # ✅ Traditional Chinese

Incorrect Examples

❌ Wrong: Placing English README in readme/ directory

MyPlugin/
├── readme/
│   ├── README_en.md        # ❌ Wrong: English should not be in readme/
│   └── README_zh_Hans.md

❌ Wrong: Root README.md contains non-English content

# MyPlugin

This is a plugin...

这是一个插件...    # ❌ Wrong: Root README.md should only contain English

README Language Fallback Logic

When a user requests a README in a specific language, LangBot will search in the following order:

Try to read readme/README_{language_code}.md
If not found, fall back to root README.md (English version)

Examples:

User requests Simplified Chinese (zh_Hans)
- → Look for readme/README_zh_Hans.md
- → If not found, return README.md (English version)
User requests Japanese (ja_JP)
- → Look for readme/README_ja_JP.md
- → If not found, return README.md (English version)

Resource Files Directory

assets/ Directory

The assets/ directory is used to store plugin static resource files. Recommended Structure:

assets/
├── icon.svg              # Plugin icon (SVG format recommended)
├── example.png           # Example image
├── screenshot1.png       # Screenshot
└── logo.png             # Logo image

Icon Specifications:

Recommended to use icon.svg as plugin icon
Supported formats: .svg, .png, .jpg, .jpeg, .gif
Recommended size: At least 256x256 pixels
Reference in manifest.yaml: icon: assets/icon.svg

Referencing Resources in README

In README documentation, you can use relative paths to reference images in the assets/ directory:

# MyPlugin

![Example](./assets/example.png)

![Screenshot](./assets/screenshot1.png)

Note: After uploading plugins to LangBot Space, resource files will be automatically processed and hosted, and images will display correctly when users view the README.

Components Directory

Plugin functionality is implemented through components, which should be organized by type in the components/ directory:

components/
├── event_listener/       # Event listeners
│   ├── on_message.py
│   └── on_message.yaml
├── commands/            # Commands
│   ├── hello.py
│   └── hello.yaml
└── tools/               # Tools
    ├── search.py
    └── search.yaml

For detailed component development specifications, please refer to: Adding Components

Configuration Files

manifest.yaml

The plugin manifest file manifest.yaml is the core configuration file, containing plugin metadata, configuration items, component lists, and other information. For detailed instructions, please refer to: Complete Plugin Configuration Information

requirements.txt

If the plugin requires additional Python dependencies, create a requirements.txt file in the root directory:

requests>=2.28.0
beautifulsoup4>=4.11.0
pillow>=9.0.0

Note: LangBot will automatically install dependencies listed in requirements.txt when installing the plugin.

Basic Tutorial - Learn how to create your first plugin
Complete Plugin Configuration Information - Configure manifest.yaml
Adding Components - Develop plugin components
Publish to Marketplace - Distribute your plugin

Plugin Development

Plugin SDK API

Core Development

Plugin Directory Structure

Basic Directory Structure

Multilingual README Specification

File Location Specification

Supported Language Codes

Example Directory Structure

Incorrect Examples

README Language Fallback Logic

Resource Files Directory

assets/ Directory

Referencing Resources in README

Components Directory

Configuration Files

manifest.yaml

requirements.txt

​Basic Directory Structure

​Multilingual README Specification

​File Location Specification

​Supported Language Codes

​Example Directory Structure

​Incorrect Examples

​README Language Fallback Logic

​Resource Files Directory

​assets/ Directory

​Referencing Resources in README

​Components Directory

​Configuration Files

​manifest.yaml

​requirements.txt

​Related Documentation

Basic Directory Structure

Multilingual README Specification

File Location Specification

Supported Language Codes

Example Directory Structure

Incorrect Examples

README Language Fallback Logic

Resource Files Directory

assets/ Directory

Referencing Resources in README

Components Directory

Configuration Files

manifest.yaml

requirements.txt

Related Documentation