Metadata-Version: 2.4
Name: nonebot-plugin-custom-welcome
Version: 0.1.0
Summary: NoneBot2 自定义加群欢迎插件
Project-URL: Homepage, https://github.com/TonyLiangP2010405/nonebot-plugin-custom-welcome
Project-URL: Repository, https://github.com/TonyLiangP2010405/nonebot-plugin-custom-welcome
Author-email: TonyLiangP2010405 <your@email.com>
License: MIT
License-File: LICENSE
Keywords: nonebot,nonebot2,onebot,plugin,welcome
Classifier: Development Status :: 4 - Beta
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Requires-Python: >=3.9
Requires-Dist: httpx>=0.24.0
Requires-Dist: nonebot-adapter-onebot>=2.4.0
Requires-Dist: nonebot2>=2.2.0
Description-Content-Type: text/markdown

# NoneBot2 自定义加群欢迎插件

一个基于 NoneBot2 + OneBot V11 的自定义加群欢迎插件，支持设置欢迎文案、欢迎图片，并支持权限管理。

## 功能特性

- 新人入群自动欢迎（@新人 + 文案 + 图片）
- 支持自定义欢迎文案（多行文本）
- 支持自定义欢迎图片（从消息或引用消息提取）
- 支持查看当前欢迎配置
- 支持清除欢迎配置
- 权限控制：仅群主、群管理员、SUPERUSER 可设置
- 防重复机制：同群 30 秒内只触发一次欢迎
- 本地 JSON 存储，无需 Redis

## 安装方法

### 方法一：从本地安装（推荐开发测试）

```bash
git clone https://github.com/TonyLiangP2010405/nonebot-plugin-custom-welcome.git
cd nonebot-plugin-custom-welcome
pip install -e .
```

### 方法二：直接复制到项目

将 `nonebot_plugin_custom_welcome` 文件夹复制到你的 NoneBot 项目 `src/plugins/` 目录下。

## 使用方法

### 新人入群

当有新人加入群聊时，机器人会自动发送：
- @新人
- 该群配置的欢迎文案
- 该群配置的欢迎图片（如有）

如果群没有配置欢迎内容，则发送默认欢迎：`@新人 欢迎新人~！`

### 设置欢迎文案

```
#设置欢迎文案 欢迎加入本群，请先看群公告~
```

或：

```
#设置欢迎文案
欢迎加入本群
请先看群公告
```

### 设置欢迎图片

**方式一：直接发送图片并附带命令**

```
#设置欢迎图片 [图片]
```

**方式二：引用图片消息**

先发送一张图片，然后引用该图片发送：

```
#设置欢迎图片
```

### 查看欢迎

```
#查看欢迎
```

### 清除欢迎

```
#清除欢迎
```

## 权限说明

| 命令 | 权限要求 |
|------|----------|
| 设置欢迎文案 | 群主 / 管理员 / SUPERUSER |
| 设置欢迎图片 | 群主 / 管理员 / SUPERUSER |
| 查看欢迎 | 任何人 |
| 清除欢迎 | 群主 / 管理员 / SUPERUSER |

权限不足时回复：`只有群主或管理员可以设置欢迎消息哦~`

## 配置项

在 `.env` 文件中可以添加以下配置：

```env
# 默认欢迎文案（可选，默认：欢迎新人~！）
CUSTOM_WELCOME_DEFAULT_TEXT=欢迎新人~！

# 数据存储目录（可选，默认：data/custom_welcome）
CUSTOM_WELCOME_DATA_DIR=data/custom_welcome
```

## 数据存储

插件使用本地 JSON 文件存储配置：

```
data/custom_welcome/
  welcome.json          # 群配置
  images/
    {group_id}/
      welcome.jpg       # 群欢迎图片
```

`welcome.json` 格式：

```json
{
  "123456789": {
    "text": "欢迎加入本群~",
    "image": "data/custom_welcome/images/123456789/welcome.jpg"
  }
}
```

## 技术细节

- 适配器：`nonebot-adapter-onebot` (OneBot V11)
- 图片下载：`httpx` 异步客户端，不会阻塞事件循环
- 配置写入：临时文件 + rename 的原子操作，避免写坏配置
- 路径处理：`pathlib`，兼容 Windows 和 Linux
- 本地图片：`file:///` URI 格式，兼容 NapCat、Lagrange、go-cqhttp

## 测试方法

1. 将插件加载到 NoneBot 项目中
2. 启动 NoneBot，确认无报错
3. 在群聊中发送 `#查看欢迎`，确认回复"该群尚未设置欢迎内容"
4. 发送 `#设置欢迎文案 测试欢迎`，确认设置成功
5. 发送一张图片后，发送 `#设置欢迎图片`，确认设置成功
6. 发送 `#查看欢迎`，确认文案和图片都显示
7. 让一个小号入群，确认收到 `@小号 测试欢迎` 和图片
8. 发送 `#清除欢迎`，确认清除成功
9. 再次让小号入群，确认收到默认欢迎
10. 普通群员发送设置/清除命令，确认被权限拒绝

## 自检清单

- [x] 插件能被 NoneBot 正常 import
- [x] 无语法错误
- [x] 无缺失依赖
- [x] 无错误的 NoneBot API 调用
- [x] `#设置欢迎文案 xxx` 能正确保存
- [x] `#设置欢迎图片` 能从当前消息或引用消息中提取图片
- [x] 新人入群时能发送 @ + 文案 + 图片
- [x] 没有配置时发送默认欢迎
- [x] 普通群员无法设置和清除
- [x] 清除欢迎后图片文件也被删除
- [x] Windows 路径可用
- [x] 多群配置互不影响
