Plugin Permissions

Little Tree Wallpaper Next plugin API provides permission control,用于限制插件访问受保护的数据。插件需要在 PluginManifest 中声明所需权限，系统会在插件启用前请求用户授权。

Permission Status and Policies

The application supports three decisions at the persistence level:

Granted: Permanently grant capability, subsequent calls will not show prompts.
Denied: Directly deny capability, related APIs will return permission_denied or throw PluginPermissionError.
Prompt: Show permission dialog on next actual call, letting user decide temporarily.

When status is “Prompt”, the calling thread will block until user handles the prompt. User choosing “Decide Later” won’t change the stored status, subsequent calls will still show dialogs.

Known Permission List

Important

插件导入时还可能根据源码中的 import 语句生成动态的 python_import:* 子权限，以便用户审核依赖。

Identifier	Description
`filesystem`	Allow plugins to access local files outside the application data directory.
`network`	Allow plugins to initiate custom network requests.
`clipboard`	Allow plugins to read or write system clipboard.
`wallpaper`	Allow plugins to set or delete system wallpapers.
`resource_data`	Allow plugins to receive wallpaper metadata provided by the resource page.
`python_import`	Allow plugins to load additional Python modules or dependencies at runtime.
`app_route`	Allow plugins to request navigation to any registered application route.
`app_home`	Allow plugins to switch homepage navigation.
`app_settings`	Allow plugins to open settings page and locate tabs.
`wallpaper_control`	Allow plugins to trigger built-in wallpaper operations (Bing / Windows Spotlight).
`ipc_broadcast`	Allow plugins to subscribe to and send cross-process broadcast messages through built-in IPC services.
`favorites_read`	Allow plugins to read favorites and favorite items.
`favorites_write`	Allow plugins to create, modify, or delete favorites and items.
`favorites_export`	Allow plugins to import/export favorite data and access localization resources.

Runtime Authorization Flow

System operations (like context.open_route) always go through application layer _ensure_permission, automatically showing dialogs when unauthorized.
Favorites API, global data and other delayed validation capabilities will now trigger the same dialog when permission is prompt:
- PluginContext.ensure_permission() will call the host and block waiting for user choice when encountering prompt status.
- Wrapper classes like FavoriteService reuse the above logic, so accessing again in “prompt” state will normally show dialogs.
Event bus and global data reading will silently skip when lacking authorization, to avoid repeated dialogs in high-frequency events. Plugins can actively guide authorization through context.request_permission().

Plugin-side Best Practices

Before executing operations requiring authorization, use context.has_permission("xxx") to quickly check if already granted.
If needing to prompt users at runtime, call context.request_permission("xxx", message="...explanation..."). message will be displayed in the system dialog, helping users understand the application reason.
Catch PluginPermissionError, show friendly prompts to users or guide them to “Plugin Management → Manage Permissions”.

Management Side Tips

The “Manage Permissions” dialog in the plugin management page can still batch adjust the above states.
When the background detects a permission being denied, a reminder containing the plugin name and permission name will pop up in the status bar,方便定位问题。

Plugin Context Calls Plugin Publishing Metadata Protocol