Struct PluginHandle 

pub struct PluginHandle { /* private fields */ }

插件服务句柄，绑定插件身份与配置。 跨平台 struct，通过 Arc 等平台 trait 注入平台代码。 插件通过 HostApi::register() 获取此句柄，后续所有服务调用通过句柄完成。 句柄自动应用注册时的插件配置（如缓存等级），插件无需在每次调用时传递配置。

Implementations

impl PluginHandle

pub fn new( plugin_id: String, config: PluginSdkConfig, capabilities: PlatformCapabilities, theme_provider: Arc<dyn ThemeProvider>, theme_mode: Arc<RwLock<String>>, icon_extractor: Arc<dyn IconExtractor>, icon_cache: Arc<IconCacheService>, shell_executor: Arc<dyn ShellExecutor>, window_manager: Arc<dyn WindowManager>, path_resolver: Arc<dyn PathResolver>, app_enumerator: Arc<dyn AppEnumerator>, app_launcher: Arc<dyn AppLauncher>, lnk_resolver: Arc<dyn LnkResolver>, resource_loader: Arc<dyn ResourceLoader>, parameter_resolver: Arc<dyn ParameterResolver>, timer_manager: Arc<dyn TimerManager>, app_resource: Arc<AppResourceService>, storage: Arc<RwLock<Arc<dyn StorageService>>>, hotkey_manager: Arc<dyn HotkeyManager>, installation_monitor: Arc<dyn InstallationMonitor>, focus_monitor: Arc<dyn FocusMonitor>, clipboard_manager: Arc<dyn ClipboardManager>, model_service: Arc<dyn ModelService>, ) -> Self

Creates a new PluginHandle with all the service references injected.

pub fn plugin_id(&self) -> &str

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

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

根据图标请求提取图标数据，行为由注册时的缓存等级决定。 参数：request - 图标请求（路径/网址/扩展名）。 返回：WebP 格式的图标字节数据（回退路径可能为 PNG），失败返回 HostApiError。

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

提取图标数据，失败时回退到默认图标。 与 get_icon 不同，此方法永不返回错误，提取失败时返回默认图标数据。

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

强制从磁盘提取图标数据并根据缓存等级更新缓存。 与 get_icon 不同，此方法跳过缓存读取，直接提取并更新缓存。 参数：request - 图标请求（路径/网址/扩展名）。 返回：WebP 格式的图标字节数据（回退路径可能为 PNG），失败返回 HostApiError。

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

覆盖指定 IconRequest 的缓存图标为自定义图标文件。 参数：original_request - 需要覆盖图标的原始 IconRequest custom_icon_path - 用户选择的自定义图标文件路径 返回：成功返回 Ok(()), 失败返回 HostApiError

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

使用系统默认方式打开目标（文件/网址/文件夹）。 参数：target - 打开目标。 返回：成功返回 Ok(())，失败返回 HostApiError。

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

在文件资源管理器中打开指定路径的父目录并选中该文件。 参数：path - 要打开所在位置的文件路径。 返回：成功返回 Ok(())，失败返回 HostApiError。

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

以管理员权限启动程序。 参数：path - 要以管理员身份运行的程序路径。 返回：成功返回 Ok(())，失败返回 HostApiError。

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

执行命令字符串（后台运行，无窗口）。 参数：command - 要执行的命令字符串。 返回：成功返回 Ok(())，失败返回 HostApiError。

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

根据进程名（如 “chrome.exe”）激活已存在的窗口。 参数：process_name - 进程名（含扩展名）。 返回：成功激活返回 Ok(true)，未找到窗口返回 Ok(false)，失败返回 HostApiError。

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

根据窗口标题的部分内容激活已存在的窗口。 参数：title - 窗口标题的部分匹配文本。 返回：成功激活返回 Ok(true)，未找到窗口返回 Ok(false)，失败返回 HostApiError。

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

根据进程 PID 激活已存在的窗口。 参数：pid - 进程标识符。 返回：成功激活返回 Ok(true)，未找到窗口返回 Ok(false)，失败返回 HostApiError。

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

根据已知路径类型解析实际文件系统路径。 参数：path - 已知路径类型枚举。 返回：解析后的路径字符串，失败返回 HostApiError。

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

将文本写入系统剪贴板。 参数：text - 要写入的文本内容。 返回：成功返回 Ok(())，失败返回 HostApiError。

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

枚举当前平台已安装的应用。 参数：无。 返回：应用信息列表。

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

启动指定应用。 参数：app_id - 应用唯一标识；args - 启动参数（可选）。 返回：成功返回 Ok(pid)，失败返回 HostApiError。

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

根据名称获取内置图标资源的文件系统路径。 参数：name - 图标名称（如 “tray_icon”, “web_pages” 等）。 返回：图标路径，未注册则返回 None。

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

解析 .lnk 快捷方式文件的目标路径。 参数：lnk_path - .lnk 文件的路径。 返回：解析成功返回目标路径，失败返回 None。

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

解析指定目录下的 desktop.ini 文件，提取 [LocalizedFileNames] 部分。 参数：dir_path - 要解析的目录路径。 返回：从原始文件名到本地化名称的映射。

pub fn update_config(&self, config: PluginSdkConfig)

更新插件的 SDK 配置。 参数：config - 新的插件 SDK 配置。 返回：无。 特性：立即生效，影响后续所有服务调用。

pub fn capabilities(&self) -> &PlatformCapabilities

查询当前平台支持的能力集合。 参数：无。 返回：平台能力的不可变引用。

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

查询宿主当前实际生效的界面主题。 显式 light/dark 配置直接返回；system 模式委托平台读取系统主题。

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

查询系统主题（未应用宿主显式 light/dark 配置），供前端 system 模式跟随。

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 必填，宿主对缺失/未知值返回 InvalidRequest）。

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>

解析参数模板

参数：

• template: 包含占位符的模板字符串
• user_args: 用户输入的参数列表
• snapshot: 系统参数快照（不透明句柄）

返回：填充后的完整字符串

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

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

参数：template - 模板字符串 返回：位置参数的数量

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

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

参数：template - 模板字符串 返回：是否包含系统参数

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

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

参数：

• delay: 触发延迟时长
• callback: 触发时调用的回调函数

返回：TimerId，可用于取消定时器。

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

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

参数：

• interval: 触发间隔时长
• callback: 每次触发时调用的回调函数

返回：TimerId，可用于取消定时器。

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

取消指定 ID 的定时器。

参数：id - 要取消的定时器 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>

直接写入资源字节数据，无需先创建临时文件或提供本地路径。 参数：resource_id - 资源标识符；data - 资源字节内容。 返回：成功返回 Ok(())，失败返回 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>

写入插件本地缓存。 参数：domain - 缓存域（按用途隔离，如 “model-embedding”）；key - 缓存键；data - 缓存字节内容。 返回：成功返回 Ok(())。 与 resource_* 的区别：缓存存放可再生的本地数据（如模型向量）， 不经过 StorageService，WebDAV 同步模式不会上传远端； 路径为 <app_data>/plugin-cache/<plugin_id>//。

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 时按修改时间删除最旧条目。 目录结构 <cache_root>/<plugin_id>//<sha前2>/.bin（两级分片）。 参数：domain - 缓存域；max_entries - 条目数上限。 返回：成功返回 Ok(())（目录不存在视为无需清理）。

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

注册按键事件回调。 参数：id - 回调标识（自动前缀化为 “{plugin_id}:{id}”）；filter - 事件过滤器；callback - 回调函数。

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

注销按键事件回调。 参数：id - 回调标识（自动前缀化为 “{plugin_id}:{id}”）。

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

注册安装事件回调。 参数：id - 回调标识（自动前缀化为 “{plugin_id}:{id}”）；callback - 回调函数。

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

注销安装事件回调。 参数：id - 回调标识（自动前缀化为 “{plugin_id}:{id}”）。

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

注册焦点事件回调。 参数：id - 回调标识（自动前缀化为 “{plugin_id}:{id}”）；callback - 回调函数。

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

注销焦点事件回调。 参数：id - 回调标识（自动前缀化为 “{plugin_id}:{id}”）。