nonebot-plugin-avatar-manager 0.1.0__tar.gz

nonebot_plugin_avatar_manager-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 nonebot-plugin-avatar-manager contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

nonebot_plugin_avatar_manager-0.1.0/PKG-INFO

@@ -0,0 +1,141 @@
+Metadata-Version: 2.1
+Name: nonebot-plugin-avatar-manager
+Version: 0.1.0
+Summary: NoneBot2 头像管理插件，支持机器人与群资料的立即修改和定时修改。
+Author-Email: Akiyy-Lab <2806578374@qq.com>
+License: MIT
+Requires-Python: >=3.10
+Requires-Dist: nonebot2>=2.3.1
+Requires-Dist: nonebot-adapter-onebot>=2.4.6
+Requires-Dist: nonebot-plugin-apscheduler>=0.5.0
+Requires-Dist: httpx>=0.27.0
+Description-Content-Type: text/markdown
+
+<div align="center">
+    <a href="https://v2.nonebot.dev/store"><img src="https://github.com/A-kirami/nonebot-plugin-template/blob/resources/nbp_logo.png" width="180" height="180" alt="NoneBotPluginLogo"></a>
+    <br>
+    <p><img src="https://github.com/A-kirami/nonebot-plugin-template/blob/resources/NoneBotPlugin.svg" width="240" alt="NoneBotPluginText"></p>
+</div>
+
+<div align="center">
+
+# nonebot-plugin-avatar-manager
+
+_✨ NoneBot2 头像管理插件，支持机器人和群资料的立即修改与定时修改 ✨_
+
+<a href="./LICENSE">
+    <img src="https://img.shields.io/github/license/Akiyy-dev/nonebot-plugin-avatar-manager.svg" alt="license">
+</a>
+<a href="https://pypi.python.org/pypi/nonebot-plugin-avatar-manager">
+    <img src="https://img.shields.io/pypi/v/nonebot-plugin-avatar-manager.svg" alt="pypi">
+</a>
+<img src="https://img.shields.io/badge/python-3.10+-blue.svg" alt="python">
+
+</div>
+
+## 📖 介绍
+
+nonebot-plugin-avatar-manager 是一个基于 NoneBot2 和 OneBot V11 的资料管理插件，提供机器人头像/昵称、群头像/群名称的立即修改和定时修改能力，并支持任务持久化恢复。
+
+插件目前支持的核心场景：
+
+- 超级管理员在私聊中查看机器人信息和可管理群列表
+- 群主或管理员在群聊中直接修改当前群头像或群名称
+- 超级管理员修改机器人自身头像或昵称
+- 为群资料或机器人资料创建定时修改任务
+- 启动时自动恢复已保存任务
+
+## 💿 安装
+
+<details open>
+<summary>使用 nb-cli 安装</summary>
+
+在 nonebot2 项目的根目录下打开命令行，输入以下指令即可安装：
+
+```bash
+nb plugin install nonebot-plugin-avatar-manager
+```
+
+</details>
+
+<details>
+<summary>使用包管理器安装</summary>
+
+在 nonebot2 项目的插件目录下打开命令行，根据你使用的包管理器，输入相应的安装命令。
+
+<details>
+<summary>pip</summary>
+
+```bash
+pip install nonebot-plugin-avatar-manager
+```
+
+</details>
+
+安装完成后，打开 nonebot2 项目根目录下的 pyproject.toml 文件，在 `[tool.nonebot]` 部分追加写入：
+
+```toml
+plugins = ["nonebot_plugin_avatar_manager"]
+```
+
+</details>
+
+## ⚙️ 配置
+
+在 nonebot2 项目的 `.env` 文件中添加下表中的配置项：
+
+| 配置项 | 必填 | 默认值 | 说明 |
+|:-----:|:----:|:----:|:----|
+| SUPERUSERS | 是 | 无 | NoneBot 超级管理员账号列表，私聊管理机器人资料时必需 |
+| ENABLE_SELF_AVATAR | 否 | true | 是否允许修改机器人自身头像与昵称 |
+| ENABLE_GROUP_AVATAR | 否 | true | 是否允许修改群头像与群名称 |
+
+示例：
+
+```env
+SUPERUSERS=["123456789"]
+ENABLE_SELF_AVATAR=true
+ENABLE_GROUP_AVATAR=true
+```
+
+## 🎉 使用
+
+### 指令表
+
+| 指令 | 权限 | 需要@ | 范围 | 说明 |
+|:----|:----|:----:|:----:|:----|
+| 头像帮助 | 超级管理员 / 群管理员 / 群主 | 否 | 私聊 / 群聊 | 查看插件帮助 |
+| 头像信息 | 超级管理员 | 否 | 私聊 | 查看机器人账号、昵称、头像地址与所在群列表 |
+| 群管 | 超级管理员 | 否 | 私聊 | 查看机器人在哪些群具备管理权限 |
+| 修改 | 群管理员 / 群主 | 否 | 群聊 | 立即修改当前群头像或群名称 |
+| 定时修改 | 群管理员 / 群主 | 否 | 群聊 | 为当前群创建定时修改任务 |
+| bot修改 | 超级管理员 | 否 | 私聊 / 群聊 | 立即修改机器人头像或昵称 |
+| bot定时修改 | 超级管理员 | 否 | 私聊 / 群聊 | 为机器人自身创建定时修改任务 |
+| 定时列表 | 超级管理员 / 群管理员 / 群主 | 否 | 私聊 / 群聊 | 查看任务列表；群聊中只显示当前群任务 |
+| 删除定时 | 超级管理员 / 群管理员 / 群主 | 否 | 私聊 / 群聊 | 删除指定任务；群聊中仅可删除当前群任务 |
+
+### 使用示例
+
+```text
+修改 https://example.com/avatar.jpg
+修改 新群名
+修改 https://example.com/avatar.jpg 新群名
+定时修改 0 8 * * * https://example.com/avatar.jpg
+定时修改 0 8 * * * 新群名
+bot修改 https://example.com/avatar.jpg 新昵称
+bot定时修改 0 9 * * 1 https://example.com/avatar.jpg
+删除定时 avatar_group_20260409100000
+```
+
+### Cron 示例
+
+```text
+0 8 * * *    每天 8 点执行
+0 9 * * 1    每周一 9 点执行
+*/30 * * * * 每 30 分钟执行一次
+```
+
+### 任务存储
+
+- `data/avatar_manager/tasks.json`：保存定时任务
+- `data/avatar_manager/temp`：保存下载的临时图片

nonebot_plugin_avatar_manager-0.1.0/README.md

@@ -0,0 +1,128 @@
+<div align="center">
+    <a href="https://v2.nonebot.dev/store"><img src="https://github.com/A-kirami/nonebot-plugin-template/blob/resources/nbp_logo.png" width="180" height="180" alt="NoneBotPluginLogo"></a>
+    <br>
+    <p><img src="https://github.com/A-kirami/nonebot-plugin-template/blob/resources/NoneBotPlugin.svg" width="240" alt="NoneBotPluginText"></p>
+</div>
+
+<div align="center">
+
+# nonebot-plugin-avatar-manager
+
+_✨ NoneBot2 头像管理插件，支持机器人和群资料的立即修改与定时修改 ✨_
+
+<a href="./LICENSE">
+    <img src="https://img.shields.io/github/license/Akiyy-dev/nonebot-plugin-avatar-manager.svg" alt="license">
+</a>
+<a href="https://pypi.python.org/pypi/nonebot-plugin-avatar-manager">
+    <img src="https://img.shields.io/pypi/v/nonebot-plugin-avatar-manager.svg" alt="pypi">
+</a>
+<img src="https://img.shields.io/badge/python-3.10+-blue.svg" alt="python">
+
+</div>
+
+## 📖 介绍
+
+nonebot-plugin-avatar-manager 是一个基于 NoneBot2 和 OneBot V11 的资料管理插件，提供机器人头像/昵称、群头像/群名称的立即修改和定时修改能力，并支持任务持久化恢复。
+
+插件目前支持的核心场景：
+
+- 超级管理员在私聊中查看机器人信息和可管理群列表
+- 群主或管理员在群聊中直接修改当前群头像或群名称
+- 超级管理员修改机器人自身头像或昵称
+- 为群资料或机器人资料创建定时修改任务
+- 启动时自动恢复已保存任务
+
+## 💿 安装
+
+<details open>
+<summary>使用 nb-cli 安装</summary>
+
+在 nonebot2 项目的根目录下打开命令行，输入以下指令即可安装：
+
+```bash
+nb plugin install nonebot-plugin-avatar-manager
+```
+
+</details>
+
+<details>
+<summary>使用包管理器安装</summary>
+
+在 nonebot2 项目的插件目录下打开命令行，根据你使用的包管理器，输入相应的安装命令。
+
+<details>
+<summary>pip</summary>
+
+```bash
+pip install nonebot-plugin-avatar-manager
+```
+
+</details>
+
+安装完成后，打开 nonebot2 项目根目录下的 pyproject.toml 文件，在 `[tool.nonebot]` 部分追加写入：
+
+```toml
+plugins = ["nonebot_plugin_avatar_manager"]
+```
+
+</details>
+
+## ⚙️ 配置
+
+在 nonebot2 项目的 `.env` 文件中添加下表中的配置项：
+
+| 配置项 | 必填 | 默认值 | 说明 |
+|:-----:|:----:|:----:|:----|
+| SUPERUSERS | 是 | 无 | NoneBot 超级管理员账号列表，私聊管理机器人资料时必需 |
+| ENABLE_SELF_AVATAR | 否 | true | 是否允许修改机器人自身头像与昵称 |
+| ENABLE_GROUP_AVATAR | 否 | true | 是否允许修改群头像与群名称 |
+
+示例：
+
+```env
+SUPERUSERS=["123456789"]
+ENABLE_SELF_AVATAR=true
+ENABLE_GROUP_AVATAR=true
+```
+
+## 🎉 使用
+
+### 指令表
+
+| 指令 | 权限 | 需要@ | 范围 | 说明 |
+|:----|:----|:----:|:----:|:----|
+| 头像帮助 | 超级管理员 / 群管理员 / 群主 | 否 | 私聊 / 群聊 | 查看插件帮助 |
+| 头像信息 | 超级管理员 | 否 | 私聊 | 查看机器人账号、昵称、头像地址与所在群列表 |
+| 群管 | 超级管理员 | 否 | 私聊 | 查看机器人在哪些群具备管理权限 |
+| 修改 | 群管理员 / 群主 | 否 | 群聊 | 立即修改当前群头像或群名称 |
+| 定时修改 | 群管理员 / 群主 | 否 | 群聊 | 为当前群创建定时修改任务 |
+| bot修改 | 超级管理员 | 否 | 私聊 / 群聊 | 立即修改机器人头像或昵称 |
+| bot定时修改 | 超级管理员 | 否 | 私聊 / 群聊 | 为机器人自身创建定时修改任务 |
+| 定时列表 | 超级管理员 / 群管理员 / 群主 | 否 | 私聊 / 群聊 | 查看任务列表；群聊中只显示当前群任务 |
+| 删除定时 | 超级管理员 / 群管理员 / 群主 | 否 | 私聊 / 群聊 | 删除指定任务；群聊中仅可删除当前群任务 |
+
+### 使用示例
+
+```text
+修改 https://example.com/avatar.jpg
+修改 新群名
+修改 https://example.com/avatar.jpg 新群名
+定时修改 0 8 * * * https://example.com/avatar.jpg
+定时修改 0 8 * * * 新群名
+bot修改 https://example.com/avatar.jpg 新昵称
+bot定时修改 0 9 * * 1 https://example.com/avatar.jpg
+删除定时 avatar_group_20260409100000
+```
+
+### Cron 示例
+
+```text
+0 8 * * *    每天 8 点执行
+0 9 * * 1    每周一 9 点执行
+*/30 * * * * 每 30 分钟执行一次
+```
+
+### 任务存储
+
+- `data/avatar_manager/tasks.json`：保存定时任务
+- `data/avatar_manager/temp`：保存下载的临时图片

nonebot_plugin_avatar_manager-0.1.0/pyproject.toml

@@ -0,0 +1,104 @@
+[project]
+name = "nonebot-plugin-avatar-manager"
+version = "0.1.0"
+description = "NoneBot2 头像管理插件，支持机器人与群资料的立即修改和定时修改。"
+authors = [
+    { name = "Akiyy-Lab", email = "2806578374@qq.com" },
+]
+dependencies = [
+    "nonebot2>=2.3.1",
+    "nonebot-adapter-onebot>=2.4.6",
+    "nonebot-plugin-apscheduler>=0.5.0",
+    "httpx>=0.27.0",
+]
+requires-python = ">=3.10"
+readme = "README.md"
+
+[project.license]
+text = "MIT"
+
+[build-system]
+requires = [
+    "pdm-backend",
+]
+build-backend = "pdm.backend"
+
+[tool.pdm]
+distribution = true
+
+[tool.pdm.build]
+includes = [
+    "src",
+]
+
+[tool.pdm.dev-dependencies]
+dev = [
+    "black>=24.4.2",
+    "isort>=5.13.2",
+    "ruff>=0.4.6",
+]
+
+[tool.pdm.scripts]
+test = "python -c 'print(\">>> Just \\\"pytest -W ignore -s\\\" when you complete your testsuite\")'"
+
+[tool.pdm.scripts.format]
+composite = [
+    "isort . ",
+    "black . ",
+    "ruff check .",
+]
+
+[tool.black]
+line-length = 90
+target-version = [
+    "py310",
+    "py311",
+    "py312",
+]
+include = "\\\\.pyi?$"
+extend-exclude = ""
+
+[tool.isort]
+profile = "black"
+line_length = 90
+length_sort = true
+skip_gitignore = true
+force_sort_within_sections = true
+extra_standard_library = [
+    "typing_extensions",
+]
+
+[tool.ruff]
+line-length = 90
+target-version = "py310"
+
+[tool.ruff.lint]
+select = [
+    "E",
+    "W",
+    "F",
+    "UP",
+    "C",
+    "T",
+    "PYI",
+    "PT",
+    "Q",
+]
+ignore = [
+    "C901",
+    "T201",
+    "E731",
+    "E402",
+]
+
+[tool.pyright]
+pythonVersion = "3.10"
+pythonPlatform = "All"
+typeCheckingMode = "basic"
+
+[tool.nonebot]
+adapters = []
+plugin_dirs = [
+    "src",
+]
+builtin_plugins = []

nonebot_plugin_avatar_manager-0.1.0/src/nonebot_plugin_avatar_manager/__init__.py

@@ -0,0 +1,36 @@
+# nonebot2
+# nonebot-adapter-onebot
+# nonebot-plugin-apscheduler
+
+from nonebot import get_driver, logger, require
+from nonebot.plugin import PluginMetadata
+
+require("nonebot_plugin_apscheduler")
+
+from . import handlers  # noqa: E402,F401
+from . import scheduler  # noqa: E402
+
+__plugin_meta__ = PluginMetadata(
+    name="头像管理器",
+    description="支持定时修改机器人自身头像/昵称以及群头像/群名称（基于 OneBot V11）",
+    usage="发送 头像帮助 查看详细指令",
+    type="application",
+    supported_adapters={"~onebot.v11"},
+)
+
+driver = get_driver()
+
+
+@driver.on_startup
+async def _on_startup() -> None:
+    await scheduler.init_scheduler()
+
+
+@driver.on_shutdown
+async def _on_shutdown() -> None:
+    await scheduler.cleanup_temp_files()
+
+
+__all__ = ["__plugin_meta__", "handlers", "scheduler"]
+
+logger.success("头像管理器插件加载完成")

nonebot_plugin_avatar_manager-0.1.0/src/nonebot_plugin_avatar_manager/config.py

@@ -0,0 +1,7 @@
+from pydantic import BaseModel, Field
+
+
+class Config(BaseModel):
+    superusers: list[str] = Field(default_factory=list)
+    enable_self_avatar: bool = True
+    enable_group_avatar: bool = True

nonebot_plugin_avatar_manager-0.1.0/src/nonebot_plugin_avatar_manager/handlers.py

@@ -0,0 +1,438 @@
+import shlex
+from datetime import datetime
+from pathlib import Path
+
+from nonebot import get_driver, logger, on_command
+from nonebot.adapters.onebot.v11 import (
+    Bot,
+    GroupMessageEvent,
+    Message,
+    PrivateMessageEvent,
+)
+from nonebot.adapters.onebot.v11.permission import GROUP_ADMIN, GROUP_OWNER
+from nonebot.params import CommandArg
+from nonebot.permission import SUPERUSER
+from nonebot.rule import Rule
+
+from .config import Config
+from .models import ScheduleTask
+from .scheduler import add_job, remove_job, run_task_now, tasks
+from .utils import download_image
+
+driver = get_driver()
+plugin_config = Config.model_validate(driver.config.dict())
+manage_permission = SUPERUSER | GROUP_ADMIN | GROUP_OWNER
+
+
+async def _private_only(event: PrivateMessageEvent) -> bool:
+    return True
+
+
+async def _group_only(event: GroupMessageEvent) -> bool:
+    return True
+
+
+def _looks_like_url(value: str) -> bool:
+    return value.startswith(("http://", "https://"))
+
+
+avatar_help = on_command(
+    "头像帮助",
+    aliases={"avatar_help"},
+    permission=manage_permission,
+    priority=5,
+    block=True,
+)
+
+avatar_info = on_command(
+    "头像信息",
+    aliases={"avatar_info"},
+    permission=SUPERUSER,
+    rule=Rule(_private_only),
+    priority=5,
+    block=True,
+)
+
+group_manage = on_command(
+    "群管",
+    permission=SUPERUSER,
+    rule=Rule(_private_only),
+    priority=5,
+    block=True,
+)
+
+group_modify = on_command(
+    "修改",
+    permission=GROUP_ADMIN | GROUP_OWNER,
+    rule=Rule(_group_only),
+    priority=5,
+    block=True,
+)
+
+group_schedule = on_command(
+    "定时修改",
+    permission=GROUP_ADMIN | GROUP_OWNER,
+    rule=Rule(_group_only),
+    priority=5,
+    block=True,
+)
+
+bot_modify = on_command(
+    "bot修改",
+    permission=SUPERUSER,
+    priority=5,
+    block=True,
+)
+
+bot_schedule = on_command(
+    "bot定时修改",
+    permission=SUPERUSER,
+    priority=5,
+    block=True,
+)
+
+schedule_list = on_command(
+    "定时列表",
+    aliases={"schedule_list"},
+    permission=manage_permission,
+    priority=5,
+    block=True,
+)
+
+del_schedule = on_command(
+    "删除定时",
+    aliases={"del_schedule"},
+    permission=manage_permission,
+    priority=5,
+    block=True,
+)
+
+
+def _extract_image_input(arg: Message) -> str | None:
+    for segment in arg:
+        if segment.type != "image":
+            continue
+
+        image_url = segment.data.get("url")
+        if image_url:
+            return str(image_url)
+
+        image_file = segment.data.get("file")
+        if image_file and Path(str(image_file)).exists():
+            return str(image_file)
+
+    return None
+
+
+def _build_job_id(target_type: str) -> str:
+    return f"avatar_{target_type}_{datetime.now().strftime('%Y%m%d%H%M%S')}"
+
+
+async def _resolve_image_value(image_input: str | None) -> str | None:
+    if image_input is None:
+        return None
+
+    if image_input.startswith(("http://", "https://")):
+        downloaded_path = await download_image(image_input)
+        if downloaded_path is None:
+            raise ValueError("图片下载失败")
+        return str(downloaded_path)
+
+    return image_input
+
+
+async def _parse_modify_payload(arg: Message) -> tuple[str | None, str | None]:
+    plain_text = arg.extract_plain_text().strip()
+    parts = shlex.split(plain_text) if plain_text else []
+
+    image_input = _extract_image_input(arg)
+    if image_input is None and parts and _looks_like_url(parts[0]):
+        image_input = parts.pop(0)
+
+    image_path_value = await _resolve_image_value(image_input)
+    new_name = " ".join(parts).strip() or None
+    if image_path_value is None and new_name is None:
+        raise ValueError("至少提供头像图片或新名称之一")
+
+    return image_path_value, new_name
+
+
+async def _parse_timed_modify_payload(arg: Message) -> tuple[str, str | None, str | None]:
+    plain_text = arg.extract_plain_text().strip()
+    if not plain_text:
+        raise ValueError("参数不能为空")
+
+    parts = shlex.split(plain_text)
+    if len(parts) < 5:
+        raise ValueError("cron 格式错误，需要 5 段表达式")
+
+    cron = " ".join(parts[:5])
+    payload_parts = parts[5:]
+
+    image_input = _extract_image_input(arg)
+    if image_input is None and payload_parts and _looks_like_url(payload_parts[0]):
+        image_input = payload_parts.pop(0)
+
+    image_path_value = await _resolve_image_value(image_input)
+    new_name = " ".join(payload_parts).strip() or None
+    if image_path_value is None and new_name is None:
+        raise ValueError("至少提供头像图片或新名称之一")
+
+    return cron, image_path_value, new_name
+
+
+@avatar_help.handle()
+async def avatar_help_handler(
+    event: PrivateMessageEvent | GroupMessageEvent, bot: Bot, arg=CommandArg()
+) -> None:
+    help_text = """
+头像管理器
+
+可用命令:
+- 头像帮助 / avatar_help
+- 头像信息 / avatar_info
+- 群管
+- 修改
+- 定时修改
+- bot修改
+- bot定时修改
+- 定时列表 / schedule_list
+- 删除定时 / del_schedule
+
+示例:
+- 群聊中发送：修改 https://example.com/avatar.jpg
+- 群聊中发送：修改 example
+- 群聊中发送：修改 https://example.com/avatar.jpg example
+- 群聊中发送：定时修改 0 8 * * * https://example.com/avatar.jpg
+- 私聊或群聊中超级管理员发送：bot修改 https://example.com/avatar.jpg
+- 私聊或群聊中超级管理员发送：bot定时修改 0 8 * * * https://example.com/avatar.jpg
+
+权限说明:
+- 私聊中：仅超级管理员可操作全部目标
+- 群聊中：群管理员和群主可配置当前群
+
+注意:
+- 具体 API 可用性取决于你使用的 OneBot V11 实现。
+""".strip()
+    await avatar_help.finish(help_text)
+
+
+@avatar_info.handle()
+async def avatar_info_handler(
+    event: PrivateMessageEvent, bot: Bot, arg=CommandArg()
+) -> None:
+    try:
+        login_info = await bot.get_login_info()
+        group_list = await bot.get_group_list()
+    except Exception as exception:
+        await avatar_info.finish(f"获取头像信息失败: {exception}")
+
+    lines = [
+        "头像管理器信息",
+        f"机器人 QQ: {bot.self_id}",
+        f"机器人昵称: {login_info.get('nickname', '未知')}",
+        f"机器人头像: http://q.qlogo.cn/headimg_dl?dst_uin={bot.self_id}&spec=640",
+        "所在群列表:",
+    ]
+
+    for group in group_list:
+        group_id = int(group["group_id"])
+        group_name = str(group.get("group_name", "未知群名"))
+        lines.append(
+            f"- {group_name} ({group_id}) | 群头像: http://p.qlogo.cn/gh/{group_id}/{group_id}/640"
+        )
+
+    await avatar_info.finish("\n".join(lines))
+
+
+@group_manage.handle()
+async def group_manage_handler(
+    event: PrivateMessageEvent, bot: Bot, arg=CommandArg()
+) -> None:
+    try:
+        group_list = await bot.get_group_list()
+    except Exception as exception:
+        await group_manage.finish(f"获取群列表失败: {exception}")
+
+    manageable_groups: list[str] = []
+    for group in group_list:
+        group_id = int(group["group_id"])
+        try:
+            member_info = await bot.get_group_member_info(
+                group_id=group_id,
+                user_id=int(bot.self_id),
+            )
+        except Exception as exception:
+            logger.warning(f"查询群 {group_id} 权限失败: {exception}")
+            continue
+
+        role = str(member_info.get("role", "member"))
+        if role in {"owner", "admin"}:
+            group_name = str(group.get("group_name", "未知群名"))
+            manageable_groups.append(f"- {group_id} | {group_name} | {role}")
+
+    if not manageable_groups:
+        await group_manage.finish("无管理权限")
+
+    await group_manage.finish("可管理群列表:\n" + "\n".join(manageable_groups))
+
+
+@group_modify.handle()
+async def group_modify_handler(
+    event: GroupMessageEvent, bot: Bot, arg=CommandArg()
+) -> None:
+    try:
+        if not plugin_config.enable_group_avatar:
+            await group_modify.finish("当前未启用群头像/群名称修改功能")
+
+        image_path, new_name = await _parse_modify_payload(arg)
+        task = ScheduleTask(
+            job_id=_build_job_id("group"),
+            target_type="group",
+            target_id=int(event.group_id),
+            cron="0 0 1 1 *",
+            new_name=new_name,
+            image_path=image_path,
+        )
+        success, message = await run_task_now(task)
+        if not success:
+            await group_modify.finish(f"立即修改失败: {message}")
+    except ValueError as exception:
+        await group_modify.finish(str(exception))
+    except Exception as exception:
+        await group_modify.finish(f"立即修改失败: {exception}")
+
+    await group_modify.finish("已立即修改当前群配置")
+
+
+@group_schedule.handle()
+async def group_schedule_handler(
+    event: GroupMessageEvent, bot: Bot, arg=CommandArg()
+) -> None:
+    try:
+        if not plugin_config.enable_group_avatar:
+            await group_schedule.finish("当前未启用群头像/群名称修改功能")
+
+        cron, image_path, new_name = await _parse_timed_modify_payload(arg)
+        task = ScheduleTask(
+            job_id=_build_job_id("group"),
+            target_type="group",
+            target_id=int(event.group_id),
+            cron=cron,
+            new_name=new_name,
+            image_path=image_path,
+        )
+        add_job(task)
+    except ValueError as exception:
+        await group_schedule.finish(str(exception))
+    except Exception as exception:
+        await group_schedule.finish(f"添加定时任务失败: {exception}")
+
+    await group_schedule.finish(f"已添加定时任务 ID: {task.job_id}")
+
+
+@bot_modify.handle()
+async def bot_modify_handler(
+    event: PrivateMessageEvent | GroupMessageEvent, bot: Bot, arg=CommandArg()
+) -> None:
+    try:
+        if not plugin_config.enable_self_avatar:
+            await bot_modify.finish("当前未启用机器人自身头像/昵称修改功能")
+
+        image_path, new_name = await _parse_modify_payload(arg)
+        task = ScheduleTask(
+            job_id=_build_job_id("self"),
+            target_type="self",
+            cron="0 0 1 1 *",
+            new_name=new_name,
+            image_path=image_path,
+        )
+        success, message = await run_task_now(task)
+        if not success:
+            await bot_modify.finish(f"立即修改失败: {message}")
+    except ValueError as exception:
+        await bot_modify.finish(str(exception))
+    except Exception as exception:
+        await bot_modify.finish(f"立即修改失败: {exception}")
+
+    await bot_modify.finish("已立即修改机器人配置")
+
+
+@bot_schedule.handle()
+async def bot_schedule_handler(
+    event: PrivateMessageEvent | GroupMessageEvent, bot: Bot, arg=CommandArg()
+) -> None:
+    try:
+        if not plugin_config.enable_self_avatar:
+            await bot_schedule.finish("当前未启用机器人自身头像/昵称修改功能")
+
+        cron, image_path, new_name = await _parse_timed_modify_payload(arg)
+        task = ScheduleTask(
+            job_id=_build_job_id("self"),
+            target_type="self",
+            cron=cron,
+            new_name=new_name,
+            image_path=image_path,
+        )
+        add_job(task)
+    except ValueError as exception:
+        await bot_schedule.finish(str(exception))
+    except Exception as exception:
+        await bot_schedule.finish(f"添加定时任务失败: {exception}")
+
+    await bot_schedule.finish(f"已添加定时任务 ID: {task.job_id}")
+
+
+@schedule_list.handle()
+async def schedule_list_handler(
+    event: PrivateMessageEvent | GroupMessageEvent, bot: Bot, arg=CommandArg()
+) -> None:
+    filtered_tasks = list(tasks.values())
+    if isinstance(event, GroupMessageEvent):
+        filtered_tasks = [
+            task
+            for task in filtered_tasks
+            if task.target_type == "group" and task.target_id == int(event.group_id)
+        ]
+
+    if not filtered_tasks:
+        await schedule_list.finish("当前没有定时任务")
+
+    lines = [
+        " | ".join(
+            [
+                f"- {task.job_id}",
+                f"target={task.target_type}",
+                f"target_id={task.target_id or '-'}",
+                f"cron={task.cron}",
+                f"name={task.new_name or '-'}",
+                f"image={task.image_path or '-'}",
+            ]
+        )
+        for task in filtered_tasks
+    ]
+    await schedule_list.finish("已保存定时任务:\n" + "\n".join(lines))
+
+
+@del_schedule.handle()
+async def del_schedule_handler(
+    event: PrivateMessageEvent | GroupMessageEvent, bot: Bot, arg=CommandArg()
+) -> None:
+    job_id = arg.extract_plain_text().strip()
+    if not job_id:
+        await del_schedule.finish("请提供要删除的任务 ID")
+
+    task = tasks.get(job_id)
+    if isinstance(event, GroupMessageEvent):
+        invalid_group_task = (
+            task is None
+            or task.target_type != "group"
+            or task.target_id != int(event.group_id)
+        )
+        if invalid_group_task:
+            await del_schedule.finish("未找到本群对应的任务 ID")
+
+    if not remove_job(job_id):
+        await del_schedule.finish(f"未找到任务 ID: {job_id}")
+
+    await del_schedule.finish(f"已删除定时任务 ID: {job_id}")

nonebot_plugin_avatar_manager-0.1.0/src/nonebot_plugin_avatar_manager/models.py

@@ -0,0 +1,13 @@
+from datetime import datetime
+
+from pydantic import BaseModel, Field
+
+
+class ScheduleTask(BaseModel):
+    job_id: str
+    target_type: str
+    target_id: int | None = None
+    cron: str
+    new_name: str | None = None
+    image_path: str | None = None
+    create_time: datetime = Field(default_factory=datetime.now)

nonebot_plugin_avatar_manager-0.1.0/src/nonebot_plugin_avatar_manager/scheduler.py

@@ -0,0 +1,213 @@
+import asyncio
+import json
+from pathlib import Path
+
+import nonebot
+from nonebot import logger
+from nonebot.adapters.onebot.v11 import Bot
+from nonebot.exception import ActionFailed
+from nonebot_plugin_apscheduler import scheduler
+
+from .models import ScheduleTask
+from .utils import TEMP_DIR, image_to_base64
+
+tasks: dict[str, ScheduleTask] = {}
+data_dir = Path("data/avatar_manager")
+tasks_file = data_dir / "tasks.json"
+
+
+def load_tasks() -> dict[str, ScheduleTask]:
+    if not tasks_file.exists():
+        return {}
+
+    try:
+        raw_data = json.loads(tasks_file.read_text(encoding="utf-8"))
+    except (json.JSONDecodeError, OSError) as exception:
+        logger.error(f"读取任务文件失败: {exception}")
+        return {}
+
+    loaded_tasks: dict[str, ScheduleTask] = {}
+    for job_id, task_data in raw_data.items():
+        try:
+            loaded_tasks[job_id] = ScheduleTask.model_validate(task_data)
+        except Exception as exception:
+            logger.error(f"加载任务 {job_id} 失败: {exception}")
+    return loaded_tasks
+
+
+def save_tasks() -> None:
+    try:
+        data_dir.mkdir(parents=True, exist_ok=True)
+        payload = {
+            job_id: task.model_dump(mode="json")
+            for job_id, task in tasks.items()
+        }
+        tasks_file.write_text(
+            json.dumps(payload, ensure_ascii=False, indent=2),
+            encoding="utf-8",
+        )
+    except OSError as exception:
+        logger.error(f"保存任务文件失败: {exception}")
+
+
+def _cron_to_kwargs(cron: str) -> dict[str, str]:
+    parts = cron.split()
+    if len(parts) != 5:
+        raise ValueError("cron 格式错误，需要 5 段表达式")
+
+    return {
+        "minute": parts[0],
+        "hour": parts[1],
+        "day": parts[2],
+        "month": parts[3],
+        "day_of_week": parts[4],
+    }
+
+
+async def _resolve_bot() -> Bot | None:
+    bot = next(
+        (
+            candidate
+            for candidate in nonebot.get_bots().values()
+            if isinstance(candidate, Bot)
+        ),
+        None,
+    )
+    if bot is None:
+        logger.warning("当前没有可用的 OneBot V11 Bot，任务已跳过")
+    return bot
+
+
+async def change_avatar_job(task: ScheduleTask, bot: Bot) -> tuple[bool, str]:
+    try:
+        upload_payload: str | None = None
+        if task.image_path:
+            image_path = Path(task.image_path)
+            if image_path.exists():
+                base64_str = await image_to_base64(image_path)
+                upload_payload = f"base64://{base64_str}"
+            else:
+                message = f"任务 {task.job_id} 的图片不存在: {task.image_path}"
+                logger.warning(message)
+                return False, message
+
+        if task.target_type == "self":
+            if upload_payload is not None:
+                await bot.call_api("set_qq_avatar", file=upload_payload)
+            if task.new_name:
+                await bot.call_api("set_qq_profile", nickname=task.new_name)
+        elif task.target_type == "group" and task.target_id is not None:
+            if upload_payload is not None:
+                await bot.call_api(
+                    "set_group_portrait",
+                    group_id=task.target_id,
+                    file=upload_payload,
+                )
+            if task.new_name:
+                await bot.call_api(
+                    "set_group_name",
+                    group_id=task.target_id,
+                    group_name=task.new_name,
+                )
+        else:
+            message = f"任务 {task.job_id} 的目标配置无效，已跳过执行"
+            logger.warning(message)
+            return False, message
+
+        success_message = f"定时任务执行成功: {task.job_id}"
+        logger.success(success_message)
+        return True, success_message
+    except ActionFailed as exception:
+        message = f"任务 {task.job_id} 调用 API 失败: {exception}"
+        logger.error(message)
+        return False, message
+    except Exception as exception:
+        message = f"任务 {task.job_id} 执行异常: {exception}"
+        logger.exception(message)
+        return False, message
+
+
+async def _run_task(job_id: str) -> None:
+    task = tasks.get(job_id)
+    if task is None:
+        logger.warning(f"未找到任务 ID: {job_id}")
+        return
+
+    bot = await _resolve_bot()
+    if bot is None:
+        return
+
+    await change_avatar_job(task, bot)
+
+
+async def run_task_now(task: ScheduleTask) -> tuple[bool, str]:
+    bot = await _resolve_bot()
+    if bot is None:
+        return False, "当前没有可用的 OneBot V11 Bot"
+
+    return await change_avatar_job(task, bot)
+
+
+def add_job(task: ScheduleTask) -> None:
+    cron_kwargs = _cron_to_kwargs(task.cron)
+    tasks[task.job_id] = task
+    scheduler.add_job(
+        _run_task,
+        "cron",
+        id=task.job_id,
+        args=[task.job_id],
+        replace_existing=True,
+        **cron_kwargs,
+    )
+    save_tasks()
+
+
+def remove_job(job_id: str) -> bool:
+    task = tasks.pop(job_id, None)
+    if task is None:
+        return False
+
+    try:
+        scheduler.remove_job(job_id)
+    except Exception as exception:
+        logger.warning(f"移除调度任务失败: {job_id} | error={exception}")
+
+    save_tasks()
+    return True
+
+
+async def init_scheduler() -> None:
+    tasks.clear()
+    tasks.update(load_tasks())
+
+    restored_count = 0
+    for task in tasks.values():
+        try:
+            cron_kwargs = _cron_to_kwargs(task.cron)
+            scheduler.add_job(
+                _run_task,
+                "cron",
+                id=task.job_id,
+                args=[task.job_id],
+                replace_existing=True,
+                **cron_kwargs,
+            )
+            restored_count += 1
+        except Exception as exception:
+            logger.error(f"恢复任务失败: {task.job_id} | error={exception}")
+
+    logger.info(f"头像管理器定时任务已恢复，共 {restored_count} 个任务")
+
+
+async def cleanup_temp_files() -> None:
+    if not TEMP_DIR.exists():
+        return
+
+    for path in TEMP_DIR.iterdir():
+        if not path.is_file():
+            continue
+
+        try:
+            await asyncio.to_thread(path.unlink)
+        except OSError as exception:
+            logger.warning(f"清理临时文件失败: {path} | error={exception}")

nonebot_plugin_avatar_manager-0.1.0/src/nonebot_plugin_avatar_manager/utils.py

@@ -0,0 +1,46 @@
+import asyncio
+import base64
+import tempfile
+from pathlib import Path
+
+import httpx
+from nonebot import logger
+
+TEMP_DIR = Path("data/avatar_manager/temp")
+
+
+async def download_image(url: str) -> Path | None:
+    """下载图片并保存到 data/temp 目录，失败时返回 None。"""
+    try:
+        TEMP_DIR.mkdir(parents=True, exist_ok=True)
+        suffix = Path(url.split("?", maxsplit=1)[0]).suffix or ".jpg"
+
+        async with httpx.AsyncClient(
+            timeout=httpx.Timeout(20.0, connect=10.0),
+            follow_redirects=True,
+        ) as client:
+            response = await client.get(url)
+            response.raise_for_status()
+
+        def _write_file() -> Path:
+            with tempfile.NamedTemporaryFile(
+                dir=TEMP_DIR,
+                prefix="avatar_",
+                suffix=suffix,
+                delete=False,
+            ) as temp_file:
+                temp_file.write(response.content)
+                return Path(temp_file.name)
+
+        return await asyncio.to_thread(_write_file)
+    except httpx.HTTPError as exception:
+        logger.error(f"下载图片失败: {exception}")
+    except OSError as exception:
+        logger.error(f"写入图片文件失败: {exception}")
+
+    return None
+
+
+async def image_to_base64(image_path: Path) -> str:
+    image_bytes = await asyncio.to_thread(image_path.read_bytes)
+    return base64.b64encode(image_bytes).decode("utf-8")