# QQ Bot Manager 使用文档 ## 项目简介 QQ Bot Manager 用于管理多个游戏社群 QQ 群，支持成员管理、内容检测、消息归档、统计审计、游戏查询和 Web 管理后台。 ## 快速开始 在群里发送命令时，先提及或回复 Bot，再按自己的身份选择命令： | 你是谁 | 第一步 | 下一步 | | --- | --- | --- | | 普通成员 | 在已启用的群发送 `@Bot 帮助` | 使用 `@Bot 帮助 <命令>` 查看可用命令和用法 | | 群管理或群主 | 在受管群发送 `@Bot 状态` | 检查群设置，再用 `@Bot 帮助` 查找有权使用的命令 | | Bot 所有者 | 在专用管理群发送 `@Bot 配置` | 开启目标群聊和所需插件，再让成员在群里使用 `@Bot 帮助` | 首次启用时，在专用管理群中发送以下命令，并按 Bot 提示分别确认： ```text @Bot 配置 群聊 123456789 开 @Bot 确认 @Bot 配置 插件 123456789 猜干员 开 @Bot 确认 @Bot 帮助 猜干员 ``` 执行前替换并核对示例中的 QQ 号、群号、分组名称和事项 ID。踢人、清理、锁群、拉黑等命令会影响真实成员，请勿随意试用。 群聊和插件都开启后，Bot 才会响应。公开页面列出全部内置命令，聊天中的 `帮助` 只显示当前会话可用的命令。 ## 命令入口 受管群使用 `@Bot <命令>`；专用管理群使用 `@Bot <群号或别名> <命令>`；好友私聊使用 `<群号或别名> <命令>`。全局命令可以直接发送。群聊和管理群通常需要提及或回复 Bot，好友私聊不需要。方舟刷图开启正则模式后，可在已启用插件的群直接问“这次活动刷哪关”“固源岩组去哪刷”；配置方法见[方舟刷图手册](../plugins/arknights_farming/README.md)。 参数命令支持紧凑形式，例如 `禁言123456789 10` 等价于 `禁言 123456789 10`。无参数命令必须精确匹配，`状态123` 不会触发 `状态`。 ## 命令语法约定 - `<必填>` 表示必须填写；`[可选]` 表示可以省略。 - 单个成员使用 ``。 - 批量目标使用 ` [更多目标]`，QQ 号可用逗号分隔，成员可连续提及。 - QQ 号和成员提及不能混用，重复目标会被拒绝。 - 回复消息类命令需要先回复目标消息；Bot、操作者本人及同级或更高权限成员受到保护。 - 只能省略命令词后的第一个分隔，且不能产生歧义。例如 `提醒订阅 寻访` 仍需保留子命令与分类间的空格；`提醒订阅寻访` 无法识别。 - 连续成员提及对应批量目标；`禁言 123456789 @成员 10` 混合格式会被拒绝，`禁言 123456789,123456789 10` 重复目标也会被拒绝。 - 管理召唤等特殊入口要求关键词与后文有明确分隔，详见对应手册；普通长词不会被当作管理命令。 ```text @Bot 禁言123456789 10 @Bot 禁言 @成员A @成员B 10 @Bot 关卡难度TO-S-1 ``` ## 权限体系 权限从低到高为：普通成员、管理、群主、超管、Bot 所有者。Bot 实时读取目标群的管理员和群主身份，从环境变量和数据库记录中读取超管，并由唯一的 `OWNER_USER_ID` 指定所有者。 跨群操作、群聊总开关、插件开关和运行时配置还会限制命令入口或操作者角色。 | 角色 | 可用功能 | 使用限制 | | --- | --- | --- | | 普通成员 | 帮助、游戏、查询、订阅 | 需开启群聊和插件，并满足特殊通道的权限要求 | | 管理 | 成员管理、统计、群问答 | 只能操作有权管理的群和低权限目标 | | 群主 | 群设置、验证、成员角色 | Bot 必须具有对应的 QQ 平台权限 | | 超管 | 分组、跨群、全局管理 | Bot 所有者专属操作不开放 | | Bot 所有者 | 全部管理功能、运行时配置 | 仍需遵守平台限制和确认流程 | 专用管理群中的普通成员从主分组入口操作时按管理级别授权；直接在目标群或好友私聊中执行群命令仍读取目标群实时 QQ 角色。请严格限制专用管理群的成员。 公开文档展示全部内置功能，聊天中的 `帮助` 按当前权限、会话和插件状态显示。部分子命令要求更高权限，包括超管列表的增删、MAA 内测通道和猜干员别名写入。 ### 二次确认 管理套件通常保留待确认操作 120 秒。收到预览后，原操作者需在同一会话发送 `确认`；在群里仍须提及或回复 Bot。Bot 会重新检查权限、目标和有效期。部分插件使用单独的确认子命令，例如 `提醒管理 确认`，请按 Bot 的提示操作。 ## 功能分类 | 功能 | 用途与注意事项 | | --- | --- | | 群成员管理 | 撤回、禁言、踢人、警告、违规、设管撤管；目标权限受保护 | | 内容与群设置 | 违禁词、检测白名单、风控、问答、欢迎、头衔、全员禁言 | | 入群安全 | 黑名单、群聊/私聊验证、超时处置；平台权限为前提 | | 数据运维 | 消息归档、成员统计、清理、分析、导出、审计 | | 分组与配置 | 主分组、别名、跨群命令、Bot 所有者管理群聊和插件开关 | | 游戏查询 | PRTS 关卡难度与干员统计、活动刷图与材料掉落图片、MAA 版本和镜像 | | 猜干员 | 立绘及技能等模式、提示、别名、赛季积分 | | 截止提醒 | 今日方舟聚合查询、分类订阅、提醒档位、来源同步与人工审核维护 | | 管理召唤 | 纯文字转发群内求助到专用管理群；未提及 Bot 时按群退避提示 | | 请求管理 | Bot 所有者处理好友请求和邀请 Bot 入群，不处理普通成员入群申请 | | 网站集成 | 公告版本通知、服务状态、指定内测群成员注册邀请 | | Codex 通知 | 接收本轮完成事件，向指定群投递最终回复；目标配置、群开关和重试见手册 | | Web 后台 | 群设置、问答、插件、配置、权限预览与管理命令 | ## 配置与部署 部署级配置使用 `.env` 设置，包括 Bot 连接、管理群、Bot 所有者、数据库路径、时区、网站集成和 Web 后台地址。运行时配置由 Bot 所有者通过 `配置` 命令维护，除后台可单独设置的 AI 分析连接外，其他敏感连接信息、Token、数据目录和账号仍需通过环境变量修改。 部署需要 Python `>=3.10,<4.0`、NoneBot2、Milky 适配器和 SQLite。维护者使用 `uv sync --frozen` 安装锁定依赖，按部署手册配置 `MANAGEMENT_GROUP_ID`、`OWNER_USER_ID`、`SUPER_ADMIN_USER_IDS` 和 Milky 连接参数。 新群聊默认关闭。开启群聊后管理套件和管理召唤默认启用，PRTS、方舟刷图、MAA、截止提醒、猜干员、MaiBot 群聊和 Codex 通知默认关闭。关闭群聊保留各插件选择，但停用群内插件响应。运行时设置覆盖环境变量的业务默认值；标注需要重启的配置不会立即生效。 Codex 通知通过 Web 管理后台的域名和 HTTP 服务接收事件，无需另开端口。先配置 `WEB_ADMIN_PUBLIC_URL`，再配置 `CODEX_NOTIFY_*` 和 Codex 用户级转发脚本，发送地址为后台域名下的 `/integrations/codex/notify`。 普通群使用 `配置 插件 <群> Codex通知 开` 启用；专用管理群在部署目标列表中启用。详见 [Codex 通知手册](../plugins/codex_notify/README.md)。 Web 后台通过 `管理后台` 获取绑定本人账号的一次性短时链接。生产环境必须使用 HTTPS 反向代理，不要直接把本机监听端口暴露到公网。 ## Web 管理后台 管理后台提供群聊与插件开关、群设置、问答管理、运行时配置、插件状态、管理命令和权限预览。普通管理和群主只能看到有权管理的群；超管可以跨群操作；Bot 所有者负责全局开关和配置。权限预览只能查看，不能修改数据或执行操作。 公开文档位于同一站点 `/docs`，原文位于 `/docs/raw`。无需登录，Bot 离线时也能阅读。页面不会显示会话、当前群列表、私有配置值、归档或审计内容；管理后台仍会实时检查权限。 页脚备案信息默认不展示。Bot 所有者可在后台“运行时配置”中设置 `manager.web_footer_icp`（ICP 备案文字）及 `manager.web_footer_police`（地区名 + 公网安备 + 14 位数字 + 号）。保存后刷新管理后台或公开文档页即可看到更新，无需重启；使用 `-` 清空对应项。 两项内容会公开展示，请只填写有意公开的备案信息。页面会根据编号生成公安备案图标及查询链接。 ## 安全与隐私 Bot 会检查管理操作的权限，必要时要求二次确认，并记录审计。请限制专用管理群成员，不要在聊天中发送 Token 或 API 密钥，并为公开 Web 地址配置 HTTPS。消息归档、成员账号、举报内容和问答数据可能包含敏感信息，应遵循社群隐私规则。 ## 故障排查 群内无响应时检查群聊开关、插件开关以及是否提及或回复 Bot。管理操作失败时检查操作者角色、Bot 是否为群管理员、目标成员权限和二次确认是否过期。提醒无消息时检查分类订阅、事项状态和来源同步状态。 | 现象 | 检查方法 | | --- | --- | | 后台链接失效 | 重新向 Bot 获取一次性链接，不重复使用旧链接 | | 命令在文档中但聊天不可见 | 检查角色、群入口、插件开关和专属条件 | | 确认未执行 | 检查会话、原操作者、有效期，以及是否有新操作覆盖了待确认操作 | | 问答不响应 | 检查触发权限、作用域、匹配模式和规则优先级 | | 游戏未结算名次积分 | 检查有效题数、赛季配置与完整结算规则 | | 提醒更新被来源覆盖 | 检查事项是否恢复自动同步 | | 分析或下载失败 | 检查所配服务、上游网络、镜像与数据缓存 | | 文档访问失败 | 检查 Web 服务启用、反向代理路径及监听地址 | ## 插件版本和兼容性 内置插件版本记录在 `plugins/versions.py`，合集版本记录在 `pyproject.toml`。升级插件后应同步检查命令帮助、配置约束和对应插件 README。 修改文档后，重启 Web 服务即可更新公开页面。命令参考、插件手册、部署手册和网站接口约定会随版本一同发布。 ## 命令完整参考 ### 撤回 尝试撤回回复的消息或已归档消息 ```text 撤回 [ [更多目标]] <每人数量> ``` - 最低权限：管理；分类：群管理。 - 所属插件：`manager_suite`；启用条件及子命令权限见下方说明与手册。 - 入口：在受管群中提及或回复 Bot；从管理群或好友私聊跨群操作时，先指定群号或别名。 - 目标范围：群命令需指定目标群或在目标群内使用。 - 确认：部分修改操作需要确认，以 Bot 提示为准。 - 参数：`<…>` 必填，`[…]` 可选，`|` 表示选项；子命令和参数之间保留必要的分隔。 - 成员：可填写 QQ 号或提及成员。标注 `[更多目标]` 的操作支持批量；QQ 号与提及不能混用，目标不能重复，时长或原因放在所有目标之后。 在受管群回复目标消息，并同时 @Bot 发送“撤回”。按归档撤回时，填写每人撤回数量。撤回状态会随归档写入，重复或延迟事件不会恢复为未撤回。 示例：回复消息后发送 `@Bot 撤回`；按成员撤回使用 `撤回 123456789 3` 或 `撤回 @成员 3`。批量撤回可用 `撤回 123456789,987654321 3`，最后的数字表示每人撤回的数量。平台时限、缓存与 Bot 权限会影响可撤回范围。 ### 禁言 禁言或解禁成员，本群可回复目标消息操作 ```text 禁言 [更多目标] [分钟] ``` - 最低权限：管理；分类：群管理。 - 所属插件：`manager_suite`；启用条件及子命令权限见下方说明与手册。 - 入口：在受管群中提及或回复 Bot；从管理群或好友私聊跨群操作时，先指定群号或别名。 - 目标范围：群命令需指定目标群或在目标群内使用。 - 确认：部分修改操作需要确认，以 Bot 提示为准。 - 参数：`<…>` 必填，`[…]` 可选，`|` 表示选项；子命令和参数之间保留必要的分隔。 - 成员：可填写 QQ 号或提及成员。标注 `[更多目标]` 的操作支持批量；QQ 号与提及不能混用，目标不能重复，时长或原因放在所有目标之后。 省略分钟数时默认 10 分钟；填 0 解禁，最多 43200 分钟。批量 QQ 号用英文逗号分隔，也可连续 @ 多位成员。批量失败会列出平台拒绝的 QQ 号。 在本群回复成员消息并 @Bot，发送 禁言 [分钟]，例如 禁言10；单个数字表示分钟。显式 @成员 或填写 QQ号 分钟 时优先使用指定目标。跨群操作须明确填写目标，不从回复推断。 示例：`禁言 123456789 10`、`禁言 @成员 10`、`禁言 123456789,987654321 10`。分钟数为最后一个参数；`禁言123456789 10` 是等价紧凑形式。`禁言 @成员 0` 用于解禁。Bot 必须能管理目标成员。 ### 踢 踢出成员 ```text 踢 [更多目标] ``` - 最低权限：管理；分类：群管理。 - 所属插件：`manager_suite`；启用条件及子命令权限见下方说明与手册。 - 入口：在受管群中提及或回复 Bot；从管理群或好友私聊跨群操作时，先指定群号或别名。 - 目标范围：群命令需指定目标群或在目标群内使用。 - 确认：部分修改操作需要确认，以 Bot 提示为准。 - 参数：`<…>` 必填，`[…]` 可选，`|` 表示选项；子命令和参数之间保留必要的分隔。 - 成员：可填写 QQ 号或提及成员。标注 `[更多目标]` 的操作支持批量；QQ 号与提及不能混用，目标不能重复，时长或原因放在所有目标之后。 示例：`踢 123456789`、`踢 @成员`、`踢 123456789,987654321`。命令会立即踢出目标成员。先核实目标，只在测试群中试用。 ### 拉黑 全局拉黑成员 ```text 拉黑 [原因] ``` - 最低权限：超管；分类：黑名单管理。 - 所属插件：`manager_suite`；启用条件及子命令权限见下方说明与手册。 - 入口：在受管群中提及或回复 Bot；从管理群或好友私聊跨群操作时，先指定群号或别名。 - 目标范围：群命令需指定目标群或在目标群内使用。 可从管理入口直接执行，无需先指定目标群。 - 确认：修改前需在原会话按预览确认，Bot 会重新检查权限；只读查询无需确认。 - 参数：`<…>` 必填，`[…]` 可选，`|` 表示选项；子命令和参数之间保留必要的分隔。 - 成员：可填写 QQ 号或提及成员。标注 `[更多目标]` 的操作支持批量；QQ 号与提及不能混用，目标不能重复，时长或原因放在所有目标之后。 示例：在管理群发送 `@Bot 拉黑 123456789 广告`，或 `@Bot 拉黑 @成员 广告`。每次只能指定一个目标，无需先指定群。Bot 会修改管理分组黑名单并执行相应处置，确认前请核对返回的操作范围。 ### 设管 设置群管理员 ```text 设管 ``` - 最低权限：群主；分类：群管理。 - 所属插件：`manager_suite`；启用条件及子命令权限见下方说明与手册。 - 入口：在受管群中提及或回复 Bot；从管理群或好友私聊跨群操作时，先指定群号或别名。 - 目标范围：群命令需指定目标群或在目标群内使用。 - 确认：修改前需在原会话按预览确认，Bot 会重新检查权限；只读查询无需确认。 - 参数：`<…>` 必填，`[…]` 可选，`|` 表示选项；子命令和参数之间保留必要的分隔。 - 成员：可填写 QQ 号或提及成员。标注 `[更多目标]` 的操作支持批量；QQ 号与提及不能混用，目标不能重复，时长或原因放在所有目标之后。 示例：`设管 123456789` 或 `设管 @成员`。一次只处理一人，需要确认；操作者和 Bot 都需具备相应的管理员任命权限。 ### 撤管 撤销群管理员 ```text 撤管 ``` - 最低权限：群主；分类：群管理。 - 所属插件：`manager_suite`；启用条件及子命令权限见下方说明与手册。 - 入口：在受管群中提及或回复 Bot；从管理群或好友私聊跨群操作时，先指定群号或别名。 - 目标范围：群命令需指定目标群或在目标群内使用。 - 确认：修改前需在原会话按预览确认，Bot 会重新检查权限；只读查询无需确认。 - 参数：`<…>` 必填，`[…]` 可选，`|` 表示选项；子命令和参数之间保留必要的分隔。 - 成员：可填写 QQ 号或提及成员。标注 `[更多目标]` 的操作支持批量；QQ 号与提及不能混用，目标不能重复，时长或原因放在所有目标之后。 示例：`撤管 123456789` 或 `撤管 @成员`。一次只处理一人，需要确认。不能撤销与自己同级或权限更高成员的管理员身份。 ### 申请头衔 向群主申请头衔，回复中会显示申请内容 ```text 申请头衔 <头衔> ``` - 最低权限：普通成员；分类：群设置。 - 所属插件：`manager_suite`；启用条件及子命令权限见下方说明与手册。 - 入口：在受管群中提及或回复 Bot；从管理群或好友私聊跨群操作时，先指定群号或别名。 - 目标范围：群命令需指定目标群或在目标群内使用。 - 确认：部分修改操作需要确认，以 Bot 提示为准。 - 参数：`<…>` 必填，`[…]` 可选，`|` 表示选项；子命令和参数之间保留必要的分隔。 示例：`申请头衔 热心群友`。群内启用申请并满足条件后提交，头衔按 QQ 的 UTF-16 长度限制校验；是否成功还取决于平台能力。填写头衔后的反馈包含 `申请头衔：热心群友`，方便核对申请内容并纠错。 ### 警告 警告一个或多个成员并记录违规，本群可回复目标消息操作 ```text 警告 [更多目标] [原因] ``` - 最低权限：管理；分类：群管理。 - 所属插件：`manager_suite`；启用条件及子命令权限见下方说明与手册。 - 入口：在受管群中提及或回复 Bot；从管理群或好友私聊跨群操作时，先指定群号或别名。 - 目标范围：群命令需指定目标群或在目标群内使用。 - 确认：部分修改操作需要确认，以 Bot 提示为准。 - 参数：`<…>` 必填，`[…]` 可选，`|` 表示选项；子命令和参数之间保留必要的分隔。 - 成员：可填写 QQ 号或提及成员。标注 `[更多目标]` 的操作支持批量；QQ 号与提及不能混用，目标不能重复，时长或原因放在所有目标之后。 在本群回复成员消息并 @Bot，发送 警告 [原因]，例如 警告刷屏。显式 QQ 号或 @成员 优先；原因以数字开头时，请用 @成员 明确目标。跨群操作须明确填写目标，不从回复推断。 示例：`警告 @成员 发布广告` 或 `警告 123456789,987654321 发布广告`。原因在所有目标后面；会记录违规并可能触发当前处置策略，不应作为测试消息随意发送。 ### 违规 查询尚未撤销的违规记录 ```text 违规 ``` - 最低权限：管理；分类：群管理。 - 所属插件：`manager_suite`；启用条件及子命令权限见下方说明与手册。 - 入口：在受管群中提及或回复 Bot；从管理群或好友私聊跨群操作时，先指定群号或别名。 - 目标范围：群命令需指定目标群或在目标群内使用。 - 确认：部分修改操作需要确认，以 Bot 提示为准。 - 参数：`<…>` 必填，`[…]` 可选，`|` 表示选项；子命令和参数之间保留必要的分隔。 - 成员：可填写 QQ 号或提及成员。标注 `[更多目标]` 的操作支持批量；QQ 号与提及不能混用，目标不能重复，时长或原因放在所有目标之后。 示例：`违规 123456789` 或 `违规 @成员`。每次查询一个目标的有效违规记录。能够查看记录的账号未必有权撤销全部历史记录。 ### 撤警 撤销有权撤销的警告 ```text 撤警 [次数|全部] ``` - 最低权限：管理；分类：群管理。 - 所属插件：`manager_suite`；启用条件及子命令权限见下方说明与手册。 - 入口：在受管群中提及或回复 Bot；从管理群或好友私聊跨群操作时，先指定群号或别名。 - 目标范围：群命令需指定目标群或在目标群内使用。 - 确认：部分修改操作需要确认，以 Bot 提示为准。 - 参数：`<…>` 必填，`[…]` 可选，`|` 表示选项；子命令和参数之间保留必要的分隔。 - 成员：可填写 QQ 号或提及成员。标注 `[更多目标]` 的操作支持批量；QQ 号与提及不能混用，目标不能重复，时长或原因放在所有目标之后。 示例：`撤警 @成员 1` 或 `撤警 123456789 全部`。指定次数或填写 `全部`，Bot 只撤销操作者有权撤销的记录。 ### 违禁词 管理本群违禁词 ```text 违禁词 [+|- <词>] ``` - 最低权限：群主；分类：内容管理。 - 所属插件：`manager_suite`；启用条件及子命令权限见下方说明与手册。 - 入口：在受管群中提及或回复 Bot；从管理群或好友私聊跨群操作时，先指定群号或别名。 - 目标范围：群命令需指定目标群或在目标群内使用。 - 确认：部分修改操作需要确认，以 Bot 提示为准。 - 参数：`<…>` 必填，`[…]` 可选，`|` 表示选项；子命令和参数之间保留必要的分隔。 示例：`违禁词` 查看；`违禁词 + 测试词` 添加；`违禁词 - 测试词` 删除。注意本群规则与分组同步关系；规则会影响真实聊天内容。 ### 白名单 管理检测白名单 ```text 白名单 [+|- ] ``` - 最低权限：群主；分类：内容管理。 - 所属插件：`manager_suite`；启用条件及子命令权限见下方说明与手册。 - 入口：在受管群中提及或回复 Bot；从管理群或好友私聊跨群操作时，先指定群号或别名。 - 目标范围：群命令需指定目标群或在目标群内使用。 - 确认：部分修改操作需要确认，以 Bot 提示为准。 - 参数：`<…>` 必填，`[…]` 可选，`|` 表示选项；子命令和参数之间保留必要的分隔。 - 成员：可填写 QQ 号或提及成员。标注 `[更多目标]` 的操作支持批量；QQ 号与提及不能混用，目标不能重复，时长或原因放在所有目标之后。 示例：`白名单 + 123456789`、`白名单 + @成员`、`白名单 - @成员`。每次只能指定一人。白名单仅豁免内容检测，不赋予管理权限。 ### 锁群 定时全员禁言 ```text 锁群 <分钟> ``` - 最低权限：群主；分类：群设置。 - 所属插件：`manager_suite`；启用条件及子命令权限见下方说明与手册。 - 入口：在受管群中提及或回复 Bot；从管理群或好友私聊跨群操作时，先指定群号或别名。 - 目标范围：群命令需指定目标群或在目标群内使用。 - 确认：部分修改操作需要确认，以 Bot 提示为准。 - 参数：`<…>` 必填，`[…]` 可选，`|` 表示选项；子命令和参数之间保留必要的分隔。 锁群时长为 1 至 1440 分钟；提前解除可发送“解锁群”。 示例：`锁群 10`。参数为分钟数，允许 1 至 1440 分钟。命令会开启全员禁言，并保存截止时间；需要提前解锁时使用 `解锁群`。 ### 解锁群 解除本群全员禁言 ```text 解锁群 ``` - 最低权限：群主；分类：群设置。 - 所属插件：`manager_suite`；启用条件及子命令权限见下方说明与手册。 - 入口：在受管群中提及或回复 Bot；从管理群或好友私聊跨群操作时，先指定群号或别名。 - 目标范围：群命令需指定目标群或在目标群内使用。 - 确认：部分修改操作需要确认，以 Bot 提示为准。 - 参数：`<…>` 必填，`[…]` 可选，`|` 表示选项；子命令和参数之间保留必要的分隔。 示例：`解锁群`。无参数，必须精确匹配；需要 Bot 有权限解除群全员禁言。 ### 清理 清理前先预览并确认，不设最低保留人数；成员重新入群时提示上次清理原因 ```text 清理 [未发言天数] [最高等级] ``` - 最低权限：群主；分类：群管理。 - 所属插件：`manager_suite`；启用条件及子命令权限见下方说明与手册。 - 入口：在受管群中提及或回复 Bot；从管理群或好友私聊跨群操作时，先指定群号或别名。 - 目标范围：群命令需指定目标群或在目标群内使用。 - 确认：修改前需在原会话按预览确认，Bot 会重新检查权限；只读查询无需确认。 - 参数：`<…>` 必填，`[…]` 可选，`|` 表示选项；子命令和参数之间保留必要的分隔。 示例：`清理 30 5`。参数依次为未发言天数和最高等级。手动清理不限制最低保留人数，先看清理预览再确认；确认时会重新筛选，只处理预览名单中仍符合条件的成员。 ### 自动清理 设置自动清理并保留最低人数；同轮多群结果合并通知，相同条件合并显示；成员重新入群时提示上次清理原因 ```text 自动清理 [开 天数 等级|关] ``` - 最低权限：超管；分类：群管理。 - 所属插件：`manager_suite`；启用条件及子命令权限见下方说明与手册。 - 入口：在受管群中提及或回复 Bot；从管理群或好友私聊跨群操作时，先指定群号或别名。 - 目标范围：群命令需指定目标群或在目标群内使用。 - 确认：修改前需在原会话按预览确认，Bot 会重新检查权限；只读查询无需确认。 - 参数：`<…>` 必填，`[…]` 可选，`|` 表示选项；子命令和参数之间保留必要的分隔。 示例：`自动清理 开 60 10` 或 `自动清理 关`。天数、等级放在 `开` 后面，修改需要确认。启用后会持续按策略清理，并保留最低人数，由 `manager.cleanup_min_remaining_members` 配置，默认保留 100 人。因人数限制跳过成员时，结果中会显示跳过人数。 ### 入群验证 设置新成员入群验证；被清理成员重新入群时附上上次清理原因 ```text 入群验证 [群聊 [分钟]|私聊 [分钟]|关|重入 允许|拒绝] ``` - 最低权限：群主；分类：群设置。 - 所属插件：`manager_suite`；启用条件及子命令权限见下方说明与手册。 - 入口：在受管群中提及或回复 Bot；从管理群或好友私聊跨群操作时，先指定群号或别名。 - 目标范围：群命令需指定目标群或在目标群内使用。 - 确认：修改前需在原会话按预览确认，Bot 会重新检查权限；只读查询无需确认。 - 参数：`<…>` 必填，`[…]` 可选，`|` 表示选项；子命令和参数之间保留必要的分隔。 示例：`入群验证 群聊 10`、`入群验证 私聊 10`、`入群验证 关`。分钟数范围为 1 至 60；私聊模式要求新人能主动联系 Bot。黑名单检查优先，验证超时会踢人；题库为空时使用随机算术题。 ### 头衔申请 管理成员头衔申请 ```text 头衔申请 [开 [等级 N] [入群 N] [连续 N]|关] ``` - 最低权限：群主；分类：群设置。 - 所属插件：`manager_suite`；启用条件及子命令权限见下方说明与手册。 - 入口：在受管群中提及或回复 Bot；从管理群或好友私聊跨群操作时，先指定群号或别名。 - 目标范围：群命令需指定目标群或在目标群内使用。 - 确认：部分修改操作需要确认，以 Bot 提示为准。 - 参数：`<…>` 必填，`[…]` 可选，`|` 表示选项；子命令和参数之间保留必要的分隔。 示例：`头衔申请 开` 或 `头衔申请 开 等级 10 入群 7 连续 3`。命令用于设置申请资格，包括成员等级、入群天数和连续活跃天数。成员提交申请时使用 `申请头衔`。 ### 欢迎 设置本群欢迎语；被清理成员重新入群时附上上次清理原因 ```text 欢迎 [文本|开|关|继承] ``` - 最低权限：群主；分类：群设置。 - 所属插件：`manager_suite`；启用条件及子命令权限见下方说明与手册。 - 入口：在受管群中提及或回复 Bot；从管理群或好友私聊跨群操作时，先指定群号或别名。 - 目标范围：群命令需指定目标群或在目标群内使用。 - 确认：部分修改操作需要确认，以 Bot 提示为准。 - 参数：`<…>` 必填，`[…]` 可选，`|` 表示选项；子命令和参数之间保留必要的分隔。 示例：`欢迎 欢迎加入群聊`、`欢迎 关`、`欢迎 继承`。文本、开关或继承三种模式择一；开启验证时欢迎语在验证通过后发送。 ### 风控强度 设置自动撤回后是否禁言或踢人 ```text 风控强度 [宽松|标准|严格|辅助设置] ``` - 最低权限：群主；分类：群设置。 - 所属插件：`manager_suite`；启用条件及子命令权限见下方说明与手册。 - 入口：在受管群中提及或回复 Bot；从管理群或好友私聊跨群操作时，先指定群号或别名。 - 目标范围：群命令需指定目标群或在目标群内使用。 - 确认：部分修改操作需要确认，以 Bot 提示为准。 - 参数：`<…>` 必填，`[…]` 可选，`|` 表示选项；子命令和参数之间保留必要的分隔。 示例：`风控强度 标准`。宽松偏向撤回，标准可追加禁言，严格可追加踢人；具体阈值与辅助设置见管理套件手册和 Bot 当前的回复。严格模式会真实影响成员去留。 ### 运行状态 查看机器人运行信息 ```text 运行状态 ``` - 最低权限：管理；分类：系统。 - 所属插件：`manager_suite`；启用条件及子命令权限见下方说明与手册。 - 入口：在受管群中提及或回复 Bot；从管理群或好友私聊跨群操作时，先指定群号或别名。 - 目标范围：群命令需指定目标群或在目标群内使用。 - 确认：部分修改操作需要确认，以 Bot 提示为准。 - 参数：`<…>` 必填，`[…]` 可选，`|` 表示选项；子命令和参数之间保留必要的分隔。 示例：`运行状态`。查看机器人的运行信息，与目标群的配置状态不同。群入口和全局入口都会检查相应权限。 ### 状态 查看群状态 ```text 状态 ``` - 最低权限：管理；分类：查询分析。 - 所属插件：`manager_suite`；启用条件及子命令权限见下方说明与手册。 - 入口：在受管群中提及或回复 Bot；从管理群或好友私聊跨群操作时，先指定群号或别名。 - 目标范围：群命令需指定目标群或在目标群内使用。 - 确认：部分修改操作需要确认，以 Bot 提示为准。 - 参数：`<…>` 必填，`[…]` 可选，`|` 表示选项；子命令和参数之间保留必要的分隔。 示例：`状态`。查看目标群配置状态，跨群时使用 `@Bot <群号或别名> 状态`；`状态123` 不是命令。 ### 成员 查看成员活跃度 ```text 成员 [未发言天数] ``` - 最低权限：管理；分类：查询分析。 - 所属插件：`manager_suite`；启用条件及子命令权限见下方说明与手册。 - 入口：在受管群中提及或回复 Bot；从管理群或好友私聊跨群操作时，先指定群号或别名。 - 目标范围：群命令需指定目标群或在目标群内使用。 - 确认：部分修改操作需要确认，以 Bot 提示为准。 - 参数：`<…>` 必填，`[…]` 可选，`|` 表示选项；子命令和参数之间保留必要的分隔。 示例：`成员 30`。可选数字表示未发言天数。统计依赖已有归档与成员数据；数据不完整时，没有发言记录的成员也可能发过言。 ### 发言 合并转发成员最近发言，本群可回复目标消息查询 ```text 发言 [数量] ``` - 最低权限：管理；分类：群管理。 - 所属插件：`manager_suite`；启用条件及子命令权限见下方说明与手册。 - 入口：在受管群中提及或回复 Bot；从管理群或好友私聊跨群操作时，先指定群号或别名。 - 目标范围：群命令需指定目标群或在目标群内使用。 - 确认：部分修改操作需要确认，以 Bot 提示为准。 - 参数：`<…>` 必填，`[…]` 可选，`|` 表示选项；子命令和参数之间保留必要的分隔。 - 成员：可填写 QQ 号或提及成员。标注 `[更多目标]` 的操作支持批量；QQ 号与提及不能混用，目标不能重复，时长或原因放在所有目标之后。 省略数量时使用“发言设置”的默认条数；单次最多查询 100 条已归档发言。 在本群回复成员消息并 @Bot，发送 发言 [数量]，例如 发言20；单个数字表示条数。显式 @成员 或填写 QQ号 数量 时优先使用指定目标。跨群操作须明确填写目标，不从回复推断。 示例：管理及以上权限发送 `@Bot 发言 123456789`、`@Bot 发言 @成员 30` 或 `@Bot 发言123456789 30`，查看目标成员在本群最近的已归档发言。Bot 以合并转发发送，默认 20 条，单次最多 100 条。管理群或私聊可用 `<群> 发言 [数量]` 查询受管群。结果不包含已撤回、超出消息保留期或 Bot 未记录的消息。 ### 扫描 实时扫描本群 ```text 扫描 ``` - 最低权限：管理；分类：查询分析。 - 所属插件：`manager_suite`；启用条件及子命令权限见下方说明与手册。 - 入口：在受管群中提及或回复 Bot；从管理群或好友私聊跨群操作时，先指定群号或别名。 - 目标范围：群命令需指定目标群或在目标群内使用。 - 确认：部分修改操作需要确认，以 Bot 提示为准。 - 参数：`<…>` 必填，`[…]` 可选，`|` 表示选项；子命令和参数之间保留必要的分隔。 示例：`扫描`。按当前权限扫描目标群，执行前核实群配置和扫描范围。 ### 分析 按时间范围分析归档消息，并说明上限及实际覆盖范围 ```text 分析 <半小时|X分钟|X小时|今|昨|起始时间 至 结束时间> ``` - 最低权限：管理；分类：查询分析。 - 所属插件：`manager_suite`；启用条件及子命令权限见下方说明与手册。 - 入口：在受管群中提及或回复 Bot；从管理群或好友私聊跨群操作时，先指定群号或别名。 - 目标范围：群命令需指定目标群或在目标群内使用。 - 确认：部分修改操作需要确认，以 Bot 提示为准。 - 参数：`<…>` 必填，`[…]` 可选，`|` 表示选项；子命令和参数之间保留必要的分隔。 结果会显示单次上限、实际覆盖范围及是否截断；超过上限时仅分析按时间排序的前段记录，请缩短时间范围后重试。范围说明同时写入 Markdown 和 PNG 报告。 示例：`分析 半小时`、`分析 6小时`。支持相对时间和明确起止时间，需要配置模型服务。分析可能向所配置的服务发送归档内容，应提前告知成员并遵守数据使用约定。 ### 导出 按时间范围导出 CSV，并说明上限及实际覆盖范围 ```text 导出 <半小时|X分钟|X小时|今|昨|起始时间 至 结束时间> ``` - 最低权限：管理；分类：查询分析。 - 所属插件：`manager_suite`；启用条件及子命令权限见下方说明与手册。 - 入口：在受管群中提及或回复 Bot；从管理群或好友私聊跨群操作时，先指定群号或别名。 - 目标范围：群命令需指定目标群或在目标群内使用。 - 确认：部分修改操作需要确认，以 Bot 提示为准。 - 参数：`<…>` 必填，`[…]` 可选，`|` 表示选项；子命令和参数之间保留必要的分隔。 结果会显示单次上限、实际覆盖范围及是否截断；超过上限时仅导出按时间排序的前段记录，请缩短时间范围后重试。CSV 中可能被表格软件识别为公式的文本会加单引号前缀，归档原文保留。 示例：`导出 昨` 或 `导出 30分钟`。导出范围由时间参数确定，结果可能包含账号与聊天内容；只交给有权接收的人，不把导出目录公开为网站静态目录。 ### 问答 管理本群问答与触发范围 ```text 问答 [列表|加|改|改问|改答|删|权限 ...] ``` - 最低权限：管理；分类：问答管理。 - 所属插件：`manager_suite`；启用条件及子命令权限见下方说明与手册。 - 入口：在受管群中提及或回复 Bot；从管理群或好友私聊跨群操作时，先指定群号或别名。 - 目标范围：群命令需指定目标群或在目标群内使用。 - 确认：部分修改操作需要确认，以 Bot 提示为准。 - 参数：`<…>` 必填，`[…]` 可选，`|` 表示选项；子命令和参数之间保留必要的分隔。 示例：`问答 列表`、`问答 加`、`问答 删 12`、`问答 权限 仅管理`、`问答 权限 关闭`。问答默认允许全员触发，群管理及以上权限可将本群改为仅管理触发、关闭或恢复全员。 新增问答时，可在会话中分开发送文字和图片，发送 `完成` 保存、`取消` 放弃。Bot 先匹配单群规则，再匹配分组规则，匹配顺序为精确、正则、模糊；ID 必须来自当前作用域。 ### 设置 查看群设置 ```text 设置 ``` - 最低权限：管理；分类：查询分析。 - 所属插件：`manager_suite`；启用条件及子命令权限见下方说明与手册。 - 入口：在受管群中提及或回复 Bot；从管理群或好友私聊跨群操作时，先指定群号或别名。 - 目标范围：群命令需指定目标群或在目标群内使用。 - 确认：部分修改操作需要确认，以 Bot 提示为准。 - 参数：`<…>` 必填，`[…]` 可选，`|` 表示选项；子命令和参数之间保留必要的分隔。 示例：`设置`。查看目标群设置，不接受参数。需要修改时，使用对应的群设置命令；Bot 只识别规定的命令格式。 ### 审计 查看群审计 ```text 审计 [数量|操作编号] ``` - 最低权限：管理；分类：查询分析。 - 所属插件：`manager_suite`；启用条件及子命令权限见下方说明与手册。 - 入口：在受管群中提及或回复 Bot；从管理群或好友私聊跨群操作时，先指定群号或别名。 - 目标范围：群命令需指定目标群或在目标群内使用。 - 确认：部分修改操作需要确认，以 Bot 提示为准。 - 参数：`<…>` 必填，`[…]` 可选，`|` 表示选项；子命令和参数之间保留必要的分隔。 示例：`审计 10`，也可用返回的操作编号查询。群内只能查询授权范围，管理入口的全局审计要求超管。查看审计后，还需核对平台实际执行结果。 ### 帮助 查看群命令帮助 ```text 帮助 [分类|命令] ``` - 最低权限：普通成员；分类：系统。 - 所属插件：`manager_suite`；启用条件及子命令权限见下方说明与手册。 - 入口：在受管群中提及或回复 Bot；从管理群或好友私聊跨群操作时，先指定群号或别名。 - 目标范围：群命令需指定目标群或在目标群内使用。 - 确认：部分修改操作需要确认，以 Bot 提示为准。 - 参数：`<…>` 必填，`[…]` 可选，`|` 表示选项；子命令和参数之间保留必要的分隔。 示例：`帮助`、`帮助 群管理`、`帮助 禁言`。聊天帮助只显示当前身份、会话和插件开关下可用的命令。公开文档列出全部命令，执行时仍需满足权限要求。 ### 解黑 移出分组黑名单 ```text 解黑 [分组] ``` - 最低权限：超管；分类：黑名单管理。 - 所属插件：`manager_suite`；启用条件及子命令权限见下方说明与手册。 - 入口：专用管理群或好友私聊；管理群提及或回复 Bot。 - 目标范围：全局命令的范围由分组或命令参数决定。 - 确认：修改前需在原会话按预览确认，Bot 会重新检查权限；只读查询无需确认。 - 参数：`<…>` 必填，`[…]` 可选，`|` 表示选项；子命令和参数之间保留必要的分隔。 - 成员：可填写 QQ 号或提及成员。标注 `[更多目标]` 的操作支持批量；QQ 号与提及不能混用，目标不能重复，时长或原因放在所有目标之后。 示例：`解黑 123456789` 或 `解黑 默认 @成员`。可选分组放在目标前面。操作只移除相应黑名单记录，不会自动邀请已踢出的成员重新入群。 ### 全局问答 管理分组全局问答 ```text 全局问答 [分组] [列表|加|改|改问|改答|删 ...] ``` - 最低权限：超管；分类：问答管理。 - 所属插件：`manager_suite`；启用条件及子命令权限见下方说明与手册。 - 入口：专用管理群或好友私聊；管理群提及或回复 Bot。 - 目标范围：全局命令的范围由分组或命令参数决定。 - 确认：部分修改操作需要确认，以 Bot 提示为准。 - 参数：`<…>` 必填，`[…]` 可选，`|` 表示选项；子命令和参数之间保留必要的分隔。 示例：`全局问答 默认 列表` 或 `全局问答 默认 加`。可选分组在子命令之前；编辑和删除需核实分组与规则 ID，单群规则仍优先。 ### 全局违禁词 管理分组统一违禁词 ```text 全局违禁词 [分组] [+|- <词>] ``` - 最低权限：超管；分类：内容管理。 - 所属插件：`manager_suite`；启用条件及子命令权限见下方说明与手册。 - 入口：专用管理群或好友私聊；管理群提及或回复 Bot。 - 目标范围：全局命令的范围由分组或命令参数决定。 - 确认：部分修改操作需要确认，以 Bot 提示为准。 - 参数：`<…>` 必填，`[…]` 可选，`|` 表示选项；子命令和参数之间保留必要的分隔。 示例：`全局违禁词 默认 + 测试词`。设置管理分组的统一规则，生效范围取决于群的分组归属和同步开关。 ### 全局同步 管理分组违禁词同步 ```text 全局同步 [分组] [开|关] ``` - 最低权限：超管；分类：内容管理。 - 所属插件：`manager_suite`；启用条件及子命令权限见下方说明与手册。 - 入口：专用管理群或好友私聊；管理群提及或回复 Bot。 - 目标范围：全局命令的范围由分组或命令参数决定。 - 确认：部分修改操作需要确认，以 Bot 提示为准。 - 参数：`<…>` 必填，`[…]` 可选，`|` 表示选项；子命令和参数之间保留必要的分隔。 示例：`全局同步 默认 开` 或 `全局同步 默认 关`。控制分组违禁词同步；省略分组时按主分组解释。 ### 全局锁群 锁定分组内目标群 ```text 全局锁群 [分组] <分钟> ``` - 最低权限：超管；分类：群设置。 - 所属插件：`manager_suite`；启用条件及子命令权限见下方说明与手册。 - 入口：专用管理群或好友私聊；管理群提及或回复 Bot。 - 目标范围：全局命令的范围由分组或命令参数决定。 - 确认：修改前需在原会话按预览确认，Bot 会重新检查权限；只读查询无需确认。 - 参数：`<…>` 必填，`[…]` 可选，`|` 表示选项；子命令和参数之间保留必要的分隔。 示例：`全局锁群 默认 10`。最后的数字为分钟数，需要确认；务必核对待操作群列表，可能影响多个社群。 ### 全局解锁 解除分组内目标群锁定 ```text 全局解锁 [分组] ``` - 最低权限：超管；分类：群设置。 - 所属插件：`manager_suite`；启用条件及子命令权限见下方说明与手册。 - 入口：专用管理群或好友私聊；管理群提及或回复 Bot。 - 目标范围：全局命令的范围由分组或命令参数决定。 - 确认：部分修改操作需要确认，以 Bot 提示为准。 - 参数：`<…>` 必填，`[…]` 可选，`|` 表示选项；子命令和参数之间保留必要的分隔。 示例：`全局解锁 默认`。解除该分组目标群的锁定。解除单个群的锁定时使用 `解锁群`。 ### 全局欢迎 设置分组统一欢迎语；被清理成员重新入群时附上上次清理原因 ```text 全局欢迎 [分组] [文本|开|关] ``` - 最低权限：超管；分类：群设置。 - 所属插件：`manager_suite`；启用条件及子命令权限见下方说明与手册。 - 入口：专用管理群或好友私聊；管理群提及或回复 Bot。 - 目标范围：全局命令的范围由分组或命令参数决定。 - 确认：部分修改操作需要确认，以 Bot 提示为准。 - 参数：`<…>` 必填，`[…]` 可选，`|` 表示选项；子命令和参数之间保留必要的分隔。 示例：`全局欢迎 默认 欢迎加入`。分组、文本之间保留分隔；各群是否继承取决于本群欢迎设置。 ### 全局统计 查看分组跨群统计 ```text 全局统计 [分组] ``` - 最低权限：超管；分类：查询分析。 - 所属插件：`manager_suite`；启用条件及子命令权限见下方说明与手册。 - 入口：专用管理群或好友私聊；管理群提及或回复 Bot。 - 目标范围：全局命令的范围由分组或命令参数决定。 - 确认：部分修改操作需要确认，以 Bot 提示为准。 - 参数：`<…>` 必填，`[…]` 可选，`|` 表示选项；子命令和参数之间保留必要的分隔。 示例：`全局统计 默认`。可选参数用于指定分组；只统计当前授权与配置范围。 ### 全扫 扫描分组内全部目标群 ```text 全扫 [分组] ``` - 最低权限：超管；分类：查询分析。 - 所属插件：`manager_suite`；启用条件及子命令权限见下方说明与手册。 - 入口：专用管理群或好友私聊；管理群提及或回复 Bot。 - 目标范围：全局命令的范围由分组或命令参数决定。 - 确认：部分修改操作需要确认，以 Bot 提示为准。 - 参数：`<…>` 必填，`[…]` 可选，`|` 表示选项；子命令和参数之间保留必要的分隔。 示例：`全扫 默认`。扫描分组全部目标群；范围大时可能耗时，避免连续重复触发。 ### 群组 查看有权管理的群 ```text 群组 ``` - 最低权限：管理；分类：查询分析。 - 所属插件：`manager_suite`；启用条件及子命令权限见下方说明与手册。 - 入口：专用管理群或好友私聊；管理群提及或回复 Bot。 - 目标范围：全局命令的范围由分组或命令参数决定。 - 确认：部分修改操作需要确认，以 Bot 提示为准。 - 参数：`<…>` 必填，`[…]` 可选，`|` 表示选项；子命令和参数之间保留必要的分隔。 示例：`群组`。只列出有权管理的群。它是无参数精确命令，不能在命令词后拼接群号作为筛选。 ### 黑名单 查看分组黑名单 ```text 黑名单 [分组] [数量] ``` - 最低权限：超管；分类：黑名单管理。 - 所属插件：`manager_suite`；启用条件及子命令权限见下方说明与手册。 - 入口：专用管理群或好友私聊；管理群提及或回复 Bot。 - 目标范围：全局命令的范围由分组或命令参数决定。 - 确认：部分修改操作需要确认，以 Bot 提示为准。 - 参数：`<…>` 必填，`[…]` 可选，`|` 表示选项；子命令和参数之间保留必要的分隔。 示例：`黑名单 默认 10`。可选参数依次为分组和数量；查看不会改变黑名单。 ### 清空黑名单 清空分组黑名单 ```text 清空黑名单 [分组] ``` - 最低权限：所有者；分类：黑名单管理。 - 所属插件：`manager_suite`；启用条件及子命令权限见下方说明与手册。 - 入口：专用管理群或好友私聊；管理群提及或回复 Bot。 - 目标范围：全局命令的范围由分组或命令参数决定。 - 确认：修改前需在原会话按预览确认，Bot 会重新检查权限；只读查询无需确认。 - 参数：`<…>` 必填，`[…]` 可选，`|` 表示选项；子命令和参数之间保留必要的分隔。 示例：`清空黑名单 默认`。仅 Bot 所有者可执行并需确认。会删除对应分组黑名单记录，先核实范围及保留需求。 ### 群别名 管理群别名 ```text 群别名 [<群号> <别名>|删 <群号>] ``` - 最低权限：超管；分类：全局管理。 - 所属插件：`manager_suite`；启用条件及子命令权限见下方说明与手册。 - 入口：专用管理群或好友私聊；管理群提及或回复 Bot。 - 目标范围：全局命令的范围由分组或命令参数决定。 - 确认：修改前需在原会话按预览确认，Bot 会重新检查权限；只读查询无需确认。 - 参数：`<…>` 必填，`[…]` 可选，`|` 表示选项；子命令和参数之间保留必要的分隔。 示例：`群别名 123456789 测试群`、`群别名 删 123456789`。群号和别名之间保留空格，写入需要确认；别名仅用于定位群，不授予访问权限。 ### 管理分组 管理项目分组及群归属 ```text 管理分组 [主分组 [名称]|新建 <名称>|删除 <名称>|加群 <名称> <群>|移群 <群>] ``` - 最低权限：超管；分类：全局管理。 - 所属插件：`manager_suite`；启用条件及子命令权限见下方说明与手册。 - 入口：专用管理群或好友私聊；管理群提及或回复 Bot。 - 目标范围：全局命令的范围由分组或命令参数决定。 - 确认：部分修改操作需要确认，以 Bot 提示为准。 - 参数：`<…>` 必填，`[…]` 可选，`|` 表示选项；子命令和参数之间保留必要的分隔。 示例：`管理分组 新建 测试组`、`管理分组 加群 测试组 123456789`、`管理分组 主分组 默认`。主分组决定省略分组时的操作范围，变更前检查后续全局命令影响。 ### 超管 查看超管列表；仅 Bot 所有者可增删数据库超管 ```text 超管 [加|删 ] ``` - 最低权限：超管；分类：全局管理。 - 所属插件：`manager_suite`；启用条件及子命令权限见下方说明与手册。 - 入口：专用管理群或好友私聊；管理群提及或回复 Bot。 - 目标范围：全局命令的范围由分组或命令参数决定。 - 确认：修改前需在原会话按预览确认，Bot 会重新检查权限；只读查询无需确认。 - 参数：`<…>` 必填，`[…]` 可选，`|` 表示选项；子命令和参数之间保留必要的分隔。 超管及以上可查看；仅 Bot 所有者可以增删数据库超管。 示例：`超管` 查看；`超管 加 123456789` 或 `超管 加 @成员` 修改。只有 Bot 所有者可以增删超管；能够查看列表的账号未必有修改权限。 ### 屏蔽对象 管理全局响应屏蔽对象 ```text 屏蔽对象 [加|删 ] ``` - 最低权限：超管；分类：全局管理。 - 所属插件：`manager_suite`；启用条件及子命令权限见下方说明与手册。 - 入口：专用管理群或好友私聊；管理群提及或回复 Bot。 - 目标范围：全局命令的范围由分组或命令参数决定。 - 确认：修改前需在原会话按预览确认，Bot 会重新检查权限；只读查询无需确认。 - 参数：`<…>` 必填，`[…]` 可选，`|` 表示选项；子命令和参数之间保留必要的分隔。 示例：`屏蔽对象 加 123456789` 或 `屏蔽对象 删 @成员`。单目标，影响全局响应屏蔽；与群内违禁检测白名单不同。 ### 运行状态 查看机器人运行信息 ```text 运行状态 ``` - 最低权限：管理；分类：系统。 - 所属插件：`manager_suite`；启用条件及子命令权限见下方说明与手册。 - 入口：专用管理群或好友私聊；管理群提及或回复 Bot。 - 目标范围：全局命令的范围由分组或命令参数决定。 - 确认：部分修改操作需要确认，以 Bot 提示为准。 - 参数：`<…>` 必填，`[…]` 可选，`|` 表示选项；子命令和参数之间保留必要的分隔。 示例：`运行状态`。查看机器人的运行信息，与目标群的配置状态不同。群入口和全局入口都会检查相应权限。 ### 审计 查看全局审计 ```text 审计 [数量|操作编号] ``` - 最低权限：超管；分类：查询分析。 - 所属插件：`manager_suite`；启用条件及子命令权限见下方说明与手册。 - 入口：专用管理群或好友私聊；管理群提及或回复 Bot。 - 目标范围：全局命令的范围由分组或命令参数决定。 - 确认：部分修改操作需要确认，以 Bot 提示为准。 - 参数：`<…>` 必填，`[…]` 可选，`|` 表示选项；子命令和参数之间保留必要的分隔。 示例：`审计 10`，也可用返回的操作编号查询。群内只能查询授权范围，管理入口的全局审计要求超管。查看审计后，还需核对平台实际执行结果。 ### 配置 管理群聊、插件及运行时配置 ```text 配置 [群聊 [群] [开|关]|插件 [群] [插件 开|关]|查看 [模块]|设置 <模块.键> <值>|重置 <模块.键>] ``` - 最低权限：所有者；分类：系统。 - 所属插件：`manager_suite`；启用条件及子命令权限见下方说明与手册。 - 入口：专用管理群或好友私聊；管理群提及或回复 Bot。 - 目标范围：全局命令的范围由分组或命令参数决定。 - 确认：部分修改操作需要确认，以 Bot 提示为准。 - 参数：`<…>` 必填，`[…]` 可选，`|` 表示选项；子命令和参数之间保留必要的分隔。 配置已保存但未能应用时，可重发原配置命令并确认，或在管理后台重新保存。 MAA 接收群使用 maa.maa_auto_upload_group_ids，多个群号用逗号分隔，- 清空列表；检查间隔使用 maa.maa_auto_upload_interval_seconds，管理群完成通知使用 maa.maa_auto_upload_notify_management（开或关）。也可在 Web 后台运行时配置中修改，保存后立即生效。 Codex通知支持 Codex 和 Pi，复用 Web 管理后台，需先配置 WEB_ADMIN_PUBLIC_URL 和 CODEX_NOTIFY_*；所有者可在后台授权 QQ 号和投递群，用户领取个人 Token 并查看 hook 教程。专用管理群通过部署配置启用。 示例：`配置 群聊 123456789 开`、`配置 插件 123456789 猜干员 开`、`配置 查看 operator_guess`。设置使用 `配置 设置 <模块.键> <值>`，重置使用 `配置 重置 <模块.键>`；写入、开关需要确认。部署密钥、账号、目录不通过此命令修改。 MAA 接收群使用 `配置 设置 maa.maa_auto_upload_group_ids 123456789,987654321`，也支持 `配置设置 maa.maa_auto_upload_group_ids 123456789,987654321`；按提示确认后立即生效。值 `-` 清空接收群，检查间隔使用 `maa.maa_auto_upload_interval_seconds`。定时上传管理群通知使用 `配置 设置 maa.maa_auto_upload_notify_management 开`，默认关闭；没有新文件时不推送。三项也可在 Web 后台「运行时配置 → 修改配置」保存，接收群需开启群聊和 MAA 插件。 Codex 群通知使用 `配置 插件 123456789 Codex通知 开`，也支持 `配置插件 123456789 Codex通知 开`；仅 Bot 所有者可操作，仍需确认。 接收接口由已有 Web 管理后台提供，需配置 `WEB_ADMIN_PUBLIC_URL` 和 `CODEX_NOTIFY_*`。普通群需加入 `CODEX_NOTIFY_GROUP_IDS` 并开启群聊。专用管理群通过部署配置启用，详情见 [Codex 通知手册](../plugins/codex_notify/README.md)。 ### 发言设置 查看或设置发言查询默认条数 ```text 发言设置 [默认条数] ``` - 最低权限：超管；分类：系统。 - 所属插件：`manager_suite`；启用条件及子命令权限见下方说明与手册。 - 入口：专用管理群或好友私聊；管理群提及或回复 Bot。 - 目标范围：全局命令的范围由分组或命令参数决定。 - 确认：部分修改操作需要确认，以 Bot 提示为准。 - 参数：`<…>` 必填，`[…]` 可选，`|` 表示选项；子命令和参数之间保留必要的分隔。 示例：超管及以上权限在管理群或私聊发送 `发言设置` 查看当前默认条数，发送 `发言设置 30` 或 `发言设置30` 修改默认条数。修改会保存，重启后仍有效；可配置范围为 1 至 100 条，单次查询仍可用 `发言 [数量]` 单独指定。 ### 管理后台 获取一次性后台登录链接，需管理及以上权限或 Codex 通知授权 ```text 管理后台 ``` - 最低权限：普通成员；分类：系统。 - 所属插件：`manager_suite`；启用条件及子命令权限见下方说明与手册。 - 入口：在群聊中提及或回复 Bot，或在好友私聊中发送；登录链接均通过私聊发送。 - 目标范围：全局命令的范围由分组或命令参数决定。 - 确认：部分修改操作需要确认，以 Bot 提示为准。 - 参数：`<…>` 必填，`[…]` 可选，`|` 表示选项；子命令和参数之间保留必要的分隔。 示例：`@Bot 管理后台` 或好友私聊 `管理后台`。需配置 Web 地址并满足管理权限；链接短时、一次性且绑定本人，勿转发。公开 `/docs` 不需要此链接。 ### 更新插件 拉取代码并同步依赖，启用 Web 后台时一并构建部署；重启前回复结果，上线后私聊报告版本变化，附操作编号和诊断日志的相对路径 ```text 更新插件 ``` - 最低权限：所有者；分类：系统。 - 所属插件：`manager_suite`；启用条件及子命令权限见下方说明与手册。 - 入口：专用管理群或好友私聊；管理群提及或回复 Bot。 - 目标范围：全局命令的范围由分组或命令参数决定。 - 确认：部分修改操作需要确认，以 Bot 提示为准。 - 参数：`<…>` 必填，`[…]` 可选，`|` 表示选项；子命令和参数之间保留必要的分隔。 仅 Bot 所有者可用。更新成功后重启前回复一次，上线后再私聊报告结果和版本变化；诊断日志路径以主数据库目录为起点。失败时先在服务端按操作编号查看诊断日志，再决定如何恢复或重试；代码或依赖可能已经更新。 示例：`更新插件`。仅 Bot 所有者可执行。Bot 会拉取代码、同步依赖；Web 后台启用时，还会安装构建依赖，在临时目录构建控制台。成功后部署资源、原子替换页面入口，再重启服务。构建或部署失败时保留原入口且不重启，更新期间拒绝重复更新和重启。 部署环境需具备对应命令及能自动重启服务的进程管理器。从 Web 执行时，反向代理还需允许等待 18 分钟。更新成功后下线前回复“更新已完成，正在重启”，上线后再私聊主人报告结果和插件版本变化；两次提醒都附操作编号和诊断位置，更新失败则立即回复。诊断位置 `update_logs/<操作编号>.jsonl` 相对主数据库目录，默认完整相对路径为 `data/update_logs/<操作编号>.jsonl`。从 Web 后台执行时，下线前的结果显示在后台，上线后私聊报告结果。旧后台会话失效，需重新获取登录链接。 ### 重启插件 重启 NoneBot 服务 ```text 重启插件 ``` - 最低权限：所有者；分类：系统。 - 所属插件：`manager_suite`；启用条件及子命令权限见下方说明与手册。 - 入口：专用管理群或好友私聊；管理群提及或回复 Bot。 - 目标范围：全局命令的范围由分组或命令参数决定。 - 确认：部分修改操作需要确认，以 Bot 提示为准。 - 参数：`<…>` 必填，`[…]` 可选，`|` 表示选项；子命令和参数之间保留必要的分隔。 示例：`重启插件`。仅 Bot 所有者使用，重启 NoneBot 服务会中断当前连接和内存会话；执行前避开正在进行的管理操作。 ### 帮助 查看可用命令，需管理及以上权限或 Codex 通知授权 ```text 帮助 [分类|命令] ``` - 最低权限：普通成员；分类：系统。 - 所属插件：`manager_suite`；启用条件及子命令权限见下方说明与手册。 - 入口：专用管理群或好友私聊；管理群提及或回复 Bot。 - 目标范围：全局命令的范围由分组或命令参数决定。 - 确认：部分修改操作需要确认，以 Bot 提示为准。 - 参数：`<…>` 必填，`[…]` 可选，`|` 表示选项；子命令和参数之间保留必要的分隔。 示例：`帮助`、`帮助 群管理`、`帮助 禁言`。聊天帮助只显示当前身份、会话和插件开关下可用的命令。公开文档列出全部命令，执行时仍需满足权限要求。 ### 这次刷什么 以图片查看活动推荐及常驻对照；正则模式支持自然问法且无需 @Bot ```text 这次刷什么 ``` - 最低权限：普通成员；分类：方舟刷图。 - 所属插件：`arknights_farming`；启用条件及子命令权限见下方说明与手册。 - 入口：在已启用插件的群聊中使用；触发方式和其他限制见对应插件手册。 - 目标范围：群命令需指定目标群或在目标群内使用。 - 确认：部分修改操作需要确认，以 Bot 提示为准。 - 参数：`<…>` 必填，`[…]` 可选，`|` 表示选项；子命令和参数之间保留必要的分隔。 示例：在启用“方舟刷图”的受管群发送 `@Bot 这次刷什么`，以图片查看当前活动推荐关卡、主要掉落材料和常驻对照。默认无参数、完整匹配；无活动时展示常见材料速查。所有者开启 `farming.arknights_farming_regex_enabled` 后无需提及 Bot，默认可直接问 `这次活动刷哪关`、`本次活动刷什么？`；自定义正则会替换对应的默认规则。 ### 活动刷图 这次刷什么的别名，查看活动刷图推荐图片 ```text 活动刷图 ``` - 最低权限：普通成员；分类：方舟刷图。 - 所属插件：`arknights_farming`；启用条件及子命令权限见下方说明与手册。 - 入口：在已启用插件的群聊中使用；触发方式和其他限制见对应插件手册。 - 目标范围：群命令需指定目标群或在目标群内使用。 - 确认：部分修改操作需要确认，以 Bot 提示为准。 - 参数：`<…>` 必填，`[…]` 可选，`|` 表示选项；子命令和参数之间保留必要的分隔。 示例：`@Bot 活动刷图`，与“这次刷什么”等价。默认无参数，`活动刷图排行` 不触发命令。普通群成员可用，须开启“方舟刷图”；正则模式无需提及 Bot，问法以配置规则为准。 ### 去哪刷 以图片对比材料的活动与常驻关卡；正则模式支持材料名在前 ```text 去哪刷 <材料名> ``` - 最低权限：普通成员；分类：方舟刷图。 - 所属插件：`arknights_farming`；启用条件及子命令权限见下方说明与手册。 - 入口：在已启用插件的群聊中使用；触发方式和其他限制见对应插件手册。 - 目标范围：群命令需指定目标群或在目标群内使用。 - 确认：部分修改操作需要确认，以 Bot 提示为准。 - 参数：`<…>` 必填，`[…]` 可选，`|` 表示选项；子命令和参数之间保留必要的分隔。 示例：`@Bot 去哪刷 固源岩组` 或 `@Bot 去哪刷固源岩组`。图片使用游戏材料图标，分区展示国服当前活动和常驻关卡，标注单件理智、样本次数及活动与常驻的成本对比。普通群成员可用；简称匹配多个材料时会提示完整名称。正则模式默认还支持不提及 Bot 发送 `固源岩组去哪刷？`、`固源岩组在哪里刷`，材料规则须用 `(?P...)` 提取材料名。 ### 材料掉落 去哪刷的别名，支持完整材料名及无歧义简称 ```text 材料掉落 <材料名> ``` - 最低权限：普通成员；分类：方舟刷图。 - 所属插件：`arknights_farming`；启用条件及子命令权限见下方说明与手册。 - 入口：在已启用插件的群聊中使用；触发方式和其他限制见对应插件手册。 - 目标范围：群命令需指定目标群或在目标群内使用。 - 确认：部分修改操作需要确认，以 Bot 提示为准。 - 参数：`<…>` 必填，`[…]` 可选，`|` 表示选项；子命令和参数之间保留必要的分隔。 示例：`@Bot 材料掉落 固源岩组` 或 `@Bot 材料掉落固源岩组`，与“去哪刷”等价。默认须在启用“方舟刷图”的受管群提及或回复 Bot；正则模式无需提及，仍仅响应已启用插件的群，不提供私聊入口。数据收集中或刷新失败时会明确提示。 ### 呼叫管理 向管理群发送求助，也支持本群配置的召唤词；未 @ 时只提示用法，连续提示会退避 ```text 呼叫管理 [说明] ``` - 最低权限：普通成员；分类：群管理。 - 所属插件：`call_admin`；启用条件及子命令权限见下方说明与手册。 - 入口：在已启用插件的群聊中使用；触发方式和其他限制见对应插件手册。 - 目标范围：群命令需指定目标群或在目标群内使用。 - 确认：部分修改操作需要确认，以 Bot 提示为准。 - 参数：`<…>` 必填，`[…]` 可选，`|` 表示选项；子命令和参数之间保留必要的分隔。 在已启用管理召唤的受管群提及或回复 Bot，发送 呼叫管理 [说明]。同一成员在同一群聊发送中或冷却内不会重复转发，管理群收到纯文字通知。 未提及 Bot 时，召唤用语及部分冲突语句只会得到固定用法提示；提示按群共享退避，不影响正式召唤。来人不触发用法提示。 示例：`@Bot 呼叫管理 请协助处理广告`、`@Bot 呼叫管理有人刷屏`。`呼叫管理` 始终可用，默认还支持 `管理`、`举报`、`召唤管理`；其他召唤词可由 Bot 所有者配置。仅在已启用插件的受管群转发，管理群收到纯文字通知，不会提及任何人。 未提及 Bot 时，召唤用语及“再说群要没了”“管理呢管一下”等冲突语句会得到固定提示：`联系管理员请发送：@Bot 呼叫管理 [说明]。` 提示按群共享退避，不会转发，也不占用正式召唤的冷却。`来人` 不再触发用法提示。主人可在 Web 后台“运行时配置 → 管理召唤匹配规则”查看并编辑关键词与冲突提示正则。正则句式、退避间隔与正式召唤冷却见[管理召唤手册](../plugins/call_admin/README.md)；不要使用本功能公开传播隐私。 ### 关卡难度 查询 PRTS 关卡难度、低配要求和常用干员 ```text 关卡难度 <关卡代号或名称> [综合|普通|突袭] ``` - 最低权限：普通成员；分类：PRTS作业。 - 所属插件：`prts_difficulty`；启用条件及子命令权限见下方说明与手册。 - 入口：在已启用插件的群聊中使用；触发方式和其他限制见对应插件手册。 - 目标范围：群命令需指定目标群或在目标群内使用。 - 确认：部分修改操作需要确认，以 Bot 提示为准。 - 参数：`<…>` 必填，`[…]` 可选，`|` 表示选项；子命令和参数之间保留必要的分隔。 示例：`关卡难度 TO-S-1`、`关卡难度TO-S-1`。关卡可用代号或名称，后面可选择综合、普通、突袭。查看关卡难度、低配要求和常用干员；数据待补充时显示暂定结果。 ### 活动难度排行 查看 PRTS 活动难度排行 ```text 活动难度排行 [页码] ``` - 最低权限：普通成员；分类：PRTS作业。 - 所属插件：`prts_difficulty`；启用条件及子命令权限见下方说明与手册。 - 入口：在已启用插件的群聊中使用；触发方式和其他限制见对应插件手册。 - 目标范围：群命令需指定目标群或在目标群内使用。 - 确认：部分修改操作需要确认，以 Bot 提示为准。 - 参数：`<…>` 必填，`[…]` 可选，`|` 表示选项；子命令和参数之间保留必要的分隔。 示例：`活动难度排行 1`。可选数字为页码。排行使用同步缓存，刚发布的活动可能尚未更新。 ### 难度排行 查看 PRTS 关卡难度排行 ```text 难度排行 [综合|普通|突袭] [分类] [页码] ``` - 最低权限：普通成员；分类：PRTS作业。 - 所属插件：`prts_difficulty`；启用条件及子命令权限见下方说明与手册。 - 入口：在已启用插件的群聊中使用；触发方式和其他限制见对应插件手册。 - 目标范围：群命令需指定目标群或在目标群内使用。 - 确认：部分修改操作需要确认，以 Bot 提示为准。 - 参数：`<…>` 必填，`[…]` 可选，`|` 表示选项；子命令和参数之间保留必要的分隔。 示例：`难度排行 综合`、`难度排行突袭 主线 2`。查看关卡难度排行，可按模式、分类和页码筛选。 ### 低配排行 查看 PRTS 关卡低配排行 ```text 低配排行 [综合|普通|突袭] [分类] [页码] ``` - 最低权限：普通成员；分类：PRTS作业。 - 所属插件：`prts_difficulty`；启用条件及子命令权限见下方说明与手册。 - 入口：在已启用插件的群聊中使用；触发方式和其他限制见对应插件手册。 - 目标范围：群命令需指定目标群或在目标群内使用。 - 确认：部分修改操作需要确认，以 Bot 提示为准。 - 参数：`<…>` 必填，`[…]` 可选，`|` 表示选项；子命令和参数之间保留必要的分隔。 示例：`低配排行 综合`、`低配排行普通 主线 2`。查看关卡低配排行，模式、分类和页码按用法顺序提供。 ### 干员排行 查看 PRTS 干员出场或难度关联排行 ```text 干员排行 [出场|关联] [综合|普通|突袭] [分类] [页码] ``` - 最低权限：普通成员；分类：PRTS作业。 - 所属插件：`prts_difficulty`；启用条件及子命令权限见下方说明与手册。 - 入口：在已启用插件的群聊中使用；触发方式和其他限制见对应插件手册。 - 目标范围：群命令需指定目标群或在目标群内使用。 - 确认：部分修改操作需要确认，以 Bot 提示为准。 - 参数：`<…>` 必填，`[…]` 可选，`|` 表示选项；子命令和参数之间保留必要的分隔。 示例：`干员排行 出场 综合` 或 `干员排行 关联 综合`。查看干员出场率或难度关联排行，可按模式、分类和页码筛选。 ### 干员统计 查询 PRTS 干员统计 ```text 干员统计 <干员名> [综合|普通|突袭] [分类] ``` - 最低权限：普通成员；分类：PRTS作业。 - 所属插件：`prts_difficulty`；启用条件及子命令权限见下方说明与手册。 - 入口：在已启用插件的群聊中使用；触发方式和其他限制见对应插件手册。 - 目标范围：群命令需指定目标群或在目标群内使用。 - 确认：部分修改操作需要确认，以 Bot 提示为准。 - 参数：`<…>` 必填，`[…]` 可选，`|` 表示选项；子命令和参数之间保留必要的分隔。 示例：`干员统计 能天使`。参数为干员名称，具体筛选格式见 PRTS 手册；没有命中时先核对名字与数据同步状态。 ### 作业数据状态 查看 PRTS 作业数据同步状态 ```text 作业数据状态 ``` - 最低权限：普通成员；分类：PRTS作业。 - 所属插件：`prts_difficulty`；启用条件及子命令权限见下方说明与手册。 - 入口：在已启用插件的群聊中使用；触发方式和其他限制见对应插件手册。 - 目标范围：群命令需指定目标群或在目标群内使用。 - 确认：部分修改操作需要确认，以 Bot 提示为准。 - 参数：`<…>` 必填，`[…]` 可选，`|` 表示选项；子命令和参数之间保留必要的分隔。 示例：`作业数据状态`。只查看数据缓存状态，不触发刷新。命令无参数，必须精确匹配。 ### 刷新作业数据 刷新 PRTS 作业数据 ```text 刷新作业数据 ``` - 最低权限：超管；分类：PRTS作业。 - 所属插件：`prts_difficulty`；启用条件及子命令权限见下方说明与手册。 - 入口：在已启用插件的群聊中使用；触发方式和其他限制见对应插件手册。 - 目标范围：群命令需指定目标群或在目标群内使用。 - 确认：部分修改操作需要确认，以 Bot 提示为准。 - 参数：`<…>` 必填，`[…]` 可选，`|` 表示选项；子命令和参数之间保留必要的分隔。 示例：`刷新作业数据`。超管及以上可启动后台刷新，使用 `作业数据状态` 查看进度。 ### MAA版本 查看 MAA 最新版本信息；内测版需群管理员以上权限 ```text MAA版本 [稳定|公测|内测] ``` - 最低权限：普通成员；分类：MAA下载。 - 所属插件：`maa_download`；启用条件及子命令权限见下方说明与手册。 - 入口：在已启用插件的群聊中使用；触发方式和其他限制见对应插件手册。 - 目标范围：群命令需指定目标群或在目标群内使用。 - 确认：部分修改操作需要确认，以 Bot 提示为准。 - 参数：`<…>` 必填，`[…]` 可选，`|` 表示选项；子命令和参数之间保留必要的分隔。 示例：`MAA版本 稳定`、`MAA版本稳定`。稳定和公测通道向群成员开放，内测通道需要管理及以上权限。 ### MAA下载 获取安装包或最新资源源码 ZIP 的镜像链接；资源包按活动名命名，不能带平台参数，内测版需群管理员及以上权限 ```text MAA下载 [稳定|公测|内测|资源] [平台] ``` - 最低权限：普通成员；分类：MAA下载。 - 所属插件：`maa_download`；启用条件及子命令权限见下方说明与手册。 - 入口：在已启用插件的群聊中使用；触发方式和其他限制见对应插件手册。 - 目标范围：群命令需指定目标群或在目标群内使用。 - 确认：部分修改操作需要确认，以 Bot 提示为准。 - 参数：`<…>` 必填，`[…]` 可选，`|` 表示选项；子命令和参数之间保留必要的分隔。 发送 MAA下载 资源、MAA下载资源 或 MAA下载 资源包 获取最新资源更新提交的源码 ZIP 镜像链接，资源包不带平台参数。获取活动信息后按活动名自动命名，结果显示活动和资源更新时间。元数据不可用时保留提交命名。 示例：`MAA下载 公测 linux-x64`、`MAA下载 资源`、`MAA下载资源` 或 `MAA下载 资源包`。省略参数默认稳定版 Windows x64；资源包返回最新自动资源更新提交的 MaaResource 源码 ZIP 镜像，群成员可用，不接受平台参数。获取活动信息后显示活动与资源更新时间，文件按活动名命名，如 `资源包_[昨日海]#1009_8d949986.zip`；元数据不可用时保留提交命名。安装包平台在通道之后；镜像来自第三方，链接可能失效。 ### MAA镜像状态 实时检测 MAA 下载镜像 ```text MAA镜像状态 ``` - 最低权限：普通成员；分类：MAA下载。 - 所属插件：`maa_download`；启用条件及子命令权限见下方说明与手册。 - 入口：在已启用插件的群聊中使用；触发方式和其他限制见对应插件手册。 - 目标范围：群命令需指定目标群或在目标群内使用。 - 确认：部分修改操作需要确认，以 Bot 提示为准。 - 参数：`<…>` 必填，`[…]` 可选，`|` 表示选项；子命令和参数之间保留必要的分隔。 示例：`MAA镜像状态`。强制刷新稳定版 Windows x64 的目录与节点状态；`MAA镜像状态123` 不触发。 ### MAA上传状态 查看上传步骤、镜像、下载进度、目标群、耗时和最近结果；相同结果合并显示群号，复用文件时显示来源群 ```text MAA上传状态 ``` - 最低权限：所有者；分类：MAA下载。 - 所属插件：`maa_download`；启用条件及子命令权限见下方说明与手册。 - 入口：在已启用插件的群聊中使用；触发方式和其他限制见对应插件手册。 - 目标范围：群命令需指定目标群或在目标群内使用。 - 确认：部分修改操作需要确认，以 Bot 提示为准。 - 参数：`<…>` 必填，`[…]` 可选，`|` 表示选项；子命令和参数之间保留必要的分隔。 仅 Bot 所有者可用；受管群、专用管理群需提及或回复 Bot，好友私聊可直接发送。无参数，必须完整匹配；任务运行中也可查询。上传响应超时或中断时先标记待确认，查询会核对群文件并更新结果。 示例：`@Bot MAA上传状态`，好友私聊直接发送 `MAA上传状态`。仅 Bot 所有者可用，支持已启用插件的受管群、专用管理群和好友私聊；无参数，`MAA上传状态123` 不触发。 运行中可查看任务来源、开始时间、步骤持续时间、最后进展、文件、镜像节点、下载进度和当前群；完成后可查看最近结果与错误步骤。配置接收群和可用群显示数量，未启用群单独列出；相同结果合并群号，当前文件名只显示一次，合并后最多显示最近 12 条结果。 Milky 上传接口不提供字节进度，上传时显示当前群和等待耗时；使用群文件链接时还会显示来源群；首群超时后显示“等待来源群上传成功”，当前任务每 30 秒核对，沿用从该次上传开始的 10 分钟确认期限，确认成功后继续上传其余群。任务诊断状态会在重启或重载配置后重新记录。 上传响应超时或网络中断时先显示“上传结果待确认”，查询状态会核对群文件，后台也每 30 秒核对；同名、同大小文件出现后改为成功。等待期间不重复上传，待确认记录在重启后继续有效；从自动接收群配置删除群号后，对应待确认记录和群级通知会在下一轮清理。 ### MAA上传状态 查看上传步骤、镜像、下载进度、目标群、耗时和最近结果；相同结果合并显示群号，复用文件时显示来源群 ```text MAA上传状态 ``` - 最低权限：所有者；分类：MAA下载。 - 所属插件：`maa_download`；启用条件及子命令权限见下方说明与手册。 - 入口：专用管理群或好友私聊；管理群提及或回复 Bot。 - 目标范围：全局命令的范围由分组或命令参数决定。 - 确认：部分修改操作需要确认，以 Bot 提示为准。 - 参数：`<…>` 必填，`[…]` 可选，`|` 表示选项；子命令和参数之间保留必要的分隔。 仅 Bot 所有者可用；受管群、专用管理群需提及或回复 Bot，好友私聊可直接发送。无参数，必须完整匹配；任务运行中也可查询。上传响应超时或中断时先标记待确认，查询会核对群文件并更新结果。 示例：`@Bot MAA上传状态`，好友私聊直接发送 `MAA上传状态`。仅 Bot 所有者可用，支持已启用插件的受管群、专用管理群和好友私聊；无参数，`MAA上传状态123` 不触发。 运行中可查看任务来源、开始时间、步骤持续时间、最后进展、文件、镜像节点、下载进度和当前群；完成后可查看最近结果与错误步骤。配置接收群和可用群显示数量，未启用群单独列出；相同结果合并群号，当前文件名只显示一次，合并后最多显示最近 12 条结果。 Milky 上传接口不提供字节进度，上传时显示当前群和等待耗时；使用群文件链接时还会显示来源群；首群超时后显示“等待来源群上传成功”，当前任务每 30 秒核对，沿用从该次上传开始的 10 分钟确认期限，确认成功后继续上传其余群。任务诊断状态会在重启或重载配置后重新记录。 上传响应超时或网络中断时先显示“上传结果待确认”，查询状态会核对群文件，后台也每 30 秒核对；同名、同大小文件出现后改为成功。等待期间不重复上传，待确认记录在重启后继续有效；从自动接收群配置删除群号后，对应待确认记录和群级通知会在下一轮清理。 ### MAA上传测试 立即下载并测试群文件上传，按文件汇总结果；正式版不重复上传到公测版文件夹。先确认来源群上传成功，再用其文件链接上传其余群；已有文件直接复用，加“覆盖”会先删除同名文件再上传 ```text MAA上传测试 [正式|公测|资源|全部] [覆盖] ``` - 最低权限：所有者；分类：MAA下载。 - 所属插件：`maa_download`；启用条件及子命令权限见下方说明与手册。 - 入口：在已启用插件的群聊中使用；触发方式和其他限制见对应插件手册。 - 目标范围：群命令需指定目标群或在目标群内使用。 - 确认：部分修改操作需要确认，以 Bot 提示为准。 - 参数：`<…>` 必填，`[…]` 可选，`|` 表示选项；子命令和参数之间保留必要的分隔。 仅 Bot 所有者可用；受管群、专用管理群需提及或回复 Bot，好友私聊可直接发送。默认测试全部文件，接收群需开启群聊和 MAA 插件。末尾加 覆盖 可先删除目标文件夹中的同名文件再上传，例如 MAA上传测试资源 覆盖；MAA上传测试覆盖 测试全部类型，Bot 需有删除群文件的权限。任务运行中可发送 MAA上传状态 查看进度。 自动上传和手动测试均先向一个群上传，确认成功后再复用群文件链接上传其余群；首群结果待确认时先等待核对，等待结束仍无法确认则暂缓其余群。测试结果按文件汇总，相同结果合并群号，文件名只显示一次。部署时配置 MAA_UPLOAD_SHARED_DIRECTORY 后首群优先共享路径上传，Bot 与 Milky 须能以相同绝对路径访问文件；未配置时首群使用二进制上传。 示例：`MAA上传测试 正式`、`MAA上传测试资源` 或 `MAA上传测试 全部`。仅 Bot 所有者可用，受管群和专用管理群需提及或回复 Bot，好友私聊直接发送。省略参数测试全部；公测接口返回正式版时跳过公测版下载和上传，手动测试和 `覆盖` 也不重复上传正式版到公测版文件夹。 立即下载最新文件并向已配置接收群上传，结果按文件汇总，相同结果合并群号，文件名只显示一次；不同状态与错误分别保留，已有同名、同大小文件直接复用。 自动上传和手动测试均先上传一个群，确认成功并取得文件 ID 后，再复用其群文件链接上传其他群；首群超时会先等待核对，确认期限结束仍无法取得来源文件 ID 时，其他群显示“暂缓上传”，覆盖模式也不会提前删除其他群的同名文件。 部署配置 `MAA_UPLOAD_SHARED_DIRECTORY` 后首群优先共享路径上传，Bot 与 Milky 须能以相同绝对路径访问文件，成功时显示“上传成功（共享路径）”；未配置或共享路径不可用时首群使用二进制。其余群通过链接上传，成功时显示“上传成功（复用群文件链接）”；链接不可用或被明确拒绝时回退到二进制上传。任务运行中会附带当前状态，也可发送 `MAA上传状态` 单独查看；接收群和 MAA 插件需先启用。 ### MAA上传测试 立即下载并测试群文件上传，按文件汇总结果；正式版不重复上传到公测版文件夹。先确认来源群上传成功，再用其文件链接上传其余群；已有文件直接复用，加“覆盖”会先删除同名文件再上传 ```text MAA上传测试 [正式|公测|资源|全部] [覆盖] ``` - 最低权限：所有者；分类：MAA下载。 - 所属插件：`maa_download`；启用条件及子命令权限见下方说明与手册。 - 入口：专用管理群或好友私聊；管理群提及或回复 Bot。 - 目标范围：全局命令的范围由分组或命令参数决定。 - 确认：部分修改操作需要确认，以 Bot 提示为准。 - 参数：`<…>` 必填，`[…]` 可选，`|` 表示选项；子命令和参数之间保留必要的分隔。 仅 Bot 所有者可用；受管群、专用管理群需提及或回复 Bot，好友私聊可直接发送。默认测试全部文件，接收群需开启群聊和 MAA 插件。末尾加 覆盖 可先删除目标文件夹中的同名文件再上传，例如 MAA上传测试资源 覆盖；MAA上传测试覆盖 测试全部类型，Bot 需有删除群文件的权限。任务运行中可发送 MAA上传状态 查看进度。 自动上传和手动测试均先向一个群上传，确认成功后再复用群文件链接上传其余群；首群结果待确认时先等待核对，等待结束仍无法确认则暂缓其余群。测试结果按文件汇总，相同结果合并群号，文件名只显示一次。部署时配置 MAA_UPLOAD_SHARED_DIRECTORY 后首群优先共享路径上传，Bot 与 Milky 须能以相同绝对路径访问文件；未配置时首群使用二进制上传。 示例：`MAA上传测试 正式`、`MAA上传测试资源` 或 `MAA上传测试 全部`。仅 Bot 所有者可用，受管群和专用管理群需提及或回复 Bot，好友私聊直接发送。省略参数测试全部；公测接口返回正式版时跳过公测版下载和上传，手动测试和 `覆盖` 也不重复上传正式版到公测版文件夹。 立即下载最新文件并向已配置接收群上传，结果按文件汇总，相同结果合并群号，文件名只显示一次；不同状态与错误分别保留，已有同名、同大小文件直接复用。 自动上传和手动测试均先上传一个群，确认成功并取得文件 ID 后，再复用其群文件链接上传其他群；首群超时会先等待核对，确认期限结束仍无法取得来源文件 ID 时，其他群显示“暂缓上传”，覆盖模式也不会提前删除其他群的同名文件。 部署配置 `MAA_UPLOAD_SHARED_DIRECTORY` 后首群优先共享路径上传，Bot 与 Milky 须能以相同绝对路径访问文件，成功时显示“上传成功（共享路径）”；未配置或共享路径不可用时首群使用二进制。其余群通过链接上传，成功时显示“上传成功（复用群文件链接）”；链接不可用或被明确拒绝时回退到二进制上传。任务运行中会附带当前状态，也可发送 `MAA上传状态` 单独查看；接收群和 MAA 插件需先启用。 ### 猜干员 发起立绘或技能猜干员；普通成员能否发起由本群设置决定 ```text 猜干员 [初级|困难|极难|噩梦|中级|立绘|困难立绘|极难立绘|噩梦立绘|技能] ``` - 最低权限：普通成员；分类：猜干员游戏。 - 所属插件：`operator_guess`；启用条件及子命令权限见下方说明与手册。 - 入口：在已启用插件的群聊中使用；触发方式和其他限制见对应插件手册。 - 目标范围：群命令需指定目标群或在目标群内使用。 - 确认：部分修改操作需要确认，以 Bot 提示为准。 - 参数：`<…>` 必填，`[…]` 可选，`|` 表示选项；子命令和参数之间保留必要的分隔。 游戏规则： - 开局后所有成员直接发送干员名答题，无需 @Bot。 - 发送 提示 或 不知道 获取提示；普通提示使本题和整局结算倍率 -2%，终极提示 -10%。 - 发送 下一题、放弃 或 跳过会揭晓答案，整局结算倍率 -5%。 - 普通群成员能否发起游戏由本群管理设置；群管理可结束游戏和维护全局自定义别名。 - 默认每局 30 题；完成至少 15 题才发放名次积分，已获得的答题积分始终计入赛季。 - 困难立绘优先展示角色外缘的小视野，积分倍率为 2 倍。 - 极难立绘将小视野切成 4×4 碎片并打乱，提示会恢复部分拼图并扩大视野，积分倍率为 3 倍。 - 噩梦立绘在外缘裁剪的基础上使用错色、勾线，或保留大致颜色位置的无轮廓色带与色块，积分倍率为 4 倍；技能模式为 2 倍。 - 同批答案只结算第一条有效正确答案；未知、重复答案和重复消息不消耗机会。 示例：`猜干员 立绘`、`猜干员 技能`。开局后成员直接发干员名答题；`提示`/`不知道` 求提示，`下一题`/`放弃`/`跳过` 揭晓答案。普通成员开局资格由群设置决定，提示和跳过影响积分倍率。完整模式、结算和结束操作见游戏手册。 ### 猜干员成员开始 设置是否允许普通群成员发起游戏 ```text 猜干员成员开始 开启|关闭 ``` - 最低权限：管理；分类：猜干员游戏。 - 所属插件：`operator_guess`；启用条件及子命令权限见下方说明与手册。 - 入口：在已启用插件的群聊中使用；触发方式和其他限制见对应插件手册。 - 目标范围：群命令需指定目标群或在目标群内使用。 - 确认：部分修改操作需要确认，以 Bot 提示为准。 - 参数：`<…>` 必填，`[…]` 可选，`|` 表示选项；子命令和参数之间保留必要的分隔。 示例：`猜干员成员开始 开启` 或 `猜干员成员开始 关闭`。群管理可以设置普通成员能否开局；该开关只影响游戏开局资格。 ### 猜干员排行 查看本群当前赛季积分榜 ```text 猜干员排行 ``` - 最低权限：普通成员；分类：猜干员游戏。 - 所属插件：`operator_guess`；启用条件及子命令权限见下方说明与手册。 - 入口：在已启用插件的群聊中使用；触发方式和其他限制见对应插件手册。 - 目标范围：群命令需指定目标群或在目标群内使用。 - 确认：部分修改操作需要确认，以 Bot 提示为准。 - 参数：`<…>` 必填，`[…]` 可选，`|` 表示选项；子命令和参数之间保留必要的分隔。 示例：`猜干员排行`。查看排行；积分受赛季、模式、提示与有效参与规则影响，完整参数见游戏手册。 ### 猜干员积分 查看自己的当前赛季积分与答题统计 ```text 猜干员积分 ``` - 最低权限：普通成员；分类：猜干员游戏。 - 所属插件：`operator_guess`；启用条件及子命令权限见下方说明与手册。 - 入口：在已启用插件的群聊中使用；触发方式和其他限制见对应插件手册。 - 目标范围：群命令需指定目标群或在目标群内使用。 - 确认：部分修改操作需要确认，以 Bot 提示为准。 - 参数：`<…>` 必填，`[…]` 可选，`|` 表示选项；子命令和参数之间保留必要的分隔。 示例：`猜干员积分`。查看个人积分。单题积分与整局名次积分分别计算，未达到整局结算门槛仍可获得单题积分；此命令只查询分数。 ### 猜干员状态 查看对局或本地资源缓存状态 ```text 猜干员状态 ``` - 最低权限：普通成员；分类：猜干员游戏。 - 所属插件：`operator_guess`；启用条件及子命令权限见下方说明与手册。 - 入口：在已启用插件的群聊中使用；触发方式和其他限制见对应插件手册。 - 目标范围：群命令需指定目标群或在目标群内使用。 - 确认：部分修改操作需要确认，以 Bot 提示为准。 - 参数：`<…>` 必填，`[…]` 可选，`|` 表示选项；子命令和参数之间保留必要的分隔。 示例：`猜干员状态`。查看当前游戏状态；游戏未开始时无法通过提示或答案消息开启。 ### 猜干员别名 查看答题时可用的干员别名 ```text 猜干员别名 查看 <干员名> ``` - 最低权限：普通成员；分类：猜干员游戏。 - 所属插件：`operator_guess`；启用条件及子命令权限见下方说明与手册。 - 入口：在已启用插件的群聊中使用；触发方式和其他限制见对应插件手册。 - 目标范围：群命令需指定目标群或在目标群内使用。 - 确认：部分修改操作需要确认，以 Bot 提示为准。 - 参数：`<…>` 必填，`[…]` 可选，`|` 表示选项；子命令和参数之间保留必要的分隔。 示例：`猜干员别名 查看 能天使`。别名维护影响全局识别，管理增删时先核对干员标准名；具体增删参数见游戏手册。 ### 猜干员别名 为干员添加一个或多个全局自定义别名 ```text 猜干员别名 添加 <干员名> <别名1> [别名2 ...] ``` - 最低权限：管理；分类：猜干员游戏。 - 所属插件：`operator_guess`；启用条件及子命令权限见下方说明与手册。 - 入口：在已启用插件的群聊中使用；触发方式和其他限制见对应插件手册。 - 目标范围：群命令需指定目标群或在目标群内使用。 - 确认：部分修改操作需要确认，以 Bot 提示为准。 - 参数：`<…>` 必填，`[…]` 可选，`|` 表示选项；子命令和参数之间保留必要的分隔。 示例：`猜干员别名 查看 能天使`。别名维护影响全局识别，管理增删时先核对干员标准名；具体增删参数见游戏手册。 ### 猜干员别名 删除全局猜干员自定义别名 ```text 猜干员别名 删除 <别名> ``` - 最低权限：管理；分类：猜干员游戏。 - 所属插件：`operator_guess`；启用条件及子命令权限见下方说明与手册。 - 入口：在已启用插件的群聊中使用；触发方式和其他限制见对应插件手册。 - 目标范围：群命令需指定目标群或在目标群内使用。 - 确认：部分修改操作需要确认，以 Bot 提示为准。 - 参数：`<…>` 必填，`[…]` 可选，`|` 表示选项；子命令和参数之间保留必要的分隔。 示例：`猜干员别名 查看 能天使`。别名维护影响全局识别，管理增删时先核对干员标准名；具体增删参数见游戏手册。 ### 今日方舟 以方舟风格长图查看未来7天截止事项、商店轮换、周常提醒和本群可用的查询入口 ```text 今日方舟 ``` - 最低权限：普通成员；分类：截止提醒。 - 所属插件：`arknights_reminders`；启用条件及子命令权限见下方说明与手册。 - 入口：在已启用插件的群聊中使用；触发方式和其他限制见对应插件手册。 - 目标范围：群命令需指定目标群或在目标群内使用。 - 确认：部分修改操作需要确认，以 Bot 提示为准。 - 参数：`<…>` 必填，`[…]` 可选，`|` 表示选项；子命令和参数之间保留必要的分隔。 在已启用截止提醒的群内提及或回复 Bot 发送 今日方舟，无需参数。专属长图按截止、商店和周常分区，24小时内事项突出标记，底部以紧凑列表展示查询入口；图片不可用时返回完整文字。事项读取已同步数据，标准与中坚黄票商店各显示最近一次轮换，周常和月常显示下次重置。 PRTS、MAA 查询入口仅在本群启用对应插件时显示；完整事项和订阅用法可发送 帮助 提醒 查看。 示例：`@Bot 今日方舟`。在开启截止提醒的群内提及或回复 Bot 使用，无参数。用一张方舟风格专属长图汇总未来 7 天的截止事项、标准与中坚黄票商店最近一次轮换、下次周常和月常重置。24 小时内事项同时以红色与文字标记，查询入口以紧凑行表展示，绘制失败时返回完整文字。每个区块最多显示 8 项，完整事项可用 `提醒 列表` 查询。仅显示全局及本群有效事项，读取已有同步数据，不改变订阅。PRTS 与 MAA 查询入口随本群对应插件开关显示。 ### 提醒 查看未截止事项 ```text 提醒 列表 [分类] [页码] ``` - 最低权限：普通成员；分类：截止提醒。 - 所属插件：`arknights_reminders`；启用条件及子命令权限见下方说明与手册。 - 入口：在已启用插件的群聊中使用；触发方式和其他限制见对应插件手册。 - 目标范围：群命令需指定目标群或在目标群内使用。 - 确认：部分修改操作需要确认，以 Bot 提示为准。 - 参数：`<…>` 必填，`[…]` 可选，`|` 表示选项；子命令和参数之间保留必要的分隔。 示例：`提醒 分类`、`提醒 订阅 寻访 活动商店 3天 1天`、`提醒 我的`、`提醒 取消订阅 寻访`。多个分类可连续指定，`全部` 不能和分类混用；默认档位 3天、1天、12小时，均为大致提前时间。提醒会避开 22:00–09:00，消息显示实际剩余时间。`提醒订阅 寻访` 只省略第一个分隔，子命令与分类之间仍需保留空格。 ### 提醒 查看可订阅分类 ```text 提醒 分类 ``` - 最低权限：普通成员；分类：截止提醒。 - 所属插件：`arknights_reminders`；启用条件及子命令权限见下方说明与手册。 - 入口：在已启用插件的群聊中使用；触发方式和其他限制见对应插件手册。 - 目标范围：群命令需指定目标群或在目标群内使用。 - 确认：部分修改操作需要确认，以 Bot 提示为准。 - 参数：`<…>` 必填，`[…]` 可选，`|` 表示选项；子命令和参数之间保留必要的分隔。 示例：`提醒 分类`、`提醒 订阅 寻访 活动商店 3天 1天`、`提醒 我的`、`提醒 取消订阅 寻访`。多个分类可连续指定，`全部` 不能和分类混用；默认档位 3天、1天、12小时，均为大致提前时间。提醒会避开 22:00–09:00，消息显示实际剩余时间。`提醒订阅 寻访` 只省略第一个分隔，子命令与分类之间仍需保留空格。 ### 提醒 订阅一个或多个分类，填“全部”可订阅所有分类；提醒时间可多选或省略，按大致提前时间安排，避开 22:00–09:00 ```text 提醒 订阅 <分类...|全部> [7天 3天 1天 12小时 3小时 1小时] ``` - 最低权限：普通成员；分类：截止提醒。 - 所属插件：`arknights_reminders`；启用条件及子命令权限见下方说明与手册。 - 入口：在已启用插件的群聊中使用；触发方式和其他限制见对应插件手册。 - 目标范围：群命令需指定目标群或在目标群内使用。 - 确认：部分修改操作需要确认，以 Bot 提示为准。 - 参数：`<…>` 必填，`[…]` 可选，`|` 表示选项；子命令和参数之间保留必要的分隔。 示例：`提醒 分类`、`提醒 订阅 寻访 活动商店 3天 1天`、`提醒 我的`、`提醒 取消订阅 寻访`。多个分类可连续指定，`全部` 不能和分类混用；默认档位 3天、1天、12小时，均为大致提前时间。提醒会避开 22:00–09:00，消息显示实际剩余时间。`提醒订阅 寻访` 只省略第一个分隔，子命令与分类之间仍需保留空格。 ### 提醒 取消一个或多个分类的订阅，填“全部”可取消所有分类订阅 ```text 提醒 取消订阅 <分类...|全部> ``` - 最低权限：普通成员；分类：截止提醒。 - 所属插件：`arknights_reminders`；启用条件及子命令权限见下方说明与手册。 - 入口：在已启用插件的群聊中使用；触发方式和其他限制见对应插件手册。 - 目标范围：群命令需指定目标群或在目标群内使用。 - 确认：部分修改操作需要确认，以 Bot 提示为准。 - 参数：`<…>` 必填，`[…]` 可选，`|` 表示选项；子命令和参数之间保留必要的分隔。 示例：`提醒 分类`、`提醒 订阅 寻访 活动商店 3天 1天`、`提醒 我的`、`提醒 取消订阅 寻访`。多个分类可连续指定，`全部` 不能和分类混用；默认档位 3天、1天、12小时，均为大致提前时间。提醒会避开 22:00–09:00，消息显示实际剩余时间。`提醒订阅 寻访` 只省略第一个分隔，子命令与分类之间仍需保留空格。 ### 提醒 查看我的分类订阅 ```text 提醒 我的 ``` - 最低权限：普通成员；分类：截止提醒。 - 所属插件：`arknights_reminders`；启用条件及子命令权限见下方说明与手册。 - 入口：在已启用插件的群聊中使用；触发方式和其他限制见对应插件手册。 - 目标范围：群命令需指定目标群或在目标群内使用。 - 确认：部分修改操作需要确认，以 Bot 提示为准。 - 参数：`<…>` 必填，`[…]` 可选，`|` 表示选项；子命令和参数之间保留必要的分隔。 示例：`提醒 分类`、`提醒 订阅 寻访 活动商店 3天 1天`、`提醒 我的`、`提醒 取消订阅 寻访`。多个分类可连续指定，`全部` 不能和分类混用；默认档位 3天、1天、12小时，均为大致提前时间。提醒会避开 22:00–09:00，消息显示实际剩余时间。`提醒订阅 寻访` 只省略第一个分隔，子命令与分类之间仍需保留空格。 ### 提醒管理 查看同步后待审核的提醒候选 ```text 提醒管理 候选 [页码|#候选ID] ``` - 最低权限：超管；分类：截止提醒。 - 所属插件：`arknights_reminders`；启用条件及子命令权限见下方说明与手册。 - 入口：专用管理群或好友私聊；管理群提及或回复 Bot。 - 目标范围：全局命令的范围由分组或命令参数决定。 - 确认：部分修改操作需要确认，以 Bot 提示为准。 - 参数：`<…>` 必填，`[…]` 可选，`|` 表示选项；子命令和参数之间保留必要的分隔。 示例：`提醒管理 状态`、`提醒管理 候选 1`、`提醒管理 刷新 全部`。新建参数依次为模板、时间、范围，随后以 `|` 分隔标题和内容；修改使用事项 ID。审核候选、暂停删除和恢复同步可能影响订阅投递，按预览执行确认。 ### 提醒管理 发布或驳回同步得到的提醒候选 ```text 提醒管理 <发布|驳回> <候选ID> ``` - 最低权限：超管；分类：截止提醒。 - 所属插件：`arknights_reminders`；启用条件及子命令权限见下方说明与手册。 - 入口：专用管理群或好友私聊；管理群提及或回复 Bot。 - 目标范围：全局命令的范围由分组或命令参数决定。 - 确认：部分修改操作需要确认，以 Bot 提示为准。 - 参数：`<…>` 必填，`[…]` 可选，`|` 表示选项；子命令和参数之间保留必要的分隔。 示例：`提醒管理 状态`、`提醒管理 候选 1`、`提醒管理 刷新 全部`。新建参数依次为模板、时间、范围，随后以 `|` 分隔标题和内容；修改使用事项 ID。审核候选、暂停删除和恢复同步可能影响订阅投递，按预览执行确认。 ### 提醒管理 新建截止事项 ```text 提醒管理 新建 <模板> <全部|群号|别名> | <标题> | <内容> ``` - 最低权限：超管；分类：截止提醒。 - 所属插件：`arknights_reminders`；启用条件及子命令权限见下方说明与手册。 - 入口：专用管理群或好友私聊；管理群提及或回复 Bot。 - 目标范围：全局命令的范围由分组或命令参数决定。 - 确认：部分修改操作需要确认，以 Bot 提示为准。 - 参数：`<…>` 必填，`[…]` 可选，`|` 表示选项；子命令和参数之间保留必要的分隔。 示例：`提醒管理 状态`、`提醒管理 候选 1`、`提醒管理 刷新 全部`。新建参数依次为模板、时间、范围，随后以 `|` 分隔标题和内容；修改使用事项 ID。审核候选、暂停删除和恢复同步可能影响订阅投递，按预览执行确认。 ### 提醒管理 修改截止事项 ```text 提醒管理 修改 <截止|标题|内容|分类|范围> <值> ``` - 最低权限：超管；分类：截止提醒。 - 所属插件：`arknights_reminders`；启用条件及子命令权限见下方说明与手册。 - 入口：专用管理群或好友私聊；管理群提及或回复 Bot。 - 目标范围：全局命令的范围由分组或命令参数决定。 - 确认：部分修改操作需要确认，以 Bot 提示为准。 - 参数：`<…>` 必填，`[…]` 可选，`|` 表示选项；子命令和参数之间保留必要的分隔。 示例：`提醒管理 状态`、`提醒管理 候选 1`、`提醒管理 刷新 全部`。新建参数依次为模板、时间、范围，随后以 `|` 分隔标题和内容；修改使用事项 ID。审核候选、暂停删除和恢复同步可能影响订阅投递，按预览执行确认。 ### 提醒管理 管理截止事项状态 ```text 提醒管理 <暂停|恢复|删除|同步源> ``` - 最低权限：超管；分类：截止提醒。 - 所属插件：`arknights_reminders`；启用条件及子命令权限见下方说明与手册。 - 入口：专用管理群或好友私聊；管理群提及或回复 Bot。 - 目标范围：全局命令的范围由分组或命令参数决定。 - 确认：部分修改操作需要确认，以 Bot 提示为准。 - 参数：`<…>` 必填，`[…]` 可选，`|` 表示选项；子命令和参数之间保留必要的分隔。 示例：`提醒管理 状态`、`提醒管理 候选 1`、`提醒管理 刷新 全部`。新建参数依次为模板、时间、范围，随后以 `|` 分隔标题和内容；修改使用事项 ID。审核候选、暂停删除和恢复同步可能影响订阅投递，按预览执行确认。 ### 提醒管理 刷新指定来源 ```text 提醒管理 刷新 [全部|PRTS|官网] ``` - 最低权限：超管；分类：截止提醒。 - 所属插件：`arknights_reminders`；启用条件及子命令权限见下方说明与手册。 - 入口：专用管理群或好友私聊；管理群提及或回复 Bot。 - 目标范围：全局命令的范围由分组或命令参数决定。 - 确认：部分修改操作需要确认，以 Bot 提示为准。 - 参数：`<…>` 必填，`[…]` 可选，`|` 表示选项；子命令和参数之间保留必要的分隔。 示例：`提醒管理 状态`、`提醒管理 候选 1`、`提醒管理 刷新 全部`。新建参数依次为模板、时间、范围，随后以 `|` 分隔标题和内容；修改使用事项 ID。审核候选、暂停删除和恢复同步可能影响订阅投递，按预览执行确认。 ### 提醒管理 暂停或继续定时拉取来源数据 ```text 提醒管理 <暂停拉取|继续拉取> [全部|PRTS|官网] ``` - 最低权限：所有者；分类：截止提醒。 - 所属插件：`arknights_reminders`；启用条件及子命令权限见下方说明与手册。 - 入口：专用管理群或好友私聊；管理群提及或回复 Bot。 - 目标范围：全局命令的范围由分组或命令参数决定。 - 确认：部分修改操作需要确认，以 Bot 提示为准。 - 参数：`<…>` 必填，`[…]` 可选，`|` 表示选项；子命令和参数之间保留必要的分隔。 示例：`提醒管理 状态`、`提醒管理 候选 1`、`提醒管理 刷新 全部`。新建参数依次为模板、时间、范围，随后以 `|` 分隔标题和内容；修改使用事项 ID。审核候选、暂停删除和恢复同步可能影响订阅投递，按预览执行确认。 ### 提醒管理 查看服务状态或确认待执行操作 ```text 提醒管理 <状态|确认> ``` - 最低权限：超管；分类：截止提醒。 - 所属插件：`arknights_reminders`；启用条件及子命令权限见下方说明与手册。 - 入口：专用管理群或好友私聊；管理群提及或回复 Bot。 - 目标范围：全局命令的范围由分组或命令参数决定。 - 确认：部分修改操作需要确认，以 Bot 提示为准。 - 参数：`<…>` 必填，`[…]` 可选，`|` 表示选项；子命令和参数之间保留必要的分隔。 示例：`提醒管理 状态`、`提醒管理 候选 1`、`提醒管理 刷新 全部`。新建参数依次为模板、时间、范围，随后以 `|` 分隔标题和内容；修改使用事项 ID。审核候选、暂停删除和恢复同步可能影响订阅投递，按预览执行确认。 ### 请求管理 管理好友请求与 Bot 入群邀请的处理和通知规则 ```text 请求管理 [好友|入群|待审|同意|拒绝 ...] ``` - 最低权限：所有者；分类：全局管理。 - 所属插件：`request_manager`；启用条件及子命令权限见下方说明与手册。 - 入口：专用管理群或好友私聊；管理群提及或回复 Bot。 - 目标范围：全局命令的范围由分组或命令参数决定。 - 确认：部分修改操作需要确认，以 Bot 提示为准。 - 参数：`<…>` 必填，`[…]` 可选，`|` 表示选项；子命令和参数之间保留必要的分隔。 示例：`请求管理`、`请求管理 待审 20`、`请求管理 同意 12`、`请求管理 拒绝 12 不符合要求`。仅 Bot 所有者可在管理群或好友私聊使用；处理好友请求和邀请 Bot 入群，不负责普通成员申请加入群。平台过期请求可能无法继续处理。 ### 网站状态 在网站通知群查看官网服务状态 ```text 网站状态 ``` - 最低权限：普通成员；分类：系统。 - 所属插件：`manager_suite`；启用条件及子命令权限见下方说明与手册。 - 入口：仅配置的网站通知群；提及或回复 Bot，且网站状态集成需要可用。 - 目标范围：群命令需指定目标群或在目标群内使用。 - 确认：部分修改操作需要确认，以 Bot 提示为准。 - 参数：`<…>` 必填，`[…]` 可选，`|` 表示选项；子命令和参数之间保留必要的分隔。 示例：在网站通知群发送 `@Bot 网站状态`。只有已启用相应网站状态集成的通知群可以查询。网络请求失败时，网站本身也可能仍在正常运行。 ### 服务状态 在网站通知群查看官网服务状态（网站状态的别名） ```text 服务状态 ``` - 最低权限：普通成员；分类：系统。 - 所属插件：`manager_suite`；启用条件及子命令权限见下方说明与手册。 - 入口：仅配置的网站通知群；提及或回复 Bot，且网站状态集成需要可用。 - 目标范围：群命令需指定目标群或在目标群内使用。 - 确认：部分修改操作需要确认，以 Bot 提示为准。 - 参数：`<…>` 必填，`[…]` 可选，`|` 表示选项；子命令和参数之间保留必要的分隔。 示例：`@Bot 服务状态`。这是 `网站状态` 的别名，入口、权限和启用条件相同。 ### 内测注册 私聊获取网站内测注册邀请码 ```text 内测注册 ``` - 最低权限：普通成员；分类：系统。 - 所属插件：`manager_suite`；启用条件及子命令权限见下方说明与手册。 - 入口：仅限私聊；是否支持好友私聊或群临时会话，请查阅对应手册。 - 目标范围：全局命令的范围由分组或命令参数决定。 - 确认：部分修改操作需要确认，以 Bot 提示为准。 - 参数：`<…>` 必填，`[…]` 可选，`|` 表示选项；子命令和参数之间保留必要的分隔。 示例：私聊或支持的群临时会话发送 `内测注册`。需确认仍在指定内测群；返回个人一次性注册链接，有效期 24 小时。Bot 不保存邀请码，不向 Bot 提交邮箱、密码或奖励参数。 ### 绑定网站 私聊绑定网站账号；请先在网站账号安全页生成绑定码 ```text 绑定网站 <绑定码> ``` - 最低权限：普通成员；分类：网站排班。 - 所属插件：`manager_suite`；启用条件及子命令权限见下方说明与手册。 - 入口：仅限私聊；是否支持好友私聊或群临时会话，请查阅对应手册。 - 目标范围：全局命令的范围由分组或命令参数决定。 - 确认：部分修改操作需要确认，以 Bot 提示为准。 - 参数：`<…>` 必填，`[…]` 可选，`|` 表示选项；子命令和参数之间保留必要的分隔。 仅网站通知群的当前成员可在好友私聊中使用。 示例：网站通知群的当前成员在好友私聊发送 `绑定网站 <绑定码>`，也支持 `绑定网站<绑定码>`。先在网站账号安全页生成 24 位绑定码。绑定后通知默认关闭；添加 Bot 为好友后再开启通知。此分类的账号、通知、结果、下载及确认命令均限当前通知群成员，退出通知群后停止个人推送。 ### 网站账号 查看绑定、通知状态和档案 ID ```text 网站账号 ``` - 最低权限：普通成员；分类：网站排班。 - 所属插件：`manager_suite`；启用条件及子命令权限见下方说明与手册。 - 入口：仅限私聊；是否支持好友私聊或群临时会话，请查阅对应手册。 - 目标范围：全局命令的范围由分组或命令参数决定。 - 确认：部分修改操作需要确认，以 Bot 提示为准。 - 参数：`<…>` 必填，`[…]` 可选，`|` 表示选项；子命令和参数之间保留必要的分隔。 仅网站通知群的当前成员可在好友私聊中使用。 示例：好友私聊发送 `网站账号`，查看绑定和通知状态，以及自己的档案名称、状态和 ID。需先部署并启用个人排班集成。 ### 开启排班通知 接收后续排班的私聊提醒和 MAA JSON ```text 开启排班通知 ``` - 最低权限：普通成员；分类：网站排班。 - 所属插件：`manager_suite`；启用条件及子命令权限见下方说明与手册。 - 入口：仅限私聊；是否支持好友私聊或群临时会话，请查阅对应手册。 - 目标范围：全局命令的范围由分组或命令参数决定。 - 确认：部分修改操作需要确认，以 Bot 提示为准。 - 参数：`<…>` 必填，`[…]` 可选，`|` 表示选项；子命令和参数之间保留必要的分隔。 仅网站通知群的当前成员可在好友私聊中使用。 示例：好友私聊发送 `开启排班通知`。开启后，网站正式排班生成时会收到个人提醒和可导入 MAA 的 JSON；需要体验券时先收到下载提示，轮班制排班在网站查看。关闭期间的排班不补发。 ### 关闭排班通知 关闭排班私聊通知并取消待发提醒 ```text 关闭排班通知 ``` - 最低权限：普通成员；分类：网站排班。 - 所属插件：`manager_suite`；启用条件及子命令权限见下方说明与手册。 - 入口：仅限私聊；是否支持好友私聊或群临时会话，请查阅对应手册。 - 目标范围：全局命令的范围由分组或命令参数决定。 - 确认：部分修改操作需要确认，以 Bot 提示为准。 - 参数：`<…>` 必填，`[…]` 可选，`|` 表示选项；子命令和参数之间保留必要的分隔。 仅网站通知群的当前成员可在好友私聊中使用。 示例：好友私聊发送 `关闭排班通知`。关闭通知并取消待发提醒，仍可主动下载排班。 ### 解绑网站 确认后解除网站账号绑定 ```text 解绑网站 ``` - 最低权限：普通成员；分类：网站排班。 - 所属插件：`manager_suite`；启用条件及子命令权限见下方说明与手册。 - 入口：仅限私聊；是否支持好友私聊或群临时会话，请查阅对应手册。 - 目标范围：全局命令的范围由分组或命令参数决定。 - 确认：修改前需在原会话按预览确认，Bot 会重新检查权限；只读查询无需确认。 - 参数：`<…>` 必填，`[…]` 可选，`|` 表示选项；子命令和参数之间保留必要的分隔。 仅网站通知群的当前成员可在好友私聊中使用。 在 120 秒内发送 确认解绑网站，或发送 取消。 示例：好友私聊发送 `解绑网站`，随后在 120 秒内发送 `确认解绑网站`，或发送 `取消`。解绑后通知关闭；重新绑定时需要再次开启。 ### 排班结果 查看自己的排班结果及结果 ID ```text 排班结果 <档案ID> [翻页码] ``` - 最低权限：普通成员；分类：网站排班。 - 所属插件：`manager_suite`；启用条件及子命令权限见下方说明与手册。 - 入口：仅限私聊；是否支持好友私聊或群临时会话，请查阅对应手册。 - 目标范围：全局命令的范围由分组或命令参数决定。 - 确认：部分修改操作需要确认，以 Bot 提示为准。 - 参数：`<…>` 必填，`[…]` 可选，`|` 表示选项；子命令和参数之间保留必要的分隔。 仅网站通知群的当前成员可在好友私聊中使用。 示例：好友私聊发送 `排班结果 <档案ID>`，也支持 `排班结果<档案ID>`。档案 ID 用 `网站账号` 查询；结果中显示结果 ID 和下载用法。还有结果时，按返回的 `排班结果 <档案ID> <翻页码>` 继续查看。 ### 下载排班 私聊下载 MAA JSON，需要体验券时先确认消耗 1 张券 ```text 下载排班 <档案ID> <结果ID> ``` - 最低权限：普通成员；分类：网站排班。 - 所属插件：`manager_suite`；启用条件及子命令权限见下方说明与手册。 - 入口：仅限私聊；是否支持好友私聊或群临时会话，请查阅对应手册。 - 目标范围：全局命令的范围由分组或命令参数决定。 - 确认：部分修改操作需要确认，以 Bot 提示为准。 - 参数：`<…>` 必填，`[…]` 可选，`|` 表示选项；子命令和参数之间保留必要的分隔。 仅网站通知群的当前成员可在好友私聊中使用。 需要体验券时，Bot 会先提示消耗 1 张券；在 120 秒内发送 确认下载排班，或发送 取消。 示例：好友私聊发送 `下载排班 <档案ID> <结果ID>`，也支持 `下载排班<档案ID> <结果ID>`。Bot 直接发送 MAA JSON 文件；需要体验券时先提示消耗 1 张券，在 120 秒内发送 `确认下载排班` 或 `取消`。网络或文件发送失败时，在确认有效期内再次确认会沿用原下载请求，避免重复扣券。 ### 确认解绑网站 确认当前私聊中待处理的解绑操作 ```text 确认解绑网站 ``` - 最低权限：普通成员；分类：网站排班。 - 所属插件：`manager_suite`；启用条件及子命令权限见下方说明与手册。 - 入口：仅限私聊；是否支持好友私聊或群临时会话，请查阅对应手册。 - 目标范围：全局命令的范围由分组或命令参数决定。 - 确认：部分修改操作需要确认，以 Bot 提示为准。 - 参数：`<…>` 必填，`[…]` 可选，`|` 表示选项；子命令和参数之间保留必要的分隔。 仅网站通知群的当前成员可在好友私聊中使用。 示例：好友私聊发送 `解绑网站` 后，在 120 秒内发送 `确认解绑网站`。只确认同一 QQ 在当前好友会话中的待处理解绑；绑定已变化时需要重新发起。 ### 确认下载排班 同意消耗 1 张体验券，下载当前待确认的 MAA JSON ```text 确认下载排班 ``` - 最低权限：普通成员；分类：网站排班。 - 所属插件：`manager_suite`；启用条件及子命令权限见下方说明与手册。 - 入口：仅限私聊；是否支持好友私聊或群临时会话，请查阅对应手册。 - 目标范围：全局命令的范围由分组或命令参数决定。 - 确认：部分修改操作需要确认，以 Bot 提示为准。 - 参数：`<…>` 必填，`[…]` 可选，`|` 表示选项；子命令和参数之间保留必要的分隔。 仅网站通知群的当前成员可在好友私聊中使用。 示例：好友私聊发起下载并看到消耗 1 张体验券的提示后，在 120 秒内发送 `确认下载排班`。这表示同意用券；文件或网络失败时可在有效期内再次发送此命令。 # Bot 公共核心 `bot_core` 为各业务插件提供共用配置、数据库、权限、插件开关、Web 后台和 Markdown 消息渲染，版本独立维护在 `plugins/versions.py`。它随 Bot 常驻运行，不提供群级开关。 ## 代码归属 | 位置 | 负责内容 | | --- | --- | | `plugins/bot_core/` | 公共配置与数据库、权限、角色与命令帮助、运行时配置、响应屏蔽、通知工具、运行状态、Web HTTP 服务、公开文档和 Markdown 图片 | | `framework/` | 命令、事件、脚本运行与 Milky 适配等通用框架；与公共核心使用同一版本 | | `frontend/` | Web 后台的 React 页面与公共组件；与公共核心使用同一版本 | | `plugins/manager_suite/` | 群管命令、归档、风控、问答、成员统计、入群验证、聊天分析和网站业务 | | 各业务插件目录 | 对应业务的命令、处理逻辑、配置及后台接口，例如 `plugins/codex_notify/web.py` | Web 后台中的管理套件功能仍调用管理套件的业务处理函数；其他插件的后台接口仍由各插件实现，公共核心负责承载 HTTP 服务、登录和权限控制。修改公共后台不再要求管理套件跟随升级；同时修改业务处理时，才更新对应业务插件版本。 后台按 Bot、成员和群缓存 QQ 群角色，成功结果保留 5 分钟，查询失败保留 15 秒后重试；刷新时允许使用平台缓存。首次查询并行执行，每项最多等待 5 秒，同一查询的并发请求共用结果。到期刷新失败时拒绝该群访问，不沿用旧权限。Bot 重新连接后重新查询；群开关、管理分组、超管身份和超管后台群限制仍在每次请求时检查。QQ 端角色变更受这段缓存及平台缓存的刷新时间影响。 共用数据库目前集中保留已有表和迁移，避免拆库或改变数据路径。`Config` 中原有环境变量、`manager.*` 运行时配置键、数据库文件、消息接口和后台 URL 均保持兼容。 ## 插件接入 业务插件在导入公共模块前声明依赖： ```python 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 消息渲染](../../docs/markdown_messages.md)。内置中文字体位于 `plugins/bot_core/resources/fonts/`，部署时须保留字体及授权文件。 ## 版本管理 - `pyproject.toml` 的 `project.version` 是合集版本，`uv.lock` 中的项目版本同步更新。 - `PLUGIN_VERSIONS["bot_core"]` 是公共核心版本；修改本目录、`framework/` 或 `frontend/` 的代码时更新它。 - 修改业务插件代码时更新该插件版本；仅修改公共核心，无需更新管理套件或其他业务插件版本。 - 同时修改公共核心与业务插件时，分别更新实际受影响的版本。本次拆分调整了所有业务插件的导入与依赖声明，因此它们各自更新一次版本。 - 合集版本随发布变更更新。新增兼容功能升 minor，兼容修复升 patch，不兼容变更按仓库版本规则处理。文档和测试单独修改不要求升版。 `运行状态`、后台“插件概览”和公开文档会展示公共核心版本；群聊插件设置只展示可按群启停的业务插件。 ## 验证 ```bash 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` 标记需要转成图片的内容，普通字符串保持文字；参数顺序就是发送顺序。 ## 纯图片 ```python 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 特殊字符按原文显示。单行提示保持文字，图片渲染失败时回退到完整原文。 ```python from plugins.bot_core.messages import render_text_panel message = await render_text_panel("群状态\n人数：120/200\n自动清理：关") await bot.send(event, message) ``` 在聊天发送入口选择需要图片展示的回复，业务查询函数仍返回文字，供 Web 后台等入口复用。目前转换范围如下： | 功能 | 图片回复 | | --- | --- | | 管理套件 | 帮助目录和用法、群状态与运行状态、网站状态查询、成员统计与扫描、群设置、违规和审计记录、分组统计、群与黑名单清单；配置、风控、入群验证、管理分组、群别名、超管、违禁词和问答的默认查询，以及问答列表、配置查看 | | PRTS 作业 | 关卡难度、关卡与活动排行、干员统计与排行、数据同步状态 | | 明日方舟提醒 | 分类、事项列表、我的订阅、待审候选及详情、来源状态 | | 请求管理 | 默认规则、待审核请求清单 | | MAA | 版本摘要、镜像检测状态、上传状态、上传测试结果 | | 猜干员 | 赛季排行榜、个人积分、资源状态、别名查询、游戏结算明细 | | 网站排班 | 私聊帮助目录和用法 | 操作确认、错误和进度提示保持文字。群回复保留真正的 QQ 提及；猜干员结束提示和积分保存失败提示保留文字，明细使用图片。下载和后台登录链接、排班查询中的档案 ID、结果 ID 及翻页命令继续使用文字，方便点击和复制。问答自动回复与 MaiBot 转发内容沿用原有消息形式。 ## 今日方舟专属卡片 `今日方舟` 使用 `plugins.arknights_reminders.today_renderer` 直接绘制深色方舟风格卡片，不经过 Markdown。`today.py` 先汇总结构化事项和查询入口，图片与失败时的文字回复共用这份数据。 长图使用项目自带的常规与粗体中文字体，固定宽 960 像素，高度按全部内容计算，输出单张 PNG。长标题和备注自动换行，常用查询使用命令与说明两列的紧凑行表，操作提示仅在分区标题处显示一次。`render_today_png` 返回 PNG 字节，Pillow 在线程中绘制，无需保存临时图片；任一步失败时回退完整文字，群回复仍保留真正的 QQ 提及。 ## 关键通知保留文字，详情转成图片 ```python 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 时，使用公共底层接口： ```python 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_core/README.md) 提供并独立管理版本。 | 功能 | 用途 | | --- | --- | | 多群管理 | 受管群、群别名、管理分组和跨群命令 | | 成员管理 | 撤回、禁言、踢人、警告、黑名单和角色调整 | | 内容策略 | 违禁词、检测白名单、问答和行为广告风控 | | 群聊配置 | 欢迎语、锁群、头衔申请和入群验证 | | 数据与维护 | 消息归档、成员统计、清理、分析、导出和审计 | | 管理入口 | 运行时配置、Web 管理后台和网站集成 | ## 快速导航 ### 入口与解析 命令入口、成员目标格式和紧凑命令规则见[主文档的命令入口](../../README.md#命令入口)。本插件只识别规定的命令格式，自然语言描述不会执行管理操作。 | 输入 | 结果 | | --- | --- | | `@Bot 禁言 123456 10` | 标准格式，禁言目标 10 分钟 | | `@Bot 禁言123456 10` | 紧凑格式，与标准格式等价 | | `@Bot 把 123456 禁言十分钟` | 自然语言，不识别为命令 | | `@Bot 状态123` | 不识别，无参数命令必须完整匹配 | ### 帮助系统 聊天帮助只显示当前入口、账号权限和插件开关允许使用的命令： ```text @Bot 帮助 @Bot 帮助 <分类> @Bot 帮助 <命令> ``` 发送 `帮助` 查看当前可用分类，再发送 `帮助 <命令>` 查看完整参数。 ### 权限体系 权限由低到高为： ```text 普通成员 < 管理 < 群主 < 超管 < Bot 所有者 ``` | 角色 | 定义方式 | 可用操作 | | --- | --- | --- | | 普通成员 | QQ 群普通成员 | 只能使用普通成员级交互，无管理写权限 | | 管理 | 实时读取目标 QQ 群的管理员身份 | 执行成员管理、查询和基础群级命令 | | 群主 | 实时读取目标 QQ 群的群主身份 | 在管理权限基础上调整群设置、入群验证和成员角色 | | 超管 | `SUPER_ADMIN_USER_IDS` 与数据库超管记录的合集 | 跨群管理、分组策略和全局操作 | | Bot 所有者 | 唯一的 `OWNER_USER_ID` | 拥有全部权限，可维护超管、群聊开关、插件开关和运行时配置 | 专用管理群中的普通成员从该入口操作主分组时，插件按「管理」级别授权；直接在目标群或好友私聊中执行群命令时，仍读取操作者在目标群的实时 QQ 角色。 操作者只能管理权限低于自己的目标。Bot、操作者本人以及同级或更高权限成员受到保护。 ### 管理分组 管理分组让多个受管群共用一套规则。每个群都属于一个分组；未分配的群位于「默认」分组。主分组决定省略分组参数时，全局命令作用于哪些群。 各分组分别保存违禁词、欢迎语、黑名单和问答，互不影响。超管及以上权限可使用以下命令： | 命令 | 用途 | | --- | --- | | `@Bot 管理分组` | 查看分组、主分组和群归属 | | `@Bot 管理分组 新建 <名称>` | 新建分组 | | `@Bot 管理分组 主分组 [名称]` | 查看或设置主分组 | | `@Bot 管理分组 加群 <名称> <群号或别名>` | 将受管群加入分组 | | `@Bot 管理分组 移群 <群号或别名>` | 将受管群移回默认分组 | | `@Bot 管理分组 删除 <名称>` | 删除空的非默认、非主分组 | ## 命令参考 | 分类 | 典型格式 | 说明 | | --- | --- | --- | | 成员管理 | `禁言 [更多目标] [分钟]`
`踢 [更多目标]`
`设管/撤管 ` | 禁言和踢人支持批量；设管/撤管要求操作者与 Bot 均具有相应权限 | | 违规处理 | `撤回 <数量>`
`撤回 [更多目标] <每人数量>`
`警告/违规/撤警 ...` | 支持按回复、数量或成员撤回，并维护未撤销警告 | | 黑名单 | `拉黑 [原因]`
`解黑 [分组] `
`黑名单 [分组] [数量]` | 管理群和私聊拉黑默认作用于主分组，受管群内拉黑作用于该群所属分组；清空黑名单仅 Bot 所有者可用 | | 内容策略 | `违禁词 [+\|- <词>]`
`白名单 [+\|- ]`
`全局违禁词/全局同步 [分组] ...` | 单群策略与分组策略分开维护 | | 问答系统 | `问答 [列表\|加\|改\|改问\|改答\|删\|权限 ...]`
`全局问答 [分组] ...` | 支持精确、模糊和正则匹配，以及图文混排答案 | | 群聊控制 | `锁群 <分钟>` / `解锁群`
`欢迎 [文本\|开\|关\|继承]`
`头衔申请 ...` / `申请头衔 <头衔>`
`风控强度 ...` | 包含单群配置及对应的分组级全局命令 | | 入群验证 | `入群验证 [群聊 [分钟]\|私聊 [分钟]\|关\|重入 允许\|拒绝]`
`验证题 <群号或别名> ...` | 支持群聊或私聊答题、重入策略和自定义题库 | | 数据查询 | `状态` / `运行状态`
`成员 [未发言天数]`
`发言 [数量]`
`设置`
`审计 [数量\|操作编号]` | 查看群状态、成员活跃度、近期发言、当前配置和审计记录 | | 数据维护 | `清理 [未发言天数] [最高等级]`
`自动清理 [开 天数 等级\|关]`
`扫描` / `全扫 [分组]`
`分析/导出 <时间范围>` | 清理先预览后确认；分析和导出基于已归档消息 | | 全局管理 | `全局统计 [分组]`
`群组`
`群别名 ...`
`管理分组 ...`
`超管 ...`
`屏蔽对象 ...` | 用于跨群查询、分组和全局权限维护 | | 系统运维 | `配置 ...`
`管理后台`
`更新插件` / `重启插件` | 配置与服务重启仅 Bot 所有者可操作；管理后台向管理及以上权限或 Codex 通知授权用户开放；只有通知授权的成员只能使用个人通知页面 | `发言` 仅查询目标群已归档且未撤回的消息，以合并转发发送。默认返回最近 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 所有者可在专用管理群或好友私聊中维护群聊、插件和业务配置： ```text @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 插件手册](../maa_download/README.md)。 新群聊默认关闭。开启群聊后，管理套件和管理召唤默认启用，PRTS 难度、MAA 下载、截止提醒和猜干员默认关闭。关闭群聊会停用全部插件，并保留各插件的选择状态。 修改群聊开关、插件开关或运行时设置后，需要发送 `@Bot 确认`。运行时设置保存在主数据库中，并覆盖对应环境变量的默认值。如果收到“配置已保存，但应用失败”，已保存的值会保留；可重发原配置命令并确认，或在管理后台重新保存以重试。 ### 环境变量 | 配置 | 用途 | | --- | --- | | `MANAGEMENT_GROUP_ID` | 专用管理群群号 | | `OWNER_USER_ID` | 唯一 Bot 所有者 QQ 号 | | `SUPER_ADMIN_USER_IDS` | 初始超管 QQ 号数组；运行时数据库记录会与其合并 | | `MESSAGE_DATABASE_PATH` | 主数据库路径，默认 `data/qqbot_manager.sqlite3` | | `TIMEZONE` | 定时任务时区，默认 `Asia/Shanghai` | | `LLM_PROTOCOL`、`LLM_API_KEY`、`LLM_BASE_URL`、`LLM_MODEL` | 消息分析默认连接；协议支持 `chat`（默认）、`responses`、`messages`，可在 Web 后台覆盖 | | `WEB_ADMIN_PUBLIC_URL`、`WEB_ADMIN_HOST`、`WEB_ADMIN_PORT` | 启用 Web 管理后台 | | `WEBSITE_*` | 网站通知、状态监控、个人排班与 MAA JSON、内测注册 | 可直接复制的部署模板和其他可选变量见根目录 [`.env.example`](../../.env.example)。Token、远程地址、数据目录、Bot 所有者账号和专用管理群等部署级配置不能通过运行时命令修改。 ### 数据存储与备份 | 数据 | 默认位置 | | --- | --- | | 群设置、分组、消息、违规、策略、验证、审计和任务状态 | `data/qqbot_manager.sqlite3` | | 消息导出 | `data/exports/` | | 分析报告 | `data/analysis_reports/` | | 问答图片 | `data/qa_images/` | | 更新诊断日志 | `data/update_logs/`，随主数据库目录移动，保留最近 10 次 | `DATA_RETENTION_CLEANUP_ENABLED` 控制新增的派生数据清理，默认关闭；原有消息保留期清理继续运行。确认下表期限及备份规则后，可在环境配置中设为 `true` 并重启服务。清理每天执行一次，失败后退避重试。 | 数据 | 默认保留期 | 起算与处理规则 | | --- | --- | --- | | 消息导出 CSV、分析 Markdown 和分页 PNG | `EXPORT_REPORT_RETENTION_DAYS=30` 天 | 文件名中的生成时间和最后修改时间都超过期限时删除 | | 主数据库中的分析报告 | 同上，30 天 | 按报告创建时间清理，与所分析消息的时间范围无关 | | 已完成的 Codex / Pi 通知正文和投递明细 | `CODEX_NOTIFY_CONTENT_RETENTION_DAYS=7` 天 | 所有目标群都已发送或取消后开始计时 | | 已完成通知的接收去重键 | `CODEX_NOTIFY_DEDUP_RETENTION_DAYS=30` 天 | 与正文使用同一完成时间；不得短于正文保留期 | | 仍有待投递目标的通知 | 持续保留 | 正文、去重键和各群投递状态均保留，继续按原约定重试 | 文件清理仅检查导出、报告目录的第一层，匹配 Bot 生成的 `messages_*.csv`、`analysis_*.md` 和 `analysis_*.png` 文件名；其他文件、子目录和符号链接均保留。恢复后最近修改过的文件也会保留完整期限。SQLite 删除后的空闲页会被后续写入复用，数据库文件体积不会立即缩小。 启用或缩短保留期限前，由运维使用 SQLite 在线备份或停机备份主数据库及 `CODEX_NOTIFY_DATABASE_PATH`，并保存问答图片、需长期保留的导出和报告、实际环境配置。备份放在清理目录之外，使用独立保留期，并验证可恢复。程序按上述期限清理运行数据，备份由现有运维流程管理。运行账号必须对所配置的数据目录具有读写权限。 旧版本群聊开关的迁移规则见[根 README 的升级说明](../../README.md#从旧版本升级)。 ## Web 管理后台 Web 后台的启用方式、一次性链接和权限模型见[根 README](../../README.md#web-管理后台)。在后台可以： - 查看群聊状态、调整群设置和管理成员； - 维护单群与分组问答； - 查看插件状态、运行状态和配置； - 由 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 排版会保留。图片渲染失败时自动改用文字发送。 最小配置： ```dotenv WEBSITE_NOTIFICATIONS_ENABLED=true WEBSITE_EVENTS_URL=https://example.com/api/integrations/qqbot/events WEBSITE_EVENTS_TOKEN= WEBSITE_NOTIFICATION_GROUP_IDS=[200000003] ``` 远程地址必须使用 HTTPS，网站通知目标群不能包含专用管理群。省略 `WEBSITE_STATUS_URL` 时，Bot 使用事件接口同源的 `/api/status`。 在同一网站通知配置中增加独立的 `WEBSITE_QQBOT_TOKEN`，即可为这些通知群的当前成员 提供个人排班通知和 MAA JSON 私聊下载。共用网站通知的开关、目标群和网站地址； 关闭网站通知会同时停止个人推送。未配置个人 Token 时，群公告和状态监控继续可用。 成员先添加 Bot 为好友，发送 `绑定网站 <绑定码>` 和 `开启排班通知`； 发送 `帮助 网站排班` 查看账号、结果查询、下载和解绑用法。成员退出通知群后停止个人 推送，自动导出不扣券，手动用券下载需先确认消耗 1 张券。 网站内测注册可独立启用，但仍需要 `WEBSITE_EVENTS_TOKEN`： ```dotenv 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](../../WEBSITE_INTEGRATION.md)。 ### 确认与审计 高风险命令需要二次确认： 1. Bot 显示操作预览，并保留 120 秒。 2. 操作者在同一会话中发送 `@Bot 确认`。 3. Bot 重新校验操作者权限和目标状态，再执行操作。 清理成员、自动清理设置、设管/撤管、全局锁群、黑名单变更、超管变更、群别名与响应屏蔽对象变更、入群验证设置，以及群聊、插件和运行时配置修改都需要确认。请按 Bot 返回的确认提示操作。 超过 120 秒后，待确认操作失效；同一会话中的新高风险命令会覆盖旧操作。所有已识别命令都会记录操作编号、操作者、执行时采用的角色、目标和结果。审计不会保存密钥、验证答案、完整违规正文或服务器绝对路径。 ## 排查指南 | 现象 | 可能原因 | 检查步骤 | | --- | --- | --- | | 命令无响应 | 群聊未开启、管理套件已关闭、未提及 Bot 或权限不足 | 由 Bot 所有者使用 `配置 群聊` 和 `配置 插件` 查看状态；确认群消息提及或回复 Bot，再使用 `@Bot 帮助` 检查可用命令 | | `设管` / `撤管` 不可见或不可用 | 操作者不是群主，或 Bot 不是目标群群主 | 在 QQ 群成员列表中确认双方角色；角色变更后重新请求帮助 | | 撤回、禁言或踢人失败 | Bot 平台权限不足，或 Milky API 调用失败 | 确认 Bot 是目标群管理员或群主，并检查 Milky 服务日志和连接状态 | | 私聊验证失败 | 新人无法发起好友私聊或群临时会话 | 使用测试账号验证两种私聊入口，并确认 Bot 在目标群具有管理权限 | | 消息分析不可用 | 协议、模型地址、模型名、密钥或网络配置错误 | 检查后台“AI 分析连接”（未保存时使用 `LLM_*` 环境变量）和 Bot 运行环境的网络访问 | | 报告中文缺字 | 字体资源缺失，或尚未更新字体修复版本 | 更新插件并保留项目 `plugins/bot_core/resources/fonts/` 中的自带中文字体，也可通过 `ANALYSIS_REPORT_FONT_PATH` 指定中文字体 | | 无法获取 Web 后台链接 | 后台未配置，或 Bot 无法向操作者发起私聊 | 检查 `WEB_ADMIN_*` 配置；先添加 Bot 好友，再私聊发送 `管理后台` | | 网站通知失败 | HTTPS、Token、接口契约或目标群配置错误 | 检查 `WEBSITE_*` 配置和网站接口日志，并按集成文档验证事件接口 | ## 相关文档 - [QQ Bot Manager 主文档](../../README.md)：安装、入口、权限和部署概览。 - [公开发布与部署](../../DEPLOYMENT.md)：systemd、反向代理、发布和回滚。 - [网站事件接口](../../WEBSITE_INTEGRATION.md)：网站通知、状态和内测注册协议。 - [请求管理](../request_manager/README.md)：好友请求与 Bot 入群邀请策略。 # 管理召唤 受管群成员可以提及 Bot 呼叫管理员。`call_admin` 会把说明和原消息序号以纯文字转发到专用管理群。 ## 快速使用 Bot 所有者先开启目标群聊和「管理召唤」插件。群聊与插件开关的用法见[主文档的运行时命令](../../README.md#运行时命令)。 在已启用插件的群聊中提及或回复 Bot，并让关键词位于消息开头： ```text @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 后台“运行时配置 → 管理召唤匹配规则”查看并编辑关键词和全部冲突提示正则。每行填写一个关键词或一条正则，分别保存后立即生效，重启后保留。固定命令 `呼叫管理` 始终显示；完整关键词匹配表达式可展开查看，会随关键词自动更新。 也可在专用管理群或好友私聊中调整配置： ```text 配置 查看 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 ``` | 配置键 | 默认值 | 约束 | | --- | --- | --- | | `call_admin.call_admin_keywords` | `管理,举报,召唤管理,呼叫管理` | 1 至 20 个字面关键词，使用逗号分隔，每个不超过 20 字；不作为正则执行 | | `call_admin.call_admin_cooldown_seconds` | `60` | 1 至 3600 秒 | | `call_admin.call_admin_reminder_patterns` | 内置 4 条冲突提示正则 | 最多 20 条，每条 1 至 500 字；使用 JSON 字符串数组或每行一条，`[]` 关闭冲突语句提示 | 运行时配置保存在管理 SQLite 中，修改后立即生效。提示正则从消息开头匹配，可在末尾使用 `$` 限定整条消息；每条必须是单行表达式，实际换行用 `\n` 表示。保存前校验语法，自定义正则在独立进程中执行，单次匹配（含排队与启动）限时 250 毫秒；超时跳过本次冲突提示并记录日志。修改这些正则不改变正式召唤关键词和提示退避。 升级会保留已保存的关键词；即使旧配置中仍含 `来人`，它也不会触发用法提示，可用上述设置或重置命令移除。通用配置命令和确认流程见[管理套件文档](../manager_suite/README.md#运行时配置)。 ### 环境变量 | 变量名 | 默认值 | 说明 | | --- | --- | --- | | `CALL_ADMIN_KEYWORDS` | `["管理","举报","召唤管理","呼叫管理"]` | 首次启动使用的字面关键词集合 | | `CALL_ADMIN_COOLDOWN_SECONDS` | `60` | 首次启动使用的冷却秒数 | | `CALL_ADMIN_REMINDER_PATTERNS` | 内置冲突提示正则 | JSON 字符串数组；建议通过 Web 后台编辑 | | `MANAGEMENT_GROUP_ID` | 无 | 接收转发的专用管理群 | | `TIMEZONE` | `Asia/Shanghai` | 转发时间使用的时区 | 完整环境变量格式见 [`.env.example`](../../.env.example)。运行时值存在时，会覆盖对应的环境变量默认值。 ## 安全与隐私 - 专用管理群应只保留确有管理职责的成员。 - 举报说明可能包含成员账号、聊天上下文或其他敏感信息，应按社群隐私规则处理。 - 消息序号用于管理员回到原群定位现场；插件不会自动裁决或处罚被举报成员。 ## 排查指南 | 现象 | 可能原因 | 检查步骤 | | --- | --- | --- | | 发送关键词后无响应 | 插件未开启；关键词不在开头；未提及 Bot 且提示仍在退避 | 检查插件开关，并使用 `@Bot 呼叫管理 <说明>` 测试 | | 正式召唤提示仍在冷却 | 同一群成员刚完成过一次转发 | 等待提示中的剩余时间；必要时由 Bot 所有者在 Web 后台清理正式召唤冷却 | | 未提及 Bot 时没有再次提示 | 同群提示正处于退避间隔 | 按固定格式提及 Bot 正式呼叫管理员，无需等待提示恢复 | | 转发失败 | Bot 无法在管理群发言或 Milky 连接异常 | 检查 Bot 的管理群发言权限和连接日志 | | 普通文字误触发 | 关键词或提示正则过于宽泛 | 在 Web 后台调整关键词与冲突提示正则 | | 自定义冲突语句未提示 | 正则不匹配、提示退避中或正则执行超时 | 核对消息开头和正则边界，并查看是否有匹配超时日志 | ## 相关文档 - [项目主文档](../../README.md)：通用入口、权限体系和插件开关。 - [管理套件](../manager_suite/README.md)：运行时配置、Web 后台和操作审计。 # PRTS Plus 难度查询 `prts_difficulty` 根据 PRTS Plus 作业估计关卡难度，提供低配要求、活动排行和干员统计，帮助群成员比较关卡、选择阵容。群成员可以查询，超管负责维护同步任务。 ## 快速使用 Bot 所有者先开启目标群聊和「PRTS 难度」插件。插件默认关闭，开关用法见[主文档的运行时命令](../../README.md#运行时命令)。 群成员在已启用插件的群聊中提及或回复 Bot： ```text @Bot 关卡难度 TO-S-1 突袭 @Bot 难度排行 综合 主线 2 @Bot 干员统计 史尔特尔 综合 ``` Bot 所有者还可在好友私聊中直接执行查询或刷新命令。专用管理群不作为该插件的查询入口。 ## 命令参考 符号约定：`<必填>` 必须提供，`[可选]` 可以省略，`A|B` 表示任选其一。 | 命令格式 | 说明 | 权限 | | --- | --- | --- | | `关卡难度 <关卡> [综合\|普通\|突袭]` | 查看关卡难度、低配要求和常用干员 | 群成员 | | `活动难度排行 [页码]` | 查看活动难度排行 | 群成员 | | `难度排行 [综合\|普通\|突袭] [分类] [页码]` | 查看关卡难度排行 | 群成员 | | `低配排行 [综合\|普通\|突袭] [分类] [页码]` | 查看关卡低配排行 | 群成员 | | `干员排行 [出场\|关联] [综合\|普通\|突袭] [分类] [页码]` | 查看干员出场率或难度关联排行 | 群成员 | | `干员统计 <干员名> [综合\|普通\|突袭] [分类]` | 查看指定干员的出场与难度关系 | 群成员 | | `作业数据状态` | 查看刷新阶段、进度和错误摘要 | 群成员 | | `刷新作业数据` | 强制启动后台刷新 | 超管及以上 | 参数命令支持省略命令词后的第一个空格，例如 `关卡难度TO-S-1` 与 `关卡难度 TO-S-1` 等价。无参数命令必须完整匹配；`作业数据状态123` 不会触发。 查询关卡时，可填写内部 ID、标准代号或名称。匹配到多个关卡时，Bot 最多返回 5 个候选，建议改用标准代号。排行每页显示 10 条；分类可使用关卡目录中的一级、二级或三级分类。 ## 查询结果 关卡结果包含： - 难度分、低配难度和难度百分位； - 作业数量、数据参考度和代表作业； - 养成、获取、操作三项要求及等效理智成本； - 常用干员的出场率和难度差。 难度分范围为 0 至 100，分数越高，阵容与操作要求越高。数据待补充时显示暂定结果及待确认项目。危机合约等可变难度模式显示作业数量和待补充的挑战条件。 活动排行展示各活动的难度、低配难度和关卡数量。干员排行可选择出场率或难度关联；干员统计展示出场比例、难度差和平均阵容要求。 评分公式、数据来源与计算规则见 [评分模型](SCORING.md)。 ## 配置 ### 运行时配置 | 配置键 | 默认值 | 说明 | | --- | --- | --- | | `prts.prts_refresh_time` | `04:30` | 每日后台刷新时间，使用 `HH:MM` | | `prts.prts_stale_hours` | `36` | 快照超过该时长后视为过期 | Bot 所有者可使用 `配置 查看 prts`、`配置 设置 <模块.键> <值>` 和 `配置 重置 <模块.键>` 维护这些值。 ### 环境变量 | 变量名 | 默认值 | 说明 | | --- | --- | --- | | `PRTS_DIFFICULTY_DATABASE_PATH` | `data/prts_difficulty.sqlite3` | 快照、详情缓存和刷新状态数据库 | | `PRTS_API_BASE_URL` | `https://prts.maa.plus` | PRTS Plus API 根地址 | | `PRTS_REFRESH_TIME` | `04:30` | 首次启动使用的每日刷新时间 | | `PRTS_STALE_HOURS` | `36` | 首次启动使用的快照过期小时数 | | `PRTS_REQUEST_TIMEOUT_SECONDS` | `15` | 单次请求超时（秒） | | `PRTS_REQUEST_RETRIES` | `3` | 请求重试次数 | | `PRTS_PAGE_SIZE` | `50` | 摘要分页大小，最大 50 | | `PRTS_DETAIL_REQUESTS_PER_SECOND` | `2` | 详情请求速率上限 | | `TIMEZONE` | `Asia/Shanghai` | 刷新时间和结果时间使用的时区 | 干员元数据、持有/培养统计和实装时间来源也可以通过 `PRTS_OPERATOR_*_URL` 调整。远程地址必须使用 HTTPS，只有本机联调地址可以使用 HTTP；地址不得包含用户名或密码。完整配置见 [`.env.example`](../../.env.example)。 ## 刷新与数据 - 插件在没有可用快照、快照过期或到达每日刷新时间时启动后台更新。 - 同一时间只运行一个刷新任务；重复刷新会直接提示正在运行。 - 查询只使用完整生成的快照，刷新失败时会保留上一份可用数据。 - `作业数据状态` 会显示摘要分页、详情处理、关卡汇总、完成时间和最近错误。 - 数据库保存活动快照、详情缓存、刷新进度和干员观测。 - 下载的干员元数据和统计缓存位于数据库同目录；来源暂时不可用时优先复用本地缓存或仓库内置数据。 ## 排查指南 | 现象 | 可能原因 | 检查步骤 | | --- | --- | --- | | 群内命令无响应 | 插件未开启；未提及 Bot | 检查群聊与插件开关，并使用 `@Bot 作业数据状态` 测试 | | 暂无可用快照 | 首次刷新尚未完成或已失败 | 查看 `作业数据状态`；由超管执行 `刷新作业数据` | | 刷新失败 | 上游、网络、URL 或超时异常 | 查看最近错误，核对 HTTPS 地址、网络和超时配置 | | 关卡无法匹配 | 名称过短、别名不唯一或该模式无作业 | 使用标准代号、完整名称，或切换为综合模式 | | 排行没有结果 | 模式或分类筛选过窄 | 减少筛选条件，并确认分类名称与关卡目录一致 | | 干员显示样本不足 | 有效作业或关卡覆盖不足 | 扩大模式/分类范围，等待后续更新收录更多作业 | ## 相关文档 - [项目主文档](../../README.md)：插件开关、命令入口和权限体系。 - [管理套件](../manager_suite/README.md)：运行时配置与 Web 管理后台。 # 方舟刷图 活动开始后，在群内问 `@Bot 这次刷什么`；缺材料时问 `@Bot 去哪刷 固源岩组`。Bot 返回刷图推荐图片，分开展示当前活动和常驻关卡，包括推荐关卡、掉落材料、单件理智消耗和活动截止时间。 ## 启用与命令 插件默认关闭。在 Web 后台的插件应用中为目标群开启“方舟刷图”，也可由所有者发送 `配置 插件 <群号> 方舟刷图 开`。普通群成员均可查询；默认须提及或回复 Bot，开启下述正则模式后可直接发送问法。暂不提供私聊入口。 | 命令 | 用途 | | --- | --- | | `这次刷什么` | 查看当前活动的蓝色精英材料推荐，并提供相同材料的常驻对照；无活动时显示常见材料速查 | | `活动刷图` | `这次刷什么`的别名，默认模式无参数、完整匹配 | | `去哪刷 <材料名>` | 查询指定精英材料，活动和常驻分别最多显示三个关卡 | | `材料掉落 <材料名>` | `去哪刷`的别名 | | `帮助 方舟刷图` | 查看命令帮助 | 参数支持省略第一个空格，例如 `去哪刷固源岩组`、`材料掉落固源岩组`。完整名称优先，也接受企鹅物流的中文别名、材料 ID 和无歧义的部分名称；匹配多个材料时会提示完整名称。 图片使用游戏内材料图标，突出关卡代号和单件理智，下方展示单次消耗与统计样本次数。活动卡片直接列出同种材料最省理智的常驻关卡、单件成本和节省或多耗的比例。单件理智越低，刷取该材料越省。活动样本不足时显示“收集中”；没有直接掉落数据的材料会提示查看合成或兑换途径。图标暂时不可用时保留文字卡片，整图渲染失败时返回文字。 ## 正则匹配模式 所有者可在 Web 后台“运行时配置”修改以下配置，也可在管理会话发送： ```text 配置 设置 farming.arknights_farming_regex_enabled 开 ``` 确认保存后立即生效，并覆盖所有已启用“方舟刷图”的群。此时无需 `@Bot`，相关查询全部按配置的正则规则匹配；关闭后恢复默认命令与提及要求。默认规则支持： - `这次活动刷哪关`、`本次活动刷什么？`、`当前活动推荐刷哪个关卡`、`这次刷什么`、`活动刷图`。 - `去哪刷固源岩组`、`去哪刷 固源岩组`、`材料掉落固源岩组`。 - `固源岩组去哪刷？`、`固源岩组在哪里刷`、`固源岩组怎么刷`。 | 配置项（模块 `farming`） | 默认值与用途 | | --- | --- | | `arknights_farming_regex_enabled` | `关`，开启后免提及并使用正则匹配 | | `arknights_farming_overview_patterns` | 内置活动问法正则列表，匹配后返回活动概览 | | `arknights_farming_material_patterns` | 内置材料问法正则列表，每条须包含 `(?P...)` 命名组，用于提取材料名 | 两类列表各自支持每行一条正则或 JSON 数组，最多 20 条，每条最多 500 字。保存时检查语法；列表替换该类默认规则，`[]` 停用该类匹配，重置配置恢复默认。规则使用 Python `re.fullmatch` 匹配整条去除首尾空白的消息，活动规则优先。普通文字如“今天刷完了”、`活动刷图排行`、`状态123` 不会命中默认规则。 自定义示例（管理会话仍按原有要求提及 Bot）： ```text 配置 设置 farming.arknights_farming_overview_patterns ["(?:这次|本次)活动刷哪关[？?]*"] 配置 设置 farming.arknights_farming_material_patterns ["(?P.+?)刷哪里[？?]*"] ``` 自定义材料规则下，`固源岩组刷哪里` 会查询固源岩组。请保留所需的原命令正则，否则被替换的命令将不再触发。正则模式仍遵守群聊、插件开关和响应屏蔽；不扫描私聊，超过 256 字的消息不匹配。自定义表达式在隔离进程中执行，匹配超时或进程不可用时跳过该条消息。 ## 数据与推荐口径 - 数据源：[企鹅物流数据统计](https://penguin-stats.io/)，使用公开 API 的国服物品、区域、关卡和掉落矩阵。排版参考[明日方舟一图流](https://ark.yituliu.cn/)，图片由本插件独立渲染。 - 按目标材料的直接掉落计算：单件理智 = 关卡理智消耗 × 样本次数 ÷ 材料掉落数量。图片只展示单件成本、单次消耗和样本次数，文字降级中的每次平均掉落为数量期望，不是“至少掉落一件”的概率。 - 至少 100 个样本才参与排序；统计周期须在当前时间内，同一关卡和材料保留最新的有效周期。不累计已经结束的活动加成数据。 - 当前活动必须在国服开放时间内，且关卡与区域均开放。常驻包括主线、支线和已常驻的插曲／别传；活动原版、复刻和常驻版分别使用各自的掉落统计。排除磨难关卡重复统计、抽奖箱及理智消耗为零的条目。 - 活动概览按每关主要蓝色材料选出各材料最省理智的关卡，最多八种材料。材料查询包含有效统计中的直接掉落。新活动尚未收录材料或统计时明确提示，不推测掉率。活动开放以数据源收录为准。 - 排序只比较目标材料的直接获取成本，不计算副产物总价值、合成链、活动商店与代币收益，也不读取个人库存；有明确缺口时优先查询该材料。高阶材料可能更适合合成。 - 数据按需获取，在进程内缓存 30 分钟。刷新失败最多使用 24 小时内的缓存并标注；活动时间仍按查询时刻重新核对。失败后一分钟内不重复请求，无可用缓存时返回错误。重启后重新获取，无后台轮询。 游戏材料图标随插件打包，来源为企鹅物流的游戏物品图集，按同一快照的 `itemId` 与 `spriteCoord` 裁切。2026-10-27 的图集包含 61 种材料，渲染无需请求图片服务器；素材来源和维护方式见 [resources/README.md](./resources/README.md)。遇到尚未打包的新材料时显示“图标缺失”，保留材料名与查询结果，不使用其他图标替代。 无需新增依赖、账号或数据库表。外部请求仅用于公开掉落数据，首次查询需等待数据加载。 验证命令： ```bash 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 下载」插件。插件默认关闭，开关用法见[主文档的运行时命令](../../README.md#运行时命令)。 群成员在已启用插件的群聊中提及或回复 Bot： ```text @Bot MAA版本 稳定 @Bot MAA下载 公测 linux-x64 @Bot MAA下载 资源 @Bot MAA镜像状态 ``` `MAA下载` 省略参数时返回稳定版 Windows x64 安装包。镜像链接来自第三方服务，可能随时失效。 ## 命令参考 | 命令格式 | 说明 | 权限 | | --- | --- | --- | | `MAA版本 [稳定\|公测\|内测]` | 查看版本、发布时间和更新内容；默认稳定版 | 稳定/公测：群成员；内测：管理及以上 | | `MAA下载 [稳定\|公测\|内测\|资源] [平台]` | 检测镜像并返回安装包或资源源码 ZIP 链接；资源不带平台参数 | 稳定/公测/资源：群成员；内测：管理及以上 | | `MAA镜像状态` | 强制刷新稳定版 Windows x64 的目录和节点状态 | 群成员 | | `MAA上传测试 [正式\|公测\|资源\|全部] [覆盖]` | 先确认来源群上传成功，再用其文件链接上传其余群，结果按文件汇总；默认全部，加“覆盖”先删除同名文件再上传 | Bot 所有者 | | `MAA上传状态` | 查看运行阶段、镜像节点、下载进度、目标群、耗时和最近结果 | Bot 所有者 | 参数命令支持省略命令词后的第一个空格，例如 `MAA版本稳定` 与 `MAA版本 稳定` 等价，`MAA上传测试资源 覆盖` 与 `MAA上传测试 资源 覆盖` 等价；`MAA上传测试覆盖` 覆盖全部类型。文件类型与 `覆盖` 之间仍需空格。无参数的 `MAA镜像状态` 和 `MAA上传状态` 必须完整匹配，`MAA镜像状态123`、`MAA上传状态123` 不会触发。 可用平台： | 参数 | 安装包 | | --- | --- | | `win-x64` | Windows x64 | | `win-arm64` | Windows ARM64 | | `macos` | macOS 通用版 | | `linux-x64` | Linux x64 AppImage | | `linux-x64-tar` | Linux x64 压缩包 | | `linux-arm64` | Linux ARM64 AppImage | | `linux-arm64-tar` | Linux ARM64 压缩包 | 通道也接受 `稳定版`、`正式版`、`beta`、`alpha` 等内置别名；日常使用时，建议填写 `稳定`、`公测`、`内测`。 发送 `MAA下载 资源`、`MAA下载资源` 或 `MAA下载 资源包` 可获取最新自动资源更新提交对应的 MaaResource 源码 ZIP 镜像链接。结果显示资源日期、提交 SHA 和文件名；获取活动信息后还会显示活动与资源更新时间，并给出按活动名命名的文件，例如 `资源包_[昨日海]#1009_8d949986.zip`。该 ZIP 不分平台，不接受额外平台参数，下载前大小可能未知。镜像的原始下载文件名可能仍是提交 SHA，可按结果中的文件名保存。 ## 自动上传群文件 Bot 所有者可在专用管理群发送以下命令，好友私聊省略 `@Bot`： ```text @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 需要能读取群文件、创建文件夹和上传文件；已有同名文件夹会直接使用。 部署环境仍可指定默认值，运行时配置优先于环境默认值： ```dotenv MAA_AUTO_UPLOAD_GROUP_IDS=[123456789,987654321] MAA_AUTO_UPLOAD_INTERVAL_SECONDS=900 ``` | 文件 | 群文件夹 | | --- | --- | | 正式版 Windows x64 安装包 | `MAA安装包-正式版（win-x64）` | | 公测版 Windows x64 安装包 | `MAA安装包-公测版（win-x64）` | | MaaResource 源码 ZIP | `MAA资源更新包` | 公测接口返回正式版时，会跳过公测版的下载和上传，正式版只上传到正式版文件夹。自动同步、手动测试和 `覆盖` 均遵循此规则；已有历史群文件保留。 Bot 上传的资源 ZIP 内顶层目录固定为 `MaaResource-main/`，解压后可直接找到 `MaaResource-main/resource/`。镜像直链仍返回上游原始 ZIP，目录名由提交 SHA 决定。 自动上传和手动测试使用相同顺序：每个文件在 Bot 下载、校验一次后，先向一个群上传，确认成功并取得文件 ID 后，再复用该群文件的下载链接上传其余群。首群明确失败时可尝试下一群建立来源；结果待确认时，会先核对该群的上传结果，暂停向其他群传二进制或文件路径。 Bot 与 Milky 能访问同一目录时，可在部署环境设置： ```dotenv 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`，按提示确认后生效： ```text @Bot 配置 设置 maa.maa_auto_upload_notify_management 开 @Bot 确认 ``` Web 后台「运行时配置 → 修改配置」使用相同配置项，值填 `开` 或 `关`。环境默认值为 `MAA_AUTO_UPLOAD_NOTIFY_MANAGEMENT=false`。 开启后，定时任务本轮下载和群文件投递结束时，向专用管理群发送简短通知，不提及管理员。相同文件版本和结果合并群号，保留全部目标群；不同文件、版本或结果分别显示。内容保留文件类型、安装包版本或资源活动名及日期和短 SHA、目标群和结果。例如： ```text MAA 定时上传结果： 群 123456789、987654321｜公测版 v6.20.0-beta.1：文件已存在 群 123456789、987654321｜资源包 [昨日海]#1009_8d949986：结果待确认 ``` 没有新文件、所有群已同步时不推送。上传结果待确认时先如实通知，后台核对后再补发最终结果，补发通知同样合并相同结果的群号；手动测试仍在原会话回复。通知发送失败会记录日志并重试，保留逐群通知记录，不改变上传结果。 ## 手动上传测试 Bot 所有者可在已开启 MAA 插件的受管群、专用管理群或好友私聊中触发测试；群内需提及或回复 Bot，私聊省略 `@Bot`： ```text @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](https://github.com/MaaAssistantArknights/MaaAssistantArknights/blob/ad3dc47efa16a3444377310e9061b4fe04e75b86/src/MaaWpfGui/ViewModels/UserControl/Settings/VersionUpdateSettingsUserControlModel.cs#L178) 一致，将 `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 资源测量记录](../../docs/maa_resource_benchmark.md)。 ## 环境变量 接收群、自动检查间隔和管理群通知开关支持运行时命令及 Web 后台配置。其他配置使用部署环境变量。 | 变量名 | 默认值 | 说明 | | --- | --- | --- | | `MAA_VERSION_API_BASE_URLS` | 官方 API + jsDelivr 备用 API | 按顺序尝试的版本 API 列表 | | `MAA_MIRROR_CATALOG_URLS` | XIU2 ScriptCat 脚本地址 | 按顺序尝试的镜像目录列表 | | `MAA_REQUEST_TIMEOUT_SECONDS` | `15` | 版本和目录请求超时（秒） | | `MAA_MIRROR_PROBE_TIMEOUT_SECONDS` | `10` | 单个镜像探测超时（秒） | | `MAA_VERSION_CACHE_SECONDS` | `300` | 版本结果缓存时间 | | `MAA_MIRROR_CATALOG_CACHE_SECONDS` | `3600` | 镜像目录缓存时间 | | `MAA_MIRROR_STATUS_CACHE_SECONDS` | `300` | 镜像探测结果缓存时间 | | `MAA_MIRROR_PROBE_CANDIDATES` | `8` | 每次抽样检测的节点数 | | `MAA_MIRROR_MAX_LINKS` | `3` | 单次最多返回的可用链接数 | | `MAA_AUTO_UPLOAD_GROUP_IDS` | `[]` | 自动接收文件的群号列表；仅向已启用 MAA 插件的群上传 | | `MAA_AUTO_UPLOAD_INTERVAL_SECONDS` | `900` | 自动检查间隔（秒），范围 60–86400 | | `MAA_AUTO_UPLOAD_NOTIFY_MANAGEMENT` | `false` | 定时上传结果推送到专用管理群，支持运行时开关 | | `MAA_AUTO_UPLOAD_DATABASE_PATH` | `data/maa_download.sqlite3` | 各群上传状态数据库，需持久保存 | | `MAA_UPLOAD_SHARED_DIRECTORY` | 未配置 | Bot 与 Milky 可用相同绝对路径访问的共享目录；配置后优先路径上传，Bot 需可写、Milky 需可读取所创建的临时文件 | | `MAA_RESOURCE_COMMITS_API_URLS` | GitHub MaaResource commits API | 按顺序尝试的资源提交 API 列表，需兼容 GitHub commits 响应和分页参数 | | `MAA_RESOURCE_VERSION_BASE_URLS` | jsDelivr CDN + Fastly jsDelivr 备用地址 | 活动元数据的 MaaResource 仓库 CDN 前缀；自动追加 `@SHA/resource/version.json`，不允许 GitHub 直连地址 | | `MAA_DOWNLOAD_TIMEOUT_SECONDS` | `300` | 完整文件下载的网络读写超时（秒） | | `MAA_DOWNLOAD_MAX_BYTES` | `1073741824` | 单文件最大下载大小（字节），默认 1 GiB | | `MAA_ZIP_MAX_FILES` | `100000` | ZIP 最大条目数，包含目录；正整数 | | `MAA_ZIP_MAX_FILE_BYTES` | `4294967296` | ZIP 单条目最大解压大小，默认 4 GiB；正整数 | | `MAA_ZIP_MAX_TOTAL_BYTES` | `8589934592` | ZIP 全部条目最大总解压大小，默认 8 GiB；正整数 | 版本 API、镜像目录、资源提交 API 和活动元数据 CDN 列表不能为空。所有配置地址必须使用 HTTPS，且不得包含凭据、查询参数或片段；资源提交 API 可以使用 GitHub，版本 API、镜像目录和活动元数据 CDN 不允许 GitHub 直连地址。最大返回链接数不能超过抽样候选数。完整格式见 [`.env.example`](../../.env.example)。 ## 排查指南 | 现象 | 可能原因 | 检查步骤 | | --- | --- | --- | | 群内命令无响应 | 插件未开启；未提及 Bot；命令拼写不完整 | 检查插件开关，并使用 `@Bot MAA版本` 测试 | | 内测命令提示权限不足 | 操作者不是目标群管理 | 由群管理员、群主、超管或 Bot 所有者执行 | | 版本查询失败 | 官方和备用 API 均不可用 | 检查网络、HTTPS 地址和请求超时配置 | | 没有可用镜像 | 目录失效或本次抽样节点不可达 | 稍后重试 `@Bot MAA镜像状态`，必要时更新镜像目录 | | Bot 显示可用但本地打不开 | Bot 与成员的网络路径不同 | 更换返回的其他节点，或使用 MAA 官方发布渠道 | | 配置启动失败 | URL 不安全或链接数大于候选数 | 按启动错误核对 URL 约束和两个数量参数 | | 群文件没有自动更新 | 群不在接收列表、插件未启用，或上传失败 | 使用 `MAA上传状态` 查看可用群、运行步骤和最近错误，再核对 Bot 群文件权限 | | 上传任务长时间运行 | 下载停滞，或群文件 API 尚未返回 | 使用 `MAA上传状态` 查看镜像节点、下载进度、当前群与阶段持续时间，结合日志定位 | | 上传响应异常，但文件稍后出现 | Milky 响应超时或中断后上传仍在继续 | 结果会先显示待确认；查询 `MAA上传状态` 或等待后台核对，确认后自动更新为成功 | | 资源提交请求失败 | GitHub API 不可达或限流 | 稍后重试，或配置可用的兼容资源提交 API | | 资源包沿用日期和 SHA 名称 | 活动元数据不可达或格式无效 | 下载和上传仍继续；检查 `MAA_RESOURCE_VERSION_BASE_URLS` 与活动元数据日志 | | 完整下载失败 | 文件过大、镜像响应损坏或连接超时 | 查看自动同步日志，核对下载及 ZIP 上限、下载超时和镜像状态 | | ZIP 超过资源上限 | 文件数、单文件或总解压大小超限 | 根据日志确认触发的上限，核对可信上游包后再调整相应 `MAA_ZIP_MAX_*` 配置 | | 临时文件读写失败 | 临时目录或共享目录空间不足、权限异常 | 检查系统临时目录和共享目录的空间及 Bot 写权限 | ## 相关文档 - [项目主文档](../../README.md)：插件开关、权限体系和部署方式。 - [管理套件](../manager_suite/README.md)：群聊与插件状态管理。 # 明日方舟截止提醒 `arknights_reminders` 从 PRTS Wiki 和明日方舟国服官网同步截止事项。发送「今日方舟」可一次查看近期事项；订阅分类后，Bot 会按所选时间发送提醒，事项由超管维护。 ## 快速使用 Bot 所有者先开启目标群聊和「截止提醒」插件。群聊与插件开关的完整用法见[主文档的运行时命令](../../README.md#运行时命令)。 成员命令只在已启用插件的群聊中响应，需要提及或回复 Bot： ```text @Bot 今日方舟 @Bot 提醒 分类 @Bot 提醒 订阅 寻访 活动商店 3天 1天 @Bot 提醒 我的 ``` 上例会持续订阅「寻访」和「活动商店」，并在截止前约 3 天、约 1 天提醒。省略档位时使用 `3天`、`1天`、`12小时`。提醒按大致提前时间安排，避开夜间，消息中会显示实际剩余时间。 超管及以上权限可在专用管理群或好友私聊中维护事项。在专用管理群中需要提及或回复 Bot；好友私聊无需提及。通用入口和权限定义见[主文档](../../README.md#命令入口)。 ## 命令参考 符号约定：`<必填>` 必须提供，`[可选]` 可以省略，`...` 表示可以提供多个值，`A|B` 表示任选其一。 ### 成员命令 | 命令格式 | 说明 | | --- | --- | | `今日方舟` | 用方舟风格长图汇总近期截止、商店轮换、周常提醒与常用查询入口，无参数 | | `提醒 列表 [分类] [页码]` | 查看有效事项，每页 10 条 | | `提醒 分类` | 查看所有可订阅分类 | | `提醒 订阅 <分类...\|全部> [档位...]` | 持续订阅一个、多个或全部分类 | | `提醒 取消订阅 <分类...\|全部>` | 取消对应分类的持续订阅 | | `提醒 我的` | 查看当前账号在本群的订阅和档位 | | `帮助 提醒` | 查看运行时帮助 | 可选档位为 `7天`、`3天`、`1天`、`12小时`、`3小时`、`1小时`。`全部` 不能与具体分类混用。 可订阅分类： | 类型 | 分类 | | --- | --- | | 活动 | 活动关卡、活动商店、奖励领取、限时物品 | | 寻访与商店 | 寻访、寻访交换所、免费寻访、限时售卖、黄票商店 | | 周期与人工事项 | 周常、月常、自定义 | 旧版的单事项订阅、忽略和恢复命令只会提示改用分类订阅，不再执行操作。 ### 今日方舟 在已开启「截止提醒」的群内发送 `@Bot 今日方舟`，普通成员即可查看： - 未来 7 天内的活动关卡、活动商店、寻访、奖励领取等截止事项，按截止时间排序。 - 标准、中坚黄票商店各自最近一次轮换，以及下次月常重置。PRTS 已同步进店干员时，显示对应干员名；尚未获取时显示轮换时间。 - 下次周常重置时间，提醒检查每周任务、剿灭报酬和可能过期的周期限理智药剂。 - 提醒列表与订阅入口；本群开启对应插件时，另显示 PRTS 难度、干员统计与 MAA 版本、下载命令。 专属长图使用深色工业网格、切角面板和黄青配色，顶部显示日期、近期截止数量及 24 小时内截止数量。24 小时内的事项用红色与文字共同标记，长标题自动换行，全部区块合成一张长图。常用查询以紧凑行表展示命令和说明，只在分区标题处提示一次使用方式。绘制失败时返回完整文字。图片由 Pillow 和项目自带中文字体在本地绘制。 每个区块最多显示 8 项，超出时提示查看完整列表。仅显示全群可见或属于当前群的有效事项，不受个人订阅影响。时间沿用 `TIMEZONE` 配置。 查询读取现有同步数据，不额外请求上游；暂无事项时会说明尚无已收录数据。此命令按需查询，不会新增每日推送或改变订阅。 ### 管理命令 | 命令格式 | 说明 | | --- | --- | | `提醒管理 候选 [页码]` | 查看待审候选 | | `提醒管理 候选 #<候选ID>` | 查看候选详情 | | `提醒管理 发布 <候选ID>` | 将候选发布为正式事项 | | `提醒管理 驳回 <候选ID>` | 驳回候选 | | `提醒管理 新建 <模板> <全部\|群号\|别名> \| <标题> \| <内容>` | 新建人工事项 | | `提醒管理 修改 <截止\|标题\|内容\|分类\|范围> <值>` | 修改事项 | | `提醒管理 暂停\|恢复 ` | 切换事项状态 | | `提醒管理 删除 ` | 删除事项及其尚未发送的提醒 | | `提醒管理 同步源 ` | 解除人工锁定，重新采用来源数据 | | `提醒管理 刷新 [全部\|PRTS\|官网]` | 启动指定来源的同步任务 | | `提醒管理 暂停拉取 [全部\|PRTS\|官网]` / `提醒管理 继续拉取 [全部\|PRTS\|官网]` | 仅 Bot 所有者可设置；省略来源时作用于全部来源，重启后保留设置；仍可手动刷新，检查来源是否恢复 | | `提醒管理 状态` | 查看来源、候选和投递状态 | | `提醒管理 确认` | 确认当前待执行的高风险操作 | 同一来源连续报错时，管理群在第三次失败后收到一次告警；来源恢复后再次故障会重新告警。暂停定时拉取不影响已有事项的提醒投递。 删除事项或提前截止时间时，Bot 会显示操作预览。原操作者须在 120 秒内发送 `提醒管理 确认`，操作才会执行。 Web 管理后台还会展示全部状态的事项和用户订阅。Bot 所有者可在全功能控制台中代成员维护订阅，后台入口与权限模型见[管理套件文档](../manager_suite/README.md#web-管理后台)。 ## 配置 ### 运行时配置 运行时配置保存在管理 SQLite 中，覆盖对应的环境变量默认值： | 配置键 | 默认值 | 说明 | | --- | --- | --- | | `arknights.arknights_reminder_refresh_interval_minutes` | `30` | 来源刷新间隔（分钟） | | `arknights.arknights_reminder_dispatch_interval_seconds` | `60` | 待投递扫描间隔（秒） | | `arknights.arknights_reminder_max_mentions_per_message` | `50` | 单条消息最多提及人数 | | `arknights.arknights_reminder_catchup_grace_minutes` | `360` | Bot 恢复后允许补发的时间范围（分钟） | Bot 所有者可通过 `配置 查看 arknights`、`配置 设置 <模块.键> <值>` 和 `配置 重置 <模块.键>` 维护这些值。 ### 环境变量 | 变量名 | 默认值 | 说明 | | --- | --- | --- | | `ARKNIGHTS_REMINDER_DATABASE_PATH` | `data/arknights_reminders.sqlite3` | 事项、订阅和投递记录数据库 | | `ARKNIGHTS_PRTS_API_URL` | PRTS Wiki API | PRTS 数据来源 | | `ARKNIGHTS_OFFICIAL_NEWS_URL` | 明日方舟官网新闻页 | 官网数据来源 | | `ARKNIGHTS_REMINDER_REQUEST_TIMEOUT_SECONDS` | `15` | 单次来源请求超时（秒） | | `ARKNIGHTS_REMINDER_REQUEST_RETRIES` | `3` | 来源请求重试次数 | | `TIMEZONE` | `Asia/Shanghai` | 截止时间、刷新和投递使用的时区 | 远程来源必须使用 HTTPS；只有本机联调地址可以使用 HTTP。其余可选变量和取值范围见 [`.env.example`](../../.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 无法读取玩家背包；「限时物品」只提醒成员自行检查库存和过期时间。 ## 排查指南 | 现象 | 可能原因 | 检查步骤 | | --- | --- | --- | | 群内命令无响应 | 群聊或插件未开启；未提及 Bot | 检查群聊与「截止提醒」插件开关，并确认消息提及或回复 Bot | | 没有收到订阅提醒 | 分类未订阅；成员已退群；事项已暂停 | 发送 `@Bot 提醒 我的`，再由超管检查事项状态 | | 来源刷新失败 | 网络、HTTPS 地址或上游异常 | 查看 `提醒管理 状态`，核对来源地址、超时和错误摘要 | | 重启后没有补发旧提醒 | 已超过补发宽限时间 | 检查 `arknights_reminder_catchup_grace_minutes`；过期档位不会补发 | | 修改后又被来源覆盖 | 事项已恢复自动同步 | 检查是否执行过 `同步源`，需要人工维护时重新修改事项 | ## 相关文档 - [项目主文档](../../README.md)：通用命令入口、权限、插件开关和部署方式。 - [管理套件](../manager_suite/README.md)：运行时配置、Web 管理后台、确认与审计。 # 猜干员 群成员可用 `operator_guess` 一起看立绘、技能图标猜干员，Bot 会记录本局成绩、连击和赛季积分。 ## 快速使用 Bot 所有者先开启目标群聊和「猜干员」插件。插件默认关闭，开关用法见[主文档的运行时命令](../../README.md#运行时命令)。 管理及以上权限可在已启用插件的群聊中提及或回复 Bot 开局： ```text @Bot 猜干员 @Bot 猜干员 困难立绘 @Bot 猜干员 技能 ``` 省略模式时，发起者需要在 60 秒内选择难度。游戏开始后，成员可直接发送干员名答题，或发送提示、跳题命令，无需提及 Bot。 ## 模式 | 模式 | 命令参数 | 赛季积分倍率 | 题面 | | --- | --- | --- | --- | | 普通立绘 | `初级`、`立绘` | 1 倍 | 局部立绘，提示会扩大视野 | | 困难立绘 | `困难`、`困难立绘` | 2 倍 | 更小的立绘视野 | | 极难立绘 | `极难`、`极难立绘` | 3 倍 | 4×4 碎片拼图，提示会恢复部分拼图并扩大视野 | | 噩梦立绘 | `噩梦`、`噩梦立绘` | 4 倍 | 随机使用错色、双色、勾线或色带效果 | | 技能 | `中级`、`技能` | 2 倍 | 技能图标与文字提示 | 语音和档案模式尚未开放；像素立绘模式当前禁用。 ## 命令参考 ### 开局与查询 | 命令格式 | 说明 | 权限 | | --- | --- | --- | | `猜干员 [模式]` | 直接开局，或省略模式进入难度选择 | 默认管理及以上；可按群开放给成员 | | `猜干员排行` | 查看本群当前赛季排行 | 群成员 | | `猜干员积分` | 查看自己的赛季积分 | 群成员 | | `猜干员状态` | 查看资源缓存、当前游戏和成员开局状态 | 群成员 | | `帮助 猜干员` | 查看运行时帮助 | 群成员 | 参数命令支持紧凑形式，例如 `猜干员困难立绘` 与 `猜干员 困难立绘` 等价。查询命令必须完整匹配。 ### 成员开局 群管理可设置是否允许本群普通成员发起游戏： ```text @Bot 猜干员成员开始 开启 @Bot 猜干员成员开始 关闭 ``` 开启后，普通成员在每个群聊每 30 分钟可发起一次游戏。冷却从发送开局命令时开始，开局失败、游戏时长或开关切换都不会重置冷却；管理发起游戏不占用该冷却。 ### 干员别名 | 命令格式 | 说明 | 权限 | | --- | --- | --- | | `猜干员别名 查看 <干员名>` | 查看内置和自定义别名 | 群成员 | | `猜干员别名 添加 <干员名> <别名1> [别名2 ...]` | 添加全局共享的自定义别名 | 管理及以上 | | `猜干员别名 删除 <别名>` | 删除自定义别名 | 管理及以上 | 别名不能覆盖正式干员名、内置别名或局内操作词。自定义别名由所有启用猜干员的群聊共享。 ## 游戏与计分规则 - 每局默认 30 题；每题默认 60 秒。题目超时会结束整局游戏。 - 每题默认允许 10 次有效错误。错误答案需能识别为干员，才会计入次数；同一成员在本题重复提交同一个错误答案不重复计数。 - 发送 `提示` 或 `不知道` 获取提示；普通提示使本题和最终结算倍率降低 2%，技能模式最后一次四选一提示降低 10%。 - 发送 `下一题`、`放弃` 或 `跳过` 会揭晓答案并使最终结算倍率降低 5%；错误机会耗尽也降低 5%。倍率最低为 50%。 - 正确答案获得本局分数和赛季积分；连续答对会增加连击奖励，其他成员答对或本人答错可能中断连击。 - 同一批到达的答案按消息时间和消息序号排序，只结算第一条有效正确答案。 - 本局排名按分数档位计算，允许并列。默认至少完成 15 题后，前三个分数档才获得名次积分。 - 名次积分以 `30/20/10` 为基础，并按模式倍率、完成进度和提示/跳题惩罚调整。 - 管理及以上权限可在难度选择或游戏中直接发送 `结束` 或 `不玩了` 终止游戏。 赛季默认按 `TIMEZONE` 指定时区的自然月切换，也可设置固定的赛季标识和名称。 ## 配置 ### 运行时配置 | 配置键 | 默认值 | 说明 | | --- | --- | --- | | `operator_guess.operator_guess_questions` | `30` | 每局题目数 | | `operator_guess.operator_guess_finish_min` | `15` | 发放名次积分所需的最低完成题数 | | `operator_guess.operator_guess_answer_limit` | `10` | 每题有效错误上限 | | `operator_guess.operator_guess_question_timeout_seconds` | `60` | 单题超时（秒） | | `operator_guess.operator_guess_selection_timeout_seconds` | `60` | 难度选择超时（秒） | | `operator_guess.operator_guess_season_key` | 空 | 固定赛季标识，`-` 表示恢复自动赛季 | | `operator_guess.operator_guess_season_name` | 空 | 固定赛季名称；设置时必须同时设置赛季标识 | Bot 所有者可使用 `配置 查看 operator_guess`、`配置 设置 <模块.键> <值>` 和 `配置 重置 <模块.键>` 维护这些值。`operator_guess_finish_min` 不能大于题目数。 ### 环境变量 | 变量名 | 默认值 | 说明 | | --- | --- | --- | | `OPERATOR_GUESS_DATABASE_PATH` | `data/operator_guess.sqlite3` | 游戏、积分、别名和群设置数据库 | | `OPERATOR_GUESS_CACHE_DIRECTORY` | `data/operator_guess_cache` | 立绘、技能图标和元数据缓存目录 | | `OPERATOR_GUESS_RESOURCE_STALE_HOURS` | `24` | 资源缓存过期时间 | | `OPERATOR_GUESS_REQUEST_TIMEOUT_SECONDS` | `20` | 资源请求超时（秒） | | `OPERATOR_GUESS_REQUEST_RETRIES` | `2` | 资源请求重试次数 | | `OPERATOR_GUESS_ASSET_CACHE_CONCURRENCY` | `8` | 缓存资源的并发数 | | `OPERATOR_GUESS_CACHE_MIN_FREE_BYTES` | `1073741824` | 缓存时要求保留的最小磁盘空间 | | `OPERATOR_GUESS_HTTP_PROXY` | 空 | 资源请求使用的 HTTP(S) 代理 | | `OPERATOR_GUESS_MAX_IMAGE_BYTES` | `15728640` | 单张图片最大字节数 | | `OPERATOR_GUESS_MAX_IMAGE_PIXELS` | `16000000` | 单张图片最大像素数 | | `TIMEZONE` | `Asia/Shanghai` | 赛季和时间显示使用的时区 | 远程资源地址、题目准备、批处理窗口和缓存重试等高级变量见 [`.env.example`](../../.env.example)。远程资源必须使用 HTTPS，本机联调地址除外。 ## 资源与限制 - 插件启动后会缓存全部可用立绘和技能图标；缓存尚未就绪时不能开局，可用 `@Bot 猜干员状态` 查看进度。 - 上游存在多个同名角色时，插件只保留题型和资源更完整的一条，避免提高该名称的出题概率。 - HTTP(S) 代理凭据只应存放在受限的环境文件中，不要写入文档、日志或源码。 - 仓库不提交游戏素材；部署和使用时应遵守上游声明及素材权利要求。 ## 排查指南 | 现象 | 可能原因 | 检查步骤 | | --- | --- | --- | | 开局命令无响应 | 插件未开启；未提及 Bot | 检查插件开关，并使用 `@Bot 猜干员状态` 测试 | | 提示资源尚未就绪 | 首次缓存未完成或上游请求失败 | 查看状态中的缓存进度，检查网络、磁盘空间和代理配置 | | 普通成员不能开局 | 本群未开启成员开局或仍在冷却 | 由群管理检查 `猜干员成员开始` 设置，并等待冷却结束 | | 答案没有被识别 | 名称/别名不存在，或游戏不在答题阶段 | 使用正式干员名；需要时查询或添加别名 | | 排行没有名次积分 | 本局完成题数低于最低结算题数 | 检查 `operator_guess_finish_min` 和本局完成进度 | | 自定义赛季配置失败 | 只设置了名称，未设置标识 | 同时设置 `operator_guess_season_key` 和名称 | ## 相关文档 - [项目主文档](../../README.md)：插件开关、命令入口和权限体系。 - [管理套件](../manager_suite/README.md)：运行时配置与 Web 管理后台。 # 请求管理 Bot 所有者可通过 `request_manager` 自动处理或人工审核好友请求和 Bot 入群邀请，并设置私聊通知规则。 也可登录 Web 管理后台，进入“请求管理”分别设置处理策略、私聊通知，并逐条同意或拒绝最近 50 条待审请求。页面仅向 Bot 所有者开放，与下列命令共用设置和审核记录。修改策略后，已有待审请求仍需逐条处理。Bot 离线时可以保存规则，恢复连接后才能审核。 插件仅处理发给 Bot 的好友请求和邀请 Bot 入群的请求。普通成员申请入群、成员邀请他人入群，仍由 QQ 群原有流程处理。 ## 快速使用 Bot 所有者可在好友私聊中直接发送命令；在专用管理群中必须提及或回复 Bot： ```text 请求管理 请求管理 好友 审核 请求管理 入群 同意 请求管理 待审 ``` 默认情况下，好友请求和入群邀请均为「不处理」，两类私聊通知均开启。 ## 命令参考 | 命令格式 | 说明 | | --- | --- | | `请求管理` | 查看好友和入群规则及通知状态 | | `请求管理 好友 <不处理\|同意\|审核\|拒绝>` | 设置好友请求处理方式 | | `请求管理 好友 通知 <开\|关>` | 控制好友请求的 Bot 所有者私聊通知 | | `请求管理 入群 <不处理\|同意\|审核\|拒绝>` | 设置 Bot 入群邀请处理方式 | | `请求管理 入群 通知 <开\|关>` | 控制入群邀请的 Bot 所有者私聊通知 | | `请求管理 待审 [数量]` | 查看最近的待审请求，默认 20 条，最多 50 条 | | `请求管理 同意 <编号>` | 同意一条待审请求 | | `请求管理 拒绝 <编号> [理由]` | 拒绝一条待审请求；理由最多 200 字符 | 参数命令支持省略 `请求管理` 后的第一个空格，例如 `请求管理好友 审核` 与 `请求管理 好友 审核` 等价。嵌套子命令仍需保留分隔，`请求管理好友审核` 不会被识别。 完整帮助也可通过 `帮助 请求管理` 查询。通用管理入口和 Bot 所有者定义见[主文档](../../README.md#命令入口)。 ## 处理策略 | 策略 | 平台请求状态 | 插件行为 | | --- | --- | --- | | 不处理 | 保持原状 | 不调用同意或拒绝接口；通知开启时仍告知 Bot 所有者 | | 同意 | 自动同意 | 成功后记录审计，并按通知设置告知 Bot 所有者 | | 审核 | 保持待处理 | 保存到待审列表，等待 Bot 所有者按编号处理 | | 拒绝 | 自动拒绝 | 成功后记录审计，并按通知设置告知 Bot 所有者 | 好友请求和入群邀请各自保存处理规则与通知开关，两类设置互不影响。重复收到同一审核事件时，只保留一条待审记录。 ## 数据与安全行为 - 规则、待审记录和处理结果保存在管理套件使用的主 SQLite 数据库中，不需要单独配置数据库路径。 - 自动同意、自动拒绝、加入待审、人工同意和人工拒绝都会写入管理审计。 - 人工处理按编号串行执行；已处理的记录不会重复调用平台接口。 - 读取规则、保存待审记录或调用平台失败时，插件会尽量保留请求的未处理状态，并尝试私聊通知 Bot 所有者。 - 如果平台操作已成功但数据库状态保存失败，Bot 会提示不要重复操作。 - 好友拒绝理由会传给平台；Bot 入群邀请接口不支持自定义拒绝理由。 备份管理数据库时，按[管理套件的数据存储与备份](../manager_suite/README.md#数据存储与备份)中的要求操作。 ## 排查指南 | 现象 | 可能原因 | 检查步骤 | | --- | --- | --- | | 命令无响应 | 操作者不是 Bot 所有者；管理群中未提及 Bot | 确认账号等于 `OWNER_USER_ID`；在管理群使用 `@Bot 请求管理` | | 收到请求但没有自动处理 | 当前策略为不处理/审核，或规则读取失败 | 发送 `请求管理` 查看规则，并检查 Bot 日志和 Bot 所有者私聊 | | 待审列表为空 | 当前策略不是审核；重复事件已去重 | 检查对应请求类型是否设置为「审核」 | | 同意或拒绝失败 | 平台请求已失效、Bot 连接异常或权限不足 | 根据返回信息确认请求状态，并检查 Milky 连接日志 | | 没有私聊通知 | 对应通知已关闭；Bot 无法给所有者发私聊 | 查看通知开关，并确认 Bot 所有者已添加 Bot 好友 | | 群成员入群申请未处理 | 不在插件处理范围内 | 使用管理套件的入群验证或 QQ 群原生审核流程 | ## 相关文档 - [项目主文档](../../README.md)：Bot 所有者、专用管理群、部署和安全说明。 - [管理套件](../manager_suite/README.md)：权限、审计、数据库和 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 管理后台配置，例如： ```dotenv WEB_ADMIN_PUBLIC_URL=https://admin.example.com WEB_ADMIN_HOST=127.0.0.1 WEB_ADMIN_PORT=8080 ``` 已有后台时保持原域名、地址和端口，在 Bot 的 `.env.prod` 中增加通知配置： ```dotenv 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 所有者在专用管理群开启群聊与插件，并分别确认： ```text @Bot 配置 群聊 123456789 开 @Bot 确认 @Bot 配置 插件 123456789 Codex通知 开 @Bot 确认 ``` 如果群聊已开启，只需开启插件。插件名也接受 `codex_notify`。 配置命令属于帮助中的“系统”分类，仅 Bot 所有者可用；例如： ```text @Bot 帮助 配置 @Bot 配置插件 123456789 Codex通知 开 ``` 紧凑形式只省略 `配置` 后的第一个分隔，子命令和参数之间仍需保留空格。 关闭群聊或插件会取消该群尚未投递的通知，重新开启后不会补发被取消的内容。 | 环境变量 | 默认值 | 用途 | | --- | --- | --- | | `CODEX_NOTIFY_ENABLED` | `false` | 是否启用后台通知接口和投递循环 | | `CODEX_NOTIFY_TOKEN` | 无 | 可选的旧共享 Bearer Token；向全部已开启目标群投递 | | `CODEX_NOTIFY_GROUP_IDS` | `[]` | 可选的补充目标群，普通群仍需开启通知插件；专用管理群在此启用；JSON 整数数组，不允许重复 | | `CODEX_NOTIFY_DATABASE_PATH` | `data/codex_notify.sqlite3` | 通知事件和投递状态数据库 | | `CODEX_NOTIFY_DETAIL` | `simple` | `simple`（简洁）显示项目名和会话名；`full`（完整）额外显示会话和轮次 ID | | `CODEX_NOTIFY_MAX_MESSAGE_CHARS` | `3500` | 群消息文字部分的字符上限及自动模式的文字长度门槛，范围 500 至 4000，图片正文不受此限制 | | `CODEX_NOTIFY_SEND_TIMEOUT_SECONDS` | `15` | 单次 QQ 发送超时，范围大于 0 且不超过 120 秒 | 这些配置属于部署级设置，通过环境变量维护，不使用“配置 设置”修改。 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`](../../scripts/codex_notify.py)， 要求 Python 3.10+。脚本可以与 Bot 分别运行在不同机器上。 将 [`scripts/codex_notify.example.json`](../../scripts/codex_notify.example.json) 复制到 **Codex 实际执行环境** 的用户配置目录，例如 `~/.codex/qqbot-notify.json`，填写： ```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`： ```toml 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 原生执行环境的示例： ```toml 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 示例。 ```json { "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`](../../scripts/pi_notify.ts) 接入。 将它复制到 `~/.pi/agent/extensions/qqbot-notify.ts`，或在 Pi 用户级 `settings.json` 的 `extensions` 数组中追加该文件的绝对路径。保留已有扩展和设置。 使用 `PI_CODING_AGENT_DIR` 时，以下文件放在该目录下。 在 `~/.pi/agent/qqbot-notify.json` 配置转发命令，Python、脚本及通知配置均使用 实际执行环境的绝对路径： ```json { "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` 设为以下形式，并替换发行版名称及路径： ```json { "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`， 继续转发到现有后台服务，配置示例见 [部署手册](../../DEPLOYMENT.md#web-管理后台)。 若代理只允许部分路径，将该通知路径加入原站点的代理范围，并保留 `Authorization` 请求头。不同机器之间使用后台现有 HTTPS 地址，无需增加 域名、证书或对外开放的端口。 脚本只允许 HTTPS 或本机 HTTP，不跟随重定向；不要把 Token 放在 URL 中。 此前独立通知监听已移除；升级时将发送地址改为后台域名下的新路径，并清理旧的 独立监听配置和代理规则。 ## 手动验证 先启动 Bot、配置目标群和开关，再在 Codex 执行环境运行： ```bash 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 `，请求体上限为 256 KiB。 接口不要求后台登录 Cookie 或浏览器 Origin，其他后台 `/api/*` 仍执行原有的 会话鉴权与来源检查，普通后台 API 的 16 KiB 请求体上限保持不变。 | 字段 | 含义 | | --- | --- | | `type` | `agent-turn-complete`、`agent-turn-failed`、`agent-turn-interrupted`、`agent-approval-required` 或静默的 `agent-turn-cancelled` | | `source` | 可选，`codex` 或 `pi`，默认 `codex` | | `thread-id` | 必填，会话标识，1 至 256 个字符，不得包含空白或控制字符 | | `turn-id` | 必填，轮次标识，约束同上 | | `thread-name` | 可选，会话名称，最多 256 个字符；转发脚本从本地会话元数据补充 | | `cwd` | 可选，工作目录，仅使用末级名称生成项目名 | | `last-assistant-message` | 可选，最终回复，可以为 `null` | | `error-message` | 可选，错误信息，最多 4000 字符；转发脚本和服务端都会隐藏其中的 URL 和 Bearer 凭证 | | `duration-ms` | 可选，本轮耗时，非负整数毫秒 | | `request-id` | 授权提醒必填，请求摘要或唯一标识，约束与轮次标识相同 | | `tool-name` | 授权提醒必填，操作名称，最多 128 字符 | 其他字段不参与消息生成或群路由。转发脚本只提交上述字段，并将超过 40000 字符的最终回复截断；Bot 接收的最终回复最多为 64000 字符，并受请求体大小限制。 | HTTP 状态 | 含义 | | --- | --- | | `202`，`status=accepted` | 事件已写入 SQLite；未被个人设置过滤的通知已创建各群投递记录，等待投递 | | `200`，`status=duplicate` | 同一用户、来源、会话和轮次已接收，不重新选择群或重新投递 | | `400` | JSON 或事件字段无效 | | `401` | Token 不匹配、已重置或授权已撤销 | | `409` | 没有已配置且已开启的目标群 | | `413` / `415` | 请求体过大 / 请求格式不是 JSON | | `503` | 服务关闭、存储暂时不可用或待投递记录达到 1000 条上限 | 已接收的完整回复保存在通知数据库中，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`，备份放在清理目录之外，并由运维设置独立保留期、验证恢复。导出、分析报告和主数据库的保留与备份规则见[管理套件的数据存储与备份](../manager_suite/README.md#数据存储与备份)。 本接口仅接收结果和授权提醒。是否授权或确认，仍需回到 Codex 或 Pi 会话决定；通知也不代表任务目标已达成。 客户端接入方式以 OpenAI 的 [通知文档](https://developers.openai.com/codex/config-advanced#notifications) 和[配置参考](https://developers.openai.com/codex/config-reference)为准。 异步钩子的配置与运行规则见 [Hooks 文档](https://learn.chatgpt.com/docs/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` 绕过忽略规则。 每次公开推送前检查暂存内容： ```bash 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 邮箱： ```bash git config user.name "PUBLIC_DISPLAY_NAME" git config user.email "GITHUB_ID+GITHUB_USERNAME@users.noreply.github.com" ``` ## 不携带私有历史进行首次公开 在新提交中删除敏感文本，并不会从旧提交中删除这些内容。首次公开前应在本地检查： ```bash git log --all --format='%h %an <%ae>' git log -p --all -- DEPLOYMENT.md ``` 仓库曾经包含私有部署信息时，推荐从已审核的当前提交生成无历史快照。 按以下流程创建公开仓库，原私有仓库会保留，旧提交及其作者元数据不会进入公开仓库： ```bash 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；共享仓库未经协商不得执行。 ## 服务器约定 示例中的部署账号和路径如下： ```text 公开仓库：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` 的结果一致。 ## 首次安装 创建独立的服务账号并克隆公开仓库： ```bash 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 ``` 使用锁文件安装依赖： ```bash sudo -u qqbot-manager sh -c \ 'cd /opt/qqbot-manager && uv sync --frozen' ``` Markdown 消息图片和聊天分析报告随项目提供中文字体，无需额外安装字体包。 也可通过 `ANALYSIS_REPORT_FONT_PATH` 指定中文字体；文件不可用或不支持中文时， 渲染器会自动使用其他可用中文字体。部署时保留 `plugins/bot_core/resources/fonts/` 目录及其中的字体和授权文件。 从脱敏模板创建生产配置： ```bash 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](WEBSITE_INTEGRATION.md) 部署持久化事件表和增量事件 API。 使用独立生成的至少 32 字节随机 Token，并分别存放在网站的密钥管理系统与 Bot 的 `.env.prod`；不要复用 Milky、GitHub、数据库或其他服务的 Token。 在 `.env.prod` 中配置： ```dotenv 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` 中配置： ```dotenv 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`，再在上方网站通知配置中增加： ```dotenv 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 部署成功后才开放 网站绑定入口。具体接口约定见 [网站集成文档](WEBSITE_INTEGRATION.md#个人排班通知与-maa-json)。 网站通知群的当前成员先添加 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 通知手册](plugins/codex_notify/README.md)。 ### Web 管理后台 后台默认关闭。启用时，为备案域名配置独立 HTTPS 站点，并反向代理到 Bot 的本机监听端口。 后台前端使用 TypeScript、React、Tailwind CSS 和 Vite。安装 Node.js 22.18+（推荐 24 LTS），在服务启动前构建静态资源： ```bash 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 服务；反向代理继续转发所有路径。开发、类型检查和浏览器回归见 [前端说明](./frontend/README.md)。 ```dotenv 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 代理时，将以下示例中的证书配置和域名替换为实际值： ```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 无法替用户撤回私聊答案。 启动前执行验证： ```bash 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`： ```ini [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 ``` 加载并启动服务： ```bash sudo systemctl daemon-reload sudo systemctl enable --now qqbot-manager.service sudo systemctl is-active qqbot-manager.service ``` 检查日志： ```bash sudo journalctl -u qqbot-manager.service -n 100 --no-pager ``` 如果日志包含 Token、QQ 号、消息正文、服务器地址或本地路径，必须脱敏后才能对外 分享。 ## 日常发布 V3 首次启动会不可逆删除旧事件表、旧清理审批表及其专属审计记录，并从群设置中 移除双人审批字段。应用不会保留影子副本。升级前若可能需要回滚，必须先停止服务并 通过独立流程备份 `data/qqbot_manager.sqlite3`；代码回滚不能恢复已经删除的数据。 开发环境先验证再推送公开仓库： ```bash 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/` 或运行时数据： ```bash 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 邮箱。 服务器仅接受快进更新，并在重启前完成验证： ```bash 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，并用双重群范围限制测试： ```dotenv 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 生成内容，且消息可能发送至所配置的第三方模型服务。 ## 回滚 出现问题时，建议先在公开仓库修复并发布新提交。需要恢复服务器版本时，先确认工作区干净， 再找到已验证的提交： ```bash 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 约定调整，各字段的含义和约束必须符合下表： | 字段 | 约束 | 说明 | | --- | --- | --- | | `sequence` | 单调递增 `BIGINT` 主键 | 事件顺序和游标来源，不使用时间戳排序 | | `event_id` | `VARCHAR(128)`、唯一、不可修改 | 例如 `announcement:123`、`release:2026.08.04` | | `event_type` | 枚举 | `announcement.published` 或 `release.published` | | `title` | 非空纯文本，最多 120 字符 | 通知图片标题 | | `summary` | 可空，纯文本或 Markdown，最多 500 字符 | 兼容旧事件与文字回退；使用摘要时限制为 300 字符，超长时以“……（完整内容见网站更新日志）”结尾，提示计入上限 | | `markdown` | 可选、可空，最多 5000 字符 | 发布时的完整 Markdown 正文快照，保留换行与缩进；图片渲染优先使用且不截断 | | `url` | 绝对 HTTPS URL | 已公开、用户可访问的公告或 changelog 页面 | | `version` | 可空，最多 64 字符 | 正式版本事件必填，公告事件必须为空 | | `published_at` | 带时区时间 | API 输出 RFC 3339 UTC 时间 | | `created_at` | 数据库时间 | 事件实际入库时间 | 事件表不参与日常清理。`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 ```http GET /api/integrations/qqbot/events?cursor={cursor|latest}&limit=100 Authorization: Bearer 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` 必须使用同一个数据库快照。 成功响应固定为： ```json { "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： | 状态 | 使用场景 | | --- | --- | | `400` | `invalid_cursor` 或 `invalid_limit` | | `401` | 缺少或无法验证 Bearer Token | | `403` | Token 有效但无此接口权限 | | `429` | 限流，并返回 `Retry-After` | | `503` | 临时服务故障 | 事件和游标不设置过期时间，因此无需 `410 cursor_expired`。所有成功响应设置 `Cache-Control: private, no-store`。 ## 鉴权与安全 - 为此接口单独生成至少 32 字节随机 Token，分别存放在网站密钥系统和 Bot 的 `.env.prod`，不得写入源码、CI 输出或访问日志。 - 网站使用恒定时间比较校验 Token；如需持久化，优先只保存 Token 哈希。 - 生产接口强制 HTTPS，反向代理不得记录 `Authorization` 请求头。 - API 只返回已经公开的内容，不返回草稿、构建日志、提交者邮箱、内部下载地址或 其他非公开字段。 - 轮换密钥时可短暂同时接受新旧 Token；确认 Bot 已使用新 Token 后立即撤销旧值。 ## 服务状态 API 通知群的主动状态查询和自动不可用告警调用网站公开状态接口： ```http GET /api/status Accept: application/json ``` 该请求不携带事件流 Bearer Token。接口必须设置 `Cache-Control: no-store`，不得接受 查询参数；可用或负载升高时返回 `200`，不可用时返回 `503`。Bot 使用以下字段，其余 字段可向后兼容扩展： ```json { "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` 请求网站为内测群成员签发个人注册邀请码： ```http POST /api/integrations/qqbot/registration-invitations Authorization: Bearer Content-Type: application/json ``` 请求体严格为： ```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 身份只取好友私聊事件发送者，不能从参数指定他人。 | 方法与路径（相对于网站根地址） | 用途 | | --- | --- | | `POST /api/integrations/qqbot/binding` | `{qq_number, binding_code}` 兑换网站生成的 24 位绑定码 | | `GET /api/integrations/qqbot/account` | 查询参数 `qq_number`，返回绑定 ID、通知状态与档案列表 | | `PATCH /api/integrations/qqbot/account` | `{qq_number, notifications_enabled}` 开关通知 | | `DELETE /api/integrations/qqbot/binding` | `{qq_number}` 解绑，Bot 先取得用户确认 | | `GET /api/integrations/qqbot/notifications` | `limit=50`，可选 `cursor`，返回待发送通知 | | `POST /api/integrations/qqbot/notifications/ack` | `{qq_number, notification_id}` 确认完成投递 | | `GET /api/integrations/qqbot/results` | `qq_number`、`profile_id`、`limit=10`、可选 `cursor`，返回 `{items, next_cursor, has_more}` | | `POST /api/integrations/qqbot/maa-export` | 按当前绑定和结果导出 MAA 执行 JSON | 网站通知统一管理公告和个人排班的 HTTP 客户端及生命周期。个人排班默认每 15 秒轮询， 所有个人接口共用本地 100 次/分钟的请求预算，为网站 120 次/分钟的限额预留余量。遇到 `429` 按 `Retry-After` 暂停请求；HTTP、QQ 和 文件上传故障指数退避。一条失败不停止其他任务。分页游标只用于本轮扫描，扫描完成 后回到第一页；进程重启也从第一页开始，不遗漏未 ACK 通知。 新通知先以通知 ID 去重存入管理 SQLite。文字发送、文件发送、提醒降级原因和 ACK 分别保存状态。发送前核对当前绑定 ID、通知开关及档案是否可用；旧绑定或关闭通知时 取消本地任务。应发送的文字和文件全部发出后才提交 ACK；ACK 失败时只重试 ACK。记录保留 7 天。 该协议至少投递一次，QQ 接受发送后、本地状态落库前崩溃仍可能重发。 自动导出请求如下，其中幂等键始终为同一通知 ID： ```json { "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 中。 ## 功能概览 | 功能 | 用途 | | --- | --- | | 群管理 | 撤回、禁言、踢人、警告、黑名单、角色调整 | | 群配置 | 违禁词、白名单、欢迎语、锁群、问答、入群验证 | | 数据与分析 | 成员统计与清理、消息导出、分析报告、操作审计 | | Web 管理后台 | 分级权限控制、群聊与插件开关、运行时配置 | | 游戏与娱乐 | PRTS Plus 关卡难度、干员统计、活动刷图与材料掉落图片、MAA 下载、截止提醒、猜干员 | | 网站集成 | 公告与版本通知、服务状态监控、内测注册、个人排班通知和 MAA JSON 私聊下载 | | Codex / Pi 通知 | 发送最终回复和本轮耗时，在报错、非手动中断及等待授权或确认时提醒；可按事件和耗时筛选，设置 @ 提醒及文字/图片显示，图片生成失败时改发文字 | ## 快速开始 ### 环境要求 - Python `>=3.10, <4.0` - [uv](https://docs.astral.sh/uv/)：用于安装依赖和运行项目 - 可用的 QQ/Milky 服务端 - Bot 在目标群中具有所需的平台权限 ### 安装与配置 安装锁定版本的依赖，并创建生产环境配置： ```bash uv sync --frozen cp .env.example .env.prod ``` 启动前编辑 `.env.prod`，填写核心配置，并将示例 QQ 号替换为实际值： ```dotenv 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： ```bash ENVIRONMENT=prod uv run python bot.py ``` ## 使用指南 ### 命令入口 在受管群中可以管理当前群；跨群操作可在专用管理群或好友私聊中执行。 | 使用场景 | 命令格式 | 示例 | | --- | --- | --- | | 在受管群操作当前群 | `@Bot <命令>` | `@Bot 状态` | | 在专用管理群跨群操作 | `@Bot <群号或别名> <命令>` | `@Bot <群号或别名> 状态` | | 在专用管理群执行全局命令 | `@Bot <全局命令>` | `@Bot 全局统计` | | 在好友私聊中管理 | `<群号或别名> <命令>` 或 `<全局命令>` | `<群号或别名> 状态` | 受管群和专用管理群中的命令需要提及或回复 Bot；好友私聊不需要提及。 命令语法约定： - 参数命令支持省略命令词后的第一个空格，例如 `禁言123456789 10` 与 `禁言 123456789 10` 等价。 - 无参数命令必须完整匹配，`状态123` 等普通文本不会触发命令。 - 单目标成员写作 ``。 - 批量命令写作 ` [更多目标]`，可使用逗号分隔的多个 QQ 号或连续多个成员提及；两种形式不能混用，目标不能重复。 ### 权限体系 权限由低到高为： ```text 管理 < 群主 < 超管 < Bot 所有者 ``` | 角色 | 定义方式 | 可用操作 | | --- | --- | --- | | 管理 | 实时读取目标 QQ 群的管理员身份 | 执行成员管理和基础群级命令；专用管理群成员从主分组入口操作时也按管理权限处理 | | 群主 | 实时读取目标 QQ 群的群主身份 | 在管理权限基础上调整群设置、入群验证和成员角色 | | 超管 | 由 `SUPER_ADMIN_USER_IDS` 初始化，Bot 所有者也可在运行时维护数据库超管 | 跨群管理、分组问答、全局数据和其他超管命令 | | Bot 所有者 | 由唯一的 `OWNER_USER_ID` 指定 | 拥有全部权限，可维护超管、群聊与插件开关及运行时配置 | Bot 所有者是部署时指定的唯一最高权限账号；超管可以有多个，但不能修改所有者专属配置。成员操作只能作用于权限更低的账号，Bot、操作者本人、同级和更高权限成员受到保护。 ### 常用命令 发送 `帮助` 可查看当前账号在本会话中能用的命令。帮助中只显示已启用的插件： ```text @Bot 帮助 @Bot 帮助 <分类> @Bot 帮助 <命令> ``` 日常管理： ```text 回复目标消息：@Bot 撤回 回复本群成员消息：@Bot 禁言 10 回复本群成员消息：@Bot 警告 刷屏 回复本群成员消息：@Bot 发言 20 @Bot 禁言 [更多目标] [分钟] @Bot 警告 [更多目标] [原因] @Bot 成员 [未发言天数] @Bot 清理 [未发言天数] [最高等级] ``` 群设置与内容： ```text @Bot 违禁词 [+|- <词>] @Bot 问答 @Bot 欢迎 [文本|开|关|继承] @Bot 入群验证 群聊 [1-60分钟] ``` 游戏与查询： ```text @Bot 今日方舟 @Bot 关卡难度 <关卡> [综合|普通|突袭] @Bot MAA下载 [稳定|公测|内测] [平台] @Bot MAA下载 资源 @Bot 提醒 列表 [分类] [页码] @Bot 猜干员 [立绘|困难立绘|极难立绘|噩梦立绘|技能] ``` 系统与跨群管理： ```text @Bot 状态 @Bot <群号或别名> 状态 @Bot 全局统计 [分组] @Bot 配置 群聊 <群号或别名> <开|关> @Bot 管理后台 ``` 其余命令和完整参数请使用 `@Bot 帮助` 查询。 结果提示省略“失败 0”“跳过 0”和重复计数，异常及需要处理的事项仍会显示。自动清理在同轮多群处理结束后合并通知，相同条件只显示一次；正常结果发到管理群，异常结果私聊 Bot 所有者。 ## 配置说明 ### 环境变量 [`.env.example`](./.env.example) 提供可直接复制的部署模板、常用变量和示例值；各插件的高级配置见对应插件文档。 | 配置 | 用途 | | --- | --- | | `MANAGEMENT_GROUP_ID`、`OWNER_USER_ID`、`SUPER_ADMIN_USER_IDS` | 管理入口与初始权限 | | `MESSAGE_DATABASE_PATH`、`EXPORT_DIRECTORY` | SQLite 数据库与导出目录 | | `TIMEZONE` | 定时任务使用的时区，默认为 `Asia/Shanghai` | | `LLM_API_KEY`、`LLM_BASE_URL`、`LLM_MODEL` | 启用 OpenAI API 兼容的消息分析服务 | | `MAIBOT_BRIDGE_*` | 启用独立 MaiBot 的本机鉴权群聊桥接 | | `CODEX_NOTIFY_*` | 接收 Codex / Pi 轮次结果、授权与确认事件，通过当前 Bot 向指定群发送通知 | | `WEB_ADMIN_PUBLIC_URL`、`WEB_ADMIN_HOST`、`WEB_ADMIN_PORT` | 启用 Web 管理后台 | | `WEBSITE_*` | 网站通知和个人排班共用开关与通知群；内测注册可独立启用 | 默认情况下，核心数据写入 `data/qqbot_manager.sqlite3`，导出、报告、问答图片和插件缓存分别写入 `data/` 下的独立目录。 ### 运行时命令 Bot 所有者可在专用管理群或好友私聊中维护业务配置： ```text @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 下载插件](./plugins/maa_download/README.md)。 Bot 所有者可在 Web 后台“运行时配置 → 管理召唤匹配规则”查看和编辑全部召唤关键词及冲突提示正则，保存后立即生效，重启后保留。 Bot 所有者可在 Web 后台“运行时配置 → AI 分析连接”设置协议、接口地址、模型和 API 密钥，保存后立即生效，重启后保留。支持 OpenAI Chat Completions、OpenAI Responses 和 Anthropic Messages，连接规则见[管理套件手册](./plugins/manager_suite/README.md#web-管理后台)。其他 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 通知手册](./plugins/codex_notify/README.md)。 ### Web 管理后台 管理控制台使用 TypeScript、React、Tailwind CSS 和 Vite，各页面共用一套组件，支持桌面侧边导航、移动端菜单和浅色 / 深色主题。 启用后台前，安装 Node.js 22.18+（推荐 24 LTS），在 `frontend/` 执行 `npm ci && npm run build`。Python 服务直接提供构建产物，无需额外前端进程。开发与验证见 [前端说明](./frontend/README.md)。 公开使用文档位于同站点 `/docs`，无需登录；`/docs/raw` 提供 Markdown 原文。文档包含全部内置命令、权限、示例和插件手册。后台仍使用根路径，通过一次性链接登录。 配置 Web 后台地址和本机监听地址后，管理及以上权限或已获 Codex 通知授权的用户，可在群内发送 `@Bot 管理后台`，或在好友私聊中发送 `管理后台`。命令必须完整匹配，Bot 会返回绑定本人账号的短时一次性链接。仅有通知授权的普通成员只能使用自己的通知页面。 普通管理和群主只能查看有权管理的群，超管可以执行全局命令。后台将 QQ 群角色缓存 5 分钟，刷新时可复用平台缓存，QQ 端权限变更可能延迟生效；查询失败后 15 秒重试，到期无法确认权限时拒绝访问。群聊总开关、插件开关和运行时配置仅 Bot 所有者可改；所有者还可在“请求管理”设置好友请求与 Bot 入群邀请的处理方式、私聊通知，并同意或拒绝待审请求。 Bot 所有者可在“群聊管理”关闭指定群的“超管后台权限”，对超管隐藏该群并禁止后台操作；涉及受限群的共享分组策略和共享提醒需由所有者管理。此限制仅作用于 Web 后台，聊天命令权限沿用原规则，详见[后台权限说明](./plugins/manager_suite/README.md#web-管理后台)。 生产环境必须使用 HTTPS 反向代理，且不要把本机监听端口直接暴露到公网。完整部署方式见 [DEPLOYMENT.md](./DEPLOYMENT.md#web-管理后台)。 ## 部署与安全 ### 权限前置条件 - 撤回、禁言、踢人和入群验证要求 Bot 是目标群管理员或群主。 - 设置或撤销群管理员要求 Bot 是目标群群主。 - 私聊验证依赖 QQ/Milky 能接收新人主动发起的好友私聊或群临时会话。 ### 安全建议 - 使用独立服务账号运行 Bot，并限制生产环境文件的读取权限。 - 定期备份 `data/` 和环境配置；不要提交数据库、导出文件或真实 QQ 号。 - 分别保管 Milky Token、网站 Token 和模型密钥，不要写入源码、日志、Issue 或聊天记录。 - Web 后台仅通过 HTTPS 反向代理开放，不要直接暴露监听端口。 ### 部署参考 - [公开发布与 systemd 部署](./DEPLOYMENT.md)：首次安装、发布、回滚和 Web 反向代理。 - [网站事件接口](./WEBSITE_INTEGRATION.md)：公告、版本通知和状态事件的接口约定。 - [请求管理](./plugins/request_manager/README.md)：配置好友请求和 Bot 入群邀请的处理策略。 - [MaiBot 群聊桥接](./plugins/maibot_bridge/README.md)：复用现有 QQ 会话连接独立 MaiBot，并限制它能发送的消息和执行的操作。 ## 开发与文档 ### 验证命令 ```bash 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 消息渲染](./docs/markdown_messages.md)。 ### 插件文档 - [Bot 公共核心](./plugins/bot_core/README.md)：共用框架、配置、存储、权限、Web 后台和 Markdown 渲染，独立管理版本。 - [管理套件](./plugins/manager_suite/README.md)：群管、配置、审计和 Web 后台。 - [管理召唤](./plugins/call_admin/README.md)：群成员向专用管理群发送求助通知。 - [PRTS Plus 难度查询](./plugins/prts_difficulty/README.md)：关卡难度、作业和干员统计。 - [方舟刷图](./plugins/arknights_farming/README.md)：活动与常驻材料掉落图片；可配置正则模式，直接问“这次活动刷哪关”“固源岩组去哪刷”，无需提及 Bot。 - [MAA 下载](./plugins/maa_download/README.md)：MAA 版本查询、镜像下载和安装包、资源包自动上传到多个群文件夹。 - [明日方舟截止提醒](./plugins/arknights_reminders/README.md)：今日方舟聚合查询、截止事项同步、订阅与提醒。 - [猜干员](./plugins/operator_guess/README.md)：多模式群聊竞猜玩法。 - [请求管理](./plugins/request_manager/README.md)：好友请求和 Bot 入群邀请策略。 - [MaiBot 群聊桥接](./plugins/maibot_bridge/README.md)：支持的 OneBot 接口、可用群范围和部署安全要求。 - [Codex / Pi 群通知](./plugins/codex_notify/README.md)：完成与异常提醒、客户端配置、指定群投递、事件去重与重试。 ## 附录 ### 版本说明 [`pyproject.toml`](./pyproject.toml) 中的 `project.version` 是插件合集版本，各插件版本维护在 [`plugins/versions.py`](./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`