让桌面的小盒子，
听见你的声音。

1. 已开启网页更新的设备。

   登录后找到已绑定设备，在“官方签名更新”区域点击“检查官方更新”。页面自动读取状态并显示设备回报的更新阶段；设备未上报下载百分比时显示进行中。设备报告 candidate.17 可用后，再点击“安装官方最新可用版本”；安装会等待当前对话结束。以设备回报的结果为准，点击按钮不代表安装已完成。这一次升级的开始提示仍由设备旧版执行：怕提示太响时，先把设备“提示音音量”设为 0，保存并等待设备已应用，再更新；完成后恢复原音量。新版会分批准备当前音色的离线固定短句，原七段聊天提示和三段更新提示缓存保留。进入手机配网的操作见下方“有限离线陪聊与手机配网”；首次启用系统权限需单独执行一次准备脚本。

2. 尚未开启网页更新：下载并复制手工包。

   先确认树莓派已经安装基础程序、依赖和本地唤醒模型。下载本次 ZIP 并解压，根目录为 acexia-bluetooth-speaker-20261004，SHA-256 为 71602742d241ca434bcaa8bb94d36331332f9e7e4be63661c584037d474cf802。在能看到此目录的 Windows PowerShell 中，将下面的用户名和树莓派 IP 替换为实际信息再执行：

   scp -r .\acexia-bluetooth-speaker-20261004 用户名@树莓派IP:~/
   ssh 用户名@树莓派IP

3. 在树莓派停止服务并安装。

   使用安装基础程序的普通用户登录；如果另有前台设备程序，先按 Ctrl+C 停止。保持供电，执行以下命令；安装器不要加 sudo：

   sudo systemctl stop voice-companion
   python3 ~/acexia-bluetooth-speaker-20261004/apply_update.py

   保存输出中的真实 Backup: 路径，只有显示 Patch installed. 后才继续启动服务：

   cd ~/voice-companion/software
   bash enable_device.sh

   本次应用更新保留绑定、模型与个人配置；安装失败时先保留输出，不要重新绑定或覆盖凭据。

4. 设置名字并试喊。

   在设备卡片开启“本地语音唤醒”，英文名只填名字，不用再填 Hi。保存后等待设备同步，直接试喊“Hi + 名字”，无需运行 wake-template 或 wake-calibrate，也无需录入声音。新版在本地匹配完整 Hi / High + 名字及少量近音拼写；不会仅听到 Hi 就触发，也不保证每种口音都能识别。先保留按键，并在自己的环境试喊和检查误唤醒。同音色提示仍需完整缓存就绪；下载或网页保存成功不代表设备已升级或实机验收通过。

1. 确认设备实际已更新到 17。

   网页出现可更新版本不代表已安装。安装完成后，在设备卡片找到“蓝牙音箱”。它默认关闭，原来的按键聊天和 5 秒手机配网保留。

2. 首次系统准备只做一次。

   在树莓派用原来运行设备程序的普通用户执行下方命令，按提示输入管理员密码。保持设备供电与网络。应用 OTA 不会替你安装系统依赖或授予系统权限。完成后等待设备回报“已准备”；如果系统有其他蓝牙音频服务，脚本会停止并提示冲突。

   cd ~/voice-companion/software
   bash enable_bluetooth_speaker.sh

3. 网页开启，按钮进入。

   在“蓝牙音箱”开启并保存，等待设备回报已应用。长按唯一按钮 9 秒后松开，进入 2 分钟连接窗口。5 秒仍是配网，不要按到 12 秒恢复出厂。网页保存不会自动进入配对。

4. 手机连接，再短按确认。

   在安卓或 iPhone 的系统蓝牙设置中选择设备。听到连接确认提示、核对是自己的手机后，重新短按按钮批准，随后在手机播放音乐。音乐连接不用 Chrome 网页蓝牙。音箱模式暂停麦克风和语音唤醒，最长 2 小时；短按一次退出，清理完成后恢复对话。

5. 音量和能力。

   网页可调音乐音量，仍受设备安全上限和夜间限制。ReSpeaker Lite 使用 16 kHz 重采样，只支持 A2DP 音乐，不支持蓝牙电话或蓝牙麦克风。进入与确认使用聊天音色缓存；缓存未就绪或提示音量为 0 时暂不进入音箱，请联网等待缓存、恢复提示音量。当前尚无实机播放验收，连接失败可短按退出，并用原按键聊天。

1. 断网也能用的固定短句。

   candidate.16 使用设备内的有限中文指令与固定回复，可以说“陪我聊聊”“讲个笑话”“讲个故事”“调大音量”或“不用了”。它不是能自由问答的本地 AI，离线时不能查询天气、新闻等实时信息。跟进仍由原有“连续对话”开关控制，沉默或结束语会结束这轮聊天。双击实体按键可静音并结束对话；再次双击解除静音。联网时会分批准备当前聊天音色的离线短句缓存。

2. 用一个按键进入手机配网。

   已绑定设备长按原有按钮 5 秒后松开，听取设备播报的随机 16 位应用临时码。不要一直按到 12 秒，那是恢复出厂操作。安卓手机用 Chrome 打开 手机蓝牙配网，连接设备、输入本次临时码和目标 Wi-Fi；设备无需先联网。临时码不是 Android 蓝牙 PIN。iPhone 或不支持网页蓝牙时，在这个配网窗口内双击按钮改用热点；听取热点名称和密码、连接后打开 http://10.42.0.1:8765/。

3. 提交新网络，再在设备上确认。

   在手机页面填写新的家庭 Wi-Fi 或手机热点名称、密码，提交后短按一次设备按钮确认。配网保留原账号绑定。需要放弃时长按 2 秒后松开退出；超过 5 分钟未完成，会退出配网并尝试恢复旧网络。外出使用手机热点时，新热点必须保持开启。

4. 首次启用的系统准备。

   手机配网需要树莓派现有蓝牙、Wi-Fi、BlueZ、NetworkManager 和本地服务权限。已完成权限准备的设备可直接使用；旧设备首次启用须先在设备程序目录执行一次 bash enable_phone_wifi.sh。单纯下载更新不能代替系统权限准备。配置和安装结果以设备回报为准；设备暂时不在线时，网页不能替它切换网络。

1. 确认先前已成功安装 .3，再下载解压。

   本包不能代替 .3 完整更新，其他版本请勿安装；安装器不会自动核对这一先决条件。ZIP 共 27081 字节，SHA-256 为 121bc103db904b85ca4fe449208812fa74874ae9d0c914461fb339be5aa5e93e。它修正麦克风尚未开始收音就显示提示、有限识别格式被拒绝，以及三条中一条无效导致整体取消的问题；仍保留独立正例、负例验证，不能保证所有漏唤醒都已解决。

2. 从 Windows 复制小补丁，再登录树莓派。

   在能看到解压后 acexia-calibration-fix-20260928 文件夹的位置打开 PowerShell。先替换下面的用户名与树莓派 IP，不要原样执行占位符：

   scp -r .\acexia-calibration-fix-20260928 用户名@树莓派IP:~/
   ssh 用户名@树莓派IP

3. 在树莓派停止程序并安装。

   其他窗口若正在聊天或测试，先按 Ctrl+C。下面的命令只在已登录的树莓派执行：

   sudo systemctl stop voice-companion

   确认服务已停再安装；保持供电，安装器不要加 sudo，本次无需 --respeaker：

   python3 ~/acexia-calibration-fix-20260928/apply_update.py

   保存本次输出的 Backup: 路径。只有看到 Patch installed. 才继续；出错时不要重新绑定或反复安装。

4. 重新校准，再测试。

   cd ~/voice-companion/software
   .venv/bin/python companion.py wake-calibrate

   每次回车后，等屏幕出现“收音已准备好，现在请说话”再开口。前 3 段建立读法、后 2 段重新试喊，最后 2 段按屏幕提示说其他话。校准只在本地处理，不上传录音。失败时保留新的分类提示，不要把补丁安装成功视为唤醒已修好。

   校准成功后运行：

   .venv/bin/python companion.py wake-test --configured

   独立测试成功后，按下方 .3 指南试听聊天和提示音，再恢复自启。此补丁本身不会启动聊天或调用收费服务；它不是签名 OTA，没有断电自动回滚。需要恢复时使用本次真实 Backup 路径和本包安装器的 --restore。

1. 下载并核对补丁。

   下载上方“同音色提示与唤醒更新”并解压。ZIP 的 SHA-256 为 7901ca6d996ba7015613d7de9c5d476ba9abcf25dc10e7be95a3cb075490efab。本补丁仅用于已有设备程序、Python 依赖与唤醒模型的树莓派；首次使用先完成下方安装流程。

2. 从 Windows 复制，再登录树莓派。

   在解压后能看到 acexia-wake-general-20260928 文件夹的位置打开 PowerShell。先将下面的“用户名”和“树莓派IP”替换为自己的实际信息，再执行，不要原样复制占位符。IP 可在路由器的已连接设备中查看；升级不需要改主机名。

   scp -r .\acexia-wake-general-20260928 用户名@树莓派IP:~/
   ssh 用户名@树莓派IP

   出现树莓派的命令提示符后再继续。以下命令都在树莓派上执行；Windows 提示 sudo 已禁用，说明还没有登录设备。压缩包内若出现用户名或内网 IP 示例，也须换成自己的设备信息。

3. 停程序，再安装。

   先在其他前台音频程序中按 Ctrl+C，然后停止后台服务。只有“找不到服务/服务未加载”可继续，其他错误先处理。

   sudo systemctl stop voice-companion

   保持供电，安装器不要加 sudo：

   python3 ~/acexia-wake-general-20260928/apply_update.py --respeaker

   保存输出中 Backup: 后的真实路径，看到 Patch installed. 才继续。--respeaker 为现有 ReSpeaker Lite 设置稳定音频名称；凭据、模型和其他配置保留。

4. 校准当前网页名字，再独立测试。

   网页开启“本地语音唤醒”，只填写英文名；后台保持停止。按提示录三段读法、两段独立验证和两段其他话。七段音频仅在设备内存中处理，不保存、不上传；校准期间不要改名或解绑。

   cd ~/voice-companion/software
   .venv/bin/python companion.py wake-calibrate

   看到“本地发音校准已保存”后，运行：

   .venv/bin/python companion.py wake-test --configured

   改名、重新绑定或更换模型后需重新校准。测试没有识别成功就先保留输出，不要把有收音强度当作成功；按键仍可使用。

5. 试听同音色提示与聊天。

   GPIOZERO_PIN_FACTORY=lgpio .venv/bin/python companion.py run --device --gpio

   先短按按钮，听到“我在”再说话。设备后台会准备所选对话音色的七段固定提示；出现“完整七段已校验并缓存”后，再试听“我在”“正在处理”和回答的音色。启动提示在下次启动试听。准备完成前可能仍用系统提示；首次合成可能消耗少量 TTS 费用，之后从本地缓存播放，唤醒时不联网合成。不要删除缓存反复生成。

6. 恢复开机自启，并在重启后实测。

   前台验证完成后按 Ctrl+C，再逐行运行：

   bash enable_device.sh
   sudo reboot

   重启联网后，实际检查按钮、唤醒词、录音、AI 回答和提示音色。服务显示 active 不代表所有功能通过。出错时按包内《安装说明.md》恢复；应用备份不包含系统服务与 Wi-Fi 配置，本补丁没有签名 OTA、系统 A/B 或断电自动回滚。

1. 准备系统与 Wi-Fi。

   使用 Raspberry Pi Imager 选择 Raspberry Pi 4 和 Raspberry Pi OS Lite 64 位，设主机名 acexia、用户名 ace、自己的密码与 Wi-Fi，并启用 SSH。写卡会清空所选卡，先核对目标；已有可用系统不用重刷，下面换成自己的用户名和主机地址。

2. 连接主板，准备程序目录。

   写卡校验完成后安全弹出，把卡插入主板并接 5V 3A 电源。电脑和主板连接同一路由器。在电脑 PowerShell 执行第一行，登录后再执行后两行：

   ssh -l ace acexia.local
   mkdir -p ~/voice-companion
   exit

   首次连接先核对主机指纹。输入密码时不显示字符是正常的；找不到 .local 时，用路由器里的树莓派 IP 替换。

3. 复制新版程序，检查主板环境。

   解压下载包，在能看到 software 文件夹的位置打开 PowerShell，执行下面两行。不要复制旧凭据、.env 或 .venv：

   scp -r -o User=ace .\software acexia.local:~/voice-companion/
   ssh -l ace acexia.local

   登录树莓派以后，再执行：

   cd ~/voice-companion/software
   bash install_pi.sh
   .venv/bin/python companion.py doctor
   .venv/bin/python companion.py dry-run
   bash install_wake.sh

   用普通用户运行安装脚本。没有声音板也能完成 doctor、dry-run 和模型下载；前两项不录音、不调用云服务，安装离线模型会联网下载并验证 SHA-256。暂时没有声卡的报告是正常的，不能据此认为语音聊天已可用。

4. 接好现有按键与音频，再做本机录放音。

   先 sudo poweroff 并断电。按包内 INSTALL_PI_V2.md 接好按钮常开触点、ReSpeaker Lite 和喇叭，再开机；没有确认按键接线时，先停在准备阶段。登录后查看音频编号，在 .env 里设置 INPUT_DEVICE、OUTPUT_DEVICE，采样率保持 16000、BUTTON_GPIO=17，云 Key 留空：

   cd ~/voice-companion/software
   .venv/bin/python companion.py devices
   nano .env
   .venv/bin/python companion.py audio-test

   录放音只在本机运行，不上传。没有麦克风或喇叭，不能完成真实语音对话验收。

5. 等待新版开启，再用安卓 Chrome 添加设备。

   确认本页显示“一键配对已开启”。在树莓派 SSH 窗口停止旧服务，再运行设备模式；服务尚不存在时可忽略第一行报错：

   sudo systemctl stop voice-companion
   .venv/bin/python companion.py run --device --gpio

   未绑定时长按已有按键 5 秒后松手。安卓开启蓝牙，在 Chrome 登录本页，点击“一键添加”并选择 Acexia 设备；无需先在安卓系统蓝牙页面配对。

   设备收到认领后，前台 SSH 会显示账号，后台会用喇叭播报。核对是自己的账号后，等提示完成，再重新短按一次实体按钮。没有声卡时只可由你在前台 SSH 看清账号后确认；后台播报失败不能继续确认，日志不能代替播报。

   也可以在前台运行 .venv/bin/python companion.py pair-v2 代替首次长按开窗，但仍须核对账号后新的实体短按。没有接好按钮，不能用键盘或网页点击绕过确认。

6. 检查连接，测试本地唤醒和真实聊天。

   需要运行其他命令时先 Ctrl+C 退出前台程序，避免同时抢占麦克风和 GPIO：

   .venv/bin/python companion.py config
   .venv/bin/python companion.py wake-test --name Aven

   说“HI Aven”进行本地测试，这一步不上传音频、不调用收费 AI。测试后按下方命令重新启动设备模式，再在网页开启唤醒；“AI 英文名”只填 Aven，不用再填 HI。先保留按键，等待约 30 秒配置同步；看到“设备已接收当前设置”和本地唤醒就绪后再试。更换名字需本地引擎支持，并重新在设备上测试。

   正在确认语音服务状态…

   听到提示音再说问题；暂不支持在回复播放过程中语音打断。实际聊天会使用云服务额度。

7. 验收通过后再启用开机自启。

   前台配对、录放音、需要的本地唤醒与至少一轮真实聊天成功后，先 Ctrl+C 退出前台，再运行：

   bash install_service.sh
   sudo systemctl enable --now voice-companion
   sudo systemctl status voice-companion --no-pager

   脚本会使用实际用户名和安装路径，不需要手动替换配置里的用户名。不要同时运行前台和后台。重启后再实测；设备通电联网且服务正常时，电脑和网页可关闭。故障后服务不会自动反复重试，修复后再手动启动。

1. 先让未绑定设备进入待配对。

   长按设备已有按键 5 秒。手机 / 电脑连接同一 Wi-Fi，点击下方“同一网络连接”；若 .local 无法解析，在路由器找到设备地址后打开 http://设备IP:8765。

2. 从设备本地页返回本站。

   本地页只转交本次临时配对信息，不要求输入网站密码。回到 HTTPS 的 acexia.xyz 后，登录并点击“认领这台设备”，再短按设备确认。首次登录如果离开本页，请重新从本地设备入口回来。

公开 HTTPS 网页不能自动扫描整个 Wi-Fi 网络。网页蓝牙通常需要 Android / 桌面 Chromium 浏览器；iPhone / iPad 的浏览器请使用同网入口。网络隔离、蓝牙权限或多台同名设备会影响发现，届时使用设备实际 IP。