外掛程式權限

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，向使用者展示友善提示或引導到「外掛程式管理 → 管理權限」。