zerolaunch_plugin_api/plugin/
plugin_trait.rs

1use crate::config::configurable::Configurable;
2use crate::host::plugin_handle::PluginHandle;
3use crate::plugin::types::{
4    PanelInteraction, PluginContext, PluginError, PluginMetadata, Query, QueryResponse,
5};
6use async_trait::async_trait;
7use std::sync::Arc;
8
9/// 所有插件对象都需实现的核心契约。
10/// 服务于插件生命周期管理、查询处理与动作执行。
11/// 配置管理能力由 Configurable trait 提供。
12#[async_trait]
13pub trait Plugin: Configurable {
14    fn metadata(&self) -> &PluginMetadata;
15
16    /// 插件初始化钩子。
17    ///
18    /// `handle` 为宿主注入的平台服务句柄：进程内（内置）插件持有
19    /// `Some(Arc<PluginHandle>)`；远端插件进程无宿主句柄（跨进程不可序列化），
20    /// 收到 `None`，平台能力经 SDK `host()` 的 host/* RPC 访问。
21    async fn init(
22        &self,
23        ctx: &PluginContext,
24        handle: Option<Arc<PluginHandle>>,
25    ) -> Result<(), PluginError>;
26
27    async fn query(&self, ctx: &PluginContext, query: &Query)
28        -> Result<QueryResponse, PluginError>;
29
30    /// 执行插件动作。
31    /// `action_id` 为插件在 `ListItem.actions` / `CustomPanel.actions` / 面板按键
32    /// 绑定中声明的动作标识；`payload` 形状由触发通道决定（插件应两种都兼容）：
33    /// - 候选确认通道（搜索栏结果列表 / 行内参数 / 参数面板确认）：
34    ///   `{"candidate_id": <u64>, "query_text": <str>, "user_args": [<str>]}`；
35    /// - 面板动作通道（`PanelKeyAction::Custom` 面板按键绑定）：插件自定义自由 JSON，
36    ///   宿主原样透传。
37    async fn execute_action(
38        &self,
39        ctx: &PluginContext,
40        action_id: &str,
41        payload: serde_json::Value,
42    ) -> Result<(), PluginError>;
43
44    /// 返回插件当前生效的交互策略（防抖延迟、提交行为等）。
45    /// 这是一次快速、同步的调用，不涉及 IO 或网络。
46    /// 默认返回无防抖、Execute 提交的交互策略。
47    fn interaction_policy(&self) -> PanelInteraction {
48        PanelInteraction::default()
49    }
50}
zerolaunch_plugin_api/plugin/plugin_trait.rs

zerolaunch_plugin_api/plugin/
plugin_trait.rs
