# 群聊日常分析插件
[](https://github.com/SXP-Simon/astrbot-qq-group-daily-analysis)
[](https://github.com/AstrBotDevs/AstrBot)
[](LICENSE)
[](https://qm.qq.com/q/oTzIrdDBIc)
_✨ 一个基于 AstrBot 的智能群聊分析插件，支持 **QQ (OneBot)**、**Discord**，未来支持更多平台。 ✨_
点击展开查看其他模板效果图
format 模板效果图
simple 模板效果图(用于展示贡献指南)
retro_futurism 模板效果图
## 使用方法
### 基础命令
#### 群分析
```
/群分析 [天数]
```
- 分析群聊近期活动
- 天数可选，默认为1天
- 例如：`/群分析 3` 分析最近3天的群聊
#### 增量状态
```
/增量状态
```
- 查看当前增量分析的实时状态
- 显示当前滑动窗口内的分析次数、消息数、话题数等统计
- **仅在启用增量分析模式时可用**
#### 分析设置
```
/分析设置 [操作]
```
- `enable`: 为当前群启用分析功能
- `disable`: 为当前群禁用分析功能
- `status`: 查看当前群的启用状态
- 例如：`/分析设置 enable`
#### 模板设置
```
/查看模板
/设置模板 [模板名称或序号]
```
- `/查看模板`: 查看所有可用模板及预览图
- `/设置模板`: 查看当前模板和可用模板列表
- `/设置模板 [序号]`: 切换到指定序号的模板
- 例如：`/设置模板 1` 或 `/设置模板 scrapbook`
## 平台支持与要求
| 平台 | 适配器类型 | 特殊要求/说明 |
|------|-----------|--------------|
| **QQ** | OneBot v11 | 建议使用 NapCat/Lagrange。需注意消息分页拉取限制。 |
| **Discord** | Discord | **必须** 拥有 `Read Message History` (查看消息历史记录) 权限。 |
> [!CAUTION]
> **Discord 用户重点注意**：
> 如果机器人无法获取群列表或分析报 `403 Forbidden`，请检查 Discord 开发者面板中：
> 1. **Privileged Gateway Intents**: 开启 `Message Content Intent`。
> 2. **频道权限**: 确保机器人所在的频道，对应的角色拥有 **“查看消息历史记录”** 权限。
## 注意事项
> [!WARNING]
> 1. **性能考虑**: 大量消息分析可能消耗较多 LLM tokens
> 2. **数据准确性**: 分析结果基于可获取的群聊记录，可能不完全准确
## 增量分析模式 (Beta)
增量分析模式是为了解决消息量大的群聊（如日均消息 > 500 条）在单次分析时容易丢失上下文的问题。
**核心特性：**
- **滑动窗口**：不再受限于自然日，分析窗口随时间滑动（如过去 24 小时），确保任何时候生成的报告都覆盖完整的时间段。
- **分批处理**：定时（如每 2 小时）执行一次小批量分析，减轻 LLM 瞬时压力。
- **自动去重**：智能识别重复话题和金句，合并生成最终报告。
**启用方法：**
在插件配置中开启 `incremental_enabled`，并根据需要调整分析间隔 (`incremental_interval_minutes`) 和消息阈值。
## 常见问题 (FAQ)
### 获取不到带记录的引用消息
**现象**：
后台日志出现 `[warn] ... 似乎是旧版客户端 ... [error] ... 获取不到带记录的引用消息`。
**原因**：
这是由于 NapCat/NTQQ 消息 ID 格式变动、消息过期或临时会话限制导致的。机器人尝试降级使用旧版序号查找失败。
**忽略**：如果只是偶尔出现（如回复久远消息），不影响机器人核心功能（收发消息），可以直接忽略。
## 贡献
### 项目架构图
### 贡献指南
### 开发环境设置
为了保持代码质量，本项目使用 [pre-commit](https://pre-commit.com/) 钩子进行代码规范检查和自动修复。所有的贡献代码都必须通过 pre-commit 检查。
#### 1. 安装 pre-commit
```bash
pip install pre-commit
```
#### 2. 安装 git hook
在项目根目录下运行，这将确保在每次提交时自动运行检查：
```bash
pre-commit install
```
#### 3. 手动运行检查
如果需要手动触发所有文件的检查（推荐在提交前运行一次）：
```bash
pre-commit run --all-files
```
### 模板贡献指南
🎨 点击展开查看如何贡献你的自定义模板给更多人玩
如果您想为插件贡献新的报告模板，请按照以下步骤操作：
#### 1. 创建模板目录
在 `src/reports/templates/` 目录下创建一个新的文件夹，例如 `my_theme`。
#### 2. 必需文件结构
您的模板目录需要包含以下文件：
```text
src/reports/templates/your_theme_name/
├── image_template.html # 图片报告主模板
├── pdf_template.html # PDF报告主模板
├── activity_chart.html # 活跃度图表组件
├── topic_item.html # 话题列表项组件
├── user_title_item.html # 用户称号项组件
└── quote_item.html # 金句项组件
```
#### 3. 模板变量说明
**主模板 (`image_template.html` / `pdf_template.html`) 可用变量:**
- `current_date`: 当前日期 (YYYY-MM-DD)
- `current_datetime`: 当前时间 (YYYY-MM-DD HH:MM:SS)
- `message_count`: 消息总数
- `participant_count`: 参与人数
- `total_characters`: 总字符数
- `emoji_count`: 表情数量
- `most_active_period`: 最活跃时段
- `hourly_chart_html`: 渲染后的活跃度图表 HTML
- `topics_html`: 渲染后的热门话题 HTML
- `titles_html`: 渲染后的用户称号 HTML
- `quotes_html`: 渲染后的金句 HTML
- `total_tokens`: Token 消耗统计
- `prompt_tokens`: 提示词 Token 消耗
- `completion_tokens`: 生成内容 Token 消耗
**组件模板可用变量:**
- `activity_chart.html`: `chart_data` (包含 `hour`, `count`, `percentage` 的列表)
- `topic_item.html`: `topic` (包含 `keyword`, `count`, `summary` 的对象), `loop.index` (序号)
- `user_title_item.html`: `user` (包含 `nickname`, `user_id`, `titles` (列表), `description` 的对象)
- `quote_item.html`: `quote` (包含 `content`, `sender_nickname`, `reason` 的对象)
#### 4. 参考示例
您可以参考 `src/reports/templates/simple/` 目录下的文件，这是一个最简化的模板实现，包含了所有必需的基本结构。
#### 5. 模板调试工具
PDF 调试模板命令 Docker 下：
```
docker exec -it astrbot python data/plugins/astrbot_plugin_qq_group_daily_analysis/scripts/mock_pdf_gen.py
```
Image 模板调试：
本项目提供了一个专门用于模板开发的调试工具 `scripts/debug_render.py`，可以在不启动完整 AstrBot 环境的情况下快速预览模板渲染效果。
**使用方法：**
```bash
# 进入项目目录
cd astrbot-qq-group-daily-analysis
# 使用默认模板 (retro_futurism) 渲染
python scripts/debug_render.py
# 指定模板名称渲染
python scripts/debug_render.py -t simple
# 指定输出文件路径
python scripts/debug_render.py -t retro_futurism -o my_output.html
# 查看帮助信息
python scripts/debug_render.py -h
```
**工具特性：**
- 使用 Mock 数据模拟真实的群聊分析结果
- 无需配置 LLM 服务或启动 AstrBot
- 输出可使用live server打开 HTML 文件，并进行修改查看
- 支持所有内置模板的快速切换预览
**开发工作流推荐：**
1. 修改模板文件
2. 运行调试工具生成预览
3. 在浏览器中打开生成的 HTML 文件查看效果
4. 重复上述步骤直到满意
## 许可证
MIT License
欢迎提交Issue和Pull Request来改进这个插件！