群聊日常分析插件

QQ群	Telegram群

✨ 一个基于 AstrBot 的智能群聊分析插件，支持 OneBot ( NapNeko/NapCatQQ, LLOneBot/LuckyLilliaBot, SnowLuma/SnowLuma)、QQ 官方机器人、Telegram、Discord，未来支持更多平台。 ✨

Scrapbook (默认)	Retro Futurism	HatsuneMiku
Hack	ATRI	BlueArchive

参考 Atri 人格的群每日漫画 Demo

• 统计数据: 全面的群聊活跃度和参与度统计
• 话题分析: 使用LLM智能提取群聊中的热门话题和讨论要点
• 用户画像: 基于聊天行为分析用户特征，分配个性化称号
• 圣经识别: 自动筛选出群聊中的精彩发言
• 每日群漫画: 将本次分析结果改编为趣味连环漫画，支持图生图参考图和独立绘图服务

• 内嵌管理面板: 原生集成在 AstrBot 插件管理页面，无需额外部署，支持查看运行概览、分析记录与历史报告列表
• 报告浏览与主题切换: 历史报告可直接在控制台在线预览（长图与 HTML 均支持），支持一键下载；也可免费切换视觉主题（手账、亚托莉、蔚蓝档案、初音未来、黑客赛博、复古像素、极简等）重新生成报告，直接复用已保存的分析数据，无需再次调用 AI，0 Token 成本
• 任务与报告双向关联: 在任务详情中可直接查看对应产生的所有报告文件；从历史报告中点击任务编号，可快速跳转到该次任务的执行明细，并且可快速查看和检索任务日志
• 全流程可观测: 每次分析任务（含群漫画）的各阶段耗时、大模型产出内容、Token 分布、子模块启停状态与异常原因均可在控制台查看，出了问题知道问题在哪
• 数据统计与消耗追踪: 按群、按时间、按状态多维筛选历史分析记录，查看消息清洗数量与各模块 Token 消耗分布
• 异常任务自动清理: AstrBot 重启时自动标记并清理未正常结束的中断任务，不留烂尾

分析记录	任务执行详情与断点续跑
任务执行详情（子模块状态与异常诊断）	历史报告列表
统计与消耗	运行日志

• 多种格式: 支持图片和文本输出格式
  • 精美图片: 生成美观的可视化报告
  • HTML报告: 生成清晰的HTML格式分析报告，可以进一步配置为外链形式发送
  • QQ群: 支持上传到群相册和群文件，查阅黑历史友好
• 详细数据: 包含消息统计、时间分布、关键词、金句等

• 多平台支持: 自动识别并适配 OneBot, QQ 官方机器人, Discord, Telegram 等平台
• 群组管理: 支持指定特定群组启用功能（支持跨平台黑白名单）
• 参数调节: 可自定义分析天数、消息数量等参数
• 定时任务: 支持设置每日自动分析时间
• 增量分析: 全新的滑动窗口分析模式，全天候覆盖群聊消息
• 自定义LLM服务: 支持自定义指定的LLM服务

每日群漫画不按自然日限流：每次成功得到群分析结果时都会尝试生成一张。手动群分析、定时传统分析、定时增量最终报告，以及开启“增量分析立即报告”后的即时增量最终报告都适用。同一群已有漫画在排队或生成时，新请求会直接跳过，避免重复出图；不同群仍受漫画并发配置限制。

也可以使用 /群漫画 [天数] 单独生成漫画。这个命令只拉取消息、提取话题并启动漫画生成，不会生成日报、称号、金句、聊天质量，也不会写入日报历史。

1. enable_daily_comic 是漫画总开关：关闭时，手动 /群漫画 和所有自动联动漫画都不会出图。
2. enable_auto_daily_comic 是自动联动开关，默认开启。它同时控制手动群分析、定时分析和增量最终报告完成后的漫画生成；关闭后仍可使用 /群漫画 按需出图。
3. 如果希望“群分析完成后自动联动漫画”，需要在 分析功能 配置组保持 topic_analysis_enabled 开启，让漫画直接复用报告已提取的话题；手动 /群漫画 会单独提取话题。
4. 使用 漫画群名单模式 和 漫画群白/黑名单列表 控制哪些群可以生成漫画。默认 inherit 会继承基础群权限：分析报告触发的漫画会直接复用已通过的手动/定时/增量入口判定，不需要重复填写名单。若只想开放漫画、不开放分析，可把漫画名单模式改为 blacklist（空列表=所有群允许）或 whitelist（只允许列表里的群）。
5. 可选切换绘图后端 drawing_backend：builtin（默认，使用本插件内置绘图客户端）；general_plugin（调用 「通用生图」插件 公共 API）；big_banana（调用 「大香蕉」插件 绘图管线）。外部后端需在对应插件中配置其自身的 API/提供商。外部后端失败时由 drawing_external_fallback 决定是否回退内置后端（默认回退，关闭则直接取消本次漫画）。
6. 在 绘图供应商配置表 点击“添加条目”，选择与上游服务匹配的预设；每个条目独立填写 API Key、端点、模型、尺寸、宽高比、超时与可选代理。至少保留一个启用且包含 API Key 的条目。
7. 多个条目按 priority 从高到低尝试；优先级相同时按表中顺序尝试。当前条目请求失败后会自动切换到下一个候选，全部失败才判定本次漫画生成失败。
8. 可选填写 drawing_prompt_provider_id。它用于把分析结果整理成绘图分镜提示词；留空时使用插件的常规 Provider 回退策略。
9. 可选在 漫画角色方案 中新增一个或多个方案：每个方案可单独选择漫画专用人格、编辑漫画场景分析提示词，并上传 jpg、jpeg、png 或 webp 参考图；没有参考图时仍会走文生图。具体会发送多少张参考图取决于当前绘图供应商的能力和条目上限。
10. 默认固定使用第一个已启用角色方案。开启 每天随机切换漫画角色 后，插件会在运行环境时区的每天首次生成漫画时随机选择一个已启用方案，并在当天持续使用同一方案；优先读取 TZ 环境变量，未设置或无效时使用系统本地时区。角色方案内的人格和场景提示词只作用于漫画分镜提示词，不会改变话题、金句或最终报告的人格。
11. 升级前已配置的 漫画参考图 会自动迁移为 默认角色方案，迁移前数据会备份到插件数据目录的 config_backups。既有角色方案会继承升级时的全局漫画场景分析提示词；新建角色方案自带默认提示词，清空后回退到全局默认模板。

致谢：@piexian/astrbot_plugin_gemini_image_generation

供应商预设负责将漫画分镜和角色参考图转换为各家的原生请求格式。是否可用仍取决于你的账号权限、模型名称、区域和上游服务状态；选择 OpenAI 兼容 Chat 预设时，也需要上游模型本身能够在聊天响应中返回图片。

所有条目均可单独配置 proxy；条目代理优先于全局 drawing_proxy，全局代理也会用于下载同次生图响应中的图片。请求超时按条目配置，重试、下载代理和投递策略仍为全局设置。

分析结果完成后，自动联动漫画会立即在后台运行，报告渲染与发送不会等待出图完成。反过来，报告发送失败也不会取消已经开始的漫画任务。自动联动只复用报告中的有效话题总结，因此需要开启话题分析；话题功能关闭、话题 LLM 无结果或标题为空时会跳过本次自动漫画。手动 /群漫画 则会独立提取话题，不依赖报告功能开关。

下面只讲“在面板里怎么点”。

系统会按下面顺序判断，前一关没过就直接停止：

1. 基础群权限（basic）
2. 定时分析名单（auto_analysis）
3. 增量名单（incremental，只决定模式，不决定放行）

一句话版：
basic 决定“能不能参与自动分析” -> auto_analysis 决定“会不会自动触发” -> incremental 决定“触发后用哪种分析方式”。

inherit 不保存或复制任何名单，而是在判定时复用上一级的最终结果：

因此，最省配置的组合是：基础名单填一次，定时分析设为 inherit，增量分析也设为 inherit。名单变更后，定时目标和增量消息计数状态会按新的继承结果刷新。

兼容性边界：定时分析和增量分析仍默认 whitelist，且空列表仍表示未启用，升级不会意外创建自动任务。只有显式改为 inherit，才会开始继承上一级名单。

1. 在插件配置面板找到 定时分析设置。
2. 把 定时分析名单模式 设为 whitelist。
3. 在 定时分析群列表 里添加你的目标群（建议粘贴 /sid 拿到的完整会话ID）。
4. 在 自动分析时间列表 里填时间（例如 09:00、21:30）。
5. 去 增量分析设置：
6. 把 增量分析名单模式 设为 whitelist，并保持 增量分析群列表 为空。
   这样就是“这个群会自动跑，但走普通分析，不走增量”。

1. 在 定时分析设置 里把 定时分析名单模式 设为 blacklist。
2. 在 定时分析群列表 里填“不要自动跑”的那个群。
3. 在 自动分析时间列表 里填每天自动运行时间。
4. 如果你希望其他群默认走增量：
5. 在 增量分析设置 把 增量分析名单模式 设为 blacklist，并把 增量分析群列表 留空。

1. 在 基础设置 配置群聊白名单或黑名单。
2. 在 定时分析设置 把 定时分析名单模式 设为 inherit。
3. 在 增量分析设置 把 增量分析名单模式 设为 inherit。
4. 在 自动分析时间列表 填入需要的时间。

例如，基础白名单只填写群 A、群 B 后，定时任务只会处理 A、B，且 A、B 都会走增量；不用再把 A、B 填到后两组列表。

1. 在面板里需要填群的地方，尽量填完整会话ID（例如 telegram2:GroupMessage:-1001234567890）。
2. 不建议新手只填纯群号，容易填错平台。
3. 先在群里执行 /sid，复制结果粘贴到列表里就行。

• 定时分析名单模式 选 whitelist 时，如果 定时分析群列表 为空，任务不会自动跑。
• 增量分析名单模式 选 whitelist 时，如果 增量分析群列表 为空，增量不会生效，会走普通分析。
• 定时分析设为 inherit 时，基础白名单为空也不会有自动目标；基础黑名单或无限制模式则会让所有未被基础名单排除的群成为自动目标。
• 增量分析设为 inherit 时，所有通过定时名单的群都会走增量；若只想让部分群增量，请改用 whitelist 或 blacklist。
• 增量失败自动回退全量分析 建议保持开启，这样增量异常时也能尽量产出报告。

• 不在“定时白名单”里，但在“增量白名单”里，会触发吗？
  不会。因为会先被“定时白名单”拦住，进不到增量判断。

• 不在“基础群权限”里，但你开了定时分析，会触发吗？
  不会。基础群权限是第一关，不通过就不会进入后续流程。

/群分析 [天数]

• 分析群聊近期活动
• 天数可选，默认为1天
• 例如：/群分析 3 分析最近3天的群聊

/群漫画 [天数]

• 单独生成群聊趣味漫画，不生成日报
• 天数可选，默认为基础配置中的分析天数
• 例如：/群漫画 3 根据最近3天群聊话题生成漫画

/增量状态

• 查看当前增量分析的实时状态
• 显示当前滑动窗口内的分析次数、消息数、话题数等统计
• 仅在启用增量分析模式时可用

/分析设置 [操作]

• enable: 为当前群启用分析功能
• disable: 为当前群禁用分析功能
• status: 查看当前群的启用状态
• 例如：/分析设置 enable

/查看模板
/设置模板 [模板名称或序号]

• /查看模板: 查看所有可用模板及预览图
• /设置模板: 查看当前模板和可用模板列表
• /设置模板 [序号]: 切换到指定序号的模板
• 例如：/设置模板 1 或 /设置模板 scrapbook

增量分析模式是为了解决消息量大的群聊（如日均消息 > 500 条）在单次分析时容易丢失上下文的问题。

核心特性：

• 滑动窗口：不再受限于自然日，分析窗口随时间滑动（如过去 24 小时），确保任何时候生成的报告都覆盖完整的时间段。
• 按量分批：目标群每累计到配置的消息数就执行一个固定规模批次，平滑 LLM 负载。
• 自动去重：智能识别重复话题和金句，合并生成最终报告。

启用方法：

• 通过 incremental_group_list_mode + incremental_group_list 指定哪些群走增量模式，并使用 incremental_min_messages 设置每批触发消息数。

如果你希望在群里发送的不是图片，而是一个可以点击跳转的精美网页链接，可以使用 HTML 格式输出。

1. 设置输出格式：在 basic 设置中将 output_format 改为 html。
2. 指定储存目录 (html_output_dir)：设置 HTML 文件在服务器上的保存路径。留空则默认保存在插件数据目录。
3. 配置外链基址 (html_base_url)：这是关键。如果你使用 Nginx/Apache 等 Web 服务器将上述目录映射到了公网，请在这里填写访问的前缀（如 https://report.example.com）。

• 机器人生成 HTML 报告并保存到本地目录。
• 机器人根据文件名和 html_base_url 拼接成完整链接发送到群里。
• 注意：本插件不提供 Web 服务器功能，你需要自行使用 Nginx 或 AstrBot 所在的服务器环境来实现静态文件的公网访问。

插件支持深度的“人格化”分析，让 AI 能够以特定的人设风格（口吻、偏好、语气）来产出摘要和锐评。

插件在构建分析任务时，会按以下顺序确定最终使用的“人设状态”：

1. 强制插件人格 (优先级最高)：在配置中开启 强制使用插件指定人格 并选择 ID。此时 全平台、所有群聊 都会统一使用这一种人设，忽略群聊本身的设置。
2. 继承会话人设 (优先级次之)：在配置中开启 继承会话人设风格。插件会尝试识别当前群聊在 AstrBot 中设置的人格（如通过 /persona 指令设置的人设）。如果该群已有人设，分析报告将尽量模拟其说话倾向。
3. 系统默认人设：若上述开关均关闭，或未识别到有效人设，则回退到当前默认设定。

插件支持动态加载和实时识别用户自定义或第三方的报告视觉排版模板：

1. 模板存放路径： 放置于插件数据目录 custom_t2i_templates/reporting_templates/<模板英文或拼音目录名>/（例如 custom_t2i_templates/reporting_templates/genshin/）。
2. 完整模板文件组成（标准的报告主题共包含以下 7 个 Jinja2 HTML 模板）：
   • image_template.html：长图海报主骨架（接收并组合以下各小模块生成的 HTML 片段）。
   • html_template.html：独立网页报告主骨架。
   • topic_item.html：话题总结列表模块（渲染 topics_list）。
   • user_title_item.html：群友称号与画像模块（渲染 titles_list、头像与 MBTI 标签）。
   • quote_item.html：群友金句与锐评模块（渲染 quotes_list）。
   • activity_chart.html：24小时活跃轨迹折线图/热力图模块（渲染 chart_data）。
   • chat_quality_item.html：群聊质量多维锐评模块（渲染质量得分与维度评价）。
3. 支持局部修改与自动兜底：
   • 全量深度定制：提供全部 7 个 HTML 文件，实现从页面主视觉到各个子卡片组件的 100% 定制。
   • 轻量局部定制：如果仅针对长图外框或主布局进行微调（例如仅提供了 image_template.html），插件的 Jinja2 多层回退引擎会自动使用默认手账模板（scrapbook）中对应的小模块 HTML 作为兜底加载，确保即使子模块不全也能稳定渲染。
4. 即选即用： 放入新模板目录后无需重启机器人，在 Web 控制台的 断点续跑弹窗 与 报告归档管理（免 Token 切换主题重绘） 下拉菜单中均会自动实时出现该选项。

插件会在每次正常启动时记录当前版本、配置结构和模板基线。后续只要检测到配置结构发生变化，就会把上一次正常加载的插件配置快照保存到插件数据目录（注意不是插件目录）的 config_backups；文件名包含旧版本和备份时间，只保留最新二十份。插件版本仅用于标识备份来源，不是备份条件；调整描述或提示文本不会生成备份。日志会显示旧版本、备份文件名和完整路径。通过 WebUI 修改配置后，请正常重载插件或重启 AstrBot，使该配置成为下一次升级可保护的快照。

如果直接修改了插件目录中的报告 T2I HTML 模板，修改后请至少重载一次插件或重启 AstrBot。插件会将已修改文件复制到插件数据目录的 custom_t2i_templates，后续报告渲染优先使用该副本；未修改的模板仍跟随插件升级。data/t2i_templates 中的独立 HTML 也会保存到该目录，供手动取回。插件目录已被更新覆盖后才首次启动时，旧文件已不存在，无法再由插件恢复。

AstrBot 更新插件时会先删除旧插件目录，再解压或移动新目录，并在实例化插件前依据新 schema 清理旧配置项。因此插件无法在更新后的目录中读取旧版本文件；升级保护依赖上一次正常启动预先保存的配置快照。WebUI 每次保存都会自动重载插件，正常保存过的配置会成为下一次升级可保护的快照；首次安装本保护功能前已经升级丢失的数据，以及手工改配置后未重载就立即更新的数据，插件无法事后恢复。

现象： 后台日志出现 [warn] ... 似乎是旧版客户端 ... [error] ... 获取不到带记录的引用消息。

原因： 这是由于 NapCat/NTQQ 消息 ID 格式变动、消息过期或临时会话限制导致的。机器人尝试降级使用旧版序号查找失败。

忽略：如果只是偶尔出现（如回复久远消息），不影响机器人核心功能（收发消息），可以直接忽略。

我们非常欢迎社区参与插件的开发与改进！

如果你希望：

• 🛠️ 参与 Python 后端或 WebUI 前端代码开发
• 🎨 贡献新的精美视觉模板（提供离线热调预览工具）
• 🐛 提交 Bug 修复或性能优化 PR
• 📝 了解代码规范（Google-style Docstring、FSD、0 any、Ruff 格式化、Conventional Commits）

👉 请参阅完整的 贡献指南 (CONTRIBUTING.md)。

❤️ 特别感谢所有 Contributors 的贡献 ❤️

MIT License

欢迎提交Issue和Pull Request来改进这个插件！