声纹录入与语音激活修复

录入页按资源检查、麦克风试录、正式录入的顺序工作。麦克风运行在浏览器或 Electron 客户端，模型与运行组件安装在实际运行 N.E.K.O 后端的机器上。远程部署时，应在后端机器处理资源故障。

麦克风与试录

允许麦克风权限后，选择输入设备，核对页面显示的实际音轨名称，再检查音量条。输入过弱时检查设备、距离与增益；削波时降低增益。试录检查降噪处理后的有效人声，原始音量正常仍可能因人声不足而失败。

试录前关联采集窗口会停止主语音输入，并等待后端关闭输入路径的确认。试录不会提交给 ASR 或 Omni，也不会保存录音或覆盖声纹档案。结束试录后，由用户重新开启主界面麦克风。

正式录入保留三段参考录音、一段验证录音及 45 秒总时限。切换设备、增益或降噪配置后需要重新试录，正式录入中的变化会取消整次录入。设备断开后重新连接并再次启用麦克风；失败重录与取消保留已有档案及启用偏好。

安装包资源修复

资源面板分别显示 CAM++、Silero、人声降噪能力、唤醒词模型和唤醒词运行组件。资源准备只是加载检查，不能补回安装包缺失的文件。

桌面端的应用修复入口打开既有关于与更新面板。CAM++、Silero、RNNoise 或唤醒运行组件缺失时，应更新或修复实际后端安装包。更新后重新准备资源，并由用户重新开启麦克风。

唤醒词下载只安装固定模型包，不执行安装命令，不改变用户的启用偏好。组件版本不兼容时，下载模型仍不能恢复唤醒能力；已打包应用须更新至包含兼容组件的版本。

源码部署

在后端仓库根目录使用其 Python 环境执行：

uv run python scripts/prepare_speaker_model.py
uv run python scripts/prepare_voice_turn_assets.py

两个脚本使用项目固定来源与摘要，准备 CAM++ 及语音端点检测资产。准备完成后回到资源面板执行加载检查。RNNoise 能力来自项目的音频运行依赖：用项目锁文件同步后端环境，再检查资源状态；模型下载不能修复 RNNoise 运行组件缺失。

唤醒词需要定制的 1.13.8+neko.kws2 运行组件。先按照 唤醒运行组件安装说明 构建并安装兼容 wheel，然后执行：

uv run --no-sync python scripts/provision_wake_word_model.py --model-dir .wake-word-model

脚本下载完整包、校验、真实试加载成功后才发布 current.json，并输出实际版本目录。显式设置 NEKO_WAKE_WORD_MODEL_DIR 时应指向该输出的 versions/<version> 目录。缓存根目录本身不是模型目录。已有显式配置优先于缓存发现。

未显式配置时，页面下载使用后端用户的受控缓存。用户主动启用唤醒词后，后端会发现并加载验证通过的当前版本；缓存存在与下载成功均不会自动启用唤醒词。禁用时保持纯声纹激活。已启用但资源异常时，语音门控保持阻断并显示原因。

当前打包流水线的唤醒组件针对 Windows x64、Python 3.11，包含固定源码、补丁、版本检查和冻结程序实际加载检查。其他平台需具备经过验收的兼容组件；不支持的平台会报告能力不可用。

激活与重试

声纹录入与质量检查不依赖独立 ASR。普通 ASR 与 Omni 都经过统一激活门控：本人声纹或已启用且就绪的唤醒词可激活；激活后沿用会话输入行为，30 秒无人声回到等待状态。

主界面显示准备中、等待激活、已激活或不可用及原因。资源可用、档案已保存与当前会话已激活是不同状态。停止、断连或切换会话后，旧状态不能更新新会话。

重试只作用于当前采集连接与会话，先退休旧实例，再准备新实例；恢复前不放行下游音频。资源修复会重新装配激活资源。交付结果不确定的旧音频不会重新投递。

等待激活时，客户端到 N.E.K.O 后端仍可能传输音频；门控控制后端向下游 ASR 与 Omni 的递交。

两仓库版本依赖与回退

N.E.K.O 的资源与试录接口、voice_identity_control 控制消息，需与 N.E.K.O.-PC 的 nekoVoiceEnrollment 桥接配套部署。桌面端保留 Session 与 partition 隔离，由实际采集窗口打开录入子窗口；不同 partition 的设备编号不会同步。

回退应用代码不会改写既有档案格式或启用偏好。模型版本目录保持不可变，发布失败与取消保留原有效指针。损坏版本通过发布新完整版本修复；达到受控缓存容量上限时停止安装并报告原因，避免删除正在使用的模型文件。

缓存容量达到上限时，只能由实际运行后端机器的维护人员进行受控维护：先停止使用该缓存的所有后端进程，保留当前完整有效版本与 current.json，再清理本功能明确拥有且已不再使用的历史版本。页面不会自动删除已发布版本；不要删除用户声纹档案或启用偏好，也不要按设备名称推测其他机器的缓存位置。

下载在工作进程中校验并试加载完整资源，先安装不可变版本目录，再由当前操作提交 current.json。提交前取消保留旧指针；提交开始后取消会等待实际发布及运行时刷新结果。接口的 committed 字段说明是否已确认发布，已发布但刷新失败时仍显示失败原因；预检结果只在刷新完成且配置未变化后标记就绪。