archipelago
7ba3109b6d
git-subtree-dir: aiui git-subtree-mainline:0c4826f8ccgit-subtree-split:e30ac1d106
99 lines
3.3 KiB
Plaintext
99 lines
3.3 KiB
Plaintext
---
|
|
description: Plugin architecture rules - interfaces, registration, lifecycle, sandboxing
|
|
globs: "**/plugins/**,**/*.plugin.ts"
|
|
alwaysApply: false
|
|
---
|
|
|
|
# Plugin System
|
|
|
|
## Philosophy
|
|
Every external integration connects through a typed plugin interface. No direct coupling to any service, provider, or protocol.
|
|
|
|
## Plugin Types
|
|
```typescript
|
|
type PluginType =
|
|
| 'ai-provider' // LLM backends (OpenRouter, Ollama, Claude, etc.)
|
|
| 'media-source' // Content sources (Plex, YouTube, Nextcloud, Archive.org)
|
|
| 'messaging' // Chat protocols (Nostr, Matrix, local)
|
|
| 'storage' // File storage (local FS, IPFS, Nextcloud)
|
|
| 'renderer' // Custom content renderers
|
|
| 'file-handler' // File open/preview handlers
|
|
| 'crypto' // Encryption providers
|
|
| 'search' // Search backends (SearXNG, local)
|
|
| 'auth' // Authentication (Nostr keys, DID, passkeys)
|
|
| 'wallet' // Bitcoin wallet deep-linking (Phoenix, Zeus, Alby, etc.)
|
|
| 'social-embed' // Social post fetching (X, Nostr, Mastodon)
|
|
| 'mcp' // Model Context Protocol servers
|
|
| 'media' // Media processing (ffmpeg.wasm, whisper, TTS)
|
|
```
|
|
|
|
## Base Plugin Interface
|
|
```typescript
|
|
interface AIUIPlugin {
|
|
id: string
|
|
name: string
|
|
version: string
|
|
type: PluginType
|
|
description?: string
|
|
icon?: string
|
|
init(context: PluginContext): Promise<void>
|
|
destroy(): Promise<void>
|
|
isAvailable(): Promise<boolean>
|
|
}
|
|
```
|
|
|
|
## Plugin Context
|
|
Plugins receive a context object with access to:
|
|
- Settings store (read/write plugin-specific settings)
|
|
- Event bus (emit/listen for app events)
|
|
- Logger (structured logging)
|
|
- Crypto utilities (for encrypting plugin data at rest)
|
|
|
|
Plugins do NOT receive:
|
|
- Direct DOM access (community plugins)
|
|
- File system access (without explicit capability grant)
|
|
- Network access to arbitrary hosts (without declaration)
|
|
|
|
## Sandboxing Tiers
|
|
|
|
### Tier 1: Trusted (built-in, official)
|
|
Run in main thread with full API access. AI adapters, core renderers, crypto providers.
|
|
|
|
### Tier 2: Community
|
|
Run in sandboxed iframes with `postMessage` API. Custom renderers, themes, visual extensions. Cannot access host DOM, file system, or network directly.
|
|
|
|
### Tier 3: External Processes
|
|
MCP servers, local AI runners. Run as separate processes (Tauri IPC) or connect via HTTP. Isolated by OS process boundary.
|
|
|
|
## Plugin Lifecycle
|
|
1. `register()` — declare plugin to registry
|
|
2. `init()` — plugin sets up, connects to services
|
|
3. Active — plugin responds to requests
|
|
4. `destroy()` — cleanup on disable/uninstall
|
|
|
|
## Registration
|
|
```typescript
|
|
import { registerPlugin } from '@aiui/core'
|
|
|
|
registerPlugin({
|
|
id: 'ai-openrouter',
|
|
name: 'OpenRouter',
|
|
type: 'ai-provider',
|
|
version: '1.0.0',
|
|
async init(ctx) { /* setup */ },
|
|
async destroy() { /* cleanup */ },
|
|
// ... adapter methods
|
|
})
|
|
```
|
|
|
|
## Plugin Settings
|
|
Each plugin can declare settings schema. Settings are stored encrypted and exposed through a standard settings UI.
|
|
|
|
## Rules
|
|
- Every plugin must declare its type
|
|
- Every plugin must implement `init()` and `destroy()`
|
|
- Every plugin must implement `isAvailable()` to report its status
|
|
- Plugins must handle errors gracefully — never crash the host
|
|
- Community plugins must not load external scripts
|
|
- All network requests must go through the plugin context (for privacy/proxy control)
|