本文是无线麦 SayAll Onboarding 的跨平台产品规范，也是检查、设计、修改和测试 Onboarding 时的唯一产品行为入口。
规范适用于现有 macOS 版本及未来 Windows 等桌面平台。平台实现必须先满足本文的产品不变量，再按平台附件实现权限、按键、音频、连接和界面差异：
本文使用以下约束词：
- 必须：所有平台不得降低或绕过的产品要求。
- 应该：除非存在经过记录的平台限制，否则应遵守。
- 可以：平台可以根据系统能力选择的实现。
平台附件不能覆盖本文的“必须”要求。若产品不变量发生变化，必须先或在同一次修改中更新本文，再更新平台附件、实现、测试和截图证据。
Onboarding 不是功能介绍或页面 Tour，而是首次可用性验收流程。
用户完成 Onboarding 时，产品必须已有证据证明：
- 用户选择的控制来源能够真实连接并发送控制事件。
- 语音会话能够由预期按键或操作开始和结束。
- 真实音频已沿当前平台配置的路线到达目标语音工具。
- 目标语音工具已把语音结果写入测试输入框。
- 用户知道日常使用所需的语音键、音频设备和第三方工具配置。
- 失败时，页面和诊断能够指出已经确认的失败边界以及下一步操作。
访问过页面、点击过按钮、收到过连接回调、音频已入队或用户勾选确认，都不能单独代表 Onboarding 成功。
Onboarding 不负责：
- 完整介绍所有高级功能或替代产品帮助中心。
- 在首次流程中提供完整按键映射编辑器。
- 读取第三方 App 的私有文件、数据库、沙盒、私有协议或未公开设置。
- 通过预设成功状态、测试桩或手动输入绕过真实端到端验证。
- 强制所有平台使用相同的系统权限名称、语音键或音频驱动实现。
- 因增加新平台而降低已有平台的完成门槛。
- 未完成必要能力检查前，不提供“跳过”“稍后继续”或进入主页面的旁路。
- 关闭 App、系统重启或连接中断后，必须保存并恢复到合理的未完成位置。
- 卡住不能等于死路。每个失败状态必须提供与当前原因直接对应的主要修复操作。
- 用户必须能够返回前一步检查选择；返回不能立即被自动路由再次推回原页面。
- 页面访问和按钮点击不是通过条件。
- 每一步必须根据当前实时能力状态决定能否继续。
- 同时存在多个控制来源时，只允许用户当前选择的来源满足连接、按键和语音门禁。
- 临时状态、旧会话结果和其他来源事件不得污染当前验证。
- 完成前必须重新检查仍会影响日常使用的权限、连接和音频条件。
- Onboarding 必须尽量复用日常运行时使用的连接、按键、音频、输入目标和语音会话链路。
- 不得为了让 Onboarding 通过而建立只存在于向导中的模拟成功路径。
- 测试工具可以注入状态或回放事件，但生产完成条件必须来自生产能力模型。
端到端语音测试页必须在输入框附近集中显示：
- SayAll 当前对应的开始/结束操作方式；具体按住或按一次提示必须与所选控制设备和输入工具匹配。
- SayAll 当前使用的音频输出路线或设备。
- 第三方语音工具应配置的语音识别键或触发方式。
- 第三方语音工具应选择的麦克风或音频输入设备。
- 当前工具特有且会阻止语音输入的必要选项。
- 无线麦输出音量的当前值、用途和可调入口；用户可以在同一页放大小声或气声，调整立即作用于后续语音测试。
如果 SayAll 与第三方工具的按键或音频配置不一致，用户必须能够在开始测试前直接看出差异。已经可以自动观察的 SayAll 状态与只能由用户确认的第三方状态必须有明显区别。
音量是连接页与 Onboarding 共用的同一个控件、同一个值（0–1000%，步长 20%，0% 静音、100% 保持解码后的原始幅度）：较高值会放大人声，也会同步放大环境噪声并增加削波风险。Onboarding 不得另外实现一套增益语义或另一套取值范围，两处渲染的都是 OutputVolumeSlider。Onboarding 应提供该滑块和简短说明，不得要求用户离开当前输入框页面才能调整；调节不改变语音键按下即开始、释放即结束的生命周期，也不触发音频链路重启。
- 只能通过公开 API、公开协议或用户可见界面获得第三方状态。
- 无法观察的第三方设置必须显示为“需要用户确认”或“未知”，不能显示为自动检查通过。
- 用户确认只能证明用户执行了核对，不能替代最终真实文字上屏。
- 切换语音工具、语音键或音频设备后，受影响的用户确认必须失效。
-
产品命名遵守
design-qa.md：英文产品名为SayAll，英文宣传称呼为SayAll App，中文为“无线麦 SayAll”，中文宣传称呼为“无线麦 SayAll App”。 -
普通用户可见页面只能说明用户当前所处的状态、实际影响和可以执行的下一步，不得展示研发流程或测试进度。
-
“待真机验证”“需要兼容性验收”“待回归”“自动化/CI 已通过”“候选实现”“开发中”“验证中”等技术、测试或内部验收用语不得出现在普通页面、状态卡、按钮、提示、错误信息或帮助文案中。
-
尚未完成真实环境验收的能力必须隐藏、不发布，或不列为支持和推荐；已经公开但当前确实不可用时，只能用“暂不支持”“暂时无法使用”等用户能够理解的结论说明实际影响，并提供可执行的替代方案或后续操作。
-
“预发布版本”“测试版”等词只有在用户主动选择发布渠道且该信息会影响其决定时，才可作为产品概念显示；不得借此暴露内部开发阶段、测试清单或验收结论。
-
技术原因码、自动化结果、兼容性矩阵和验收状态只能写入脱敏日志、用户主动复制的诊断、测试手册、Bug 记录或 PR 证据。页面如需反映同一问题，必须转换为普通用户能够理解的结果和解决办法。
-
面向用户的产品或第三方 App 名称必须采用其官方公开名称，不得自行拼接
Input Method等非官方后缀；英文类别说明使用普通用户可理解的voice typing app或voice app，不得使用含义不清的voice tool。 -
本地化文案必须在生产最小窗口内完整显示。不得用单行截断、固定最大高度或缩小到最低字号以下来掩盖英文等较长语言的布局问题。
语音测试至少必须确认：
- 当前所选来源开始了语音会话。
- 收到了非空的真实音频样本。
- 音频被投递到当前选择且有效的路线。
- 用户结束了同一次语音会话。
- 第三方语音工具把文字写入当前测试输入框。
手动键盘输入、粘贴旧文字、其他窗口出现文字或上一 attempt 的迟到结果不能满足最终门禁。
平台可以根据系统能力合并相邻页面或调整说明方式，但不得改变以下依赖顺序和完成语义。
- 说明本流程将完成真实设置和验证，而不是只展示教程。
- 不显示会鼓励跳过必要步骤的入口。
- 可以使用简短阶段导航，但不应制造“快速点完页面即可完成”的预期。
- macOS 当前可见页面顺序为：欢迎、控制设备、权限、连接控制设备、音频、语音工具、语音测试、普通按键、完成。
- 欢迎页可以复制无屏 AI 配置提示；该提示只允许 Agent 修改无线麦自己的配置，配置后必须停在真实语音验证步骤。
- 欢迎页之后先使用单页按“实体遥控器 / 更多控制方式”展示当前构建真实支持的来源，实体遥控器排序和视觉权重高于 App 或网页。
- “更多控制方式”默认折叠，只有用户主动展开或已选择其中来源时显示。
- 不得展示当前构建缺少实现 Package、因而无法完成后续门禁的来源。
- 需要独立安装组件的来源，还必须确认本机已安装该组件。未安装时隐藏卡片；已保存但不可用的选择返回控制来源页。
- Siri Remote 的日常语音属于会员功能。组件已安装时，会员和非会员都可使用生产链路完成真实语音测试。
- 流程必须保存进入前的 Siri Remote 启用状态，并在退出续接时保留。完成前，仅在本次临时启用且会员权益不足时停用；原本已启用、会员或有效离线租约均保持原状态。页面必须说明试用与日常使用的区别。
- 支持多种语音手势的来源必须让用户明确选择按住或按一次；来源上报实际模式时以本次会话事实为准。
- 已经由生产状态确认主设备可用时可以预选对应实体设备，但仍保留本页供用户确认，不能为判断而提前触发权限或扫描。
- Onboarding 控制来源页必须隐藏 Chromecast 选项。Chromecast 的运行时实现、持久化值和兼容代码必须保留，隐藏只适用于本次 Onboarding 选择界面。
- 显示平台支持或已检测到的语音工具。
- 推荐工具未安装时，必须提供官方来源入口，不得用第三方下载地址代替。
- Onboarding 的临时语音键固定为 Fn，不在工具选择页展示配置来源、快捷键学习或 Command/Option 选择。
- 固定 Fn 只约束本次 staged 配置；选择工具或返回页面不得立即覆盖正式设置。
- 选择“其他语音工具”时，必须明确要求该工具支持 Fn 语音输入并配置正确麦克风。
- 选择结果必须进入后续配置核对和诊断上下文。
- 工具相对顺序固定为豆包、微信、Vokie、Typeless、其他；豆包、Vokie 和其他始终显示，微信与 Typeless 只有通过公开系统能力确认已经安装时才显示，未安装时不保留空卡片。ChatterFly 不属于当前 Onboarding 支持选项。
- 英文界面中豆包显示官方名称
Doubao，微信输入法显示官方名称WeType，“其他”显示为Other Voice App；内部枚举、持久化值和 Input Source ID 不因展示名称改变。 - 选择任一可见工具后，右栏必须显示该工具对应的设置步骤；豆包、微信和 Vokie 使用匹配当前浅色/深色外观的真实截图，Typeless 与其他工具使用简短操作说明。
- 所有可见工具的右栏步骤都必须包含“去除系统 Fn 占用”，显示 macOS 键盘设置截图、当前公开可观察状态和打开键盘设置操作；该步骤用于避免系统动作抢占本次 staged Fn。语音测试页仍需提醒用户在目标工具中选择与 SayAll 相同的麦克风，并避免微信 App 的全局 Fn 快捷键冲突。
- 语音测试页只显示当前控制设备与工具匹配的“按住”或“按一次”操作说明，不显示 Fn、地球键或快捷键来源。
- 输入工具与控制来源都选定后，必须生成一份明确的配对计划：输入工具、快捷键、按住/按一次语义、必要转换和证据状态。
- 当前 Onboarding 一律生成 Fn staged Binding；控制来源的按住/按一次能力决定是否需要 Fn 点按转换。
- staged Binding 不得在真实测试前覆盖正式配置。
- 只有同一次真实语音开始、非空 PCM、正常结束和文字上屏全部通过后，才能原子提交为 verified Binding。
- 返回更换工具/来源、退出未完成流程或测试失败时，必须恢复进入 Onboarding 前的正式语音配置。
- 老用户主动重跑时，进入欢迎页和选择工具本身不得修改已有快捷键或触发方式。
- 无屏配置命令通过受校验的本机接口读取无线麦自身状态和公开系统能力，不要求 Agent 操作窗口或屏幕。
- 命令可以准备控制来源、语音工具、Fn staged Binding、音频设备和增益，并将流程定位到语音测试页。
- 命令必须支持 JSON 结果、候选选择、权限阻断、备份、校验和失败回滚；不能将配置写入当作真实语音文字验证成功。
- 只请求当前产品链路真正需要的系统权限。
- 必须解释权限用于哪项用户功能，并展示实时授权状态。
- 已授权项目仍应该允许用户打开对应系统设置进行检查或恢复。
- 拒绝、受限、需要重启和权限历史异常必须有不同的恢复指引。
- 必须确认当前选择的控制来源真实连接。
- 至少观察一个来自该来源的真实普通控制事件，避免把系统设备列表中的“已连接”误当成产品可用。
- 连接、协议准备和事件可用性如果是不同边界，必须分别记录。
- 必须选择当前平台支持且能够把无线麦音频提供给第三方语音工具的路线。
- 页面必须区分 SayAll 的音频输出端与第三方工具的麦克风输入端，并要求两端匹配。
- 音频名称使用系统实际枚举值：新安装显示 SayAll，旧安装保持 MiRemoteV 2ch，BlackHole 2ch 继续支持。不得重命名已有设备或覆盖用户已保存的选择。
- 设备存在、已选择、实际绑定、正在投递和已经排空是不同状态，不能用一个布尔值替代全部事实。
- 不满足语音输入用途的扬声器或普通输出设备不能通过门禁。
- 在测试输入框页显示完整配置核对卡。
- SayAll 可自动观察的配置应直接显示当前值与正常/异常状态。
- 第三方不可观察的配置必须逐项要求用户确认。
- 未完成配置核对、SayAll 自身配置异常或音频路线失效时不能完成流程。
- 即使所有确认均已勾选，仍必须完成一次真实语音到文字的端到端验证。
- 使用当前选择的控制来源验证多个不同普通按键或等价控制操作。
- 重复同一个按键不能伪装成多个独立能力已经可用。
- 语音键不应被计入普通按键体验。
- 首次要求普通控制键时，页面必须在用户操作前明确指出可按的具体按键，并明确排除麦克风/语音键，不能只显示“监听已连接”等技术状态。
- 如果当前来源在普通按键检查页触发了语音会话，页面必须立即说明刚才按的是语音键，并给出正确的普通按键操作；不得把该输入静默忽略为无响应。
- 完成页必须重新确认关键运行条件仍然成立。
- 条件退化时应返回最接近问题的修复步骤，而不是清空整个流程。
- 完成后进入主页面，并保存当前 Onboarding 流程版本。
- 每个页面只突出当前最重要的任务和一个主要修复动作。
- 必要配置、错误和继续条件必须直接显示，不能只放在悬停提示、弹窗或帮助文档中。
- 能在当前页面完成的选择和确认应平铺展示，避免连续弹窗和深层菜单。
- 右栏插图和说明在可用空间内应保持整体垂直居中。内容超出高度时可以滚动，但初始位置不能把内容固定在顶部。
- 控制来源选择页可以纵向滚动访问全部来源，但不得显示滚动条或滚动轨道。
- 连接 Mac 页面在二维码尚未生成时，必须说明下一步会生成二维码。不得使用“正在生成二维码”表示尚未开始的操作。
- “继续”按钮的禁用原因必须能够从当前页面状态理解。
- 所有用户可见文本必须支持平台要求的辅助功能、键盘导航、屏幕阅读和缩放。
- 中文界面文字不得小于项目规定的最小字号；其他平台也必须制定等价的可读性门槛。
- 浅色、深色、高对比度和系统缩放下不能裁切主要任务、状态、输入框或导航。
必须持久化：
- Onboarding 流程版本。
- 是否完成当前流程版本。
- 当前合理恢复步骤。
- 用户选择的语音工具和控制来源。
- 平台适配明确要求保留的非敏感配置。
不得把临时会话状态持久化为已经通过，例如当前连接回调、按键按下状态、音频样本、输入框文字或某次 attempt 的成功标志。
升级规则：
- 已安装用户不能仅因加入 Onboarding 而被误判为全新用户。
- 产品新增真正必要的能力门禁时，使用流程版本决定补跑范围。
- 权限或设备在完成后失效时，应优先进入定向修复，而不是强制重跑全部步骤。
- 用户主动重新运行 Onboarding 时，不得清除连接资料、按键映射、音频选择和其他无关设置。
每个步骤必须定义：
- 已确认事实。
- 当前未知边界。
- 稳定失败原因码。
- 用户可以执行的下一步。
- 重试、取消、返回、断连和 App 重启后的状态。
日志必须遵守仓库根目录 LOGGING.md，覆盖从用户操作到最终可见结果的完整链路。语音 attempt 必须有唯一标识和唯一终态，并区分：
- 控制触发没有发生。
- 会话未开始或未结束。
- 没有收到音频。
- 音频路线、绑定或播放失败。
- 输入目标未准备好或持续失焦。
- SayAll 可观察链路正常，但第三方工具没有提交文字。
第三方内部状态不可观察时，诊断必须明确 observable=false 或等价边界；用户确认与自动观察不得使用同一字段语义。
普通按键检查的诊断必须区分语音键触发和普通控制键观察，至少记录脱敏计数与最后输入类型。连接成功但普通按键未观察到时，不能仅输出统一的 button_not_ready 而丢失“用户实际按了语音键”的已确认事实。
普通按键检查是一次独立的能力检测，不是用户快捷键回放：进入该页时只统计本次流程收到的不同普通按键，并暂时抑制已有单击、双击、长按和内部动作映射。重新运行 Onboarding 不得读取或修改用户已有映射，也不得因为历史映射的目标动作而改变通过结果。
如果实体遥控器已经连接但在有限等待后仍没有收到普通按键，可以使用 macOS 公开的安全输入布尔信号作为候选诊断。该信号只用于显示普通用户可理解的“系统安全输入可能影响遥控器按键”提示和“重新检测”操作，不是独立失败原因，不读取进程身份或第三方 App 私有状态，也不能替代真实按键门禁。
Onboarding 不得记录或导出：
- 用户说出的音频或可恢复音频的样本。
- 测试输入框文字、长度或上下文。
- 用户身份、设备身份、路径、窗口标题、文档名或凭据。
- 第三方 App 私有文件、数据库、沙盒、内部设置或未公开协议数据。
允许记录稳定枚举、布尔状态、脱敏计数、耗时、平台版本、App 版本、流程版本、失败边界和用户是否完成某项确认。完整要求以 LOGGING.md 为准。
每个平台附件必须明确以下映射：
| 产品能力 | 平台附件必须回答的问题 |
|---|---|
| 控制来源 | 支持哪些真实设备、手机或网页来源，如何证明当前来源可用？ |
| 权限 | 每项权限对应什么能力，拒绝和恢复路径是什么？ |
| 语音触发 | SayAll 发出什么按键或操作，第三方工具如何配置为一致？ |
| 音频路线 | SayAll 输出端是什么，第三方工具输入端是什么，如何证明投递成功？ |
| 输入目标 | 如何确认文字会进入当前测试输入框？ |
| 第三方状态 | 哪些可以公开观察，哪些只能由用户确认？ |
| 持久化 | 平台保存哪些选择，升级时如何迁移？ |
| 日志 | 哪些边界可以自动确认，哪些必须记录为未知？ |
| UI 与辅助功能 | 最小窗口、缩放、键盘导航和屏幕阅读如何验收？ |
| 真实验收 | 哪些必须使用真实设备、系统权限和第三方 App？ |
平台不支持某项现有实现时，必须提供实现同一产品目标的等价能力，或明确缩小该平台公开支持范围；不能静默跳过门禁。
Onboarding 修改必须同时考虑以下四层：
- 流程自动化：状态机、分支、持久化、门禁、失败恢复、旧配置迁移和来源隔离。
- UI 与截图：按
AGENTS.md的风险分类验证。流程、能力和共享布局变化做完整检查；纯文案或局部变化做受影响页面、来源和状态检查，覆盖中英文、浅色/深色、最小窗口及必要缩放。页面和场景以生产清单为准。 - 构建与产物：目标平台构建、架构、签名、安装、升级和启动。
- 真实环境：真实权限、控制设备、音频路线、第三方语音工具、前后台、断连和最终文字写入。
前一层通过不能替代后一层。交付说明必须明确哪些层已经通过、哪些仍待现场验收。
检查或修改 Onboarding 前：
- 已完整阅读本文和当前平台附件。
- 已确认本次变更属于跨平台产品规则还是单个平台适配。
- 已画出从用户动作到最终可见结果的逻辑链路。
- 已列出受影响页面、能力门禁、持久化、日志和恢复路径。
提交前：
- 产品不变量变化已更新本文。
- 平台行为变化已更新对应平台附件。
- 测试手册覆盖成功、拒绝、失败、重试、返回、重启和升级边界。
- 已记录风险分类，按生产清单完成适用的完整或定向截图检查。
- 日志能区分确定事实、用户确认、未知边界和最终结果。
- 未读取或记录第三方私有状态和用户敏感信息。
- 已明确自动化、截图、模拟环境和真实设备验收边界。