Bot 公共核心

bot_core 为各业务插件提供共用配置、数据库、权限、插件开关、Web 后台和 Markdown 消息渲染，版本独立维护在 plugins/versions.py。它随 Bot 常驻运行，不提供群级开关。

代码归属

Web 后台中的管理套件功能仍调用管理套件的业务处理函数；其他插件的后台接口仍由各插件实现，公共核心负责承载 HTTP 服务、登录和权限控制。修改公共后台不再要求管理套件跟随升级；同时修改业务处理时，才更新对应业务插件版本。

后台按 Bot、成员和群缓存 QQ 群角色，成功结果保留 5 分钟，查询失败保留 15 秒后重试；刷新时允许使用平台缓存。首次查询并行执行，每项最多等待 5 秒，同一查询的并发请求共用结果。到期刷新失败时拒绝该群访问，不沿用旧权限。Bot 重新连接后重新查询；群开关、管理分组、超管身份和超管后台群限制仍在每次请求时检查。QQ 端角色变更受这段缓存及平台缓存的刷新时间影响。

共用数据库目前集中保留已有表和迁移，避免拆库或改变数据路径。Config 中原有环境变量、manager.* 运行时配置键、数据库文件、消息接口和后台 URL 均保持兼容。

插件接入

业务插件在导入公共模块前声明依赖：

from nonebot import require

require("plugins.bot_core")

from plugins.bot_core.database import plugin_config, store
from plugins.bot_core.permissions import permissions
from plugins.bot_core.plugin_settings import plugin_settings
from plugins.bot_core.messages import Markdown, render_message, render_text_panel

require 保证公共核心先加载，多次声明不会重复注册生命周期。单独导入公共配置、权限、渲染器或 Web 模块不会自动导入管理套件业务。实际调用各业务的后台处理器时，才导入对应业务模块。

公共核心启动时初始化数据库，加载 AI 连接、运行时配置和插件开关，初始化响应屏蔽，再启动 Web 服务；关闭时清理 Web 服务。群消息归档队列和维护任务由管理套件维护。群级关闭管理套件不会停止公共后台和其他插件使用的公共能力。

render_text_panel 将已有多行回复排成图片面板，单行提示保持文字，失败时回退完整原文；只在聊天发送入口调用，便于其他入口继续复用文字结果。完整渲染示例及已接入的命令范围见 Markdown 消息渲染。内置中文字体位于 plugins/bot_core/resources/fonts/，部署时须保留字体及授权文件。

版本管理

• pyproject.toml 的 project.version 是合集版本，uv.lock 中的项目版本同步更新。
• PLUGIN_VERSIONS["bot_core"] 是公共核心版本；修改本目录、framework/ 或 frontend/ 的代码时更新它。
• 修改业务插件代码时更新该插件版本；仅修改公共核心，无需更新管理套件或其他业务插件版本。
• 同时修改公共核心与业务插件时，分别更新实际受影响的版本。本次拆分调整了所有业务插件的导入与依赖声明，因此它们各自更新一次版本。
• 合集版本随发布变更更新。新增兼容功能升 minor，兼容修复升 patch，不兼容变更按仓库版本规则处理。文档和测试单独修改不要求升版。

运行状态、后台“插件概览”和公开文档会展示公共核心版本；群聊插件设置只展示可按群启停的业务插件。

验证

uv run --frozen python -m unittest -q tests.test_bot_core tests.test_markdown_messages tests.test_report_renderer
uv run --frozen python -m unittest -q
cd frontend
npm test
npm run build

Markdown 消息渲染

各插件的通用图文通过 plugins.bot_core.messages.render_message 构造 Milky 消息，再交给现有发送入口。Markdown 标记需要转成图片的内容，普通字符串保持文字；参数顺序就是发送顺序。

纯图片

from plugins.bot_core.messages import Markdown, render_message

message = await render_message(Markdown("# 查询结果\n\n**已完成**\n\n- 第一项\n- 第二项"))
await bot.send(event, message)

长内容自动分页，同一个消息中会包含多张 PNG。

命令回复面板

已有的多行文字回复可使用 render_text_panel：首行为标题，其余内容保留换行。图片省略命令标题前的装饰 emoji，避免字体缺字显示为方框；昵称、事项标题等内容中的 Markdown 特殊字符按原文显示。单行提示保持文字，图片渲染失败时回退到完整原文。

from plugins.bot_core.messages import render_text_panel

message = await render_text_panel("群状态\n人数：120/200\n自动清理：关")
await bot.send(event, message)

在聊天发送入口选择需要图片展示的回复，业务查询函数仍返回文字，供 Web 后台等入口复用。目前转换范围如下：

操作确认、错误和进度提示保持文字。群回复保留真正的 QQ 提及；猜干员结束提示和积分保存失败提示保留文字，明细使用图片。下载和后台登录链接、排班查询中的档案 ID、结果 ID 及翻页命令继续使用文字，方便点击和复制。问答自动回复与 MaiBot 转发内容沿用原有消息形式。

今日方舟专属卡片

今日方舟 使用 plugins.arknights_reminders.today_renderer 直接绘制深色方舟风格卡片，不经过 Markdown。today.py 先汇总结构化事项和查询入口，图片与失败时的文字回复共用这份数据。

长图使用项目自带的常规与粗体中文字体，固定宽 960 像素，高度按全部内容计算，输出单张 PNG。长标题和备注自动换行，常用查询使用命令与说明两列的紧凑行表，操作提示仅在分区标题处显示一次。render_today_png 返回 PNG 字节，Pillow 在线程中绘制，无需保存临时图片；任一步失败时回退完整文字，群回复仍保留真正的 QQ 提及。

关键通知保留文字，详情转成图片

from nonebot.adapters.milky import MessageSegment

from plugins.bot_core.messages import Markdown, render_message

message = await render_message(
    MessageSegment.mention(user_id),
    "\n⚠️ 任务需要处理，请先查看截止时间。\n",
    Markdown("## 详细信息\n\n| 项目 | 状态 |\n| --- | --- |\n| 构建 | 失败 |"),
    "\n处理入口：https://example.com/tasks/123",
    fallback="⚠️ 构建失败，请查看 https://example.com/tasks/123",
)
await bot.send_group_message(group_id=group_id, message=message)

可以继续交替传入文字和多个 Markdown 块，也可以传入现有 Message 或 MessageSegment。换行由调用方显式写入，接口不会额外添加分隔符。只传普通文字或消息段时，直接构造消息，不执行图片渲染。

返回值也可以交给框架的 ctx.reply(message)、bot.send_private_message(...) 等现有入口。接口只构造消息，权限校验、目标选择、发送失败和重试由调用方处理。网站通知、Codex / Pi 通知及上述命令面板均使用公共消息渲染接口。

排版与失败回退

支持中文、标题、粗体、斜体、删除线、列表、引用、表格、分隔线、代码块和链接；链接地址会显示在图片中。HTML 按文字处理，Markdown 图片语法显示替代文字，不读取本地图片或下载远程图片。需要可点击的链接、可复制的命令或真正的 QQ 提及时，将它们作为文字或消息段传入。

图片默认宽度为 1280 像素，每页最高 4096 像素。可通过 max_width、max_height 调整；实际范围分别为 640–1600 和 640–8192 像素。渲染和临时文件读写在线程中执行，返回前已将 PNG 读入消息并清理临时目录，无需调用方保留文件。

任一 Markdown 块渲染或图片读取失败时，整个消息回退到文字，不发送残缺的图片。未传 fallback 时，用 Markdown 原文替换图片块，保留其他文字和消息段；传入 fallback 字符串或 Message 时，用它替换整个消息。文字长度限制由调用方根据业务决定，例如通知可传入有长度上限的摘要。

空白 Markdown 块不生成图片。任务取消会正常向外传递，发送异常也由现有发送入口处理。

字体和文件输出

font_path 可指定中文字体路径，不传时使用系统中文字体或 plugins/bot_core/resources/fonts/ 中的内置字体。配置了 ANALYSIS_REPORT_FONT_PATH 的插件应在调用时传入对应的 Path，例如 font_path=plugin_config.analysis_report_font_path。

需要持久保存 PNG 时，使用公共底层接口：

import asyncio
from pathlib import Path

from plugins.bot_core.markdown import render_markdown_to_pngs

paths = await asyncio.to_thread(
    render_markdown_to_pngs,
    "# 报告\n\n详细内容",
    Path("report.png"),
)

输出目录需已存在。第一页使用指定路径，后续页使用 report_2.png、report_3.png 等文件名。render_markdown_to_png 返回第一页路径；长内容需要完整发送时使用复数接口。管理套件原有的 plugins.manager_suite.report_renderer 保留这两个函数的兼容导入；framework.markdown 和 framework.messages 也保留兼容导入。公共能力的版本统一归属 bot_core。

QQ 群管理套件

概述

manager_suite 是 QQ Bot Manager 的群管理业务插件，提供多群管理、成员管理、内容检测、入群验证、消息归档、统计分析、网站通知和操作审计功能。共用配置、数据库、权限、Web 后台和 Markdown 渲染由 Bot 公共核心 提供并独立管理版本。

快速导航

入口与解析

命令入口、成员目标格式和紧凑命令规则见主文档的命令入口。本插件只识别规定的命令格式，自然语言描述不会执行管理操作。

帮助系统

聊天帮助只显示当前入口、账号权限和插件开关允许使用的命令：

@Bot 帮助
@Bot 帮助 <分类>
@Bot 帮助 <命令>

发送 帮助 查看当前可用分类，再发送 帮助 <命令> 查看完整参数。

权限体系

权限由低到高为：

普通成员 < 管理 < 群主 < 超管 < Bot 所有者

专用管理群中的普通成员从该入口操作主分组时，插件按「管理」级别授权；直接在目标群或好友私聊中执行群命令时，仍读取操作者在目标群的实时 QQ 角色。

操作者只能管理权限低于自己的目标。Bot、操作者本人以及同级或更高权限成员受到保护。

管理分组

管理分组让多个受管群共用一套规则。每个群都属于一个分组；未分配的群位于「默认」分组。主分组决定省略分组参数时，全局命令作用于哪些群。

各分组分别保存违禁词、欢迎语、黑名单和问答，互不影响。超管及以上权限可使用以下命令：

命令参考

发言 仅查询目标群已归档且未撤回的消息，以合并转发发送。默认返回最近 20 条，单次可指定 1 至 100 条；超管可在管理群或私聊用 发言设置 [默认条数] 查询或修改默认值。

行为与特殊规则

成员管理与警告

• 支持批量的命令可使用英文逗号分隔多个 QQ 号，或连续提及多个成员。禁止混用两种格式，且同一命令内目标不得重复。
• 设管 / 撤管 会直接调整目标成员的 QQ 群管理员身份，只有 Bot 为目标群群主时才可执行。
• 在本群回复成员的消息并 @Bot，可发送 禁言 10、警告 刷屏 或 发言 20，也支持 禁言10、警告刷屏、发言20。省略参数时，禁言和发言使用默认值，警告使用“未填写原因”。
• 回复成员消息时，禁言和发言的单个数字分别表示分钟和条数。显式 @成员、QQ号 参数 或批量 QQ 列表优先使用指定目标；警告中的显式 QQ 号也优先，纯数字原因请用 @成员 明确目标。回复 Bot 不会将 Bot 作为目标。回复作者无法确认时须填写 QQ 号或 @成员，管理群与私聊的跨群操作也须明确填写目标。
• 禁言默认持续 10 分钟；分钟数为 0 时表示解禁。按成员撤回的数量按每名目标分别计算；撤回直接尝试平台操作，失败由平台返回。批量禁言、踢人和撤回会列出平台拒绝的 QQ 号；撤回按消息作者列出，警告触发自动踢出失败时也会标明成员。
• 第 3 次及之后的未撤销警告会尝试踢出目标；即使踢出成功，警告记录也会保留。

内容检测、问答与风控

• 违禁词使用 Aho-Corasick（多模式字符串匹配算法）检查普通消息和合并转发节点。
• 行为广告检测只评估含域名或 URL 的普通消息与合并转发内容。普通文字和图片的发送频率不计入风险。
• 跨账号投放同一域名、近似内容跨群传播、轮换域名、多域名或联系方式、新成员首条链接、短期退群重入，以及近期自动撤回或人工警告都会增加风险分。
• 入群不满 24 小时或平台返回的群成员等级为 0 至 1 时，如果消息包含广告结构信号，也会增加风险分。
• 自动内容检测不会增加警告次数。管理员、群主、超管、Bot 所有者和检测白名单成员不进入自动检测。
• 问答优先匹配单群规则，再匹配分组规则；同一作用域按精确、正则、模糊的顺序匹配。正则匹配超时或任务繁忙时会跳过本次匹配，其他功能继续运行。
• @Bot 问答 加 会进入 5 分钟的会话式新增流程。后续文字和图片无需再次提及 Bot，发送 完成 保存，发送 取消 放弃。

风控强度按群保存：

风控强度 还可设置禁言分钟数、行为广告处置分数、违禁词是否追加处罚，以及严格模式踢出时是否拒绝再次申请。

群设置与入群验证

• 锁群截止时间会保存到数据库。单群欢迎语默认继承分组设置；启用验证后，Bot 会在新人验证通过后发送欢迎语。
• 被自动清理或手动 清理 成功移除的成员重新加入原群时，群聊／私聊验证的群内提示和已启用的欢迎语会自动附上上次清理条件，例如“上次被清理原因：至少 60 天未发言且群等级 ≤ 10”。每个群分别保存该成员最近一次成功清理的原因，重启后仍保留；踢出失败或跳过的成员不记录。此功能从更新后发生的清理开始记录。
• 群主负责审核头衔申请；头衔长度按 QQ 的 UTF-16 平台规则校验。
• 群主可启用群聊或私聊验证。题库为空时使用随机算术题；黑名单检查先于验证，验证超时会踢出新人。
• 私聊验证要求新人能主动发起好友私聊或群临时会话。Bot 必须是目标群管理员或群主。

数据与服务维护

• 时间范围支持 半小时、30分钟、6小时、今、昨，或 2026-09-06 10:00 至 2026-09-06 12:00。
• 清理 不限制最低保留人数，会先生成预览，并在确认时重新筛选，只处理预览名单中仍符合条件的成员。
• 自动清理 会保留最低人数，manager.cleanup_min_remaining_members 默认为 100。同轮多群清理结束后，正常结果合并发送到管理群且不 @ 管理员，异常结果合并私聊所有者；相同清理条件只显示一次，无人需要清理时不发送通知。
• 清理结果省略“失败 0”和相同的符合条件／实际尝试人数。失败 QQ、非零跳过原因和人数限制仍会显示，发生失败或跳过时附操作编号；正常清理的编号仍可在审计中查询。清理预览只显示一次可清理人数，保留条件、人数变化和确认提示。分组操作结果同样省略“失败 0”和“因权限跳过 0 条”。
• 分析 同时生成 Markdown 报告和分页 PNG 图片，图片会排版标题、列表、表格和代码块。开始提示、结果回复和报告均会注明单次上限、请求范围及实际覆盖范围；归档记录与参与分析的文本消息分别计数。导出 回复也会注明这些范围和是否截断。CSV 中可能被 Excel、WPS 等表格软件识别为公式的文本会加单引号前缀，数据库中的归档原文保留。超过上限时只处理按时间排序的前段记录，请缩短时间范围后重试。
• 更新插件 执行仅快进的 Git 拉取，通过 uv sync --frozen 同步依赖；Web 后台启用时通过 npm ci --include=dev 安装构建依赖，在临时目录构建 React 控制台，再部署资源并原子替换页面入口，全部成功后重启服务。构建或部署失败保留原入口且不重启，更新期间拒绝重复更新和重启；重启插件 只重启服务。
• 服务重启会使现有 Web 管理链接和会话失效，恢复后需重新发送 管理后台。
• 响应屏蔽对象仍会进入归档、统计和违禁词检测，但不会执行命令或触发自动回复。
• 消息保存和撤回标记使用同一归档写入队列，覆盖风控、手动撤回和入群验证清理。撤回标记按群号和消息序号保存，先撤回后归档、重复消息和延迟撤回事件都不会把状态恢复为未撤回；标记随消息保留期维护清理。
• 消息归档写入失败会保留当前批次并退避重试；保留期清理失败也会自动重试，连续失败时通知所有者。归档队列最多缓冲 2,000 条事件，另保留最多 100 条当前重试事件；队列满时丢弃新消息和新撤回标记的归档事件，风控和命令继续处理。溢出时记录累计丢弃数量并在后台通知所有者，日志和通知最多每分钟一次。服务关闭最多等待归档排空 30 秒，超时后在日志中报告未落库消息。待写消息仅在内存中，进程退出或崩溃仍可能丢失。

更新诊断与恢复

执行 更新插件，成功后 Bot 会在重启前回复“更新已完成，正在重启”，上线后再私聊所有者报告结果和有变化的插件版本。两次提醒都附操作编号，以及相对主数据库目录的日志路径 update_logs/<操作编号>.jsonl。更新失败时会立即回复。从 Web 后台执行时，重启前的结果显示在后台，上线后仍通过私聊报告。

日志默认位于 data/update_logs/，需使用服务器上的 Bot 运行账号查看，无法通过群聊或 Web 后台下载。目录权限为 0700，日志权限为 0600。

每次操作会记录更新前的合集及插件版本、Git 提交、各步骤的起止时间和退出码，以及合并、脱敏后的 stdout/stderr 末尾输出。命令不存在、非零退出、超时和取消分别记录；超时或取消会终止进程组并等待回收。

每步最多保留末尾 32 KiB 输出，单份日志不超过 256 KiB，最多保留最近 10 次操作；达到上限时标明输出截断，仍保留步骤结果。需要长期保存的故障日志应及时另行备份。

日志会过滤配置及环境中的凭据、URL 用户信息、认证头、密钥字段和私钥内容。日志目录不可写时停止更新；若操作日志未创建，可用同一操作编号检查服务运行日志，并检查目录权限和磁盘空间。

更新失败时，Git 拉取或依赖同步可能已经改变了运行目录。先查看对应操作日志的 before_update、before_revision 和 step_finished，确定原版本及最后完成的步骤，再处理具体错误。需要回退时，在维护窗口保护本地改动和数据备份，按记录的 Git 提交恢复代码，使用该版本锁文件重新执行 uv sync --frozen；启用 Web 后台时还需重新安装、构建并部署对应版本的前端，验证后再重启。程序不会自动回退代码或依赖。

重要配置

运行时配置

Bot 所有者可在专用管理群或好友私聊中维护群聊、插件和业务配置：

@Bot 配置 群聊 [群号或别名]
@Bot 配置 群聊 <群号或别名> <开|关>
@Bot 配置 插件 [群号或别名]
@Bot 配置 插件 <群号或别名> <插件> <开|关>
@Bot 配置 查看 [manager|call_admin|prts|maa|arknights|operator_guess]
@Bot 配置 设置 <模块.键> <值>
@Bot 配置 设置 maa.maa_auto_upload_group_ids <群号列表|->
@Bot 配置 重置 <模块.键>

MAA 自动上传接收群使用 maa.maa_auto_upload_group_ids（逗号分隔群号，- 清空），检查间隔使用 maa.maa_auto_upload_interval_seconds。定时上传管理群通知开关使用 maa.maa_auto_upload_notify_management（开或关）。三项也可在 Web 后台“运行时配置 → 修改配置”保存，立即生效并覆盖环境默认值；接收群需已开启 MAA 插件。所有者可发送 MAA上传测试 [正式|公测|资源|全部] [覆盖] 手动验证下载和上传，末尾加 覆盖 可先删除目标文件夹中的同名文件再上传，使用 MAA上传状态 查看步骤、进度、耗时和最近结果，详见 MAA 插件手册。

新群聊默认关闭。开启群聊后，管理套件和管理召唤默认启用，PRTS 难度、MAA 下载、截止提醒和猜干员默认关闭。关闭群聊会停用全部插件，并保留各插件的选择状态。

修改群聊开关、插件开关或运行时设置后，需要发送 @Bot 确认。运行时设置保存在主数据库中，并覆盖对应环境变量的默认值。如果收到“配置已保存，但应用失败”，已保存的值会保留；可重发原配置命令并确认，或在管理后台重新保存以重试。

环境变量

可直接复制的部署模板和其他可选变量见根目录 .env.example。Token、远程地址、数据目录、Bot 所有者账号和专用管理群等部署级配置不能通过运行时命令修改。

数据存储与备份

DATA_RETENTION_CLEANUP_ENABLED 控制新增的派生数据清理，默认关闭；原有消息保留期清理继续运行。确认下表期限及备份规则后，可在环境配置中设为 true 并重启服务。清理每天执行一次，失败后退避重试。

文件清理仅检查导出、报告目录的第一层，匹配 Bot 生成的 messages_*.csv、analysis_*.md 和 analysis_*.png 文件名；其他文件、子目录和符号链接均保留。恢复后最近修改过的文件也会保留完整期限。SQLite 删除后的空闲页会被后续写入复用，数据库文件体积不会立即缩小。

启用或缩短保留期限前，由运维使用 SQLite 在线备份或停机备份主数据库及 CODEX_NOTIFY_DATABASE_PATH，并保存问答图片、需长期保留的导出和报告、实际环境配置。备份放在清理目录之外，使用独立保留期，并验证可恢复。程序按上述期限清理运行数据，备份由现有运维流程管理。运行账号必须对所配置的数据目录具有读写权限。

旧版本群聊开关的迁移规则见根 README 的升级说明。

Web 管理后台

Web 后台的启用方式、一次性链接和权限模型见根 README。在后台可以：

• 查看群聊状态、调整群设置和管理成员；
• 维护单群与分组问答；
• 查看插件状态、运行状态和配置；
• 由 Bot 所有者调整每群的超管后台权限，配置请求处理规则、私聊通知并审核请求；
• 执行清理、审计、全局配置等高级命令，沿用现有的确认和审计流程。

后台使用当前登录账号的权限执行操作，并记录该账号，不会借用 Bot 所有者的权限。

群聊默认向超管开放。所有者关闭某群的“超管后台权限”后，超管无法在后台查看该群及其别名、插件状态、问答和审计，也不能通过手动填写群号或二次确认绕过限制；所有者的超管权限预览遵循相同限制。全局统计、扫描、锁群和解锁仅处理获授权的群；包含受限群的共享分组策略、共享提醒和分组归属修改需由所有者执行。保存后对后续请求生效，不需要重新登录。此设置仅限制 Web 后台，不改变聊天命令权限。

“请求管理”仅 Bot 所有者可见，可分别设置好友请求、Bot 入群邀请的“不处理 / 同意 / 审核 / 拒绝”策略和私聊通知，查看最近 50 条待审请求，并逐条同意或拒绝。页面与聊天命令共用数据库、审核锁和审计；已存在的待审请求不会因修改策略而自动处理。Bot 离线时仍可保存规则，恢复连接后才能审核请求。

Bot 所有者可在“运行时配置 → AI 分析连接”选择 OpenAI Chat Completions、OpenAI Responses 或 Anthropic Messages，填写接口基础地址、模型名称和 API 密钥。保存后立即用于后续分析，无需重启；配置保存在主数据库中，重启后继续覆盖环境变量默认值。密钥不会回传到页面或写入审计；留空保留原值，勾选“清除已保存密钥”后停用分析，直到重新填写密钥。

基础地址自动补全 /v1，并保留网关前缀。例如 https://api.example.com/coding 使用 Messages 协议时请求 /coding/v1/messages。也支持以 /chat/completions、/responses 或 /messages 结尾的完整接口地址：保留 API 前缀，再按所选协议确定末尾接口名称。地址须使用 HTTPS，本机联调可使用 HTTP。Chat Completions 优先使用 max_completion_tokens，服务明确拒绝该参数时以 max_tokens 重试一次；Responses 使用 max_output_tokens 和 store: false；Messages 使用独立的系统提示、max_tokens 和 Anthropic 鉴权。

页脚备案信息默认不展示。Bot 所有者可在后台“运行时配置”设置 manager.web_footer_icp 和 manager.web_footer_police，保存后刷新页面即可看到更新；使用 - 清空对应项。公安备案文字格式为“地区名 + 公网安备 + 14 位数字 + 号”，页面会自动展示对应图标与链接。管理后台与公开文档页使用同一配置。

高级功能

网站通知与内测注册

网站公告、正式版本通知和状态监控默认关闭。公告和版本通知的标题与摘要以 Markdown PNG 图片发送，长内容自动分页；通知类型、版本号、发布时间和详情链接以文字显示。图片与文字摘要均最多保留 300 字符，超长时以“……（完整内容见网站更新日志）”结尾，提示计入上限。纯文本公告和版本摘要会按换行、中英文分号拆成独立条目，并按分类标题分组；已有 Markdown 排版会保留。图片渲染失败时自动改用文字发送。

最小配置：

WEBSITE_NOTIFICATIONS_ENABLED=true
WEBSITE_EVENTS_URL=https://example.com/api/integrations/qqbot/events
WEBSITE_EVENTS_TOKEN=<at_least_32_random_bytes>
WEBSITE_NOTIFICATION_GROUP_IDS=[200000003]

远程地址必须使用 HTTPS，网站通知目标群不能包含专用管理群。省略 WEBSITE_STATUS_URL 时，Bot 使用事件接口同源的 /api/status。

在同一网站通知配置中增加独立的 WEBSITE_QQBOT_TOKEN，即可为这些通知群的当前成员 提供个人排班通知和 MAA JSON 私聊下载。共用网站通知的开关、目标群和网站地址； 关闭网站通知会同时停止个人推送。未配置个人 Token 时，群公告和状态监控继续可用。 成员先添加 Bot 为好友，发送 绑定网站 <绑定码> 和 开启排班通知； 发送 帮助 网站排班 查看账号、结果查询、下载和解绑用法。成员退出通知群后停止个人 推送，自动导出不扣券，手动用券下载需先确认消耗 1 张券。

网站内测注册可独立启用，但仍需要 WEBSITE_EVENTS_TOKEN：

WEBSITE_REGISTRATION_ENABLED=true
WEBSITE_REGISTRATION_URL=https://example.com/api/integrations/qqbot/registration-invitations
WEBSITE_REGISTRATION_GROUP_ID=200000004

内测成员在好友私聊或群临时会话中发送 内测注册。Bot 确认其仍在指定群后，向网站申请 24 小时有效的一次性注册链接。接口、游标和鉴权约定见 WEBSITE_INTEGRATION.md。

确认与审计

高风险命令需要二次确认：

1. Bot 显示操作预览，并保留 120 秒。
2. 操作者在同一会话中发送 @Bot 确认。
3. Bot 重新校验操作者权限和目标状态，再执行操作。

清理成员、自动清理设置、设管/撤管、全局锁群、黑名单变更、超管变更、群别名与响应屏蔽对象变更、入群验证设置，以及群聊、插件和运行时配置修改都需要确认。请按 Bot 返回的确认提示操作。

超过 120 秒后，待确认操作失效；同一会话中的新高风险命令会覆盖旧操作。所有已识别命令都会记录操作编号、操作者、执行时采用的角色、目标和结果。审计不会保存密钥、验证答案、完整违规正文或服务器绝对路径。

排查指南

相关文档

• QQ Bot Manager 主文档：安装、入口、权限和部署概览。
• 公开发布与部署：systemd、反向代理、发布和回滚。
• 网站事件接口：网站通知、状态和内测注册协议。
• 请求管理：好友请求与 Bot 入群邀请策略。

管理召唤

受管群成员可以提及 Bot 呼叫管理员。call_admin 会把说明和原消息序号以纯文字转发到专用管理群。

快速使用

Bot 所有者先开启目标群聊和「管理召唤」插件。群聊与插件开关的用法见主文档的运行时命令。

在已启用插件的群聊中提及或回复 Bot，并让关键词位于消息开头：

@Bot 呼叫管理 有人持续发布广告，请协助处理
@Bot 举报 发现疑似诈骗链接
@Bot 召唤管理 请查看消息序号 12345

默认关键词为 管理、举报、召唤管理、呼叫管理。呼叫管理 始终可用，不受自定义关键词配置影响。好友私聊、专用管理群和未启用插件的群聊不会触发转发。

忘记提及 Bot 时，发送 管理、举报：有人发广告、管理有人刷屏，或“再说群要没了”“管理呢管一下”等语句，会收到固定提示：联系管理员请发送：@Bot 呼叫管理 [说明]。 提示按群共享退避，避免多人连续触发刷屏；提示不会转发，也不影响正式召唤。来人 不再属于默认关键词，也不会触发用法提示。

触发与转发规则

• 关键词位于消息开头，后接消息结束、空白或明确标点；也支持 管理有人刷屏、管理在吗 等求助含义明确的连写形式。管理学、管理后台、举报机制 等普通长词不会触发。
• 未提及 Bot 时用正则识别召唤用语及常见冲突句式，例如“再说下去这群就要没了”“再吵群要炸了”“管理员呢，处理一下”“群管理赶紧管一下”“别吵了，叫管理员”。引用的文字示例、回复他人或开头提及他人的消息不会收到提示；召唤词后提及被举报成员仍可收到提示。
• 用法提示按群共享退避，首次间隔使用 call_admin_cooldown_seconds，此后每次发出提示时翻倍，默认依次为 60、120、240、480、900 秒，最长 15 分钟。连续 30 分钟未命中后恢复初始间隔；被抑制的匹配也算命中。若基础冷却超过 15 分钟，则以基础冷却为上限，并在安静两倍基础冷却后重置。
• 正式召唤仍按成员和群聊冷却，时长使用 call_admin_cooldown_seconds，不受提示退避影响。
• 转发内容包含来源群、召唤者、时间、关键词、用户说明和原消息序号。
• 用户说明最多保留 500 个字符，超出部分会截断。
• 转发只包含文字，不会提及任何人，也不查询管理群成员列表。
• 同一成员在同一群聊使用不同召唤词时，共用一个冷却时间；其他群聊或成员不受影响。
• 同一成员在同一群聊同时只能发送一次召唤，发送中的重复请求会提示等待；失败或取消后可重试。只有转发成功后才开始冷却。冷却保存在内存中，Bot 重启后清空。
• 转发失败时会提示召唤者，可立即重试。

配置

运行时配置

Bot 所有者可在 Web 后台“运行时配置 → 管理召唤匹配规则”查看并编辑关键词和全部冲突提示正则。每行填写一个关键词或一条正则，分别保存后立即生效，重启后保留。固定命令 呼叫管理 始终显示；完整关键词匹配表达式可展开查看，会随关键词自动更新。

也可在专用管理群或好友私聊中调整配置：

配置 查看 call_admin
配置 设置 call_admin.call_admin_keywords 管理,举报,召唤管理,呼叫管理
配置 设置 call_admin.call_admin_cooldown_seconds 60
配置 设置 call_admin.call_admin_reminder_patterns ["再说群要没了$","管理呢管一下$"]
配置 重置 call_admin.call_admin_keywords
配置 重置 call_admin.call_admin_reminder_patterns

运行时配置保存在管理 SQLite 中，修改后立即生效。提示正则从消息开头匹配，可在末尾使用 $ 限定整条消息；每条必须是单行表达式，实际换行用 \n 表示。保存前校验语法，自定义正则在独立进程中执行，单次匹配（含排队与启动）限时 250 毫秒；超时跳过本次冲突提示并记录日志。修改这些正则不改变正式召唤关键词和提示退避。

升级会保留已保存的关键词；即使旧配置中仍含 来人，它也不会触发用法提示，可用上述设置或重置命令移除。通用配置命令和确认流程见管理套件文档。

环境变量

完整环境变量格式见 .env.example。运行时值存在时，会覆盖对应的环境变量默认值。

安全与隐私

• 专用管理群应只保留确有管理职责的成员。
• 举报说明可能包含成员账号、聊天上下文或其他敏感信息，应按社群隐私规则处理。
• 消息序号用于管理员回到原群定位现场；插件不会自动裁决或处罚被举报成员。

排查指南

相关文档

• 项目主文档：通用入口、权限体系和插件开关。
• 管理套件：运行时配置、Web 后台和操作审计。

PRTS Plus 难度查询

prts_difficulty 根据 PRTS Plus 作业估计关卡难度，提供低配要求、活动排行和干员统计，帮助群成员比较关卡、选择阵容。群成员可以查询，超管负责维护同步任务。

快速使用

Bot 所有者先开启目标群聊和「PRTS 难度」插件。插件默认关闭，开关用法见主文档的运行时命令。

群成员在已启用插件的群聊中提及或回复 Bot：

@Bot 关卡难度 TO-S-1 突袭
@Bot 难度排行 综合 主线 2
@Bot 干员统计 史尔特尔 综合

Bot 所有者还可在好友私聊中直接执行查询或刷新命令。专用管理群不作为该插件的查询入口。

命令参考

符号约定：<必填> 必须提供，[可选] 可以省略，A|B 表示任选其一。

参数命令支持省略命令词后的第一个空格，例如 关卡难度TO-S-1 与 关卡难度 TO-S-1 等价。无参数命令必须完整匹配；作业数据状态123 不会触发。

查询关卡时，可填写内部 ID、标准代号或名称。匹配到多个关卡时，Bot 最多返回 5 个候选，建议改用标准代号。排行每页显示 10 条；分类可使用关卡目录中的一级、二级或三级分类。

查询结果

关卡结果包含：

• 难度分、低配难度和难度百分位；
• 作业数量、数据参考度和代表作业；
• 养成、获取、操作三项要求及等效理智成本；
• 常用干员的出场率和难度差。

难度分范围为 0 至 100，分数越高，阵容与操作要求越高。数据待补充时显示暂定结果及待确认项目。危机合约等可变难度模式显示作业数量和待补充的挑战条件。

活动排行展示各活动的难度、低配难度和关卡数量。干员排行可选择出场率或难度关联；干员统计展示出场比例、难度差和平均阵容要求。

评分公式、数据来源与计算规则见 评分模型。

配置

运行时配置

Bot 所有者可使用 配置 查看 prts、配置 设置 <模块.键> <值> 和 配置 重置 <模块.键> 维护这些值。

环境变量

干员元数据、持有/培养统计和实装时间来源也可以通过 PRTS_OPERATOR_*_URL 调整。远程地址必须使用 HTTPS，只有本机联调地址可以使用 HTTP；地址不得包含用户名或密码。完整配置见 .env.example。

刷新与数据

• 插件在没有可用快照、快照过期或到达每日刷新时间时启动后台更新。
• 同一时间只运行一个刷新任务；重复刷新会直接提示正在运行。
• 查询只使用完整生成的快照，刷新失败时会保留上一份可用数据。
• 作业数据状态 会显示摘要分页、详情处理、关卡汇总、完成时间和最近错误。
• 数据库保存活动快照、详情缓存、刷新进度和干员观测。
• 下载的干员元数据和统计缓存位于数据库同目录；来源暂时不可用时优先复用本地缓存或仓库内置数据。

排查指南

相关文档

• 项目主文档：插件开关、命令入口和权限体系。
• 管理套件：运行时配置与 Web 管理后台。

方舟刷图

活动开始后，在群内问 @Bot 这次刷什么；缺材料时问 @Bot 去哪刷 固源岩组。Bot 返回刷图推荐图片，分开展示当前活动和常驻关卡，包括推荐关卡、掉落材料、单件理智消耗和活动截止时间。

启用与命令

插件默认关闭。在 Web 后台的插件应用中为目标群开启“方舟刷图”，也可由所有者发送 配置 插件 <群号> 方舟刷图 开。普通群成员均可查询；默认须提及或回复 Bot，开启下述正则模式后可直接发送问法。暂不提供私聊入口。

参数支持省略第一个空格，例如 去哪刷固源岩组、材料掉落固源岩组。完整名称优先，也接受企鹅物流的中文别名、材料 ID 和无歧义的部分名称；匹配多个材料时会提示完整名称。

图片使用游戏内材料图标，突出关卡代号和单件理智，下方展示单次消耗与统计样本次数。活动卡片直接列出同种材料最省理智的常驻关卡、单件成本和节省或多耗的比例。单件理智越低，刷取该材料越省。活动样本不足时显示“收集中”；没有直接掉落数据的材料会提示查看合成或兑换途径。图标暂时不可用时保留文字卡片，整图渲染失败时返回文字。

正则匹配模式

所有者可在 Web 后台“运行时配置”修改以下配置，也可在管理会话发送：

配置 设置 farming.arknights_farming_regex_enabled 开

确认保存后立即生效，并覆盖所有已启用“方舟刷图”的群。此时无需 @Bot，相关查询全部按配置的正则规则匹配；关闭后恢复默认命令与提及要求。默认规则支持：

• 这次活动刷哪关、本次活动刷什么？、当前活动推荐刷哪个关卡、这次刷什么、活动刷图。
• 去哪刷固源岩组、去哪刷 固源岩组、材料掉落固源岩组。
• 固源岩组去哪刷？、固源岩组在哪里刷、固源岩组怎么刷。

两类列表各自支持每行一条正则或 JSON 数组，最多 20 条，每条最多 500 字。保存时检查语法；列表替换该类默认规则，[] 停用该类匹配，重置配置恢复默认。规则使用 Python re.fullmatch 匹配整条去除首尾空白的消息，活动规则优先。普通文字如“今天刷完了”、活动刷图排行、状态123 不会命中默认规则。

自定义示例（管理会话仍按原有要求提及 Bot）：

配置 设置 farming.arknights_farming_overview_patterns ["(?:这次|本次)活动刷哪关[？?]*"]
配置 设置 farming.arknights_farming_material_patterns ["(?P<material>.+?)刷哪里[？?]*"]

自定义材料规则下，固源岩组刷哪里 会查询固源岩组。请保留所需的原命令正则，否则被替换的命令将不再触发。正则模式仍遵守群聊、插件开关和响应屏蔽；不扫描私聊，超过 256 字的消息不匹配。自定义表达式在隔离进程中执行，匹配超时或进程不可用时跳过该条消息。

数据与推荐口径

• 数据源：企鹅物流数据统计，使用公开 API 的国服物品、区域、关卡和掉落矩阵。排版参考明日方舟一图流，图片由本插件独立渲染。
• 按目标材料的直接掉落计算：单件理智 = 关卡理智消耗 × 样本次数 ÷ 材料掉落数量。图片只展示单件成本、单次消耗和样本次数，文字降级中的每次平均掉落为数量期望，不是“至少掉落一件”的概率。
• 至少 100 个样本才参与排序；统计周期须在当前时间内，同一关卡和材料保留最新的有效周期。不累计已经结束的活动加成数据。
• 当前活动必须在国服开放时间内，且关卡与区域均开放。常驻包括主线、支线和已常驻的插曲／别传；活动原版、复刻和常驻版分别使用各自的掉落统计。排除磨难关卡重复统计、抽奖箱及理智消耗为零的条目。
• 活动概览按每关主要蓝色材料选出各材料最省理智的关卡，最多八种材料。材料查询包含有效统计中的直接掉落。新活动尚未收录材料或统计时明确提示，不推测掉率。活动开放以数据源收录为准。
• 排序只比较目标材料的直接获取成本，不计算副产物总价值、合成链、活动商店与代币收益，也不读取个人库存；有明确缺口时优先查询该材料。高阶材料可能更适合合成。
• 数据按需获取，在进程内缓存 30 分钟。刷新失败最多使用 24 小时内的缓存并标注；活动时间仍按查询时刻重新核对。失败后一分钟内不重复请求，无可用缓存时返回错误。重启后重新获取，无后台轮询。

游戏材料图标随插件打包，来源为企鹅物流的游戏物品图集，按同一快照的 itemId 与 spriteCoord 裁切。2026-10-27 的图集包含 61 种材料，渲染无需请求图片服务器；素材来源和维护方式见 resources/README.md。遇到尚未打包的新材料时显示“图标缺失”，保留材料名与查询结果，不使用其他图标替代。

无需新增依赖、账号或数据库表。外部请求仅用于公开掉落数据，首次查询需等待数据加载。

验证命令：

uv run python -m unittest tests.test_arknights_farming tests.test_bot_core tests.test_public_docs

MAA 下载

maa_download 查询 MAA 官方版本信息，检测镜像并提供下载链接，也可自动下载正式版、公测版 Windows x64 安装包和资源源码 ZIP，上传到多个群的指定群文件夹。

快速使用

Bot 所有者先开启目标群聊和「MAA 下载」插件。插件默认关闭，开关用法见主文档的运行时命令。

群成员在已启用插件的群聊中提及或回复 Bot：

@Bot MAA版本 稳定
@Bot MAA下载 公测 linux-x64
@Bot MAA下载 资源
@Bot MAA镜像状态

MAA下载 省略参数时返回稳定版 Windows x64 安装包。镜像链接来自第三方服务，可能随时失效。

命令参考

参数命令支持省略命令词后的第一个空格，例如 MAA版本稳定 与 MAA版本 稳定 等价，MAA上传测试资源 覆盖 与 MAA上传测试 资源 覆盖 等价；MAA上传测试覆盖 覆盖全部类型。文件类型与 覆盖 之间仍需空格。无参数的 MAA镜像状态 和 MAA上传状态 必须完整匹配，MAA镜像状态123、MAA上传状态123 不会触发。

可用平台：

通道也接受 稳定版、正式版、beta、alpha 等内置别名；日常使用时，建议填写 稳定、公测、内测。

发送 MAA下载 资源、MAA下载资源 或 MAA下载 资源包 可获取最新自动资源更新提交对应的 MaaResource 源码 ZIP 镜像链接。结果显示资源日期、提交 SHA 和文件名；获取活动信息后还会显示活动与资源更新时间，并给出按活动名命名的文件，例如 资源包_[昨日海]#1009_8d949986.zip。该 ZIP 不分平台，不接受额外平台参数，下载前大小可能未知。镜像的原始下载文件名可能仍是提交 SHA，可按结果中的文件名保存。

自动上传群文件

Bot 所有者可在专用管理群发送以下命令，好友私聊省略 @Bot：

@Bot 配置 查看 maa
@Bot 配置 设置 maa.maa_auto_upload_group_ids 123456789,987654321
@Bot 配置 设置 maa.maa_auto_upload_interval_seconds 900

按 Bot 提示发送 确认 后，配置立即生效并持久保存。接收群用逗号分隔，不允许重复群号；设置值 - 清空接收列表，使用 配置 重置 maa.maa_auto_upload_group_ids 恢复环境默认值。

也可由 Bot 所有者在 Web 后台「运行时配置 → 修改配置」填写配置项 maa.maa_auto_upload_group_ids，配置值填写 123456789,987654321 后保存；检查间隔使用 maa.maa_auto_upload_interval_seconds。Web 与命令使用相同配置，保存后立即生效，无需重启。

确保接收群已开启群聊和「MAA 下载」插件。接收群列表默认为空，检查间隔默认 15 分钟；首次检查会补传当前版本。Bot 需要能读取群文件、创建文件夹和上传文件；已有同名文件夹会直接使用。

部署环境仍可指定默认值，运行时配置优先于环境默认值：

MAA_AUTO_UPLOAD_GROUP_IDS=[123456789,987654321]
MAA_AUTO_UPLOAD_INTERVAL_SECONDS=900

公测接口返回正式版时，会跳过公测版的下载和上传，正式版只上传到正式版文件夹。自动同步、手动测试和 覆盖 均遵循此规则；已有历史群文件保留。

Bot 上传的资源 ZIP 内顶层目录固定为 MaaResource-main/，解压后可直接找到 MaaResource-main/resource/。镜像直链仍返回上游原始 ZIP，目录名由提交 SHA 决定。

自动上传和手动测试使用相同顺序：每个文件在 Bot 下载、校验一次后，先向一个群上传，确认成功并取得文件 ID 后，再复用该群文件的下载链接上传其余群。首群明确失败时可尝试下一群建立来源；结果待确认时，会先核对该群的上传结果，暂停向其他群传二进制或文件路径。

Bot 与 Milky 能访问同一目录时，可在部署环境设置：

MAA_UPLOAD_SHARED_DIRECTORY=/srv/qqbot-shared/maa

两端必须使用相同的绝对路径，Bot 需要写权限，Milky 需要读取 Bot 创建的临时文件；临时文件默认仅允许创建者读取，两端可使用相同系统用户或 UID。Docker 部署时，将同一目录挂载到两个容器内的相同路径。

配置后，Bot 直接在共享目录下载和处理 ZIP，首群复用校验完成的文件路径，省去将完整包读入内存、Base64 编码和文件内容的 API 传输；首群成功后，其余群使用群文件链接。路径上传阶段与结果会显示“共享路径”。

共享目录不可写或路径被 Milky 明确拒绝时，首群回退到二进制上传；未配置共享目录时，首群直接使用二进制。成功响应返回文件 ID，或核对到同名、同大小文件及其 ID 后，后续群才开始上传，由 Milky 下载来源群链接并投递到指定文件夹。本轮检查到已有同名、同大小文件且提供文件 ID 时，也可直接用作来源。重启或下轮补传时，会重新查找已同步群的文件作为来源，避免再次传二进制。每次投递重新获取链接，不持久保存下载链接。

首群响应超时或网络中断时，在当前任务内每 30 秒核对一次，沿用从该次上传开始的 10 分钟确认期限。期间状态显示“等待来源群上传成功”，其余群不会开始上传；覆盖模式也不会提前删除其余群的同名文件。核对成功后立即继续链接上传；期限结束仍无法取得来源文件 ID 时，剩余群显示“暂缓上传”，等后续检查再继续。查询失败不能判定上传失败，此时保留待确认记录和共享文件。

链接复用会减少 Bot 到 Milky 的重复文件传输和 Base64 编码。Milky 没有跨群文件转发接口，链接复用仍可能让 Milky 重新下载并上传；实际耗时和 Milky 到 QQ 的流量取决于协议端及 QQ 的处理。获取链接失败或链接无效时沿用二进制上传；链接上传被接口明确拒绝时也会回退，网络中断或超时则先等待核对，避免重复投递。

共享临时文件在本轮投递结束且没有待确认记录引用时自动删除；网络中断、超时或任务取消时，保留文件和待确认记录，重启后继续核对。所有引用该文件的记录确认成功、等待结束或对应群移出接收配置后，再清理文件。共享目录与上传状态数据库需在重启后保留。

上传成功状态按群持久保存，重启不会重复上传；单群明确失败不影响其他群，下次检查会重试。上传响应超时或网络中断时标记为“结果待确认”，每 30 秒核对群文件，确认出现同名、同大小文件后补记成功；等待期间不会重复上传。待确认记录也会持久保存，重启后继续核对；从接收群配置删除群号后，对应待确认记录和群级通知会在下一轮自动清理，不再重试或告警。状态尚未记录但文件夹内已有同名、同大小文件时，会补记状态。新增接收群会补传当前文件，历史群文件保留。

定时上传完成通知

通知默认关闭。Bot 所有者可在管理群设置，好友私聊省略 @Bot，按提示确认后生效：

@Bot 配置 设置 maa.maa_auto_upload_notify_management 开
@Bot 确认

Web 后台「运行时配置 → 修改配置」使用相同配置项，值填 开 或 关。环境默认值为 MAA_AUTO_UPLOAD_NOTIFY_MANAGEMENT=false。

开启后，定时任务本轮下载和群文件投递结束时，向专用管理群发送简短通知，不提及管理员。相同文件版本和结果合并群号，保留全部目标群；不同文件、版本或结果分别显示。内容保留文件类型、安装包版本或资源活动名及日期和短 SHA、目标群和结果。例如：

MAA 定时上传结果：
群 123456789、987654321｜公测版 v6.20.0-beta.1：文件已存在
群 123456789、987654321｜资源包 [昨日海]#1009_8d949986：结果待确认

没有新文件、所有群已同步时不推送。上传结果待确认时先如实通知，后台核对后再补发最终结果，补发通知同样合并相同结果的群号；手动测试仍在原会话回复。通知发送失败会记录日志并重试，保留逐群通知记录，不改变上传结果。

手动上传测试

Bot 所有者可在已开启 MAA 插件的受管群、专用管理群或好友私聊中触发测试；群内需提及或回复 Bot，私聊省略 @Bot：

@Bot MAA上传测试 正式
@Bot MAA上传测试 公测
@Bot MAA上传测试 资源
@Bot MAA上传测试 全部
@Bot MAA上传测试 资源 覆盖
@Bot MAA上传测试覆盖

测试会立即获取并重新下载最新文件，检查已配置接收群的文件夹，不会因为已有上传记录而跳过。与自动上传一样，先确认一个来源群成功，再复用群文件链接上传其余群。配置共享目录时，首群优先路径上传，成功结果显示“上传成功（共享路径）”；其余群成功时显示“上传成功（复用群文件链接）”。

Bot 会先提示任务开始，随后按文件汇总上传结果：文件名只显示一次，相同结果合并群号，待确认、上传成功、链接复用成功和失败分别保留；已有同名、同大小文件会复用，测试成功也会记录上传状态。

自动上传或其他测试正在运行时，会显示当前状态并提示稍后再试。未找到可用接收群时，先配置接收列表并启用对应群的 MAA 插件。

需要重新上传已有文件时，在命令末尾加 覆盖；省略文件类型时覆盖全部类型。Bot 会先下载并校验新文件，再删除各群目标文件夹中所有同名文件后上传，不论旧文件大小，其他文件保留。Bot 需有删除群文件的权限；某群删除失败时停止该群本次上传并继续处理其他群。删除成功后若上传明确失败，旧上传记录会清除，后续检查可重试；上传结果待确认时仍先等待核对。

查看上传状态

所有者发送 @Bot MAA上传状态 可查看当前或最近一次上传任务。支持已启用 MAA 插件的受管群、专用管理群和好友私聊，私聊省略 @Bot。任务运行时也可查询，不会等待上传完成。

状态会显示已配置接收群和当前可用群的数量，单独列出未启用群聊或 MAA 插件的群号。同时显示自动任务、Bot 连接情况，以及以下信息：

• 自动同步或手动测试、开始时间和总耗时。
• 当前步骤及持续时间、距最后进展的时间，便于发现停滞。
• 当前文件、镜像节点、已下载大小与百分比；资源 ZIP 无总大小时显示已下载大小。
• 当前处理的群、群进度和文件夹；上传时显示是否正在等待 Milky 返回，使用群文件链接时显示来源群。
• 本次上传结果和最近错误所在步骤；相同结果合并群号，当前文件名只显示一次，不同文件和结果分别保留。先合并再显示最近 12 条，避免同一结果的群号被截掉。

Milky 上传接口不提供字节进度，上传阶段显示当前群和等待耗时。任务诊断状态保留在当前服务内存中，重启或重载配置后重新记录；各群已上传文件和待确认上传的持久化记录保持有效。

上传接口返回 NetworkError 或超时，只能说明响应未正常返回。此时状态显示“上传结果待确认”，不计为上传失败。MAA上传状态 会核对待确认文件，后台也每 30 秒核对一次；文件出现后，结果更新为“上传成功（已核对群文件）”。只有查询成功且等待 10 分钟后仍未找到同名、同大小文件，才提示“未确认成功”并允许下轮重试。群文件查询失败时会保留待确认记录，避免误判或重复上传。

数据来源与检测规则

• 插件优先从 MAA 官方 api.maa.plus 版本 API 获取信息，失败后按配置顺序尝试备用 API。
• 安装包版本号中没有 -beta、-alpha、-rc 等预发布后缀时视为正式版，不因公测接口返回该版本就重复上传到公测版文件夹；+ 后的构建元数据不影响此判断。
• 默认备用版本 API 使用 jsDelivr CDN；安装包和资源 ZIP 都通过动态镜像下载，镜像跳转到 GitHub、局域网地址或非 HTTPS 地址时会拒绝下载。
• 插件从 XIU2 的活跃 GitHub 镜像目录读取已启用的 Release 节点，随机抽样后逐个检测。
• 节点检测使用 Range: bytes=0-0 的 GET 请求，只读取探测所需内容，不下载完整安装包。
• 下载结果最多返回 MAA_MIRROR_MAX_LINKS 个已通过本次检测的节点，并优先展示响应较快的节点。
• MAA镜像状态 显示 Bot 服务器的检测结果；成员能否访问还取决于本地网络。
• 镜像目录不可用或抽样节点全部失效时，查询会返回错误，自动上传会记录错误并在下次检查重试。
• 自动上传按探测响应时间依次尝试可用镜像，完整下载后检查文件大小和 ZIP 完整性；网页、截断文件和损坏压缩包不会上传。
• 资源提交元数据默认从 GitHub API 获取，可配置备用 API。按时间从新到旧分页查找首个标题为 chore: Auto Update Game Resources - YYYY-MM-DD 的提交，忽略普通功能、文档和版本号提交。
• 资源包下载该提交 SHA 对应的 MaaResource 源码快照，校验后将 ZIP 内的 MaaResource-完整SHA/ 顶层目录改为 MaaResource-main/ 再上传，保留文件内容、子目录和文件属性。活动元数据通过 jsDelivr CDN 获取该 SHA 的 resource/version.json，不读取可能更新更快的 main，也不直连 GitHub；首个 CDN 不可用时尝试备用地址，成功结果按 SHA 缓存。
• 资源包使用 activity.name 命名为 资源包_[活动名]#MMDD_短SHA.zip。与 MAAGui 一致，将 last_updated 按 UTC 解析，再转换到 Bot 的 TIMEZONE（默认 Asia/Shanghai）；文件名、资源日期和更新时间均使用转换后的时间，字段缺失时回退到自动资源更新提交标题中的日期。例如 last_updated 为 2026-10-09 23:31:13.000 时，北京时间为 2026-10-10 07:31:13+08:00，文件名为 资源包_[昨日海]#1010_8d949986.zip。activity.time 是活动时间，不用于资源版本命名。文件名中的路径分隔符、控制字符和非法字符会替换为下划线。
• 活动元数据不可用或无效时，保留 MaaResource-日期-完整SHA.zip 命名并继续下载。上传去重始终使用完整 SHA，同一天不同提交会上传；活动名称变化或元数据恢复不会使同一 SHA 再次自动上传。旧版上传记录和待确认记录保持有效，手动测试也能复用旧名称的同 SHA、同大小文件。
• 下载分块写入临时文件。开始解压前检查 ZIP 条目数（含目录）、单条目及总解压大小；校验和资源包重打包按 64 KiB 分块进行，保留 CRC 校验、文件内容、目录和属性，不按压缩比拒绝文件。上限可通过下表环境变量调整，边界值允许通过。
• 配置共享目录时直接复用处理后的文件路径；未配置、目录不可写或路径被 Milky 明确拒绝时，才读取完整文件进行二进制上传。二进制上传仍需要完整包及 Base64 编码的内存；校验和资源包重打包还需要临时磁盘空间，重打包期间输入与输出文件同时存在。正常完成、失败和下载取消时清理未使用文件；ZIP 处理取消后先等待工作线程停止再删除文件，待确认上传引用的共享文件按原规则保留。一次只处理一个文件。
• 群文件链接允许 HTTP 或 HTTPS，拒绝凭据、局域网、GitHub 直连地址及无效链接；镜像与活动元数据仍要求 HTTPS。资源上限及可复现的 RSS、耗时和清理测量见MAA 资源测量记录。

环境变量

接收群、自动检查间隔和管理群通知开关支持运行时命令及 Web 后台配置。其他配置使用部署环境变量。

版本 API、镜像目录、资源提交 API 和活动元数据 CDN 列表不能为空。所有配置地址必须使用 HTTPS，且不得包含凭据、查询参数或片段；资源提交 API 可以使用 GitHub，版本 API、镜像目录和活动元数据 CDN 不允许 GitHub 直连地址。最大返回链接数不能超过抽样候选数。完整格式见 .env.example。

排查指南

相关文档

• 项目主文档：插件开关、权限体系和部署方式。
• 管理套件：群聊与插件状态管理。

明日方舟截止提醒

arknights_reminders 从 PRTS Wiki 和明日方舟国服官网同步截止事项。发送「今日方舟」可一次查看近期事项；订阅分类后，Bot 会按所选时间发送提醒，事项由超管维护。

快速使用

Bot 所有者先开启目标群聊和「截止提醒」插件。群聊与插件开关的完整用法见主文档的运行时命令。

成员命令只在已启用插件的群聊中响应，需要提及或回复 Bot：

@Bot 今日方舟
@Bot 提醒 分类
@Bot 提醒 订阅 寻访 活动商店 3天 1天
@Bot 提醒 我的

上例会持续订阅「寻访」和「活动商店」，并在截止前约 3 天、约 1 天提醒。省略档位时使用 3天、1天、12小时。提醒按大致提前时间安排，避开夜间，消息中会显示实际剩余时间。

超管及以上权限可在专用管理群或好友私聊中维护事项。在专用管理群中需要提及或回复 Bot；好友私聊无需提及。通用入口和权限定义见主文档。

命令参考

符号约定：<必填> 必须提供，[可选] 可以省略，... 表示可以提供多个值，A|B 表示任选其一。

成员命令

可选档位为 7天、3天、1天、12小时、3小时、1小时。全部 不能与具体分类混用。

可订阅分类：

旧版的单事项订阅、忽略和恢复命令只会提示改用分类订阅，不再执行操作。

今日方舟

在已开启「截止提醒」的群内发送 @Bot 今日方舟，普通成员即可查看：

• 未来 7 天内的活动关卡、活动商店、寻访、奖励领取等截止事项，按截止时间排序。
• 标准、中坚黄票商店各自最近一次轮换，以及下次月常重置。PRTS 已同步进店干员时，显示对应干员名；尚未获取时显示轮换时间。
• 下次周常重置时间，提醒检查每周任务、剿灭报酬和可能过期的周期限理智药剂。
• 提醒列表与订阅入口；本群开启对应插件时，另显示 PRTS 难度、干员统计与 MAA 版本、下载命令。

专属长图使用深色工业网格、切角面板和黄青配色，顶部显示日期、近期截止数量及 24 小时内截止数量。24 小时内的事项用红色与文字共同标记，长标题自动换行，全部区块合成一张长图。常用查询以紧凑行表展示命令和说明，只在分区标题处提示一次使用方式。绘制失败时返回完整文字。图片由 Pillow 和项目自带中文字体在本地绘制。

每个区块最多显示 8 项，超出时提示查看完整列表。仅显示全群可见或属于当前群的有效事项，不受个人订阅影响。时间沿用 TIMEZONE 配置。

查询读取现有同步数据，不额外请求上游；暂无事项时会说明尚无已收录数据。此命令按需查询，不会新增每日推送或改变订阅。

管理命令

同一来源连续报错时，管理群在第三次失败后收到一次告警；来源恢复后再次故障会重新告警。暂停定时拉取不影响已有事项的提醒投递。

删除事项或提前截止时间时，Bot 会显示操作预览。原操作者须在 120 秒内发送 提醒管理 确认，操作才会执行。

Web 管理后台还会展示全部状态的事项和用户订阅。Bot 所有者可在全功能控制台中代成员维护订阅，后台入口与权限模型见管理套件文档。

配置

运行时配置

运行时配置保存在管理 SQLite 中，覆盖对应的环境变量默认值：

Bot 所有者可通过 配置 查看 arknights、配置 设置 <模块.键> <值> 和 配置 重置 <模块.键> 维护这些值。

环境变量

远程来源必须使用 HTTPS；只有本机联调地址可以使用 HTTP。其余可选变量和取值范围见 .env.example。

同步与投递规则

• 来源数据冲突或已锁定事项发生变化时，插件会生成候选，由超管审核后发布。
• 人工修改来源事项后，插件会锁定该事项，避免下次同步覆盖；执行 同步源 可恢复自动同步。
• 提醒按配置时区在每天 09:00–22:00 发送。预计落在 22:00–次日 09:00 的提醒提前到夜间开始前的 21:00，白天时间保持不变。例如 8 月 20 日 04:00 截止的事项，3天 档在 8 月 16 日 21:00 提醒，1天 档在 8 月 18 日 21:00 提醒，12小时 档在 8 月 19 日 16:00 提醒，3小时、1小时 档合并在 8 月 19 日 21:00 提醒。
• 订阅或新增事项时，若调整后的时间已过、原档位时间尚未到达，且当前仍在白天发送时段，会立即提醒。升级后自动重排已有事项，已发送档位不会重复发送。
• 同一轮扫描中，本群到期的不同事项和档位合并发送，按截止时间列出事项、实际剩余时间和截止时间。每位订阅成员只提及一次，并标明对应的事项编号；订阅相同事项的成员共用一行提及。发送前过滤已退群成员，超过单条提及人数上限时按成员分批，每条只列出该批成员需要提醒的事项。
• 投递失败后，插件按数据库中保存的计划重试；重试次数用完后通知管理人员。
• 重载配置或停止服务时，会等待当前投递完成清理，释放本轮已领取但未完成的记录；下次投递仍遵守补发宽限时间。平台已发送、但本地尚未记录成功时，重试可能重复发送。
• 补发和失败重试同样避开夜间；Bot 恢复运行时只补发宽限时间内最近错过的一档提醒，已截止事项不会补发。
• Bot 无法读取玩家背包；「限时物品」只提醒成员自行检查库存和过期时间。

排查指南

相关文档

• 项目主文档：通用命令入口、权限、插件开关和部署方式。
• 管理套件：运行时配置、Web 管理后台、确认与审计。

猜干员

群成员可用 operator_guess 一起看立绘、技能图标猜干员，Bot 会记录本局成绩、连击和赛季积分。

快速使用

Bot 所有者先开启目标群聊和「猜干员」插件。插件默认关闭，开关用法见主文档的运行时命令。

管理及以上权限可在已启用插件的群聊中提及或回复 Bot 开局：

@Bot 猜干员
@Bot 猜干员 困难立绘
@Bot 猜干员 技能

省略模式时，发起者需要在 60 秒内选择难度。游戏开始后，成员可直接发送干员名答题，或发送提示、跳题命令，无需提及 Bot。

模式

语音和档案模式尚未开放；像素立绘模式当前禁用。

命令参考

开局与查询

参数命令支持紧凑形式，例如 猜干员困难立绘 与 猜干员 困难立绘 等价。查询命令必须完整匹配。

成员开局

群管理可设置是否允许本群普通成员发起游戏：

@Bot 猜干员成员开始 开启
@Bot 猜干员成员开始 关闭

开启后，普通成员在每个群聊每 30 分钟可发起一次游戏。冷却从发送开局命令时开始，开局失败、游戏时长或开关切换都不会重置冷却；管理发起游戏不占用该冷却。

干员别名

别名不能覆盖正式干员名、内置别名或局内操作词。自定义别名由所有启用猜干员的群聊共享。

游戏与计分规则

• 每局默认 30 题；每题默认 60 秒。题目超时会结束整局游戏。
• 每题默认允许 10 次有效错误。错误答案需能识别为干员，才会计入次数；同一成员在本题重复提交同一个错误答案不重复计数。
• 发送 提示 或 不知道 获取提示；普通提示使本题和最终结算倍率降低 2%，技能模式最后一次四选一提示降低 10%。
• 发送 下一题、放弃 或 跳过 会揭晓答案并使最终结算倍率降低 5%；错误机会耗尽也降低 5%。倍率最低为 50%。
• 正确答案获得本局分数和赛季积分；连续答对会增加连击奖励，其他成员答对或本人答错可能中断连击。
• 同一批到达的答案按消息时间和消息序号排序，只结算第一条有效正确答案。
• 本局排名按分数档位计算，允许并列。默认至少完成 15 题后，前三个分数档才获得名次积分。
• 名次积分以 30/20/10 为基础，并按模式倍率、完成进度和提示/跳题惩罚调整。
• 管理及以上权限可在难度选择或游戏中直接发送 结束 或 不玩了 终止游戏。

赛季默认按 TIMEZONE 指定时区的自然月切换，也可设置固定的赛季标识和名称。

配置

运行时配置

Bot 所有者可使用 配置 查看 operator_guess、配置 设置 <模块.键> <值> 和 配置 重置 <模块.键> 维护这些值。operator_guess_finish_min 不能大于题目数。

环境变量

远程资源地址、题目准备、批处理窗口和缓存重试等高级变量见 .env.example。远程资源必须使用 HTTPS，本机联调地址除外。

资源与限制

• 插件启动后会缓存全部可用立绘和技能图标；缓存尚未就绪时不能开局，可用 @Bot 猜干员状态 查看进度。
• 上游存在多个同名角色时，插件只保留题型和资源更完整的一条，避免提高该名称的出题概率。
• HTTP(S) 代理凭据只应存放在受限的环境文件中，不要写入文档、日志或源码。
• 仓库不提交游戏素材；部署和使用时应遵守上游声明及素材权利要求。

排查指南

相关文档

• 项目主文档：插件开关、命令入口和权限体系。
• 管理套件：运行时配置与 Web 管理后台。

请求管理

Bot 所有者可通过 request_manager 自动处理或人工审核好友请求和 Bot 入群邀请，并设置私聊通知规则。

也可登录 Web 管理后台，进入“请求管理”分别设置处理策略、私聊通知，并逐条同意或拒绝最近 50 条待审请求。页面仅向 Bot 所有者开放，与下列命令共用设置和审核记录。修改策略后，已有待审请求仍需逐条处理。Bot 离线时可以保存规则，恢复连接后才能审核。

插件仅处理发给 Bot 的好友请求和邀请 Bot 入群的请求。普通成员申请入群、成员邀请他人入群，仍由 QQ 群原有流程处理。

快速使用

Bot 所有者可在好友私聊中直接发送命令；在专用管理群中必须提及或回复 Bot：

请求管理
请求管理 好友 审核
请求管理 入群 同意
请求管理 待审

默认情况下，好友请求和入群邀请均为「不处理」，两类私聊通知均开启。

命令参考

参数命令支持省略 请求管理 后的第一个空格，例如 请求管理好友 审核 与 请求管理 好友 审核 等价。嵌套子命令仍需保留分隔，请求管理好友审核 不会被识别。

完整帮助也可通过 帮助 请求管理 查询。通用管理入口和 Bot 所有者定义见主文档。

处理策略

好友请求和入群邀请各自保存处理规则与通知开关，两类设置互不影响。重复收到同一审核事件时，只保留一条待审记录。

数据与安全行为

• 规则、待审记录和处理结果保存在管理套件使用的主 SQLite 数据库中，不需要单独配置数据库路径。
• 自动同意、自动拒绝、加入待审、人工同意和人工拒绝都会写入管理审计。
• 人工处理按编号串行执行；已处理的记录不会重复调用平台接口。
• 读取规则、保存待审记录或调用平台失败时，插件会尽量保留请求的未处理状态，并尝试私聊通知 Bot 所有者。
• 如果平台操作已成功但数据库状态保存失败，Bot 会提示不要重复操作。
• 好友拒绝理由会传给平台；Bot 入群邀请接口不支持自定义拒绝理由。

备份管理数据库时，按管理套件的数据存储与备份中的要求操作。

排查指南

相关文档

• 项目主文档：Bot 所有者、专用管理群、部署和安全说明。
• 管理套件：权限、审计、数据库和 Web 管理后台。

Codex / Pi 群通知

codex_notify 通过当前 NoneBot/Milky Bot 向指定 QQ 群发送 Codex 和 Pi 的完成、报错、 非手动中断通知，以及 Codex 的操作授权和 Pi 的交互确认提醒。完成通知附带最终回复和本轮耗时。两端共用独立的 Python 转发脚本，不需要安装 NoneBot 或其他第三方依赖。原有插件名“Codex通知”、 CODEX_NOTIFY_* 设置和接收地址继续使用。

接收接口由现有 Web 管理后台的 HTTP 服务提供，使用后台域名、HTTPS 反向代理 和 WEB_ADMIN_HOST / WEB_ADMIN_PORT，无需额外监听端口。

本插件独立实现，参考了 Kentaczi/tele-codex 将事件接收与消息发送分开的方式。 它负责单向通知，不提供从 QQ 发起任务、审批或远程执行命令的入口。

通知行为

• “本轮处理结束”表示客户端已返回本轮最终回复，不表示需求全部实现或测试全部通过。
• 标题用“Codex”或“Pi”标明通知来源。
• Codex 和 Pi 报错时显示“本轮处理报错”和错误信息，非手动中断时显示“本轮意外中断”。 手动停止不提醒；自动重试尚未结束时不提醒。Codex 用新输入替换当前轮次和退出审阅也不提醒。
• Codex 请求操作授权、Pi 扩展弹出确认对话框时显示“等待操作授权”，需返回会话确认。群内不能代为授权。 同一轮次的相同请求只提醒一次；轮次结束后取消尚未开始投递的授权提醒，迟到的请求不再入队。
• Codex 和 Pi 的结果通知附带本轮耗时；旧 Codex 客户端没有提供耗时时不显示。 Pi 的耗时包括自动重试、压缩、排队的后续执行和等待确认的时间。
• 群消息以文字显示项目名和会话名；读取不到会话名时只显示项目名。最终回复默认排版为 Markdown PNG 图片并自动分页，个人可选择文字或按长度自动选择。
• 将 CODEX_NOTIFY_DETAIL 设置为 full（完整）时，额外显示会话 ID 和轮次 ID；默认 simple（简洁）隐藏这两个标识。
• QQ 文字部分默认最多 3500 个字符，超长文字附带截断提示；图片包含接收到的完整回复。图片生成失败时改发文字，未提供最终回复时发送文字提示。
• 不转发用户输入、过程日志或完整工作目录。
• 个人通知默认接收全部事件，可在后台筛选完成通知的耗时，并分别开关报错、意外中断和授权提醒。
• 个人通知默认在报错、意外中断和等待授权时 @ 本人，完成通知默认不 @。用户可在后台“个人通知设置”逐项调整。
• 所有者为自己和其他 QQ 号指定投递群；每个用户使用个人 Token，只向自己的指定群投递。群号不能通过通知请求修改。
• 原有部署级共享 Token 继续向全部已配置、已开启的目标群投递。
• 普通群从配置数据库读取，必须同时开启群聊和“Codex通知”插件；无需再写入 env。
• 专用管理群可以作为目标，但必须明确写入 CODEX_NOTIFY_GROUP_IDS； 它不使用受管群的插件开关，移除配置或关闭全局服务后停用。

配置 Bot

先启用或保留已有的 Web 管理后台配置，例如：

WEB_ADMIN_PUBLIC_URL=https://admin.example.com
WEB_ADMIN_HOST=127.0.0.1
WEB_ADMIN_PORT=8080

已有后台时保持原域名、地址和端口，在 Bot 的 .env.prod 中增加通知配置：

CODEX_NOTIFY_ENABLED=true
# 可选：补充目标群，例如不使用受管群开关的专用管理群。
# CODEX_NOTIFY_GROUP_IDS=[123456789]
# 可选：保留原有共享 Token 接入；多用户使用后台生成的个人 Token。
# CODEX_NOTIFY_TOKEN=REPLACE_WITH_AT_LEAST_32_RANDOM_BYTES

后台选群列表只显示已开启 Codex 通知的群。普通群从配置数据库读取，并要求群聊和 Codex 通知插件均已开启；写入 CODEX_NOTIFY_GROUP_IDS 不会绕过普通群的插件开关。 专用管理群仍通过 CODEX_NOTIFY_GROUP_IDS 明确启用。 数据库中的群聊或插件设置修改后立即生效，无需修改 env 或重启。 Bot 必须已加入目标群并能够发言。 个人 Token 在后台生成，无需配置 CODEX_NOTIFY_TOKEN。如保留共享 Token，两端使用 同一个独立生成的随机 Token，至少为 32 个无空白 ASCII 字符。 通知 Token 与后台登录会话独立，不能用于后台管理 API；后台登录 Cookie 也不能 替代通知 Token。修改部署配置后重启 Bot。启用通知却未配置 WEB_ADMIN_PUBLIC_URL 时，服务会在启动阶段报错。

普通群还需由 Bot 所有者在专用管理群开启群聊与插件，并分别确认：

@Bot 配置 群聊 123456789 开
@Bot 确认
@Bot 配置 插件 123456789 Codex通知 开
@Bot 确认

如果群聊已开启，只需开启插件。插件名也接受 codex_notify。 配置命令属于帮助中的“系统”分类，仅 Bot 所有者可用；例如：

@Bot 帮助 配置
@Bot 配置插件 123456789 Codex通知 开

紧凑形式只省略 配置 后的第一个分隔，子命令和参数之间仍需保留空格。 关闭群聊或插件会取消该群尚未投递的通知，重新开启后不会补发被取消的内容。

这些配置属于部署级设置，通过环境变量维护，不使用“配置 设置”修改。 Web 后台的普通群插件列表会显示“Codex通知”，开关权限仍限 Bot 所有者。 通知队列在后台 HTTP 服务开始接收请求前初始化，后台服务关闭时停止投递任务。 图片与聊天分析报告共用字体设置，默认使用可用中文字体，系统缺少中文字体时 自动使用项目自带字体。也可通过 ANALYSIS_REPORT_FONT_PATH 指定中文字体文件。

多用户后台接入

1. Bot 所有者私聊发送 管理后台，登录后打开 Codex 通知 页面。
2. 先开启目标群的群聊和 Codex 通知插件，再在“授权通知用户”填写 QQ 号并选择投递群。 列表只显示当前已开启通知的群，保存授权时也会重新检查开关；关闭插件后，该群立即 从可选列表移除，停止投递并取消尚未发送的通知。
3. 授权用户添加 Bot 好友后，私聊发送 管理后台，使用一次性链接登录。 群聊中也可发送 @Bot 管理后台，登录链接只通过私聊发送。
4. 在 Codex 通知 页面生成个人 Access Token、下载脚本与通知配置，按页面教程配置 Codex 的轮次通知 hook、仅完成通知的用户级 notify 或 Pi 扩展。
5. 所有者点击“设置我的投递群”，勾选目标群并保存，再生成个人 Token。所有者本人也 显示在授权列表中，可随时编辑投递群；修改后立即生效，已有个人 Token 无需更换。 生成或重置 Token 都会保留指定群，后续开启其他群的通知插件不会扩大个人投递范围。 尚未设置投递群时，所有者的个人通知不会发送，也不能生成个人 Token。

所有者的客户端应使用后台生成的个人 Token。旧部署级共享 CODEX_NOTIFY_TOKEN 继续按全局范围投递，不使用个人投递群设置。

管理后台 必须完整匹配；管理后台123 和 管理后台 现在 不会触发。 该命令属于“系统”帮助分类，仅向管理角色和通知授权用户展示。 授权用户可发送 帮助 系统（也支持 帮助系统）查看入口说明。 只有通知授权的普通成员只能查看自己的通知页面，不能获取群管理、问答或运行时配置权限； 管理角色仍按原有范围执行操作，通知权限由所有者单独授权。

个人 Token 仅在生成后显示一次，页面提供复制和配置下载；数据库仅保存 Token 的 SHA-256 摘要，不保存原文。离开页面后需重置 Token 才能再次获取；重置使旧 Token 立即失效， 用户需更新本地配置。每个 QQ 号有一个有效 Token，可供其多台设备使用。 所有者撤销授权后，该用户的 Token 和通知后台访问权限立即失效，待投递通知取消； 移除某个投递群也会取消该用户在该群的待投递通知。所有者移除自己的投递设置后， 个人 Token 失效、待投递通知取消，仍可登录和管理后台。已发送消息不会撤回。 授权、Token 摘要和投递状态均保存在 CODEX_NOTIFY_DATABASE_PATH，重启后保留。

个人通知设置

授权用户在通知页面的“个人通知设置”中选择需要 @ 自己的事件，保存后用于新接收的 Codex 和 Pi 通知。完成、报错、意外中断和等待授权均可单独勾选；默认仅勾选后三项。 只会 @ Token 所属 QQ 账号，客户端不能指定其他人。共享 Token 没有个人身份，不发送 @ 提醒。

“通知范围”提供三种选择：

• 全部通知：接收全部完成通知。
• 仅异常和授权：关闭完成通知。
• 仅接收耗时超过 N 分钟的完成通知：仅接收耗时严格超过门槛的完成通知，门槛为 1 至 1440 的整数分钟。 恰好等于门槛或客户端未提供耗时时不发送完成通知。

报错、意外中断和授权提醒分别通过“异常与授权通知”的开关控制，不受上述耗时门槛限制。 关闭事件通知后，即使勾选该事件的 @ 选项也不会发送消息。共享 Token 继续发送全部事件。

“消息显示方式”提供三种选择：

• 文字：标题与最终回复一起发送，便于搜索和复制。超过文字上限时截断并显示“回复已截断”。
• 图片：标题用文字，最终回复排版为 Markdown 图片；长回复自动分页。这是默认模式。
• 按长度自动选择：标题与回复的文字总长度不超过部署设置的文字上限时发送文字，否则发送图片。 默认上限为 3500 字符，@ 后的换行也计入文字长度。

图片生成失败时自动改发有长度限制的文字。QQ群发送失败仍保留队列并重试。 共享 Token 和升级前已入队的通知使用默认图片模式，也支持图片失败降级。

被过滤的事件仍会确认接收并记录去重；被过滤的结束事件仍清理该轮尚未投递的授权提醒。 修改设置后重新提交同一事件不会补发。

设置保存在数据库中，重启、重置个人 Token 或调整投递群后保留。已入队通知使用接收时的 设置，修改偏好不会改变正在重试的通知。所有者需先设置自己的投递群，才能保存个人设置。

配置 Codex 转发脚本

转发脚本为 scripts/codex_notify.py， 要求 Python 3.10+。脚本可以与 Bot 分别运行在不同机器上。

将 scripts/codex_notify.example.json 复制到 Codex 实际执行环境 的用户配置目录，例如 ~/.codex/qqbot-notify.json，填写：

{
  "url": "https://admin.example.com/integrations/codex/notify",
  "token": "REPLACE_WITH_THE_SAME_BOT_TOKEN",
  "timeout_seconds": 10
}

将示例域名替换为现有 WEB_ADMIN_PUBLIC_URL，并追加 /integrations/codex/notify。同机联调可使用 http://127.0.0.1:8080/integrations/codex/notify，端口应与 实际 WEB_ADMIN_PORT 一致。

保护配置文件，Linux 可执行 chmod 600 ~/.codex/qqbot-notify.json。 脚本也支持 CODEX_NOTIFY_URL、CODEX_NOTIFY_TOKEN 和 CODEX_NOTIFY_TIMEOUT_SECONDS 环境变量，环境变量优先于 JSON 文件。 桌面端建议使用配置文件，以免桌面应用启动时没有继承所需的环境变量。

如需完成、报错、非手动中断及操作授权提醒，使用下方的轮次通知 Hook。 只需要完成通知时，可在 Codex 用户级 ~/.codex/config.toml 顶层配置 notify：

notify = [
  "/usr/bin/python3",
  "/absolute/path/qqbot_manager/scripts/codex_notify.py",
  "--config",
  "/home/yourname/.codex/qqbot-notify.json"
]

路径必须替换为实际 Python、脚本和配置文件的绝对路径。不要把 notify 放在 [tui] 等其他表内，也不要覆盖已经存在的其他通知脚本而不保留其功能。 Codex 会将通知 JSON 自动追加为最后一个参数。 项目级 .codex/config.toml 中的 notify 会被 Codex 忽略。

Windows 原生执行环境的示例：

notify = [
  "C:/Python313/python.exe",
  "D:/qqbot_manager/scripts/codex_notify.py",
  "--config",
  "C:/Users/YourName/.codex/qqbot-notify.json"
]

在 WSL 中运行 Codex 时，使用 WSL 路径和该环境的配置目录；在 Windows 原生环境中 运行时，使用 Windows 路径。请按任务的实际执行环境配置路径，仓库存放位置不能决定执行环境。 配置后重启客户端或新建会话，并运行一个短任务验证该客户端是否触发 notify。

Codex 轮次通知 Hook（CLI / App / WSL）

Windows Codex App 可能将顶层 notify 包装为自己的 Windows 桌面回调。 任务在 WSL 中执行时，该 Windows 路径无法直接启动；修改这个路径还可能被 App 再次覆盖。这种执行环境使用原生钩子接入，保留 App 自己的 桌面回调，并移除其中旧的 QQ 转发入口，避免两条通知入口同时启用。

所用版本需支持异步 UserPromptSubmit 钩子，并在轮次结束记录中提供错误信息； 已使用 Codex CLI 0.162.0-alpha.17.2 验证完成、失败和手动停止。 在用户配置的 [features] 中启用 hooks = true， 在实际 CODEX_HOME 下的 hooks.json 中添加以下配置。 替换旧的 QQ 通知 Stop 项或 notify 入口，保留其他钩子和 App 桌面回调。 Python、脚本和配置路径均使用实际执行环境的绝对路径；以下为 WSL 示例。

{
  "hooks": {
    "UserPromptSubmit": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "/usr/bin/python3 /absolute/path/qqbot_manager/scripts/codex_notify.py --config /mnt/c/Users/YourName/.codex/qqbot-notify.json --hook",
            "async": true,
            "timeout": 86400,
            "statusMessage": "等待 Codex 轮次结果"
          }
        ]
      }
    ],
    "PermissionRequest": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "/usr/bin/python3 /absolute/path/qqbot_manager/scripts/codex_notify.py --config /mnt/c/Users/YourName/.codex/qqbot-notify.json --hook",
            "async": true,
            "timeout": 45,
            "statusMessage": "发送操作授权提醒"
          }
        ]
      }
    ]
  }
}

--hook 收到 UserPromptSubmit 后，由 Codex 在后台运行，只读该会话的 transcript_path，等待对应 turn_id 的结束记录，再提交一次结果。 不转发用户输入、工具输出或中间错误；有终态错误才发报错提醒。 手动停止等无需提醒的结束记录只提交静默结束事件，用于清理排队中的授权提醒。 PermissionRequest 同样在后台提交提醒，发送操作名称，不发送命令、工具参数或用户输入。 请求标识由工具和参数计算摘要，同一轮次的相同请求重复触发时不会重复提醒。 脚本不返回授权决定、继续任务或阻止结束的指令， 提交失败会报钩子错误。现有 Stop 接入仍可发送完成通知，但不支持异常提醒， 不要与新的轮次通知 Hook 同时使用。

技术说明：兼容 task_complete / turn_complete 的 error 字段以及 turn_aborted 记录。忽略 interrupted、replaced、review_ended 中断原因， 其余中断原因发送提醒。记录文件尚未创建时会短暂重试，被截断后会重新读取。 后台 Hook 最长等待 24 小时，收到结束记录即退出， 会话关闭时由 Codex 取消。应用被强制结束、没有写入结束记录时无法发送提醒。 会话记录格式可能随 Codex 更新变化，升级后需验证实际完成和失败事件。

Codex 的接入方式都会自动补充会话名：只读查询 CODEX_SQLITE_HOME（未设置时使用 CODEX_HOME，默认 ~/.codex）下的 state_*.sqlite，优先使用会话 name， 其次使用 title；数据库不可用或没有对应记录时，读取 CODEX_HOME 下的 session_index.jsonl 中该会话最新的 thread_name。读取失败仍照常提交通知。

新建或修改的钩子必须通过 Codex 的钩子信任检查后才会执行。在 CLI 的 /hooks 中检查、审阅并信任这个具体钩子，再用新会话验证实际轮次结束事件。 手动调用脚本成功说明通知可以提交；App 是否会自动触发，还需用实际轮次结束事件验证。

配置 Pi

Pi 0.87.0+（需支持 agent_before_settle、agent_settled 和 ui_prompt_start）通过扩展 scripts/pi_notify.ts 接入。 将它复制到 ~/.pi/agent/extensions/qqbot-notify.ts，或在 Pi 用户级 settings.json 的 extensions 数组中追加该文件的绝对路径。保留已有扩展和设置。 使用 PI_CODING_AGENT_DIR 时，以下文件放在该目录下。

在 ~/.pi/agent/qqbot-notify.json 配置转发命令，Python、脚本及通知配置均使用 实际执行环境的绝对路径：

{
  "command": [
    "/usr/bin/python3",
    "/absolute/path/qqbot_manager/scripts/codex_notify.py",
    "--config",
    "/home/yourname/.codex/qqbot-notify.json"
  ]
}

--config 指向前文包含 url、token 和 timeout_seconds 的通知配置文件， 可以复用已有 Codex 配置，也可以使用 Pi 自己的文件。无需另配置接口、Token 或目标群。 Windows 原生 Pi 可使用 Windows Python 和脚本路径；如果转发脚本保存在 WSL， 则将 command 设为以下形式，并替换发行版名称及路径：

{
  "command": [
    "C:/Windows/System32/wsl.exe", "--distribution", "Ubuntu", "--exec",
    "/usr/bin/python3",
    "/home/yourname/qqbot_manager/scripts/codex_notify.py",
    "--config", "/mnt/c/Users/YourName/.codex/qqbot-notify.json"
  ]
}

扩展通过标准输入传递通知，转发命令不经 shell 执行。Pi 在 agent_settled 事件触发后发送结果：自动重试、压缩和排队的后续执行结束后，才投递最终回复、 报错或意外中断提醒，并附带从本轮开始到结束的耗时。失败和中断不转发未完成的回复； 工具调用消息、思考内容和用户输入不转发。手动停止保持静默。

Pi 扩展在本轮运行中使用 ctx.ui.confirm() 等待确认时，立即发送操作授权提醒。 提醒只包含工具名称；没有唯一的正在运行工具时显示“交互确认”，不转发对话框标题、命令或工具参数。 选项、输入框、编辑器和自定义界面不发送授权提醒。确认仍在 Pi 中完成。

会话名直接从 Pi 读取，未命名时只显示项目名。每轮生成独立轮次 ID，自动重试和后续执行 沿用该 ID，授权提醒与最终结果也使用同一个 ID；相同确认请求按请求标识去重。 手动停止或工具结束且未提供最终回复时，仅在已有授权提醒的情况下提交静默结束事件， 清理尚未投递的授权提醒。重复触发结束事件不会重新提交通知。 提交失败在 Pi 中显示提示；转发子进程最多运行 45 秒。

技术说明：agent_before_settle 的结果区分正常完成、报错和非主动中断；显式取消会跳过 该边界，因此只清理授权提醒。每次底层 agent_start 保留整轮起始时间，最终在 agent_settled 计算耗时。会话切换、重新加载或关闭时清理扩展状态，不发送旧回复。 强制结束进程、没有触发结束事件时无法发送提醒。

升级时替换原有 Pi 扩展并重新启动 Pi；已使用绝对路径加载仓库脚本时可重新加载扩展。 Bot 端需升级到支持 Pi 的版本并重启，群消息才能正确显示 “Pi”及项目名、会话名。原有 Codex通知 群开关同时控制两种来源。

复用现有后台站点

现有后台的 location / 代理可以直接处理 /integrations/codex/notify， 继续转发到现有后台服务，配置示例见 部署手册。 若代理只允许部分路径，将该通知路径加入原站点的代理范围，并保留 Authorization 请求头。不同机器之间使用后台现有 HTTPS 地址，无需增加 域名、证书或对外开放的端口。

脚本只允许 HTTPS 或本机 HTTP，不跟随重定向；不要把 Token 放在 URL 中。 此前独立通知监听已移除；升级时将发送地址改为后台域名下的新路径，并清理旧的 独立监听配置和代理规则。

手动验证

先启动 Bot、配置目标群和开关，再在 Codex 执行环境运行：

python3 /absolute/path/qqbot_manager/scripts/codex_notify.py \
  --config "$HOME/.codex/qqbot-notify.json" \
  '{"type":"agent-turn-complete","thread-id":"manual-test","turn-id":"1","cwd":"/tmp/demo","last-assistant-message":"通知链路测试。"}'

脚本退出码 0 表示服务已接收或已接收过相同事件，不表示 QQ 已发送成功。 再次使用相同会话和轮次不会重新投递；再次测试时换一个 turn-id。 脚本最多向服务提交三次，网络错误或 HTTP 5xx 会短暂退避后重试； 配置错误、其他 HTTP 错误或最终提交失败返回非零退出码。 未知事件类型直接忽略，不发送网络请求。

接口与持久化

接口为 POST /integrations/codex/notify，要求 Content-Type: application/json 和 Authorization: Bearer <Token>，请求体上限为 256 KiB。 接口不要求后台登录 Cookie 或浏览器 Origin，其他后台 /api/* 仍执行原有的 会话鉴权与来源检查，普通后台 API 的 16 KiB 请求体上限保持不变。

其他字段不参与消息生成或群路由。转发脚本只提交上述字段，并将超过 40000 字符的最终回复截断；Bot 接收的最终回复最多为 64000 字符，并受请求体大小限制。

已接收的完整回复保存在通知数据库中，Bot 重启后继续生成图片并投递。 升级前已经被截断的待投递回复会按保存的内容生成图片。 Milky Bot 离线时保留队列，恢复后继续发送； 发送失败采用指数退避，首次等待 5 秒，最长等待 30 分钟，投递循环每 5 秒检查。 每个群独立记录结果，重试某个群不会重新发送到已成功的其他群。 日志只记录目标群、尝试次数和错误类型，不记录 Token、最终回复或用户输入。

默认情况下，同一用户、来源、会话和轮次的接收去重记录持续保存在数据库中；启用下述保留策略后，去重保障覆盖配置的保留窗口。用户之间分别去重； 个人 Token 重置不会改变该 QQ 号的去重记录。Pi 使用内部会话前缀隔离， 原有 Codex 去重记录保持有效。授权提醒额外按请求标识去重，与本轮最终结果分别保存。 结束事件会清理对应用户、来源、会话及轮次的待发授权提醒；静默结束事件不创建群投递。 去重记录保留期间，已结束轮次的迟到授权请求也返回 200、status=duplicate，不再投递。 QQ 发送与本地数据库提交无法在同一事务中完成。若 QQ 已收到消息，但请求超时，或进程在保存成功状态前退出，重试可能重复发送。因此，通知会持久保存并重试，但无法保证 QQ 只收到一次。 删除数据库会丢失用户授权、Token 摘要、去重和待投递状态。

Bot 整个进程停止时无法接收新事件；转发脚本三次提交失败后不会在后台无限重试。 只有已经收到 accepted 的事件才有恢复后补发保障。

保留策略与备份

新增的数据清理默认关闭。确认保留期限并完成备份后，在部署环境中设置 DATA_RETENTION_CLEANUP_ENABLED=true 并重启。管理套件每天统一维护；即使通知投递开关关闭，已有通知数据库也会参与清理。

• CODEX_NOTIFY_CONTENT_RETENTION_DAYS=7：整条通知的所有目标群都已发送或取消后，保留正文和投递明细 7 天；之后清除这些内容，继续保留接收去重键。
• CODEX_NOTIFY_DEDUP_RETENTION_DAYS=30：从相同完成时间起保留去重键 30 天，不得短于正文保留期。过滤后的通知、静默结束事件和已取消的授权提醒也使用此策略。
• 仍有待投递目标的通知不参与清理，包括已成功发送到部分群的通知。服务端继续按原退避规则重试；客户端自动提交最多三次，远短于至少一天的去重窗口。窗口到期后，手工重放相同事件会被作为新事件接收。
• 升级时无法确定完成时间的历史已完成记录，从升级时开始计算保留期。用户授权、个人偏好和 Token 摘要持续保留。

启用或缩短期限前，使用 SQLite 在线备份或停机备份 CODEX_NOTIFY_DATABASE_PATH，备份放在清理目录之外，并由运维设置独立保留期、验证恢复。导出、分析报告和主数据库的保留与备份规则见管理套件的数据存储与备份。

本接口仅接收结果和授权提醒。是否授权或确认，仍需回到 Codex 或 Pi 会话决定；通知也不代表任务目标已达成。 客户端接入方式以 OpenAI 的 通知文档 和配置参考为准。 异步钩子的配置与运行规则见 Hooks 文档。

公开 GitHub 发布与部署

Web 管理后台启用后，同站点 /docs 与 /docs/raw 分别提供公开使用文档和 Markdown 原文，无需登录。反向代理需转发这两个路径；根路径与 /api/* 仍要求登录并检查权限。

发布时保留 docs/、各插件 README、项目 README、本部署文档和 WEBSITE_INTEGRATION.md。修改文档后，重启服务即可更新页面。不要将整个仓库配置为静态文件根目录。

示例中的个人用户名、主目录、服务器地址、QQ 号、访问令牌和私有仓库路径均使用占位值。 执行命令前，请将 GITHUB_OWNER 等全大写占位符替换为实际值。

公开前隐私检查

公开仓库只应包含源码和脱敏示例。以下内容必须留在本地或受控服务器上：

• .env、.env.prod 及其他真实环境配置；
• data/、SQLite 数据库、导出文件、备份和日志；
• API Key、访问令牌、SSH 私钥、真实 QQ 号、服务器地址和私有部署路径；
• IDE 配置、虚拟环境及运行时缓存。

仓库的 .gitignore 已忽略上述运行时文件。不要使用 git add -f 绕过忽略规则。

每次公开推送前检查暂存内容：

git status --short
git diff --cached --check
git diff --cached
git ls-files | rg '(^|/)(\.env($|\.)|data/|backups/|\.idea/|\.venv/)'
git grep -n -I -E 'BEGIN (RSA |OPENSSH |EC )?PRIVATE KEY|(/home/|/Users/)|access[_-]?token|api[_-]?key'

最后两条命令只允许命中脱敏示例字段和本文档中的检查规则，也可能没有输出。 公开前必须逐条检查命中结果，确认没有泄露信息。

Git 提交元数据同样会公开。在新的公开仓库中提交前，建议使用公开显示名和 GitHub 提供的 noreply 邮箱：

git config user.name "PUBLIC_DISPLAY_NAME"
git config user.email "GITHUB_ID+GITHUB_USERNAME@users.noreply.github.com"

不携带私有历史进行首次公开

在新提交中删除敏感文本，并不会从旧提交中删除这些内容。首次公开前应在本地检查：

git log --all --format='%h %an <%ae>'
git log -p --all -- DEPLOYMENT.md

仓库曾经包含私有部署信息时，推荐从已审核的当前提交生成无历史快照。 按以下流程创建公开仓库，原私有仓库会保留，旧提交及其作者元数据不会进入公开仓库：

git status --short
git archive HEAD -o ../qqbot-manager-public.tar
mkdir ../qqbot-manager-public
tar -xf ../qqbot-manager-public.tar -C ../qqbot-manager-public
cd ../qqbot-manager-public
git init --initial-branch=main
git config user.name "PUBLIC_DISPLAY_NAME"
git config user.email "GITHUB_ID+GITHUB_USERNAME@users.noreply.github.com"
git add -A
git diff --cached --check
git commit -m "feat: publish initial QQ bot manager"
git remote add origin https://github.com/GITHUB_OWNER/qqbot_manager.git
git push -u origin main

确认公开仓库内容无误后删除临时压缩包。不要复制私有仓库的 .git/ 或任何未跟踪 文件。

如果必须保留历史，应使用专门的 Git 历史清理工具，并逐个检查全部提交。历史重写 会改变提交 ID；共享仓库未经协商不得执行。

服务器约定

示例中的部署账号和路径如下：

公开仓库：https://github.com/GITHUB_OWNER/qqbot_manager.git
运行目录：/opt/qqbot-manager
服务账号：qqbot-manager
systemd 单元：qqbot-manager.service

服务器需要 Git、Python 3.10 或更高版本以及 uv。systemd 中使用的 uv 绝对 路径必须与服务器上 command -v uv 的结果一致。

首次安装

创建独立的服务账号并克隆公开仓库：

sudo useradd --system --create-home --home-dir /var/lib/qqbot-manager \
  --shell /usr/sbin/nologin qqbot-manager
sudo git clone --branch main \
  https://github.com/GITHUB_OWNER/qqbot_manager.git \
  /opt/qqbot-manager
sudo chown -R qqbot-manager:qqbot-manager /opt/qqbot-manager

使用锁文件安装依赖：

sudo -u qqbot-manager sh -c \
  'cd /opt/qqbot-manager && uv sync --frozen'

Markdown 消息图片和聊天分析报告随项目提供中文字体，无需额外安装字体包。 也可通过 ANALYSIS_REPORT_FONT_PATH 指定中文字体；文件不可用或不支持中文时， 渲染器会自动使用其他可用中文字体。部署时保留 plugins/bot_core/resources/fonts/ 目录及其中的字体和授权文件。

从脱敏模板创建生产配置：

sudo -u qqbot-manager cp \
  /opt/qqbot-manager/.env.example \
  /opt/qqbot-manager/.env.prod
sudo chmod 600 /opt/qqbot-manager/.env.prod
sudoedit /opt/qqbot-manager/.env.prod

先替换所有 REPLACE_WITH_... 占位符，再根据当前 Milky 适配器官方文档补充连接 配置，所有 Token 只保存在 .env.prod。不要把完成后的配置粘贴到 Issue、PR、CI 日志或聊天中。

网站公告与正式版本通知

网站通知默认关闭。启用前，网站必须先按 WEBSITE_INTEGRATION.md 部署持久化事件表和增量事件 API。 使用独立生成的至少 32 字节随机 Token，并分别存放在网站的密钥管理系统与 Bot 的 .env.prod；不要复用 Milky、GitHub、数据库或其他服务的 Token。

在 .env.prod 中配置：

WEBSITE_NOTIFICATIONS_ENABLED=true
WEBSITE_EVENTS_URL=https://example.com/api/integrations/qqbot/events
WEBSITE_EVENTS_TOKEN=REPLACE_WITH_AT_LEAST_32_RANDOM_BYTES
WEBSITE_NOTIFICATION_GROUP_IDS=[REPLACE_WITH_WEBSITE_USER_GROUP_QQ]
WEBSITE_POLL_INTERVAL_SECONDS=60
WEBSITE_REQUEST_TIMEOUT_SECONDS=10

网站通知目标群独立于 QQ 群聊及插件开关，且不得包含 MANAGEMENT_GROUP_ID。第一次启用 只保存网站当前游标，不发送已有公告或已有版本；此后 Bot 停机期间生成的事件会在 恢复后补发。若要回退，只需关闭 WEBSITE_NOTIFICATIONS_ENABLED 并重启服务，不要 删除 SQLite 数据库，否则会丢失游标和待投递状态。

网站内测注册可以独立于网站通知启用。网站接口必须先部署 POST /api/integrations/qqbot/registration-invitations，然后在 .env.prod 中配置：

WEBSITE_REGISTRATION_ENABLED=true
WEBSITE_REGISTRATION_URL=https://example.com/api/integrations/qqbot/registration-invitations
WEBSITE_REGISTRATION_GROUP_ID=REPLACE_WITH_BETA_TEST_GROUP_QQ

内测成员好友私聊发送 内测注册。Bot 会实时确认成员仍在指定内测群，随后使用 WEBSITE_EVENTS_TOKEN 获取 24 小时有效的一次性注册链接。该 Token 只能注入受控 Bot 运行环境，不得写入日志或仓库。

个人网站排班通知

先在网站部署个人排班接口并执行数据库迁移 2026-10-04.1，再在上方网站通知配置中增加：

WEBSITE_QQBOT_TOKEN=REPLACE_WITH_A_SEPARATE_32_BYTE_RANDOM_TOKEN
WEBSITE_QQBOT_POLL_INTERVAL_SECONDS=15

个人排班归入网站通知，共用 WEBSITE_NOTIFICATIONS_ENABLED 和 WEBSITE_NOTIFICATION_GROUP_IDS，网站根地址从 WEBSITE_EVENTS_URL 推导。 WEBSITE_QQBOT_TOKEN 至少 32 字节，与网站侧相同，独立于公告 WEBSITE_EVENTS_TOKEN 和网站发布确认 Token；未配置时仍可只使用群公告和状态监控。Bot 部署成功后才开放 网站绑定入口。具体接口约定见 网站集成文档。

网站通知群的当前成员先添加 Bot 为好友，在网站账号安全页生成绑定码，私聊发送 绑定网站 <绑定码>， 再发送 开启排班通知。已有内测资格关联也需要主动完成本功能绑定。 发送 帮助 网站排班 查看账号、结果查询、下载和解绑操作。个人功能只支持好友私聊， 群临时会话不能接收文件。每次操作及实际推送前重新检查成员身份；退出网站通知群后 停止个人推送。自动导出不会消耗体验券，手动用券下载必须先确认消耗 1 张券。

投递记录存入管理 SQLite，文字、文件和网站 ACK 分别保存状态；重启后继续重试未完成 步骤。公告和个人排班共用 HTTP 客户端，由网站通知统一启停。一个网站部署只运行 一个个人排班轮询实例，并保留数据库中的去重记录。 每轮分页扫描未 ACK 通知，不永久保存分页游标；共享请求额度，并遵守 Retry-After。 通知和本地投递记录保留 7 天。文件直接以内存字节上传，不生成公开链接或临时文件。

Codex / Pi 群通知

Codex 通知插件接收 Codex 和 Pi 的完成、报错、非手动中断事件，以及 Codex 操作授权和 Pi 交互确认请求，默认关闭，复用当前 Milky Bot 向指定群投递提醒和最终回复， 接收接口复用下方 Web 管理后台的域名、HTTPS 代理和 HTTP 服务，不另开端口。 需要在 Bot 端配置 CODEX_NOTIFY_ENABLED、CODEX_NOTIFY_TOKEN 和 CODEX_NOTIFY_GROUP_IDS，普通群还需开启群聊及“Codex通知”插件。 专用管理群可直接写入目标列表，无需受管群开关。

在 Codex 实际执行环境中配置 scripts/codex_notify.py 的地址与 Token，并在 用户级 config.toml 顶层设置 notify。发送地址为已有 WEB_ADMIN_PUBLIC_URL 追加 /integrations/codex/notify；同机联调可直接使用后台本机地址。 启用通知必须先配置 WEB_ADMIN_PUBLIC_URL，接口使用独立通知 Token，不复用后台 登录 Cookie。现有后台 location / 代理可直接转发通知，无需新增监听或代理端口。 Pi 0.87.0+ 使用 scripts/pi_notify.ts 扩展，在整个执行结束后通过同一转发脚本提交结果及耗时， 等待扩展确认对话框时发送提醒，直接读取 Pi 会话名。升级时替换原有扩展并重新加载或重启 Pi。 Bot 需升级到支持 Pi 的版本后才能正确显示来源并隔离去重记录。 完整配置、Windows/WSL 路径、手动验证及离线投递限制见 Codex / Pi 通知手册。

Web 管理后台

后台默认关闭。启用时，为备案域名配置独立 HTTPS 站点，并反向代理到 Bot 的本机监听端口。

后台前端使用 TypeScript、React、Tailwind CSS 和 Vite。安装 Node.js 22.18+（推荐 24 LTS），在服务启动前构建静态资源：

sudo -u qqbot-manager sh -c \
  'cd /opt/qqbot-manager/frontend && npm ci --include=dev && npm run build'

frontend/dist/ 不纳入 Git，部署时必须构建或上传该目录。缺少构建产物时，根页面会返回 503 并说明原因。Python 服务提供 /assets/*，无需运行 Vite 或另起 Node 服务；反向代理继续转发所有路径。开发、类型检查和浏览器回归见 前端说明。

WEB_ADMIN_PUBLIC_URL=https://admin.example.com
WEB_ADMIN_HOST=127.0.0.1
WEB_ADMIN_PORT=8080
WEB_ADMIN_LINK_TTL_SECONDS=300
WEB_ADMIN_SESSION_TTL_SECONDS=43200

配置 Nginx 代理时，将以下示例中的证书配置和域名替换为实际值：

server {
    listen 443 ssl http2;
    server_name admin.example.com;

    location / {
        proxy_pass http://127.0.0.1:8080;
        proxy_set_header Host $host;
        proxy_set_header X-Forwarded-Proto https;
        proxy_set_header Authorization $http_authorization;
        proxy_read_timeout 18m;
    }
}

proxy_read_timeout 18m 为 Web 后台执行 更新插件 预留构建时间，前端该请求也使用 18 分钟超时。已有站点需更新代理配置，执行 sudo nginx -t 验证后通过 sudo systemctl reload nginx 生效；其他代理也需设置相应超时。QQ 命令不依赖此代理等待。

不要直接将 WEB_ADMIN_PORT 暴露到公网。部署完成后，Bot 所有者在好友私聊中向 Bot 发送 管理后台 获取一次性链接，命令必须完整匹配。非敏感查询参数仅用于强制浏览器加载新页面，访问令牌所在的 链接片段不会随 HTTP 请求发送，应用也关闭了 aiohttp 访问日志。 页脚备案信息默认留空，由 Bot 所有者在后台“运行时配置”中设置 manager.web_footer_icp（ICP 备案文字）和 manager.web_footer_police（地区名 + 公网安备 + 14 位数字 + 号）。保存后刷新后台或公开文档页即生效，无需重启；使用 - 清空对应项。公安备案图标仅在公安备案信息已配置时展示，链接由编号自动生成。

若要启用入群验证，Bot 必须是每个目标群的管理员，才能撤回验证问答、禁言和踢出 超时成员。私聊验证还依赖 QQ/Milky 能接收新人主动发起的好友私聊或群临时会话； 上线前应使用测试账号分别验证这两种私聊入口。Bot 无法替用户撤回私聊答案。

启动前执行验证：

sudo -u qqbot-manager sh -c \
  'cd /opt/qqbot-manager && uv run python -m compileall -q plugins tests'
sudo -u qqbot-manager sh -c \
  'cd /opt/qqbot-manager && uv run python -m unittest -v'

systemd 服务

创建 /etc/systemd/system/qqbot-manager.service。如果 command -v uv 返回其他 位置，请替换下面的 /usr/local/bin/uv：

[Unit]
Description=QQ Bot Manager
After=network-online.target
Wants=network-online.target

[Service]
Type=simple
User=qqbot-manager
Group=qqbot-manager
WorkingDirectory=/opt/qqbot-manager
Environment=ENVIRONMENT=prod
ExecStart=/usr/local/bin/uv run --frozen python bot.py
Restart=always
RestartSec=5
UMask=0077

[Install]
WantedBy=multi-user.target

加载并启动服务：

sudo systemctl daemon-reload
sudo systemctl enable --now qqbot-manager.service
sudo systemctl is-active qqbot-manager.service

检查日志：

sudo journalctl -u qqbot-manager.service -n 100 --no-pager

如果日志包含 Token、QQ 号、消息正文、服务器地址或本地路径，必须脱敏后才能对外 分享。

日常发布

V3 首次启动会不可逆删除旧事件表、旧清理审批表及其专属审计记录，并从群设置中 移除双人审批字段。应用不会保留影子副本。升级前若可能需要回滚，必须先停止服务并 通过独立流程备份 data/qqbot_manager.sqlite3；代码回滚不能恢复已经删除的数据。

开发环境先验证再推送公开仓库：

uv run python -m compileall -q plugins tests
uv run python -m unittest -v
npm --prefix frontend ci
npm --prefix frontend test
npm --prefix frontend run build
git diff --check
git status --short

本地 main 跟踪私有生产仓库，公开检出位于同级目录 qqbot_manager_public。 两者历史分叉，不要从私有仓库直接推送或合并到公开仓库。确认工作区干净、当前提交 的文件符合上文的隐私检查后，从私有提交导出受 Git 管理的文件，再在公开检出中 复核差异、提交并推送。不要复制私有仓库的 .git/ 或运行时数据：

git archive HEAD | tar -xf - -C ../qqbot_manager_public
cd ../qqbot_manager_public
git status --short
git diff --check
git diff
git add -A
git diff --cached --check
git diff --cached
git commit -m "chore: sync reviewed public source"
git push origin main

归档不会删除公开检出中私有仓库已删除的文件；提交前还要检查 git ls-files 并移除过时文件。提交元数据应使用公开显示名和 GitHub noreply 邮箱。

服务器仅接受快进更新，并在重启前完成验证：

sudo -u qqbot-manager git -C /opt/qqbot-manager pull --ff-only origin main
sudo -u qqbot-manager sh -c \
  'cd /opt/qqbot-manager && uv sync --frozen'
sudo -u qqbot-manager sh -c \
  'cd /opt/qqbot-manager/frontend && npm ci --include=dev && npm test && npm run build'
sudo -u qqbot-manager sh -c \
  'cd /opt/qqbot-manager && uv run python -m compileall -q plugins tests'
sudo -u qqbot-manager sh -c \
  'cd /opt/qqbot-manager && uv run python -m unittest -v'
sudo systemctl restart qqbot-manager.service
sudo systemctl is-active qqbot-manager.service

Bot 所有者执行的 更新插件 和 重启插件 依赖 Restart=always：Bot 回复命令后向自身发送 终止信号，由 systemd 重新启动，无需 sudoers 授权。更新插件 执行 git pull --ff-only 和 uv sync --frozen；Web 后台启用时还会执行前端 npm ci --include=dev（生产环境也安装 TypeScript、Vite 等构建依赖），然后将 npm run build 的产物写入临时目录。构建成功后复制散列资源到 frontend/dist/assets/， 保留旧资源供已打开的页面使用，最后原子替换 index.html 并触发重启。构建或部署失败 会保留原页面入口且不重启；更新期间拒绝重复更新和重启，临时构建目录会自动清理。 失败不会自动回滚已拉取的代码或已同步的依赖。重启插件 只触发重启。

服务环境的 PATH 必须能找到 git、uv、npm 和 node。生产 Git 远程仓库必须 位于启用 ProtectHome=true 后仍可访问的路径，例如 /path/to/accessible/repos/qqbot_manager.git，且工作树与 .git 应由运行账号或其有效组持有。 重启后的 Bot 连接成功后，会私聊通知所有者更新或重启已完成。

手工部署时，依赖安装、编译或测试失败不要重启服务，也不要直接在服务器修改受 Git 管理的源码。

MaiBot 群聊桥接

MaiBot 使用独立进程和独立运行目录，但继续复用本项目现有的 Milky QQ 会话。不要让 同一 QQ 账号再登录 NapCat，也不需要在 LLBot 中开启额外 WebSocket。桥接端口默认只 监听 127.0.0.1，MaiBot 官方 NapCat Adapter 作为客户端连接该端口。

在 Bot 的生产环境文件中配置独立的至少 32 字节 Token，并用双重群范围限制测试：

MAIBOT_BRIDGE_ENABLED=true
MAIBOT_BRIDGE_HOST=127.0.0.1
MAIBOT_BRIDGE_PORT=18082
MAIBOT_BRIDGE_TOKEN=REPLACE_WITH_AT_LEAST_32_RANDOM_BYTES
MAIBOT_BRIDGE_GROUP_IDS=[REPLACE_WITH_TEST_GROUP_QQ]
MAIBOT_BRIDGE_OUTBOUND_ENABLED=true

MaiBot 官方适配器还应使用群白名单、关闭主动私聊工具并清空私聊白名单。服务端会再次 拒绝私聊、管理群、未启用群、@全体成员 和所有群管理动作。上线前应告知测试群成员 群内包含 AI 生成内容，且消息可能发送至所配置的第三方模型服务。

回滚

出现问题时，建议先在公开仓库修复并发布新提交。需要恢复服务器版本时，先确认工作区干净， 再找到已验证的提交：

git -C /opt/qqbot-manager status --short
git -C /opt/qqbot-manager log --oneline --decorate -5

不要在运行目录执行 git clean -fdx，该命令可能删除被忽略的生产配置和数据。 .env.prod 与 data/ 应通过独立且受访问控制的流程备份，备份不得提交到 Git。

网站公告与正式版本通知接口

网站与 QQ Bot 通过 V1 接口同步公告和正式版本通知。Bot 通过 HTTPS 定时读取事件流， 网站无需访问 Bot，也无需为 Bot 配置公网 webhook。

发布事件模型

网站需在自身数据库中增加只追加记录的通知事件表。字段名称可按网站现有 ORM 约定调整，各字段的含义和约束必须符合下表：

事件表不参与日常清理。event_id 永不复用，同一 ID 的公开字段也不得修改；这样 Bot 可以在长期离线后继续读取，并能安全识别网站的幂等重放。

Bot 优先将标题和 markdown 正文渲染为 Markdown PNG 图片，长内容自动分页， 不裁切代码块、链接或列表。正文原样持久化，重启和发送重试使用同一快照；SQLite 启动迁移 0022_website_notification_markdown 为已有事件增加可空正文，不改变投递状态或游标。

markdown 缺失、为 null 或为空白时使用 summary。版本通知增加“更新内容” 标题。公告和版本的纯文本摘要均按换行、中英文分号拆成独立列表项；分类：内容 （也支持英文冒号）和 【分类】内容 转为分类标题，后续条目归入该分类。未显式标注 分类时，以“新增”“优化”“修复”“调整”“移除”开头的条目按对应类别分组，其他条目 保留为普通列表。已有 Markdown 排版保留，不拆分代码、链接或列表中的分号。 例如 新增：批量操作；下载加速；修复：登录异常；通知丢失 会排成“新增”和“修复” 两个分类，每类各两个条目。

通知类型、版本号、发布时间和详情链接仍以文字发送，方便打开原文。渲染失败时回退 为原有文字通知。

生成事件的事务边界

公告仅在草稿第一次转换为公开发布状态时生成 announcement.published。编辑已发布 公告不重复通知；确需再次通知时，应创建新的公告发布记录和新的事件 ID。公告状态 更新与事件插入必须处于同一个数据库事务。

正式版本事件只表示已经成功上线的生产版本。生产部署、健康检查和 changelog 公开 全部完成后，才生成 release.published。普通 CI 构建、测试或预览部署、失败部署和 尚未对用户开放的版本均不得生成事件。

如果部署由独立 CI/CD 系统完成，流水线应在生产健康检查通过后调用网站内部受保护 的“确认正式发布”操作。该操作在一个事务中写入正式版本状态、公开 changelog 和 通知事件。这个内部操作与 Bot 读取接口分开，不得向普通用户开放。

增量读取 API

GET /api/integrations/qqbot/events?cursor={cursor|latest}&limit=100
Authorization: Bearer <token>
Accept: application/json

V1 游标来自 sequence，在 JSON 中编码为十进制字符串。Bot 会原样保存服务端返回 的 next_cursor，不会自行加一或根据发布时间推算游标。

• cursor=latest 仅用于首次接入。网站原子读取当前最大 sequence，并返回空事件列表、 当前高水位和 has_more=false；没有事件时游标为 "0"。
• 普通 cursor 返回 sequence > cursor 的事件，按 sequence 严格升序排列。
• limit 默认为 100，允许范围为 1 至 100。
• next_cursor 是本页最后一个事件的 sequence；空页必须等于输入 cursor。
• 超过一页时返回 has_more=true；Bot 随即使用 next_cursor 读取下一页。
• API 查询事件、计算 next_cursor 和 has_more 必须使用同一个数据库快照。

成功响应固定为：

{
  "schema_version": 1,
  "events": [
    {
      "id": "announcement:123",
      "type": "announcement.published",
      "title": "服务升级公告",
      "summary": "本次升级将改善下载速度与稳定性。",
      "markdown": "## 更新内容\n\n- **优化**下载速度\n- 改善稳定性\n",
      "url": "https://example.com/announcements/123",
      "published_at": "2026-08-04T08:30:00Z",
      "version": null
    },
    {
      "id": "release:2026.08.04",
      "type": "release.published",
      "title": "2026.08.04 正式版",
      "summary": "新增批量操作并修复登录异常。",
      "url": "https://example.com/changelog/2026.08.04",
      "published_at": "2026-08-04T09:00:00Z",
      "version": "2026.08.04"
    }
  ],
  "next_cursor": "842",
  "has_more": false
}

错误响应使用不含堆栈、SQL、内部路径或敏感配置的 JSON：

事件和游标不设置过期时间，因此无需 410 cursor_expired。所有成功响应设置 Cache-Control: private, no-store。

鉴权与安全

• 为此接口单独生成至少 32 字节随机 Token，分别存放在网站密钥系统和 Bot 的 .env.prod，不得写入源码、CI 输出或访问日志。
• 网站使用恒定时间比较校验 Token；如需持久化，优先只保存 Token 哈希。
• 生产接口强制 HTTPS，反向代理不得记录 Authorization 请求头。
• API 只返回已经公开的内容，不返回草稿、构建日志、提交者邮箱、内部下载地址或 其他非公开字段。
• 轮换密钥时可短暂同时接受新旧 Token；确认 Bot 已使用新 Token 后立即撤销旧值。

服务状态 API

通知群的主动状态查询和自动不可用告警调用网站公开状态接口：

GET /api/status
Accept: application/json

该请求不携带事件流 Bearer Token。接口必须设置 Cache-Control: no-store，不得接受 查询参数；可用或负载升高时返回 200，不可用时返回 503。Bot 使用以下字段，其余 字段可向后兼容扩展：

{
  "generated_at": "2026-08-15T10:00:00Z",
  "status": "available",
  "queue": {
    "queued": 0,
    "running": 1,
    "queue_limit": 200,
    "worker_concurrency": 3,
    "worker_instances": 1
  },
  "incidents": []
}

status 允许 available、scaling、busy、congested、overloaded 和 unavailable。unavailable 必须配合 HTTP 503；其他状态必须配合 HTTP 200。 不可用时 queue 可为 null。generated_at 必须是带时区的 RFC 3339 时间。

Bot 按 WEBSITE_POLL_INTERVAL_SECONDS 定时监测，只有连续三次返回 unavailable 或无法获取有效状态才向通知群告警，两类异常合并计数。任何一次返回其他有效状态 都会清零连续异常次数；短暂异常不发送告警或恢复通知。持续异常时每群只告警一次， 恢复后仅向已收到告警的群发送一次恢复通知，之后再次异常重新累计。

网站端测试与联合验收

网站单元测试或集成测试至少应覆盖这些情况：

• 草稿、编辑、测试构建和失败部署不生成事件。
• 并发重复发布只生成一个 event_id。
• 发布事务失败时，公开状态和通知事件一起回滚。
• cursor=latest 不返回历史事件。
• 普通游标分页无遗漏、无乱序、无重复，并在并发插入时保持快照一致性。
• Bearer 鉴权、限流和错误码符合本文约定。

联合验收时，先部署网站事件 API，再启用 Bot。发布一条真实公告，确认所有配置群 在一个轮询周期内各收到一次通知。随后暂停 Bot、发布一个正式版本并恢复 Bot， 确认离线事件会补发，已经成功投递的群不会因其他群失败而重复收到消息。

QQ 群内测注册邀请码

Bot 可使用同一个 WEBSITE_EVENTS_TOKEN 请求网站为内测群成员签发个人注册邀请码：

POST /api/integrations/qqbot/registration-invitations
Authorization: Bearer <token>
Content-Type: application/json

请求体严格为：

{"qq_number":"123456789"}

成功响应的 status 为 created、active、renewed 或 bound。前三者返回 invitation_code、expires_at 和带 #invite= 片段的 registration_url；bound 只返回状态，不暴露账号或邀请码。created 使用 HTTP 201，其余成功状态使用 HTTP 200。 邀请码有效期为 24 小时；Bot 每次都应将当前响应中的最新注册链接发送给用户。

该接口只接受 QQ 号，不接受邮箱、密码、道具代码或数量。网站负责注册时的 QQ 绑定、 邀请码消费和新人内测道具发放，Bot 不保存邀请码，也不参与奖励参数和发放状态管理。

个人排班通知与 MAA JSON

个人排班使用独立的 WEBSITE_QQBOT_TOKEN，不使用公告游标或公告凭据。 Bot 通过网站通知统一开启或关闭个人排班功能，共用 WEBSITE_NOTIFICATIONS_ENABLED 和 WEBSITE_NOTIFICATION_GROUP_IDS，接口根地址从 WEBSITE_EVENTS_URL 推导。 只有这些通知群的当前成员可在好友私聊中操作或接收个人排班，成员身份在操作及实际 发送前重新查询；查询失败时先重试，确认已退群则停止旧任务。 网站先执行迁移 2026-10-04.1，Bot 部署后再开放网站账号安全页的绑定入口。 Token 至少 32 个 UTF-8 字节，与公告和发布确认 Token 的值不同；所有请求使用 Bearer 鉴权，关闭重定向。QQ 身份只取好友私聊事件发送者，不能从参数指定他人。

网站通知统一管理公告和个人排班的 HTTP 客户端及生命周期。个人排班默认每 15 秒轮询， 所有个人接口共用本地 100 次/分钟的请求预算，为网站 120 次/分钟的限额预留余量。遇到 429 按 Retry-After 暂停请求；HTTP、QQ 和 文件上传故障指数退避。一条失败不停止其他任务。分页游标只用于本轮扫描，扫描完成 后回到第一页；进程重启也从第一页开始，不遗漏未 ACK 通知。

新通知先以通知 ID 去重存入管理 SQLite。文字发送、文件发送、提醒降级原因和 ACK 分别保存状态。发送前核对当前绑定 ID、通知开关及档案是否可用；旧绑定或关闭通知时 取消本地任务。应发送的文字和文件全部发出后才提交 ACK；ACK 失败时只重试 ACK。记录保留 7 天。 该协议至少投递一次，QQ 接受发送后、本地状态落库前崩溃仍可能重发。

自动导出请求如下，其中幂等键始终为同一通知 ID：

{
  "qq_number": "123456789",
  "binding_id": "当前绑定ID",
  "profile_id": "档案ID",
  "result_id": "结果ID",
  "idempotency_key": "notify:通知ID",
  "automatic": true
}

成功响应包含 {result, result_id, filename, consumed_coupon}。Bot 只把 result 对象序列化成 UTF-8 JSON，使用响应的 filename 私聊上传文件，不发送响应外壳、 公开链接或完整网站计算数据。自动导出不携带 use_coupon。

需要券返回 403 maa_export_coupon_required；Bot 只推送完成提醒及主动下载命令。 轮班制、JSON 校验失败、结果删除也只提醒并 ACK。手动下载取得用户确认消耗 1 张 体验券后，才提交 use_coupon: true；同一确认有效期内的重试保留原幂等键。 绑定码、凭据和 JSON 文件内容不进入插件日志。error 字符串与 code 均可能出现， Bot 对没有 code 的轮班制错误也能提示用户到网站查看。

本地验收使用模拟网站 HTTP、真实临时 SQLite 和模拟 Milky Bot，覆盖私聊身份、 紧凑输入、帮助可见性、通知开关、分页、分步重试、重新绑定、用券确认和限流。 上线后需再用真实账号完成“绑定、开启、生成排班、收到提醒与 JSON”的联合验收。

QQ Bot Manager

QQ Bot Manager 用于管理明日方舟等游戏社群的多个 QQ 群，支持成员管理、游戏数据查询和群内互动。

Bot 基于 NoneBot2 与 Milky，群配置、消息归档、审计记录和定时任务保存在本地 SQLite 中。

功能概览

快速开始

环境要求

• Python >=3.10, <4.0
• uv：用于安装依赖和运行项目
• 可用的 QQ/Milky 服务端
• Bot 在目标群中具有所需的平台权限

安装与配置

安装锁定版本的依赖，并创建生产环境配置：

uv sync --frozen
cp .env.example .env.prod

启动前编辑 .env.prod，填写核心配置，并将示例 QQ 号替换为实际值：

ENVIRONMENT=prod
MANAGEMENT_GROUP_ID=100000001
OWNER_USER_ID=300000001
SUPER_ADMIN_USER_IDS=[300000002]

• MANAGEMENT_GROUP_ID：专用管理群群号。
• OWNER_USER_ID：唯一 Bot 所有者账号，即 Bot 运行者或最高权限维护者。
• SUPER_ADMIN_USER_IDS：初始超管 QQ 号，使用 JSON 数组；不设置初始超管时填写 []。
• 还需按当前 nonebot-adapter-milky 版本补充 QQ/Milky 连接配置。
• 启用网站、模型分析或 Web 后台时，再填写 .env.example 中对应的可选变量。

配置完成后启动 Bot：

ENVIRONMENT=prod uv run python bot.py

使用指南

命令入口

在受管群中可以管理当前群；跨群操作可在专用管理群或好友私聊中执行。

受管群和专用管理群中的命令需要提及或回复 Bot；好友私聊不需要提及。

命令语法约定：

• 参数命令支持省略命令词后的第一个空格，例如 禁言123456789 10 与 禁言 123456789 10 等价。
• 无参数命令必须完整匹配，状态123 等普通文本不会触发命令。
• 单目标成员写作 <QQ号|@成员>。
• 批量命令写作 <QQ号|@成员> [更多目标]，可使用逗号分隔的多个 QQ 号或连续多个成员提及；两种形式不能混用，目标不能重复。

权限体系

权限由低到高为：

管理 < 群主 < 超管 < Bot 所有者

Bot 所有者是部署时指定的唯一最高权限账号；超管可以有多个，但不能修改所有者专属配置。成员操作只能作用于权限更低的账号，Bot、操作者本人、同级和更高权限成员受到保护。

常用命令

发送 帮助 可查看当前账号在本会话中能用的命令。帮助中只显示已启用的插件：

@Bot 帮助
@Bot 帮助 <分类>
@Bot 帮助 <命令>

日常管理：

回复目标消息：@Bot 撤回
回复本群成员消息：@Bot 禁言 10
回复本群成员消息：@Bot 警告 刷屏
回复本群成员消息：@Bot 发言 20
@Bot 禁言 <QQ号|@成员> [更多目标] [分钟]
@Bot 警告 <QQ号|@成员> [更多目标] [原因]
@Bot 成员 [未发言天数]
@Bot 清理 [未发言天数] [最高等级]

群设置与内容：

@Bot 违禁词 [+|- <词>]
@Bot 问答
@Bot 欢迎 [文本|开|关|继承]
@Bot 入群验证 群聊 [1-60分钟]

游戏与查询：

@Bot 今日方舟
@Bot 关卡难度 <关卡> [综合|普通|突袭]
@Bot MAA下载 [稳定|公测|内测] [平台]
@Bot MAA下载 资源
@Bot 提醒 列表 [分类] [页码]
@Bot 猜干员 [立绘|困难立绘|极难立绘|噩梦立绘|技能]

系统与跨群管理：

@Bot 状态
@Bot <群号或别名> 状态
@Bot 全局统计 [分组]
@Bot 配置 群聊 <群号或别名> <开|关>
@Bot 管理后台

其余命令和完整参数请使用 @Bot 帮助 查询。

结果提示省略“失败 0”“跳过 0”和重复计数，异常及需要处理的事项仍会显示。自动清理在同轮多群处理结束后合并通知，相同条件只显示一次；正常结果发到管理群，异常结果私聊 Bot 所有者。

配置说明

环境变量

.env.example 提供可直接复制的部署模板、常用变量和示例值；各插件的高级配置见对应插件文档。

默认情况下，核心数据写入 data/qqbot_manager.sqlite3，导出、报告、问答图片和插件缓存分别写入 data/ 下的独立目录。

运行时命令

Bot 所有者可在专用管理群或好友私聊中维护业务配置：

@Bot 配置 群聊 [群号或别名]
@Bot 配置 群聊 <群号或别名> <开|关>
@Bot 配置 插件 [群号或别名]
@Bot 配置 插件 <群号或别名> <插件> <开|关>
@Bot 配置 插件 <群号或别名> Codex通知 <开|关>
@Bot 配置 查看 [manager|call_admin|prts|maa|arknights|operator_guess]
@Bot 配置 设置 <模块.键> <值>
@Bot 配置 设置 maa.maa_auto_upload_group_ids <群号列表|->
@Bot 配置 重置 <模块.键>

修改群聊或插件开关、设置或重置配置时，Bot 会要求二次确认并记录审计。运行时配置保存在管理 SQLite 中，覆盖对应的环境变量默认值。标记为需要重启的配置会在重启后生效。

Bot 所有者可通过上述命令或 Web 后台“运行时配置”，修改 MAA 接收群、检查间隔和管理群通知开关，修改后立即生效。将 maa.maa_auto_upload_notify_management 设为 开，即可接收简短的定时上传结果通知。

发送 MAA上传测试 [正式|公测|资源|全部] [覆盖] 可测试下载和群文件上传。末尾加 覆盖 会先删除目标文件夹中的同名文件再上传；发送 MAA上传状态 查看步骤、进度、耗时和最近结果。详细用法见 MAA 下载插件。

Bot 所有者可在 Web 后台“运行时配置 → 管理召唤匹配规则”查看和编辑全部召唤关键词及冲突提示正则，保存后立即生效，重启后保留。

Bot 所有者可在 Web 后台“运行时配置 → AI 分析连接”设置协议、接口地址、模型和 API 密钥，保存后立即生效，重启后保留。支持 OpenAI Chat Completions、OpenAI Responses 和 Anthropic Messages，连接规则见管理套件手册。其他 Token、远程地址、数据目录、Bot 所有者账号和专用管理群等部署级配置通过环境变量修改。

新群聊默认关闭。开启群聊后，管理套件和管理召唤默认启用，PRTS 查询、方舟刷图、MAA 下载、截止提醒、猜干员、MaiBot 群聊和 Codex 通知默认关闭。

Codex 通知插件同时支持 Codex 和 Pi，通过 Web 管理后台的域名和 HTTP 服务接收事件，接口为 /integrations/codex/notify，无需另开端口。先配置 WEB_ADMIN_PUBLIC_URL 和 CODEX_NOTIFY_ENABLED。可选投递群只包含已开启 Codex 通知的群；普通群读取配置数据库，并要求群聊和插件均已开启。CODEX_NOTIFY_GROUP_IDS 可选用于补充目标群。所有者在后台的“Codex 通知”页面为自己或其他 QQ 号指定投递群，个人 Token 只向指定群发送，重置 Token 保留设置。用户私聊发送 管理后台 后即可领取个人 Access Token、下载脚本并查看 Codex 轮次通知钩子、仅完成通知的 notify 或 Pi 扩展的接入教程。原有共享 CODEX_NOTIFY_TOKEN 可继续使用。

普通群还需开启群聊及插件；专用管理群可在部署目标列表中启用。接入方式、重试和去重规则见 Codex 通知手册。

Web 管理后台

管理控制台使用 TypeScript、React、Tailwind CSS 和 Vite，各页面共用一套组件，支持桌面侧边导航、移动端菜单和浅色 / 深色主题。

启用后台前，安装 Node.js 22.18+（推荐 24 LTS），在 frontend/ 执行 npm ci && npm run build。Python 服务直接提供构建产物，无需额外前端进程。开发与验证见 前端说明。

公开使用文档位于同站点 /docs，无需登录；/docs/raw 提供 Markdown 原文。文档包含全部内置命令、权限、示例和插件手册。后台仍使用根路径，通过一次性链接登录。

配置 Web 后台地址和本机监听地址后，管理及以上权限或已获 Codex 通知授权的用户，可在群内发送 @Bot 管理后台，或在好友私聊中发送 管理后台。命令必须完整匹配，Bot 会返回绑定本人账号的短时一次性链接。仅有通知授权的普通成员只能使用自己的通知页面。

普通管理和群主只能查看有权管理的群，超管可以执行全局命令。后台将 QQ 群角色缓存 5 分钟，刷新时可复用平台缓存，QQ 端权限变更可能延迟生效；查询失败后 15 秒重试，到期无法确认权限时拒绝访问。群聊总开关、插件开关和运行时配置仅 Bot 所有者可改；所有者还可在“请求管理”设置好友请求与 Bot 入群邀请的处理方式、私聊通知，并同意或拒绝待审请求。

Bot 所有者可在“群聊管理”关闭指定群的“超管后台权限”，对超管隐藏该群并禁止后台操作；涉及受限群的共享分组策略和共享提醒需由所有者管理。此限制仅作用于 Web 后台，聊天命令权限沿用原规则，详见后台权限说明。

生产环境必须使用 HTTPS 反向代理，且不要把本机监听端口直接暴露到公网。完整部署方式见 DEPLOYMENT.md。

部署与安全

权限前置条件

• 撤回、禁言、踢人和入群验证要求 Bot 是目标群管理员或群主。
• 设置或撤销群管理员要求 Bot 是目标群群主。
• 私聊验证依赖 QQ/Milky 能接收新人主动发起的好友私聊或群临时会话。

安全建议

• 使用独立服务账号运行 Bot，并限制生产环境文件的读取权限。
• 定期备份 data/ 和环境配置；不要提交数据库、导出文件或真实 QQ 号。
• 分别保管 Milky Token、网站 Token 和模型密钥，不要写入源码、日志、Issue 或聊天记录。
• Web 后台仅通过 HTTPS 反向代理开放，不要直接暴露监听端口。

部署参考

• 公开发布与 systemd 部署：首次安装、发布、回滚和 Web 反向代理。
• 网站事件接口：公告、版本通知和状态事件的接口约定。
• 请求管理：配置好友请求和 Bot 入群邀请的处理策略。
• MaiBot 群聊桥接：复用现有 QQ 会话连接独立 MaiBot，并限制它能发送的消息和执行的操作。

开发与文档

验证命令

uv run python -m unittest -v
uv run python -m compileall -q plugins tests
git diff --check

Markdown 消息

帮助、状态、排行榜和配置清单等多行查询回复使用 Markdown 图片，长内容自动分页；「今日方舟」将全部区块合为一张方舟风格长图，突出临近截止事项，查询入口紧凑排列。渲染失败时回退完整文字。操作确认、错误提示、下载与后台登录链接，以及需要复制的排班 ID 和翻页命令保留文字。插件通过 plugins.bot_core.messages 中的 render_message 构造图文消息，或用 render_text_panel 将已有文字排成图片面板；具体范围、调用示例和字体设置见 Markdown 消息渲染。

插件文档

• Bot 公共核心：共用框架、配置、存储、权限、Web 后台和 Markdown 渲染，独立管理版本。
• 管理套件：群管、配置、审计和 Web 后台。
• 管理召唤：群成员向专用管理群发送求助通知。
• PRTS Plus 难度查询：关卡难度、作业和干员统计。
• 方舟刷图：活动与常驻材料掉落图片；可配置正则模式，直接问“这次活动刷哪关”“固源岩组去哪刷”，无需提及 Bot。
• MAA 下载：MAA 版本查询、镜像下载和安装包、资源包自动上传到多个群文件夹。
• 明日方舟截止提醒：今日方舟聚合查询、截止事项同步、订阅与提醒。
• 猜干员：多模式群聊竞猜玩法。
• 请求管理：好友请求和 Bot 入群邀请策略。
• MaiBot 群聊桥接：支持的 OneBot 接口、可用群范围和部署安全要求。
• Codex / Pi 群通知：完成与异常提醒、客户端配置、指定群投递、事件去重与重试。

附录

版本说明

pyproject.toml 中的 project.version 是插件合集版本，各插件版本维护在 plugins/versions.py。公共能力、framework/ 和 Web 前端统一归属 bot_core，公共代码变化只更新公共核心及合集版本；同时改变业务插件代码或行为时，再更新对应插件版本。@Bot 运行状态 会按系统、消息、连接和版本分组显示运行信息。

从旧版本升级

数据库迁移会将当前环境变量 MANAGED_GROUP_IDS 中的群一次性导入为已开启群聊。迁移完成后，该变量不再参与运行时判断；新部署无需配置。

插件版本

• bot_core：0.7.2
• manager_suite：0.51.0
• request_manager：0.3.0
• call_admin：0.6.0
• operator_guess：0.7.1
• prts_difficulty：0.6.0
• arknights_reminders：0.8.4
• arknights_farming：0.2.1
• maa_download：0.11.2
• maibot_bridge：0.2.5
• codex_notify：0.12.5