插件權限 – 小树工作室文档中心

插件權限

Little Tree Wallpaper Next 插件 API 中提供了權限控制，用於限制插件訪問受保護的數據。插件需要在 PluginManifest 中聲明所需權限，系統會在插件啟用前請求用戶授權。

權限狀態與策略

應用在持久化層面支持三種決策：

允許（granted）：永久授予能力，後續調用不會再彈出提示。
拒絕（denied）：直接拒絕能力，相關 API 會返回 permission_denied 或拋出 PluginPermissionError。
下次詢問（prompt）：在下一次實際調用時彈出權限對話框，由用戶臨時決定。

當狀態為「下次詢問」時，調用線程會阻塞直到用戶處理提示。用戶選擇「稍後決定」不會改變存儲狀態，後續再次調用仍會彈窗。

Important

插件導入時還可能根據源碼中的 import 語句生成動態的 python_import:* 子權限，以便用戶審核依賴。

標識符	說明
`filesystem`	允許插件訪問應用數據目錄之外的本地文件。
`network`	允許插件發起自定義網絡請求。
`clipboard`	允許插件讀取或寫入系統剪貼板。
`wallpaper`	允許插件設置或刪除系統壁紙。
`resource_data`	允許插件接收資源頁提供的壁紙元數據。
`python_import`	允許插件在運行時加載額外的 Python 模塊或依賴。
`app_route`	允許插件請求跳轉到任意已註冊的應用路由。
`app_home`	允許插件切換首頁導航。
`app_settings`	允許插件打開設置頁並定位標籤。
`wallpaper_control`	允許插件觸發內置壁紙操作（Bing / Windows 聚焦）。
`ipc_broadcast`	允許插件通過內置 IPC 服務訂閱、發送跨進程廣播消息。
`favorites_read`	允許插件讀取收藏夾及收藏條目。
`favorites_write`	允許插件創建、修改或刪除收藏夾與條目。
`favorites_export`	允許插件導入 / 導出收藏數據、訪問本地化資源。

系統操作（如 context.open_route） 始終通過應用層 _ensure_permission，未授權時自動彈出對話框。
收藏 API、全局數據等延遲校驗能力 現在會在權限為 prompt 時觸發同樣的對話框：
- PluginContext.ensure_permission() 會在遇到 prompt 狀態時調用宿主並阻塞等待用戶選擇。
- FavoriteService 等包裝類復用了上述邏輯，因此在「下次詢問」狀態下再次訪問會正常彈窗。
事件總線與全局數據讀取 會在缺少授權時靜默跳過，以免在高頻事件下反覆彈窗。插件可通過 context.request_permission() 主動引導授權。

在執行需要授權的操作前，使用 context.has_permission("xxx") 快速檢查是否已授予。
若需要在運行時提示用戶，調用 context.request_permission("xxx", message="...說明...")。message 會顯示在系統彈窗內，幫助用戶理解申請原因。
捕獲 PluginPermissionError，向用戶展示友好提示或引導到「插件管理 → 管理權限」。