Skip to content

design-qa.md

Latest commit

 

History

History
263 lines (193 loc) · 38.4 KB

design-qa.md

File metadata and controls

263 lines (193 loc) · 38.4 KB
Raw

Design QA：macOS 14 兼容与 macOS 26 Liquid Glass 设置页

English

本文是 macOS 界面设计与生产窗口验收的中文权威规范。英文文件仅为同步翻译，不独立产生规则；下方带日期的 QA 内容是历史验证证据，不得覆盖“审查范围”“当前实现”和“交互、布局与字体硬性规范”。

产品命名与宣传文案

使用场景 统一写法
英文产品名 SayAll
英文宣传文案中的产品称呼 SayAll App
中文产品名 无线麦 SayAll
中文宣传文案中的产品称呼 无线麦 SayAll App
  • 英文产品名不得写为 Remote Mic、Wireless Mic 或 SayAll Wireless Mic。
  • 中文名称保留半角空格；不得使用“无线麦SayAll.app”“无线麦 SayAll.app”或单独“无线麦”作为当前产品名。
  • 页面、按钮、错误、权限说明、辅助功能标签、帮助和版本说明均遵守本规则。宣传标题、功能介绍和推广入口使用宣传称呼。
  • 仅调整面向用户的文字，不据此修改布局、业务逻辑、文件名、路径、Bundle ID、协议、数据键或历史兼容标识。
  • 安装迁移说明引用真实旧文件名时保留原值；硬件麦克风的普通描述不作为产品名称。

审查范围

  • 设置窗口：默认及最小尺寸 1020×772，可自由缩放；
  • 首次使用 Onboarding：约 1020×772，不显示步骤编号、总数、百分比、“跳过”或“稍后继续”；
  • 页面：连接与语音、按键映射、统计、回眸、设置（含权限与隐私、通用、诊断与日志）；
  • 各页面顶部仅显示主标题，不显示重复说明页面内容的副标题；
  • 仓库截图：

截图与设计稿归档

  • 上方链接的仓库内截图属于历史资产，不再新增同类文件。新的生产截图和设计稿按 AGENTS.md 的截图与设计稿归档规范 使用 PR 附件或持久链接，仓库内只保留 manifest.json 索引。
  • 历史 QA 记录中的 Screenshots/... 路径只说明当时的证据上下文。路径移出仓库或缺失时，以索引中的格式、尺寸和 SHA-256 说明原件，不得据此推断当前实现。
  • 构建必需资源（App 图标、Onboarding 工具图、状态图标、字体）不受此限。

当前实现

  • 未完成当前流程版本时，主窗口使用 Typeless 式双栏 Onboarding：顶部仅显示“准备 › 设置 › 试一下”，当前每条控制来源路径九页，均在 1020 × 772 内一次完整展示、不使用内部滚动；控制来源改为单页，实体遥控器置于主区域，iPhone/Watch 与网页置于弱化的备用区域，并只显示当前 Package 实际支持的入口；左侧完成当前任务，右侧显示对应控制方式、实时检查或输入工具指引；音频页只平铺并接受 MiRemoteV 2ch 与 BlackHole 2ch，不使用下拉框；必要能力未通过时主按钮禁用，完成前根视图不显示设置页；
  • Onboarding 当前卡点在页面内只突出一个主要修复动作，诊断复制为同卡片中的次要操作；完成页环境变化时直接返回受影响阶段，不新增 Sheet、Popover 或连续确认弹窗；
  • 实体遥控器连接页在等待普通按键时必须直接写明“圆盘中间确定键或方向键”，并明确排除麦克风/语音键；检测到误按语音键时在原状态卡位置显示橙色纠正状态，不新增弹窗、不放宽普通按键门槛，并保留生产 HID 监听状态；
  • 输入工具页左侧只显示固定排序的工具卡和普通用户能理解的安装/运行状态，右侧对五个工具都显示四项匹配步骤；豆包、微信、Vokie 使用随浅色/深色切换的真实截图，Typeless 与其他工具使用简短说明，第 3 项统一显示“去除系统 Fn 占用”。缩略图固定 220pt 高，点击后打开覆盖整窗的放大层：遮罩、卡片和右上角关闭按钮为固定形态，点击遮罩或关闭按钮（含 Esc）退出，不改变页面状态；横版截图完整适配卡片，竖版长截图按接近原始宽度显示并在卡片内滚动。页面不显示快捷键配置来源、学习路径、Command/Option 选择或内部证据状态；本次 Onboarding staged 语音键固定为 Fn；
  • Onboarding 语音测试输入框页必须在同一张不可忽略的配置卡中同时显示无线麦发送语音键、SayAll 音频输出、第三方语音识别键和第三方麦克风；豆包额外显示“全局唤起语音”，Typeless 显示 Fn 点按语义，其他工具显示“需支持语音输入并自行配置麦克风”。第三方内部状态只能由用户逐项确认，不能伪装成自动检测；音频输出未就绪必须使用红色状态，切换工具或设备后确认自动失效，未确认不得继续；中文字号不低于 12pt。
  • 设置页使用窄侧栏、标题区和分层内容区，五个页面的主要操作在最小窗口下可访问；页面可以滚动但不显示滚动条；
  • 连接页右侧顶部显示“无线麦 SayAll 移动端”，移动端各行用相同的较小普通文字表达状态（按用户要求匹配小程序/Web 现有 caption）；非会员时各行右侧显示私有组件提供的“会员功能，点击开通”按钮，不重复展示会员限制说明，不显示“扫码优先”。
  • 连接页的音频区域只显示主要设备、增益、状态和刷新操作，不显示豆包兼容专用卡片、BlackHole 获取入口、测试音按钮或测试音状态。
  • Onboarding 完成后及后续普通启动默认选中当前可见侧边栏第一项；当前第一项为“按键”，侧边栏顺序调整时启动页随同一顺序源自动变化；
  • 侧栏选择态和按键选择态使用低透明度语义蓝交互玻璃；
  • 侧边栏底部个人中心使用 person.crop.circle 系统图标。除侧边栏和设置页品牌名 SayAll 使用 Oxanium SemiBold 600 外，使用系统字体、语义字号和系统颜色，跟随浅色、深色、降低透明度与增强对比度设置；
  • 窗口保留原生红黄绿按钮与逻辑标题，隐藏可见标题和标题栏分隔线，页面背景延伸到顶部；仅顶部专用空白区域可拖动窗口，页面内容、滑块和其他交互区域不会带动整个窗口移动，交互内容仍避开窗口按钮；
  • 个人中心复用遥控器设备卡的淡底色、10pt 圆角和细描边，分享与统计面板不使用玻璃；其他 macOS 26 面板和按钮使用原生 glassEffect 与 glass button style；macOS 14/15 使用系统 Material 与标准按钮，不使用自定义模糊实现；
  • 按键页面复用 Resources/RC003-remote-photo.png，保持 508×1030 原始比例；
  • 普通实体按键按下时会高亮遥控器示意图并定位映射行，语音键使用独立的语音活动状态；
  • 动作编辑区顶部显示“基础按键 / 系统与媒体 / 输入框 / 组合动作 / 常用语 / 打开 App”六个平级筛选按钮，只筛选动作候选；首次打开时展示全部平级分组，但不显示“全部”按钮。具体 APP 不折叠，打开自定义 APP 位于该组末尾；常用语的打开和调整入口使用与其他动作一致的按钮样式。目标 APP 的输入框聚焦与上下翻页滚动不折叠在“打开具体 APP”动作里，统一放到侧边栏独立的「APP 适配」页面按 APP 配置，按键编辑区只显示该 APP 的只读状态摘要与“去配置”入口；这两项只要该 APP 在前台就可用，与“打开具体 APP”动作无关。“打开具体 APP”动作组里只保留目标 APP 选择。筛选只改变候选列表，编辑另一个按键时恢复未筛选状态；
  • 界面未展示实物上不存在的独立静音键。
  • 普通界面使用产品语言，不显示遥控器型号代号、蓝牙语音协议名、按键协议名、十六进制按键编号或设备标识术语；
  • 遥控器设备卡只用标准电池图标和百分比表达电量；空电、低电、正常和满电使用不同电池符号与语义颜色，充电或外接电源时在图标上叠加闪电，不再额外显示“可充电电池”文字；
  • 统计页已改名为“个人中心 / Profile”：页头只显示页面标题，不显示“数据仅存本机”一类隐私说明；宽窗口顶部四项 KPI 必须保持单行，窄窗口允许自适应为两列，累计语音时长等 KPI 数值在小时级以上也必须完整显示，不得出现省略号；下方左侧为排行榜、右侧为最近半年日历热力图，移除柱状图与“少—多”图例；日历方格必须为正方形并使用语义蓝色；排行和日历日期支持进入“回眸”。历史设计稿 dist/designs/profile-v4/profile-v4-dark-refined.png 当前已不存在，不能继续作为唯一视觉基线；现行规则、生产截图和可审计 PR 证据共同作为验收依据；
  • “回眸”作为紧跟“统计”的独立侧边栏页面，页头标题右侧显示最多两行的本地隐私说明，保存开关固定在最右侧，页面底部不重复隐私卡；页面默认展示全部 App 的倒序时间线，顶部应用栏固定显示“全部应用”，其余 App 按最近使用排序并支持单行横向浏览或在页面内展开为自适应网格，图标无法解析时回退通用 App 图标；日期分组默认展开最新一天，并支持逐日展开或折叠；本地 Agent 访问区放在历史之后，使用页面内开关、文本框、复制按钮和授权列表完成配置，不使用下拉框、Popover 或 Sheet；关闭时仍可查看和撤销授权；功能说明和无描边“全部删除”位于页面最底部；
  • 网页连接入口直接打开会话页，不显示邀请码录入或校验弹窗；iOS 正式版推荐继续位于连接页，地址不直接显示，并提供打开页面和复制链接操作；
  • 设置页把当前版本、可更新版本、检查更新、更新内容与默认关闭的预发布更新开关放在同一区域，待更新版本 Release Notes 显示在其右侧；权限与隐私位于通用上方，诊断与日志同页展示；导出/导入配置同一行，登录自动启动/启动打开主窗口同一行；语言选项始终完整展示，不使用下拉框；官网和 GitHub 保持显眼，版本历史按钮、术语表与退出按钮不再显示；
  • 设置页“通用”区域使用页面内图标按钮选择 App 图标，只展示当前安装包真实包含的图标资源；选择立即更新 Dock、应用切换器和设置页品牌图标并持久保存，资源缺失时回退默认图标，不显示不可用占位选项；
  • 设置页使用确认设计稿的紧凑平铺分区，不在首屏展示品牌 Hero、反馈大卡或展开二维码；支持入口位于诊断之后；分享模块位于个人中心顶部、四项 KPI 之前，在页面内展开二维码，设置页和侧边栏不再显示独立分享入口；
  • 所有界面文案使用稳定语义 key；当前语言缺少 Markdown 帮助时回退英文。

已确认侧边栏设计

2026-10-29 用户确认第八版 HTML 设计稿，并要求据此开发。内容稿、原始 PNG 和摘要清单保存在同一目录；存档保留审核时原始字节，稿中“未开发”等状态只表示审核时点。

2026-10-31 按用户要求收窄侧边栏：宽度不再固定为 136pt，改为按当前语言下最宽的一行（含页头品牌区）测量，取值范围 104–136pt；文字到左缘和右缘的留白都保持 15pt，不再把多余空白堆在文字右侧。中英文都约 129pt（顶部品牌区最宽）；包含更长英文入口时按内容增长，最多到 136pt。

验证截图保存在 Screenshots/design-drafts/sidebar-width/（sidebar-width-zh-hans-dark.png、sidebar-width-zh-hans-light.png、sidebar-width-en-dark.png、sidebar-width-en-light.png），为 1020 × 772 窗口的 2 倍图 2040 × 1544。

  • 侧边栏宽度按内容测量，范围为 104–136pt。顶部品牌、导航项与底部账户入口均采用“图标在左、文字在右”。
  • 顶部 Logo 为 44 × 44pt，距窗口控制区下沿 16pt，图片框左边距 15pt。品牌文字在 Logo 右侧，水平间距 8pt。
  • 侧边栏 SayAll 使用 16pt Oxanium SemiBold 600。文字相对第五版下移 2pt；版本号使用 12pt 系统字体，并紧贴品牌文字下方。版本必须取自安装包。
  • 导航图标为 18pt，文字为 13pt 系统 Semibold。图标距侧边栏左缘 15pt，按可见轮廓与顶部 Logo 视觉左对齐；图文间距为 8pt，文字左对齐。
  • 导航项最小高度为 44pt。保留完整 Button Profiles，空间不足时按实际宽度换行，不改名为 Profiles。图标与整个多行文字块垂直居中；更多行时随内容增高，不缩小字体或裁切文字。
  • 底部账户入口使用 person.crop.circle。账户区最小高度为 56pt，沿用导航的图标列、文字列和居中规则。长用户名完整换行，不按每 8 个字符强制断行、不用省略号；更长内容使账户区增高。
  • 选中项保留低透明度强调色圆角底；设置更新圆点位于该行右侧，并为圆点预留文字空间。
  • 品牌与账户区保持固定，中间导航保留纵向滚动兜底。在生产最小窗口 1020 × 772 下检查全部已启用入口、中文/英文及浅色/深色；不能以隐藏入口或缩小中文字号换取无滚动。
  • 保留现有页面名称、顺序、显示条件、账号来源和功能行为。设计稿中的可选功能与虚构用户名只用于布局，不定义新的功能或真实账号状态；设置页品牌字体继续使用 Oxanium 600。

交互、布局与字体硬性规范

  • 二级页面顶部使用同一行的返回按钮与页面标题，返回按钮位于左侧、标题紧邻其右侧，两者垂直居中；返回按钮文案只用“返回”（英文为 Back），点击区域至少 72pt 宽、44pt 高，整个按钮区域均可点击。

  • 卡片形式、有背景或有边框的按钮，整个卡片或边框范围都必须响应点击，包括文字、图标及其周围的空白区域。点击这些区域必须执行同一按钮动作。卡片内独立的次要按钮只执行各自动作；禁用按钮不得响应点击。验收时逐项点击文字、图标、空白区域和边框内侧，不得只检查文字。按键页六个筛选在 800×650 压力尺寸下保持单行、无横向滚动和点击区域裁切；较长名称可尾部截断，辅助功能保留完整名称。

  • 普通用户可见页面必须使用产品语言，只说明当前状态、实际影响和可执行操作。不得显示“待真机验证”“需要兼容性验收”“待回归”“自动化/CI 已通过”“候选实现”“开发中”“验证中”等研发、测试或内部验收用语；未完成验收的能力应隐藏、不发布或不列为支持和推荐，已经公开但不可用时应改写为用户能理解的“暂不支持”“暂时无法使用”及下一步。技术原因码和验收状态只允许出现在脱敏日志、用户主动复制的诊断和内部文档中。

  • 用户悬停在开关、按钮或功能入口上时，可以通过系统帮助标签或同类悬停提示补充解释该功能。提示文案必须使用普通用户能够理解的产品语言，只说明用途、影响或使用方式，不得暴露技术术语、内部原理、协议、实现细节或调试信息。关键状态、错误、风险和完成任务所必需的操作说明仍须直接显示，不能只依赖悬停提示。

  • 界面默认只保留帮助用户判断和操作所必需的短文案；可由悬停提示承载的补充说明不应再以大段常驻文字重复展示。需要持续可见的说明应拆短、分层或放到最相关的控件附近，避免说明文字挤占主要操作空间。

  • 控件应尽量紧凑并按内容确定尺寸，避免没有必要的长条形组件，尤其避免横向铺满页面的按钮、开关容器、选择项和状态条。只有文本输入、进度、数据展示或布局确实需要连续宽度时才使用长条布局，并确保视觉层级清晰。

  • 设计必须统一考虑整体美观与视觉秩序：同层级元素的边缘或文字基线应对齐，同类控件的尺寸应一致，页面边距、分区间距、控件间距和内部留白应遵循统一节奏；不得出现无理由的尺寸、对齐或间距差异。

  • 中文界面文字的最终显示字号不得小于 12pt。不得使用 8～11pt 的中文文字，也不得通过 minimumScaleFactor 把中文缩小到 12pt 以下；空间不足时优先增加控件高度、调整布局、允许换行或对次要内容做尾部截断。

  • 尽量不使用下拉列表，尤其避免把基础按键、系统动作、自定义动作和具体 APP 混在同一个长列表中。选项较多时必须按语义分区，优先使用页面内按钮网格、分段选择或清晰的分组列表。

  • 主要任务和相关配置优先在页面内完成。高频主流程、当前对象、必需操作及关键状态必须持续可见；普通说明、进度和结果优先就地显示。

  • 短时选择、次要编辑和系统原生操作可以使用 Popover 或 Sheet。浮层必须可取消，支持键盘与辅助功能，保留当前上下文，并说明完成或取消后的返回位置；不得用连续浮层隐藏必需步骤或关键错误。

  • 文件选择、权限授权和不可恢复操作使用适合的系统交互。现有产品规范明确要求就地处理的具体流程仍按该规范执行。

代码对应位置

  • 窗口创建与最小尺寸：Sources/RemoteMic/RemoteMicApp.swift；
  • Onboarding 根视图、布局和门禁：Sources/RemoteMic/RemoteMicRootView.swift、Sources/RemoteMic/OnboardingView.swift、Sources/RemoteMic/OnboardingFlow.swift；
  • 页面布局、材质和遥控器热点：Sources/RemoteMic/SettingsView.swift；“回眸”内容布局与 App 图标：Sources/RemoteMic/TranscriptHistorySection.swift；
  • 实体按键活动状态：Sources/RemoteMic/HIDRemoteMonitor.swift 与 Sources/RemoteMic/BridgeAppModel.swift。

结论

当前仓库截图对应 macOS 26 Liquid Glass 外观；同一页面结构在 macOS 14/15 自动切换到兼容样式。仓库未保留依赖本机临时目录的审查引用。

Onboarding 截图按 Testing/FirstRunOnboarding.md 的生产页面与场景清单生成。数量由当前构建启用的来源、页面、语言、外观和附加状态推导；不在本文件维护另一组固定基线。流程和共享布局变化做完整检查，纯文案和局部变化按 AGENTS.md 做定向检查。截图原件保存在仓库外的持久目录，仓库内只按 AGENTS.md 的截图与设计稿归档规范 保留 manifest.json 索引；逐张检查生产最小窗口下的 chrome、标题、导航、卡片、右栏、裁切、对比度及字号，并记录格式、尺寸和 SHA-256。截图不能替代真实权限、设备、音频和文字上屏验收。

历史 QA 记录（非现行规范）

以下带日期内容保留当时的实现、候选环境和验证边界，便于审计。若其中的页面数量、窗口尺寸、筛选项、设计稿路径或产品状态与本文前半部分或专项 PRODUCT_SPEC.md 不一致，以现行权威规则为准；历史路径不存在时不能作为当前交付证据。

2026-08-11 全流程恢复审计补充了遥控器 HID 状态与“重新检测按键”、音频页回到前台自动刷新，以及完成页对当前权限、BLE 和音频的最终重验。当时的浅色、深色各 8 张生产 Onboarding 截图已逐张检查；设备卡新电池图标仍需在浅色、深色生产设置页和真实充电线状态下复验。

2026-08-16 组合动作页面 QA

  • 参考：用户提供的新建前后、组合动作编辑及遥控器触发方式截图；实现：1.8.24 (117) 本地 ad-hoc 构建，窗口内容约 1024 × 768。
  • 已在同一视觉对比中检查参考与实际页面：页面信息层级保持一致，遥控器固定尺寸，新建前后不会缩放；名称标签和输入框同行；步骤编号与动作标题字号、字重一致；App 图标、名称和 Bundle ID 位于同一信息行。
  • “测试动作”与可用状态的“保存修改”使用主要按钮样式；失焦或禁用时按照 macOS 系统规则降低强调，不额外伪造蓝色。
  • 遥控器触发方式文字会根据按键位置做纵向动画：左键位于右上区域，TV 键位于右下区域；点击页面热点和真实 HID 按键都更新当前按键。
  • 已安装 App 网格保持收起式展示；当前机器实际识别无线麦、Codex、Claude、cmux、飞书、微信、天气、豆包、OpenCode、剪映、Cursor、Xcode、网易云音乐、Chrome、Safari、Zed 和 DimAgent。WorkBuddy 按 com.workbuddy.workbuddy 过滤，需在安装该 App 的用户机器复验。
  • 实测名称超过 20 字符会截断，回车保存后焦点退出输入框；列表删除辅助操作可删除临时组合动作并显示成功状态。
  • final result: passed。真实遥控器触发提示和 WorkBuddy 显示仍列入用户机器人工验收，不以当前机器截图替代。

2026-08-17 语音工具页移除左栏内部滚动，四个工具卡统一高度并顶部对齐；豆包/微信四项输入法设置迁移到右栏。新增两层控制方式选择后，实体遥控器浅色/深色各 9 页、iPhone 和网页版浅色/深色各 10 页，以及豆包四种右栏指引状态和微信浅色/深色语音工具页均已用生产视图复验，在 1020 × 772 下无内部滚动、错位或裁切。

2026-08-17 控制选择改为两层：第一层并列显示“有遥控器 / 当前没有遥控器”并优先推荐实体遥控器；只有选择没有遥控器，第二层才显示推荐 iPhone App 与“没有 iPhone 时使用网页版”。生产状态已经确认遥控器连接时自动跳过第一层，但不会为判断提前启动 discovery。三种控制方式统一显示蓝牙、输入监控和辅助功能权限，连接页分别显示实体遥控器、Nearby 或二维码/WSS 状态。

2026-08-17 系统 Fn 第 3 项加入 macOS 键盘设置浅色/深色原图。生产视图已检查浅色、深色正常状态及浅色冲突状态，截图、实时说明、紧凑“打开键盘设置”按钮和底部导航均同时可见，未重新引入内部滚动。

2026-08-18 回眸页面验证

  • 当时记录的确认稿为 dist/designs/reflections-layout/expanded-app-switcher-collapsible-timeline.png，实现截图为 dist/designs/reflections-layout/implemented-expanded.png，比较图为 dist/designs/reflections-layout/reference-vs-implemented.png；这些历史路径当前已不存在，只能说明当时的验证上下文，不能作为当前设计稿或交付证据。
  • 在生产设置窗口中确认“回眸”紧跟“统计”，页头隐私说明与最右侧开关完整可见；顶部应用栏可在单行和页面内网格之间展开、收起，“全部应用”始终可见。
  • 使用当前真实的 2 个 App、1 个日期、12 条记录确认单 App 筛选、倒序时间线、每条记录的 App 图标和名称、日期折叠恢复，以及页面底部无包围样式的“全部删除”；验证期间未执行任何删除。
  • 生产窗口当前最小尺寸高于 800 × 650，本轮按实际生产窗口完成检查，不能表述为已在 800 × 650 生产窗口验收。10 App 横向滚动、跨日期默认折叠和浅色/深色仍需对应数据与外观环境复验。

final result: passed（上述真实数据与窗口边界除外）

2026-08-18 本地 Agent 访问区验证

  • 在当前生产最小窗口中确认本地 Agent 访问区位于完整历史之后、“全部删除”之前；历史仍是页面主内容，新增区域没有制造核心空白或遮挡记录。
  • 缺少设置事件时自动化确认默认关闭；实际页面检查时“允许访问”保持关闭，关闭状态仍显示授权列表，没有创建授权、复制令牌或改动历史。
  • 中文标题、说明、开关、授权列表和底部操作均完整显示，字号不低于 12pt；页面内没有新增下拉框、Popover 或 Sheet。
  • 当前生产窗口最小尺寸高于 800 × 650，本轮沿用实际生产最小窗口验证；开启、生成配置、长客户端名称、英文、浅色/深色和真实 MCP 客户端仍按测试手册人工验收。

final result: passed（上述人工状态与窗口边界除外）

2026-08-19 组合动作与回眸 MCP 边界说明

  • 组合动作页底部增加固定 12pt 中英文信息行，明确“学习输入框”只负责聚焦目标 App，“回眸”中的 Codex MCP / TOML 只负责授权读取本地历史；没有新增副标题、下拉框、Popover、Sheet 或确认弹窗。
  • 宿主公开构建和注入最新私有模块的编译、本地化及设置页结构测试通过；组合动作现已无需邀请码直接显示，本次仍未完成中英文、浅色/深色和 800 × 650 真实组合动作页面人工验收。

2026-08-20 自定义快捷键选择器 QA

  • 自定义快捷键编辑区新增页面内“常用组合 / 标准键盘”分段选择，不使用下拉列表、Popover 或 Sheet；原有键盘录入、当前值和清除入口仍位于同一编辑区。
  • 2026-08-30 真实键盘录入扩展为普通单键、组合键和单独左右修饰键/Fn；修饰键按下时保持等待，只有单独释放才保存，后接主键时仍形成组合。提示文案明确组合键可以留空，保存格式与既有发送路径不变。
  • 常用组合在 800 × 650 中文浅色生产 App 视图中完整显示；选择态使用低透明度语义蓝，选择预设本身不会执行快捷键。
  • 标准键盘在 800 × 650 中文浅色、中文深色和英文浅色生产 App 视图中检查了组合键、主键区和方向导航区；Command 等长标签保持单行，键盘没有横向滚动或横向裁切。
  • 同一生产视图以 800 × 1400 展开检查了 F1～F20、数字键盘和单独左/右 Command、Option、Control、Shift 与 Fn；全部中文说明和按键文字不小于 12pt。最小高度下通过既有页面纵向滚动访问后续键区，不改变窗口几何。
  • 自动化覆盖预设键码、标准键盘关键分区、左右 Option 键码和单独修饰键的按下/释放顺序。离屏生产视图与自动化不能替代实体遥控器、真实 Spotlight、系统权限和左右修饰键目标 APP 的桌面验收，人工步骤见 Testing/KeyboardShortcutPicker.md。

final result: passed（真实遥控器与真实系统快捷键验收除外）

2026-08-30 按键动作分类筛选 QA（已被 2026-09-13 三筛选规则取代）

  • 动作编辑区顶部增加页面内“全部 / 基础按键 / 系统与媒体 / 自定义动作”胶囊筛选，不使用下拉列表、Popover 或 Sheet；选中项使用系统强调色和语义选中文字颜色。
  • 筛选只改变当前可见候选，不持久化、不执行动作、不改变当前按键映射；“自定义动作”同时覆盖自定义动作与“打开具体 APP”分类，进入时展开具体 APP 动作。
  • 需在 800 × 650 中文、英文、浅色和深色生产 App 视图中确认四个筛选项保持单行、中文最终字号不小于 12pt、无横向滚动或裁切，编辑另一个按键时恢复“全部”。

final result: 800 × 650 中文、英文、浅色和深色真实生产视图截图均通过，四个筛选项保持单行且无裁切；实体遥控器人工验收仍待完成

2026-09-05 Onboarding 语音配置核对卡 QA

  • 生产 OnboardingView 在语音测试输入框页增加配置核对卡，显示无线麦发送键、SayAll 音频输出以及第三方工具必须自行设置的语音识别键和麦克风；豆包额外显示全局唤起语音。
  • 微信输入法、Typeless、其他语音工具分别检查了长按 Fn、点按 Fn 和“需支持语音输入并自行配置麦克风”的差异文案；切换工具或音频设备后用户确认会清除。
  • 语音测试页浅色/深色以及实体遥控器、iPhone、网页版控制方式截图均无明显裁切；音频设备未就绪显示红色，不能误导为已通过。
  • 真实第三方 App 内部按键和麦克风状态仍不可观察；截图、自动化和离屏渲染不能替代真实豆包/微信/Typeless 文字上屏验收。

2026-08-24 语音键模式布局 QA

  • “按键映射”页底部的 HID 状态、选择锁定、语音触发键、Fn 点按、短按聚焦和恢复默认使用稳定纵向分区；三段选择和两个开关保留在页面内，不使用下拉列表、Popover 或 Sheet。
  • 使用生产 SwiftUI 视图和中英文正式资源完成 800 × 1400 压力渲染，并用英文完成 1020 × 1400 渲染；侧边栏、左右映射卡、三段选择、Fn 点按区和恢复默认按钮均无横向裁切。
  • 800 宽结果只属于截图 harness 压力审计，不代表生产设置窗口支持 800 × 650；真实窗口默认及最小尺寸仍为 1020 × 772。
  • 新增和既有中文控件保持 12pt 或更大；帮助文字允许换行，没有使用 minimumScaleFactor 缩小中文。
  • 自动化已增加 footer 紧凑布局门禁。真实 1020 × 772 窗口逐一点击侧边栏、纵向滚动、中英文、浅色/深色和系统增强对比度仍按 Testing/VoiceKeyModes.md 人工验收。

final result: passed（横向布局与静态字号；真实窗口交互和真实设备除外）

快速连接补充约束

  • Codex、Claude Code、Cursor、OpenCode 使用页面内两列卡片，不使用下拉列表、Popover 或 Sheet；每张卡显示客户端图标或回退图标、名称、检测/连接状态和单一主操作。
  • 手动客户端名称与复制配置保留在快速连接卡片之后，作为冲突、JSONC、CLI 失败和其他 MCP 客户端的降级路径。
  • 自动连接失败只显示页面内错误文案，不连续弹窗；在 800 × 650 检查中必须确认四张卡、手动配置区、授权列表和页面底部“全部删除”可通过现有页面滚动完整到达。
  • “已授权客户端”只展示当前有效授权，不展示快速连接失败产生的撤销记录；错误文案必须包含对应客户端名称和可行动的失败原因，不能只显示统一的“自动连接失败”。
  • 快速连接成功状态必须显示具体客户端名称，例如“请重新打开 Codex”；说明文案明确无需重启无线麦，避免把“客户端”误解为当前 App。
  • App 改名、移动或旧连接缺少 Helper 路径指纹时，客户端卡和授权行使用橙色文字显示“先移除，再重新连接”；提示留在页面内、不弹窗，不把自定义安装路径或令牌展示给用户。

设置页配置导出

  • 点击“导出配置”后直接打开系统保存窗口，只选择文件位置和名称。
  • 使用个人备份格式，自动收集全部可迁移对象及通用、音频、语音、当前遥控器按键设置。
  • 不显示内容多选、分享类型、设置分组或导出预览；输入框定位指纹继续排除。
  • 组合动作与键位方案页面的分享，以及导入确认流程，沿用各自的现有规则。

2026-09-10 设置页设计稿一致性 QA

  • 视觉真值：Screenshots/design-drafts/settings-page/option-1-revision-1.png，PNG，1442 × 1091，SHA-256 3aaaa7ff12f3fbb8a5546d5ac11477a60f11f32fb1c714a557367bd68293521f。
  • 实现截图：历史截图证据已按仓库清理规则移出，生产 App 资源包的隐藏离屏入口，窗口 800 × 650、Retina 输出 1600 × 1300，中文浅色，SHA-256 6192b69d53de67c3ec828029f021efad59a88f5a29fde7e5b5f1643676f1c04b。
  • 底部分享状态：历史截图证据已按仓库清理规则移出，同窗口与密度，侧边栏分享入口触发展开并滚动到底部，SHA-256 2a7205af09ab6d542817f363decf81875066414ba3a3a7a60d5181c69d7445cc。
  • 完整同图对照：历史截图证据已按仓库清理规则移出，把设计稿等比缩放并居中到 1600 × 1300 后与实现并排，SHA-256 d8b352f9a9db36e927939c1f7613287c2aa32a4e7a3240d532afa4bef9c6319f。
  • 顶部重点区域对照：历史截图证据已按仓库清理规则移出，用于核对应用信息、版本检查、Release Notes、权限行和分隔线；没有对设计或实现内容做重绘，SHA-256 974bb53aa7d328731e24d4f4a8db5f642a881c6a242d3b8a87145218272defeb。

比较历史

  • 第一轮实现（Commit e83f9d4d）存在 P1：首屏被大号品牌 Hero、反馈大卡和默认展开的分享二维码占据，版本、权限与通用无法形成设计稿的紧凑系统设置层级。
  • 修正：移除顶部独立 Hero 与反馈大卡；把 App 信息合并到“应用与更新”；权限、通用、诊断改为无大圆角容器的平铺行和分隔线；反馈、官网与 GitHub 收敛为底部支持行；分享移动为内容栈最后一个模块，侧边栏入口通过稳定锚点定位并展开。
  • 第二轮同图复核：上述 P1 已消除。实际产品保留既有多页面侧边栏、预发布更新开关和官网/GitHub 功能，因此不会复制设计稿仅有单个侧边栏入口的静态示意；这些差异属于现有功能边界，不改变主内容的信息架构和视觉语言。

必查视觉面

  • 字体与排版：使用系统字体与语义字重；正文与辅助说明不低于 12pt；中英文均未使用 minimumScaleFactor；英文长按钮在窄窗口按系统规则截断，完整功能可访问。
  • 间距与布局：主要分区、行高、图标列、状态列、操作列和分隔线已与设计稿的紧凑节奏一致；800 × 650 首屏可同时看到应用更新、完整权限和通用开头，纵向滚动访问其余内容。
  • 颜色与视觉 token：使用系统背景、分隔线、语义蓝和权限绿色状态，浅色与深色均保持对比度；不再使用与设计稿不一致的大面积卡片和阴影层级。
  • 图片质量：继续使用 App 包内真实应用图标，未替换为占位图、重绘图或代码近似资源；设计稿原图字节保持不变。
  • 文案与内容：应用与更新、权限与隐私、通用、诊断与日志均与确认方案一致；待更新版本 Release Notes 位于检查更新区域右侧；导入/导出与两个启动开关各自保持同一行；分享为页面最后一个模块。

剩余边界

  • 截图证明静态布局、语言和外观，不替代真实系统权限跳转、Sparkle 安装更新、文件导入导出、登录项审批和实体设备验收；对应人工步骤保留在 Testing/AboutUpdateCenter.md。
  • 设计稿画布比例与生产 800 × 650 窗口比例不同；同图对照采用等比缩放和居中，不把画布留白或既有侧边栏页面数量作为实现缺陷。

final result: passed

2026-10-31 个人中心页头与 KPI 完整性修复

  • 改动：个人中心页头只保留“个人中心 / Profile”标题，移除右上角锁图标与“数据仅存本机 / Data stays on this Mac”说明，并删除对应本地化键；累计语音时长改为紧凑写法（15小时31分 / 15h 31m），数值行增加收紧与缩放兜底，避免小时级数据被省略号截断。
  • 实现截图：Screenshots/bug-fixes/profile-header-and-kpi-fit/zh-hans-light/profile-1020x772.png，PNG，2040 × 1544，SHA-256 3549588ef46f8c2c2abea6e7a7a8434377429a4a7861d727f42937cc5a01627d。
  • 实现截图：Screenshots/bug-fixes/profile-header-and-kpi-fit/zh-hans-dark/profile-1020x772.png，PNG，2040 × 1544，SHA-256 d73526e0feb0d1c9db500fdfc8e2a437ffb45adda73994d011794d2607573a5a。
  • 实现截图：Screenshots/bug-fixes/profile-header-and-kpi-fit/en-light/profile-1020x772.png，PNG，2040 × 1544，SHA-256 5204ae3ccdbbc720ce7a8942145d0b3015af9a4f214d66d602a4972237aa15ba。
  • 窄宽压力截图：Screenshots/bug-fixes/profile-header-and-kpi-fit/zh-hans-light/profile-800x650.png，PNG，1600 × 1300，SHA-256 ceedca97a88768acf59d97bce6350ce3dd3938e9c918766ee51d46ba454ba450。
  • 英文文案同批修整：计数不再带 times 单位（statistics.metric.count_unit 在英文下为空，行内与卡片都不渲染单位），Longest Voice Session(s) 改为 Longest Voice Input(s)，日历提示改为 Click a day or an entry to open Reflections，分享说明改为 Invite friends to try voice input on their Mac with a remote or a phone.，按钮改为 Show QR code；中文文案不变，仍显示“次”。
  • 验证边界：四张截图均来自生产 SettingsView 的隐藏离屏入口，1020 × 772 为当前生产最小窗口；小时级时长来自离屏样本数据，不替代真实使用数月后的极端数据、真实权限与实体设备验收。英文另在 800 × 650 复验日历提示完整换行、计数无单位、卡片不裁切。

final result: passed

2026-11-01 语音键设置改为点击后出现

  • 改动：“按键映射”页不再常驻语音键设置页脚。连接状态、语音触发键、语音键模拟 Fn 点按和恢复默认收进一块语音键设置面板，只有点击画布上的语音键卡片后才出现在画布下方；再点同一张卡片收起。
  • 同时移除“锁定当前按键”开关：它与语音键无关，只是画布选中项的浏览辅助。开关下线，但“按下实体遥控器不移动选中项”的行为固定保留——选中项决定高亮和编辑落点，跟着按键跳会把正在编辑的按键顶掉；按键按下时仍以橙色按下态显示。
  • 互斥：打开该面板时收起普通按键与按住的编辑器，打开任一按键编辑器时收起该面板，页面上任何时刻只有一份正在编辑的设置；切换遥控器、切换侧边栏分区同样收起。
  • 适用三种遥控器共用的 hardwareMappingPage，小米遥控器页、Siri Remote 页与 Chromecast 页行为一致；触摸面方向开关随同一面板显示，Siri Remote 页不再单独常驻。
  • 按钮文字、三段选择和开关沿用既有本地化键，没有新增文案；面板内分区、字号和 恢复默认 位置不变，800 × 650 压力渲染与 1020 × 772 生产窗口均无横向裁切。
  • 验证方式：生产 SettingsView 的隐藏离屏入口在 1020 × 772 渲染“未点击语音键”和“点击后”两种状态，确认未点击时页面底部不再出现该卡片、点击后只出现这一块面板。
  • 验证边界：离屏渲染只证明静态布局与状态门控，真实指针点击、再点收起、按键编辑器互换和实体遥控器连接仍按 Testing/VoiceKeyModes.md 用例 1 人工验收。

final result: passed（状态门控与静态布局；真实点击交互除外）