插件上下文調用

PluginContext 向插件提供了以下能力：

• page: 當前 Flet Page 實例，可用於構建 UI 控件或註冊事件。
• register_navigation(view): 註冊一個主導航視圖（見下文）。
• register_route(view): 註冊一個附加路由，通過 page.go() 訪問。
• register_startup_hook(hook): 註冊應用啟動後執行的回調。
• set_initial_route(route): 可選地改變初始路由。
• logger: 已綁定插件 identifier 的 loguru.Logger，直接 logger.info("...") 即可。
• metadata: 字典，可用於在插件及核心系統之間傳遞額外信息；也可通過 context.add_metadata(key, value) 輔助寫入。
• 全局數據接口：
  • register_data_namespace(identifier, *, description="", permission=None)：註冊命名空間，聲明數據歸屬以及訪問權限。
  • publish_data(namespace_id, entry_id, payload)：寫入 / 更新命名空間中的數據條目。
  • latest_data(namespace_id) / get_data(namespace_id, entry_id) / list_data(namespace_id)：讀取共享數據快照，需被授予命名空間所要求的權限。
• 存儲路徑工廠：plugin_data_path、plugin_config_path、plugin_cache_path 以及對應的 *_dir 方法用於訪問 / 初始化插件專屬的數據、配置、緩存目錄。傳入 create=True 時會確保目錄存在。
• add_bing_action(factory): 在「資源 → Bing 每日」操作行追加自定義按鈕或其他控件。
• add_spotlight_action(factory): 在「資源 → Windows 聚焦」操作行追加控件。
• register_settings_page(label, builder, *, icon=None, button_label="插件設置", description=None): 註冊插件的專屬設置頁面。插件管理面板會在對應插件卡片中顯示一個「插件設置」按鈕，並在新頁面中渲染 builder 返回的控件。
• 收藏管理接口（核心插件激活後可用，需在 manifest 中聲明並獲批對應的 favorites_* 權限；使用前可通過 context.has_favorite_support() 判斷）：
  • context.favorites：返回 FavoriteService 實例，包裹了全部收藏操作並在內部執行權限校驗。歷史屬性 context.favorite_manager 仍可用，但會返回同一服務實例。
  • 讀取：favorites.list_folders() / favorites.get_folder(id) / favorites.list_items(folder_id="__all__") / favorites.get_item(item_id) / favorites.find_by_source(source)（需 favorites_read）。
  • 寫入：favorites.create_folder(...)、favorites.update_folder(...)、favorites.delete_folder(...)、favorites.add_or_update_item(...)、favorites.update_item(...)、favorites.remove_item(...)、favorites.register_classifier(...)、favorites.classify_item(...)（需 favorites_write）。
  • 導入導出：favorites.export_folders(target_path, folder_ids=None, include_assets=True)、favorites.import_package(path)、favorites.localize_items_from_files(mapping)、favorites.localization_root()（需 favorites_export）。 相關數據類型（FavoriteSource、FavoriteItem 等）可直接從 app.plugins 導入。 相關數據類型（FavoriteSource、FavoriteItem 等）可直接從 app.plugins 導入。
• 系統操作接口（返回 PluginOperationResult，詳見下文）：
  • open_route(route: str): 請求跳轉到指定路由。需聲明並獲得 app_route 權限。
  • switch_home(navigation_id: str): 切換首頁側邊欄導航項（例如 home、resource）。需 app_home 權限。
  • open_settings_tab(tab: int): 打開設置頁並定位到指定標籤（按設置tabs順序，從0開始）。需 app_settings 權限。
  • set_wallpaper(path: str): 將本地圖片設置為系統壁紙。需 wallpaper_control 權限。
  • ipc_broadcast(channel: str, payload: dict): 通過跨進程廣播發布消息。需 ipc_broadcast 權限。
  • ipc_subscribe(channel: str): 訂閱跨進程廣播頻道，成功時結果的 data 為 IPCSubscription 對象，可調用 .get() 讀取隊列消息。
  • ipc_unsubscribe(subscription_id: str): 取消訂閱，傳入 ipc_subscribe 返回的訂閱 ID。