RunVSAgent Documentation

The ClineExtensionProvider.isAvailable(project) method determines if the extension can be used by checking two primary locations:

1. Project/User Space Directory: Checks if files exist at ${VsixManager.getBaseDirectory()}/${config.codeDir} (where codeDir is retrieved from ExtensionConfiguration).
2. Plugin Built-in Resources: If not found in the user space, it checks the plugin's internal resources using PluginResourceUtil.getResourcePath(PLUGIN_ID, config.codeDir).

If files are found in either location, the method returns true.

override fun isAvailable(project: Project): Boolean {
    // Check if roo-code extension files exist
    val extensionConfig = ExtensionConfiguration.getInstance(project)
    val config = extensionConfig.getConfig(ExtensionType.CLINE)

    // First check project paths
    val possiblePaths = listOf(
        "${getBaseDirectory()}/${config.codeDir}"
    )

    if (possiblePaths.any { File(it).exists() }) {
        return true
    }

    // Then check plugin resources (for built-in extensions)
    try {
        val pluginResourcePath = PluginResourceUtil.getResourcePath(
            PluginConstants.PLUGIN_ID,
            config.codeDir
        )
        if (pluginResourcePath != null && File(pluginResourcePath).exists()) {
            return true
        }
    } catch (e: Exception) {
        // Ignore exceptions when checking plugin resources
    }

    return false
}

The extension system follows a layered architecture to integrate AI agents (like Cline) into the IDE:

1. Extension Provider Layer: Implements the ExtensionProvider contract. This is where the specific agent (e.g., Cline) defines its identity, initialization logic, availability checks, and metadata.
2. Global Extension Management Layer: Managed by extensions/core/ExtensionManager. It acts as a central service for registering, selecting, and switching between different extension providers, while coordinating UI updates and configuration.
3. UI Dynamic Adaptation Layer: Uses DynamicButtonManager and DynamicContextMenuManager to generate buttons and context menus based on the currently active provider. Providers implement ClineButtonProvider and ClineContextMenuProvider to define their specific UI elements.
4. Command/Event Interaction Layer: UI entries trigger commands via executeCommand("cline.xxx", ...) to interact with the host. Core actions are dispatched to backend logic.
5. WebView Capability Layer: Uses WebViewManager to host the agent's frontend interface. Certain actions (like 'New Task') perform availability checks on the WebViewManager before execution.

graph TD
    subgraph UI[UI 层]
        BTN[Toolbar Buttons<br/>ClineButtonProvider]
        MENU[Context Menu<br/>ClineContextMenuProvider]
    end

    subgraph Actions[命令分发]
        EXEC[executeCommand cline commands<br/>actions package]
    end

    subgraph ProjectSvc[项目级扩展管理]
        EM[extensions/core/ExtensionManager]
        DBM[DynamicButtonManager]
        DCM[DynamicContextMenuManager]
    end

    subgraph Provider[扩展提供方]
        CLP[ClineExtensionProvider<br/>initialize/isAvailable/getConfiguration]
    end

    subgraph Core[核心扩展系统（VSCode 兼容层）]
        CEM[core/ExtensionManager<br/>register/activate]
        RPC[JSON-RPC / IPC]
        EXTH[ExtHostExtensionService.activate]
    end

    subgraph WebView[WebView 能力]
        WVM[WebViewManager]
        WV[WebView Instances]
    end

    BTN -->|Plus 点击前检查| WVM
    WVM -->|has latest WebView?| WV
    WV -->|是| EXEC
    WVM -. 无/空 .-> BTN

    MENU --> EXEC
    EXEC --> EM
    EM -->|setCurrentProvider/initialize| CLP
    EM --> DBM
    EM --> DCM

    CLP -->|getConfiguration| CEM
    CEM -->|register/activate| RPC --> EXTH

    EXEC -->|界面联动| WVM --> WV

To integrate an agent like Cline, you must implement three core provider classes:

1. ClineExtensionProvider: Defines the extension's identity (getExtensionId(), getDisplayName(), getDescription()), manages its lifecycle (initialize(project), dispose()), checks for its presence (isAvailable(project)), and provides metadata via getConfiguration(project).
2. ClineButtonProvider: Defines the set of toolbar buttons (e.g., Plus, History, Account, Settings, MCP). When a button is clicked, it dispatches a command (e.g., cline.plusButtonClicked). Note that the 'Plus' button typically checks WebViewManager availability before executing.
3. ClineContextMenuProvider: Defines which context menu actions are visible using isActionVisible(actionType).

Additionally, ensure that:

• extensions/core/ExtensionManager is used to register the provider.
• Commands (e.g., cline.*) are registered in the com.sina.weibo.agent.actions center and align with the frontend WebView.
• The extension's package.json and main entry point are correctly located in the user directory or plugin resources to satisfy isAvailable checks.

// Example implementation of ClineExtensionProvider
class ClineExtensionProvider : ExtensionProvider {
    
    override fun getExtensionId(): String = "cline"
    
    override fun getDisplayName(): String = "Cline AI"
    
    override fun getDescription(): String = "AI-powered coding assistant with advanced features"
    
    override fun initialize(project: Project) {
        // Initialize cline extension configuration
        val extensionConfig = ExtensionConfiguration.getInstance(project)
        extensionConfig.initialize()
        
        // Initialize extension manager factory if needed
        try {
            val extensionManagerFactory = ExtensionManagerFactory.getInstance(project)
            extensionManagerFactory.initialize()
        } catch (e: Exception) {
            // If ExtensionManagerFactory is not available, continue without it
        }
    }
}

Follow these steps to integrate a new extension like Cline:

1. Implement Provider: Create a class implementing ClineExtensionProvider in extensions/plugin/cline/. Ensure getExtensionId() returns "cline" and implement initialize, isAvailable, getConfiguration, and dispose.
2. Register Provider: Add your provider to the ExtensionManager.getAllExtensions() list.
3. UI Integration: Define buttons in ClineButtonProvider and visibility in ClineContextMenuProvider.
4. Command Dispatch: Register cline.* command handlers in the backend and ensure the WebView can respond.
5. Prepare Files: Place extension files (including package.json) in ${VsixManager.getBaseDirectory()}/${config.codeDir}.
6. Metadata Configuration: Verify ExtensionConfiguration.getConfig(ExtensionType.CLINE) matches your actual codeDir, publisher, version, and mainFile.
7. Initialization: Call ExtensionManager.initialize() on startup and use setCurrentProvider("cline") to switch to it.
8. Self-Test: Verify button clicks, command dispatch, and WebView rendering.

To build the project, you must first initialize the development environment. The build process produces both VSCode extensions and IntelliJ IDEA plugins.

Linux/macOS

1. Initialize environment: ./scripts/setup.sh
2. Build project: ./scripts/build.sh

Windows

1. Initialize environment: .\scripts\run.ps1 setup
2. Build project: .\scripts\run.ps1 build

Build Options

• Build specific component: Use idea to build only the IntelliJ IDEA plugin.
• Build mode: Use --mode debug for development builds with debug symbols and source maps. The default is release mode (optimized for production).
• Custom output: Use --output <path> to specify a custom directory for artifacts.

# First time setup
./scripts/setup.sh --verbose

# Build in debug mode
./scripts/build.sh --mode debug

# Build specific component (IDEA plugin)
./scripts/build.sh idea

# Build with custom output directory
./scripts/build.sh --output ./dist