@lobehub/lobehub 2.0.0-next.353 → 2.0.0-next.354

package/.cursor/rules/debug-usage.mdc

@@ -1,86 +0,0 @@
----
-description: 包含添加 console.log 日志请求时
-globs:
-alwaysApply: false
----
-
-# Debug 包使用指南
-
-本项目使用 `debug` 包进行调试日志记录。使用此规则来确保团队成员统一调试日志格式。
-
-## 基本用法
-
-1. 导入 debug 包：
-
-```typescript
-import debug from 'debug';
-```
-
-1. 创建一个命名空间的日志记录器：
-
-```typescript
-// 格式: lobe:[模块]:[子模块]
-const log = debug('lobe-[模块名]:[子模块名]');
-```
-
-1. 使用日志记录器：
-
-```typescript
-log('简单消息');
-log('带变量的消息: %O', object);
-log('格式化数字: %d', number);
-```
-
-## 命名空间约定
-
-- 桌面应用相关: `lobe-desktop:[模块]`
-- 服务端相关: `lobe-server:[模块]`
-- 客户端相关: `lobe-client:[模块]`
-- 路由相关: `lobe-[类型]-router:[模块]`
-
-## 格式说明符
-
-- `%O` - 对象展开（推荐用于复杂对象）
-- `%o` - 对象
-- `%s` - 字符串
-- `%d` - 数字
-
-## 示例
-
-查看 `src/server/routers/edge/market/index.ts` 中的使用示例：
-
-```typescript
-import debug from 'debug';
-
-const log = debug('lobe-edge-router:market');
-
-log('getAgent input: %O', input);
-```
-
-## 启用调试
-
-要在开发时启用调试输出，需设置环境变量：
-
-### 在浏览器中
-
-在控制台执行：
-
-```javascript
-localStorage.debug = 'lobe-*';
-```
-
-### 在 Node.js 环境中
-
-```bash
-DEBUG=lobe-* npm run dev
-# 或者
-DEBUG=lobe-* pnpm dev
-```
-
-### 在 Electron 应用中
-
-可以在主进程和渲染进程启动前设置环境变量：
-
-```typescript
-process.env.DEBUG = 'lobe-*';
-```

package/.cursor/rules/desktop-controller-tests.mdc

@@ -1,189 +0,0 @@
----
-description: 桌面端测试
-globs:
-alwaysApply: false
----
-
-# 桌面端控制器单元测试指南
-
-## 测试框架与目录结构
-
-LobeChat 桌面端使用 Vitest 作为测试框架。控制器的单元测试应放置在对应控制器文件同级的 `__tests__` 目录下，并以原控制器文件名加 `.test.ts` 作为文件名。
-
-```plaintext
-apps/desktop/src/main/controllers/
-├── __tests__/
-│   ├── index.test.ts
-│   ├── MenuCtr.test.ts
-│   └── ...
-├── McpCtr.ts
-├── MenuCtr.ts
-└── ...
-```
-
-## 测试文件基本结构
-
-```typescript
-import { beforeEach, describe, expect, it, vi } from 'vitest';
-
-import type { App } from '@/core/App';
-
-import YourController from '../YourControllerName';
-
-// 模拟依赖
-vi.mock('依赖模块', () => ({
-  依赖函数: vi.fn(),
-}));
-
-// 模拟 App 实例
-const mockApp = {
-  // 按需模拟必要的 App 属性和方法
-} as unknown as App;
-
-describe('YourController', () => {
-  let controller: YourController;
-
-  beforeEach(() => {
-    vi.clearAllMocks();
-    controller = new YourController(mockApp);
-  });
-
-  describe('方法名', () => {
-    it('测试场景描述', async () => {
-      // 准备测试数据
-
-      // 执行被测方法
-      const result = await controller.方法名(参数);
-
-      // 验证结果
-      expect(result).toMatchObject(预期结果);
-    });
-  });
-});
-```
-
-## 模拟外部依赖
-
-### 模拟模块函数
-
-```typescript
-const mockFunction = vi.fn();
-
-vi.mock('module-name', () => ({
-  functionName: mockFunction,
-}));
-```
-
-### 模拟 Node.js 核心模块
-
-例如模拟 `child_process.exec` 和 `util.promisify`:
-
-```typescript
-// 存储模拟的 exec 实现
-const mockExecImpl = vi.fn();
-
-// 模拟 child_process.exec
-vi.mock('child_process', () => ({
-  exec: vi.fn((cmd, callback) => {
-    return mockExecImpl(cmd, callback);
-  }),
-}));
-
-// 模拟 util.promisify
-vi.mock('util', () => ({
-  promisify: vi.fn((fn) => {
-    return async (cmd: string) => {
-      return new Promise((resolve, reject) => {
-        mockExecImpl(cmd, (error: Error | null, result: any) => {
-          if (error) reject(error);
-          else resolve(result);
-        });
-      });
-    };
-  }),
-}));
-```
-
-## 编写有效的测试用例
-
-### 测试分类
-
-将测试用例分为不同类别，每个类别测试一个特定场景：
-
-```typescript
-// 成功场景
-it('应该成功完成操作', async () => {});
-
-// 边界条件
-it('应该处理边界情况', async () => {});
-
-// 错误处理
-it('应该优雅地处理错误', async () => {});
-```
-
-### 设置测试数据
-
-```typescript
-// 模拟返回值
-mockExecImpl.mockImplementation((cmd: string, callback: any) => {
-  if (cmd === '命令') {
-    callback(null, { stdout: '成功输出' });
-  } else {
-    callback(new Error('错误信息'), null);
-  }
-});
-```
-
-### 断言
-
-使用 Vitest 的断言函数验证结果：
-
-```typescript
-// 检查基本值
-expect(result.success).toBe(true);
-
-// 检查对象部分匹配
-expect(result.data).toMatchObject({
-  key: 'value',
-});
-
-// 检查数组
-expect(result.items).toHaveLength(2);
-expect(result.items[0].name).toBe('expectedName');
-
-// 检查函数调用
-expect(mockFunction).toHaveBeenCalledWith(expectedArgs);
-expect(mockFunction).toHaveBeenCalledTimes(1);
-```
-
-## 最佳实践
-
-1. **隔离测试**：确保每个测试互不影响，使用 `beforeEach` 重置模拟和状态
-2. **全面覆盖**：测试正常流程、边界条件和错误处理
-3. **清晰命名**：测试名称应清晰描述测试内容和预期结果
-4. **避免测试实现细节**：测试应该关注行为而非实现细节，使代码重构不会破坏测试
-5. **模拟外部依赖**：使用 `vi.mock()` 模拟所有外部依赖，减少测试的不确定性
-
-## 示例：测试 IPC 事件处理方法
-
-```typescript
-it('应该正确处理 IPC 事件', async () => {
-  // 模拟依赖
-  mockSomething.mockReturnValue({ result: 'success' });
-
-  // 调用 IPC 方法
-  const result = await controller.ipcMethodName({
-    param1: 'value1',
-    param2: 'value2',
-  });
-
-  // 验证结果
-  expect(result).toEqual({
-    success: true,
-    data: { result: 'success' },
-  });
-
-  // 验证依赖调用
-  expect(mockSomething).toHaveBeenCalledWith('value1', 'value2');
-});
-```

package/.cursor/rules/desktop-feature-implementation.mdc

@@ -1,155 +0,0 @@
----
-description: 当要做 electron 相关工作时
-globs:
-alwaysApply: false
----
-
-# 桌面端新功能实现指南
-
-## 桌面端应用架构概述
-
-LobeChat 桌面端基于 Electron 框架构建，采用主进程-渲染进程架构：
-
-1. **主进程 (Main Process)**：
-   - 位置：`apps/desktop/src/main`
-   - 职责：控制应用生命周期、系统API交互、窗口管理、后台服务
-
-2. **渲染进程 (Renderer Process)**：
-   - 复用 Web 端代码，位于 `src` 目录
-   - 通过 IPC 与主进程通信
-
-3. **预加载脚本 (Preload)**：
-   - 位置：`apps/desktop/src/preload`
-   - 职责：安全地暴露主进程功能给渲染进程
-
-## 添加新桌面端功能流程
-
-### 1. 确定功能需求与设计
-
-首先确定新功能的需求和设计，包括：
-
-- 功能描述和用例
-- 是否需要系统级API（如文件系统、网络等）
-- UI/UX设计（如必要）
-- 与现有功能的交互方式
-
-### 2. 在主进程中实现核心功能
-
-1. **创建控制器 (Controller)**
-   - 位置：`apps/desktop/src/main/controllers/`
-   - 示例：创建 `NewFeatureCtr.ts`
-   - 需继承 `ControllerModule`，并设置 `static readonly groupName`（例如 `static override readonly groupName = 'newFeature';`）
-   - 按 `_template.ts` 模板格式实现，并在 `apps/desktop/src/main/controllers/registry.ts` 的 `controllerIpcConstructors` 中注册，保证类型推导与自动装配
-
-2. **定义 IPC 事件处理器**
-   - 使用 `@IpcMethod()` 装饰器暴露渲染进程可访问的通道
-   - 通道名称基于 `groupName.methodName` 自动生成，不再手动拼接字符串
-   - 处理函数可通过 `getIpcContext()` 获取 `sender`、`event` 等上下文信息，并按照需要返回结构化结果
-
-3. **实现业务逻辑**
-   - 可能需要调用 Electron API 或 Node.js 原生模块
-   - 对于复杂功能，可以创建专门的服务类 (`services/`)
-
-### 3. 定义 IPC 通信类型
-
-1. **在共享类型定义中添加新类型**
-   - 位置：`packages/electron-client-ipc/src/types.ts`
-   - 添加参数类型接口（如 `NewFeatureParams`）
-   - 添加返回结果类型接口（如 `NewFeatureResult`）
-
-### 4. 在渲染进程实现前端功能
-
-1. **创建服务层**
-   - 位置：`src/services/electron/`
-   - 添加服务方法调用 IPC
-   - 使用 `ensureElectronIpc()` 生成的类型安全代理，避免手动拼通道名称
-
-   ```typescript
-   // src/services/electron/newFeatureService.ts
-   import type { NewFeatureParams } from '@lobechat/electron-client-ipc';
-
-   import { ensureElectronIpc } from '@/utils/electron/ipc';
-
-   const ipc = ensureElectronIpc();
-
-   export const newFeatureService = async (params: NewFeatureParams) => {
-     return ipc.newFeature.doSomething(params);
-   };
-   ```
-
-2. **实现 Store Action**
-   - 位置：`src/store/`
-   - 添加状态更新逻辑和错误处理
-
-3. **添加 UI 组件**
-   - 根据需要在适当位置添加UI组件
-   - 通过 Store 或 Service 层调用功能
-
-### 5. 如果是新增内置工具，遵循工具实现流程
-
-参考 `desktop-local-tools-implement.mdc` 了解更多关于添加内置工具的详细步骤。
-
-### 6. 添加测试
-
-1. **单元测试**
-   - 位置：`apps/desktop/src/main/controllers/__tests__/`
-   - 测试主进程组件功能
-
-2. **集成测试**
-   - 测试 IPC 通信和功能完整流程
-
-## 最佳实践
-
-1. **安全性考虑**
-   - 谨慎处理用户数据和文件系统访问
-   - 适当验证和清理输入数据
-   - 限制暴露给渲染进程的API范围
-
-2. **性能优化**
-   - 对于耗时操作，考虑使用异步方法
-   - 大型数据传输考虑分批处理
-
-3. **用户体验**
-   - 为长时间操作添加进度指示
-   - 提供适当的错误反馈
-   - 考虑操作的可撤销性
-
-4. **代码组织**
-   - 遵循项目现有的命名和代码风格约定
-   - 为新功能添加适当的文档和注释
-   - 功能模块化，避免过度耦合
-
-## 示例：实现系统通知功能
-
-```typescript
-// apps/desktop/src/main/controllers/NotificationCtr.ts
-import type {
-  DesktopNotificationResult,
-  ShowDesktopNotificationParams,
-} from '@lobechat/electron-client-ipc';
-import { Notification } from 'electron';
-
-import { ControllerModule, IpcMethod } from '@/controllers';
-
-export default class NotificationCtr extends ControllerModule {
-  static override readonly groupName = 'notification';
-
-  @IpcMethod()
-  async showDesktopNotification(
-    params: ShowDesktopNotificationParams,
-  ): Promise<DesktopNotificationResult> {
-    if (!Notification.isSupported()) {
-      return { error: 'Notifications not supported', success: false };
-    }
-
-    try {
-      const notification = new Notification({ body: params.body, title: params.title });
-      notification.show();
-      return { success: true };
-    } catch (error) {
-      console.error('[NotificationCtr] Failed to show notification:', error);
-      return { error: error instanceof Error ? error.message : 'Unknown error', success: false };
-    }
-  }
-}
-```

package/.cursor/rules/desktop-local-tools-implement.mdc

@@ -1,81 +0,0 @@
----
-description:
-globs:
-alwaysApply: false
----
-
-**新增桌面端工具流程:**
-
-1. **定义工具接口 (Manifest):**
-   - **文件:** `src/tools/[tool_category]/index.ts` (例如: `src/tools/local-files/index.ts`)
-   - **操作:**
-     - 在 `ApiName` 对象（例如 `LocalFilesApiName`）中添加一个新的、唯一的 API 名称。
-     - 在 `Manifest` 对象（例如 `LocalFilesManifest`）的 `api` 数组中，新增一个对象来定义新工具的接口。
-     - **关键字段:**
-       - `name`: 使用上一步定义的 API 名称。
-       - `description`: 清晰描述工具的功能，供 Agent 理解和向用户展示。
-       - `parameters`: 使用 JSON Schema 定义工具所需的输入参数。
-         - `type`: 通常是 'object'。
-         - `properties`: 定义每个参数的名称、`description`、`type` (string, number, boolean, array, etc.)，使用英文。
-         - `required`: 一个字符串数组，列出必须提供的参数名称。
-
-2. **定义相关类型:**
-   - **文件 1:** `packages/electron-client-ipc/src/types.ts` (或类似的共享 IPC 类型文件)
-     - **操作:** 定义传递给 IPC 事件的参数类型接口 (例如: `RenameLocalFileParams`, `MoveLocalFileParams`)。确保与 Manifest 中定义的 `parameters` 一致。
-   - **文件 2:** `src/tools/[tool_category]/type.ts` (例如: `src/tools/local-files/type.ts`)
-     - **操作:** 定义此工具执行后，存储在前端 Zustand Store 中的状态类型接口 (例如: `LocalRenameFileState`, `LocalMoveFileState`)。这通常包含操作结果（成功/失败）、错误信息以及相关数据（如旧路径、新路径等）。
-
-3. **实现前端状态管理 (Store Action):**
-   - **文件:** `src/store/chat/slices/builtinTool/actions/[tool_category].ts` (例如: `src/store/chat/slices/builtinTool/actions/localFile.ts`)
-   - **操作:**
-     - 导入在步骤 2 中定义的 IPC 参数类型和状态类型。
-     - 在 Action 接口 (例如: `LocalFileAction`) 中添加新 Action 的方法签名，使用对应的 IPC 参数类型。
-     - 在 `createSlice` (例如: `localFileSlice`) 中实现该 Action 方法：
-       - 接收 `id` (消息 ID) 和 `params` (符合 IPC 参数类型)。
-       - 设置加载状态 (`toggleLocalFileLoading(id, true)`)。
-       - 调用对应的 `Service` 层方法 (见步骤 4)，传递 `params`。
-       - 使用 `try...catch` 处理 `Service` 调用可能发生的错误。
-       - **成功时:**
-         - 调用 `updatePluginState(id, {...})` 更新插件状态，使用步骤 2 中定义的状态类型。
-         - 调用 `internal_updateMessageContent(id, JSON.stringify({...}))` 更新消息内容，通常包含成功确认信息。
-       - **失败时:**
-         - 记录错误 (`console.error`)。
-         - 调用 `updatePluginState(id, {...})` 更新插件状态，包含错误信息。
-         - 调用 `internal_updateMessagePluginError(id, {...})` 设置消息的错误状态。
-         - 调用 `internal_updateMessageContent(id, JSON.stringify({...}))` 更新消息内容，包含错误信息。
-       - 在 `finally` 块中取消加载状态 (`toggleLocalFileLoading(id, false)`)。
-       - 返回操作是否成功 (`boolean`)。
-
-4. **实现 Service 层 (调用 IPC):**
-   - **文件:** `src/services/electron/[tool_category]Service.ts` (例如: `src/services/electron/localFileService.ts`)
-   - **操作:**
-     - 导入在步骤 2 中定义的 IPC 参数类型。
-     - 添加一个新的 `async` 方法，方法名通常与 Action 名称对应 (例如: `renameLocalFile`)。
-     - 方法接收 `params` (符合 IPC 参数类型)。
-     - 通过 `ensureElectronIpc()` 获取 IPC 代理 (`const ipc = ensureElectronIpc();`)，调用与 Manifest 中 `name` 字段匹配的链式方法，并将 `params` 传递过去。
-     - 定义方法的返回类型，通常是 `Promise<{ success: boolean; error?: string }>`，与后端 Controller 返回的结构一致。
-
-5. **实现后端逻辑 (Controller / IPC Handler):**
-   - **文件:** `apps/desktop/src/main/controllers/[ToolName]Ctr.ts` (例如: `apps/desktop/src/main/controllers/LocalFileCtr.ts`)
-   - **操作:**
-     - 导入 Node.js 相关模块 (`fs`, `path` 等) 和 IPC 相关依赖 (`ControllerModule`, `IpcMethod`、参数类型等)。
-     - 添加一个新的 `async` 方法，方法名通常以 `handle` 开头 (例如: `handleRenameFile`)。
-     - 使用 `@IpcMethod()` 装饰器将此方法注册为对应 IPC 事件的处理器，确保方法名与 Manifest 中的 `name` 以及 Service 层的链式调用一致。
-     - 方法的参数应解构自 Service 层传递过来的对象，类型与步骤 2 中定义的 IPC 参数类型匹配。
-     - 实现核心业务逻辑：
-       - 进行必要的输入验证。
-       - 执行文件系统操作或其他后端任务 (例如: `fs.promises.rename`)。
-       - 使用 `try...catch` 捕获执行过程中的错误。
-       - 处理特定错误码 (`error.code`) 以提供更友好的错误消息。
-     - 返回一个包含 `success` (boolean) 和可选 `error` (string) 字段的对象。
-
-6. **更新 Agent 文档 (System Role):**
-   - **文件:** `src/tools/[tool_category]/systemRole.ts` (例如: `src/tools/local-files/systemRole.ts`)
-   - **操作:**
-     - 在 `<core_capabilities>` 部分添加新工具的简要描述。
-     - 如果需要，更新 `<workflow>`。
-     - 在 `<tool_usage_guidelines>` 部分为新工具添加详细的使用说明，解释其参数、用途和预期行为。
-     - 如有必要，更新 `<security_considerations>`。
-     - 如有必要（例如工具返回了新的数据结构或路径），更新 `<response_format>` 中的示例。
-
-通过遵循这些步骤，可以系统地将新的桌面端工具集成到 LobeChat 的插件系统中。