Metadata-Version: 2.4
Name: nonebot-plugin-tieba-monitor
Version: 0.1.8
Summary: NoneBot2 plugin for monitoring Tieba forums
Author-email: su-liu-guang <wuhui0404@gmail.com>
License: GNU AGPLv3
Project-URL: Homepage, https://github.com/su-liu-guang/nonebot-plugin-tieba-monitor
Project-URL: Bug Tracker, https://github.com/su-liu-guang/nonebot-plugin-tieba-monitor/issues
Classifier: Programming Language :: Python :: 3
Classifier: License :: OSI Approved :: GNU Affero General Public License v3
Classifier: Operating System :: OS Independent
Classifier: Framework :: Robot Framework :: Library
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: nonebot2>=2.3.0
Requires-Dist: nonebot-adapter-onebot>=2.2.3
Requires-Dist: nonebot-plugin-apscheduler>=0.3.0
Requires-Dist: aiotieba>=4.5.3
Requires-Dist: openai>=1.0.0
Requires-Dist: nonebot-plugin-localstore>=0.7.2
Dynamic: license-file

# nonebot-plugin-tieba-monitor

基于 [NoneBot2](https://nonebot.dev/) 的贴吧帖子监控插件，用于监控指定贴吧的新帖子并发送到 QQ 群。

## 功能特性

- 监控多个贴吧的新帖子
- 支持自定义检查时间间隔
- 支持多群组通知
- 首次启动自动执行一次巡检，后续按计划任务运行
- 在本地目录缓存帖子数据，便于手动读取最新记录
- 提供 SUPERUSER 触发的 `刷新帖子` / `检查贴吧` 命令
- 支持 AI 内容分析与过滤（可选）

## 安装

### 使用 nb-cli

```bash
nb plugin install nonebot-plugin-tieba-monitor
```

## 使用方法

1. 在 NoneBot2 项目中，确保配置了 OneBot 适配器
2. 在 `.env` 文件中添加插件配置
3. 启动 NoneBot2，插件将自动运行并按照配置的时间间隔监控贴吧

## Bot 命令

| 指令 | 权限 | 说明 |
|------|------|------|
| `刷新帖子 <贴吧名>` | SUPERUSER | 立即读取指定贴吧在本地缓存的最新帖子并推送到当前群，结果会标记为“手动刷新”。 |
| `检查贴吧` | SUPERUSER | 立刻轮询所有已配置的贴吧，触发抓取、AI 筛选与群发，并返回成功/失败统计。 |

> 以上命令默认需要 `to_me` 规则（@机器人）才能触发，可通过 NoneBot 配置调整。

## 功能说明

1. **定时抓取**：依赖 `nonebot_plugin_apscheduler`，按照 `tieba_check_interval_seconds` 周期检测全部已配置贴吧。
2. **启动即查**：Bot 启动后延迟 5 秒执行一次初始检查，确保冷启动时也能收到最新帖子。
3. **数据持久化**：所有帖子缓存到 `tieba_output_directory` 指定的 JSON 文件，`刷新帖子` 命令直接读取这些文件。
4. **AI 审核**：启用 `tieba_ai_enabled` 后会调 OpenAI 兼容接口进行敏感/广告判别，命中 `tieba_ai_filter_keys` 中任意字段会被过滤。
5. **多群播报**：每个贴吧可绑定多个群号；抓取到的新帖会逐群发送，并加入随机延迟减少风控。
6. **手动控制**：`检查贴吧` 命令同步执行完整抓取流程，并返回成功/失败统计，方便排查。

## 配置项

在 `.env` 文件中，你可以配置以下参数：

### 基础配置

| 配置项 | 类型 | 默认值 | 说明 |
|-------|------|--------|------|
| `tieba_check_interval_seconds` | int | 300 | 检查新帖子的时间间隔（秒） |
| `tieba_output_directory` | str | "data/tieba_data" | 保存帖子数据的文件夹路径 |
| `tieba_threads_to_retrieve` | int | 5 | 每次检查时获取的最新帖子数量 |
| `tieba_forum_groups` | Dict[str, List[int]] | {} | 每个贴吧特定的通知群组，需填写合法 JSON/字典字符串，如：`{"贴吧名称": [123456789, 987654321]}` |

> `.env` 中写入复杂结构时推荐使用单行 JSON 并转义双引号，或改用 Python 字典字符串。

### AI 分析配置（可选）

| 配置项 | 类型 | 默认值 | 说明 |
|-------|------|--------|------|
| `tieba_ai_enabled` | bool | false | 是否启用 AI 分析 |
| `tieba_ai_apikey` | str | "" | AI API 密钥 |
| `tieba_ai_endpoint` | str | "https://api.openai.com/v1" | AI API 端点 |
| `tieba_ai_model` | str | "gpt-3.5-turbo" | AI 模型名称 |
| `tieba_ai_max_chars` | int | 100 | 发送给 AI 的最大字符数，0 表示不截断 |
| `tieba_ai_system_prompt` | str | (见代码) | AI 分析使用的系统提示词，用于自定义 AI 的分析行为 |
| `tieba_ai_filter_keys` | List[str] | ["是否包含敏感内容", "是否包含广告、营销信息"] | 命中任意字段且值为 `true` 时视为不发送 |

> `TIEBA_AI_ENABLED` 等布尔环境变量不区分大小写；若自定义 `tieba_ai_system_prompt`，请确保与 `tieba_ai_filter_keys` 中的字段对应。

## 配置示例

```dotenv
# 基础配置
tieba_check_interval_seconds=300
tieba_output_directory=data/tieba_data
tieba_threads_to_retrieve=10

# 贴吧监控配置 - 格式: {'贴吧名': [群号1, 群号2]}
# 例如监控"王者荣耀"贴吧并发送到群 123456789 和 987654321
tieba_forum_groups={"王者荣耀": [123456789, 987654321], "英雄联盟": [123456789]}

# AI 分析配置（可选）
tieba_ai_enabled=false
tieba_ai_apikey=your_api_key
tieba_ai_endpoint=https://api.openai.com/v1
tieba_ai_model=gpt-3.5-turbo
tieba_ai_max_chars=500
tieba_ai_filter_keys=["是否包含敏感内容", "是否包含广告、营销信息"]
tieba_ai_system_prompt="""你是一个帖子内容分析助手。分析以下内容并返回JSON格式的结果..."""
```


## 注意事项

- 请确保 `.env` 文件中的 `tieba_forum_groups` 参数格式正确
- 若启用 AI 分析功能，请提供有效的 API 密钥
- 首次启动时，插件将立即执行一次贴吧检查
- 如需自定义 AI 提示词，请确保返回格式与默认提示词一致
- 手动命令仅 SUPERUSER 可用，且默认需要 @ 机器人
- 帖子缓存文件保存在 `tieba_output_directory` 指定的目录下，`刷新帖子` 命令依赖这些文件

## 更多信息

- 本插件利用 `aiotieba` 库进行贴吧内容获取
- 使用 `nonebot-plugin-apscheduler` 进行定时任务管理
- 插件会将帖子数据保存在配置的输出目录中


## 许可证
本项目使用 [GNU AGPLv3](https://choosealicense.com/licenses/agpl-3.0/) 作为开源许可证。
