DuRT 前端开发指南

1. 技术选型与版本

- **核心框架**: Electron 24.0.0 (支持 macOS 原生 API 集成)
- **UI 框架**: React 18.2 + TypeScript 5.0 
- **状态管理**: Jotai 2.0 (轻量级原子状态)
- **样式方案**: Tailwind CSS 3.3 + CSS Modules
- **关键依赖**:
  - `system-sounds`: 1.2.0 (麦克风访问)
  - `electron-positon`: 2.1.3 (悬浮窗定位)
  - `onnxruntime-web`: 1.15.0 (本地模型推理)
- **构建工具**: Vite 4.3 + electron-builder 24.5

2. 架构设计

🔄 正在加载流程图...

graph TD A[主进程] -->|IPC通信| B[渲染进程] B --> C[语音捕获模块] B --> D[本地AI服务] B --> E[悬浮窗UI] D --> F[ONNX模型] C -->|音频流| D D -->|识别结果| E

3. 核心模块实现

3.1 悬浮窗系统

// FloatingWindow.tsx
import { useDraggable } from '@dnd-kit/core';

export default function FloatingWindow() {
  const { attributes, transform } = useDraggable({ id: 'durt-window' });
  
  return (
    <div 
      className="fixed shadow-2xl rounded-lg bg-opacity-90 backdrop-blur-md"
      style={{ 
        transform: `translate3d(${transform?.x}px, ${transform?.y}px, 0)`,
        top: '10%',
        right: '2%',
        zIndex: 9999 
      }}
      {...attributes}
    >
      <TranslationResultDisplay />
      <MicrophoneIndicator />
    </div>
  );
}

3.2 语音处理流程

// speechService.js
const { ipcRenderer } = require('electron');

const startRecognition = () => {
  navigator.mediaDevices.getUserMedia({ audio: true })
    .then(stream => {
      const processor = new AudioWorkletNode('recognition-processor.worklet');
      processor.port.onmessage = ({ data }) => {
        ipcRenderer.send('audio-chunk', data); // 发送到主进程AI推理
      };
    });
};

// 主进程处理
ipcMain.on('audio-chunk', (_, chunk) => {
  const results = ortSession.run({ input: new Float32Array(chunk) });
  mainWindow.webContents.send('translation-update', results);
});

3.3 性能优化策略

渲染优化：
- 使用 React.memo 避免结果文本重复渲染
- Canvas 绘制音频波形替代 DOM 操作
内存管理：
- 音频流分块处理（200ms/块）
- Web Workers 处理音频预处理

GPU加速：

.floating-window {
  will-change: transform, opacity;
  contain: strict;
}

4. 安全与隐私实现

### 4.1 数据安全
- 所有音频处理在本地完成（无网络请求）
- 使用 Electron 的 `safeStorage` 加密用户配置
- 禁用远程模块：`webPreferences: { nodeIntegration: false }`

### 4.2 权限控制
```javascript
// main.js
app.on('ready', () => {
  systemPreferences.askForMediaAccess('microphone'); // macOS权限请求
});

5. 可扩展性设计

// 插件接口设计
interface ITranslationPlugin {
  id: string;
  process(text: string): Promise<string>;
}

const pluginManager = {
  register(plugin: ITranslationPlugin) {
    // 注册第三方翻译引擎
  }
};

// 示例：DeepL插件集成
pluginManager.register({
  id: 'deepl',
  async process(text) {
    return await deepLTranslate(text); 
  }
});

6. 开发流程

# 环境配置
npm install -g electron-forge

# 启动开发
npm run dev # 同时启动React和Electron

# 构建命令
npm run make -- --platform=darwin

# 测试要点
- 悬浮窗置顶测试 (CMD+Tab切换验证)
- 内存泄漏测试 (持续录音1小时)
- 隐私合规测试 (使用Consolation.app监控API调用)

7. 异常处理机制

// 全局错误捕获
process.on('uncaughtException', (err) => {
  logService.sendCrashReport(err);
  showErrorOverlay('系统遇到意外错误');
});

// 音频恢复策略
navigator.mediaDevices.ondevicechange = () => {
  if (!currentStream.active) {
    reconnectAudio();
  }
};

最佳实践建议：

使用 electron-updater 实现静默更新

悬浮窗添加 NSScreen 边界检测防止越界

采用 CoreML 替代 ONNX 提升M系列芯片性能30%

本指南覆盖了从架构设计到具体实现的关键路径，重点解决本地AI集成、高性能悬浮窗、隐私保护三大核心需求。通过模块化设计保证后续可扩展第三方翻译服务，同时严格遵循Apple人机交互指南确保原生体验。

前端开发指南文档