# Cherry Studio 快捷键系统重构设计文档 v2.1

> 最近更新：2025-01-30  
> 维护者：Architecture Team

## 目录

- [背景与目标](#背景与目标)
- [核心原则](#核心原则)
- [架构分层](#架构分层)
- [关键实现](#关键实现)
- [数据流](#数据流)
- [默认快捷键](#默认快捷键)
- [迁移与兼容性](#迁移与兼容性)
- [后续演进方向](#后续演进方向)

---

## 背景与目标

旧版快捷键系统存在以下问题：

1. 依赖已弃用的 `configManager`，与 v2 架构不兼容；
2. Redux store 与本地存储重复维护状态；
3. 处理器通过 `switch-case` 硬编码，可维护性差；
4. 快捷键定义分散，缺乏统一真相源；
5. 新增快捷键需要触达多处文件，易错且低效。

新版系统要实现：

- **单一真相源**：快捷键定义集中管理，保证一致性；
- **偏好服务优先**：所有运行时状态通过 `preferenceService` 管理；
- **处理器注册表**：解除 `switch-case` 依赖，改用 Map 注册；
- **类型安全**：从定义、存储到消费全链路具备 TypeScript 约束；
- **易扩展**：新增快捷键仅需「定义 → 注册处理器 → 使用」三步；
- **性能稳定**：支持 100+ 快捷键规模，主/渲染进程高效同步；
- **多窗口同步**：借助 `preferenceService` 自动推送变更。

---

## 核心原则

1. **关注点分离**  
   - 定义层：静态元数据（名称、默认绑定、作用域、分类等）；  
   - 偏好层：用户可变配置（绑定、启用状态等）；  
   - 服务层：主进程注册、电焦/失焦时的生命周期管理；  
   - UI 层：设置面板、快捷键提示等。

2. **复用基础设施**  
   - 所有持久化均依赖 `preferenceService`（SQLite + 内存缓存 + IPC）；  
   - 变更通过订阅自动广播至所有窗口；  
   - 新增键位无需改动主进程/渲染进程的底层框架代码。

---

## 架构分层

```
┌──────────────────────────────────────────────┐
│                   Shortcut 系统               │
├──────────────────────────────────────────────┤
│ 📋 Definitions (packages/shared/shortcuts)   │
│   - types.ts：类型、作用域、分类              │
│   - definitions.ts：静态定义（真相之源）      │
│   - utils.ts：转换/校验工具                   │
│                                              │
│ 💾 Preferences (preferenceService)            │
│   - preferenceSchemas.ts 默认值               │
│   - preferenceTypes.ts 类型导出               │
│                                              │
│ ⚙️ Services                                   │
│   - src/main/services/ShortcutService.ts      │
│     · 处理器注册表、focus/blur 生命周期       │
│     · preference 订阅、主进程快捷键注册       │
│   - 渲染进程 useShortcut/useShortcutDisplay   │
│                                              │
│ 🎨 UI                                         │
│   - 设置页 ShortcutSettings                   │
│   - 各功能模块中的 useShortcut/useShortcutDisplay │
└──────────────────────────────────────────────┘
```

---

## 关键实现

### 1. 静态定义

- 所有快捷键在 `packages/shared/shortcuts/definitions.ts` 中集中维护；
- 包含 `scope`（main / renderer / both）、`category`、`persistOnBlur` 等元信息；
- `enabledWhen` 支持动态启用（如 mini window 与 quick assistant 开关关联）；
- 新增快捷键步骤：
  1. 在 `preferenceSchemas.ts` 中声明默认值；
  2. 在 `definitions.ts` 中补充静态定义；
  3. 在主/渲染进程相关模块注册处理器或消费 Hook。

### 2. 偏好系统

- 所有运行时配置通过 `preferenceService` 读写；
- 默认值与 `PreferenceShortcutType` 结构保持一致；
- `ShortcutService` / `useShortcuts` 访问偏好时统一调用 `coerceShortcutPreference`，确保 fallback 与类型安全；
- 批量重置通过 `preferenceService.setMultiple` 实现。

### 3. 主进程服务

- `ShortcutService` 负责：
  - 生命周期：随着窗口 focus/blur 注册或卸载快捷键；
  - 处理器注册：Map 替换 `switch-case`；
  - 订阅偏好变更：自动重新注册；
  - `persistOnBlur`：例如 `show_main_window` 在窗口失焦时仍可触发；
  - `shortcut.app.show_settings` 会在需要时唤起窗口并调用 `window.navigate('/settings/provider')`，避免重复 blur/focus。

### 4. 渲染进程 Hook

- `useShortcut`：从偏好获取绑定 → 转为 `react-hotkeys-hook` 字符串 → 注册快捷键；
- `useShortcutDisplay`：转换为 UI 显示字符串（`⌘` / `Ctrl+` 等）；
- `useAllShortcuts`：批量拉取配置 + diff 默认值，供设置面板使用；
- 新增 `enableOnContentEditable` 等配置支撑设置页和富文本场景。

### 5. 设置界面

- `ShortcutSettings` 直接消费 `useAllShortcuts`；
- 支持录制、清空、重置默认、启用/禁用、冲突检测；
- 重新绑定时使用 `convertKeyToAccelerator` / `isValidShortcut` / `formatShortcutDisplay`；
- “重置全部” 通过 `preferenceService.setMultiple` 一次性写入默认配置；
- 新增表格展示 `hasCustomBinding`，区分用户自定义与继承默认值。

---

## 数据流

### 启动阶段

1. `preferenceService.initialize()` 载入缓存；
2. `shortcutService` 构造时注册处理器与订阅；
3. 窗口创建后调用 `shortcutService.registerForWindow`，在 `focus` 时注册主进程快捷键。

### 运行时变更

1. 设置页或其他模块调用 `preferenceService.set` / `setMultiple`；
2. 主进程订阅触发 → `globalShortcut.unregisterAll()` → 按新配置重注册；
3. 渲染进程通过 `usePreference`/`useMultiplePreferences` 自动收到更新，UI 即时刷新。

---

## 默认快捷键

| preference key                          | 默认绑定                    | 描述 / 备注                          |
|----------------------------------------|-----------------------------|--------------------------------------|
| `shortcut.app.show_main_window`        | `Cmd/Ctrl + Shift + A`      | 主窗口显示（失焦持久）               |
| `shortcut.app.show_mini_window`        | `Cmd/Ctrl + E`              | Mini 窗口（与 quick assistant 联动） |
| `shortcut.app.show_settings`           | `Cmd/Ctrl + ,`              | 设置页入口                           |
| `shortcut.app.toggle_show_assistants`  | `Cmd/Ctrl + [`              | 助手侧边栏                           |
| `shortcut.app.exit_fullscreen`         | `Escape`                    | 系统级，不可编辑                     |
| `shortcut.app.zoom_in/out/reset`       | `Cmd/Ctrl + = / - / 0`      | 包含数字键盘变体                     |
| `shortcut.app.search_message`          | `Cmd/Ctrl + Shift + F`      | 全局搜索                             |
| `shortcut.chat.clear`                  | `Cmd/Ctrl + L`              | 清空消息                             |
| `shortcut.chat.search_message`         | `Cmd/Ctrl + F`              | 聊天内搜索                           |
| `shortcut.chat.toggle_new_context`     | `Cmd/Ctrl + K`              | 新上下文                             |
| `shortcut.chat.copy_last_message`      | `Cmd/Ctrl + Shift + C`      | 复制最后一条                         |
| `shortcut.chat.edit_last_user_message` | `Cmd/Ctrl + Shift + E`      | 编辑最后一条用户消息                 |
| `shortcut.topic.new`                   | `Cmd/Ctrl + N`              | 新增话题（默认启用）                 |
| `shortcut.topic.rename`                | `Cmd/Ctrl + T`              | 重命名话题（默认启用，自 2025-01 调整） |
| `shortcut.topic.toggle_show_topics`    | `Cmd/Ctrl + ]`              | 话题侧边栏                           |
| `shortcut.selection.*`                 | 无默认绑定                  | 划词助手开关、取词                   |

> 具体配置以 `preferenceSchemas.ts` 为准，可在设置页查看或调整。

---

## 迁移与兼容性

- 已有用户偏好：沿用旧值；新增键（如 `shortcut.topic.rename`）在数据库不存在时继承新默认；
- 旧版 Redux store / `configManager` 已彻底移除；
- `IpcChannel.Shortcuts_Update` 与 `window.api.shortcuts.update` 相关逻辑已弃用；
- `PreferenceMigrator` 中保留与旧 keys 的映射，确保升级顺畅。

---

## 后续演进方向

1. **冲突检测增强**：主/渲染进程联动校验冲突并提示；
2. **导入导出**：允许用户批量备份/恢复自定义快捷键；
3. **多作用域绑定**：同一逻辑支持按窗口类型或上下文切换；
4. **可视化录制**：增加「录制模式」避免输入框手动录制；
5. **自动化测试**：补充主进程/渲染进程快捷键单元测试样板。

---

> 如需扩展或有疑问，请联系架构团队或在仓库中提交 Issue。  
> 设计文档 v2.1 同步最新实现（2025-01），包含 `shortcut.topic.rename` 默认启用、`show_settings` 优化等补充说明。