From b8e4068c75a1434b2dbff315e45d7d35a354b41c Mon Sep 17 00:00:00 2001
From: Soulter <37870767+Soulter@users.noreply.github.com>
Date: Mon, 15 Dec 2025 16:50:44 +0800
Subject: [PATCH] feat: support key-value storage for plugins (#4048)

* feat: support key-value storage for plugins

* fix: remove unnecessary initialization method from Main class
---
 astrbot/core/star/__init__.py         |  6 +++++-
 astrbot/core/star/star_manager.py     | 12 ++++++++++++
 astrbot/core/utils/plugin_kv_store.py | 28 +++++++++++++++++++++++++++
 3 files changed, 45 insertions(+), 1 deletion(-)
 create mode 100644 astrbot/core/utils/plugin_kv_store.py

diff --git a/astrbot/core/star/__init__.py b/astrbot/core/star/__init__.py
index e27db7405..c474962c5 100644
--- a/astrbot/core/star/__init__.py
+++ b/astrbot/core/star/__init__.py
@@ -2,15 +2,19 @@ from astrbot.core import html_renderer
 from astrbot.core.provider import Provider
 from astrbot.core.star.star_tools import StarTools
 from astrbot.core.utils.command_parser import CommandParserMixin
+from astrbot.core.utils.plugin_kv_store import PluginKVStoreMixin
 
 from .context import Context
 from .star import StarMetadata, star_map, star_registry
 from .star_manager import PluginManager
 
 
-class Star(CommandParserMixin):
+class Star(CommandParserMixin, PluginKVStoreMixin):
     """所有插件（Star）的父类，所有插件都应该继承于这个类"""
 
+    author: str
+    name: str
+
     def __init__(self, context: Context, config: dict | None = None):
         StarTools.initialize(context)
         self.context = context
diff --git a/astrbot/core/star/star_manager.py b/astrbot/core/star/star_manager.py
index abdedc249..15dc91b48 100644
--- a/astrbot/core/star/star_manager.py
+++ b/astrbot/core/star/star_manager.py
@@ -467,6 +467,18 @@ class PluginManager:
                             metadata.star_cls = metadata.star_cls_type(
                                 context=self.context,
                             )
+
+                        p_name = (metadata.name or "unknown").lower().replace("/", "_")
+                        p_author = (
+                            (metadata.author or "unknown").lower().replace("/", "_")
+                        )
+                        setattr(metadata.star_cls, "name", p_name)
+                        setattr(metadata.star_cls, "author", p_author)
+                        setattr(
+                            metadata.star_cls,
+                            "plugin_id",
+                            f"{p_author}/{p_name}",
+                        )
                     else:
                         logger.info(f"插件 {metadata.name} 已被禁用。")
 
diff --git a/astrbot/core/utils/plugin_kv_store.py b/astrbot/core/utils/plugin_kv_store.py
new file mode 100644
index 000000000..88460c8e1
--- /dev/null
+++ b/astrbot/core/utils/plugin_kv_store.py
@@ -0,0 +1,28 @@
+from typing import TypeVar
+
+from astrbot.core import sp
+
+SUPPORTED_VALUE_TYPES = int | float | str | bytes | bool | dict | list | None
+_VT = TypeVar("_VT")
+
+
+class PluginKVStoreMixin:
+    """为插件提供键值存储功能的 Mixin 类"""
+
+    plugin_id: str
+
+    async def put_kv_data(
+        self,
+        key: str,
+        value: SUPPORTED_VALUE_TYPES,
+    ) -> None:
+        """为指定插件存储一个键值对"""
+        await sp.put_async("plugin", self.plugin_id, key, value)
+
+    async def get_kv_data(self, key: str, default: _VT) -> _VT | None:
+        """获取指定插件存储的键值对"""
+        return await sp.get_async("plugin", self.plugin_id, key, default)
+
+    async def delete_kv_data(self, key: str) -> None:
+        """删除指定插件存储的键值对"""
+        await sp.remove_async("plugin", self.plugin_id, key)