astrbot_plugin_qq_group_daily_analysis

群聊日常分析插件

QQ群	Telegram群

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

• 常见问题 (FAQ)
• 效果
• 功能特色
• 配置选项
• 每日群漫画配置
• 使用方法
• 大模型原生函数调用 (LLM Tools)
• 平台支持与要求
• 增量分析模式
• 图片报告与 Typst 本地渲染
• 数据与资源管理
• HTML报告与自建外链
• 人格设定 (Persona)

效果

1. 群分析报告：生成群聊活跃度、参与度、话题、金句等统计的可视化报告

HatsuneMiku (默认)	maria	Scrapbook
Hack	ATRI	DeepSeek 鲸鱼女仆娘 deepseek_maid · 素材署名与许可

2. 每日群漫画：将群分析结果改编为趣味连环漫画，支持图生图参考图和独立绘图服务

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

功能特色

🎯 智能分析

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

🎛️ WebUI 控制台

• 内嵌管理面板: 原生集成在 AstrBot 插件管理页面，无需额外部署，集中提供运行总览、分析记录、统计与消耗、历史报告、运行日志、配置中心与数据管理七大板块
• 插件配置中心: 内置专属可视化配置界面，提供 12 个功能分组导航与即时搜索；支持已有人格与大模型服务商下拉点选、漫画参考图本地上传与灯箱预览，修改保存即时生效
• 趋势分析与消耗看板: 支持近48小时、近7天、近14天、近30天等不同时间跨度切换，直观呈现 API 请求走势、大模型 Tokens 消耗堆叠图与服务商消耗占比环形饼图
• 报告浏览与主题重绘: 历史报告支持长图与 HTML 在线预览及一键下载；支持切换视觉主题（手账、亚托莉、蔚蓝档案、初音未来、黑客赛博、复古像素、极简等）重新生成报告，直接复用已有数据，0 Token 成本
• 时序事件时间线: 在统计与消耗页面提供连续水平时间轴，支持鼠标拖拽平移与快速回溯历史样本，直观查看各群聊的消息清洗留存与模块消耗
• 全流程可观测性与实时监控: 运行中任务状态与步骤实时同步感知；任务详情按父子阶段展示分析、素材准备、排队、编译和发送过程，保留重试与恢复原因；Typst 可分别查看编译子进程内存、CPU 耗时与宿主内存净变化
• 任务停止与断点续跑: 群内手动分析沿用 AstrBot 内置 stop，WebUI 任务可在运行总览中止；续跑有有效快照的任务时复用已有分析，重复续跑也继承原任务数据与分析日期
• 字体、素材与存储管理: 可从 Typst 方案直达字体或素材管理，按主题补齐、上传及替换；报告文件支持搜索、类型筛选与多选删除，自定义模板按实际目录选择管理，详见数据与资源管理
• 任务与报告双向关联: 在任务详情中可直接查看对应产生的所有报告文件；从历史报告中点击任务编号，可快速跳转到该次任务的执行明细与日志
• 异常任务自动清理: AstrBot 重启时自动标记并清理未正常结束的中断任务，不留烂尾

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

📊 可视化报告

• 多种格式: 支持图片、文本与 HTML 输出格式
  • 精美图片: 可通过 AstrBot T2I、自定义 T2I 服务或插件独立 Typst 引擎生成报告长图；Typst 无需浏览器，支持内置主题，详见启用方法
  • HTML报告: 生成清晰的HTML格式分析报告，可以进一步配置为外链形式发送
  • QQ群: 支持上传到群相册和群文件，查阅黑历史友好
• 详细数据: 包含消息统计、时间分布、关键词、金句等

配置选项

每日群漫画配置

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

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

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，增量分析也设为 inherit。名单变更后，定时目标和增量消息计数状态会按新的继承结果刷新。

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

场景 A：只让一个群自动出报告（最常用）

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

场景 B：除了某个群，其他群都自动跑

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

场景 C：名单只填一次，所有自动群都走增量

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

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

场景 D：Telegram 用户怎么填最稳

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

最容易踩坑的 5 点

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

你可能会问（关键边界）

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

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

使用方法

基础命令

群分析

/群分析 [天数]

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

手动分析进行中，可在同一会话发送 AstrBot 内置的 /stop（前缀跟随 AstrBot 配置，如 *stop）。插件通过宿主后台任务登记和共享停止信号取消关联的分析、渲染和后续发送，不额外注册 stop 命令，也不覆盖宿主 Agent 的停止回调。启用群内用户会话隔离时，需要由原发起人在同一机器人实例下发送。不提供后台任务登记的旧版宿主依赖内置 stop 写入前台事件停止标记；如果旧版第三方 Agent 只终止事件传播，需要升级宿主。WebUI 或定时任务请在任务面板中止。

群漫画

/群漫画 [天数]

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

增量状态

/增量状态

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

分析设置

/分析设置 [操作]

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

模板设置

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

• /查看模板: 查看可用模板及预览图；QQ 官方 Bot 每次展示一张，可用按钮填入翻页或切换命令，没有相关权限时使用普通消息
• /查看模板 [序号或名称]: 查看指定模板，例如 /查看模板 2；查看和设置仍需管理员权限
• /设置模板: 查看当前模板和可用模板列表
• /设置模板 [序号]: 切换到指定序号的模板
• 例如：/设置模板 1 或 /设置模板 scrapbook

发送预览时会自动转为 JPEG 并复用缓存，兼容平台图片接口；WebUI 画廊仍使用 WebP。

大模型原生函数调用 (LLM Tools)

插件原生接入 AstrBot @filter.llm_tool 规范，为宿主大模型（Agent）注入群聊分析记忆与调度能力。用户无需记忆任何 / 斜杠指令，在日常自然语言对话中即可与 AI 助手无缝交互：

群友: "今天群里聊了什么？大家都在讨论什么热点话题？"
AI:   (自动调用 group_daily_analysis_get_report)
      "今天群里主要讨论了两个话题：1. Docker 容器网络配置... 2. 新番讨论..."

管理员: "帮我重新分析一下今天的群聊，发到群里"
AI:     (自动调用 group_daily_analysis_trigger)
        "已为您提交今日群聊的异步重算任务（预计耗时约 1 分钟）。分析完成后将自动把长图推送到本群！"

原生工具矩阵

工具特性与设计亮点

1. 只读报告检索 (group_daily_analysis_get_report)：

   • 4 级群目标自适应解析（防反问）：群聊环境中调用时自动精准绑定当前群；私聊中支持群名模糊搜索；出现重名时返回候选列表引导用户。大模型无需反复向用户追问群号。
   • 弹性自然语言日期：无缝支持 今天、昨天、前天 以及标准 YYYY-MM-DD 格式；当指定日期尚无报告时，自动向后滑动探测最近一天的有效快照。
   • 同日多版本窗口去重：底层基于 SQL 窗口函数，即使一天内手动或定时多次触发，永远仅返回最新生成的一份有效报告。
   • 跨平台脱敏与格式清洗：自动将话题发言人中的纯数字 ID / OpenID 清洗替换为真实群昵称；过滤空称号与无效空行。
   • 防爆流安全截断：文本输出上限严格控制在 40,000 字符以内，防止超长记录击穿模型上下文窗口。

2. 按需异步触发 (group_daily_analysis_trigger)：

   • 严格管理员双重鉴权：仅限群主、群管理员、Bot 全局管理员及配置白名单用户触发，普通成员越权触发时秒级拦截并引导其使用只读检索工具，防止昂贵分析流水线被闲聊误刷。
   • 异步非阻塞受理（Fire-and-Forget）：群分析全量流水线通常需要约 1 分钟，触发工具在 500ms 内向大模型返回 Trace 受理凭证，将计算任务转交后台协程异步执行，彻底消除对话端 30s HTTP 阻塞超时与 504 网关中断隐患。
   • 长图推送与静默模式双轨 (render_to_chat)：
     • 默认发图 (render_to_chat=True)：符合用户自然期待，分析完成后自动调用派发器将渲染出的高清日报长图发送至目标群聊。
     • 静默入库 (render_to_chat=False)：当明确要求“后台更新不要发群”时，仅完成数据持久化落库，不打扰群友。
   • 群级并发排他锁：群粒度互斥锁保护，防止同一群聊并发重复触发分析任务。

平台支持与要求

[!IMPORTANT] QQ 官方机器人用户注意： 插件同时支持 AstrBot 的 qq_official 与 qq_official_webhook 平台。

• 在群聊中需要由群主允许机器人接收群内全部消息，使 AstrBot 能收到 GROUP_MESSAGE_CREATE 事件；只开放 @ 消息时，报告只能覆盖 @ 机器人的聊天。
• QQ 官方 API 不提供“按群拉取历史消息”的接口。插件会从启用后开始实时保存消息，并从 AstrBot 本地消息历史库分页读取；启用前的群聊无法自动回填。
• 官方群和成员使用 group_openid / member_openid，不是群号或 QQ 号。配置白名单、定时任务时建议先在群内执行 /sid，填写完整 UMO。
• 新分析会通过官方接口查询群名并显示在任务记录中，无需新增配置。群名会缓存一小时；权限不足、限流或网络失败时保留上次获取的群名或 OpenID，五分钟后可再次尝试，不影响分析和发送。已有历史记录不会批量改名，群名查询也不用于判断管理员权限。
• 官方群事件提供有效昵称时会用于报告；昵称缺失时使用群内稳定匿名名，避免直接展示 member_openid。
• 表情统计只采用本条原始事件的 <faceType=…> 标记或明确的 Face 组件，入库保存类型、标识与必要的可读名称，历史读取后用于群统计、个人统计及增量合并。同一消息重复接收不会重复入库；同一条正文中重复使用的表情按实际次数记录，引用消息中的表情不重复计算。
• QQ 官方附件无法仅凭 URL、GIF 后缀或文件名可靠区分普通图片与表情包，因此图片保持图片类型，不一律计为表情；纯文本 Unicode emoji 也不额外扫描，不增加相关依赖。旧记录若只剩 [表情:…] 描述，无法确定是否为用户手打文字，不据此补猜表情。
• QQ 官方文本报告使用自定义 Markdown，默认启用透明背景的群聊概览图，将日期、基础统计和 24 小时竖向直方图合并为紧凑布局。可在 QQ 官方机器人 → 启用群聊概览图 关闭（原名称为“启用 T2I 群聊概览图”，配置键不变）。生成或发送概览图失败时恢复包含文字条形图的完整报告。
• 首选图片方案为 Typst 时，使用插件数据目录中的中文字体生成固定 940×423 PNG，通过 QQ 官方素材管理接口上传，获得 qqbot-media:// 引用后与正文在同一条 Markdown 中发送；不需要公网图床，也不会把本地路径或 Base64 塞进 Markdown。请先在数据管理下载中文字体。
• QQ 素材接口有每个机器人 100 张的数量限制；报告发送结束后，插件只删除本次自己上传的素材以释放配额，已发送消息中的图片不受影响。接口不可用或上传失败时使用完整文字报告，不会另发独立图片。
• HTML/T2I 概览图沿用公网 URL 在 Markdown 内嵌入图片；请确保 T2I 端点域名已加入 QQ 开放平台的消息 URL 配置。消息要求 QQ 校验图片转存，失败后使用完整文字报告。
• 本次适配只覆盖普通 QQ 群，不包含频道或子频道。

[!CAUTION] Discord 用户重点注意： 如果机器人无法获取群列表或分析报 403 Forbidden，请检查 Discord 开发者面板中：

1. Privileged Gateway Intents: 开启 Message Content Intent。
2. 频道权限: 确保机器人所在的频道，对应的角色拥有 “查看消息历史记录” 权限。

注意事项

增量分析模式 (Beta)

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

核心特性：

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

启用方法：

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

图片报告与 Typst 本地渲染

选择渲染方式

图片报告可按优先级依次尝试不同方案：

Typst 只生成静态图片，支持 PNG 和 JPEG；HTML 网页报告仍走 HTML 模板，保留网页交互与动效。远程 T2I 通常无法访问机器人本机的文件，给 Typst 下载字体或素材不会让远程 HTML 渲染器自动使用它们，HTML 默认仍使用 CDN 字体和图片。

目前内置主题提供 Typst 排版。各主题保留自身配色和主要组件结构；静态图片不包含 HTML 的响应式布局、折叠或动画。

启用 Typst

1. 升级插件并确认依赖安装成功。若提示缺少 typst，通过 AstrBot 插件依赖安装流程补装后重载插件。
2. 打开插件 WebUI「配置中心 → 图片渲染策略 → 图片渲染方案」，点击「添加渲染方案 → Typst 本地排版」。希望首先使用本地渲染时，设置比其他方案更小的优先级；同优先级按列表顺序执行。已有 T2I 方案可保留用于失败回退。
3. 在该方案的「Typst 字体」选择报告主题，点击「下载所选模板字体」；在「模板原始素材」选择同一主题并下载缺失素材。只需准备所用主题，共享文件自动复用，也可一次补齐全部预设资源。
4. 在「基础设置」选择「报告模板」，并在「输出格式（可多选）」中包含 image。手动分析使用首个选中的输出格式，希望手动生成图片时请将 image 放在首位。方案内的 PNG / JPEG 是图片文件格式，与这里的 image / text / html 报告类型不同。
5. 保存配置。可先点击方案内的「测试渲染」验证编译器能否出图；测试不调用大模型、不向群发送消息，也不能代替完整主题的字体和素材检查。随后使用群内「群分析」命令或 WebUI「手动触发分析」生成报告。

字体与素材下载、上传

方案内的「管理 / 上传字体」和「管理 / 上传模板素材」可直达同一套数据管理面板，带上所选主题和下载来源；返回方案后保留未保存的配置。

• 字体来源：默认「CDN 优先（大字库直连）」，也可切换为「GitHub Raw 直连（全部字体）」。ATRI 文楷、Miku 全瀨體等大字体本身就从固定版本 Raw 下载，更换 CDN 不会改变这些直连地址。下载由机器人服务器或容器执行，浏览器能访问不代表服务端能访问；Raw 受限时需检查服务端网络或代理。
• 下载进度与取消：字体显示当前文件、实际来源、接收字节与等待时间，素材显示完成数量与失败文件。下载可以取消，已完成文件保留；失败重试只补缺失项，可切换 CDN 或字体来源后再试。
• 手动补字体：在字体管理对应行点击「查看上游」核对版本，或使用「直接下载」在浏览器下载，再点击该行「上传此字体」，自动按预设文件名保存。上传显示进度并支持取消；普通「上传字体」保留文件名，适合自定义字体。若提示宿主不支持二进制上传，请升级 AstrBot 后重试。
• 逐文件补素材：进入「模板原始素材 → 主题素材管理」，选定主题并展开「素材文件与状态」，可上传或替换清单中的单个文件；「本地素材与替换」管理已保存到插件 data 的文件。资源优先本地复用，尚未准备的装饰图会在渲染时尝试从方案 CDN 获取，缺图时记录警告并降级展示。
• 共享影响：替换或移除字体可能影响多个主题，操作前可查看依赖关系。

清晰度、超时与运行开销

Typst 排版固定为 940px 逻辑版心，高度随内容增长。方案的「导出清晰度（PPI）」只改变像素密度，不改变字号、换行和布局：

PNG 无损，调节「JPEG 质量」不会改变 PNG 清晰度。超长报告会在导出前根据像素预算逐档降低密度，任务详情显示请求值与实际值。提高 PPI 会增加栅格导出耗时和内存，不能保证本地渲染比远程 T2I 更快；多个原生编译任务共用编译名额，排队可以避免同时生成长图叠加内存峰值。

「单次编译超时（毫秒）」默认 30000（30 秒），仅限制每次编译进程，素材准备与排队另计；主题编译和基础恢复分别计时，整轮图片生成仍受五分钟总上限约束。主题失败或超时时，会尝试以标准密度的基础排版保留正文；仍失败时继续尝试已配置的其他方案，最终无法出图时回退文字。主动取消不会继续恢复或尝试下一方案。

耗时较长时，打开「分析记录 → 详情」，逐层展开图片渲染阶段，查看素材、排队、布局与栅格导出耗时。开启运行时遥测后还可查看编译子进程 RSS 峰值、峰值增长与 CPU 耗时；「宿主 RSS 净变化」仅表示 AstrBot 进程变化，不能代替编译内存占用。父阶段包含子阶段耗时，各层百分比不要直接相加。CPU 较弱、报告较长或密度较高时，可降低 PPI，或根据实测调整单次编译超时。

数据与资源管理

打开插件 WebUI「数据管理 → 存储空间概览 → 存储分区明细与管理」，可查看各类数据占用，并进入对应管理页：

文件列表包含「Typst 模板（.typ）」等类型筛选。多选删除每批最多 200 项，改变筛选条件会清空选择，防止误删隐藏项；覆盖和删除会校验文件版本，遇到其他页面刚修改过的文件时请刷新后再操作。增量批次、阶段快照与分析存档也提供相应的查询和管理入口，无需直接编辑数据库文件。

WebUI 手动分析可从「运行总览 → 正在执行中的分析任务 → 中止」取消。取消请求接受后仍需等待后台资源回收；运行状态、分析记录与任务详情会同步更新。任务失败后可在详情中续跑，有有效分析快照时复用已经完成的 LLM 分析；历史记录只有摘要时不能还原完整结果。

HTML 报告与自建外链

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

1. 配置流程

1. 设置输出格式：在「基础设置」的「输出格式（可多选）」（output_format）中选择 html；手动分析希望直接发送网页时，将它放在首位。
2. 指定储存目录 (html_output_dir)：设置 HTML 文件在服务器上的保存路径。留空则默认保存在插件数据目录。
3. 配置外链基址 (html_base_url)：这是关键。如果你使用 Nginx/Apache 等 Web 服务器将上述目录映射到了公网，请在这里填写访问的前缀（如 https://report.example.com）。

2. 工作原理

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

人格设定 (Persona)

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

人格识别优先级

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

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

自定义与第三方报告视觉模板

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

1. 模板存放路径： 放置于插件数据目录 custom_t2i_templates/reporting_templates/<模板英文或拼音目录名>/（例如 custom_t2i_templates/reporting_templates/genshin/）。

2. 按所需输出提供入口：

   • report.typ：Typst 图片入口，可以独立组成 Typst 模板，也可与 HTML 入口共存；接收运行时提供的 data.json，使用固定 940px 逻辑版心，高度自然延伸。

   HTML 主题可包含以下 7 个 Jinja2 文件，分别提供长图、网页与子模块排版：

   • 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 作为兜底加载，确保即使子模块不全也能稳定渲染。
   • Typst 失败恢复：主题编译失败后尝试基础排版保留正文。HTML 与 Typst 主入口各自独立，不会把缺少入口的主题当作另一种引擎的完整实现。

4. 即选即用： 放入新模板目录后无需重启机器人。配置、断点续跑和历史报告重绘按当前渲染引擎及输出格式筛选兼容入口，展示 HTML 图片、HTML 网页、Typst 图片等支持标签；只有 Typst 入口的模板不能用于 HTML 网页输出。

5. 在线安装与卸载： 在 Web 控制台配置页的模板选择器旁点击「安装模板」，可通过 GitHub 仓库链接 （如 https://github.com/owner/repo，支持 /tree/<分支>）自动下载安装， 或直接上传 zip 压缩包；安装后立即生效，可随时通过「卸载模板」移除。 也可在「数据管理 → 存储分区明细与管理 → 自定义报告模板」安装模板包，通过可搜索的选择器进入指定模板，维护源码与素材。安装包、手动创建的模板及缺少有效入口的目录均可按整组移除；内置模板不可卸载。删除整个模板前请确认没有群聊仍在使用它。 📖 完整模板制作指南（变量契约、回退机制、打包规范、调试、贡献清单）见 《报告视觉模板开发指南》，参考示例仓库：lingyun14beta/daily-analysis-report-theme。

插件更新升级配置保护

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

官方内置模板（src/infrastructure/reporting/templates/）与用户自定义模板（data/plugin_data/astrbot_plugin_qq_group_daily_analysis/custom_t2i_templates/reporting_templates/）完全解耦分离。内置模板跟随插件统一升级维护，自定义模板可在 WebUI「安装模板」或通过独立目录存放，无需改动源码，升级不丢失。

AstrBot 更新插件时会先删除旧插件目录，再解压或移动新目录，并在实例化插件前依据新 schema 清理旧配置项。因此升级保护依赖上一次正常启动预先保存的配置快照。WebUI 每次保存都会自动重载插件，正常保存过的配置会成为下一次升级可保护的快照。

常见问题 (FAQ)

获取不到带记录的引用消息

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

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

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

图片生成失败 / 渲染返回非图片数据 / 头部 496e7465726e616c... 的排查指南

以下排查针对 HTML / T2I 服务。若使用「Typst 本地排版」，请先查看本地渲染的超时与开销说明，并在任务详情区分素材下载、排队、编译和编码耗时；Typst 不使用 Playwright / Chromium。

🔍 报错根因拆解

十六进制 496e7465726e616c2053 转为 ASCII 文本即为 Internal S（Internal Server Error）。说明 T2I 渲染服务在调用 Playwright / Chromium 无头浏览器生成T2I时遭遇了内部错误或超时，向 AstrBot 返回了 HTTP 500 纯文本而非合法的 PNG/JPEG 二进制图片流。

🛠️ 典型根因与排查解决手段

README 内容过长，已截取前 64 KB。完整内容请前往 GitHub 仓库查看。