Struct PluginHandle 

pub struct PluginHandle { /* private fields */ }

插件服务句柄（插件接口层）。 绑定插件身份（plugin_id）、配置（PluginSdkConfig）与能力集，并持有宿主操作契约 Arc<dyn PluginHost>；所有服务操作委托宿主执行，宿主内部再决定直接处理或 转发平台实现。插件通过 HostApi::register() 获取此句柄。

Implementations

impl PluginHandle

pub fn new( plugin_id: String, config: PluginSdkConfig, capabilities: PlatformCapabilities, host: Arc<dyn PluginHost>, ) -> Self

绑定插件身份与宿主契约构造句柄。 参数：plugin_id - 插件唯一标识；config - 插件 SDK 配置； capabilities - 平台能力集；host - 宿主操作契约实现。

pub fn plugin_id(&self) -> &str

返回当前插件 ID（宿主模型缓存等按插件隔离目录需要）。

pub fn update_config(&self, config: PluginSdkConfig)

更新插件的 SDK 配置，立即生效，影响后续所有服务调用。

pub fn capabilities(&self) -> &PlatformCapabilities

查询当前平台支持的能力集合。

pub async fn get_icon( &self, request: IconRequest, ) -> Result<Vec<u8>, HostApiError>

根据图标请求提取图标数据，行为由注册时的缓存等级决定。

pub async fn get_icon_or_default(&self, request: IconRequest) -> Vec<u8>

提取图标数据，失败时回退到默认图标（永不返回错误）。

pub async fn get_icon_and_update_cache( &self, request: IconRequest, ) -> Result<Vec<u8>, HostApiError>

强制从磁盘提取图标数据并根据缓存等级更新缓存。

pub async fn override_icon_cache( &self, original_request: &IconRequest, custom_icon_path: &str, ) -> Result<(), HostApiError>

覆盖指定 IconRequest 的缓存图标为自定义图标文件。

pub async fn shell_open(&self, target: OpenTarget) -> Result<(), HostApiError>

使用系统默认方式打开目标（文件/网址/文件夹）。

pub async fn shell_open_folder(&self, path: &str) -> Result<(), HostApiError>

在文件资源管理器中打开指定路径的父目录并选中该文件。

pub async fn shell_execute_elevation( &self, path: &str, ) -> Result<(), HostApiError>

以管理员权限启动程序。

pub async fn shell_execute_command( &self, command: &str, ) -> Result<(), HostApiError>

执行命令字符串（后台运行，无窗口）。

pub async fn activate_window_by_process( &self, process_name: &str, ) -> Result<bool, HostApiError>

根据进程名（如 “chrome.exe”）激活已存在的窗口。

pub async fn activate_window_by_title( &self, title: &str, ) -> Result<bool, HostApiError>

根据窗口标题的部分内容激活已存在的窗口。

pub async fn activate_window_by_pid( &self, pid: u32, ) -> Result<bool, HostApiError>

根据进程 PID 激活已存在的窗口。

pub fn resolve_path(&self, path: KnownPath) -> Result<String, HostApiError>

根据已知路径类型解析实际文件系统路径。

pub fn set_clipboard_text(&self, text: &str) -> Result<(), HostApiError>

将文本写入系统剪贴板。

pub async fn enumerate_apps(&self) -> Vec<AppInfo>

枚举当前平台已安装的应用。

pub async fn launch_app( &self, app_id: &str, args: Option<&[String]>, ) -> Result<u32, HostApiError>

启动指定应用。

pub fn get_app_icon_path(&self, name: &str) -> Option<String>

根据名称获取内置图标资源的文件系统路径。

pub fn resolve_lnk_target(&self, lnk_path: &str) -> Option<String>

解析 .lnk 快捷方式文件的目标路径。

pub fn parse_localized_names_from_dir( &self, dir_path: &Path, ) -> HashMap<String, String>

解析指定目录下的 desktop.ini 文件，提取 [LocalizedFileNames] 部分。

pub fn get_theme(&self) -> Result<Theme, HostApiError>

查询宿主当前实际生效的界面主题（system 模式由宿主解析）。

pub fn get_system_theme(&self) -> Result<Theme, HostApiError>

查询系统主题（未应用宿主显式 light/dark 配置）。

pub fn model_list(&self) -> Vec<ModelInfo>

全网模型清单（聚合缓存，含所有已注册提供方）。

pub async fn model_chat( &self, req: ModelChatRequest, ) -> Result<ModelChatResponse, ModelError>

按 model_id 调用文本生成。

pub async fn model_embedding( &self, req: ModelEmbeddingRequest, ) -> Result<ModelEmbeddingResponse, ModelError>

按 model_id 调用文本向量化（task_type 必填）。

pub async fn model_similarity( &self, req: ModelSimilarityRequest, ) -> Result<ModelSimilarityResponse, ModelError>

按 model_id 计算查询向量与多个目标向量的相似度。

pub async fn resolve_parameters( &self, template: &str, user_args: &[String], snapshot: &ParameterSnapshot, ) -> Result<String, HostApiError>

解析参数模板。

pub fn count_user_parameters(&self, template: &str) -> usize

统计模板中需要用户输入的参数数量。

pub fn has_system_parameters(&self, template: &str) -> bool

检查模板是否包含系统参数。

pub async fn set_timeout( &self, delay: Duration, callback: TimerCallback, ) -> Result<TimerId, HostApiError>

创建一个一次性定时器，在指定延迟后触发回调。

pub async fn set_interval( &self, interval: Duration, callback: TimerCallback, ) -> Result<TimerId, HostApiError>

创建一个重复定时器，每隔指定间隔触发回调。

pub async fn cancel_timer(&self, id: TimerId) -> Result<(), HostApiError>

取消指定 ID 的定时器。

pub async fn cancel_all_timers(&self) -> Result<(), HostApiError>

取消所有定时器。

pub async fn resource_upload( &self, resource_id: &str, file_path: &str, max_size: Option<u64>, ) -> Result<String, HostApiError>

上传资源文件到本插件的资源空间。

pub async fn resource_put( &self, resource_id: &str, data: &[u8], ) -> Result<(), HostApiError>

直接写入资源字节数据，无需先创建临时文件或提供本地路径。

pub async fn resource_get( &self, resource_id: &str, ) -> Result<Vec<u8>, HostApiError>

获取资源文件内容。

pub async fn resource_delete( &self, resource_id: &str, ) -> Result<(), HostApiError>

删除资源文件。

pub async fn resource_list(&self) -> Result<Vec<String>, HostApiError>

列出本插件的所有资源。

pub async fn cache_put( &self, domain: &str, key: &str, data: &[u8], ) -> Result<(), HostApiError>

写入插件本地缓存。 与 resource_* 的区别：缓存存放可再生的本地数据（如模型向量）， 不经过 StorageService，仅落在本地缓存目录。

pub async fn cache_get( &self, domain: &str, key: &str, ) -> Result<Option<Vec<u8>>, HostApiError>

读取插件本地缓存；缓存不存在时返回 Ok(None)。

pub async fn cache_delete( &self, domain: &str, key: &str, ) -> Result<(), HostApiError>

删除插件本地缓存条目；缓存不存在时视为成功。

pub async fn cache_cleanup( &self, domain: &str, max_entries: usize, ) -> Result<(), HostApiError>

容量控制：缓存域条目超过 max_entries 时按修改时间删除最旧条目。

pub fn register_hotkey_callback( &self, id: &str, filter: HotkeyEventFilter, callback: HotkeyCallback, )

注册按键事件回调。ID 自动前缀化为 “{plugin_id}:{id}”。

pub fn unregister_hotkey_callback(&self, id: &str)

注销按键事件回调。

pub fn register_installation_callback( &self, id: &str, callback: InstallationCallback, )

注册安装事件回调。ID 自动前缀化为 “{plugin_id}:{id}”。

pub fn unregister_installation_callback(&self, id: &str)

注销安装事件回调。

pub fn register_focus_callback(&self, id: &str, callback: FocusCallback)

注册焦点事件回调。ID 自动前缀化为 “{plugin_id}:{id}”。

pub fn unregister_focus_callback(&self, id: &str)

注销焦点事件回调。