add: 如何扩展探索功能的媒体数据源

README.md

@@ -526,7 +526,74 @@ def get_dashboard(self, key: str, **kwargs) -> Optional[Tuple[Dict[str, Any], Di
     pass
 ```
 
-### 9. 如何发布插件版本？
+### 9. 如何扩展探索功能的媒体数据源（仅V2版本）？
+- 探索功能仅内置`TheMovieDb`、`豆瓣`和`Bangumi`数据源，`v2.2.7+`版本可通过插件扩展探索功能的数据源范围，按以下方法开发插件：
+- 1. 实现`ChainEventType.DiscoverSource`链式事件响应，将额外的媒体数据源塞入事件数据`extra_sources`数组中（注意：如果事件中已经有其它数据源，需要叠加而不是替换，避免影响其它插件塞入的数据）
+  
+  - `name`：数据源名称
+
+  - `mediaid_prefix`：数据源的唯一ID
+
+  - `api_path`：数据获取API相对路径，需要在插件中实现API接口功能，GET模式接收过滤参数（注意：page参数默认需要有），返回`List[schemas.MediaInfo])`格式数据（注意：mediaid_prefix和media_id需要赋值，用于唯一索引媒体详细信息和转换媒体数据），参考`app/api/endpoints/tmdb.py` 中的 `tmdb_movies`。
+
+  - `filter_params`：数据源过滤参数名的字典，相关参数会传入插件API的GET请求中
+
+  - `filter_ui`：数据过滤选项的UI配置json，与插件配置表单方式一致
+
+```python
+class DiscoverMediaSource(BaseModel):
+    """
+    探索媒体数据源的基类
+    """
+    name: str = Field(..., description="数据源名称")
+    mediaid_prefix: str = Field(..., description="媒体ID的前缀，不含:")
+    api_path: str = Field(..., description="媒体数据源API地址")
+    filter_params: Optional[Dict[str, Any]] = Field(default=None, description="过滤参数")
+    filter_ui: Optional[List[dict]] = Field(default=[], description="过滤参数UI配置")
+
+class DiscoverSourceEventData(ChainEventData):
+    """
+    DiscoverSource 事件的数据模型
+
+    Attributes:
+        # 输出参数
+        extra_sources (List[DiscoverMediaSource]): 额外媒体数据源
+    """
+    # 输出参数
+    extra_sources: List[DiscoverMediaSource] = Field(default_factory=list, description="额外媒体数据源")
+```
+
+- 2. 实现`ChainEventType.MediaRecognizeConvert`链式事件响应，根据媒体ID和转换类型，返回TheMovieDb或豆瓣的媒体数据，将转换后的数据注入事件数据`media_dict`中，可参考`app/chain/media.py`中的`get_tmdbinfo_by_bangumiid`。
+
+  - `mediaid`：媒体ID，格式为`mediaid_prefix:media_id`，如 tmdb:12345、douban:1234567
+
+  - `convert_type`：转换类型，仅支持：themoviedb/douban，需要转换为对应的媒体数据并返回
+
+  - `media_dict`：转换后的媒体数据，格式为`TheMovieDb/豆瓣`的媒体数据
+
+```python
+class MediaRecognizeConvertEventData(ChainEventData):
+    """
+    MediaRecognizeConvert 事件的数据模型
+
+    Attributes:
+        # 输入参数
+        mediaid (str): 媒体ID，格式为`前缀:ID值`，如 tmdb:12345、douban:1234567
+        convert_type (str): 转换类型 仅支持：themoviedb/douban，需要转换为对应的媒体数据并返回
+
+        # 输出参数
+        media_dict (dict): TheMovieDb/豆瓣的媒体数据
+    """
+    # 输入参数
+    mediaid: str = Field(..., description="媒体ID")
+    convert_type: str = Field(..., description="转换类型（themoviedb/douban）")
+
+    # 输出参数
+    media_dict: dict = Field(default=dict, description="转换后的媒体信息（TheMovieDb/豆瓣）")
+```
+- 3. 启用插件后，点击探索功能将自动生成额外的数据源标签及页面，页面中选择不同的过滤条件时会重新触发API请求。
+
+### 10. 如何发布插件版本？
 - 修改插件代码后，需要修改`package.json`中的`version`版本号，MoviePilot才会提示用户有更新，注意版本号需要与`__init__.py`文件中的`plugin_version`保持一致。
 - `package.json`中的`level`用于定义插件用户可见权限，`1`为所有用户可见，`2`为仅认证用户可见，`3`为需要密钥才可见（一般用于测试）。如果插件功能需要使用到站点则应该为2，否则即使插件对用户可见但因为用户未认证相关功能也无法正常使用。
 - `package.json`中的`history`用于记录插件更新日志，格式如下：
@@ -540,6 +607,6 @@ def get_dashboard(self, key: str, **kwargs) -> Optional[Tuple[Dict[str, Any], Di
 ```
 - 新增加的插件请配置在`package.json`中的末尾，这样可被识别为最新增加，可用于用户排序。
 
-### 10. 如何开发V2版本的插件以及实现插件多版本兼容？
+### 11. 如何开发V2版本的插件以及实现插件多版本兼容？
 
 - 请参阅 [V2版本插件开发指南](./docs/V2_Plugin_Development.md)