权限系统 | xbot

本文档的英文版本包含完整的代码示例和 API 参考。请参阅 English version 获取完整内容。

本文档提供权限系统的中文概览。详细的 API 参考和代码示例请参阅英文版本。

xbot’s plugin permission system provides fine-grained capability control. Plugins declare required permissions in plugin.json and can only access the APIs they declare.

How It Works

Declaration: Plugins list required permissions in plugin.json:

{
  "permissions": ["tools.register", "ui.contribute", "storage"]
}

Validation: During manifest loading, permissions are validated against the known list. Unknown permissions are rejected.
Enforcement: At runtime, PluginContext wraps every method call with a PermissionChecker. Undeclared permissions return an error.

Permission List

Backend (Go) Permissions

Permission	Description	PluginContext Methods
`tools.register`	Register tools for the LLM	`RegisterTool`, `RegisterTools`, `UseMiddleware`
`hooks.register`	Register lifecycle hooks	`OnPreToolUse`, `OnPostToolUse`, `OnUserPrompt`, `OnAgentStop`, `OnSessionStart`, `OnSessionEnd`, `OnEvent`, `OnAllToolUse`, `OnError`
`bus.read`	Subscribe to event bus	`Subscribe`
`bus.write`	Publish to event bus	`Publish`
`bus.plugin`	Plugin-to-plugin events	Requires `bus.read` + `bus.write`
`ui.contribute`	Contribute UI widgets	`ContributeUI`, `UpdateWidget`, `RegisterWebActionHandler`
`ui.themes`	Contribute themes	`ContributeTheme`
`channels.register`	Register channel providers	Channel provider registration
`storage`	Access per-plugin KV storage	`Storage`, `StorageInt`, `StorageBool`, `StorageJSON`, `StorageGetJSON`
`cron`	Schedule cron jobs	`ScheduleCron`

Frontend (Web) Permissions

Permission	Description	Context API
`rpc`	Make RPC calls to the backend	`ctx.rpc`
`ui`	Access UI API (open views, tabs)	`ctx.ui`
`events`	Access event bus	`ctx.events`
`commands`	Register and execute commands	`ctx.commands`
`state`	Access shared state	`ctx.state`
`plugins`	Access plugin management API	`ctx.plugins`
`config`	Access configuration API	`ctx.config`

PermissionChecker

The PermissionChecker (plugin/permissions.go) validates permissions:

type PermissionChecker struct {
    permissions map[string]bool
}

func NewPermissionChecker(permissions []string) *PermissionChecker

func (pc *PermissionChecker) Has(permission string) bool
func (pc *PermissionChecker) HasAll(permissions ...string) bool
func (pc *PermissionChecker) HasAny(permissions ...string) bool

Validation

During manifest loading, validateManifest checks that all declared permissions are valid:

func IsValidPermission(perm string) bool
func AllPermissions() []string

Unknown permissions cause manifest validation to fail, preventing the plugin from loading.

Best Practices

Declare only what you need: Minimize the permission surface
Don’t request bus.plugin unless you need both read and write: Use bus.read or bus.write individually
Frontend permissions are separate: Web plugins use a different permission set (rpc, ui, events, etc.)
Permissions are not hierarchical: ui.contribute does not imply ui.themes