add 统一缓存使用说明

README.md

@@ -23,6 +23,7 @@ MoviePilot官方插件市场：https://github.com/jxxghp/MoviePilot-Plugins
   - [12. 如何通过插件扩展支持的存储类型？](#12-如何通过插件扩展支持的存储类型)
   - [13. 如何将插件功能集成到工作流？](#13-如何将插件功能集成到工作流)
   - [14. 如何在插件中通过消息持续与用户交互？](#14-如何在插件中通过消息持续与用户交互)
+  - [15. 如何在插件中使用系统级统一缓存？](#15-如何在插件中使用系统级统一缓存)
 - [版本发布](#版本发布)
   - [1. 如何发布插件版本？](#1-如何发布插件版本)
   - [2. 如何开发V2版本的插件以及实现插件多版本兼容？](#2-如何开发v2版本的插件以及实现插件多版本兼容)
@@ -1167,6 +1168,190 @@ def get_actions(self) -> List[Dict[str, Any]]:
   - 建议在交互中保存用户状态数据，以支持复杂的多步骤操作
   - 可以结合插件数据存储功能保存用户的交互历史和偏好设置
 
+### 15. 如何在插件中使用系统级统一缓存？
+**（仅支持 `v2.7.4+` 版本）**
+- MoviePilot提供了统一的缓存系统，支持内存缓存、文件系统缓存和Redis缓存自动管理，当有Redis时优先使用Redis，否则使用内存或文件系统。插件可以通过系统提供的缓存接口实现高效的缓存管理，无需关心系统设置。
+
+- 1. 使用缓存装饰器：
+    ```python
+    from app.core.cache import cached
+    
+    class MyPlugin(_PluginBase):
+        @cached(region="my_plugin", ttl=3600)
+        def get_data(self, key: str):
+            """
+            使用缓存装饰器，缓存结果1小时
+            """
+            # 复杂的计算或网络请求
+            return expensive_operation(key)
+        
+        @cached(region="my_plugin_async", ttl=1800, skip_none=True)
+        async def get_async_data(self, key: str):
+            """
+            异步函数缓存，跳过None值
+            """
+            return await async_expensive_operation(key)
+    ```
+
+- 2. 使用TTLCache类：
+    ```python
+    from app.core.cache import TTLCache
+    
+    class MyPlugin(_PluginBase):
+        def __init__(self):
+            super().__init__()
+            # 创建缓存实例，最大128项，TTL 30分钟
+            self.cache = TTLCache(region="my_plugin", maxsize=128, ttl=1800)
+        
+        def process_data(self, key: str):
+            # 检查缓存
+            if key in self.cache:
+                return self.cache[key]
+            
+            # 计算并缓存结果
+            result = expensive_operation(key)
+            self.cache[key] = result
+            return result
+        
+        def clear_cache(self):
+            """
+            清理插件缓存
+            """
+            self.cache.clear()
+    ```
+
+- 3. 使用文件缓存后端（适用于大文件缓存）：
+    ```python
+    from app.core.cache import FileCache, AsyncFileCache
+    from pathlib import Path
+    
+    class MyPlugin(_PluginBase):
+        def __init__(self):
+            super().__init__()
+            # 获取文件缓存后端，支持Redis和文件系统
+            self.file_cache = FileCache(
+                base=Path("/tmp/my_plugin_cache"),
+                ttl=86400  # 24小时
+            )
+        
+        def cache_large_file(self, key: str, data: bytes):
+            """
+            缓存大文件数据
+            """
+            self.file_cache.set(key, data, region="large_files")
+        
+        def get_cached_file(self, key: str) -> Optional[bytes]:
+            """
+            获取缓存的文件数据
+            """
+            return self.file_cache.get(key, region="large_files")
+        
+        async def async_cache_operations(self):
+            """
+            异步文件缓存操作
+            """
+            async_cache = AsyncFileCache(
+                base=Path("/tmp/my_plugin_async_cache"),
+                ttl=3600
+            )
+            
+            # 异步设置缓存
+            await async_cache.set("async_key", b"async_data", region="async_files")
+            
+            # 异步获取缓存
+            data = await async_cache.get("async_key", region="async_files")
+            
+            await async_cache.close()
+    ```
+
+- 4. 直接使用缓存后端（高级用法）：
+    ```python
+    from app.core.cache import Cache
+    
+    class MyPlugin(_PluginBase):
+        def __init__(self):
+            super().__init__()
+            # 直接获取缓存后端实例，系统自动选择Redis或内存缓存
+            self.cache_backend = Cache(maxsize=256, ttl=3600)
+        
+        def custom_cache_operation(self, key: str, value: Any):
+            """
+            自定义缓存操作
+            """
+            # 设置缓存
+            self.cache_backend.set(key, value, region="custom_region")
+            
+            # 检查缓存是否存在
+            if self.cache_backend.exists(key, region="custom_region"):
+                # 获取缓存
+                cached_value = self.cache_backend.get(key, region="custom_region")
+                return cached_value
+            
+            return None
+        
+        def iterate_cache_items(self):
+            """
+            遍历缓存项
+            """
+            for key, value in self.cache_backend.items(region="custom_region"):
+                print(f"缓存键: {key}, 值: {value}")
+        
+        def cleanup(self):
+            """
+            清理缓存
+            """
+            self.cache_backend.clear(region="custom_region")
+            self.cache_backend.close()
+    ```
+
+- 5. 缓存装饰器参数说明：
+    ```python
+    @cached(
+        region="my_plugin",           # 缓存区域，用于隔离不同插件的缓存
+        maxsize=512,                  # 最大缓存条目数（仅内存缓存有效）
+        ttl=1800,                     # 缓存存活时间（秒）
+        skip_none=True,               # 是否跳过None值缓存
+        skip_empty=False              # 是否跳过空值缓存（空列表、空字典等）
+    )
+    def my_function(self, param):
+        pass
+    ```
+
+- 6. 缓存管理功能：
+    ```python
+    class MyPlugin(_PluginBase):
+        @cached(region="my_plugin")
+        def cached_function(self, param):
+            return expensive_operation(param)
+        
+        def clear_my_cache(self):
+            """
+            清理指定区域的缓存
+            """
+            self.cached_function.cache_clear()
+        
+        def get_cache_info(self):
+            """
+            获取缓存信息
+            """
+            cache_region = self.cached_function.cache_region
+            return f"缓存区域: {cache_region}"
+    ```
+
+- 7. 缓存后端自动选择：
+    - 系统会根据配置自动选择缓存后端：
+        - `CACHE_BACKEND_TYPE=redis`：使用Redis作为缓存后端
+        - `CACHE_BACKEND_TYPE=memory`：使用内存缓存（cachetools）
+    - 插件代码无需修改，系统会自动处理缓存后端的切换
+
+- 8. 最佳实践：
+    - 为每个插件使用独立的缓存区域（region），避免缓存键冲突
+    - 合理设置TTL，避免缓存过期时间过长导致数据过期
+    - 对于频繁访问的数据使用较长的TTL，对于实时性要求高的数据使用较短的TTL
+    - 使用`skip_none=True`避免缓存无意义的None值
+    - 大文件或二进制数据建议使用文件缓存后端
+    - 在插件卸载时清理相关缓存，避免内存泄漏
+
 
 ## 版本发布