OpenACP/docs/gitbook/extending/plugin-system.md
0xmrpeter add905a40c docs: clean up and simplify gitbook documentation
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
2026-04-01 22:28:37 +07:00

93 lines
2.7 KiB
Markdown

# Plugin System Overview
> **Note:** This page provides a quick overview of plugin management from a user's perspective. For the full technical deep dive into the plugin infrastructure, see [Architecture > Plugin System](../architecture/plugin-system.md).
---
## What Are Plugins?
Plugins are modules that extend OpenACP with new capabilities. Everything beyond the core kernel is a plugin: messaging adapters (Telegram, Discord, Slack), security, speech, tunnels, usage tracking, and more.
Plugins can:
- Register **services** that other plugins consume
- Register **chat commands** available on all platforms
- Register **middleware** to intercept and modify message flows
- Subscribe to **events** for cross-plugin communication
- Use **storage** for persistent data
---
## Installing a Plugin
```bash
openacp plugin install @community/my-plugin
```
If the plugin has `essential: true`, its interactive `install()` hook runs immediately. Otherwise, it's registered and available on next restart.
## Listing Plugins
```bash
openacp plugins
```
Shows all installed plugins with their version, source (builtin/npm), and enabled state.
## Configuring a Plugin
```bash
openacp plugin configure @community/my-plugin
```
Runs the plugin's interactive `configure()` hook.
## Disabling / Enabling
```bash
openacp plugin disable @openacp/speech
openacp plugin enable @openacp/speech
```
Built-in plugins cannot be uninstalled, but they can be disabled.
## Uninstalling
```bash
openacp plugin uninstall @community/my-plugin
openacp plugin uninstall @community/my-plugin --purge # also delete settings
```
---
## Plugin Interface (Quick Reference)
```typescript
interface OpenACPPlugin {
name: string
version: string
description?: string
pluginDependencies?: Record<string, string>
permissions?: PluginPermission[]
settingsSchema?: ZodSchema
essential?: boolean
setup(ctx: PluginContext): Promise<void>
teardown?(): Promise<void>
install?(ctx: InstallContext): Promise<void>
configure?(ctx: InstallContext): Promise<void>
migrate?(ctx: MigrateContext, oldSettings: unknown, oldVersion: string): Promise<unknown>
uninstall?(ctx: InstallContext, opts: { purge: boolean }): Promise<void>
}
```
---
## Further Reading
- [Architecture > Plugin System](../architecture/plugin-system.md) -- complete plugin infrastructure deep dive
- [Architecture > Writing Plugins](../architecture/writing-plugins.md) -- step-by-step guide for plugin authors
- [Architecture > Built-in Plugins](../architecture/built-in-plugins.md) -- reference for all 11 built-in plugins
- [Architecture > Command System](../architecture/command-system.md) -- how chat commands work
- [Building Adapters](building-adapters.md) -- building adapter plugins specifically