@lobehub/lobehub 2.0.0-next.164 → 2.0.0-next.166

package/apps/desktop/README.md

@@ -183,10 +183,18 @@ The `App.ts` class orchestrates the entire application lifecycle through key pha
 #### 🔌 Dependency Injection & Event System
 
 - **IoC Container** - WeakMap-based container for decorated controller methods
-- **Decorator Registration** - `@ipcClientEvent` and `@ipcServerEvent` decorators
+- **Typed IPC Decorators** - `@IpcMethod` and `@IpcServerMethod` wire controller methods into type-safe channels
 - **Automatic Event Mapping** - Events registered during controller loading
 - **Service Locator** - Type-safe service and controller retrieval
 
+##### 🧠 Type-Safe IPC Flow
+
+- **Async Context Propagation** - `src/main/utils/ipc/base.ts` captures the `IpcContext` with `AsyncLocalStorage`, so controller logic can call `getIpcContext()` anywhere inside an IPC handler without explicitly threading arguments.
+- **Service Constructors Registry** - `src/main/controllers/registry.ts` exports `controllerIpcConstructors`, `DesktopIpcServices`, and `DesktopServerIpcServices`, enabling automatic typing of both renderer and server IPC proxies.
+- **Renderer Proxy Helper** - `src/utils/electron/ipc.ts` exposes `ensureElectronIpc()` which lazily builds a proxy on top of `window.electronAPI.invoke`, giving React/Next.js code a type-safe API surface without exposing raw proxies in preload.
+- **Server Proxy Helper** - `src/server/modules/ElectronIPCClient/index.ts` mirrors the same typing strategy for the Next.js server runtime, providing a dedicated proxy for `@IpcServerMethod` handlers.
+- **Shared Typings Package** - `apps/desktop/src/main/exports.d.ts` augments `@lobechat/electron-client-ipc` so every package can consume `DesktopIpcServices` without importing desktop business code directly.
+
 #### 🪟 Window Management
 
 - **Theme-Aware Windows** - Automatic adaptation to system dark/light mode
@@ -235,6 +243,7 @@ The `App.ts` class orchestrates the entire application lifecycle through key pha
 
 #### 🎮 Controller Pattern
 
+- **Typed IPC Decorators** - Controllers extend `ControllerModule` and expose renderer methods via `@IpcMethod`
 - **IPC Event Handling** - Processes events from renderer with decorator-based registration
 - **Lifecycle Hooks** - `beforeAppReady` and `afterAppReady` for initialization phases
 - **Type-Safe Communication** - Strong typing for all IPC events and responses
@@ -256,6 +265,33 @@ The `App.ts` class orchestrates the entire application lifecycle through key pha
 - **Context Awareness** - Events include sender context for window-specific operations
 - **Error Propagation** - Centralized error handling with proper status codes
 
+##### 🧩 Renderer IPC Helper
+
+Renderer code uses a lightweight proxy generated at runtime to keep IPC calls type-safe without exposing raw Electron objects through `contextBridge`. Use the helper exported from `src/utils/electron/ipc.ts` to access the main-process services:
+
+```ts
+import { ensureElectronIpc } from '@/utils/electron/ipc';
+
+const ipc = ensureElectronIpc();
+await ipc.windows.openSettingsWindow({ tab: 'provider' });
+```
+
+The helper internally builds a proxy on top of `window.electronAPI.invoke`, so no proxy objects need to be cloned across the preload boundary.
+
+##### 🖥️ Server IPC Helper
+
+Next.js (Node) modules use the same proxy pattern via `ensureElectronServerIpc` from `src/server/modules/ElectronIPCClient`. It lazily wraps the socket-based `ElectronIpcClient` so server code can call controllers with full type safety:
+
+```ts
+import { ensureElectronServerIpc } from '@/server/modules/ElectronIPCClient';
+
+const ipc = ensureElectronServerIpc();
+const dbPath = await ipc.system.getDatabasePath();
+await ipc.upload.deleteFiles(['foo.txt']);
+```
+
+All server methods are declared via `@IpcServerMethod` and live in dedicated controller classes, keeping renderer typings clean.
+
 #### 🛡️ Security Features
 
 - **OAuth 2.0 + PKCE** - Secure authentication with state parameter validation

package/apps/desktop/README.zh-CN.md

@@ -183,7 +183,7 @@ src/main/core/
 #### 🔌 依赖注入和事件系统
 
 - **IoC 容器** - 基于 WeakMap 的装饰控制器方法容器
-- **装饰器注册** - `@ipcClientEvent` 和 `@ipcServerEvent` 装饰器
+- **装饰器注册** - `@IpcMethod` 和 `@IpcServerMethod` 装饰器
 - **自动事件映射** - 控制器加载期间注册的事件
 - **服务定位器** - 类型安全的服务和控制器检索
 
@@ -256,6 +256,31 @@ src/main/core/
 - **上下文感知** - 事件包含用于窗口特定操作的发送者上下文
 - **错误传播** - 具有适当状态码的集中错误处理
 
+##### 🧩 渲染器 IPC 助手
+
+渲染端通过 `src/utils/electron/ipc.ts` 提供的 `ensureElectronIpc` 获得一个运行时代理，无需在 preload 中暴露 Proxy 对象即可获得类型安全的调用体验：
+
+```ts
+import { ensureElectronIpc } from '@/utils/electron/ipc';
+
+const ipc = ensureElectronIpc();
+await ipc.windows.openSettingsWindow({ tab: 'provider' });
+```
+
+##### 🖥️ Server IPC 助手
+
+Next.js 服务端模块可通过 `ensureElectronServerIpc`（位于 `src/server/modules/ElectronIPCClient`）获得同样的类型安全代理，并复用 socket IPC 通道：
+
+```ts
+import { ensureElectronServerIpc } from '@/server/modules/ElectronIPCClient';
+
+const ipc = ensureElectronServerIpc();
+const path = await ipc.system.getDatabasePath();
+await ipc.upload.deleteFiles(['foo.txt']);
+```
+
+所有 `@IpcServerMethod` 方法都放在独立的控制器中，这样渲染端的类型推导不会包含这些仅供服务器调用的通道。
+
 #### 🛡️ 安全功能
 
 - **OAuth 2.0 + PKCE** - 具有状态参数验证的安全认证

package/apps/desktop/electron.vite.config.ts

@@ -39,6 +39,7 @@ export default defineConfig({
     resolve: {
       alias: {
         '~common': resolve(__dirname, 'src/common'),
+        '@': resolve(__dirname, 'src/main'),
       },
     },
   },

package/apps/desktop/src/main/controllers/AuthCtr.ts

@@ -7,7 +7,7 @@ import { URL } from 'node:url';
 import { createLogger } from '@/utils/logger';
 
 import RemoteServerConfigCtr from './RemoteServerConfigCtr';
-import { ControllerModule, ipcClientEvent } from './index';
+import { ControllerModule, IpcMethod } from './index';
 
 // Create logger
 const logger = createLogger('controllers:AuthCtr');
@@ -17,6 +17,7 @@ const logger = createLogger('controllers:AuthCtr');
  * Implements OAuth authorization flow using intermediate page + polling mechanism
  */
 export default class AuthCtr extends ControllerModule {
+  static override readonly groupName = 'auth';
   /**
    * Remote server configuration controller
    */
@@ -56,7 +57,7 @@ export default class AuthCtr extends ControllerModule {
   /**
    * Request OAuth authorization
    */
-  @ipcClientEvent('requestAuthorization')
+  @IpcMethod()
   async requestAuthorization(config: DataSyncConfig) {
     // Clear any old authorization state
     this.clearAuthorizationState();
@@ -119,7 +120,7 @@ export default class AuthCtr extends ControllerModule {
   /**
    * Request Market OAuth authorization (desktop)
    */
-  @ipcClientEvent('requestMarketAuthorization')
+  @IpcMethod()
   async requestMarketAuthorization(params: MarketAuthorizationParams) {
     const { authUrl } = params;
 

package/apps/desktop/src/main/controllers/BrowserWindowsCtr.ts

@@ -1,22 +1,21 @@
 import { InterceptRouteParams, OpenSettingsWindowOptions } from '@lobechat/electron-client-ipc';
 import { findMatchingRoute } from '~common/routes';
 
-import {
-  AppBrowsersIdentifiers,
-  WindowTemplateIdentifiers,
-} from '@/appBrowsers';
-import { IpcClientEventSender } from '@/types/ipcClientEvent';
+import { AppBrowsersIdentifiers, WindowTemplateIdentifiers } from '@/appBrowsers';
+import { getIpcContext } from '@/utils/ipc';
 
-import { ControllerModule, ipcClientEvent, shortcut } from './index';
+import { ControllerModule, IpcMethod, shortcut } from './index';
 
 export default class BrowserWindowsCtr extends ControllerModule {
+  static override readonly groupName = 'windows';
+
   @shortcut('showApp')
   async toggleMainWindow() {
     const mainWindow = this.app.browserManager.getMainWindow();
     mainWindow.toggleVisible();
   }
 
-  @ipcClientEvent('openSettingsWindow')
+  @IpcMethod()
   async openSettingsWindow(options?: string | OpenSettingsWindowOptions) {
     const normalizedOptions: OpenSettingsWindowOptions =
       typeof options === 'string' || options === undefined
@@ -53,26 +52,32 @@ export default class BrowserWindowsCtr extends ControllerModule {
     }
   }
 
-  @ipcClientEvent('closeWindow')
-  closeWindow(data: undefined, sender: IpcClientEventSender) {
-    this.app.browserManager.closeWindow(sender.identifier);
+  @IpcMethod()
+  closeWindow() {
+    this.withSenderIdentifier((identifier) => {
+      this.app.browserManager.closeWindow(identifier);
+    });
   }
 
-  @ipcClientEvent('minimizeWindow')
-  minimizeWindow(data: undefined, sender: IpcClientEventSender) {
-    this.app.browserManager.minimizeWindow(sender.identifier);
+  @IpcMethod()
+  minimizeWindow() {
+    this.withSenderIdentifier((identifier) => {
+      this.app.browserManager.minimizeWindow(identifier);
+    });
   }
 
-  @ipcClientEvent('maximizeWindow')
-  maximizeWindow(data: undefined, sender: IpcClientEventSender) {
-    this.app.browserManager.maximizeWindow(sender.identifier);
+  @IpcMethod()
+  maximizeWindow() {
+    this.withSenderIdentifier((identifier) => {
+      this.app.browserManager.maximizeWindow(identifier);
+    });
   }
 
   /**
    * Handle route interception requests
    * Responsible for handling route interception requests from the renderer process
    */
-  @ipcClientEvent('interceptRoute')
+  @IpcMethod()
   async interceptRoute(params: InterceptRouteParams) {
     const { path, source } = params;
     console.log(
@@ -115,7 +120,7 @@ export default class BrowserWindowsCtr extends ControllerModule {
   /**
    * Create a new multi-instance window
    */
-  @ipcClientEvent('createMultiInstanceWindow')
+  @IpcMethod()
   async createMultiInstanceWindow(params: {
     path: string;
     templateId: WindowTemplateIdentifiers;
@@ -149,7 +154,7 @@ export default class BrowserWindowsCtr extends ControllerModule {
   /**
    * Get all windows by template
    */
-  @ipcClientEvent('getWindowsByTemplate')
+  @IpcMethod()
   async getWindowsByTemplate(templateId: string) {
     try {
       const windowIds = this.app.browserManager.getWindowsByTemplate(templateId);
@@ -169,7 +174,7 @@ export default class BrowserWindowsCtr extends ControllerModule {
   /**
    * Close all windows by template
    */
-  @ipcClientEvent('closeWindowsByTemplate')
+  @IpcMethod()
   async closeWindowsByTemplate(templateId: string) {
     try {
       this.app.browserManager.closeWindowsByTemplate(templateId);
@@ -191,4 +196,12 @@ export default class BrowserWindowsCtr extends ControllerModule {
     const browser = this.app.browserManager.retrieveByIdentifier(targetWindow);
     browser.show();
   }
+
+  private withSenderIdentifier(fn: (identifier: string) => void) {
+    const context = getIpcContext();
+    if (!context) return;
+    const identifier = this.app.browserManager.getIdentifierByWebContents(context.sender);
+    if (!identifier) return;
+    fn(identifier);
+  }
 }

package/apps/desktop/src/main/controllers/DevtoolsCtr.ts

@@ -1,7 +1,9 @@
-import { ControllerModule, ipcClientEvent } from './index';
+import { ControllerModule, IpcMethod } from './index';
 
 export default class DevtoolsCtr extends ControllerModule {
-  @ipcClientEvent('openDevtools')
+  static override readonly groupName = 'devtools';
+
+  @IpcMethod()
   async openDevtools() {
     const devtoolsBrowser = this.app.browserManager.retrieveByIdentifier('devtools');
     devtoolsBrowser.show();

package/apps/desktop/src/main/controllers/LocalFileCtr.ts

@@ -30,19 +30,20 @@ import { FileResult, SearchOptions } from '@/types/fileSearch';
 import { makeSureDirExist } from '@/utils/file-system';
 import { createLogger } from '@/utils/logger';
 
-import { ControllerModule, ipcClientEvent } from './index';
+import { ControllerModule, IpcMethod } from './index';
 
 // Create logger
 const logger = createLogger('controllers:LocalFileCtr');
 
 export default class LocalFileCtr extends ControllerModule {
+  static override readonly groupName = 'localSystem';
   private get searchService() {
     return this.app.getService(FileSearchService);
   }
 
   // ==================== File Operation ====================
 
-  @ipcClientEvent('openLocalFile')
+  @IpcMethod()
   async handleOpenLocalFile({ path: filePath }: OpenLocalFileParams): Promise<{
     error?: string;
     success: boolean;
@@ -59,7 +60,7 @@ export default class LocalFileCtr extends ControllerModule {
     }
   }
 
-  @ipcClientEvent('openLocalFolder')
+  @IpcMethod()
   async handleOpenLocalFolder({ path: targetPath, isDirectory }: OpenLocalFolderParams): Promise<{
     error?: string;
     success: boolean;
@@ -77,7 +78,7 @@ export default class LocalFileCtr extends ControllerModule {
     }
   }
 
-  @ipcClientEvent('readLocalFiles')
+  @IpcMethod()
   async readFiles({ paths }: LocalReadFilesParams): Promise<LocalReadFileResult[]> {
     logger.debug('Starting batch file reading:', { count: paths.length });
 
@@ -94,7 +95,7 @@ export default class LocalFileCtr extends ControllerModule {
     return results;
   }
 
-  @ipcClientEvent('readLocalFile')
+  @IpcMethod()
   async readFile({
     path: filePath,
     loc,
@@ -192,7 +193,7 @@ export default class LocalFileCtr extends ControllerModule {
     }
   }
 
-  @ipcClientEvent('listLocalFiles')
+  @IpcMethod()
   async listLocalFiles({ path: dirPath }: ListLocalFileParams): Promise<FileResult[]> {
     logger.debug('Listing directory contents:', { dirPath });
 
@@ -250,7 +251,7 @@ export default class LocalFileCtr extends ControllerModule {
     }
   }
 
-  @ipcClientEvent('moveLocalFiles')
+  @IpcMethod()
   async handleMoveFiles({ items }: MoveLocalFilesParams): Promise<LocalMoveFilesResultItem[]> {
     logger.debug('Starting batch file move:', { itemsCount: items?.length });
 
@@ -355,7 +356,7 @@ export default class LocalFileCtr extends ControllerModule {
     return results;
   }
 
-  @ipcClientEvent('renameLocalFile')
+  @IpcMethod()
   async handleRenameFile({
     path: currentPath,
     newName,
@@ -440,7 +441,7 @@ export default class LocalFileCtr extends ControllerModule {
     }
   }
 
-  @ipcClientEvent('writeLocalFile')
+  @IpcMethod()
   async handleWriteFile({ path: filePath, content }: WriteLocalFileParams) {
     const logPrefix = `[Writing file ${filePath}]`;
     logger.debug(`${logPrefix} Starting to write file`, { contentLength: content?.length });
@@ -485,7 +486,7 @@ export default class LocalFileCtr extends ControllerModule {
   /**
    * Handle IPC event for local file search
    */
-  @ipcClientEvent('searchLocalFiles')
+  @IpcMethod()
   async handleLocalFilesSearch(params: LocalSearchFilesParams): Promise<FileResult[]> {
     logger.debug('Received file search request:', {
       directory: params.directory,
@@ -523,7 +524,7 @@ export default class LocalFileCtr extends ControllerModule {
     }
   }
 
-  @ipcClientEvent('grepContent')
+  @IpcMethod()
   async handleGrepContent(params: GrepContentParams): Promise<GrepContentResult> {
     const {
       pattern,
@@ -639,7 +640,7 @@ export default class LocalFileCtr extends ControllerModule {
     }
   }
 
-  @ipcClientEvent('globLocalFiles')
+  @IpcMethod()
   async handleGlobFiles({
     path: searchPath = process.cwd(),
     pattern,
@@ -680,7 +681,7 @@ export default class LocalFileCtr extends ControllerModule {
 
   // ==================== File Editing ====================
 
-  @ipcClientEvent('editLocalFile')
+  @IpcMethod()
   async handleEditFile({
     file_path: filePath,
     new_string,

package/apps/desktop/src/main/controllers/MenuCtr.ts

@@ -1,10 +1,11 @@
-import { ControllerModule, ipcClientEvent } from './index';
+import { ControllerModule, IpcMethod } from './index';
 
 export default class MenuController extends ControllerModule {
+  static override readonly groupName = 'menu';
   /**
    * Refresh menu
    */
-  @ipcClientEvent('refreshAppMenu')
+  @IpcMethod()
   refreshAppMenu() {
     // Note: May need to decide whether to allow renderer process to refresh all menus based on specific circumstances
     return this.app.menuManager.refreshMenus();
@@ -13,7 +14,7 @@ export default class MenuController extends ControllerModule {
   /**
    * Show context menu
    */
-  @ipcClientEvent('showContextMenu')
+  @IpcMethod()
   showContextMenu(params: { data?: any; type: string }) {
     return this.app.menuManager.showContextMenu(params.type, params.data);
   }
@@ -21,7 +22,7 @@ export default class MenuController extends ControllerModule {
   /**
    * Set development menu visibility
    */
-  @ipcClientEvent('setDevMenuVisibility')
+  @IpcMethod()
   setDevMenuVisibility(visible: boolean) {
     // Call MenuManager method to rebuild application menu
     return this.app.menuManager.rebuildAppMenu({ showDevItems: visible });

package/apps/desktop/src/main/controllers/NetworkProxyCtr.ts

@@ -11,7 +11,7 @@ import {
   ProxyDispatcherManager,
   ProxyTestResult,
 } from '../modules/networkProxy';
-import { ControllerModule, ipcClientEvent } from './index';
+import { ControllerModule, IpcMethod } from './index';
 
 // Create logger
 const logger = createLogger('controllers:NetworkProxyCtr');
@@ -21,10 +21,11 @@ const logger = createLogger('controllers:NetworkProxyCtr');
  * 处理桌面应用的网络代理相关功能
  */
 export default class NetworkProxyCtr extends ControllerModule {
+  static override readonly groupName = 'networkProxy';
   /**
    * 获取代理设置
    */
-  @ipcClientEvent('getProxySettings')
+  @IpcMethod()
   async getDesktopSettings(): Promise<NetworkProxySettings> {
     try {
       const settings = this.app.storeManager.get(
@@ -45,32 +46,30 @@ export default class NetworkProxyCtr extends ControllerModule {
   /**
    * 设置代理配置
    */
-  @ipcClientEvent('setProxySettings')
-  async setProxySettings(config: NetworkProxySettings): Promise<void> {
+  @IpcMethod()
+  async setProxySettings(config: Partial<NetworkProxySettings>): Promise<void> {
     try {
-      // 验证配置
-      const validation = ProxyConfigValidator.validate(config);
-      if (!validation.isValid) {
-        const errorMessage = `Invalid proxy configuration: ${validation.errors.join(', ')}`;
-        logger.error(errorMessage);
-        throw new Error(errorMessage);
-      }
-
       // 获取当前配置
       const currentConfig = this.app.storeManager.get(
         'networkProxy',
         defaultProxySettings,
       ) as NetworkProxySettings;
 
-      // 检查是否有变化
-      if (isEqual(currentConfig, config)) {
+      // 合并配置并验证
+      const newConfig = merge({}, currentConfig, config);
+
+      const validation = ProxyConfigValidator.validate(newConfig);
+      if (!validation.isValid) {
+        const errorMessage = `Invalid proxy configuration: ${validation.errors.join(', ')}`;
+        logger.error(errorMessage);
+        throw new Error(errorMessage);
+      }
+
+      if (isEqual(currentConfig, newConfig)) {
         logger.debug('Proxy settings unchanged, skipping update');
         return;
       }
 
-      // 合并配置
-      const newConfig = merge({}, currentConfig, config);
-
       // 应用代理设置
       await ProxyDispatcherManager.applyProxySettings(newConfig);
 
@@ -92,7 +91,7 @@ export default class NetworkProxyCtr extends ControllerModule {
   /**
    * 测试代理连接
    */
-  @ipcClientEvent('testProxyConnection')
+  @IpcMethod()
   async testProxyConnection(url: string): Promise<{ message?: string; success: boolean }> {
     try {
       const result = await ProxyConnectionTester.testConnection(url);
@@ -112,7 +111,7 @@ export default class NetworkProxyCtr extends ControllerModule {
   /**
    * 测试指定代理配置
    */
-  @ipcClientEvent('testProxyConfig')
+  @IpcMethod()
   async testProxyConfig({
     config,
     testUrl,

package/apps/desktop/src/main/controllers/NotificationCtr.ts

@@ -7,11 +7,12 @@ import { macOS, windows } from 'electron-is';
 
 import { createLogger } from '@/utils/logger';
 
-import { ControllerModule, ipcClientEvent } from './index';
+import { ControllerModule, IpcMethod } from './index';
 
 const logger = createLogger('controllers:NotificationCtr');
 
 export default class NotificationCtr extends ControllerModule {
+  static override readonly groupName = 'notification';
   /**
    * Set up desktop notifications after the application is ready
    */
@@ -51,7 +52,7 @@ export default class NotificationCtr extends ControllerModule {
   /**
    * Show system desktop notification (only when window is hidden)
    */
-  @ipcClientEvent('showDesktopNotification')
+  @IpcMethod()
   async showDesktopNotification(
     params: ShowDesktopNotificationParams,
   ): Promise<DesktopNotificationResult> {
@@ -126,7 +127,7 @@ export default class NotificationCtr extends ControllerModule {
   /**
    * Check if the main window is hidden
    */
-  @ipcClientEvent('isMainWindowHidden')
+  @IpcMethod()
   isMainWindowHidden(): boolean {
     try {
       const mainWindow = this.app.browserManager.getMainWindow();

package/apps/desktop/src/main/controllers/RemoteServerConfigCtr.ts

@@ -7,7 +7,7 @@ import { URL } from 'node:url';
 import { OFFICIAL_CLOUD_SERVER } from '@/const/env';
 import { createLogger } from '@/utils/logger';
 
-import { ControllerModule, ipcClientEvent } from './index';
+import { ControllerModule, IpcMethod } from './index';
 
 /**
  * Non-retryable OIDC error codes
@@ -39,6 +39,7 @@ const logger = createLogger('controllers:RemoteServerConfigCtr');
  * Used to manage custom remote LobeChat server configuration
  */
 export default class RemoteServerConfigCtr extends ControllerModule {
+  static override readonly groupName = 'remoteServer';
   /**
    * Key used to store encrypted tokens in electron-store.
    */
@@ -47,7 +48,7 @@ export default class RemoteServerConfigCtr extends ControllerModule {
   /**
    * Get remote server configuration
    */
-  @ipcClientEvent('getRemoteServerConfig')
+  @IpcMethod()
   async getRemoteServerConfig() {
     logger.debug('Getting remote server configuration');
     const { storeManager } = this.app;
@@ -64,7 +65,7 @@ export default class RemoteServerConfigCtr extends ControllerModule {
   /**
    * Set remote server configuration
    */
-  @ipcClientEvent('setRemoteServerConfig')
+  @IpcMethod()
   async setRemoteServerConfig(config: Partial<DataSyncConfig>) {
     logger.info(
       `Setting remote server storageMode: active=${config.active}, storageMode=${config.storageMode}, url=${config.remoteServerUrl}`,
@@ -81,7 +82,7 @@ export default class RemoteServerConfigCtr extends ControllerModule {
   /**
    * Clear remote server configuration
    */
-  @ipcClientEvent('clearRemoteServerConfig')
+  @IpcMethod()
   async clearRemoteServerConfig() {
     logger.info('Clearing remote server configuration');
     const { storeManager } = this.app;

package/apps/desktop/src/main/controllers/RemoteServerSyncCtr.ts

@@ -15,7 +15,7 @@ import { defaultProxySettings } from '@/const/store';
 import { createLogger } from '@/utils/logger';
 
 import RemoteServerConfigCtr from './RemoteServerConfigCtr';
-import { ControllerModule, ipcClientEvent } from './index';
+import { ControllerModule, IpcMethod } from './index';
 
 // Create logger
 const logger = createLogger('controllers:RemoteServerSyncCtr');
@@ -25,6 +25,7 @@ const logger = createLogger('controllers:RemoteServerSyncCtr');
  * For handling data synchronization with remote servers via IPC.
  */
 export default class RemoteServerSyncCtr extends ControllerModule {
+  static override readonly groupName = 'remoteServerSync';
   /**
    * Cached instance of RemoteServerConfigCtr
    */
@@ -345,7 +346,7 @@ export default class RemoteServerSyncCtr extends ControllerModule {
    * Handles the 'proxy-trpc-request' IPC call from the renderer process.
    * This method should be invoked by the ipcMain.handle setup in your main process entry point.
    */
-  @ipcClientEvent('proxyTRPCRequest')
+  @IpcMethod()
   public async proxyTRPCRequest(args: ProxyTRPCRequestParams): Promise<ProxyTRPCRequestResult> {
     logger.debug('Received proxyTRPCRequest IPC call:', {
       headers: args.headers,

package/apps/desktop/src/main/controllers/ShellCommandCtr.ts

@@ -11,7 +11,7 @@ import { randomUUID } from 'node:crypto';
 
 import { createLogger } from '@/utils/logger';
 
-import { ControllerModule, ipcClientEvent } from './index';
+import { ControllerModule, IpcMethod } from './index';
 
 const logger = createLogger('controllers:ShellCommandCtr');
 
@@ -24,10 +24,11 @@ interface ShellProcess {
 }
 
 export default class ShellCommandCtr extends ControllerModule {
+  static override readonly groupName = 'shellCommand';
   // Shell process management
   private shellProcesses = new Map<string, ShellProcess>();
 
-  @ipcClientEvent('runCommand')
+  @IpcMethod()
   async handleRunCommand({
     command,
     description,
@@ -153,7 +154,7 @@ export default class ShellCommandCtr extends ControllerModule {
     }
   }
 
-  @ipcClientEvent('getCommandOutput')
+  @IpcMethod()
   async handleGetCommandOutput({
     filter,
     shell_id,
@@ -212,7 +213,7 @@ export default class ShellCommandCtr extends ControllerModule {
     };
   }
 
-  @ipcClientEvent('killCommand')
+  @IpcMethod()
   async handleKillCommand({ shell_id }: KillCommandParams): Promise<KillCommandResult> {
     const logPrefix = `[killCommand: ${shell_id}]`;
     logger.debug(`${logPrefix} Attempting to kill shell`);

package/apps/desktop/src/main/controllers/ShortcutCtr.ts

@@ -1,12 +1,13 @@
 import { ShortcutUpdateResult } from '@/core/ui/ShortcutManager';
 
-import { ControllerModule, ipcClientEvent } from '.';
+import { ControllerModule, IpcMethod } from '.';
 
 export default class ShortcutController extends ControllerModule {
+  static override readonly groupName = 'shortcut';
   /**
    * Get all shortcut configurations
    */
-  @ipcClientEvent('getShortcutsConfig')
+  @IpcMethod()
   getShortcutsConfig() {
     return this.app.shortcutManager.getShortcutsConfig();
   }
@@ -14,7 +15,7 @@ export default class ShortcutController extends ControllerModule {
   /**
    * Update a single shortcut configuration
    */
-  @ipcClientEvent('updateShortcutConfig')
+  @IpcMethod()
   updateShortcutConfig({
     id,
     accelerator,