zerolaunch_plugin_api/config/
configurable.rs

1use crate::config::action::ConfigActionDef;
2use crate::config::component_core::ComponentCore;
3use crate::config::component_type::ComponentType;
4use crate::config::error::ConfigError;
5use crate::config::setting_def::{SettingDefinition, SettingsContribution};
6use async_trait::async_trait;
7
8/// 所有可配置组件都需实现的核心契约。
9///
10/// 提供组件标识、配置定义、配置读写和配置变更回调能力。
11#[async_trait]
12pub trait Configurable: Send + Sync {
13    /// 返回组件身份核心。
14    ///
15    /// 实现者只需提供对 `ComponentCore` 的引用，identity 相关方法即可使用默认实现。
16    fn core(&self) -> &ComponentCore;
17
18    fn component_id(&self) -> &str {
19        self.core().component_id()
20    }
21
22    fn component_name(&self) -> &str {
23        self.core().component_name()
24    }
25
26    fn component_type(&self) -> ComponentType {
27        self.core().component_type()
28    }
29
30    /// 组件显示排序优先级，数值越小越靠前。
31    fn priority(&self) -> u32 {
32        self.core().priority()
33    }
34
35    /// 组件的功能描述文本，用于设置面板中向用户解释该组件的用途。
36    fn component_description(&self) -> &str {
37        self.core().component_description()
38    }
39
40    /// 返回组件的设置项 schema 定义列表。
41    ///
42    /// 组件实现者在此方法中通过 `SchemaBuilder` 声明所有配置字段。
43    /// 默认返回空列表。
44    fn setting_schema(&self) -> Vec<SettingDefinition>;
45
46    /// 将 `setting_schema()` 的输出编译为 `SettingsContribution`。
47    ///
48    /// 内含 schema 校验（重复 key、UI pointer 一致性、约束合法性等）。
49    /// 默认实现调用 `SettingsContribution::from_entries()`。
50    fn settings_contribution(&self) -> Result<SettingsContribution, ConfigError> {
51        SettingsContribution::from_entries(self.setting_schema())
52            .map_err(ConfigError::ValidationFailed)
53    }
54
55    /// 获取组件当前的配置值（JSON 格式）。
56    fn get_settings(&self) -> serde_json::Value {
57        serde_json::json!({})
58    }
59
60    /// 应用配置到组件。
61    /// 使用 &self 签名，组件内部通过 RwLock 等实现可变性。
62    /// async：远端插件（RemoteComponent）实现需经 RPC 下发配置到插件进程。
63    async fn apply_settings(&self, settings: serde_json::Value) -> Result<(), ConfigError> {
64        let _ = settings;
65        Ok(())
66    }
67
68    /// 校验一组配置值是否合法（不会实际应用）。
69    /// async：远端插件实现需经 RPC 委托插件进程补充业务校验。
70    async fn validate_settings(&self, settings: &serde_json::Value) -> Result<(), ConfigError> {
71        let contribution = self.settings_contribution()?;
72        // 组件无 schema 字段时，允许 settings 为 null（等价于空对象）。
73        if contribution.properties.is_empty() && settings.is_null() {
74            return Ok(());
75        }
76        contribution
77            .validate_values(settings)
78            .map_err(ConfigError::ValidationFailed)
79    }
80
81    fn get_default_settings(&self) -> serde_json::Value {
82        match self.settings_contribution() {
83            Ok(c) => c.default_settings(),
84            Err(e) => {
85                tracing::warn!("获取默认设置失败: {}", e);
86                serde_json::Value::Object(serde_json::Map::new())
87            }
88        }
89    }
90
91    fn on_settings_changed(&self) {}
92
93    /// 返回该组件支持的配置动作定义列表。
94    /// 配置动作用于在设置面板中提供一键式辅助操作（如自动检测浏览器），
95    /// 前端据此渲染操作按钮，用户点击后通过 execute_config_action 执行。
96    fn config_actions(&self) -> Vec<ConfigActionDef> {
97        Vec::new()
98    }
99
100    /// 执行配置动作。
101    /// 参数：action - 动作标识符，对应 ConfigActionDef.action。
102    ///       params - 前端传递的附加参数（如书签文件路径）。
103    /// 返回：动作执行结果（JSON 格式），由前端根据配置项类型解析并填充。
104    async fn execute_config_action(
105        &self,
106        action: &str,
107        params: &serde_json::Value,
108    ) -> Result<serde_json::Value, String> {
109        let _ = params;
110        Err(format!("Unknown config action: {}", action))
111    }
112
113    /// 返回组件的默认启用状态。
114    /// 某些组件可能默认禁用（如实验性功能）。
115    /// 实际启用状态由 ConfigManager 管理，用户设置会覆盖此默认值。
116    fn default_enabled(&self) -> bool {
117        true
118    }
119}
zerolaunch_plugin_api/config/configurable.rs

zerolaunch_plugin_api/config/
configurable.rs
