xinyin025/LangBot
1
0
Fork 0
mirror of https://github.com/langbot-app/LangBot.git synced 2026-10-29 20:05:25 +08:00
Code Issues Packages Projects Releases Wiki Activity

docs: add guidance for dir struct

Browse Source
This commit is contained in:
Junyan Qin
2025-11-21 12:35:39 +08:00
parent f3ce348fe0
commit 3ad8010282
3 changed files with 384 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/.vitepress/config.mts
+2
View File
@@ -196,6 +196,7 @@ export default defineConfig({
items: [
{ text: "基础教程", link: "/zh/plugin/dev/tutor" },
{ text: "完善配置信息", link: "/zh/plugin/dev/basic-info" },
{ text: "目录规范", link: "/zh/plugin/dev/directory-structure" },
{
text: "组件开发",
collapsed: true,
@@ -467,6 +468,7 @@ export default defineConfig({
items: [
{ text: "Basic Tutorial", link: "/en/plugin/dev/tutor" },
{ text: "Complete Plugin Configuration Information", link: "/en/plugin/dev/basic-info" },
{ text: "Directory Structure", link: "/en/plugin/dev/directory-structure" },
{
text: "Component Development",
collapsed: true,
docs/en/plugin/dev/directory-structure.md
+191
View File
@@ -0,0 +1,191 @@
# Plugin Directory Structure
:::info Table of Contents
[[toc]]
:::
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:**
1. **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
2. **`readme/` Directory (Optional)**
- Used to store **non-English** README documents
- File naming format: `README_{language_code}.md`
### Supported Language Codes
According to [RFC 4646](https://datatracker.ietf.org/doc/html/rfc4646) 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 |
### 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**
```markdown
# 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:
1. Try to read `readme/README_{language_code}.md`
2. 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:
```markdown
# 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](/en/plugin/dev/components/add)
## 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](/en/plugin/dev/basic-info)
### 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.
## Related Documentation
- [Basic Tutorial](/en/plugin/dev/tutor) - Learn how to create your first plugin
- [Complete Plugin Configuration Information](/en/plugin/dev/basic-info) - Configure manifest.yaml
- [Adding Components](/en/plugin/dev/components/add) - Develop plugin components
- [Publish to Marketplace](/en/plugin/dev/publish/market) - Distribute your plugin
docs/zh/plugin/dev/directory-structure.md
+191
View File
@@ -0,0 +1,191 @@
# 插件目录规范
:::info 目录
[[toc]]
:::
本文介绍 LangBot 插件的标准目录结构和文件组织规范，帮助开发者创建符合规范的插件。
## 基本目录结构
一个标准的 LangBot 插件应遵循以下目录结构：
```
MyPlugin/
├── manifest.yaml # 插件清单文件（必需）
├── main.py # 插件主入口文件（必需）
├── README.md # 英文版插件说明文档（必需）
├── readme/ # 多语言 README 目录（可选）
│ ├── README_zh_Hans.md # 简体中文版说明文档
│ ├── README_ja_JP.md # 日文版说明文档
│ └── README_zh_Hant.md # 繁体中文版说明文档（可选）
├── assets/ # 资源文件目录
│ ├── icon.svg # 插件图标（推荐）
│ └── ... # 其他资源文件
├── components/ # 组件目录
│ ├── event_listener/ # 事件监听器组件
│ ├── commands/ # 命令组件
│ └── tools/ # 工具组件
├── requirements.txt # Python 依赖（可选）
└── config/ # 配置文件目录（可选）
```
## 多语言 README 规范
### 文件位置规范
LangBot 插件支持多语言 README 文档，以便为不同语言的用户提供本地化的插件说明。
**重要规范：**
1. **根目录 `README.md`（必需）**
- 必须使用**英文**编写
- 作为插件的默认说明文档
- 当请求的语言版本不存在时，将回退到此文档
2. **`readme/` 目录（可选）**
- 用于存放**非英文**的 README 文档
- 文件命名格式：`README_{语言代码}.md`
### 支持的语言代码
根据 [RFC 4646](https://datatracker.ietf.org/doc/html/rfc4646) 标准，LangBot 目前支持以下语言代码：
| 语言 | 语言代码 | 文件名 | 位置 |
|------|----------|--------|------|
| 英文 | `en` 或 `en_US` | `README.md` | **插件根目录** |
| 简体中文 | `zh_Hans` | `README_zh_Hans.md` | `readme/` 目录 |
| 繁体中文 | `zh_Hant` | `README_zh_Hant.md` | `readme/` 目录 |
| 日语 | `ja_JP` | `README_ja_JP.md` | `readme/` 目录 |
### 示例目录结构
```
MyPlugin/
├── README.md # ✅ 英文版（必需，放在根目录）
└── readme/ # ✅ 多语言目录
├── README_zh_Hans.md # ✅ 简体中文版
├── README_ja_JP.md # ✅ 日语版
└── README_zh_Hant.md # ✅ 繁体中文版
```
### 错误示例
❌ **错误做法：将英文 README 放在 readme/ 目录**
```
MyPlugin/
├── readme/
│ ├── README_en.md # ❌ 错误：英文不应该在 readme/ 目录
│ └── README_zh_Hans.md
```
❌ **错误做法：根目录 README.md 包含非英文内容**
```markdown
# MyPlugin
This is a plugin...
这是一个插件... # ❌ 错误：根目录 README.md 只能包含英文
```
### README 语言回退逻辑
当用户请求特定语言的 README 时，LangBot 将按以下顺序查找：
1. 尝试读取 `readme/README_{语言代码}.md`
2. 如果不存在，回退到根目录的 `README.md`（英文版）
**示例：**
- 用户请求简体中文（`zh_Hans`）
- → 查找 `readme/README_zh_Hans.md`
- → 如果不存在，返回 `README.md`（英文版）
- 用户请求日语（`ja_JP`）
- → 查找 `readme/README_ja_JP.md`
- → 如果不存在，返回 `README.md`（英文版）
## 资源文件目录
### assets/ 目录
`assets/` 目录用于存放插件的静态资源文件。
**推荐结构：**
```
assets/
├── icon.svg # 插件图标（推荐使用 SVG 格式）
├── example.png # 示例图片
├── screenshot1.png # 截图
└── logo.png # Logo 图片
```
**图标规范：**
- 推荐使用 `icon.svg` 作为插件图标
- 支持的格式：`.svg`、`.png`、`.jpg`、`.jpeg`、`.gif`
- 推荐尺寸：至少 256x256 像素
- 在 `manifest.yaml` 中引用：`icon: assets/icon.svg`
### 在 README 中引用资源
在 README 文档中，可以使用相对路径引用 assets/ 目录中的图片：
```markdown
# MyPlugin
![Example](./assets/example.png)
![Screenshot](./assets/screenshot1.png)
```
**注意：** 插件上传到 LangBot Space 后，资源文件会被自动处理并托管，用户查看 README 时会正确显示图片。
## 组件目录
插件的功能通过组件实现，组件文件应按类型组织在 `components/` 目录下：
```
components/
├── event_listener/ # 事件监听器
│ ├── on_message.py
│ └── on_message.yaml
├── commands/ # 命令
│ ├── hello.py
│ └── hello.yaml
└── tools/ # 工具
├── search.py
└── search.yaml
```
详细的组件开发规范请参考：[添加组件](/zh/plugin/dev/components/add)
## 配置文件
### manifest.yaml
插件清单文件 `manifest.yaml` 是插件的核心配置文件，包含插件的元数据、配置项、组件列表等信息。
详细说明请参考：[完善配置信息](/zh/plugin/dev/basic-info)
### requirements.txt
如果插件需要额外的 Python 依赖包，应在根目录创建 `requirements.txt` 文件：
```
requests>=2.28.0
beautifulsoup4>=4.11.0
pillow>=9.0.0
```
**注意：** LangBot 在安装插件时会自动安装 `requirements.txt` 中列出的依赖。
## 相关文档
- [基础教程](/zh/plugin/dev/tutor) - 了解如何创建第一个插件
- [完善配置信息](/zh/plugin/dev/basic-info) - 配置 manifest.yaml
- [添加组件](/zh/plugin/dev/components/add) - 开发插件组件
- [发布到插件市场](/zh/plugin/dev/publish/market) - 分发你的插件