Kirara AI

Appearance

状态管理 ​

本页面介绍如何在插件中管理状态和数据。

状态类型 ​

会话状态 ​

存储单个会话的临时数据。

python
from kirara.state import SessionState

class MyPlugin(Plugin):
    async def handle_message(self, message: Message):
        state = SessionState(message.session_id)
        
        # 设置状态
        await state.set("step", 1)
        await state.set("data", {"key": "value"})
        
        # 获取状态
        step = await state.get("step")
        data = await state.get("data")

用户状态 ​

存储用户相关的数据。

python
from kirara.state import UserState

class MyPlugin(Plugin):
    async def handle_message(self, message: Message):
        state = UserState(message.sender.id)
        
        # 设置用户数据
        await state.set("preferences", {
            "language": "zh-CN",
            "theme": "dark"
        })
        
        # 获取用户数据
        prefs = await state.get("preferences")

全局状态 ​

存储插件级别的数据。

python
from kirara.state import GlobalState

class MyPlugin(Plugin):
    def __init__(self):
        self.state = GlobalState()
        
    async def initialize(self):
        # 设置全局数据
        await self.state.set("config", {
            "version": "1.0.0",
            "enabled": True
        })

状态操作 ​

基本操作 ​

python
class MyPlugin(Plugin):
    async def handle_state(self, state):
        # 设置值
        await state.set("key", "value")
        
        # 获取值
        value = await state.get("key")
        
        # 删除值
        await state.delete("key")
        
        # 检查是否存在
        exists = await state.exists("key")

批量操作 ​

python
class MyPlugin(Plugin):
    async def handle_batch(self, state):
        # 批量设置
        await state.set_many({
            "key1": "value1",
            "key2": "value2"
        })
        
        # 批量获取
        values = await state.get_many(["key1", "key2"])
        
        # 批量删除
        await state.delete_many(["key1", "key2"])

过期时间 ​

设置数据的过期时间。

python
class MyPlugin(Plugin):
    async def handle_expiry(self, state):
        # 设置带过期时间的数据
        await state.set("temp", "value", expire=3600)  # 1小时后过期
        
        # 更新过期时间
        await state.expire("temp", 7200)  # 延长到2小时
        
        # 获取剩余时间
        ttl = await state.ttl("temp")

数据持久化 ​

文件存储 ​

将数据保存到文件。

python
from kirara.storage import FileStorage

class MyPlugin(Plugin):
    def __init__(self):
        self.storage = FileStorage("data.json")
        
    async def save_data(self):
        # 保存数据
        await self.storage.save({
            "settings": self.settings,
            "cache": self.cache
        })
        
        # 加载数据
        data = await self.storage.load()

数据库存储 ​

使用数据库存储数据。

python
from kirara.storage import Database

class MyPlugin(Plugin):
    def __init__(self):
        self.db = Database()
        
    async def handle_database(self):
        # 插入数据
        await self.db.insert("users", {
            "id": "user1",
            "name": "张三"
        })
        
        # 查询数据
        user = await self.db.find_one("users", {"id": "user1"})

状态同步 ​

状态锁 ​

防止并发访问冲突。

python
from kirara.state import StateLock

class MyPlugin(Plugin):
    async def handle_message(self, message: Message):
        async with StateLock("resource"):
            # 在锁内的操作
            state = await self.state.get("data")
            state["count"] += 1
            await self.state.set("data", state)

状态订阅 ​

监听状态变化。

python
from kirara.state import StateObserver

class MyPlugin(Plugin, StateObserver):
    async def on_state_change(self, key, old_value, new_value):
        self.logger.info(f"状态变化：{key} = {new_value}")

最佳实践 ​

  1. 状态设计

    • 合理划分状态范围
    • 选择适当的存储方式
    • 注意数据结构设计

  2. 性能优化

    • 使用缓存
    • 批量操作
    • 控制数据大小

  3. 安全考虑

    • 验证数据
    • 控制访问权限
    • 加密敏感信息

  4. 错误处理

    • 处理存储错误
    • 数据备份
    • 状态恢复