跳转到主要内容
本文介绍 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 标准，LangBot 目前支持以下语言代码：
语言语言代码文件名位置
英文en 或 en_USREADME.md插件根目录
简体中文zh_HansREADME_zh_Hans.mdreadme/ 目录
繁体中文zh_HantREADME_zh_Hant.mdreadme/ 目录
日语ja_JPREADME_ja_JP.mdreadme/ 目录

​
示例目录结构

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 包含非英文内容 
# 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/ 目录中的图片： 
# 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
详细的组件开发规范请参考：添加组件

​
配置文件

​
manifest.yaml

插件清单文件 manifest.yaml 是插件的核心配置文件，包含插件的元数据、配置项、组件列表等信息。 详细说明请参考：完善配置信息

​
requirements.txt

如果插件需要额外的 Python 依赖包，应在根目录创建 requirements.txt 文件： 
requests>=2.28.0
beautifulsoup4>=4.11.0
pillow>=9.0.0
注意： LangBot 在安装插件时会自动安装 requirements.txt 中列出的依赖。

​
相关文档