Feature: Plugin System

Relevant source files

The following files were used as context for generating this wiki page:

• locales/en-US/plugin.json
• packages/database/src/repositories/dataImporter/tests/fixtures/with-client-id.json
• src/tools/local-system/systemRole.ts
• src/tools/artifacts/systemRole.ts
• src/features/PluginDevModal/index.tsx
• src/services/plugin/client.test.ts
• src/store/tool/slices/plugin/selectors.test.ts
• src/features/Conversation/components/MarkdownElements/remarkPlugins/createRemarkSelfClosingTagPlugin.test.ts
• packages/prompts/src/chains/summaryDescription.ts
• locales/en-US/discover.json

The LobeChat Plugin System is a core feature that extends the application's capabilities by allowing the Large Language Model (LLM) to interact with external services, APIs, and the user's local file system. This enables the AI to perform a wide range of tasks beyond simple text generation, such as searching the web, creating images, analyzing data, and managing local files. The system is designed to be flexible, supporting official, third-party, and custom-developed plugins.

The plugin architecture encompasses frontend components for discovery and management, client-side state management for installed tools, and a backend service for handling plugin installation and execution logic. This allows for a seamless integration of external tools into the conversational experience.

Architecture Overview

The plugin system is composed of several key components that work together across the client and server.

This diagram shows the high-level architecture of the plugin system, from user interaction in the Plugin Store to the execution of a tool call within a conversation.
Sources: src/features/PluginStore/index.tsx, src/features/PluginDevModal/index.tsx, src/store/tool/slices/plugin/selectors.test.ts, src/services/plugin/client.test.ts

Plugin Types

The system supports several types of plugins, providing flexibility for both users and developers.

Plugin Type	Description
LobeChat / MCP Plugin	The primary plugin type, based on the Multi-platform Copilot Protocol (MCP). These can communicate via stdio (for local execution in the desktop app) or http (for remote servers).
OpenAI Plugin	Supports plugins that adhere to the standard OpenAI plugin specification.
Custom Plugin	Allows users to develop and install their own plugins, either from a manifest URL or by configuring it directly in the UI.
Local System	A special built-in plugin that grants the AI capabilities to interact with the user's local file system.

Sources: locales/en-US/plugin.json:42-47, 100-101, src/tools/local-system/systemRole.ts

Plugin Manifest

The plugin manifest is a JSON file that defines a plugin's metadata, capabilities, and configuration. It is the central piece of information for the system to understand and interact with a plugin.

This diagram illustrates the structure of a typical plugin manifest.
Sources: packages/database/src/repositories/dataImporter/tests/fixtures/with-client-id.json:5-100

Key Manifest Properties

Property	Description	Example from midjourney plugin
identifier	A unique string that identifies the plugin.	midjourney
meta	Contains metadata for display in the UI, such as title, description, and avatar.	{ "title": "Midjourney", "description": "Unleash creativity...", "avatar": "..." }
api	An array of objects, where each object defines a tool (function) the LLM can call. Includes the function name, description, and JSON schema for parameters.	[{ "name": "showMJ", "description": "...", "parameters": { ... } }]
ui	Defines an iframe-based UI component that can be rendered in the chat. Specifies the URL, width, and height.	{ "url": "https://midjourney.chat-plugin.lobehub.com/iframe", "width": 360, "height": 420 }
settings	A JSON schema defining the configuration options the user must provide for the plugin to work (e.g., API keys).	{ "required": ["MIDJOURNEY_PROXY_URL"], "properties": { ... } }
systemRole	A prompt that provides instructions to the LLM on how to use the plugin's tools effectively.	"As MidjourneyGPT, your role is to write, refine, and mix prompts..."

Sources: packages/database/src/repositories/dataImporter/tests/fixtures/with-client-id.json:5-100

Frontend Components

Plugin Development & Management

The frontend provides modals for users to add, configure, and develop plugins.

• Add/Edit Custom Plugin: A modal allows users to create a new plugin by providing a manifest URL or by configuring it manually. It supports LobeChat Plugin and OpenAI Plugin types.
• Manifest Configuration: Users can define the plugin's metadata (title, description, author, avatar), and for MCP plugins, connection details like the endpoint URL, authentication, and environment variables.
• Preview: The modal includes a preview pane to show how the plugin card will appear and what tools it exposes.

The diagram below shows the flow for creating a custom plugin.

Client-Side State Management

Plugin state is managed using Zustand. The tool slice of the store holds all plugin-related data and actions.

State Structure

• installedPlugins: An array of LobeTool objects representing all plugins the user has installed.
• pluginInstallLoading: A map to track the installation loading state for each plugin by its identifier.
• pluginStoreList: A list of available plugins fetched from the plugin marketplace.

Key Selectors

• getToolManifestById(id): Returns the manifest for a given plugin ID.
• isPluginInstalled(id): Checks if a plugin with the given ID is installed.
• getInstalledPluginById(id): Retrieves the full installed plugin object by its ID.
• installedPluginManifestList: Returns a list of all manifests for installed plugins.

Sources: src/store/tool/slices/plugin/selectors.test.ts:12-40, 108-120

Plugin Installation Flow

The following sequence diagram shows how a plugin is installed from the Plugin Store.

Specialized Built-in Tools

Local System Tool

This powerful built-in tool allows the AI to interact with the user's local file system. It is governed by a detailed system prompt that instructs the model on its capabilities and constraints.

Capabilities:

Function	Description
listLocalFiles	Lists files and directories in a specified path.
readLocalFile	Reads the content of a file (text, PDF, Word, etc.), with optional line range.
writeFile	Writes content to a plain text file.
searchLocalFiles	Searches for files based on keywords, content, dates, and other criteria.
renameLocalFile	Renames a single file or directory.
moveLocalFiles	Moves multiple files or directories.

Sources: src/tools/local-system/systemRole.ts:11-23, locales/en-US/plugin.json:237-244

Response Format:
When responding with file paths, the model must use a special self-closing XML tag, <localFile />, which is then parsed by a remark plugin on the frontend to render a special component.

• For a file: <localFile name="report.pdf" path="/Users/me/Documents/report.pdf" />
• For a directory: <localFile name="Documents" path="/Users/me/Documents" isDirectory />

Sources: src/tools/local-system/systemRole.ts:74-82, src/features/Conversation/components/MarkdownElements/remarkPlugins/createRemarkSelfClosingTagPlugin.test.ts:14-25

Artifacts

Artifacts are used for generating substantial, self-contained content that is displayed in a separate UI window. This is ideal for code, documents, or visualizations that the user might want to edit, copy, or reuse. The decision to use an artifact is guided by a system prompt.

Artifact Creation Logic:

Artifact Types:
The type attribute of the <lobeArtifact> tag specifies how the content should be rendered.

Type	type Attribute Value	Description
Code	application/lobe.artifacts.code	For code snippets. Requires a language attribute.
Documents	text/markdown	For plain text or Markdown documents.
HTML	text/html	Renders a single-file HTML page.
SVG	image/svg+xml	Renders an SVG image.
Mermaid	application/lobe.artifacts.mermaid	Renders a Mermaid.js diagram.
React	application/lobe.artifacts.react	Renders a React component, with support for shadcn/ui and recharts.

Sources: src/tools/artifacts/systemRole.ts:37-93

Summary

The LobeChat Plugin System is a robust and developer-friendly framework for extending the AI's core functionality. Through a well-defined manifest structure, support for multiple plugin types (including local file system access), and a dedicated UI for management, it allows for the seamless integration of external tools. The use of artifacts further enhances the user experience by providing a dedicated space for complex, editable content, making LobeChat a highly versatile and powerful conversational AI platform.