diff --git a/.gitignore b/.gitignore index d6677d4..b0de59e 100644 --- a/.gitignore +++ b/.gitignore @@ -72,3 +72,6 @@ logs/ # Local model / runtime payloads internal/ .gstack/ + +# Internal capture working set (do not commit raw screenshot batches) +platforms/macos/client/docs/redesign/logi-options-plus-reference-spec/captures/raw-local/ diff --git a/platforms/macos/client/docs/redesign/00-glossary.md b/platforms/macos/client/docs/redesign/00-glossary.md new file mode 100644 index 0000000..95dea3a --- /dev/null +++ b/platforms/macos/client/docs/redesign/00-glossary.md @@ -0,0 +1,188 @@ +# AhaKey Studio 概念词汇表 + +更新时间：2026-05-02 +状态：规范文档（所有 redesign 文档应以本文为准） + +--- + +## 原则 + +本文档的目的是消除 AhaKey Studio 设计和开发过程中的概念混淆。每个词条给出： +- **定义**：这个词指什么 +- **不要混淆**：容易和哪些词混用 +- **用户可见文案**：UI 里应该用什么词 + +--- + +## 一、进程与运行时 + +### AhaKey Studio +**定义：** 用户打开的主 macOS 应用程序。负责配置编辑、按键映射写入、OLED 上传、UI 展示。 + +**用户可见文案：** "AhaKey Studio" + +--- + +### ahakeyconfig-agent（后台守护进程） +**定义：** 一个独立的后台进程（macOS LaunchAgent），由 AhaKey Studio 安装和管理。负责监听 Claude/Cursor/Codex 的 Hook 事件，通过 BLE 向键盘发送灯效状态、读取拨杆位置。用户不直接操作它。 + +**不要混淆：** +- 不要叫"Agent 模式"——这不是一种使用模式，是一个后台进程 +- 不要叫"AI Agent"——它不是 AI，是一个状态桥接进程 +- 不要在 UI 里暴露"ahakeyconfig-agent"这个技术名称 + +**用户可见文案：** "后台服务"或"状态同步服务"（如果必须提及） + +--- + +### AI 工具 / AI 平台（Claude Code / Cursor / Codex 等） +**定义：** 用户在电脑上运行的 AI 编程工具。AhaKey 通过 Hook 机制感知这些工具的状态，并把状态映射到键盘灯效和按键行为。 + +**不要混淆：** +- 不要叫"Agent"——Claude Code / Cursor 本身不是 AhaKey 的 Agent +- 不要叫"模式"——这是"平台"或"工具上下文" + +**用户可见文案：** "Claude Code"、"Cursor"、"Codex"（直接用产品名） + +--- + +### 通用智能体（Hermes / OpenClaw 等） +**定义：** 用户本地运行的通用 AI Agent 运行时，不绑定特定 IDE。可能同时运行多个实例，通过 app id / port 区分。 + +**不要混淆：** +- 和 ahakeyconfig-agent（后台守护进程）是完全不同的东西 +- 和 Claude Code / Cursor（IDE 工具）也不同——通用智能体没有固定的 Hook 协议 + +**用户可见文案：** "本地 Agent"（作为类别名），具体实例用产品名（"Hermes"、"OpenClaw"） + +--- + +## 二、BLE 连接 + +### BLE 连接持有方 +**定义：** CoreBluetooth 限制同一时刻只能有一个进程持有与键盘的 GATT 连接。持有方可以是 AhaKey Studio（主 App）或 ahakeyconfig-agent（后台守护进程）。 + +**不要混淆：** +- 不要叫"App 模式 / Agent 模式"——这不是模式，是底层资源的持有状态 +- 不要把这个概念暴露给用户——用户不需要知道"谁持有 BLE" + +**用户可见文案：** 不直接暴露。翻译成用户能理解的两种状态（见下） + +--- + +### 配置模式（App 持有 BLE） +**定义：** AhaKey Studio 持有 BLE 连接，可以向键盘写入配置。此时后台守护进程断开，灯效不跟随 AI 工具状态。 + +**触发：** 用户点击"编辑配置"按钮 + +**用户可见文案：** "配置中"（顶栏 chip） + +--- + +### 运行模式（后台守护进程持有 BLE） +**定义：** 后台守护进程持有 BLE 连接，灯效跟随 AI 工具状态，拨杆生效。此时 AhaKey Studio 无法向键盘发送 BLE 命令。 + +**触发：** 用户点击"完成配置"/ App 启动默认状态 + +**用户可见文案：** "运行中"（顶栏 chip） + +--- + +## 三、配置状态 + +### 草稿（Draft） +**定义：** 用户在 AhaKey Studio 里正在编辑的配置，存储在本地，尚未写入键盘。草稿在 App 关闭后持久化。 + +**不要混淆：** +- 不要叫"本地配置"——容易和"已同步配置"混淆 +- 不要叫"当前配置"——"当前"有歧义（是草稿还是设备上的？） + +**用户可见文案：** 不直接暴露"草稿"这个词。通过"未同步改动 N 项"间接表达。 + +--- + +### 已同步配置（Last Synced） +**定义：** 上一次成功写入键盘的配置快照，存储在本地。是 App 知道的"键盘应该是什么状态"。 + +**不要混淆：** +- 不等于"设备真实状态"——键盘可能在 App 不知情的情况下被其他工具修改 +- 不等于"草稿"——草稿是用户正在编辑的，已同步配置是上次写入的 + +**用户可见文案：** 不直接暴露。通过"已同步"状态标注间接表达。 + +--- + +### 设备真实状态（Device Ground Truth） +**定义：** 键盘此刻实际运行的配置。只有在 App 持有 BLE 且主动查询时才可知。运行模式下（后台守护进程持有 BLE）对 App 不可观测。 + +**不要混淆：** +- 不等于"已同步配置"——两者可能因为固件更新、其他工具写入等原因产生差异 + +**用户可见文案：** 不直接暴露。仅在切换到配置模式时触发一次查询，差异通过 banner 提示。 + +--- + +## 四、平台与模式 + +### 平台（Platform） +**定义：** 用户当前使用的 AI 工具上下文，决定了键盘按键的行为映射。对应固件层的 Mode 0/1/2，但用户不需要知道 Mode 编号。 + +**不要混淆：** +- 不要叫"模式"——"模式"在 AhaKey 里有太多含义（固件 Mode、配置模式、运行模式） +- 不要叫"场景"——太模糊 + +**用户可见文案：** 直接用产品名（"Claude Code"、"Cursor"、"Codex"） + +--- + +### 固件 Mode（Mode 0 / 1 / 2） +**定义：** 键盘固件内部的工作档位，决定了按键发出的 HID 码。是技术实现细节，不是用户概念。 + +**不要混淆：** +- 不要在 UI 里暴露"Mode 0 / 1 / 2"——用平台名替代 +- 不要叫"模式"（在用户文案里） + +**用户可见文案：** 不暴露。内部映射：Mode 0 = Claude Code，Mode 1 = Cursor，Mode 2 = Codex（默认，可配置） + +--- + +### Hook +**定义：** 安装在 AI 工具（Claude Code / Cursor / Codex）里的脚本，在工具执行特定操作时触发，向后台守护进程发送状态事件。 + +**用户可见文案：** "Hook"（技术用户可以理解），或"状态感知"（面向普通用户时） + +--- + +## 五、操作 + +### 同步（Sync） +**定义：** 把草稿写入键盘的操作。需要 App 持有 BLE 连接。 + +**用户可见文案：** "同步到键盘"（主按钮） + +--- + +### 编辑配置 +**定义：** 切换到配置模式的操作（App 抢占 BLE）。 + +**用户可见文案：** "编辑配置"（按钮） + +--- + +### 完成配置 +**定义：** 切换回运行模式的操作（App 释放 BLE，后台守护进程重新连接）。可以选择同步后切换，也可以不同步直接切换。 + +**用户可见文案：** "完成"或"同步并完成"（按钮，根据是否有未同步改动动态变化） + +--- + +## 六、禁止使用的词 + +| 禁止词 | 原因 | 替代词 | +|--------|------|--------| +| Agent 模式 | 混淆"后台守护进程"和"AI Agent"两个概念 | 运行模式 | +| App 模式 | 不直观，用户不理解"App"在这里的含义 | 配置模式 | +| 模式（单独使用） | 在 AhaKey 里有四种不同含义，必须加限定词 | 加限定词：固件 Mode / 配置模式 / 运行模式 / 平台 | +| 当前配置 | 歧义：是草稿还是已同步？ | 草稿 / 已同步配置（明确区分） | +| Agent 控制中 | 暴露了技术实现细节 | 运行中 | +| 设备信息 · Agent | 把设备信息和 Agent 混在一起 | 设备信息（独立）/ 后台服务（独立） | diff --git a/platforms/macos/client/docs/redesign/00-redesign-index.md b/platforms/macos/client/docs/redesign/00-redesign-index.md new file mode 100644 index 0000000..abf1d43 --- /dev/null +++ b/platforms/macos/client/docs/redesign/00-redesign-index.md @@ -0,0 +1,54 @@ +# AhaKey Studio macOS — 重设计文档索引 + +更新时间：2026-05-02 + +## 目录定位 + +本目录存放 AhaKey Studio macOS 客户端的 UI/UX 重设计过程中产生的**决策文档、设计规范和架构思考**。 + +与 `docs/` 根目录下的文档的区别： +- 根目录文档（`ahakey-native-director-brief.md`、`02-ux-blueprint.md`）是**当前已落地实现的规范** +- 本目录文档是**正在演进中的重设计方向**，经过审批后会合并或替换根目录文档 + +## 设计参考基准 + +| 参考产品 | 借鉴维度 | 不借鉴维度 | +|---------|---------|----------| +| Logi Options+ | 首页设备 hero、信息架构分层、Settings 层级、右上角操作区 | 多设备生态复杂度、Flow 跨设备功能 | +| Typeless | 侧栏克制、试用卡样式、权限引导优雅度 | 仪表盘指标、历史记录页 | +| Via / QMK Configurator | 画布点击配置交互、按键映射 UX | 工程师向的信息密度 | + +## 文档列表 + +| 文件 | 内容 | 状态 | +|------|------|------| +| [00-glossary.md](./00-glossary.md) | **概念词汇表（所有文档的用词基准）** | 规范 | +| [01-home-page.md](./01-home-page.md) | 首页（设备 Hero 页）重设计规范 | 草稿 | +| [02-device-studio-page.md](./02-device-studio-page.md) | 设备配置页（Studio）重设计规范 | 草稿 | +| [03-ux-state-machine.md](./03-ux-state-machine.md) | UX 状态机：连接/控制权/草稿同步三层状态 | 草稿 | +| [04-navigation-architecture.md](./04-navigation-architecture.md) | 全局导航架构与页面拆分方案 | 待写 | +| [04-settings-hierarchy.md](./04-settings-hierarchy.md) | Settings 面板层级规范 | 待写 | +| [05-voice-page.md](./05-voice-page.md) | 语音设置页重设计规范 | 待写 | +| [06-agent-page.md](./06-agent-page.md) | Agent 控制台页重设计规范 | 待写 | +| [logi-options-plus-reference-spec/09-web-electron-prototype-spec.md](./logi-options-plus-reference-spec/09-web-electron-prototype-spec.md) | **下一轮 Web / Electron 原型交付 spec** | 草稿 | +| [logi-options-plus-reference-spec/10-inspector-content-spec.md](./logi-options-plus-reference-spec/10-inspector-content-spec.md) | **Inspector 逐部件内容边界与信息披露层次** | 草稿 | + +## 专题目录 + +| 目录 | 内容 | 状态 | +|------|------|------| +| [logi-options-plus-reference-spec/](./logi-options-plus-reference-spec/00-index.md) | 以 Logi Options+ 为高保真参考样本的前台壳重构专题 spec | 草稿 | + +## 下一轮执行口径 + +截至 2026-05-03，下一轮优先做 **Web 前端原型**，必要时再用薄 Electron 壳包装给合作者体验；不在本轮完整构建 macOS 桌面应用。SwiftUI 拆分方案保留为后续原生迁移参考。 + +## 核心设计判断（持续更新） + +1. **首页是设备选择器，不是功能入口。** 用户打开 App 的第一个问题是"我要配置哪个设备"，而不是"我要用哪个功能"。即使当前只有一个设备，首页也应该以设备 hero 为中心，为生态扩展预留结构。 + +2. **三条产品主线必须分离。** 配置主线（键盘编辑）、状态反馈主线（Agent/Hook/灯效）、控制权主线（App vs Agent 蓝牙占用）不能混在同一个页面。每个导航目的地只回答一个问题。 + +3. **Inspector 只做属性编辑。** 语音配置、Agent 状态、权限管理不属于 Inspector 的职责范围，应该迁移到独立页面。Inspector 的职责是：当前选中硬件部件的属性编辑面板。 + +4. **Settings 是元操作的容器。** 只有"不属于任何具体功能页面、但影响全局行为"的操作才进 Settings。具体功能的配置（语音预设、Agent 选择）留在对应功能页面。 diff --git a/platforms/macos/client/docs/redesign/01-home-page.md b/platforms/macos/client/docs/redesign/01-home-page.md new file mode 100644 index 0000000..7fab248 --- /dev/null +++ b/platforms/macos/client/docs/redesign/01-home-page.md @@ -0,0 +1,247 @@ +# 首页（设备 Hero 页）重设计规范 + +更新时间：2026-05-02 +状态：草稿 + +参考：Logi Options+ 首页（设备总览页） + +--- + +## 1. 页面定位 + +**首页回答一个问题：我有哪些 AhaKey 设备，我要配置哪一个？** + +首页不是功能入口，不是仪表盘，不是状态监控页。它是一个**设备选择器**，以设备的视觉形态为中心，让用户建立"我在配置一个真实的物理设备"的心智。 + +当前实现的问题：App 启动后直接进入配置界面（`AhaKeyStudioView`），跳过了设备选择层。这在只有一个设备时可以接受，但结构上是错的——它把"选择设备"和"配置设备"混在了同一个视图里。 + +--- + +## 2. 页面结构 + +``` +┌─────────────────────────────────────────────────────────────────┐ +│ 顶栏 │ +│ [AhaKey Studio] [+ 添加设备] [⚡ 快捷操作] [⚙] │ +├─────────────────────────────────────────────────────────────────┤ +│ │ +│ │ +│ 设备 Hero 区（可滚动） │ +│ │ +│ ┌──────────────────────────────────┐ │ +│ │ │ │ +│ │ AhaKey 键盘渲染（1:1） │ │ +│ │ │ │ +│ └──────────────────────────────────┘ │ +│ vibe code 154F │ +│ 🔋 68% · 已连接 · Mode 2 │ +│ │ +│ （未来：多设备时横向排列，类 Logi Options+ 布局） │ +│ │ +│ │ +└─────────────────────────────────────────────────────────────────┘ +``` + +--- + +## 3. 顶栏设计 + +顶栏采用**三区布局**：左品牌 / 中空 / 右操作区。 + +### 3.1 左侧：品牌区 + +- App 名称：`AhaKey Studio` +- 不放设备状态（设备状态在 hero 区下方） +- 不放 Pro Trial 徽章（Trial 状态放在 hero 区下方或侧边） + +### 3.2 右侧操作区（从左到右） + +``` +[+ 添加设备] [⚡ 快捷操作] | [⚙ 设置] +``` + +**+ 添加设备**：扫描并配对新设备。当前版本可以是一个扫描 BLE 的 sheet。 + +**⚡ 快捷操作**（对应 Logi Options+ 的 Smart Actions）： +见第 4 节详细说明。 + +**⚙ 设置**：全局设置面板。见第 5 节详细说明。 + +**账户图标**：暂不需要。AhaKey 当前无需用户鉴权。 +Trial/Pro 状态通过 hero 区下方的徽章或侧边卡片展示，不需要独立账户入口。 +（未来如果引入云同步或订阅，再加账户图标。） + +--- + +## 4. 快捷操作（⚡ Quick Actions） + +对应 Logi Options+ 的 Smart Actions，但语义完全不同。 + +Logi Options+ 的 Smart Actions 是跨设备自动化工作流。AhaKey 的快捷操作是**一键切换当前工作上下文**。 + +### 4.1 核心操作 + +| 操作 | 说明 | +|------|------| +| **切换到 Agent 模式** | 将键盘切换到 Agent 控制模式（拨杆自动批准 + Agent 接管蓝牙） | +| **切换到 IDE 模式** | 将键盘切换到 IDE 配置模式（App 控制蓝牙，用户手动操作） | +| **同步所有配置到设备** | 一键把当前草稿全部同步到键盘 | +| **重启 Agent** | Agent 进程异常时快速重启 | + +### 4.2 交互形式 + +点击 ⚡ 图标后弹出一个轻量 popover（不是 sheet，不是新窗口），列出上述操作。 + +每个操作用一行：图标 + 标题 + 当前状态说明。例如： + +``` +⚡ 快捷操作 +───────────────────────────── +🤖 切换到 Agent 模式 + 当前：IDE 模式 · App 控制蓝牙 + +🖥 切换到 IDE 模式 + 当前：已在 IDE 模式 + +↑ 同步所有配置到设备 + 上次同步：3 分钟前 + +↺ 重启 Agent + Agent 状态：未运行 +───────────────────────────── +``` + +### 4.3 为什么不用 segmented control 或 toolbar 按钮 + +Agent 模式 / IDE 模式的切换不是高频操作——用户不会每隔几分钟就切换一次。把它放在 toolbar 的 segmented control 里会让 toolbar 显得很重。放在 Quick Actions popover 里，既保持了 toolbar 的轻量，又让操作可发现。 + +--- + +## 5. 设置面板（⚙ Settings） + +Settings 只放**元操作**：不属于任何具体功能页面、但影响全局行为的配置。 + +具体功能的配置（语音预设、Agent 选择、按键映射）留在对应功能页面，不进 Settings。 + +### 5.1 层级结构 + +``` +设置 +│ +├── 通用（General） +│ ├── 登录时启动 AhaKey Studio +│ ├── 外观：浅色 / 深色 / 跟随系统 +│ └── 语言（如果未来支持多语言） +│ +├── 设备（Device） +│ ├── 默认连接行为（自动连接 / 手动连接） +│ ├── 断开连接时的行为（保持草稿 / 重置） +│ └── 固件更新（检查更新 / 自动更新） +│ +├── Agent 与 Hook +│ ├── Claude Hooks 安装状态 + 安装/卸载 +│ ├── Cursor Hooks 安装状态 + 安装/卸载 +│ ├── Codex Hooks 安装状态 + 安装/卸载 +│ └── Agent 自动启动（登录时 / 手动） +│ +├── 语音（Voice） +│ ├── 默认语音预设（macOS 原生 / Typeless / 微信 / …） +│ ├── 转写语言 +│ └── 权限管理（麦克风 / 语音转写 / 输入监控 / 辅助功能） +│ +├── 通知（Notifications） +│ ├── 设备连接/断开通知 +│ ├── Agent 状态变化通知 +│ └── 同步完成通知 +│ +└── 高级（Advanced） + ├── 诊断模式（展开 BLE 日志、UUID、通信帧） + ├── 导出诊断文件 + ├── 重置所有配置到出厂默认 + └── 关于（版本号、开源协议、反馈入口） +``` + +### 5.2 分层原则 + +**一级分组**（侧栏导航）：通用 / 设备 / Agent 与 Hook / 语音 / 通知 / 高级 + +**二级内容**（右侧面板）：每个分组对应一个设置面板，用 `Form` 或分组列表展示。 + +**高级分组的处理**：高级分组里的内容（诊断模式、BLE 日志）对普通用户是噪音，但对开发者和售后很重要。建议： +- 高级分组默认折叠或放在列表最底部 +- 诊断模式用一个 toggle 开关控制，开启后才展示 BLE 细节 +- 不要把 BLE UUID、通信日志等工程信息放在普通用户能轻易看到的地方 + +### 5.3 Settings 的实现形式 + +macOS 原生 Settings 用 `Settings` scene（SwiftUI）或 `NSWindowController` + `NSTabViewController`。 + +推荐用 SwiftUI 的 `Settings` scene，配合 `Form` 和 `Section`，风格与系统偏好设置一致。 + +--- + +## 6. 设备 Hero 区 + +### 6.1 单设备状态（当前） + +设备渲染居中，下方显示： +- 设备名（可编辑，双击进入编辑） +- 电量 + 连接状态 + 当前 Mode +- 点击设备渲染 → 进入 Studio 配置页 + +### 6.2 多设备状态（未来） + +多个设备横向排列，类 Logi Options+ 布局： +- 每个设备一个卡片，包含渲染 + 名称 + 状态 +- 点击卡片 → 进入该设备的 Studio 配置页 +- 未连接的设备显示为灰色/半透明 + +### 6.3 无设备状态 + +显示一个空状态区域： +- 插图（AhaKey 键盘轮廓，虚线风格） +- 文案：「还没有连接的设备」 +- 按钮：「+ 添加设备」 + +### 6.4 设备渲染的技术实现 + +当前 `AhaKeyKeyboardCanvasView` 是一个 SwiftUI 绘制的 1:1 键盘画布，用于配置页。 + +首页的设备渲染可以复用同一个 View，但以**只读模式**展示（不显示热区高亮，不响应点击配置）。 +点击整个设备区域 → 导航到 Studio 配置页。 + +--- + +## 7. 与现有实现的关系 + +### 当前实现 + +``` +ContentView.swift + └── AhaKeyStudioView.swift（直接进入配置界面） +``` + +### 目标结构 + +``` +ContentView.swift + ├── HomeView.swift（首页：设备 Hero 页）← 新增 + │ └── 点击设备 → 导航到 StudioView + └── StudioView.swift（配置页：画布 + Inspector）← 重构自 AhaKeyStudioView +``` + +### 迁移策略 + +1. 新建 `HomeView.swift`，实现首页结构 +2. `AhaKeyStudioView` 重命名为 `StudioView`，作为从首页导航进入的子页面 +3. `ContentView` 改为根据连接状态决定显示 `HomeView` 还是直接进入 `StudioView` +4. 语音配置、Agent 状态从 `StudioView` 的 Inspector 迁移到独立页面（见后续文档） + +--- + +## 8. 待决策项 + +- [ ] 首页是否需要侧栏导航？（Logi Options+ 没有侧栏，导航完全通过设备点击） +- [ ] 快捷操作 popover 的触发方式：点击图标 vs 长按设备渲染 +- [ ] 设备渲染在首页是否需要动效（OLED 动图、灯条动效） +- [ ] Trial/Pro 状态的展示位置：hero 区下方 vs 顶栏右侧 vs 侧边卡片 diff --git a/platforms/macos/client/docs/redesign/02-device-studio-page.md b/platforms/macos/client/docs/redesign/02-device-studio-page.md new file mode 100644 index 0000000..3e57746 --- /dev/null +++ b/platforms/macos/client/docs/redesign/02-device-studio-page.md @@ -0,0 +1,313 @@ +# 设备配置页（Studio）重设计规范 + +更新时间：2026-05-02 +状态：草稿 + +参考：Logi Options+ 设备详情页（Keys / Easy-Switch / Settings 三段导航 + Add Application 机制） + +--- + +## 1. 页面定位 + +**设备配置页回答一个问题：这台 AhaKey 键盘在不同 AI 工具上下文里，每个硬件部件应该做什么？** + +从首页点击设备渲染后进入本页。本页是 AhaKey Studio 的核心工作区。 + +--- + +## 2. 页面骨架 + +``` +┌─────────────────────────────────────────────────────────────────────┐ +│ ← AhaKey Studio [Claude] [Cursor] [Codex] [+] [⚙ 设置] │ +│ vibe code 154F │ +├──────────┬──────────────────────────────────────────────────────────┤ +│ │ │ +│ 左侧 │ 中央：键盘画布（1:1，可点击热区） │ +│ 导航 │ │ +│ │ │ +│ ⌨ 按键 │ │ +│ 🖥 OLED │ │ +│ 💡 灯条 │ │ +│ 🔀 拨杆 │ │ +│ │ │ +│ ───── │ │ +│ 🤖 Agent │ │ +│ 🎙 语音 │ │ +│ │ │ +│ ───── │ │ +│ ℹ 设备 │ │ +│ │ │ +│ ───── │ │ +│ 🔋 68% │ │ +│ ⚡ Mode2 │ │ +│ │ │ +└──────────┴──────────────────────────────────────────────────────────┘ +``` + +当用户点击画布上的某个热区后，右侧 Inspector 展开： + +``` +┌──────────┬──────────────────────────────┬──────────────────────────┐ +│ 左侧 │ 中央：键盘画布 │ 右侧：Inspector │ +│ 导航 │ （Key 1 高亮选中） │ │ +│ │ │ Key 1 · 语音键 │ +│ ⌨ 按键 │ │ ───────────────────── │ +│ 🖥 OLED │ │ [Claude 上下文] │ +│ 💡 灯条 │ │ 语音预设：macOS 原生 │ +│ 🔀 拨杆 │ │ 快捷键绑定：F18 │ +│ │ │ 按键描述：Record │ +│ ───── │ │ │ +│ 🤖 Agent │ │ ───────────────────── │ +│ 🎙 语音 │ │ [同步到键盘] │ +│ │ │ │ +└──────────┴──────────────────────────────┴──────────────────────────┘ +``` + +--- + +## 3. 顶栏设计 + +### 3.1 左侧：返回 + 设备名 + +``` +← AhaKey Studio vibe code 154F +``` + +- `←` 返回首页（设备选择器） +- 设备名可点击进入设备信息页（或 inline 编辑） + +### 3.2 右侧：平台上下文切换器 + 设置 + +``` +[Claude logo] [Cursor logo] [Codex logo] [+] | [⚙] +``` + +这是本页最关键的设计决策，见第 4 节详细说明。 + +--- + +## 4. 平台上下文切换器（核心设计） + +### 4.1 概念映射 + +| Logi Options+ | AhaKey | +|--------------|--------| +| Add Application | 添加 AI 平台 | +| 应用图标切换器 | Claude / Cursor / Codex logo 切换器 | +| 当前前台应用（自动切换） | 当前工作模式（手动切换 + 硬件拨杆） | +| 每个应用独立的按键映射 | 每个平台独立的按键映射 | + +AhaKey 的"平台"（Claude Code / Cursor / Codex）本质上就是 Logi Options+ 的"应用"。两者都是"同一个硬件设备，在不同软件上下文里有不同的按键行为"。 + +### 4.2 交互逻辑 + +**状态一：未选中任何键位（画布默认态）** + +顶栏右侧显示平台图标列表，当前选中的平台图标有下划线高亮。 +画布显示当前平台下所有键位的摘要标签（类 Logi Options+ 的 callout 标签）。 +右侧 Inspector 不展开（或显示当前平台的全局说明）。 + +``` +顶栏：[Claude ▼] [Cursor] [Codex] [+] +画布：Key1=Record Key2=Yes Key3=No Key4=Enter （callout 标签） +右侧：空 / 平台说明 +``` + +**状态二：点击画布上的某个键位** + +右侧 Inspector 展开，显示该键位在当前平台下的配置。 +Inspector 顶部显示当前平台 logo + 平台名，可在此切换平台（不需要回到顶栏）。 + +``` +顶栏：[Claude ▼] [Cursor] [Codex] [+] +画布：Key1 高亮选中 +右侧： + Inspector + ───────────────── + [Claude logo] Claude Code + ───────────────── + Key 1 · 语音键 + 语音预设：macOS 原生 + 快捷键绑定：F18 + 按键描述：Record + ───────────────── + [同步到键盘] +``` + +**状态三：在 Inspector 展开态切换平台** + +点击 Inspector 顶部的平台 logo → 切换到该平台的配置，键位选中状态保持不变。 +顶栏的平台切换器同步更新高亮。 + +### 4.3 为什么用顶栏图标而不是 segmented control + +当前实现用的是 `Picker(.segmented)` 显示 "Mode 0 / Mode 1 / Mode 2"。这有两个问题： + +1. "Mode 0 / 1 / 2" 是固件层的概念，对用户来说不直观 +2. Segmented control 占用了顶栏大量空间，且视觉权重过高 + +改用平台 logo 图标（类 Logi Options+ 的应用图标切换器）的优势： +- 视觉识别度高（Claude / Cursor / Codex 的 logo 用户已经熟悉） +- 占用空间小 +- 可扩展（未来加新平台只需加一个图标） +- 与 Logi Options+ 的交互范式一致，用户学习成本低 + +### 4.4 平台与 Mode 的映射关系 + +平台（Claude / Cursor / Codex）是用户心智模型中的概念。 +Mode（0 / 1 / 2）是固件层的概念。 + +两者的映射关系在 Studio 内部处理，不暴露给用户： + +| 用户看到的 | 固件层 | +|-----------|--------| +| Claude Code | Mode 0 | +| Cursor | Mode 1 | +| Codex | Mode 2 | + +这个映射关系应该是可配置的（用户可以把 Cursor 映射到 Mode 0），但默认值固定。 + +--- + +## 5. 左侧导航 + +左侧导航按**硬件部件**和**软件功能**两个维度分组。 + +### 5.1 硬件部件组 + +| 图标 | 标签 | 说明 | +|------|------|------| +| ⌨ | 按键 | 四个主按键（Key 1~4）的配置入口 | +| 🖥 | OLED | OLED 屏幕的动图和显示配置 | +| 💡 | 灯条 | 灯条状态映射（只读，出厂固件驱动） | +| 🔀 | 拨杆 | 自动批准 / 手动批准切换逻辑 | + +点击左侧导航项 → 画布高亮对应的硬件区域 → Inspector 展开对应配置。 +这和直接点击画布热区的效果相同，两者互相联动。 + +### 5.2 软件功能组 + +| 图标 | 标签 | 说明 | +|------|------|------| +| 🤖 | Agent | Agent 状态、Hook 安装、蓝牙控制权 | +| 🎙 | 语音 | 语音预设、权限管理、转写配置 | + +这两项不对应具体的硬件部件，而是跨硬件的软件功能配置。 +点击后进入独立的配置视图（不是 Inspector，而是替换中央区域的内容）。 + +### 5.3 设备信息组 + +| 图标 | 标签 | 说明 | +|------|------|------| +| ℹ | 设备 | 固件版本、BLE 诊断、高级设置 | + +### 5.4 底部状态区 + +左侧导航底部（类 Logi Options+ 的左下角电量 + 蓝牙图标）： + +``` +🔋 68% ⚡ Mode 2 ● 已连接 +``` + +这些是只读状态，不是可点击的导航项。 + +--- + +## 6. 中央画布区 + +### 6.1 默认态（未选中键位） + +画布显示完整键盘，每个热区上方有 callout 标签，显示当前平台下的功能摘要： + +``` +[Record] [Yes] [No] [Enter] +``` + +类 Logi Options+ 的 callout 标签风格：白色圆角矩形，细线连接到热区。 + +### 6.2 选中态 + +选中的热区有明显描边 + 外发光。 +其他热区降低对比度（不消失，保持空间感）。 +右侧 Inspector 展开。 + +### 6.3 画布顶部信息条 + +画布顶部有一条轻量信息条，显示当前上下文： + +``` +[Claude logo] Claude Code · Key 1 已选中 · 待同步 2 项 +``` + +--- + +## 7. 右侧 Inspector + +Inspector 只在用户选中某个热区后展开。未选中时不显示（或显示空状态提示）。 + +### 7.1 Inspector 头部 + +``` +[平台 logo] 平台名 +───────────────── +部件名 · 部件副标题 +[未同步] / [已同步] +``` + +平台 logo 可点击切换平台（不需要回到顶栏）。 + +### 7.2 Inspector 内容 + +根据选中的部件类型，显示对应的配置项： + +**按键（Key 1~4）**： +- 快捷键绑定 / 宏 +- 按键描述（写入 OLED） +- 语音预设（仅 Key 1） + +**OLED**： +- 当前模式的动图选择 +- 帧率设置 + +**灯条**： +- 只读说明（出厂固件驱动） +- 状态预览（可发送到设备预览） + +**拨杆**： +- 当前档位（只读，来自硬件） +- 自动批准 / 手动批准的行为说明 + +### 7.3 Inspector 底部操作栏 + +固定在 Inspector 底部，不随内容滚动： + +``` +[切换模式] [同步到键盘] +``` + +- 左侧次按钮：切换到下一个平台（快捷操作） +- 右侧主按钮：同步当前草稿到键盘 + +--- + +## 8. 与当前实现的差异 + +| 维度 | 当前实现 | 目标设计 | +|------|---------|---------| +| 平台切换 | Segmented control "Mode 0/1/2" | 顶栏平台 logo 图标切换器 | +| 左侧导航 | 无（单页全功能） | 硬件部件 + 软件功能两组导航 | +| 语音配置 | 嵌套在 Key 1 的 Inspector 里 | 独立的"语音"导航项 | +| Agent 状态 | 嵌套在拨杆 Inspector 里 | 独立的"Agent"导航项 | +| Inspector 展开时机 | 始终展开 | 仅在选中热区后展开 | +| 平台概念 | 暴露 Mode 0/1/2 | 隐藏 Mode，暴露 Claude/Cursor/Codex | + +--- + +## 9. 待决策项 + +- [ ] 平台 logo 切换器：点击切换 vs hover 预览 vs 下拉菜单 +- [ ] 未选中热区时，Inspector 区域显示什么（空状态 / 平台全局说明 / 隐藏） +- [ ] 左侧导航的"Agent"和"语音"是否替换中央画布，还是在右侧 Inspector 展开 +- [ ] 平台与 Mode 的映射是否允许用户自定义 +- [ ] callout 标签的显示时机：始终显示 vs 仅在 hover 时显示 diff --git a/platforms/macos/client/docs/redesign/03-ux-state-machine.md b/platforms/macos/client/docs/redesign/03-ux-state-machine.md new file mode 100644 index 0000000..1790398 --- /dev/null +++ b/platforms/macos/client/docs/redesign/03-ux-state-machine.md @@ -0,0 +1,182 @@ +# AhaKey Studio UX 状态机设计规范 + +更新时间：2026-05-02 +状态：草稿 + +--- + +## 1. 问题定位 + +AhaKey Studio 是一个上位机软件。它的 UX 难点不在于界面美观，而在于它同时管理三个独立的状态空间，且这三个空间随时可能不一致： + +``` +本地草稿（用户正在编辑的意图） + ≠ +已同步到设备的配置（上次成功写入键盘的值） + ≠ +设备当前真实状态（键盘此刻实际运行的值） +``` + +Logi Options+ 不存在这个问题，因为它的配置是即时生效的（写入即同步）。AhaKey 因为 BLE 写入有代价、需要显式触发，所以这三个空间必须被显式管理。 + +--- + +## 2. 设备连接状态机 + +AhaKey 的设备连接有五个状态，不是简单的"连接/断开"： + +``` +未扫描 + ↓ 用户触发 / App 启动 +扫描中 + ↓ 发现设备 +已发现（未连接） + ↓ 用户确认 / 自动连接 +连接中 + ↓ 成功 +已连接 + ↓ 断开（掉线 / 用户主动 / Agent 接管） +已断开（有上次同步记录） +``` + +**关键设计原则：每个状态下，用户能做什么、看到什么，必须有明确规则。** + +| 连接状态 | 画布显示 | Inspector | 同步按钮 | 状态指示 | +|---------|---------|-----------|---------|---------| +| 未扫描 / 扫描中 | 设备轮廓（灰色） | 可编辑草稿 | 禁用，提示"等待连接" | 顶栏 chip：扫描中 | +| 已连接（App 控制） | 完整画布，实时状态 | 可编辑 | 启用 | 顶栏 chip：编辑配置中 | +| 已连接（Agent 控制） | 完整画布，只读 | 只读 + 提示 | 禁用，提示"Agent 控制中" | 顶栏 chip：键盘控制中 | +| 已断开（有草稿） | 设备轮廓（半透明） | 可编辑草稿，标注"离线草稿" | 禁用，提示"连接后可同步" | 顶栏 chip：已断开 | + +**离线编辑是允许的，但必须清楚标注"本地草稿"。** 用户可以在设备不在线时继续编辑，重连后提示差异并确认同步。 + +--- + +## 3. 蓝牙控制权状态机 + +这是 AhaKey 特有的复杂度，Logi Options+ 完全没有对应物。 + +CoreBluetooth 同一时刻只能有一个进程连接键盘，所以 App 和 Agent 之间存在控制权竞争： + +``` +App 控制（编辑配置模式） + ↔ 用户点"同步并返回控制" / "编辑配置" +Agent 控制（运行时模式） +``` + +**这个状态是 AhaKey 最核心的 UX 状态，必须始终可见，但不能喧宾夺主。** + +设计原则： +- 控制权状态用顶栏的一个 chip 表达，始终可见 +- chip 颜色：蓝色 = App 控制（编辑中），绿色 = Agent 控制（运行中） +- 切换控制权的操作是主按钮（"同步到键盘" / "编辑配置"），不是隐藏在菜单里 + +--- + +## 4. 草稿同步状态机 + +``` +已同步（草稿 = 设备） + ↓ 用户编辑 +有未同步改动（草稿 ≠ 设备） + ↓ 用户点同步 +同步中 + ↓ 成功 +已同步 + ↓ 失败 +同步失败（草稿 ≠ 设备，有错误信息） +``` + +**底部状态栏只需要表达这一个维度：** + +``` +✓ 已同步 （绿色，轻量） +● 未同步改动 3 项 （橙色，中等权重） +↑ 同步中… （蓝色，动效） +✗ 同步失败：设备未响应 [重试] （红色，需要操作） +``` + +当前实现把"选中部件 · 当前模式"也放在底部状态栏，这是冗余的——选中状态已经在画布和 Inspector 里体现了。底部状态栏应该只表达同步状态。 + +--- + +## 5. 状态信息的归属原则 + +基于以上分析，各类状态信息的正确归属： + +### 归入首页（设备 Hero 页） +- 电量 +- 蓝牙连接状态（已连接 / 未连接） +- 固件版本 +- 设备名 + +**理由：** Logi Options+ 把这些放在首页设备卡片下方是对的。这些是"设备身份信息"，不是"编辑会话信息"。用户进入配置页后不需要时刻看到电量——那是首页的职责。 + +### 归入顶栏 chip（始终可见） +- 蓝牙控制权（App 控制 / Agent 控制） +- 当前平台（Claude / Cursor / Codex） + +**理由：** 这两个是"当前会话的核心上下文"，用户在配置页的任何操作都依赖这两个状态。 + +### 归入底部状态栏（轻量，仅同步状态） +- 未同步改动数量 +- 同步进度 / 结果 + +**理由：** 类 IDE 底部状态栏，视觉权重最低，只在需要时引起注意。 + +### 归入左侧导航底部（设备状态区） +- 拨杆当前档位（自动批准 / 手动批准） +- 连接状态简要（已连接 · vibe code 154F） + +**理由：** 拨杆状态是硬件状态，不是编辑会话状态，放在左侧导航底部类 Logi Options+ 的左下角状态区。 + +### 从顶栏移除 +- 电量（移入首页） +- 设备名（移入首页 / 左侧导航底部） +- "扫描中 · 等待设备"（移入顶栏 chip，简化表达） + +--- + +## 6. "更多"菜单的拆解归位 + +| 原操作 | 归入位置 | 理由 | +|--------|---------|------| +| 恢复当前模式默认值 | 对应平台 Inspector 底部（破坏性操作，需上下文） | 破坏性操作不应在全局菜单 | +| 重新连接设备 | 顶栏连接状态 chip 的点击操作 / 左侧导航底部 | 连接操作应在连接状态旁边 | +| 清空 OLED 预览 | OLED Inspector 内部 | 局部操作归入局部上下文 | +| 设备信息 | 左侧导航"设备"项 | 导航入口不应在菜单里 | +| 隐藏到后台 | 删除，交给 macOS ⌘W | 系统级操作 | +| 退出 AhaKey Studio | 删除，交给 macOS ⌘Q | 系统级操作 | + +"更多"菜单拆解后应该消失。 + +--- + +## 7. 重连时的 UX 流程 + +这是上位机 UX 最容易做错的地方。 + +**场景：用户在离线状态下编辑了草稿，设备重新连接。** + +``` +设备重新连接 + ↓ +检测本地草稿 vs 设备当前配置 + ↓ +有差异？ + ├── 否 → 静默同步，底部状态栏显示"已同步" + └── 是 → 顶部 banner 提示： + "检测到 3 项本地改动与设备当前配置不同" + [查看差异] [同步到设备] [放弃本地改动] +``` + +不要自动覆盖，不要静默丢弃。用户必须知道发生了什么。 + +--- + +## 8. 待决策项 + +- [ ] 离线草稿的视觉标注方式：整体 banner vs 每个改动项单独标注 +- [ ] 重连时差异提示的触发时机：立即弹出 vs 用户主动点同步时提示 +- [ ] Agent 控制期间，用户是否可以预览（只读）配置，还是完全锁定 +- [ ] 拨杆状态变化（用户物理拨动）是否需要在 UI 里有即时反馈动效 diff --git a/platforms/macos/client/docs/redesign/logi-options-plus-reference-spec/00-index.md b/platforms/macos/client/docs/redesign/logi-options-plus-reference-spec/00-index.md new file mode 100644 index 0000000..13598f4 --- /dev/null +++ b/platforms/macos/client/docs/redesign/logi-options-plus-reference-spec/00-index.md @@ -0,0 +1,151 @@ +# AhaKey Studio macOS - Logi Options+ Reference Spec + +更新时间：2026-05-02 +状态：专题参考 spec（高保真重构工作底稿） + +--- + +## 1. 目录目的 + +本目录用于沉淀一套**以 Logi Options+ 为高保真参考，对 AhaKey Studio 前台壳做高保真重构**的详细 spec。 + +这不是一套“直接替换现有正式规范”的文档，而是一组为下一轮重构服务的**专题参考文档**。它回答的问题不是“当前代码已经是什么”，而是： + +- Logi Options+ 的前台产品壳到底有哪些值得借鉴的结构 +- 哪些借鉴适合 AhaKey，哪些不适合 +- AhaKey 特有的 BLE / Agent / 草稿同步复杂度，应该如何嫁接到 Logi 式 UI/UX 语言里 +- 后续 Web / Electron 原型与 SwiftUI 原生重构时，页面、组件、导航和状态层应该怎样拆 + +--- + +## 2. 与现有文档的关系 + +本目录与以下文档并行存在： + +- [00-redesign-index.md](../00-redesign-index.md)：`redesign/` 的总索引 +- [00-glossary.md](../00-glossary.md)：所有重设计文档的用词基准 +- [02-ux-blueprint.md](../../02-ux-blueprint.md)：当前已落地原生实现的首版蓝图 + +关系说明： + +1. [02-ux-blueprint.md](../../02-ux-blueprint.md) 记录的是**当前首版已落地实现**。 +2. `redesign/` 目录下原有草稿，记录的是**AhaKey 自身正在演进中的重设计方向**。 +3. 本目录记录的是**“以 Logi Options+ 为高保真参考样本”这条专题线**，重点是把参考对象、迁移原则和实现拆分写清楚。 + +因此，本目录的文档默认都属于： + +- 正在演进中的参考 spec +- 可以指导实现 +- 但不会自动替代根级正式规范 + +只有在后续重构真正落地并经过审批后，才会把其中稳定的部分提升为正式规范，或并入根级文档。 + +--- + +## 3. 阅读顺序 + +建议按以下顺序阅读： + +1. [01-reference-baseline.md](./01-reference-baseline.md) +2. [02-information-architecture.md](./02-information-architecture.md) +3. [03-home-overview-spec.md](./03-home-overview-spec.md) +4. [04-device-studio-spec.md](./04-device-studio-spec.md) +5. [05-secondary-pages-spec.md](./05-secondary-pages-spec.md) +6. [06-state-machine-spec.md](./06-state-machine-spec.md) +7. [07-visual-system-spec.md](./07-visual-system-spec.md) +8. [09-web-electron-prototype-spec.md](./09-web-electron-prototype-spec.md) +9. [08-swiftui-implementation-spec.md](./08-swiftui-implementation-spec.md) + +阅读逻辑： + +- `01` 先界定“参考对象是什么、我们看到了什么、哪些不能照搬” +- `02~05` 给出前台产品壳与各页面 spec +- `06` 单独处理 AhaKey 最复杂的状态问题 +- `07` 把“像 Logi”收敛成可执行的视觉与组件规则 +- `09` 定义下一轮优先执行的 Web / Electron 原型交付边界 +- `08` 保留为后续 SwiftUI 原生迁移参考 + +--- + +## 4. 文档列表 + +| 文件 | 作用 | 状态 | +|------|------|------| +| [01-reference-baseline.md](./01-reference-baseline.md) | Logi 参考样本基线、可观察证据、借鉴边界 | 草稿 | +| [02-information-architecture.md](./02-information-architecture.md) | AhaKey 前台信息架构与导航骨架 | 草稿 | +| [03-home-overview-spec.md](./03-home-overview-spec.md) | 首页设备总览页详细 spec | 草稿 | +| [04-device-studio-spec.md](./04-device-studio-spec.md) | 设备工作区详细 spec | 草稿 | +| [05-secondary-pages-spec.md](./05-secondary-pages-spec.md) | Agent / 语音 / Settings / 设备信息等次级页面 spec | 草稿 | +| [06-state-machine-spec.md](./06-state-machine-spec.md) | BLE / 控制权 / 草稿同步三层状态机 | 草稿 | +| [07-visual-system-spec.md](./07-visual-system-spec.md) | 视觉系统、token 与组件语气 | 草稿 | +| [09-web-electron-prototype-spec.md](./09-web-electron-prototype-spec.md) | 下一轮 Web / Electron 原型交付 spec | 草稿 | +| [10-inspector-content-spec.md](./10-inspector-content-spec.md) | Inspector 逐部件内容边界与信息披露层次 | 草稿 | +| [08-swiftui-implementation-spec.md](./08-swiftui-implementation-spec.md) | SwiftUI 重构拆分与实现约束，现作为后续原生迁移参考 | 草稿 | + +附属目录： + +- [captures](./captures/)：后续存放截图、标注图、页面比对图，仅做内部参考 + +--- + +## 5. 本目录的适用边界 + +本目录默认采用以下边界： + +### 5.1 借鉴对象 + +借鉴的是 Logi Options+ 的： + +- 信息架构 +- 页面骨架 +- 导航层次 +- 工作区组织方式 +- 组件语气 +- 视觉节奏 +- 设置层级 + +不是借鉴它的： + +- 设备生态规模 +- Flow 自动化能力 +- Logitech 品牌表达 +- 云服务 / 账户体系 +- 具体后端协议和业务能力 + +### 5.2 实现目标 + +目标是让 AhaKey 的前台壳达到： + +- 用户第一次打开时更像成熟桌面产品 +- 页面职责更清晰 +- AhaKey 的复杂状态被表达清楚 +- 后续拆 Web / Electron 或 SwiftUI 组件和页面时有明确边界 + +不是目标： + +- 做一份法律意义上的逐像素复制 +- 在本阶段改变 BLE / Agent / Voice 后端协议 +- 直接从 Logi 包里搬资源进正式产物 + +### 5.3 下一轮交付口径 + +截至 2026-05-03，下一轮优先交付不再是完整 macOS 原生应用，而是： + +- 先做浏览器可运行的 Web 前端原型 +- 必要时用极薄 Electron 壳包装给合作者体验 +- 不在本轮接入真实 BLE、系统权限、后台协议或完整桌面发布链路 + +详见 [09-web-electron-prototype-spec.md](./09-web-electron-prototype-spec.md)。 + +--- + +## 6. 输出标准 + +本目录下的每份文档都应该做到： + +1. 另一个工程师读完后可以直接开始拆页面、建组件、重构导航 +2. 不需要再追问“这个页面回答什么问题” +3. 不需要再追问“这个状态到底显示在哪里” +4. 不需要再追问“哪些行为是 Logi 式参考，哪些是 AhaKey 特有补丁” + +如果后续阅读时发现某份文档仍需要大量口头补充，说明那份 spec 仍未完成。 diff --git a/platforms/macos/client/docs/redesign/logi-options-plus-reference-spec/01-reference-baseline.md b/platforms/macos/client/docs/redesign/logi-options-plus-reference-spec/01-reference-baseline.md new file mode 100644 index 0000000..491d0de --- /dev/null +++ b/platforms/macos/client/docs/redesign/logi-options-plus-reference-spec/01-reference-baseline.md @@ -0,0 +1,303 @@ +# Logi Options+ 参考基线 + +更新时间：2026-05-03 +状态：草稿 + +--- + +## 1. 文档定位 + +本文档用于记录这条专题线已经确认的**客观事实**、**参考边界**与**迁移原则**。 + +它回答的问题是： + +- 我们实际看到了什么，而不是猜到了什么 +- Logi Options+ 哪些部分值得作为 AhaKey 的高保真参考 +- 哪些部分虽然可见，但不应进入 AhaKey 的正式产品表达 + +这份文档是后续所有页面 spec 的前置约束。 + +--- + +## 2. 已确认的客观事实 + +### 2.1 本机样本 + +本机安装了 `logioptionsplus.app`，当前观察样本版本为： + +- App 名称：`logioptionsplus` +- Bundle Identifier：`com.logi.optionsplus` +- Version：`2.3.879545` + +### 2.2 技术栈确认 + +该样本不是原生 App，而是 **Electron + React** 桌面应用。 + +已确认的证据包括： + +- `Info.plist` 中存在 `ElectronAsarIntegrity` +- `NSPrincipalClass` 为 `AtomApplication` +- 包内存在 `Electron Framework.framework` +- `Contents/Resources` 下存在 `app.asar` + +结论： + +- 这是一个基于 Web 前端封装的桌面应用 +- 前台 UI 结构、样式和资源都具有较高可观察性 + +### 2.3 可见前端资产 + +`app.asar` 中已观察到： + +- `app.min.js` +- `app.min.css` +- 多个 chunk 文件 +- 大量 `assets/` 资源 +- 图片、SVG、字体、GIF 等静态素材 + +还观察到以下前端信号： + +- React +- React Router +- i18n 相关实现 +- CSS 资源完整存在 + +结论： + +- 该应用的前台壳层具有足够高的可见性 +- 我们可以从结构、术语、资源类型、页面家族、样式信号层面对其做高保真参考分析 + +### 2.4 页面家族信号 + +从前端包中的词汇、资源和文案信号可确认，它至少包含以下前台页面家族： + +- 设备总览 / Devices +- 设备详情 / Device +- Keys +- Settings +- Flow / Smart Actions 相关区域 +- Easy-Switch 相关区域 +- 自定义 / Customize 相关区域 + +对 AhaKey 最有参考价值的是： + +- 首页设备总览页 +- 设备详情工作区 +- 右上角操作区 +- Settings 层级 +- 应用上下文切换机制 + +### 2.5 当前截图证据 + +截至 2026-05-03，除 React / CSS / assets 逆向外，已观察到用户提供的运行截图，覆盖： + +- 首页无设备空态 +- 首页单设备 / 多设备总览态 +- 顶部添加设备、Smart Actions、账户、设置等右上角操作区 +- 添加设备的连接类型选择页 +- 设备详情页中的应用 / 平台切换器 +- 中央设备画布、热点 callout、右侧 inspector +- 深色 Settings 的通用设置、通知、反馈与支持页 +- Settings 左侧导航、当前项高亮、开关、下拉框、主题卡片 + +这些截图足以支撑下一轮 Web 原型的视觉方向，但仍不足以穷尽全部 hover、focus、错误、权限和同步状态。 + +### 2.6 主题 token 信号 + +已从 `app.min.css` 中确认 Logi Options+ 使用 `body.light` / `body.dark` 两套主题变量。 + +可确认的关键 token 包括： + +| 角色 | light | dark | +|------|-------|------| +| `--primary` | `#814efa` | `#00ead0` | +| `--primary-hover` | `#673ec8` | `#03dbc3` | +| `--primary-light` | `#d3c3fe` | `#99f7ec` | +| `--primary-background-1` | `#fff` | `#000` | +| `--primary-background-2` | `#000` | `#fff` | +| `--primary-background-4` | `#f5f5f5` | `#060606` | +| `--primary-background-5` | `#d9d9d9` | `#5c5c5c` | +| `--secondary-200` | `#f0f0f0` | `#333` | +| `--text` | `#222425` | `#fbfbfb` | +| `--text-shade-1` | `#888` | `#ccc` | +| `--text-shade-2` | `#fbfbfb` | `#191919` | +| `--checkbox-hover` | `#d1b7ff` | `#99f7ec` | +| `--host-tile-line-1` | `#d8d8d8` | `#666` | + +结论： + +- 明暗两色不是只能从截图估算，而是可以从 React / CSS 包中拿到可靠 token。 +- AhaKey 原型可以建立自己的语义 token，但应保留 Logi 的层级关系：浅色以白底 + 紫色强调为基准，深色以近黑底 + 青绿色强调为基准。 +- 正式产物不直接复制变量名或全量色值，只把它们作为内部参考依据。 + +--- + +## 3. 为什么它适合作为参考样本 + +Logi Options+ 对 AhaKey 来说，不是“业务相同”的参考，而是“**前台产品壳成熟度相近且可迁移**”的参考。 + +两者共同点： + +- 都是桌面端硬件配置软件 +- 都需要在“物理设备”与“软件配置”之间建立稳定心智 +- 都需要把设备身份信息、工作区、设置、状态反馈组织清楚 +- 都需要处理“多上下文映射同一硬件”的问题 + +因此，我们借鉴的不是 Logitech 的具体业务，而是它的： + +- 页面分层方式 +- 设备 hero 表达 +- 工作区组织方法 +- 设置层次感 +- 应用上下文切换语法 + +--- + +## 4. 可借鉴范围 + +### 4.1 允许高保真借鉴的部分 + +- 首页是设备选择器，而不是功能首页 +- 设备 hero 为中心的总览布局 +- 顶栏品牌区 / 操作区分层 +- 设备详情页的工作区组织方式 +- “应用上下文切换器”这类高识别度入口 +- 左侧导航与工作区的职责分离 +- Settings 层级与元操作收纳方式 +- 空态、未连接态、权限态的产品气质 +- 卡片、分隔、弱阴影、弱边框的视觉节奏 + +### 4.2 允许借鉴但必须 AhaKey 化改写的部分 + +- 应用上下文切换：映射为 `Claude Code / Cursor / Codex` +- 顶部快捷操作：映射为 AhaKey 的“编辑配置 / 完成配置 / 同步 / 后台服务” +- 设备详情页的分区：需要适配 AhaKey 的按键 / OLED / 灯条 / 拨杆 +- Settings 的分组：需要适配 Hook、权限、后台服务、BLE 诊断 +- 状态提示：需要覆盖 AhaKey 的草稿与控制权问题 + +### 4.3 不应借鉴或不应出现在正式产物中的部分 + +- Logitech 品牌、图标、文案 +- 原始截图直接作为正式产品资源 +- Flow 自动化完整能力 +- 多设备生态复杂度 +- Logitech 专属设备能力 +- 账户、订阅、云同步表达 +- 直接抽取的前端代码、资源、组件名称 + +--- + +## 5. AhaKey 与 Logi 的根本差异 + +如果不把差异讲清楚，后续 spec 很容易只是“看起来像 Logi”，但产品逻辑是错的。 + +### 5.1 Logi 更接近“即时配置” + +Logi Options+ 的很多配置行为默认是： + +- 用户进入设备详情 +- 修改设备上的配置 +- 修改几乎可视作即时生效 + +因此它不需要显式暴露“本地草稿 / 上次同步 / 设备真实状态”这三层概念。 + +### 5.2 AhaKey 有更强的状态分裂 + +AhaKey 当前存在三层必须被显式管理的状态： + +1. BLE 连接状态 +2. 蓝牙连接持有方（AhaKey Studio vs 后台守护进程） +3. 草稿与同步状态 + +这意味着： + +- AhaKey 不能只学 Logi 的皮 +- 必须在 Logi 式前台壳里，单独补上属于 AhaKey 的状态语言 + +### 5.3 AhaKey 有平台语义，不是应用语义 + +Logi 的“应用切换”是“这台设备在不同前台 App 下行为不同”。 + +AhaKey 的“平台切换”虽然可以借用同样的交互范式，但本质上是： + +- `Claude Code` +- `Cursor` +- `Codex` + +这些是用户明确知道的工作上下文，而不是系统检测到的泛应用列表。 + +因此： + +- AhaKey 需要一个更强的“平台”心智 +- 不能把它做成完全开放式的通用应用列表 + +--- + +## 6. 对正式产物的约束 + +### 6.1 资源层约束 + +允许把 Logi 的资源作为内部观察样本，但： + +- 不把 Logitech 图片、图标、品牌元素直接带入正式产品 +- 不把抽出的资源放进 AhaKey 代码仓库的正式资源链 + +内部参考图一律放在本专题目录的 `captures/` 下，且只做分析用途。 + +### 6.2 文案层约束 + +正式产品中： + +- 使用 AhaKey 自己的产品术语 +- 遵循 [00-glossary.md](../00-glossary.md) 的词汇规则 +- 不复用 Logitech 专有命名 + +### 6.3 架构层约束 + +本专题线只重构前台壳，不触碰： + +- BLE 协议层 +- Agent 通信协议 +- Voice Relay 核心机制 +- 固件命令定义 + +若某个体验问题只能通过协议改造解决，必须在 spec 中单独标记，不能暗含在 UI 重构任务里。 + +### 6.4 下一轮交付约束 + +下一轮优先做 Web 前端原型，并在需要时用 Electron 作为轻量演示壳。 + +该阶段不要求： + +- 完整桌面应用构建 +- 原生 macOS 交互落地 +- 真实 BLE / Agent / Voice 接入 +- 系统权限申请链路 + +该阶段要求： + +- 页面结构足够接近成熟桌面产品 +- 状态模型可以通过 mock 完整演示 +- 视觉、布局、交互节奏足够让合作者评审 +- 代码结构不阻碍后续 Electron 包装或 SwiftUI 迁移 + +--- + +## 7. 对后续 spec 的工作原则 + +后续所有页面 spec 默认遵守以下原则： + +1. **先学结构，再学皮肤。** + 先复刻信息架构、层级、交互节奏，再讨论视觉精修。 + +2. **先保证页面职责清晰，再保证页面像。** + 页面回答的问题必须清楚，否则再像 Logi 也只是空壳。 + +3. **AhaKey 特有复杂度必须显式写出来。** + 尤其是 BLE 占用、运行模式 / 配置模式、草稿同步。 + +4. **一切正式 UI 文案以 AhaKey 术语为准。** + 不把“Mode 0 / 1 / 2”“Agent 模式”这类混乱术语继续扩散。 + +5. **本专题是“高保真参考”，不是“直接复制计划”。** + 目标是借鉴成熟产品语言，而不是做 Logitech 外观替身。 diff --git a/platforms/macos/client/docs/redesign/logi-options-plus-reference-spec/02-information-architecture.md b/platforms/macos/client/docs/redesign/logi-options-plus-reference-spec/02-information-architecture.md new file mode 100644 index 0000000..0b901f3 --- /dev/null +++ b/platforms/macos/client/docs/redesign/logi-options-plus-reference-spec/02-information-architecture.md @@ -0,0 +1,360 @@ +# 前台信息架构 + +更新时间：2026-05-02 +状态：草稿 + +--- + +## 1. 文档定位 + +本文档定义 AhaKey Studio macOS 在 Logi Options+ 参考框架下的**前台信息架构**。 + +它回答的问题是： + +- 用户打开 App 后，先看到什么 +- 各页面分别回答什么问题 +- 页面之间如何进入、返回、切换 +- 哪些内容属于首页、工作区、次级页面、Settings + +这是所有页面 spec 的总骨架。 + +--- + +## 2. 信息架构总原则 + +### 2.1 首页不是功能入口 + +首页只回答一个问题： + +**“我要配置哪台设备？”** + +因此首页应以设备 hero 为中心，而不是以功能卡片、表格或状态仪表盘为中心。 + +### 2.2 设备工作区不是万能页面 + +设备工作区只回答一个问题： + +**“这台设备在当前平台上下文里，每个硬件部件应该做什么？”** + +因此： + +- 设备工作区负责硬件部件编辑 +- 语音、后台服务、权限、诊断等跨硬件内容，不塞进 inspector + +### 2.3 设置页只承载元操作 + +Settings 负责： + +- 影响全局行为 +- 不属于任何单页主任务 +- 需要系统级或应用级持久化的配置 + +不负责： + +- 单个硬件部件属性编辑 +- 平台上下文映射细节 +- 当前页面的即时配置 + +### 2.4 状态反馈主线与配置主线分离 + +AhaKey 有三条主线： + +1. 配置主线：改键、OLED、灯条、拨杆 +2. 状态反馈主线：后台服务、Hook、权限、运行状态 +3. 控制权主线：当前谁持有 BLE、能否编辑、是否需要同步 + +信息架构上必须让这三条线： + +- 可以相互感知 +- 但不互相污染页面职责 + +--- + +## 3. 页面层级 + +建议的前台层级如下： + +```text +AhaKey Studio +├── 首页 / Home +│ ├── 单设备 hero +│ ├── 多设备总览（未来） +│ ├── 添加设备 +│ ├── 快捷操作 +│ └── Settings 入口 +│ +├── 设备工作区 / Device Studio +│ ├── 按键 +│ ├── OLED +│ ├── 灯条 +│ ├── 拨杆 +│ ├── 平台切换（Claude / Cursor / Codex） +│ └── Inspector +│ +├── 次级页面 +│ ├── 后台服务 / Agent +│ ├── 语音 +│ ├── 设备信息 +│ └── 权限与诊断 +│ +└── Settings + ├── 通用 + ├── 设备 + ├── 后台服务与 Hook + ├── 语音 + ├── 通知 + └── 高级 +``` + +--- + +## 4. 页面职责定义 + +### 4.1 首页 / Home + +首页回答： + +- 我有哪些设备 +- 当前设备是否可用 +- 我是否需要先连接设备 +- 我接下来应该进入哪台设备的工作区 + +首页不回答： + +- 具体某个按键怎么配 +- 语音权限为什么失败 +- 后台服务日志细节 + +### 4.2 设备工作区 / Device Studio + +设备工作区回答： + +- 当前平台下，这台设备各硬件部件如何工作 +- 当前我选中了哪个部件 +- 我的修改是否已同步 +- 我现在是否处于可编辑状态 + +设备工作区不回答： + +- Hook 如何安装 +- 输入监控 / 辅助功能权限为什么没有 +- 后台服务的运行日志 + +### 4.3 后台服务页 / Agent + +后台服务页回答： + +- 后台守护进程是否安装、是否运行 +- Hook 是否已装到 Claude / Cursor / Codex +- 当前运行模式是否正常 +- 用户如何把键盘控制权交回后台服务 + +### 4.4 语音页 / Voice + +语音页回答： + +- 当前有哪些语音路由 +- 当前权限是否齐全 +- 各平台的语音行为如何映射 +- 如何重新检查或引导用户完成权限 + +### 4.5 设备信息页 / Device Info + +设备信息页回答： + +- 设备身份信息 +- 固件与 BLE 诊断 +- 当前连接状态与最近通信状态 +- 面向开发与售后的高级信息 + +### 4.6 Settings + +Settings 回答： + +- 默认连接策略 +- 开机自启、外观、语言等全局行为 +- Hook 与后台服务的全局偏好 +- 通知与高级设置 + +--- + +## 5. 顶层导航原则 + +### 5.1 主路径 + +主路径应始终保持清晰： + +1. 打开 App +2. 到达首页 +3. 选中设备 +4. 进入设备工作区 +5. 编辑并同步 +6. 返回运行状态 + +### 5.2 页面间跳转规则 + +#### 首页 -> 设备工作区 + +- 点击设备 hero / 设备卡片进入 +- 若当前只有一个已连接设备，也建议先看到首页，而不是直接跳过 + +#### 设备工作区 -> 首页 + +- 左上返回入口 +- 返回后保留设备列表上下文 + +#### 设备工作区 -> 后台服务 / 语音 / 设备信息 + +- 通过左侧导航进入 +- 这些页面属于当前设备上下文下的次级视图 +- 返回时应回到设备工作区的最近状态 + +#### 任意页面 -> Settings + +- 通过全局右上角 `⚙` 进入 +- Settings 默认是应用级层，不挂在某个 inspector 内 + +--- + +## 6. 建议的导航承载方式 + +### 6.1 App 级导航 + +App 顶层需要有独立导航状态，而不是让 `ContentView` 直接绑定 `AhaKeyStudioView`。 + +最低限度需要有： + +- 当前顶层页面 +- 当前设备 +- 当前次级页面（如后台服务 / 语音） + +### 6.2 设备工作区内导航 + +设备工作区内部再分两层： + +1. 页面级导航：按键 / OLED / 灯条 / 拨杆 / 后台服务 / 语音 / 设备信息 +2. 画布级选中态：当前选中的具体硬件部件 + +这两层不能混用。 + +示例： + +- “按键”是页面级导航 +- “Key 1”是画布级选中态 + +### 6.3 Settings 承载方式 + +Settings 保持 macOS 原生的独立体验，优先使用系统风格的 Settings scene 或独立设置窗口。 + +不建议： + +- 把 Settings 做成设备工作区里的一个 inspector 分页 +- 把 Settings 混成首页弹层里的长表单 + +--- + +## 7. 关键入口与返回路径 + +### 7.1 首页关键入口 + +- `+ 添加设备` +- `快捷操作` +- `⚙ 设置` +- 设备 hero / 设备卡片 + +### 7.2 设备工作区关键入口 + +- 顶部平台切换器 +- 左侧硬件导航 +- 左侧软件功能导航 +- `同步到键盘` +- `完成` + +### 7.3 次级页面关键入口 + +- 后台服务：从设备工作区左侧导航进入 +- 语音：从设备工作区左侧导航进入 +- 设备信息：从设备工作区左侧导航进入 +- Settings：从全局 `⚙` 进入 + +### 7.4 返回规则 + +- 页面级返回优先回到“上一个页面上下文” +- 不允许让用户在次级页面返回时丢失当前设备上下文 +- 不允许通过关闭 sheet 才能回到主路径 + +--- + +## 8. 空态、加载态、异常态在架构中的位置 + +### 8.1 首页层 + +首页需要承载： + +- 无设备空态 +- 扫描中 +- 扫描失败 +- 已连接 / 未连接设备列表 + +### 8.2 设备工作区层 + +设备工作区需要承载： + +- 配置模式 / 运行模式的不可编辑差异 +- 未同步改动提示 +- 同步中 / 同步失败 / 同步成功 +- 局部能力开发中占位 + +### 8.3 次级页面层 + +后台服务页 / 语音页 / 设备信息页需要各自承载： + +- 权限缺失态 +- 后台服务未安装态 +- Hook 未安装态 +- 诊断信息不可用态 + +### 8.4 全局层 + +全局层只承载： + +- 严重错误 +- 需要阻塞用户继续操作的确认框 +- 系统级操作反馈 + +不承载所有普通提示。 + +--- + +## 9. 与现有代码约束的映射 + +当前代码中已经存在： + +- `AhaKeyBLEManager` +- `AgentManager` +- `VoiceRelayService` +- `AhaKeyStudioView` + +信息架构层默认约束为： + +1. 保留这些运行时单例与状态源 +2. 新建页面壳与导航层，不改它们的核心职责 +3. 让当前集中在 `AhaKeyStudioView` 内的职责拆分到多个页面和组件 + +这意味着： + +- 信息架构重构优先是**前台壳层重构** +- 不是协议层或服务层重构 + +--- + +## 10. 验收标准 + +当有人只看这份文档时，应能明确回答： + +- 首页、设备工作区、次级页面、Settings 各自回答什么问题 +- 用户从打开 App 到完成配置的主路径是什么 +- 语音和后台服务为什么不应继续留在 inspector 里 +- AhaKey 的三条主线在页面层级里分别落在哪里 + +如果这些问题还需要口头解释，说明信息架构仍不完整。 diff --git a/platforms/macos/client/docs/redesign/logi-options-plus-reference-spec/03-home-overview-spec.md b/platforms/macos/client/docs/redesign/logi-options-plus-reference-spec/03-home-overview-spec.md new file mode 100644 index 0000000..7e64d00 --- /dev/null +++ b/platforms/macos/client/docs/redesign/logi-options-plus-reference-spec/03-home-overview-spec.md @@ -0,0 +1,290 @@ +# 首页设备总览页 Spec + +更新时间：2026-05-02 +状态：草稿 + +--- + +## 1. 页面定位 + +首页回答的问题是： + +**“我有哪些 AhaKey 设备，我要进入哪一台设备的工作区？”** + +这是一个设备选择器，不是功能入口页，不是监控台，也不是状态日志页。 + +--- + +## 2. 目标用户问题 + +用户打开首页时，最想知道的是： + +- 我的设备有没有被识别到 +- 当前是否已连接 +- 哪台设备可配置 +- 我接下来点哪里进入编辑 +- 如果现在还没有设备，下一步该怎么做 + +--- + +## 3. 页面骨架 + +```text +┌──────────────────────────────────────────────────────────────────┐ +│ [AhaKey Studio] [+ 添加设备] [⚡] [⚙] │ +├──────────────────────────────────────────────────────────────────┤ +│ │ +│ 设备 Hero / 设备卡片区域 │ +│ │ +│ ┌────────────────────────────────────────────┐ │ +│ │ │ │ +│ │ 设备 1:1 渲染 / hero 视图 │ │ +│ │ │ │ +│ └────────────────────────────────────────────┘ │ +│ vibe code 154F │ +│ 已连接 · 68% · 运行中 │ +│ │ +│ [进入设备工作区] │ +│ │ +└──────────────────────────────────────────────────────────────────┘ +``` + +未来多设备时改为横向卡片或分页 hero，但首版仍以单设备 hero 为主。 + +--- + +## 4. 页面模块 + +### 4.1 顶栏 + +顶栏采用三段结构： + +- 左侧：品牌区 +- 中间：留白 +- 右侧：操作区 + +#### 左侧品牌区 + +- 文案：`AhaKey Studio` +- 不显示复杂设备状态 +- 不显示工程术语 + +#### 右侧操作区 + +- `+ 添加设备` +- `快捷操作` +- `⚙ 设置` + +可选补充： + +- 如果后续需要全局状态提示，可在最右侧加小型状态图标，但不让它成为主焦点 + +### 4.2 设备 hero 区 + +设备 hero 是首页视觉主角，应占首屏最多注意力。 + +它包含： + +- 设备 1:1 渲染 +- 设备名 +- 电量 +- 连接状态 +- 当前运行状态（运行中 / 配置中） +- 进入设备工作区的明确点击路径 + +### 4.3 次级说明区 + +设备 hero 下方可选承载轻量说明，例如： + +- 上次同步时间 +- 当前平台映射摘要 +- 当前是否有未完成的本地草稿 + +但这些信息只能作为辅助信息，不能抢设备 hero 主体。 + +--- + +## 5. 核心状态 + +### 5.1 无设备 + +页面显示： + +- 空状态插图或键盘轮廓占位 +- 文案：“还没有连接的设备” +- 主按钮：`+ 添加设备` + +不显示： + +- 大量诊断文字 +- 系统术语 + +### 5.2 扫描中 + +页面显示： + +- hero 区保持布局稳定 +- 中央显示扫描中反馈 +- 顶部 `+ 添加设备` 进入 loading 态 + +用户应知道： + +- App 正在做事 +- 不需要再点很多次 + +### 5.3 单设备已连接 + +页面显示： + +- 设备 hero +- 已连接状态 +- 电量 +- 当前运行模式摘要 +- CTA：进入设备工作区 + +这是首版的默认强路径。 + +### 5.4 单设备未连接 + +页面显示： + +- 同一份设备 hero，但状态弱化 +- 未连接提示 +- 明确按钮：`连接设备` + +不直接把用户扔进设备工作区。 + +### 5.5 多设备（未来） + +页面显示： + +- 多个 hero 卡片横向排列 +- 每张卡片显示设备名、状态、电量、进入按钮 + +但首版 spec 中只需预留结构，不要求全部实现。 + +--- + +## 6. 主要交互 + +### 6.1 进入设备工作区 + +点击以下任意区域都可以进入： + +- hero 主体 +- 明确 CTA 按钮 +- 设备名称区域（可选） + +点击后进入当前设备上下文下的设备工作区。 + +### 6.2 添加设备 + +点击 `+ 添加设备` 后： + +- 打开扫描 / 配对 sheet +- 不离开首页主上下文 + +理由： + +- 这是一个新增动作，不应打断首页结构 + +### 6.3 快捷操作 + +点击 `⚡ 快捷操作` 后： + +- 打开轻量 popover +- 提供少量高频控制 + +建议内容： + +- 编辑配置 +- 完成配置 +- 同步所有改动 +- 重启后台服务 + +不把快捷操作做成独立大页面。 + +### 6.4 Settings + +点击 `⚙` 后： + +- 进入独立 Settings 层 +- 返回时应回到首页原上下文 + +--- + +## 7. 与 AhaKey 现有约束的映射 + +### 7.1 BLE 状态 + +首页需要感知： + +- `AhaKeyBLEManager.isConnected` +- `isScanning` +- `batteryLevel` +- `deviceName` + +但首页只显示用户能理解的结果，不暴露 BLE 术语。 + +### 7.2 控制权状态 + +首页需要感知： + +- 当前是运行中还是配置中 + +默认映射： + +- `AhaKey Studio` 持有 BLE -> `配置中` +- 后台守护进程持有 BLE -> `运行中` + +首页不显示“谁持有 BLE”，只显示可理解结果。 + +### 7.3 草稿状态 + +首页可显示轻量提醒： + +- 有未同步改动 + +但不能把首页变成编辑页。 + +--- + +## 8. 非目标项 + +本页不负责： + +- 编辑单个按键 +- 显示完整的权限引导流程 +- 展示后台服务详细日志 +- 展示 BLE 通信明细 +- 承担设置表单 + +--- + +## 9. 验收标准 + +### 9.1 结构验收 + +- 用户打开 App 后先进入首页，而不是直接进入工作区 +- 首页的视觉主角是设备，不是功能列表 +- 顶栏操作区简洁，设备 hero 位置明确 + +### 9.2 心智验收 + +用户应在 5 秒内理解： + +- 这是 AhaKey Studio +- 中间这就是我要配置的设备 +- 点它可以进入编辑 +- 右上角分别是添加设备、快捷操作、设置 + +### 9.3 实现验收 + +另一个工程师仅靠这份 spec，即可开始定义： + +- `HomeView` +- `DeviceHeroCard` +- `QuickActionsPopover` +- `DeviceScannerSheet` + +而不需要再问“首页到底是不是仪表盘”。 diff --git a/platforms/macos/client/docs/redesign/logi-options-plus-reference-spec/04-device-studio-spec.md b/platforms/macos/client/docs/redesign/logi-options-plus-reference-spec/04-device-studio-spec.md new file mode 100644 index 0000000..37e4281 --- /dev/null +++ b/platforms/macos/client/docs/redesign/logi-options-plus-reference-spec/04-device-studio-spec.md @@ -0,0 +1,459 @@ +# 设备工作区 Spec + +更新时间：2026-05-06 +状态：草稿 + +--- + +## 1. 页面定位 + +设备工作区回答的问题是： + +**“这台 AhaKey 设备在当前平台上下文里，每个硬件部件应该做什么？”** + +它是 AhaKey Studio 的核心生产页面。 + +--- + +## 2. 目标用户问题 + +用户进入设备工作区后，最想知道的是： + +- 我现在在配置哪台设备 +- 我现在在配置哪个平台上下文 +- 我点哪里可以改键、改 OLED、改拨杆 +- 我现在是不是可编辑状态 +- 我改了之后有没有同步到键盘 + +--- + +## 3. 页面骨架 + +```text +┌──────────────────────────────────────────────────────────────────────────┐ +│ ← AhaKey Studio [logo] [logo] [logo] │ +│ vibe code 154F │ +├──────────────┬───────────────────────────────────────┬─────────────────┤ +│ 左侧导航 │ 中央工作区 │ 右侧 Inspector │ +│ │ │ │ +│ ⌨ 按键 │ 1:1 键盘画布 / OLED / 灯条 / 拨杆 │ 当前选中部件属性 │ +│ 🖥 OLED │ │ │ +│ 💡 灯条 │ │ │ +│ 🔀 拨杆 │ │ │ +│ │ │ │ +│ ─────────── │ │ │ +│ 🤖 后台服务 │ │ │ +│ 🎙 语音 │ │ │ +│ ℹ 设备信息 │ │ │ +└──────────────┴───────────────────────────────────────┴─────────────────┘ +``` + +--- + +## 4. 页面 / 模块定位 + +### 4.1 顶部 + +顶部负责承载： + +- 返回首页 +- 当前设备身份 +- 平台切换器 + +不负责： + +- 显示一大堆状态 chip +- 语音权限、后台服务日志等复杂信息 +- 全局设置入口或主页动作组 + +### 4.2 左侧导航 + +左侧导航只做**页面 / 工作区视图切换**。 + +分两组： + +1. 硬件部件组 +2. 软件功能组 + +默认展开态显示 `icon + label`。 + +当右侧 Inspector 在桌面宽度下打开时，左侧导航自动折叠成 `icon-only rail`，只保留： + +- icon +- active tint +- hover / tooltip 名称 + +左侧导航不承载： + +- 二级部件目录 +- 教学说明文字 +- 当前工作流解释 +- 状态摘要块 + +### 4.3 中央工作区 + +中央工作区负责： + +- 展示当前导航项对应的主要内容 +- 在“硬件部件组”下展示 1:1 键盘工作画布 +- 在“后台服务 / 语音 / 设备信息”下替换成对应视图 + +### 4.4 右侧 Inspector + +Inspector 只在“硬件部件编辑上下文”里出现。 + +它负责： + +- 显示当前选中部件的属性 +- 修改该部件在当前平台下的配置 +- 提示脏状态 / 同步相关状态 + +它不负责： + +- 后台服务全页配置 +- 权限全页引导 +- 日志或诊断工具主视图 + +--- + +## 5. 核心状态 + +本页最重要的不是“默认长什么样”，而是**不同状态下的工作区语义**。 + +### 5.1 平台上下文 + +平台切换器在可见层使用 symbol-only logo。 + +- 用户看到的是右上角 3 个平台 logo +- 完整平台名只保留在 tooltip / accessibility label +- 不对用户暴露 `Mode 0 / 1 / 2` + +内部仍可映射： + +- workspace A -> `Mode 0` +- workspace B -> `Mode 1` +- workspace C -> `Mode 2` + +### 5.2 页面级导航状态 + +页面级导航项包括： + +- 按键 +- OLED +- 灯条 +- 拨杆 +- 后台服务 +- 语音 +- 设备信息 + +导航切换时： + +- 保留当前设备上下文 +- 保留当前平台上下文 +- 对硬件编辑页可记住最近一次选中部件 + +### 5.3 选中态 + +在硬件编辑页里，需要有明确的部件选中态： + +- `Key 1` +- `Key 2` +- `Key 3` +- `Key 4` +- `OLED` +- `灯条` +- `拨杆` + +选中态由以下入口共同驱动： + +- 点击画布热区 +- 点击左侧硬件导航 +- Inspector 内的相关切换入口 + +### 5.4 配置模式 / 运行模式 + +本页必须显式区分： + +- `配置中`：本 App 持有 BLE，可编辑、可同步 +- `运行中`：后台守护进程持有 BLE，不可直接写设备 + +这不是辅助状态，而是工作区能否工作的根条件。 + +### 5.5 草稿 / 已同步 + +本页必须显式区分： + +- 无未同步改动 +- 有未同步改动 +- 正在同步 +- 同步失败 + +这是 AhaKey 与 Logi 最大的差异之一，必须成为页面主状态语言的一部分。 + +--- + +## 6. 平台切换器 + +### 6.1 定位 + +平台切换器是本页最重要的高层上下文入口。 + +它表达的不是“一个小过滤器”，而是： + +**“同一台硬件，在不同 AI 平台下的行为映射”** + +### 6.2 交互形式 + +形式参考 Logi 的应用图标切换器，但 AhaKey 采用 logo-only。 + +要求： + +- 空间比传统 segmented control 更轻 +- 视觉上像高层上下文切换，而不是局部表单控件 +- 支持扩展更多平台 +- 不在正文、Inspector、系统页副标题里重复平台品牌名 + +### 6.3 切换行为 + +切换平台时： + +- 保持当前页面级导航项不变 +- 在硬件编辑页里，尽量保持当前选中部件不变 +- Inspector 内容切换为对应平台下的配置 + +--- + +## 7. 左侧导航 + +左侧导航只保留一级导航项，不再显示 Key 1 / Key 2 / Key 3 / Key 4 的左侧二级目录。 + +硬件部件的精确选择由设备热区承担，Inspector 打开时左栏折叠，避免与中央对象争夺注意力。 + +### 7.1 硬件部件组 + +#### 按键 + +- 默认显示键盘画布 +- Key 1 默认选中 + +#### OLED + +- 进入 OLED 编辑上下文 +- 中央仍可显示设备画布，但强调 OLED 区域 + +#### 灯条 + +- 进入灯条编辑上下文 +- 若当前版本只支持有限编辑或只读预览，也要在本页清楚说明 + +#### 拨杆 + +- 进入拨杆配置上下文 +- 解释自动批准 / 手动批准映射 + +### 7.2 软件功能组 + +#### 后台服务 + +- 中央工作区切换为后台服务页 +- Inspector 隐藏 + +#### 语音 + +- 中央工作区切换为语音页 +- Inspector 隐藏 + +#### 设备信息 + +- 中央工作区切换为设备信息页 +- Inspector 隐藏 + +### 7.3 底部状态组 + +仅显示，只读： + +- 运行中 / 配置中 +- 已连接 / 未连接 +- 电量 +- 当前同步概况 + +不把它们做成导航项。 + +--- + +## 8. 中央工作区 + +### 8.1 默认着陆点 + +默认着陆点建议为： + +- 进入工作区时默认落在 `按键` +- 默认平台为当前硬件所处平台 +- 默认选中 `Key 1` + +这样最容易让用户立刻开始配置主价值链。 + +### 8.2 硬件编辑态 + +在 `按键 / OLED / 灯条 / 拨杆` 导航下： + +- 中央工作区显示 1:1 设备工作画布 +- 当前焦点部件高亮 +- 其它部件可见但退后 + +### 8.3 软件功能页态 + +在 `后台服务 / 语音 / 设备信息` 导航下： + +- 中央工作区切换为完整的单页内容 +- 不再强行保留右侧 inspector + +### 8.4 同步状态表达 + +中央工作区顶部或底部需要一个稳定位置表达： + +- 有未同步改动 +- 正在同步 +- 同步成功 +- 同步失败 + +这不能只藏在某个按钮文案里。 + +--- + +## 9. Inspector + +### 9.1 骨架 + +Inspector 统一骨架： + +1. 当前平台摘要 +2. 当前部件标题 +3. 该部件主属性 +4. 预览 / 说明 +5. 高级项 +6. 同步提示 + +### 9.2 Key 1 示例 + +`Key 1` Inspector 重点包括： + +- 当前平台 +- 语音行为 +- 触发键映射 +- 当前语音路由摘要 +- 权限 / 可用性提示（只做摘要，详细内容去语音页） + +### 9.3 OLED 示例 + +`OLED` Inspector 重点包括： + +- 当前显示模式 +- 当前素材摘要 +- 预览入口 +- 上传 / 替换动作 + +### 9.4 灯条示例 + +`灯条` Inspector 重点包括： + +- 状态映射摘要 +- 当前预览 +- 当前阶段支持范围 + +### 9.5 拨杆示例 + +`拨杆` Inspector 重点包括： + +- 自动批准 / 手动批准语义 +- 当前平台下拨杆对应行为 +- 与运行中状态的关系说明 + +### 9.6 不该放进 Inspector 的内容 + +- Hook 安装向导 +- 详细权限流程 +- BLE 日志 +- 后台服务生命周期控制 + +这些内容应跳去对应单页。 + +--- + +## 10. 与 AhaKey 现有约束的映射 + +### 10.1 当前已有运行时 + +本页默认依赖： + +- `AhaKeyBLEManager` +- `AgentManager` +- `VoiceRelayService` + +### 10.2 当前代码现实 + +当前 `AhaKeyStudioView` 已经同时承载： + +- 顶部工具栏 +- 画布 +- Inspector +- 语音权限弹层 +- 设备信息 sheet +- 同步逻辑 + +本 spec 的目标是把这些职责拆开，而不是继续让单视图膨胀。 + +### 10.3 需要保留的核心事实 + +- 平台最终仍映射到固件 `Mode` +- Voice Relay 仍与 `AhaKeyModeSlot` 绑定 +- BLE 连接抑制逻辑仍由 `AgentManager` 与 `AhaKeyBLEManager` 协同 + +因此重构的重点是： + +- 改页面结构 +- 改组件边界 +- 改用户可见心智 + +不是重写服务逻辑。 + +--- + +## 11. 非目标项 + +本页不负责： + +- 定义所有 Settings 表单细项 +- 详细描述权限申请 API +- 修改 BLE 指令协议 +- 重做 Voice Relay 机制 + +--- + +## 12. 验收标准 + +### 12.1 用户视角 + +用户进入设备工作区后，应能迅速理解： + +- 我当前在配置哪台设备 +- 我当前在配置哪个平台 +- 左边切的是“页面 / 功能” +- 中间是设备主工作区 +- 右边是当前部件属性 +- 顶部或固定位置能看到是否需要同步 + +### 12.2 工程视角 + +另一个工程师读完后，应能直接拆出： + +- `StudioView` +- `PlatformSwitcher` +- `StudioSidebar` +- `StudioCanvasHost` +- `StudioInspector` +- `AgentPage` +- `VoicePage` +- `DeviceInfoPage` + +并明确哪些是页面级切换，哪些是部件选中态。 diff --git a/platforms/macos/client/docs/redesign/logi-options-plus-reference-spec/05-secondary-pages-spec.md b/platforms/macos/client/docs/redesign/logi-options-plus-reference-spec/05-secondary-pages-spec.md new file mode 100644 index 0000000..c99666c --- /dev/null +++ b/platforms/macos/client/docs/redesign/logi-options-plus-reference-spec/05-secondary-pages-spec.md @@ -0,0 +1,374 @@ +# 次级页面 Spec + +更新时间：2026-05-02 +状态：草稿 + +--- + +## 1. 文档定位 + +本文档定义设备工作区之外、但仍属于 AhaKey Studio 主前台壳的次级页面 spec。 + +包括： + +- 后台服务页 +- 语音页 +- Settings +- 设备信息页 +- 权限 / 异常 / 辅助弹层规则 + +这些页面的共同目标是： + +- 把跨硬件功能从 inspector 中拆出来 +- 让页面职责更稳定 +- 让用户在复杂状态下仍知道自己在处理哪一类问题 + +--- + +## 2. 总体原则 + +### 2.1 次级页面回答的是“系统能力问题” + +这些页面共同回答的不是“这个键该怎么配”，而是： + +- 系统是否准备好了 +- 后台服务是否正常 +- 权限是否齐全 +- 设备状态是否可信 + +### 2.2 次级页面需要完整画布，而不是塞进小 panel + +因此： + +- 进入次级页面时，中央工作区切换为整页 +- 右侧 inspector 默认隐藏 + +### 2.3 这些页面应降低认知负担 + +它们不该长得像工程调试工具。 + +即使包含诊断信息，也要： + +- 先给结论 +- 再给操作 +- 最后才给细节 + +--- + +## 3. 后台服务页 / Agent + +### 3.1 页面回答的问题 + +- 后台守护进程是否安装 +- 是否正在运行 +- 当前 Hook 覆盖到哪些 AI 工具 +- 当前设备是否处于运行中 +- 如何切回由后台服务持有键盘控制权 + +### 3.2 页面骨架 + +```text +┌─────────────────────────────────────────────────────┐ +│ 后台服务 │ +├─────────────────────────────────────────────────────┤ +│ 状态总览卡 │ +│ - 已安装 / 未安装 │ +│ - 运行中 / 未运行 │ +│ - 已连接键盘 / 未连接键盘 │ +│ │ +│ Hook 覆盖区 │ +│ - Claude Code │ +│ - Cursor │ +│ - Codex │ +│ │ +│ 控制权区 │ +│ - 当前为运行中 / 配置中 │ +│ - 切回运行中 / 进入配置中 │ +│ │ +│ 高级 / 诊断折叠区 │ +└─────────────────────────────────────────────────────┘ +``` + +### 3.3 核心状态 + +- 未安装 +- 已安装但未运行 +- 已运行但未连接键盘 +- 已运行且已连接键盘 +- Hook 不完整 + +### 3.4 主要交互 + +- 安装后台服务 +- 启用 / 停用后台服务 +- 重新检查状态 +- 安装 / 修复 Hook +- 切换到运行中 / 配置中 + +### 3.5 非目标项 + +- 不在这里编辑单个键位 +- 不在这里展示完整 BLE 通信日志默认态 + +--- + +## 4. 语音页 / Voice + +### 4.1 页面回答的问题 + +- 当前语音路由是否有效 +- 系统权限是否齐全 +- 各平台下的语音行为如何映射 +- 用户下一步该去系统设置还是该回到工作区 + +### 4.2 页面骨架 + +```text +┌─────────────────────────────────────────────────────┐ +│ 语音 │ +├─────────────────────────────────────────────────────┤ +│ 权限总览卡 │ +│ - 输入监控 │ +│ - 辅助功能 │ +│ - 麦克风 │ +│ - 语音识别 │ +│ │ +│ 平台语音映射区 │ +│ - Claude Code │ +│ - Cursor │ +│ - Codex │ +│ │ +│ 当前路由摘要 │ +│ │ +│ 操作区 │ +│ - 重新检查权限 │ +│ - 打开系统设置 │ +│ - 重启并重新打开 │ +└─────────────────────────────────────────────────────┘ +``` + +### 4.3 核心状态 + +- 权限全部齐全 +- 缺少输入监控 +- 缺少辅助功能 +- 缺少麦克风 / 语音识别 +- 路由为空 +- 路由存在但依赖某外部 App + +### 4.4 主要交互 + +- 重新检查权限 +- 打开系统权限设置 +- 引导重启 App +- 查看当前平台的语音映射 + +### 4.5 设计要求 + +- 先说清权限状态 +- 再给下一步动作 +- 最后才解释底层原理 + +--- + +## 5. 设备信息页 / Device Info + +### 5.1 页面回答的问题 + +- 当前设备是谁 +- 固件是什么版本 +- 当前 BLE 状态是否正常 +- 我是否需要进入诊断模式 + +### 5.2 页面骨架 + +```text +┌─────────────────────────────────────────────────────┐ +│ 设备信息 │ +├─────────────────────────────────────────────────────┤ +│ 身份卡 │ +│ - 设备名 │ +│ - 型号 │ +│ - 固件版本 │ +│ - UUID │ +│ │ +│ 连接状态卡 │ +│ - 已连接 / 未连接 │ +│ - 电量 / 信号 │ +│ - 当前平台 / 当前运行状态 │ +│ │ +│ 高级诊断区（折叠） │ +│ - BLE 状态 │ +│ - 最近日志 │ +│ - 导出诊断 │ +└─────────────────────────────────────────────────────┘ +``` + +### 5.3 核心状态 + +- 已连接且信息完整 +- 已连接但部分信息未读到 +- 未连接 +- 诊断模式开启 + +### 5.4 主要交互 + +- 重新读取设备信息 +- 导出诊断 +- 进入高级诊断展开态 + +### 5.5 设计要求 + +- 默认态不应工程化 +- 高级诊断默认折叠 + +--- + +## 6. Settings + +### 6.1 页面回答的问题 + +- 影响整个应用的偏好是什么 +- 哪些行为是默认策略 +- 哪些是与单个页面无关的元设置 + +### 6.2 建议层级 + +- 通用 +- 设备 +- 后台服务与 Hook +- 语音 +- 通知 +- 高级 + +### 6.3 Settings 承载方式 + +优先采用： + +- macOS 原生 Settings scene 或独立设置窗口 + +不建议： + +- 大 sheet +- 从首页弹一个超长浮层 + +### 6.4 各组示意 + +#### 通用 + +- 登录时启动 +- 外观 +- 语言（未来） + +#### 设备 + +- 默认连接策略 +- 断连后的行为 +- 固件更新入口（未来） + +#### 后台服务与 Hook + +- Hook 安装状态 +- 自动启动后台服务 +- 默认运行策略 + +#### 语音 + +- 默认语音行为 +- 默认平台路由偏好 + +#### 通知 + +- 连接通知 +- 同步完成通知 +- 后台服务异常通知 + +#### 高级 + +- 诊断模式 +- 导出诊断 +- 重置配置 +- 关于 + +--- + +## 7. 弹层 / sheet / dialog 规则 + +### 7.1 Popover + +适合： + +- 快捷操作 +- 轻量帮助说明 +- 局部二级选择 + +不适合： + +- 大表单 +- 权限引导主流程 + +### 7.2 Sheet + +适合： + +- 添加设备 +- 大型媒体预览 +- 一次性向导 + +### 7.3 Dialog / Alert + +适合： + +- 切换运行状态的确认 +- 未同步改动离开确认 +- 需要重启 App 的确认 + +### 7.4 独立页面 + +以下内容优先用独立页面而非弹层： + +- 后台服务 +- 语音 +- 设备信息 +- Settings + +--- + +## 8. 与现有约束的映射 + +### 8.1 后台服务页 + +应直接复用 `AgentManager` 的状态，而不是再造一个平行状态源。 + +### 8.2 语音页 + +应直接复用： + +- `VoiceRelayService` +- `NativeSpeechTranscriptionService` + +### 8.3 设备信息页 + +应直接复用 `AhaKeyBLEManager` 已发布状态与诊断信息。 + +### 8.4 当前实现存在的问题 + +当前部分内容分散在： + +- 顶栏 +- inspector +- sheet +- alert + +本 spec 的目标是把这些零散入口收敛成稳定页面。 + +--- + +## 9. 验收标准 + +读完本文后，另一个工程师应能直接明确： + +- 哪些内容属于独立页面 +- 哪些页面需要隐藏 inspector +- 哪些动作该用 popover / sheet / alert +- 为什么后台服务和语音不该继续塞在 `AhaKeyStudioView` 的右侧属性面板里 diff --git a/platforms/macos/client/docs/redesign/logi-options-plus-reference-spec/06-state-machine-spec.md b/platforms/macos/client/docs/redesign/logi-options-plus-reference-spec/06-state-machine-spec.md new file mode 100644 index 0000000..bc44d96 --- /dev/null +++ b/platforms/macos/client/docs/redesign/logi-options-plus-reference-spec/06-state-machine-spec.md @@ -0,0 +1,403 @@ +# UX 状态机 Spec + +更新时间：2026-05-02 +状态：草稿 + +--- + +## 1. 文档定位 + +本文档定义 AhaKey Studio 在高保真重构后必须遵守的**三层状态机**。 + +这是整套专题文档里最关键的一份，因为： + +- Logi Options+ 没有这套复杂度 +- AhaKey 的大量 UX 风险都来自状态层表达不清 + +本文档回答的问题是： + +- 用户当前到底处于什么工作状态 +- 哪些状态是互斥的，哪些是并行的 +- 每个状态下允许哪些操作 +- 状态应该显示在页面的什么位置 + +--- + +## 2. 为什么需要单独写状态机 + +如果只看页面结构，很容易把 AhaKey 误做成“像 Logi 的配置软件”。 + +但 AhaKey 与 Logi 的根本差异在于： + +- 不是所有时候都能编辑 +- 不是所有改动都会即时生效 +- App 并不总是持有设备连接 + +因此必须把以下三层状态拆开： + +1. BLE 连接状态 +2. 键盘控制权状态 +3. 草稿 / 同步状态 + +任何一个页面，只要忽略其中一层，用户就会对“我现在到底能不能改、改了会不会生效”产生误解。 + +--- + +## 3. 三层状态定义 + +### 3.1 第一层：BLE 连接状态 + +回答： + +**“App 当前是否与设备建立了可用连接？”** + +状态集合： + +- 未连接 +- 扫描中 +- 连接中 +- 已连接 +- 连接异常 + +用户可见位置： + +- 首页设备 hero +- 设备工作区左下状态区 +- 设备信息页 + +### 3.2 第二层：控制权状态 + +回答： + +**“当前由谁持有与键盘的可写控制权？”** + +内部真实状态： + +- `AhaKey Studio` 持有 BLE +- `ahakeyconfig-agent` 持有 BLE + +用户可见文案映射： + +- `配置中` +- `运行中` + +用户可见位置： + +- 首页 hero 状态摘要 +- 设备工作区左下状态区 +- 工作区顶部主状态提示 +- 后台服务页 + +### 3.3 第三层：草稿 / 同步状态 + +回答： + +**“我正在看的配置，是本地草稿、已同步快照，还是设备真实状态？”** + +用户可见的主要状态： + +- 无未同步改动 +- 有未同步改动 +- 同步中 +- 同步成功 +- 同步失败 +- 设备真实状态未知 + +用户可见位置： + +- 设备工作区顶部或底部稳定提示区 +- Inspector 辅助提示 +- 首页轻量摘要（可选） + +--- + +## 4. 三层状态之间的关系 + +三层状态不是一条线性状态机，而是三条并行状态线。 + +可以组合出如下典型工作态： + +| BLE | 控制权 | 草稿/同步 | 用户语义 | +|----|----|----|----| +| 已连接 | 配置中 | 无未同步改动 | 可以继续编辑，也可以结束 | +| 已连接 | 配置中 | 有未同步改动 | 正在编辑，尚未写入键盘 | +| 已连接 | 配置中 | 同步中 | 正在把草稿写入键盘 | +| 已连接 | 配置中 | 同步失败 | 用户需要重试或处理异常 | +| 未连接 | 运行中 | 无未同步改动 | 键盘由后台服务运行，App 当前不可写 | +| 未连接 | 运行中 | 有未同步改动 | 本地仍有草稿，但当前不能直接写设备 | +| 连接异常 | 配置中 | 有未同步改动 | 高风险态，需优先保护草稿 | + +结论： + +- “是否已连接”并不能替代“是否可编辑” +- “是否可编辑”也不能替代“是否需要同步” + +--- + +## 5. 状态优先级 + +当多个状态同时成立时，界面必须有优先级。 + +建议优先级如下： + +1. 严重阻断态 +2. 控制权冲突态 +3. 未同步改动态 +4. 一般信息态 + +### 5.1 严重阻断态 + +例如： + +- 连接异常 +- 同步失败 +- 关键权限缺失导致功能完全不可用 + +表现要求： + +- 页面必须显著提示 +- 用户无需找半天才知道为什么不能继续 + +### 5.2 控制权冲突态 + +例如： + +- 当前处于运行中，用户进入工作区但不能直接写设备 + +表现要求： + +- 工作区需要显式提示“当前不可写，需要进入配置中” +- 不能让用户误以为自己正在改真实设备 + +### 5.3 未同步改动态 + +例如： + +- 草稿已改但未同步 + +表现要求： + +- 必须持续可见 +- 但不应比阻断态更抢眼 + +### 5.4 一般信息态 + +例如： + +- 电量 +- 最近同步时间 +- 当前平台名 + +这些信息可以低权重表达。 + +--- + +## 6. 关键用户流状态机 + +### 6.1 从首页进入设备工作区 + +#### 情况 A：当前为运行中 + +用户进入设备工作区后应看到： + +- 当前设备上下文 +- 当前平台 +- 页面可浏览 +- 但需要一个清楚的主提示：当前是运行中，若要写入配置，需要进入配置中 + +允许操作： + +- 查看配置 +- 切换平台 +- 浏览后台服务 / 语音 / 设备信息 + +不允许误导用户： + +- 以为点了就已经写到设备 + +#### 情况 B：当前为配置中 + +用户进入设备工作区后应看到： + +- 可直接编辑 +- 当前同步状态 +- 明确的同步和完成操作 + +### 6.2 切换到配置中 + +触发后状态变化： + +1. 后台守护进程释放控制权 +2. App 抢占 BLE +3. BLE 进入连接中 +4. 成功后进入已连接 + 配置中 +5. 工作区从“浏览 / 半可用”切到“可编辑” + +若失败： + +- 停留在原状态 +- 给出清楚失败提示 + +### 6.3 编辑并产生草稿 + +用户修改配置后： + +- 进入“有未同步改动” +- 当前修改仅写入草稿 +- 页面必须持续显示未同步状态 + +### 6.4 同步到键盘 + +点击同步后： + +1. 进入同步中 +2. 禁用部分冲突操作 +3. 成功后进入无未同步改动 +4. 失败后进入同步失败 + +### 6.5 完成配置 + +点击完成时要区分： + +#### 无未同步改动 + +- 直接释放 BLE +- 回到运行中 + +#### 有未同步改动 + +需要显式二选一： + +- 同步并完成 +- 放弃本次写入，回到运行中，但本地草稿保留 + +这里不能隐式做决定。 + +--- + +## 7. 状态可见位置规范 + +### 7.1 首页 + +首页只展示高层状态： + +- 已连接 / 未连接 +- 运行中 / 配置中 +- 电量 +- 可选：存在未同步改动 + +不展示： + +- 复杂诊断态 +- 详细同步错误栈 + +### 7.2 设备工作区 + +设备工作区必须同时承载三层状态摘要： + +- 左下：连接与控制权 +- 顶部或底部主状态带：同步与阻断态 +- Inspector 辅助提示：当前部件相关的同步 / 权限摘要 + +### 7.3 次级页面 + +#### 后台服务页 + +重点显示控制权状态。 + +#### 语音页 + +重点显示权限状态。 + +#### 设备信息页 + +重点显示连接与诊断状态。 + +--- + +## 8. 状态与操作权限矩阵 + +| 状态 | 可浏览 | 可编辑草稿 | 可同步到设备 | 可切回运行中 | +|------|------|------|------|------| +| 运行中 + 未连接 | 是 | 受限，默认只读或本地预编辑 | 否 | 已在运行中 | +| 配置中 + 连接中 | 部分 | 否 | 否 | 否 | +| 配置中 + 已连接 + 无脏改动 | 是 | 是 | 是 | 是 | +| 配置中 + 已连接 + 有脏改动 | 是 | 是 | 是 | 是（需确认） | +| 配置中 + 同步中 | 是 | 部分禁用 | 进行中 | 否 | +| 配置中 + 同步失败 | 是 | 是 | 是（可重试） | 是（需确认） | + +注： + +- “运行中 + 未连接”是否允许本地预编辑，需要在实现层明确选择。默认建议允许编辑草稿，但明确告诉用户尚未写入设备。 + +--- + +## 9. 与现有代码的映射 + +### 9.1 BLE 层 + +来源： + +- `AhaKeyBLEManager` + +关键字段： + +- `isScanning` +- `isConnected` +- `bleConnectionStatus` +- `batteryLevel` +- `workMode` + +### 9.2 控制权层 + +来源： + +- `AgentManager.bluetoothConnectionOwner` + +用户文案映射必须遵守 [00-glossary.md](../00-glossary.md)： + +- `AhaKey Studio` 持有 -> `配置中` +- `agentDaemon` 持有 -> `运行中` + +### 9.3 草稿层 + +当前代码中的现实来源： + +- `studioDraft` +- `lastSyncedDraft` +- `isSyncing` + +重构后应上升为明确的页面级状态模型，而不是继续散落在一个超长 view 中。 + +--- + +## 10. 实现约束 + +### 10.1 不允许把状态只藏在按钮文案里 + +用户不能靠阅读按钮文字猜自己现在是什么状态。 + +### 10.2 不允许把控制权状态只写在技术页里 + +“运行中 / 配置中”必须在首页和工作区主路径上可见。 + +### 10.3 不允许把未同步改动做成一闪而过的 toast + +未同步改动是持续状态，不是一次性提示。 + +### 10.4 不允许用“Mode 0 / 1 / 2”替代平台状态 + +固件层模式只存在于内部实现，不进入主状态语言。 + +--- + +## 11. 验收标准 + +另一个工程师读完后，应能明确回答： + +- 当前 App 里到底有哪三层状态 +- 为什么 Logi 的工作区模型不能直接套用 +- 每一层状态应该显示在哪 +- 哪些操作在不同状态下可用 / 不可用 + +如果这些还需要靠会议口头补充，说明状态机 spec 仍不完整。 diff --git a/platforms/macos/client/docs/redesign/logi-options-plus-reference-spec/07-visual-system-spec.md b/platforms/macos/client/docs/redesign/logi-options-plus-reference-spec/07-visual-system-spec.md new file mode 100644 index 0000000..7c22360 --- /dev/null +++ b/platforms/macos/client/docs/redesign/logi-options-plus-reference-spec/07-visual-system-spec.md @@ -0,0 +1,474 @@ +# 视觉系统与组件语气 Spec + +更新时间：2026-05-03 +状态：草稿 + +--- + +## 1. 文档定位 + +本文档把“像 Logi Options+”从模糊感觉，收敛成可执行的视觉和组件规则。 + +目标不是复制 Logitech 品牌，而是建立一种适合 AhaKey 的桌面产品语言： + +- 克制 +- 稳定 +- 设备导向 +- 工作区导向 +- 对复杂状态友好 + +--- + +## 2. 整体视觉目标 + +### 2.1 视觉关键词 + +- 轻 +- 稳 +- 清楚 +- 设备中心 +- 以内容分层而不是以装饰取胜 + +### 2.2 参考的是“语气”，不是“品牌” + +允许高保真接近的维度： + +- 留白节奏 +- 表面层级 +- 分隔方式 +- 卡片与 panel 的克制感 +- 操作区的轻量密度 + +不复制： + +- Logitech 品牌色策略 +- Logitech 图标与品牌资产 +- 原始设备渲染素材 + +--- + +## 3. 视觉层级 + +建议把页面分为 4 层表面： + +### 3.1 App 背景层 + +用途： + +- 整个窗口底色 +- 大面积后退背景 + +特征： + +- 很轻的中性底 +- 不使用重渐变 +- 不制造强装饰 + +### 3.2 主内容层 + +用途： + +- 首页 hero 区 +- 中央工作区 +- 次级页面主体 + +特征： + +- 近白或轻微分层背景 +- 与窗口底有明确但温和的区分 + +### 3.3 辅助面板层 + +用途： + +- Inspector +- Settings 子面板 +- 状态卡 + +特征： + +- 比主内容层更“实体” +- 但不靠重阴影 + +### 3.4 浮层层 + +用途： + +- Popover +- Sheet 内重点区域 +- 关键确认框 + +特征： + +- 视觉上更聚焦 +- 不花哨 + +--- + +## 4. Token 建议 + +以下不是最终代码常量名，但应作为 Web / Electron 原型与后续 SwiftUI token 层的基线。 + +### 4.1 颜色角色 + +- `windowBackground` +- `pageSurface` +- `panelSurface` +- `panelSurfaceElevated` +- `dividerSubtle` +- `dividerStrong` +- `textPrimary` +- `textSecondary` +- `textTertiary` +- `accentPrimary` +- `accentSoft` +- `success` +- `warning` +- `danger` +- `info` + +要求： + +- 用“角色”命名，而不是直接写具体色值含义 +- 保证浅色 / 深色模式都能映射 + +### 4.1.1 Logi 主题 token 参考 + +Logi Options+ 的 `app.min.css` 已确认存在 `body.light` / `body.dark` 两套 CSS 变量。下一轮 Web 原型可以据此建立 AhaKey 自己的语义 token。 + +参考映射： + +| AhaKey token | Logi light 参考 | Logi dark 参考 | 用途 | +|--------------|-----------------|----------------|------| +| `--ak-bg-app` | `#fff` / `#fbfbfb` | `#000` | 应用大背景 | +| `--ak-bg-page` | `#fbfbfb` | `#191919` | 页面主体与 Settings 背景 | +| `--ak-bg-panel` | `#f5f5f5` | `#222425` / `#333` | 设置项、下拉框、局部 panel | +| `--ak-bg-panel-muted` | `#f0f0f0` | `#191919` | 次级控件底 | +| `--ak-text-primary` | `#222425` | `#fbfbfb` | 标题与主要正文 | +| `--ak-text-secondary` | `#888` | `#ccc` | 辅助说明 | +| `--ak-text-inverse` | `#000` | `#fff` | 反色文字 | +| `--ak-accent` | `#814efa` | `#00ead0` | 选中态、主操作、链接 | +| `--ak-accent-hover` | `#673ec8` | `#03dbc3` | hover / pressed | +| `--ak-accent-soft` | `rgba(129,78,250,.1)` | `rgba(0,234,208,.1)` | 轻量选中底 | +| `--ak-border` | `#d8d8d8` | `#666` | Settings 卡片、分隔、输入控件 | +| `--ak-success` | `#79e053` | `#79e053` | 电量、连接成功 | +| `--ak-warning` | `#ffa414` | `#ffa414` | 警告 | +| `--ak-danger` | `#ff2947` | `#ff2947` | 错误 | + +执行要求： + +- 原型必须支持 `light` / `dark` 两套 token。 +- 主题入口在 mock / review 面板里可切换，方便合作者对照。 +- AhaKey 默认不直接照搬 Logi 的紫色品牌感；可以保留紫色作为 light accent 参考，但最终 accent 应优先服从 AhaKey 品牌。 +- 深色模式的结构必须来自 token，不允许只给页面套 `filter` 或反色。 + +### 4.2 圆角 + +建议分三级： + +- 小：表单控件、pill、列表项 +- 中：panel、inspector、设置分组 +- 大：首页 hero、重要主卡片 + +要求： + +- 整体圆角克制 +- 不要到处使用过于圆润的玩具感卡片 + +### 4.3 阴影 + +阴影只承担： + +- 分层 +- 聚焦 + +不承担： + +- 装饰感 + +要求： + +- 常态阴影极轻 +- 选中态 / 浮层态稍强 +- 不出现厚重悬浮感 + +### 4.4 分隔线 + +优先使用： + +- 极浅实体线 +- 轻微透明度变化 + +不优先使用： + +- 深色重边框 +- 卡片套卡片式厚分隔 + +--- + +## 5. 排版系统 + +### 5.1 标题层级 + +- App / 页面标题 +- 分组标题 +- 面板标题 +- 字段标签 +- 辅助说明 + +要求： + +- 层级清楚 +- 字重变化克制 +- 不依赖超大字号制造“设计感” + +### 5.2 文本密度 + +桌面应用允许比营销页更高的信息密度，但必须： + +- 容易扫读 +- 大段说明前先给结论 +- 状态说明尽量简短直接 + +### 5.3 文案语气 + +延续 AhaKey 当前规范： + +- 优先用用户能理解的结果词 +- 少用工程术语 +- 使用 [00-glossary.md](../00-glossary.md) 里的术语 + +--- + +## 6. 关键组件语气 + +### 6.1 顶栏 + +语气： + +- 稳定 +- 稀疏 +- 品牌感轻 + +不做成： + +- 一排非常重的彩色按钮 +- 仪表盘式状态墙 + +### 6.2 平台切换器 + +语气： + +- 高层上下文切换器 +- 视觉上比 segmented control 更轻、更像“平台标签” + +要求： + +- 当前平台识别强 +- 未选中平台弱化但清晰可点 + +### 6.3 左侧导航 + +语气： + +- 工具式 +- 克制 +- 可连续扫读 + +要求： + +- 当前项高亮清楚 +- 分组分隔明确 +- 底部状态区与导航项视觉区别明显 + +### 6.4 Hero 卡片 + +语气： + +- 页面主角 +- 设备中心 +- 不像营销 banner + +要求： + +- 真实设备是主要注意力 +- 状态和入口围绕设备组织 + +### 6.5 Inspector + +语气： + +- 专业 +- 安静 +- 结构化 + +要求： + +- 标题、主配置、说明、辅助提示分区明确 +- 不出现大块花哨装饰 + +### 6.6 状态 pill + +状态 pill 用于： + +- 运行中 / 配置中 +- 已连接 / 未连接 +- 未同步改动 + +要求： + +- 轻量 +- 一眼可识别 +- 不做成抢眼大 badge + +### 6.7 提示条 / banner + +用于： + +- 当前不可写 +- 有未同步改动 +- 同步失败 +- 权限不完整 + +要求： + +- 永远先给结论 +- 再给建议动作 +- 色彩权重服从严重程度 + +--- + +## 7. 交互反馈 + +### 7.1 Hover + +桌面端必须用好 hover，但要克制。 + +适用： + +- 导航项 +- 热区 +- 次按钮 +- 卡片点击区 + +### 7.2 Selection + +选中态必须稳定可见。 + +适用： + +- 当前平台 +- 当前导航项 +- 当前画布部件 + +### 7.3 Disabled + +禁用态需要清楚表达“为什么不可用”，尤其是： + +- 当前处于运行中 +- 同步中 +- 权限缺失 + +不能只是灰掉。 + +### 7.4 Success / Failure + +同步成功 / 失败应有清楚反馈，但不需要重动画。 + +建议： + +- 成功：轻量短暂确认 +- 失败：稳定留存，直到用户处理 + +--- + +## 8. 页面密度与布局约束 + +### 8.1 首页 + +- 低到中密度 +- 重心在 hero +- 尽量不出现多列杂项卡片 + +### 8.2 工作区 + +- 中密度 +- 中央画布与右侧 inspector 权重平衡 +- 左侧导航始终轻于中央内容 + +### 8.3 次级页面 + +- 中密度 +- 先摘要卡，后详细内容 +- 高级诊断折叠在后 + +### 8.4 Settings + +- 中高密度但结构化 +- 与系统偏好设置语气一致 +- 深色模式下采用左侧固定导航 + 中央内容列，不使用卡片堆砌 +- 当前导航项用左侧青色竖条和文字强调表达 +- 通用设置、通知、反馈与支持等页面使用大标题 + 分组标题 + 行级控件结构 +- 开关使用青绿色轨道与黑色圆点，默认态保持轻量 + +### 8.5 Settings 深色参考 + +用户提供的深色 Settings 截图确认了以下规则： + +- 背景接近纯黑，但内容不是高对比白卡片，而是直接在同一平面上排布。 +- 左侧导航宽度稳定，当前项用 accent 竖条和 accent 文本，不依赖大块背景。 +- 中央内容列有明确左边界感，页面标题约在内容列顶部偏左。 +- 表单控件体量大但数量克制：下拉框、toggle、主题卡都保持可扫读。 +- 主题卡选中态使用 accent 边框 + 圆形 check，不需要额外说明文字。 +- 链接统一使用 accent，正文和标题使用白色 / 浅灰分层。 + +--- + +## 9. 动效原则 + +动效只用于： + +- 状态切换确认 +- 页面级上下文切换 +- Inspector 与 panel 的轻量展开 + +不用于： + +- 装饰性炫技 +- 大面积漂浮 / 弹跳 + +要求： + +- 节奏短 +- 不打断工作 +- 不制造多余拟物感 + +--- + +## 10. 实现要求 + +这份视觉 spec 必须落成一层共享样式系统，而不是散落在各页内联写样式。 + +最少需要抽出： + +- 颜色角色 +- 字体角色 +- 圆角等级 +- 面板样式 +- 导航项样式 +- 状态 pill 样式 +- banner 样式 +- 按钮等级样式 + +否则后续重构会继续回到“一个页面一个风格”的状态。 + +--- + +## 11. 验收标准 + +另一个工程师读完后，应能直接回答： + +- AhaKey 的前台表面应该分几层 +- 哪些颜色 / 圆角 / 阴影需要 token 化 +- 首页 hero、工作区、inspector、状态 pill 分别应该是什么语气 +- 为什么这套系统是“像 Logi 的成熟度”，而不是“做成 Logitech 皮肤” diff --git a/platforms/macos/client/docs/redesign/logi-options-plus-reference-spec/08-swiftui-implementation-spec.md b/platforms/macos/client/docs/redesign/logi-options-plus-reference-spec/08-swiftui-implementation-spec.md new file mode 100644 index 0000000..5618037 --- /dev/null +++ b/platforms/macos/client/docs/redesign/logi-options-plus-reference-spec/08-swiftui-implementation-spec.md @@ -0,0 +1,288 @@ +# SwiftUI 实现映射 Spec + +更新时间：2026-05-02 +状态：草稿，现作为后续原生迁移参考 + +--- + +## 1. 文档定位 + +本文档把前面的产品 spec 直接翻译成 SwiftUI 实现层的拆分约束。 + +2026-05-03 更新： + +下一轮优先执行路径已调整为 [Web / Electron 原型交付](./09-web-electron-prototype-spec.md)。本文档暂不作为下一轮直接实施计划，而是保留为页面边界稳定后迁移到 SwiftUI 原生客户端时的参考。 + +它回答的问题是： + +- 页面应该怎样拆 +- 共享样式层应该怎样落 +- 当前 `AhaKeyStudioView` 应怎样被拆解 +- 哪些状态模型要上升为页面级导航状态 +- 哪些底层服务保持不动 + +--- + +## 2. 实现目标 + +本轮实现不是“给现有视图补几个 panel”，而是做一次**前台壳层重构**。 + +目标： + +1. `ContentView` 不再直接承载当前 studio +2. 首页与设备工作区分层 +3. 工作区与次级页面分层 +4. Inspector 职责收敛 +5. 样式系统抽离 + +非目标： + +- 改 BLE 协议 +- 改 `AgentManager` / `VoiceRelayService` 的核心逻辑 +- 改固件命令结构 + +--- + +## 3. 建议的视图拆分 + +### 3.1 顶层 + +建议新增： + +- `AppRootView` +- `HomeView` +- `StudioView` +- `Settings` scene + +当前： + +- `ContentView` 直接包 `AhaKeyStudioView` + +目标： + +- `ContentView` 或 `AppRootView` 只负责顶层导航分发 + +### 3.2 设备工作区 + +建议把当前 `AhaKeyStudioView` 拆成至少以下几个部分： + +- `StudioToolbar` +- `StudioSidebar` +- `PlatformSwitcher` +- `StudioCanvasHost` +- `StudioInspectorHost` +- `StudioStatusBanner` +- `StudioBottomStatus` + +### 3.3 次级页面 + +建议新增： + +- `AgentPageView` +- `VoicePageView` +- `DeviceInfoPageView` + +这些页面作为 `StudioView` 中央区域的替代内容，而不是 sheet 拼凑物。 + +### 3.4 首页 + +建议新增： + +- `DeviceHeroCard` +- `QuickActionsPopover` +- `AddDeviceSheet` + +--- + +## 4. 建议的状态模型拆分 + +### 4.1 顶层导航状态 + +需要新增一个顶层导航状态模型，至少包含： + +- 当前顶层页面 +- 当前设备 id / 当前设备引用 +- 当前是否显示设置 + +### 4.2 Studio 页面状态 + +设备工作区需要独立页面状态模型，至少包含： + +- 当前平台 +- 当前页面级导航项 +- 当前选中部件 +- 当前是否显示 inspector + +### 4.3 运行状态模型 + +在不改服务层的前提下，需要增加一个**面向页面的聚合状态层**，把底层服务翻译成 UI 能直接消费的状态。 + +例如聚合出： + +- `connectionState` +- `controlState` +- `syncState` + +而不是让页面到处自己拼： + +- `bleManager.isConnected` +- `agentManager.bluetoothConnectionOwner` +- `isSyncing` +- `studioDraft != lastSyncedDraft` + +### 4.4 视图状态 vs 服务状态 + +必须明确区分： + +- 服务状态：来自 BLE / Agent / Voice 单例 +- 页面状态：当前用户正在看哪里、选中了什么 + +这两层不能继续混在同一个巨型 view 里。 + +--- + +## 5. 样式系统建议 + +### 5.1 新建共享 UI 样式层 + +建议新增独立样式文件或目录，承载： + +- 色彩 token +- 字体角色 +- 圆角等级 +- 面板样式 +- 状态 pill 样式 +- banner 样式 + +### 5.2 避免继续在页面内散落样式 + +当前 `AhaKeyStudioView` 已经包含大量局部渐变、描边、圆角、阴影逻辑。 + +重构时应把这些收口到共享样式层，避免： + +- 首页一套风格 +- 工作区一套风格 +- 次级页面再一套风格 + +--- + +## 6. 现有 `AhaKeyStudioView` 迁移策略 + +### 6.1 保留的部分 + +当前可直接复用或局部重包的部分： + +- 键盘画布逻辑 +- 热区选中逻辑 +- OLED 预览相关视图 +- 同步命令拼装逻辑 + +### 6.2 需要拆出的部分 + +必须从 `AhaKeyStudioView` 中拆出的部分： + +- 顶栏 +- 左侧导航 +- 页面级状态表达 +- 后台服务 / 语音 / 设备信息的入口与承载 +- 全局状态提示 + +### 6.3 需要降级职责的部分 + +Inspector 应降级为： + +- 只处理当前部件属性编辑 + +不再承载： + +- 全局语音页职责 +- 后台服务页职责 +- 设备信息整页职责 + +--- + +## 7. 数据流建议 + +### 7.1 自上而下的导航分发 + +顶层页面切换从 root state 下发。 + +### 7.2 服务状态聚合 + +建议增加一层 UI-facing adapter / store，把： + +- `AhaKeyBLEManager` +- `AgentManager` +- `VoiceRelayService` + +聚合成页面可直接消费的状态对象。 + +### 7.3 草稿编辑流 + +建议保留草稿在本地编辑、显式同步的模型，但把“脏状态判断”和“同步状态文案”统一封到页面状态层。 + +--- + +## 8. 页面级实现顺序 + +建议的实现顺序： + +1. 建立 root navigation 与 `HomeView` +2. 拆出 `StudioView` 框架（顶栏 / 左栏 / 中央 / 右栏） +3. 把现有 `AhaKeyStudioView` 内容迁入 `StudioCanvasHost + StudioInspectorHost` +4. 实现 `AgentPageView / VoicePageView / DeviceInfoPageView` +5. 新建共享样式层 +6. 再做视觉统一与交互精修 + +理由： + +- 先把信息架构站稳 +- 再把功能从单视图里搬出来 +- 最后做视觉收口 + +--- + +## 9. 回归边界 + +本轮重构必须确保不破坏以下能力： + +- BLE 自动连接与手动连接 +- BLE 抑制逻辑（交给后台守护进程时本 App 不抢连） +- 现有同步命令链路 +- OLED 上传链路 +- Voice Relay 路由更新 +- 后台守护进程安装与状态检测 + +如果某次页面重构导致上述能力异常，应视为阻断问题，而不是“后面再看”的视觉问题。 + +--- + +## 10. 验收标准 + +### 10.1 工程结构验收 + +另一个工程师应能根据本文，直接开始建立： + +- 顶层导航 +- 首页 +- Studio 页面壳 +- 次级页面 +- 样式系统 + +### 10.2 代码边界验收 + +应能明确判断： + +- 哪些逻辑还留在服务层 +- 哪些逻辑属于页面状态聚合层 +- 哪些视图只负责渲染 + +### 10.3 产品一致性验收 + +应能确保： + +- 页面结构符合前面的信息架构 spec +- 状态表达符合状态机 spec +- 视觉语气符合视觉系统 spec + +如果实现时仍要频繁重新决定“这个页面到底归谁管”，说明这份实现 spec 还不够完整。 diff --git a/platforms/macos/client/docs/redesign/logi-options-plus-reference-spec/09-web-electron-prototype-spec.md b/platforms/macos/client/docs/redesign/logi-options-plus-reference-spec/09-web-electron-prototype-spec.md new file mode 100644 index 0000000..adbe95e --- /dev/null +++ b/platforms/macos/client/docs/redesign/logi-options-plus-reference-spec/09-web-electron-prototype-spec.md @@ -0,0 +1,418 @@ +# Web / Electron 原型交付 Spec + +更新时间：2026-05-03 +状态：下一轮优先执行草稿 + +--- + +## 1. 文档定位 + +本文档定义下一轮更务实的交付路径： + +**优先做 Web 形态的高保真前端原型，必要时再用 Electron 壳包装给合作者体验；不在本轮完整构建桌面应用。** + +它替代“直接进入 SwiftUI 原生重构”作为下一轮执行入口。SwiftUI 拆分文档仍保留，但降级为后续原生迁移参考。 + +--- + +## 2. 为什么先做 Web / Electron 原型 + +Logi Options+ 本身是 Electron + React，说明它的前台体验可以用 Web 技术完整承载。 + +对 AhaKey 当前阶段来说，先做 Web 原型的收益更高： + +- 合作者可以直接打开网页或压缩包预览 +- 页面、动线、状态表达可以快速迭代 +- 不需要先处理 macOS 原生窗口、权限、BLE、后台服务打包 +- 可以高保真参考 Logi 的页面壳、布局节奏和组件语气 +- 后续如果要包 Electron，只需要加薄壳，不改变前端页面结构 + +本轮目标不是证明技术集成，而是先把“产品壳长什么样、用户怎么走、状态怎么表达”定下来。 + +--- + +## 3. 交付形态 + +### 3.1 首选交付 + +一个可运行的 Web 前端原型： + +- 本地开发时通过 dev server 预览 +- 对外交付时可导出静态构建目录或压缩包 +- 合作者不需要安装完整 macOS App + +### 3.2 可选包装 + +如果需要更像桌面应用，可以加一个极薄 Electron wrapper： + +- 只负责打开同一套 Web 前端 +- 不接入真实 BLE +- 不接入真实后台服务 +- 不处理系统级权限 +- 不引入自动更新、签名、公证、安装器 + +Electron 在本阶段只是“演示容器”，不是完整桌面产品。 + +### 3.3 非目标 + +本轮不做： + +- 完整 macOS 原生客户端 +- SwiftUI 页面落地 +- BLE 真实连接 +- Agent / Voice 后端协议接入 +- 系统权限真实申请 +- 设备固件写入 +- Logitech 资源或代码复制 + +--- + +## 4. 推荐技术边界 + +建议使用： + +- React +- TypeScript +- Vite +- CSS Modules 或普通 CSS token 层 +- 本地 mock state +- 可选 Electron wrapper + +不建议本轮引入： + +- 复杂后端 +- 数据库 +- 跨平台桌面构建流水线 +- 真实系统 API +- 大型 UI 组件库 + +理由：这轮最重要的是页面判断和交互节奏，不是工程平台完备度。 + +### 4.1 开工基线 + +截至 2026-05-03，远端状态如下： + +- 本地 `desktop/main` 当前仍在 `d1bdb4d`。 +- `upstream/main` 已推进到 `42a13be`，比本地多 24 个提交。 +- `upstream/main` 已合入 `upstream/dev` 的 VoiceAgent / Feishu / AhaKey 工作台相关改动。 +- `upstream/main` 新增了 `platforms/macos/client/docs/prototypes/ahakey-design-spec.md` 和旧 HTML 原型资料。 +- `upstream/main` 新增了 SwiftUI 侧的 `AhaKeyDesignSystem.swift`，其中已有浅色 / 深色 appearance mode 与基础 token。 + +下一轮原型应基于远端最新 `upstream/main` 开干净分支或 worktree，不建议直接在当前 dirty 工作区 `pull`。 + +推荐做法： + +- 先保留当前 spec 文档改动。 +- 从 `upstream/main` 开原型分支，例如 `prototype/logi-web-shell`。 +- 原型代码放在 macOS client 文档/原型范围内，优先避免碰现有 Swift 源文件。 +- 只有需要复用远端设计说明时，读取 `docs/prototypes/ahakey-design-spec.md` 和 `AhaKeyDesignSystem.swift`，不要把旧 HTML 原型当作最终架构。 + +### 4.2 远端新信息对原型的影响 + +远端新推送意味着下一轮不是从空白开始： + +- VoiceAgent 已成为产品主线之一，原型必须保留 `Agent` / `Voice` 页面入口。 +- Feishu 集成已经进入远端，原型的 Agent/Voice 页应预留第三方集成状态，但不要在首版做真实登录。 +- 远端已有 AhaKey 自己的设计 token 草案，Web 原型应吸收其角色命名和层级，不只参考 Logi。 +- 旧 HTML 原型可作为 AhaKey 自身风格历史参考，但本轮主目标仍是 Logi 式前台壳。 + +--- + +## 5. 页面范围 + +### 5.1 必做页面 + +#### Home + +参考 Logi 首页设备总览： + +- 顶部问候 / 品牌区 +- 右上角操作区 +- 无设备空态 +- 单设备已连接态 +- 多设备布局预留 +- 添加设备入口 +- Smart Actions / 快捷操作入口 +- Settings 入口 + +AhaKey 映射： + +- 首页是设备选择器 +- 主视觉从 Logi 的鼠标 / 键盘 hero 改为 AhaKey 设备 hero +- 不展示 Logitech 品牌、生态文案、原始插图 + +#### Add Device Flow + +参考已观察到的“选择连接类型”页面： + +- 返回按钮 +- 居中标题 +- 单个或多个连接方式卡片 +- 底部辅助说明 + +AhaKey 映射： + +- 首版可以只保留 `Bluetooth` +- 文案改为 AhaKey 语气 +- 权限和扫描结果用 mock 状态表达 + +#### Device Studio + +参考 Logi 设备详情 / 自定义工作区： + +- 返回首页 +- 平台 / 应用上下文切换器 +- 中央设备画布 +- 可点击热点 +- 右侧 inspector +- 状态 pill / 同步状态 + +AhaKey 映射： + +- 平台切换器固定为 `Claude Code / Cursor / Codex` +- 中央画布使用 AhaKey 键盘示意，不使用 Logi 设备图 +- inspector 编辑 AhaKey 的按键、OLED、灯条、拨杆 +- 明确显示草稿 / 同步 / 控制权状态 + +### 5.2 应做页面 + +#### Settings + +用于承载全局元操作： + +- 启动项 +- 后台服务 +- 权限 +- 诊断 +- 关于 + +#### Agent + +作为设备工作区内的软件功能页： + +- 后台服务状态 +- 当前运行模式 +- 控制权说明 +- mock 启停操作 + +#### Voice + +作为设备工作区内的软件功能页： + +- 麦克风权限态 +- 语音输入启用态 +- 当前语音目标或 provider mock + +--- + +## 6. 原型状态模型 + +Web 原型不接真实服务，但必须模拟 AhaKey 的核心状态复杂度。 + +### 6.1 设备状态 + +至少支持： + +- `noDevice` +- `scanning` +- `connected` +- `disconnected` +- `permissionRequired` + +### 6.2 控制权状态 + +至少支持： + +- `runtimeOwnerAgent`：运行中，后台持有连接 +- `configOwnerStudio`：配置中，Studio 持有连接 +- `handoffPending`：控制权切换中 +- `handoffFailed`：控制权切换失败 + +### 6.3 草稿同步状态 + +至少支持： + +- `clean` +- `dirty` +- `syncing` +- `synced` +- `syncFailed` + +这些状态要在页面里可切换，方便合作者评审所有状态，而不是只看一张静态默认态。 + +--- + +## 7. 组件拆分建议 + +建议第一版拆成以下组件边界： + +- `AppShell` +- `HomePage` +- `TopActionBar` +- `DeviceHero` +- `DeviceStatusPill` +- `AddDevicePage` +- `DeviceStudioPage` +- `PlatformSwitcher` +- `StudioCanvas` +- `HotspotCallout` +- `StudioInspector` +- `SyncStatusBanner` +- `SettingsPage` +- `AgentPage` +- `VoicePage` +- `MockStatePanel` + +`MockStatePanel` 只在原型评审版本里显示，用于切换状态矩阵；未来正式 UI 可移除。 + +--- + +## 8. 视觉执行原则 + +从当前截图与 React / CSS 逆向可以确定的方向： + +- 大面积浅背景 +- 极少边框 +- 顶部操作区右对齐 +- 主设备 hero 居中偏视觉重心 +- 文字层级克制 +- icon + text 组合用于主要动作 +- 右侧 inspector 使用独立浅表面 +- 状态 pill 小而明确 +- 紫色只作为选中 / 强调色，不作为整页主色 +- 明暗主题都必须是一等公民 +- 深色 Settings 使用近黑背景、白色文本层级和青绿色 accent + +需要 AhaKey 化的地方： + +- 不使用 Logi 插图和设备图 +- 不使用 Logitech 品牌色和品牌文案 +- 不照搬鼠标滚轮、Flow、Easy-Switch 等专属能力 +- AhaKey 的状态语言要比 Logi 更显式，因为它有控制权和草稿同步问题 + +### 8.1 原型主题 token + +已确认 Logi React/CSS 包提供 `body.light` / `body.dark` 两套主题变量。Web 原型必须建立自己的 `:root[data-theme="light"]` / `:root[data-theme="dark"]` token。 + +最低 token 集： + +```css +:root[data-theme="light"] { + --ak-bg-app: #fff; + --ak-bg-page: #fbfbfb; + --ak-bg-panel: #f5f5f5; + --ak-bg-control: #f0f0f0; + --ak-text-primary: #222425; + --ak-text-secondary: #888; + --ak-accent: #814efa; + --ak-accent-hover: #673ec8; + --ak-accent-soft: rgba(129, 78, 250, 0.1); + --ak-border: #d8d8d8; +} + +:root[data-theme="dark"] { + --ak-bg-app: #000; + --ak-bg-page: #191919; + --ak-bg-panel: #222425; + --ak-bg-control: #333; + --ak-text-primary: #fbfbfb; + --ak-text-secondary: #ccc; + --ak-accent: #00ead0; + --ak-accent-hover: #03dbc3; + --ak-accent-soft: rgba(0, 234, 208, 0.1); + --ak-border: #666; +} +``` + +这些值来自 Logi CSS token 的参考抽取，不作为 AhaKey 最终品牌色承诺。实现时应通过角色 token 使用，不允许在组件里散落硬编码色值。 + +### 8.2 深色 Settings 页面规则 + +根据新截图，Settings 原型至少覆盖： + +- `General` +- `Notifications` +- `Feedback & Support` + +页面规则： + +- 左侧固定导航，当前项用 accent 竖条 + accent 文本。 +- 内容列最大宽度控制在可读范围内，不铺满整屏。 +- 每页使用大标题、分组标题、正文 / 链接 / 控件的层级。 +- `General` 必须包含版本信息、检查更新、自动更新 toggle、语言下拉、主题卡片。 +- `Notifications` 必须包含通用通知 toggle 与叠加通知分组。 +- `Feedback & Support` 必须包含反馈链接、评分链接、故障排除链接、蓝牙问题 checkbox 组。 +- 深色截图只作为结构与语气参考，文案必须改为 AhaKey。 + +--- + +## 9. 当前证据来源 + +截至 2026-05-03，本专题的 UI 判断来自三类来源： + +| 来源 | 当前贡献 | 适合决定什么 | 不适合决定什么 | +|------|----------|--------------|----------------| +| React / CSS / assets 逆向 | 高 | 页面家族、组件名称、样式 token、文案、状态信号 | 最终运行时像素表现 | +| 用户提供截图 | 中 | 首页、添加设备、设备详情、inspector、深色 Settings 的真实视觉节奏 | 全状态覆盖、交互逻辑完整性 | +| AhaKey 产品约束 | 高 | BLE 控制权、草稿同步、平台语义 | Logi 原组件真实细节 | +| 远端 AhaKey 新推送 | 中 | VoiceAgent/Feishu 已进入产品主线、AhaKey 自有 token 草案、旧原型资料 | Logi 原组件真实细节 | + +粗略判断： + +- 信息架构：React / CSS 已足够覆盖约 80% +- 组件清单：React / CSS 加截图可覆盖约 75% +- 视觉方向：当前截图可覆盖约 60%，还需要 AhaKey 设备工作区细节补图 +- 明暗主题 token：React / CSS 已确认可覆盖约 80%，截图用于校验运行时观感 +- 交互状态：React / CSS 可辅助推断约 60%，但关键状态仍需 mock 验证 +- 像素级复刻：不追求法律意义上的逐像素复制，目标是 85% 左右的产品体验相似度 + +--- + +## 10. 还需要的截图资产 + +因为下一轮改为 Web 原型，截图不再追求穷尽采集，而是只补关键决策缺口。 + +优先需要： + +1. 设备详情页完整正视角截图 +2. 右侧 inspector 的默认态、选中态、编辑态 +3. 平台 / 应用切换器的 hover、selected、添加应用态 +4. Settings 首页与一个二级设置页 +5. 权限态或错误态页面 + +可选需要： + +- 首页设备 hover 态 +- 设备断开态 +- 同步中 / 成功 / 失败状态 +- popover 或 sheet 打开态 +- 短录屏，用于观察页面切换和 hover 动效 + +截图只进入 `captures/raw-local/`，由后续整理动作筛选为 `tracked/` 精选资产。 + +--- + +## 11. 验收标准 + +下一轮原型完成后，应满足： + +1. 合作者能在浏览器里完整走通 Home -> Add Device -> Device Studio -> Settings。 +2. 主要页面不依赖真实后端，也能展示关键状态。 +3. Device Studio 能表达平台切换、热点选中、右侧 inspector、草稿同步。 +4. 视觉上能明显看出参考了 Logi 的成熟桌面软件壳层。 +5. 内容、品牌、设备图、文案都已经 AhaKey 化。 +6. 代码结构允许后续升级为 Electron 包装或迁移到 SwiftUI。 + +--- + +## 12. 与 SwiftUI 文档的关系 + +[08-swiftui-implementation-spec.md](./08-swiftui-implementation-spec.md) 仍然有效，但它不再是下一轮的直接执行入口。 + +新的顺序是： + +1. 先用 Web 原型验证 UI/UX 和状态模型 +2. 必要时用 Electron 壳交付给合作者 +3. 等页面边界和状态表达稳定后，再决定是否迁移到 SwiftUI 原生客户端 + +这样可以避免在产品壳还没定型时，就提前承担完整桌面工程成本。 diff --git a/platforms/macos/client/docs/redesign/logi-options-plus-reference-spec/10-inspector-content-spec.md b/platforms/macos/client/docs/redesign/logi-options-plus-reference-spec/10-inspector-content-spec.md new file mode 100644 index 0000000..acf042e --- /dev/null +++ b/platforms/macos/client/docs/redesign/logi-options-plus-reference-spec/10-inspector-content-spec.md @@ -0,0 +1,459 @@ +# Inspector 内容 Spec + +更新时间：2026-05-06 +状态：草稿 + +--- + +## 1. 文档定位 + +本文档定义 AhaKey Studio 设备工作区右侧 Inspector 的**逐部件内容边界**。 + +它回答的问题是： + +- 每个硬件部件的 Inspector 里应该有什么 +- 哪些内容必须移出 Inspector，移到哪个独立页面 +- Inspector 的通用结构模板是什么 + +本文档是 [04-device-studio-spec.md](./04-device-studio-spec.md) 的内容层细化，与 [05-secondary-pages-spec.md](./05-secondary-pages-spec.md) 互为对照。 + +--- + +## 2. Inspector 总体原则 + +### 2.1 Inspector 只回答一个问题 + +> **"当前选中的这个硬件部件，在当前平台下应该做什么？"** + +Inspector 是属性编辑面板，不是功能配置中心。 + +### 2.2 Inspector 不承载的内容 + +以下内容不属于 Inspector 的职责范围： + +- 跨硬件的软件功能配置（语音预设选择、权限申请流程） +- 后台服务生命周期控制（安装、启动、停止） +- Hook 安装向导 +- BLE 诊断日志 +- 控制权切换操作 + +这些内容有各自的独立页面（语音页、后台服务页、设备信息页）。 + +### 2.3 Inspector 空态 + +未选中任何热区时，Inspector 区域**隐藏**，不显示占位内容。 + +点击画布热区后，Inspector 从右侧滑入。 + +这样中央画布在默认态可以占满宽度，用户的注意力集中在设备全貌上。 + +### 2.4 Inspector 头部固定结构 + +所有部件的 Inspector 共用同一个极简头部结构： + +``` +┌─────────────────────────────────┐ +│ 部件名 │ +└─────────────────────────────────┘ +``` + +- 平台切换器只保留在工作区右上角，不进入 Inspector 头部 +- 不显示平台名 +- 不显示 `部件名 · 副标题` 这类中点式标题 +- 如需提示脏状态，应作为极轻的局部 badge 出现，不制造第二层标题区 + +### 2.5 Inspector 底部固定操作栏 + +Inspector 底部操作栏按需出现，固定在底部不随内容滚动： + +``` +┌─────────────────────────────────┐ +│ [同步到键盘] │ +└─────────────────────────────────┘ +``` + +- 主按钮只在当前部件确实有待提交改动时出现 +- 不固定保留“次操作”按钮；次操作更适合并入内容区或移到次级页面 + +--- + +## 3. 各部件 Inspector 内容定义 + +### 3.1 Key 1（语音键） + +#### 留在 Inspector + +| 内容 | 类型 | 说明 | +|------|------|------| +| 当前语音预设名称 | 只读文本 | 如"macOS 原生"、"Typeless"、"微信" | +| 当前触发键绑定 | 只读文本 | 固定为 F18，不可在此修改 | +| 权限状态 badge | 只读状态 | 绿色"正常" / 红色"缺少权限" | +| 按键描述 | 可编辑文本 | 写入 OLED 的标签文字，如"Record" | +| 跳转链接 | 导航入口 | "→ 语音设置"，导航到语音页 | + +#### 移出 Inspector（移到语音页） + +| 内容 | 原位置 | 目标位置 | +|------|--------|---------| +| VoicePresetPicker 下拉选择器 | Key 1 Inspector | 语音页 · 平台语音映射区 | +| VoiceRelayService 状态详情 | Key 1 Inspector | 语音页 · 当前路由摘要 | +| NativeSpeechTranscriptionService 状态 | Key 1 Inspector | 语音页 · 当前路由摘要 | +| 输入监控 / 辅助功能权限引导 | Key 1 Inspector | 语音页 · 权限总览卡 | +| 麦克风 / 语音识别权限引导 | Key 1 Inspector | 语音页 · 权限总览卡 | +| lastPermissionCheckSummary | Key 1 Inspector | 语音页 | +| lastInspectorSimulateHint | Key 1 Inspector | 语音页 | + +#### 设计理由 + +Key 1 的 Inspector 应该告诉用户"现在语音是什么状态"，而不是"如何配置语音"。 + +语音预设的选择会影响所有平台下的 Key 1 行为，是跨平台的全局配置，不属于单个部件在单个平台下的属性编辑。把它放在 Inspector 里会让用户误以为这是"当前平台专属"的设置。 + +#### 示意 + +``` +Key 1 +───────────────────────────────── +语音预设：macOS 原生 +触发键：F18 +权限：● 正常 + +→ 语音设置 +───────────────────────────────── +按键描述：Record +───────────────────────────────── + [同步到键盘] +``` + +--- + +### 3.2 Key 2（批准键）/ Key 3（拒绝键）/ Key 4（提交键） + +#### 留在 Inspector + +| 内容 | 类型 | 说明 | +|------|------|------| +| 当前激活层 | radio 切换 | 快捷键 / 宏，二选一 | +| 快捷键绑定 | 可编辑 | HID keycode picker，当前平台下的绑定值 | +| 宏编辑器 | inline 展开 | 见下方说明 | +| 按键描述 | 可编辑文本 | 写入 OLED 的标签文字 | + +#### 平台差异 + +Inspector 内容结构在三个工作区下相同，但绑定值随平台切换而变化。 + +切换平台时，Inspector 内容刷新为对应工作区的值，不需要重新选中热区。 + +可见平台状态只在右上角切换器呈现，Inspector 正文不重复品牌名。 + +各工作区的默认绑定值： + +| 键位 | Workspace A | Workspace B | Workspace C | +|------|-------------|--------|-------| +| Key 2 | Yes（F19） | Accept | Approve | +| Key 3 | No（Escape） | Reject | Reject | +| Key 4 | Submit（Enter） | Submit | Submit | + +用户可以在任意平台下覆盖默认值，各平台独立存储。 + +#### 宏编辑器 + +宏编辑器作为 Inspector 内的**展开区域**（inline expand），不弹出独立 sheet 或页面。 + +展开后显示： + +- 步骤列表（最多 49 步） +- 每步支持：downKey / upKey / upAllKeys / delay / noOp +- delay 单位：3ms +- 步骤可拖拽排序、删除、插入 + +理由：宏编辑是当前键位在当前平台下的属性，上下文明确，不需要独立页面。inline 展开保持了"我在编辑这个键"的心智，不会让用户迷失在独立页面里。 + +#### 示意 + +``` +Key 2 +───────────────────────────────── +激活层：● 快捷键 ○ 宏 + +快捷键：[F19] + +按键描述：Yes +───────────────────────────────── + [同步到键盘] +``` + +--- + +### 3.3 OLED + +#### 留在 Inspector + +| 内容 | 类型 | 说明 | +|------|------|------| +| GIF 素材选择 | 缩略图列表 | 当前平台下的动图选择 | +| 帧率设置 | stepper | 1–30 FPS | +| 预览区 | 只读 | 当前帧静态预览 | +| 上传按钮 | 主操作 | 文案："上传并保存" | +| 上传进度条 | 状态 | 上传中显示 | +| 上传结果 | 状态 | ✓ 已保存到设备 / ✗ 上传失败 [重试] | + +#### saveConfig 修复 + +当前代码 `uploadCurrentOLEDToDevice()` 在上传像素帧数据（`updatePicture(0x82)`）后没有追加 `saveConfig(0x04)`，导致像素数据写入了外部 Flash，但 `key_bund.pic[mode]` 引用只在 RAM 里，设备重启后 OLED 恢复为空。 + +修复方案： + +- `uploadCurrentOLEDToDevice()` 完成后自动追加 `saveConfig(0x04)` +- 不向用户暴露"像素数据"和"引用"的区别，这是固件实现细节 +- 按钮文案改为"上传并保存"，明确表达这是一个持久化操作 +- 上传成功后，OLED 相关的 `dirtyCount` 清零 + +用户不需要知道有两步，只需要知道"上传并保存"是一个完整的操作。 + +#### 移出 Inspector + +无。OLED 配置相对自洽，不需要独立页面。 + +#### 示意 + +``` +OLED +───────────────────────────────── +[缩略图] [缩略图] [缩略图] [缩略图] +[缩略图] [缩略图] [缩略图] [+] + +帧率：[12] FPS + +预览：[████████] + +───────────────────────────────── + [上传并保存] +``` + +--- + +### 3.4 灯条 + +#### 留在 Inspector + +| 内容 | 类型 | 说明 | +|------|------|------| +| 版本说明 | 只读文本 | "灯条效果由固件根据键盘状态自动驱动" | +| IDEState → 灯效映射摘要 | 只读表格 | 9 个状态对应颜色/效果，不可编辑 | +| 预览到设备按钮 | 操作 | 发送 updateState 命令，临时预览某个状态的灯效 | +| 阶段限制说明 | 只读文本 | "自定义灯效将在后续版本支持" | + +#### 移出 Inspector + +无。灯条当前只读，内容量合适，不需要独立页面。 + +#### 注意 + +灯条 Inspector 不显示 IDEState 的完整编辑界面，只做摘要 + 预览。 + +IDEState 的 9 个状态： + +| 状态 | 含义 | +|------|------| +| notification | 通知 | +| permissionRequest | 权限请求 | +| postToolUse | 工具调用后 | +| preToolUse | 工具调用前 | +| sessionStart | 会话开始 | +| stop | 停止 | +| taskCompleted | 任务完成 | +| userPromptSubmit | 用户提交 | +| sessionEnd | 会话结束 | + +#### 示意 + +``` +灯条 · 状态映射 +───────────────────────────────── +灯条效果由固件根据键盘状态自动驱动 + +状态 灯效 +────────────────── +会话开始 蓝色呼吸 +工具调用前 黄色常亮 +工具调用后 绿色闪烁 +任务完成 绿色常亮 +停止 红色常亮 +… + +预览：[选择状态 ▼] [预览到设备] + +自定义灯效将在后续版本支持 +``` + +--- + +### 3.5 拨杆（批准模式） + +#### 留在 Inspector + +| 内容 | 类型 | 说明 | +|------|------|------| +| 当前档位 | 只读状态 | 来自硬件实时状态：自动批准 / 手动批准 | +| 档位语义说明 | 只读文本 | 见下方 | +| 当前平台下的行为说明 | 只读文本 | 与平台切换器联动 | +| 跳转链接 | 导航入口 | "→ 后台服务"，导航到后台服务页 | + +档位语义说明： + +- **自动批准**：后台服务运行时，工具调用自动确认，无需物理按键 +- **手动批准**：每次工具调用需要物理按下 Key 2 确认 + +#### 移出 Inspector（移到后台服务页） + +| 内容 | 原位置 | 目标位置 | +|------|--------|---------| +| 后台服务安装状态（isInstalled） | 拨杆 Inspector | 后台服务页 · 状态总览卡 | +| 后台服务运行状态（isRunning） | 拨杆 Inspector | 后台服务页 · 状态总览卡 | +| 后台服务 BLE 连接状态（isAgentBLEConnected） | 拨杆 Inspector | 后台服务页 · 状态总览卡 | +| Hook 安装状态（claudeHooksInstalled 等） | 拨杆 Inspector | 后台服务页 · Hook 覆盖区 | +| inline 安装/启动按钮 | 拨杆 Inspector | 后台服务页 · 主要交互 | +| 控制权切换操作（bluetoothConnectionOwner） | 拨杆 Inspector | 后台服务页 · 控制权区 | + +#### 用词规范（重要） + +拨杆 Inspector 全文**禁止出现"Agent"一词**。 + +统一用词： + +| 禁止 | 使用 | +|------|------| +| Agent | 后台服务 | +| Agent 模式 | 运行中 | +| IDE 模式 | 配置中 | +| ahakeyconfig-agent | 后台服务 | + +理由：在 Inspector 这个上下文里，"Agent"极易与 AI Agent（Claude、Cursor 等）混淆，造成用户误解。"后台服务"是准确且无歧义的描述。 + +#### 示意 + +``` +拨杆 · 批准模式 +───────────────────────────────── +当前档位：● 自动批准 + +自动批准 +后台服务运行时，工具调用自动确认， +无需物理按键。 + +手动批准 +每次工具调用需要物理按下 Key 2 确认。 + +───────────────────────────────── +→ 后台服务 +``` + +--- + +## 4. Inspector 通用结构模板 + +``` +┌─────────────────────────────────┐ +│ [平台 logo] 平台名 │ ← 可点击切换平台 +│ ─────────────────────────────── │ +│ 部件名 · 副标题 [● 未同步] │ ← 脏状态 badge（有改动时显示） +│ ─────────────────────────────── │ +│ │ +│ 主属性区（可编辑） │ +│ │ +│ ─────────────────────────────── │ +│ 预览 / 说明区（只读） │ +│ │ +│ ─────────────────────────────── │ +│ 跳转链接（如有） │ +│ │ +│ ─────────────────────────────── │ +│ [次操作] [同步到键盘] │ ← 固定底部操作栏 +└─────────────────────────────────┘ +``` + +各区域说明： + +- **主属性区**：当前部件在当前平台下的可编辑属性 +- **预览 / 说明区**：只读内容，帮助用户理解当前配置的效果 +- **跳转链接**：当部件有关联的独立页面时，提供导航入口 +- **底部操作栏**：固定，不随内容滚动 + +--- + +## 5. 信息披露层次总表 + +| 信息类型 | Inspector | 语音页 | 后台服务页 | 设备信息页 | +|---------|-----------|--------|-----------|-----------| +| 语音预设名称（当前值） | ✓ 只读 | ✓ 可编辑 | — | — | +| 语音权限状态 badge | ✓ 摘要 | ✓ 详细 + 操作 | — | — | +| 语音路由详情 | — | ✓ | — | — | +| 语音预设选择器 | — | ✓ | — | — | +| 按键快捷键绑定 | ✓ 可编辑 | — | — | — | +| 宏编辑器 | ✓ inline 展开 | — | — | — | +| 按键描述 | ✓ 可编辑 | — | — | — | +| OLED 素材选择 | ✓ | — | — | — | +| OLED 帧率 | ✓ | — | — | — | +| 灯效映射摘要 | ✓ 只读 | — | — | — | +| 灯效预览操作 | ✓ | — | — | — | +| 拨杆当前档位 | ✓ 只读 | — | — | — | +| 拨杆语义说明 | ✓ | — | — | — | +| 后台服务安装/运行状态 | — | — | ✓ | — | +| Hook 安装状态 | — | — | ✓ | — | +| 控制权切换操作 | — | — | ✓ | — | +| BLE 连接状态 | — | — | — | ✓ | +| 固件版本 | — | — | — | ✓ | +| BLE 诊断日志 | — | — | — | ✓ | + +--- + +## 6. 与现有代码的映射 + +### 6.1 需要修改的行为 + +以下修改只涉及 `Views/` 层，不改 BLE / 后台服务层： + +**`oledInspector`（AhaKeyStudioView.swift）** +- 上传完成后追加 `saveConfig(0x04)` +- 按钮文案从"上传到设备"改为"上传并保存" +- 上传成功后清零 OLED 相关的 dirtyCount + +**`keyInspector`（Key 1 分支）** +- 移除 VoicePresetPicker +- 移除权限引导 badge 详情（保留一个汇总 badge） +- 移除 VoiceRelayService 状态展示 +- 移除 NativeSpeechTranscriptionService 状态展示 +- 添加"→ 语音设置"跳转链接 + +**`switchInspector`** +- 移除 isInstalled / isRunning / hooksInstalled badge +- 移除 inline 安装/启动按钮 +- 移除控制权切换操作 +- 保留当前档位只读显示 + 语义说明 +- 添加"→ 后台服务"跳转链接 +- 全文不出现"Agent" + +**Inspector 空态** +- `selectedPart` 为 nil 时，隐藏 Inspector 区域（不显示占位内容） +- 点击热区后 Inspector 从右侧滑入 + +### 6.2 不改的层 + +- `BLE/AhaKeyBLEManager.swift` +- `BLE/AhaKeyProtocol.swift` +- `Agent/` 目录下所有文件 +- `Utilities/AgentManager.swift` +- `Utilities/VoiceRelayService.swift` +- `Utilities/NativeSpeechTranscriptionService.swift` + +--- + +## 7. 验收标准 + +1. 另一个工程师读完后能直接知道每个 Inspector 里有什么、没有什么 +2. 每个"移出 Inspector"的内容都有明确的目标页面 +3. 拨杆 Inspector 全文不出现"Agent"一词 +4. OLED 上传流程的 saveConfig 修复方案有明确的实现指引 +5. 信息披露层次总表覆盖所有当前 Inspector 中存在的内容类型 +6. 语音预设选择器的归属（语音页）与 Key 1 Inspector 的只读摘要之间的关系清晰 diff --git a/platforms/macos/client/docs/redesign/logi-options-plus-reference-spec/captures/00-capture-index.md b/platforms/macos/client/docs/redesign/logi-options-plus-reference-spec/captures/00-capture-index.md new file mode 100644 index 0000000..e3a747c --- /dev/null +++ b/platforms/macos/client/docs/redesign/logi-options-plus-reference-spec/captures/00-capture-index.md @@ -0,0 +1,106 @@ +# Capture Index + +更新时间：2026-05-03 +状态：capture 落库方案已建结构，待填充实际素材 + +--- + +## 1. 文档目的 + +本文档是 `captures/` 目录的工作索引，用于回答： + +- capture 资产现在分为哪些页面 +- 哪些组件已经进入跟踪区 +- 哪些只是预留目录 +- 首批试运行样本有哪些 + +--- + +## 2. 目录角色 + +### `tracked/` + +进 git，保留： + +- 精选默认态图 +- 标注图 +- 状态矩阵拼图 +- 组件说明 +- 页面 manifest + +### `raw-local/` + +不进 git，保留： + +- 原始整页截图 +- 临时裁片 +- 重复版本 +- 实验图 + +--- + +## 3. 页面分组 + +| 页面 | tracked | raw-local | 说明 | +|------|---------|-----------|------| +| `home` | 已建 | 已建 | 首页设备总览相关 capture | +| `device-studio` | 已建 | 已建 | 设备工作区相关 capture | +| `settings` | 已建 | 已建 | Settings 相关 capture | +| `agent` | 已建 | 已建 | 后台服务页相关 capture | +| `voice` | 已建 | 已建 | 语音页相关 capture | + +--- + +## 4. 首批试运行组件 + +### home + +- `hero` +- `topbar` +- `quick-actions` + +### device-studio + +- `platform-switcher` +- `sidebar` +- `canvas-hotspot` +- `inspector` +- `sync-banner` +- `status-pills` + +### settings + +- `nav` +- `form-group` + +### agent + +- `status-card` + +### voice + +- `permission-card` + +--- + +## 5. 当前推荐工作顺序 + +1. `home/hero` +2. `device-studio/platform-switcher` +3. `device-studio/inspector` + +完成这三项后，再决定是否扩展到其余组件。 + +--- + +## 6. 单组件最低交付物 + +一个组件进入 `tracked/` 的最低标准是： + +1. `*-default.png` +2. `*-annotated.png` +3. `*-states-contact-sheet.png` +4. `*-notes.md` +5. 对应页面 `00-page-manifest.yaml` 已记录 + +若只存在原始图或临时裁片，则应停留在 `raw-local/`，不进入 git。 diff --git a/platforms/macos/client/docs/redesign/logi-options-plus-reference-spec/captures/README.md b/platforms/macos/client/docs/redesign/logi-options-plus-reference-spec/captures/README.md new file mode 100644 index 0000000..7468752 --- /dev/null +++ b/platforms/macos/client/docs/redesign/logi-options-plus-reference-spec/captures/README.md @@ -0,0 +1,133 @@ +# Captures + +本目录用于存放 Logi Options+ 的内部参考 capture 资料。 + +它不是正式产品资源目录，而是专题 spec 的配套分析资产目录。 + +--- + +## 1. 目录目标 + +本目录承载两类内容： + +1. **可跟随源码保留的精选 capture** +2. **只保留在本地、不进入 git 的原始截图与临时素材** + +本目录只服务于以下用途： + +- 页面结构分析 +- 原组件视觉拆解 +- 状态矩阵对照 +- AhaKey 映射讨论 + +不服务于： + +- 正式产品资源打包 +- 营销素材管理 +- 运行时静态资源引用 + +--- + +## 2. 目录结构 + +```text +captures/ +├── README.md +├── 00-capture-index.md +├── tracked/ +│ ├── home/ +│ ├── device-studio/ +│ ├── settings/ +│ ├── agent/ +│ └── voice/ +└── raw-local/ + ├── home/ + ├── device-studio/ + ├── settings/ + ├── agent/ + └── voice/ +``` + +规则： + +- `tracked/`：进 git，只放精选导出图、标注图、状态矩阵拼图、说明与 manifest +- `raw-local/`：不进 git，放原始整页截图、临时裁片、重复版本、实验图 + +--- + +## 3. 组织方式 + +一级目录按页面： + +- `home` +- `device-studio` +- `settings` +- `agent` +- `voice` + +二级目录按组件。 + +每个组件目录只跟踪以下 4 类主文件： + +- `*-default.png` +- `*-annotated.png` +- `*-states-contact-sheet.png` +- `*-notes.md` + +如果某个组件状态非常多，允许额外拆多个 contact sheet，但文件名前缀必须一致。 + +--- + +## 4. 命名规则 + +### 4.1 tracked 精选文件 + +- 全小写 +- kebab-case +- 不带日期 + +示例： + +- `hero-default.png` +- `hero-annotated.png` +- `hero-states-contact-sheet.png` +- `hero-notes.md` + +### 4.2 raw-local 原始文件 + +- 文件名必须带日期 +- 可以带状态、倍率、批次等局部说明 + +示例： + +- `2026-05-03-home-hero-default@2x.png` +- `2026-05-03-platform-switcher-hover@2x.png` +- `2026-05-03-inspector-selected-pass-02.png` + +--- + +## 5. 使用规则 + +1. 仅作为内部分析素材使用。 +2. 不将 Logitech 原始品牌资源纳入正式产品资源链。 +3. 原始大图默认先进入 `raw-local/`，筛选后再生成 `tracked/` 内容。 +4. 每个页面必须有 `00-page-manifest.yaml` 记录覆盖情况。 +5. 每个已跟踪组件必须有 `*-notes.md` 说明职责、状态、映射建议和 capture 缺口。 + +--- + +## 6. 首批试运行样本 + +当前首批建议优先落这 3 个组件： + +- `home/hero` +- `device-studio/platform-switcher` +- `device-studio/inspector` + +这 3 个样本足以验证： + +- 页面 -> 组件 的组织方式 +- 完整状态矩阵是否可操作 +- manifest 是否足够表达覆盖率 + +具体索引见 [00-capture-index.md](./00-capture-index.md)。 diff --git a/platforms/macos/client/docs/redesign/logi-options-plus-reference-spec/captures/tracked/agent/00-page-manifest.yaml b/platforms/macos/client/docs/redesign/logi-options-plus-reference-spec/captures/tracked/agent/00-page-manifest.yaml new file mode 100644 index 0000000..2c7ea03 --- /dev/null +++ b/platforms/macos/client/docs/redesign/logi-options-plus-reference-spec/captures/tracked/agent/00-page-manifest.yaml @@ -0,0 +1,16 @@ +page_id: agent +source_app: Logi Options+ +source_version: 2.3.879545 +capture_date: 2026-05-03 +owner: ethan +capture_policy: + tracked_assets_only: true + raw_local_ignored_by_git: true +components: + - component_id: status-card + source_screen: agent + states_expected: [default, active, disabled, success, error] + states_captured: [] + tracked_files: [] + raw_local_prefix: 2026-05-03-agent-status-card + notes_file: status-card/status-card-notes.md diff --git a/platforms/macos/client/docs/redesign/logi-options-plus-reference-spec/captures/tracked/agent/status-card/status-card-notes.md b/platforms/macos/client/docs/redesign/logi-options-plus-reference-spec/captures/tracked/agent/status-card/status-card-notes.md new file mode 100644 index 0000000..19e7daa --- /dev/null +++ b/platforms/macos/client/docs/redesign/logi-options-plus-reference-spec/captures/tracked/agent/status-card/status-card-notes.md @@ -0,0 +1,38 @@ +# Status Card Notes + +## 组件职责 + +后台服务页的核心状态卡。 + +## 视觉结构拆解 + +- 状态标题 +- 当前结果 +- 主要动作 +- 辅助说明 + +## 状态变化规律 + +目标状态集合： + +- `default` +- `active` +- `disabled` +- `success` +- `error` + +已捕获状态： + +- 暂无，待采集 + +## 与 AhaKey 的映射建议 + +- 对应后台服务安装、运行、连接状态摘要 + +## 明确不照搬的内容 + +- Logitech 生态相关业务字段 + +## Capture 缺口 + +- 缺成功 / 错误对照样本 diff --git a/platforms/macos/client/docs/redesign/logi-options-plus-reference-spec/captures/tracked/device-studio/00-page-manifest.yaml b/platforms/macos/client/docs/redesign/logi-options-plus-reference-spec/captures/tracked/device-studio/00-page-manifest.yaml new file mode 100644 index 0000000..c5a1e59 --- /dev/null +++ b/platforms/macos/client/docs/redesign/logi-options-plus-reference-spec/captures/tracked/device-studio/00-page-manifest.yaml @@ -0,0 +1,51 @@ +page_id: device-studio +source_app: Logi Options+ +source_version: 2.3.879545 +capture_date: 2026-05-03 +owner: ethan +capture_policy: + tracked_assets_only: true + raw_local_ignored_by_git: true +components: + - component_id: platform-switcher + source_screen: device-detail + states_expected: [default, hover, pressed, selected, disabled] + states_captured: [] + tracked_files: [] + raw_local_prefix: 2026-05-03-platform-switcher + notes_file: platform-switcher/platform-switcher-notes.md + - component_id: sidebar + source_screen: device-detail + states_expected: [default, hover, selected, disabled] + states_captured: [] + tracked_files: [] + raw_local_prefix: 2026-05-03-sidebar + notes_file: sidebar/sidebar-notes.md + - component_id: canvas-hotspot + source_screen: device-detail + states_expected: [default, hover, selected, focused, disabled] + states_captured: [] + tracked_files: [] + raw_local_prefix: 2026-05-03-canvas-hotspot + notes_file: canvas-hotspot/canvas-hotspot-notes.md + - component_id: inspector + source_screen: device-detail + states_expected: [default, active, selected, disabled, error] + states_captured: [] + tracked_files: [] + raw_local_prefix: 2026-05-03-inspector + notes_file: inspector/inspector-notes.md + - component_id: sync-banner + source_screen: device-detail + states_expected: [default, dirty, syncing, success, error] + states_captured: [] + tracked_files: [] + raw_local_prefix: 2026-05-03-sync-banner + notes_file: sync-banner/sync-banner-notes.md + - component_id: status-pills + source_screen: device-detail + states_expected: [default, active, selected, disabled, syncing, success, error] + states_captured: [] + tracked_files: [] + raw_local_prefix: 2026-05-03-status-pills + notes_file: status-pills/status-pills-notes.md diff --git a/platforms/macos/client/docs/redesign/logi-options-plus-reference-spec/captures/tracked/device-studio/canvas-hotspot/canvas-hotspot-notes.md b/platforms/macos/client/docs/redesign/logi-options-plus-reference-spec/captures/tracked/device-studio/canvas-hotspot/canvas-hotspot-notes.md new file mode 100644 index 0000000..2e16e8c --- /dev/null +++ b/platforms/macos/client/docs/redesign/logi-options-plus-reference-spec/captures/tracked/device-studio/canvas-hotspot/canvas-hotspot-notes.md @@ -0,0 +1,39 @@ +# Canvas Hotspot Notes + +## 组件职责 + +工作区中央设备画布上的可交互热区。 + +## 视觉结构拆解 + +- 热区边界 +- 选中高亮 +- hover 反馈 +- 焦点与禁用表达 + +## 状态变化规律 + +目标状态集合： + +- `default` +- `hover` +- `selected` +- `focused` +- `disabled` + +已捕获状态： + +- 暂无，待采集 + +## 与 AhaKey 的映射建议 + +- 对应当前 `AhaKeyKeyboardCanvasView` 中的热区交互 + +## 明确不照搬的内容 + +- Logitech 设备外形 +- Logitech 功能标签 + +## Capture 缺口 + +- 缺热区 hover / selected / focused 样本 diff --git a/platforms/macos/client/docs/redesign/logi-options-plus-reference-spec/captures/tracked/device-studio/inspector/inspector-notes.md b/platforms/macos/client/docs/redesign/logi-options-plus-reference-spec/captures/tracked/device-studio/inspector/inspector-notes.md new file mode 100644 index 0000000..911c1d0 --- /dev/null +++ b/platforms/macos/client/docs/redesign/logi-options-plus-reference-spec/captures/tracked/device-studio/inspector/inspector-notes.md @@ -0,0 +1,42 @@ +# Inspector Notes + +## 组件职责 + +设备工作区右侧属性面板。 + +## 视觉结构拆解 + +- 标题区 +- 主配置区 +- 辅助说明 +- 高级区 +- 状态提示区 + +## 状态变化规律 + +目标状态集合： + +- `default` +- `active` +- `selected` +- `disabled` +- `error` + +已捕获状态： + +- 暂无，待采集 + +## 与 AhaKey 的映射建议 + +- 对应工作区的 `StudioInspector` +- 重点借鉴结构化布局与密度，不继续把跨硬件功能塞进去 + +## 明确不照搬的内容 + +- Logitech 专有字段 +- Logitech 业务流程 + +## Capture 缺口 + +- 缺默认态、选中态、错误态样本 +- 缺字段组间距与状态提示样本 diff --git a/platforms/macos/client/docs/redesign/logi-options-plus-reference-spec/captures/tracked/device-studio/platform-switcher/platform-switcher-notes.md b/platforms/macos/client/docs/redesign/logi-options-plus-reference-spec/captures/tracked/device-studio/platform-switcher/platform-switcher-notes.md new file mode 100644 index 0000000..9ce1bef --- /dev/null +++ b/platforms/macos/client/docs/redesign/logi-options-plus-reference-spec/captures/tracked/device-studio/platform-switcher/platform-switcher-notes.md @@ -0,0 +1,40 @@ +# Platform Switcher Notes + +## 组件职责 + +设备工作区高层上下文切换器，对应不同平台 / 应用上下文。 + +## 视觉结构拆解 + +- 图标 / 标签区 +- 当前选中指示 +- 未选中项弱化方式 + +## 状态变化规律 + +目标状态集合： + +- `default` +- `hover` +- `pressed` +- `selected` +- `disabled` + +已捕获状态： + +- 暂无，待采集 + +## 与 AhaKey 的映射建议 + +- 对应 `Claude Code / Cursor / Codex` 平台切换器 +- 重点参考它作为“上下文切换器”而非传统 segmented control 的语气 + +## 明确不照搬的内容 + +- Logitech 应用图标 +- Logitech 应用列表语义 + +## Capture 缺口 + +- 缺默认态、hover、selected 对照 +- 缺禁用 / 不可切换样本 diff --git a/platforms/macos/client/docs/redesign/logi-options-plus-reference-spec/captures/tracked/device-studio/sidebar/sidebar-notes.md b/platforms/macos/client/docs/redesign/logi-options-plus-reference-spec/captures/tracked/device-studio/sidebar/sidebar-notes.md new file mode 100644 index 0000000..b90328b --- /dev/null +++ b/platforms/macos/client/docs/redesign/logi-options-plus-reference-spec/captures/tracked/device-studio/sidebar/sidebar-notes.md @@ -0,0 +1,37 @@ +# Sidebar Notes + +## 组件职责 + +设备工作区左侧导航区。 + +## 视觉结构拆解 + +- 导航分组 +- 当前项高亮 +- 分隔线与底部状态区 + +## 状态变化规律 + +目标状态集合： + +- `default` +- `hover` +- `selected` +- `disabled` + +已捕获状态： + +- 暂无，待采集 + +## 与 AhaKey 的映射建议 + +- 对应 `按键 / OLED / 灯条 / 拨杆 / 后台服务 / 语音 / 设备信息` + +## 明确不照搬的内容 + +- Logitech 专属导航文案 + +## Capture 缺口 + +- 缺整组默认态 +- 缺选中项与 hover 项差异样本 diff --git a/platforms/macos/client/docs/redesign/logi-options-plus-reference-spec/captures/tracked/device-studio/status-pills/status-pills-notes.md b/platforms/macos/client/docs/redesign/logi-options-plus-reference-spec/captures/tracked/device-studio/status-pills/status-pills-notes.md new file mode 100644 index 0000000..984d2a3 --- /dev/null +++ b/platforms/macos/client/docs/redesign/logi-options-plus-reference-spec/captures/tracked/device-studio/status-pills/status-pills-notes.md @@ -0,0 +1,39 @@ +# Status Pills Notes + +## 组件职责 + +轻量状态 pill，用于连接、运行中、配置中、同步结果等简短状态。 + +## 视觉结构拆解 + +- 胶囊形容器 +- 图标 / 文案 +- 不同状态色与强调度 + +## 状态变化规律 + +目标状态集合： + +- `default` +- `active` +- `selected` +- `disabled` +- `syncing` +- `success` +- `error` + +已捕获状态： + +- 暂无，待采集 + +## 与 AhaKey 的映射建议 + +- 服务于首页和工作区的轻量状态表达 + +## 明确不照搬的内容 + +- Logitech 文案与图标 + +## Capture 缺口 + +- 缺多状态对照样本 diff --git a/platforms/macos/client/docs/redesign/logi-options-plus-reference-spec/captures/tracked/device-studio/sync-banner/sync-banner-notes.md b/platforms/macos/client/docs/redesign/logi-options-plus-reference-spec/captures/tracked/device-studio/sync-banner/sync-banner-notes.md new file mode 100644 index 0000000..f7e6447 --- /dev/null +++ b/platforms/macos/client/docs/redesign/logi-options-plus-reference-spec/captures/tracked/device-studio/sync-banner/sync-banner-notes.md @@ -0,0 +1,37 @@ +# Sync Banner Notes + +## 组件职责 + +工作区内同步与脏状态提示条。 + +## 视觉结构拆解 + +- 提示文案 +- 状态色 +- 次动作 + +## 状态变化规律 + +目标状态集合： + +- `default` +- `dirty` +- `syncing` +- `success` +- `error` + +已捕获状态： + +- 暂无，待采集 + +## 与 AhaKey 的映射建议 + +- 直接服务于 AhaKey 特有的草稿 / 同步状态机 + +## 明确不照搬的内容 + +- Logitech 不具备的状态语义不强行套用 + +## Capture 缺口 + +- 缺完整状态样本 diff --git a/platforms/macos/client/docs/redesign/logi-options-plus-reference-spec/captures/tracked/home/00-page-manifest.yaml b/platforms/macos/client/docs/redesign/logi-options-plus-reference-spec/captures/tracked/home/00-page-manifest.yaml new file mode 100644 index 0000000..6889b9b --- /dev/null +++ b/platforms/macos/client/docs/redesign/logi-options-plus-reference-spec/captures/tracked/home/00-page-manifest.yaml @@ -0,0 +1,33 @@ +page_id: home +source_app: Logi Options+ +source_version: 2.3.879545 +capture_date: 2026-05-03 +owner: ethan +capture_policy: + tracked_assets_only: true + raw_local_ignored_by_git: true +components: + - component_id: hero + source_screen: home-overview + states_expected: [default, hover, selected, disabled] + states_captured: [default] + tracked_files: + - hero/hero-default.png + - hero/hero-annotated.png + - hero/hero-states-contact-sheet.png + raw_local_prefix: 2026-05-03-home-hero + notes_file: hero/hero-notes.md + - component_id: topbar + source_screen: home-overview + states_expected: [default, hover, pressed] + states_captured: [] + tracked_files: [] + raw_local_prefix: 2026-05-03-home-topbar + notes_file: topbar/topbar-notes.md + - component_id: quick-actions + source_screen: home-overview + states_expected: [default, hover, pressed, active, disabled] + states_captured: [] + tracked_files: [] + raw_local_prefix: 2026-05-03-home-quick-actions + notes_file: quick-actions/quick-actions-notes.md diff --git a/platforms/macos/client/docs/redesign/logi-options-plus-reference-spec/captures/tracked/home/hero/hero-annotated.png b/platforms/macos/client/docs/redesign/logi-options-plus-reference-spec/captures/tracked/home/hero/hero-annotated.png new file mode 100644 index 0000000..eeab7b3 Binary files /dev/null and b/platforms/macos/client/docs/redesign/logi-options-plus-reference-spec/captures/tracked/home/hero/hero-annotated.png differ diff --git a/platforms/macos/client/docs/redesign/logi-options-plus-reference-spec/captures/tracked/home/hero/hero-default.png b/platforms/macos/client/docs/redesign/logi-options-plus-reference-spec/captures/tracked/home/hero/hero-default.png new file mode 100644 index 0000000..f69174f Binary files /dev/null and b/platforms/macos/client/docs/redesign/logi-options-plus-reference-spec/captures/tracked/home/hero/hero-default.png differ diff --git a/platforms/macos/client/docs/redesign/logi-options-plus-reference-spec/captures/tracked/home/hero/hero-notes.md b/platforms/macos/client/docs/redesign/logi-options-plus-reference-spec/captures/tracked/home/hero/hero-notes.md new file mode 100644 index 0000000..c768663 --- /dev/null +++ b/platforms/macos/client/docs/redesign/logi-options-plus-reference-spec/captures/tracked/home/hero/hero-notes.md @@ -0,0 +1,50 @@ +# Hero Notes + +## 组件职责 + +首页设备 hero，承载设备身份、主视觉、连接状态与进入工作区入口。 + +## 视觉结构拆解 + +- 中央空态插图：键盘、鼠标、收纳盒、蓝牙图标、接收器图标。 +- 主 CTA：插图下方的 `连接设备`。 +- 周边留白：hero 在页面中央，左侧问候语和右上操作区保持远离。 +- 标注图中蓝框标出空态插图主体，橙框标出连接设备入口。 + +## 状态变化规律 + +目标状态集合： + +- `default` +- `hover` +- `selected` +- `disabled` + +已捕获状态： + +- `default`：来自 `raw-local/home/2026-05-03-home-window-empty-state@2x.png` + +## 与 AhaKey 的映射建议 + +- 对应 [03-home-overview-spec.md](../../03-home-overview-spec.md) 的设备 hero +- 重点借鉴布局、层级、状态摘要位置 +- AhaKey 可把 Logi 的空态插图语义改写为 AhaKey 键盘 hero；未连接时保留中央设备视觉和低权重 CTA。 + +## 明确不照搬的内容 + +- Logitech 品牌元素 +- Logitech 设备渲染 +- Logitech 专有文案 + +## Capture 缺口 + +- 缺 hover / selected 差异样本 +- 缺 CTA 交互状态 +- 缺已连接设备 hero 样本 +- 缺多设备 hero 样本 + +## 当前来源比例 + +- 真实视觉截图：本组件默认态与标注图来自截图。 +- React / CSS / Electron 包：用于确认来源 app、版本、资源存在性，不用于本组件几何标注。 +- macOS 窗口信息：用于确认截取窗口标题、坐标和尺寸。 diff --git a/platforms/macos/client/docs/redesign/logi-options-plus-reference-spec/captures/tracked/home/hero/hero-states-contact-sheet.png b/platforms/macos/client/docs/redesign/logi-options-plus-reference-spec/captures/tracked/home/hero/hero-states-contact-sheet.png new file mode 100644 index 0000000..8d900f4 Binary files /dev/null and b/platforms/macos/client/docs/redesign/logi-options-plus-reference-spec/captures/tracked/home/hero/hero-states-contact-sheet.png differ diff --git a/platforms/macos/client/docs/redesign/logi-options-plus-reference-spec/captures/tracked/home/quick-actions/quick-actions-notes.md b/platforms/macos/client/docs/redesign/logi-options-plus-reference-spec/captures/tracked/home/quick-actions/quick-actions-notes.md new file mode 100644 index 0000000..e5c6b51 --- /dev/null +++ b/platforms/macos/client/docs/redesign/logi-options-plus-reference-spec/captures/tracked/home/quick-actions/quick-actions-notes.md @@ -0,0 +1,39 @@ +# Quick Actions Notes + +## 组件职责 + +首页或顶栏中的快捷操作入口及其展开内容。 + +## 视觉结构拆解 + +- 触发按钮 +- popover 面板 +- 面板条目层级 + +## 状态变化规律 + +目标状态集合： + +- `default` +- `hover` +- `pressed` +- `active` +- `disabled` + +已捕获状态： + +- 暂无，待采集 + +## 与 AhaKey 的映射建议 + +- 对应 AhaKey 的 `快捷操作` +- 重点参考 popover 气质与操作密度 + +## 明确不照搬的内容 + +- Flow / Smart Actions 专有能力 + +## Capture 缺口 + +- 缺触发按钮状态 +- 缺弹出层展开态 diff --git a/platforms/macos/client/docs/redesign/logi-options-plus-reference-spec/captures/tracked/home/topbar/topbar-notes.md b/platforms/macos/client/docs/redesign/logi-options-plus-reference-spec/captures/tracked/home/topbar/topbar-notes.md new file mode 100644 index 0000000..68fd33d --- /dev/null +++ b/platforms/macos/client/docs/redesign/logi-options-plus-reference-spec/captures/tracked/home/topbar/topbar-notes.md @@ -0,0 +1,38 @@ +# Topbar Notes + +## 组件职责 + +首页顶部品牌区与右侧操作区。 + +## 视觉结构拆解 + +- 品牌区 +- 右侧工具入口 +- 留白与对齐节奏 + +## 状态变化规律 + +目标状态集合： + +- `default` +- `hover` +- `pressed` + +已捕获状态： + +- 暂无，待采集 + +## 与 AhaKey 的映射建议 + +- 对应首页顶栏 +- 借鉴密度、对齐、工具入口权重 + +## 明确不照搬的内容 + +- Logitech 文案 +- Logitech 品牌图标 + +## Capture 缺口 + +- 缺默认态顶栏 +- 缺右侧按钮 hover / pressed 样本 diff --git a/platforms/macos/client/docs/redesign/logi-options-plus-reference-spec/captures/tracked/settings/00-page-manifest.yaml b/platforms/macos/client/docs/redesign/logi-options-plus-reference-spec/captures/tracked/settings/00-page-manifest.yaml new file mode 100644 index 0000000..c80c463 --- /dev/null +++ b/platforms/macos/client/docs/redesign/logi-options-plus-reference-spec/captures/tracked/settings/00-page-manifest.yaml @@ -0,0 +1,23 @@ +page_id: settings +source_app: Logi Options+ +source_version: 2.3.879545 +capture_date: 2026-05-03 +owner: ethan +capture_policy: + tracked_assets_only: true + raw_local_ignored_by_git: true +components: + - component_id: nav + source_screen: settings + states_expected: [default, hover, selected, disabled] + states_captured: [] + tracked_files: [] + raw_local_prefix: 2026-05-03-settings-nav + notes_file: nav/nav-notes.md + - component_id: form-group + source_screen: settings + states_expected: [default, focused, disabled, error] + states_captured: [] + tracked_files: [] + raw_local_prefix: 2026-05-03-settings-form-group + notes_file: form-group/form-group-notes.md diff --git a/platforms/macos/client/docs/redesign/logi-options-plus-reference-spec/captures/tracked/settings/form-group/form-group-notes.md b/platforms/macos/client/docs/redesign/logi-options-plus-reference-spec/captures/tracked/settings/form-group/form-group-notes.md new file mode 100644 index 0000000..57c1079 --- /dev/null +++ b/platforms/macos/client/docs/redesign/logi-options-plus-reference-spec/captures/tracked/settings/form-group/form-group-notes.md @@ -0,0 +1,37 @@ +# Form Group Notes + +## 组件职责 + +Settings 中的单个设置分组与表单块。 + +## 视觉结构拆解 + +- 分组标题 +- 表单项 +- 分隔线 +- 说明文案 + +## 状态变化规律 + +目标状态集合： + +- `default` +- `focused` +- `disabled` +- `error` + +已捕获状态： + +- 暂无，待采集 + +## 与 AhaKey 的映射建议 + +- 用于未来 Settings 表单系统 + +## 明确不照搬的内容 + +- Logitech 专有设置项 + +## Capture 缺口 + +- 缺默认态与聚焦态样本 diff --git a/platforms/macos/client/docs/redesign/logi-options-plus-reference-spec/captures/tracked/settings/nav/nav-notes.md b/platforms/macos/client/docs/redesign/logi-options-plus-reference-spec/captures/tracked/settings/nav/nav-notes.md new file mode 100644 index 0000000..f6780b3 --- /dev/null +++ b/platforms/macos/client/docs/redesign/logi-options-plus-reference-spec/captures/tracked/settings/nav/nav-notes.md @@ -0,0 +1,36 @@ +# Settings Nav Notes + +## 组件职责 + +Settings 内导航区或分组切换区。 + +## 视觉结构拆解 + +- 导航项 +- 分组层级 +- 当前项高亮 + +## 状态变化规律 + +目标状态集合： + +- `default` +- `hover` +- `selected` +- `disabled` + +已捕获状态： + +- 暂无，待采集 + +## 与 AhaKey 的映射建议 + +- 对应未来 `通用 / 设备 / 后台服务与 Hook / 语音 / 通知 / 高级` + +## 明确不照搬的内容 + +- Logitech 设置分组名称 + +## Capture 缺口 + +- 缺导航区整态样本 diff --git a/platforms/macos/client/docs/redesign/logi-options-plus-reference-spec/captures/tracked/voice/00-page-manifest.yaml b/platforms/macos/client/docs/redesign/logi-options-plus-reference-spec/captures/tracked/voice/00-page-manifest.yaml new file mode 100644 index 0000000..82711c2 --- /dev/null +++ b/platforms/macos/client/docs/redesign/logi-options-plus-reference-spec/captures/tracked/voice/00-page-manifest.yaml @@ -0,0 +1,16 @@ +page_id: voice +source_app: Logi Options+ +source_version: 2.3.879545 +capture_date: 2026-05-03 +owner: ethan +capture_policy: + tracked_assets_only: true + raw_local_ignored_by_git: true +components: + - component_id: permission-card + source_screen: voice + states_expected: [default, active, disabled, success, error] + states_captured: [] + tracked_files: [] + raw_local_prefix: 2026-05-03-voice-permission-card + notes_file: permission-card/permission-card-notes.md diff --git a/platforms/macos/client/docs/redesign/logi-options-plus-reference-spec/captures/tracked/voice/permission-card/permission-card-notes.md b/platforms/macos/client/docs/redesign/logi-options-plus-reference-spec/captures/tracked/voice/permission-card/permission-card-notes.md new file mode 100644 index 0000000..d65f84b --- /dev/null +++ b/platforms/macos/client/docs/redesign/logi-options-plus-reference-spec/captures/tracked/voice/permission-card/permission-card-notes.md @@ -0,0 +1,38 @@ +# Permission Card Notes + +## 组件职责 + +语音页中的权限状态卡或引导卡。 + +## 视觉结构拆解 + +- 权限名称 +- 当前状态 +- 下一步动作 +- 辅助说明 + +## 状态变化规律 + +目标状态集合： + +- `default` +- `active` +- `disabled` +- `success` +- `error` + +已捕获状态： + +- 暂无，待采集 + +## 与 AhaKey 的映射建议 + +- 用于输入监控、辅助功能、麦克风、语音识别等权限表达 + +## 明确不照搬的内容 + +- Logitech 不相关的权限语义 + +## Capture 缺口 + +- 缺缺权限 / 已授权 / 错误态样本