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    /// 返回组件运行态快照（非用户配置：不写入 settings、不下发前端、不参与远端配置同步）。
92    ///
93    /// 适用于需要在重启后延续统计/状态的**宿主内置组件**（写入独立的运行态文件）。
94    /// 默认 None 表示该组件无运行态需要持久化；第三方插件组件（远端进程）不参与
95    /// 本通道——它们经 SDK 的 `resource_*` / `cache_*` / `ZEROLAUNCH_DATA_DIR` 自行持久化。
96    fn runtime_state(&self) -> Option<serde_json::Value> {
97        None
98    }
99
100    /// 从持久化的运行态恢复组件内部状态。
101    ///
102    /// 由 ConfigManager 在 `load_from_storage` 内对**当时已注册**的组件调用一次
103    /// （内置组件在 Phase A 注册，故恢复先于搜索管道构建）；配置加载之后才注册的
104    /// 组件（第三方插件组件）不经过本方法。默认空实现。
105    fn restore_runtime_state(&self, state: serde_json::Value) {
106        let _ = state;
107    }
108
109    fn on_settings_changed(&self) {}
110
111    /// 返回该组件支持的配置动作定义列表。
112    /// 配置动作用于在设置面板中提供一键式辅助操作（如自动检测浏览器），
113    /// 前端据此渲染操作按钮，用户点击后通过 execute_config_action 执行。
114    fn config_actions(&self) -> Vec<ConfigActionDef> {
115        Vec::new()
116    }
117
118    /// 执行配置动作。
119    /// 参数：action - 动作标识符，对应 ConfigActionDef.action。
120    ///       params - 前端传递的附加参数（如书签文件路径）。
121    /// 返回：动作执行结果（JSON 格式），由前端根据配置项类型解析并填充。
122    async fn execute_config_action(
123        &self,
124        action: &str,
125        params: &serde_json::Value,
126    ) -> Result<serde_json::Value, String> {
127        let _ = params;
128        Err(format!("Unknown config action: {}", action))
129    }
130
131    /// 返回组件的默认启用状态。
132    /// 某些组件可能默认禁用（如实验性功能）。
133    /// 实际启用状态由 ConfigManager 管理，用户设置会覆盖此默认值。
134    fn default_enabled(&self) -> bool {
135        true
136    }
137}
zerolaunch_plugin_api/config/configurable.rs

zerolaunch_plugin_api/config/
configurable.rs
