0.1.197 · 设备协同与音效同步优化

HachimiDock 0.1.197 · 设备协同与音效同步优化

本次更新

• 新增独立音效下发，支持单独更新或移除状态提示音，无需重新传输整套形象视频。
• 优化音效配置入口，将“下发音效”放到 WAV 上传与移除操作旁。
• 优化任务完成提示音的触发逻辑，避免同一任务重复提醒，保留原有提示音效果。
• 优化宠物状态气泡的切换顺序，修复空完成提示和休息状态残留。
• 改进 ChatGPT（Codex）、WorkBuddy、DeepSeek Harness 的语音输入与目标会话处理。
• 改进 Agent 切换、形象同步、USB 连接恢复和固件升级的状态处理。
• 提供统一城市设置和整体音量控制，优化组件安装、素材显示及城市电台播放体验。
• 改进形象生成的动作适配与任务恢复，支持更多外观形态。

下载与升级

• macOS：选择 macOS-arm64.dmg，适用于 Apple 芯片 Mac。
• Windows：选择 Windows-x64-setup.exe，适用于 Windows x64。
• 配套固件为 0.7.103-p4-r178；请先更新客户端和固件，再使用独立音效下发。
• 已有设备建议通过客户端升级固件。完整烧录包用于首次初始化或恢复出厂，会清空设备数据；操作前请备份，并按实际芯片修订版选择 v1 或 v3，二者不可混刷。
• macOS 安装包尚未经过 Apple 公证；Windows 安装包未附数字签名。

附件的 SHA-256 校验值见 SHA256SUMS。许可证与第三方声明已包含在安装包和烧录包中，FFmpeg 对应源码可单独下载。

0.1.168 · 公开维护版

HachimiDock 0.1.168 · 公开维护版

本次变更

• 提供 macOS arm64、Windows x64 客户端及配套 v1/v3 固件 0.7.103-p4-r2。
• 保留现有用户数据和配置。
• 基于上一正常公开版维护，不包含尚未验收的框架改动，也不包含 0.7.108 分支。

下载

• Apple silicon Mac：HachimiDock_0.1.168_macOS-arm64.dmg
• Windows x64：HachimiDock_0.1.168_Windows-x64-setup.exe
• ESP32-P4 v1：HachimoDock-P4-v1_0.7.103-p4-r2_Factory-Flasher.zip
• ESP32-P4 v3：HachimoDock-P4-v3_0.7.103-p4-r2_Factory-Flasher.zip

升级与兼容
现有设备请优先通过客户端固件升级入口更新应用固件，以保留存储数据。
完整 Factory-Flasher 包用于新设备或明确恢复出厂，会擦除设置、形象和组件。请先备份，按实际芯片修订版选择 v1/v3，不可互刷。设备型号中的 M 不代表芯片修订版。
烧录脚本需要 Python 3.10+，使用 esptool 5.4.0，核对芯片后才执行擦除。显示排线连接 DSI，断电后插拔。
请使用与设备芯片修订版匹配的客户端配套固件。

公开版与隐私
本次为正常公开版，不内置服务 Key、内部证书或构建电脑的固定代理。语音及生成服务请使用自己的 API 配置。
发布前对实际安装包、嵌入前端、资源目录和固件包进行隐私与完整性检查；许可证及对应第三方源码保留。检查结果仅覆盖本次发布产物。
各文件校验值及构建来源见 SHA256SUMS 和 release-manifest.json。

验证边界
已执行自动回归、升级兼容测试及实际包体检查。本次没有刷机或清空任何用户设备，没有录音、播放或调用付费模型。
Windows 安装包为跨平台构建，本次未在 Windows 实机运行；部分电脑的 COM 口打开问题仍在排查，本版本不宣称修复该问题。
macOS 包采用本地 ad-hoc 签名，未公证；Windows 安装包未签名。请只从本仓库下载，并核对校验值。

第三方许可
LICENSE、THIRD_PARTY_NOTICES.md、Xiaomi-Miloco-LICENSE.md、Espressif-ESP-SR-LICENSE.txt、sysinfo-LICENSE.txt 与 FFmpeg 完整对应源码随本 Release 提供；各自适用许可不变。

0.1.167 · 语音、每日资讯与形象生成优化

HachimiDock 0.1.167 · 常规对外发布

本版本同步 2026-10-24 已验证修复，基于 0.1.166 功能快照。
本版本不内置语音、豆包或图像/视频服务 Key；使用云端功能前请在 API 配置中填写自己的凭据。
对应功能源码已同步到 main。2026-10-28 清理了公开文档及历史资料，提交和标签指向可能变化；现有安装包、固件及校验附件未替换。旧克隆请重新克隆，勿合并或强推旧历史。GitHub 自动生成的 Source code 按对应清理后的标签生成，最新功能源码请使用 main。

语音与桌面任务

• 统一按键语音和宠物实时对话的输入定位：已有输入框焦点时沿用；无输入框焦点时定位底部主输入框。
• ASR 写入不再等待上一轮写入回执或草稿字数校验；新一轮语音与上轮任务独立。
• 修复任务只写入不发送、发送完成后回执匹配及宠物播报问题；不自动重复派发已提交任务。
• 补充定位、写入、提交、接收和播报的分阶段诊断。

每日资讯与组件

• PC 启动时提前准备每日九条资讯，缓存文字与语音；分类失败仅补失败分类，失败保留上一期可用内容。
• 修复每日新鲜事、每天一本书、每日新知进入自动播放及播放诊断；主动停止后不自行恢复。
• 城市电台进入即播放；修复组件列表进入后闪烁与顺序跳变。
• 固件基于 0.7.103-p4-r1，包含组件资源完整性检查及逐组件恢复，避免单项损坏导致整体回退无图启动版。
• 未引入实验性的 0.7.108 分支。

照片与形象生成

• 补齐 macOS 照片图库兼容读取及分阶段错误诊断。
• 参考主体支持人物与动物；保留身份特征和合理随身道具，清理无关背景和杂物。
• 新增可选风格描述与预览；未填写时采用默认风格。
• 选图后自动生成整套动画；保留已有结果，恢复优先查询已提交任务，避免重复收费。
• 修复失败任务阻断新任务、已有部分成功仍显示笼统失败、JSON 解析及模型参数错误分类。
• 不再把同一张图锁作全部动画的相同首尾帧；每个动作族使用独立首帧，保持同一形象身份，不锁定尾帧。
• 独立首帧策略用于新生成；已有成功动画保留，不会为替换旧结果自动再次收费生成。
• 优化模型选择、默认模型初始化和 404 错误处理。

安装与使用说明

• macOS：ARM64（Apple Silicon）DMG；采用本地 ad-hoc 签名，未进行 Apple 公证。
• Windows：x64 安装程序；本轮通过交叉编译与安装包解包检查，未在实体 Windows 系统运行验收，未做代码签名。
• 两份工厂烧录 ZIP 分别适配 P4 v1 / v3，不可互刷。完整工厂烧录会清空设备数据；日常保留数据升级应使用客户端固件升级。
• 本轮打包没有安装客户端、连接设备、录音、刷机或发起付费模型调用。
• 之前已完成的实机/生成验证沿用同源功能证据；本轮执行新的自动回归、构建和安装包静态审查，不冒充新一轮完整实机验收。
• 发布前请核对 SHA256SUMS 与 release-manifest.json。

0.1.144 · 语音输入与 AI 形象生成修复

Pet Manager 0.1.144

本次只发布安装包与固件资源，不更新仓库源代码。客户端在 0.1.138 稳定版本基础上修复和优化。

更新内容

• 修复 macOS 语音输入框定位、光标位置、连续追加、完整文字写入和确认发送校验问题。
• macOS 配置保存改为本机加密存储，正常使用不再调用钥匙串或出现解锁按钮；修复已填写语音识别配置仍提示未配置的问题。
• 对话、提示词和视频生成模型支持选择；更新豆包 Lite 默认值与 Seedream 5.0 Flash 图片处理默认值，明确模型不存在或无权限的错误，不盲目重试收费请求。
• 形象生成先清理参考图中的手和杂物，再确认参考图、试生成一个动作、确认后生成其余动作；缓存中间结果和已提交任务，减少重复生成。
• 补充生成阶段、耗时和脱敏请求编号诊断，调整提示词与 Seedance 模型参数兼容性。
• 保留 29 个内置组件、PetUI 资源和稳定固件。

下载说明

• macOS：Apple Silicon（arm64）DMG。
• Windows：x64 安装程序。
• 固件：沿用已验证的 0.7.103-p4，提供 P4 v1 / v3 两种 Factory Flasher 包。请按芯片版本选择；本次没有引入试验性 Wi-Fi 固件。
• SHA256SUMS 提供校验值；第三方许可证与所需 FFmpeg 源码归档随 Release 提供。

验证与限制

• 前端测试：792 项通过，1 项跳过；连接桥测试：213 项通过；原生测试：657 项通过，79 项忽略。
• 已实测参考图处理、提示词生成及两个短视频，验证参考图确认、试片确认和恢复流程。
• 安装包解包后进行密钥、个人配置、内部地址、本机路径与资源完整性检查；结果以 release-manifest.json 为准。
• macOS 使用本地签名，未经过 Apple 公证；Windows 包通过交叉编译和内容校验，本轮未在实体 Windows 电脑运行验收。
• API 服务需使用者自行配置，安装包不附带服务密钥。公开社区地址是产品服务配置，不是内网地址。

自动生成的 Source code 链接仍指向仓库既有公开提交，不代表本次安装包源码已上传。

0.1.138 · 组件中心与社区体验更新

0.1.138 · 组件中心与社区体验更新

• 社区详情页迁移到服务端，优化评论、昵称编辑及客户端交互。
• 本地预置 29 个组件和最新 PetUI，更新组件封面、名称、排序与交互资源。
• 同步设备输入、组件运行和连接容错相关改进。
• 客户端内置 ESP32-P4 v1 / v3 应用固件 0.7.103-p4，按芯片版本匹配。

下载

• macOS Apple Silicon：HachimoDock-Pet-Manager_0.1.138_macOS-arm64.dmg
• Windows x64：HachimoDock-Pet-Manager_0.1.138_Windows-x64-setup.exe
• 首次完整烧录：选择与实际芯片匹配的 v1 或 v3 Factory-Flasher.zip。不要混刷或使用强制跳过检查参数。完整出厂烧录会清空设备原有数据；日常升级请优先使用客户端应用固件升级。

公开包与验证说明

• 本次仅发布二进制包，不更新项目源码分支。Release 标签指向已有公开提交，GitHub 自动生成的 Source code 压缩包不是本次二进制对应的完整源码快照。
• 公开构建不注入内部 API 凭据、企业证书或内部代理配置，不包含用户聊天、账户设置及本机私有文件。需要模型等云服务的功能，请自行配置凭据。
• 附带 SHA256SUMS、release-manifest.json 及第三方许可。FFmpeg 对应源码附件用于满足第三方许可要求，不属于本次项目源码更新。
• macOS 使用本地 ad-hoc 签名，尚未通过 Apple 公证；Windows 包未做本轮实体 Windows 机器运行验收。固件完成双芯片构建和主机回归，本轮未重新刷机验收。

0.1.115 · 桌面 Agent 协作优化

哈基米桌搭 0.1.115

• 优化桌面 Agent 任务派发：执行中可插入新指令，不停止原有任务，也不因派发失败自动重复执行。
• 改进 ChatGPT（Codex）与 WorkBuddy 的输入框定位、上下文传递及结果回执关联。
• 同步提供 macOS Apple Silicon、Windows x64 客户端，以及 ESP32-P4 v1、v3 配套固件。

下载与安装

• macOS：下载 macOS-arm64.dmg。本次为本地签名，尚未经过 Apple 公证。
• Windows：下载 Windows-x64-setup.exe。
• 已能连接客户端的设备，优先使用客户端固件升级；全量烧录请根据芯片版本选择 v1 或 v3 的 Factory-Flasher.zip，阅读包内指南。全量烧录会清除设备数据，两个版本不可混刷。
• 对外包不内置服务 API Key 或企业证书，相关能力需自行配置。

本次仅发布二进制安装包及固件，不同步更新仓库源码。标签关联的源码归档不代表本次二进制的完整源码快照。

文件校验值见 SHA256SUMS，构建与验证说明见 release-manifest.json。本次尚未完成 Windows 实机运行及设备刷机验收。

0.1.101 · 桌面组件与交互优化

桌面组件与交互优化

• 优化 PC 与设备组件中心的布局、内置组件顺序和交互。
• 提供敲木鱼、近期待办、电脑状态及自选股行情组件。
• 改进按键语音、实时对话、Agent 状态同步与设备交互。
• 客户端升级至 0.1.101，配套 v1/v3 固件 0.7.72-p4。

下载与升级

• macOS：选择 macOS-arm64.dmg（Apple silicon）。采用本地签名，未经 Apple 公证。
• Windows：选择 Windows-x64-setup.exe。本次已完成交叉构建与安装包完整性检查，尚未完成 Windows 真机运行验收。
• 已有设备建议通过客户端升级固件，保留配置与资源。
• 全新设备可使用对应 v1/v3 的完整烧录包。完整烧录会清除设备数据，请确认芯片版本并先备份。

公开包不预置服务 API Key、企业 CA 或固定代理；使用相关云服务前请自行配置凭据。源码和安装包已进行敏感信息检查，SHA-256 与验证范围见附带清单；自动检查不等同于完整安全审计或所有硬件场景验收。

家居控制能力由 Xiaomi MiLoCo 提供。相关版权、许可证与免责声明见 第三方声明 及随包许可证。

HachimoDock 0.1.82

HachimoDock 0.1.82

Windows x64 / macOS Apple Silicon 公开版，配套 ESP32-P4 v1、v3 的 0.7.64-p4 固件。

更新内容

• 对话大模型名称可编辑；切换服务商读取各自保存的 Key，不再沿用其他服务商的 Key。默认豆包，MiMo 默认 mimo-v2.6-flash。
• 实时对话支持按需联网检索与行情查询，由宠物口语总结，不新增 PC 搜索结果面板。需要自行配置对应服务 Key 和权限。
• 回复期间增加 ASR 二次确认后打断，保留单字“停”。环境声、外部音箱播放及 Windows 场景的间歇性误打断仍在排查，本版不承诺已消除。
• 内置西高地出厂默认音色为「佩奇猪 2.0」。已有音色配置保留，可在人设与声音中手动选择，或按需恢复出厂人设。
• v1/v3 固件同步去掉实时对话固定状态文案的省略号，避免字库显示问号；普通字幕标点不变。
• Tauri 升级至 2.11.1，包含 IPC 来源校验安全修复；双端安装包补齐 ESP-SR 许可证。

隐私与首次使用

公开安装包不内置 API Key、企业 CA 或固定代理地址，不携带打包机器的账号令牌、聊天日志和用户配置。首次使用请在「API 配置」中填写自己的 Key；智能家居需自行授权米家账号。

固件和烧录

• 已在使用的设备：安装客户端后，在「固件升级」中升级至 0.7.64-p4。普通 OTA 保留形象、组件及配置，安装 PC 包不会自动刷机。
• 新板或恢复出厂：下载对应 v1 / v3 的 Factory-Flasher.zip，解压后按 README-FLASHING-CN.md 操作。完整出厂烧录会清除设备数据。
• v1 与 v3 的烧录包不可互刷，具体版本可以咨询客服进行确认。 每种芯片的固件由 Windows/macOS 共用。屏幕接 DSI，不是 CSI；插拔排线前先断电。
• 烧录工具：Python 3.10+、esptool 5.4.0（脚本安装并校验版本）。自行构建使用 PlatformIO Core 6.1.19+，v3 不支持 6.1.18，具体平台依赖见源码 firmware/BUILD.md。

校验与验证边界

提供 SHA256SUMS、release-manifest.json、依赖许可证及 FFmpeg 对应源码。安装包经过实际挂载/解包扫描与固件一致性校验。

本次完成前端、桥接、固件主机及 Rust 回归和双端构建；不等于 Windows 实机语音、所有 v1/v3 板型和声学环境均已验收。macOS 为本地 ad-hoc 签名，未作 Apple 公证；Windows 包未作代码签名。请在确认下载来源和校验值后安装。

家居控制能力来自 Xiaomi MiLoCo；相关版权、许可证及第三方声明随源码与分发组件保留。

HachimoDock 0.1.79

HachimoDock 0.1.79

Windows 与 macOS 客户端现已支持实时对话、自然语言智能家居控制和自选股行情，随包提供 ESP32-P4 0.7.63-p4 的 v1/v3 固件。

本次更新

• 与宠物实时聊天：配置语音服务及对话大模型，在宠物界面长按 SW2 开始，再次长按结束。支持人设、TTS 2.0 音色和蓝色字幕气泡；配套固件支持边听边说、打断当前回复。声学效果受硬件安装和环境影响。
• 自然语言控制家居：在「智能家居」连接米家账号，即可在实时对话中说“播放一首爵士乐”“把客厅灯调暗”等。具体能力以设备和账号权限为准；超过 5 步或保存常用任务时通过语音确认。页面明确标注能力来自 Xiaomi MiLoCo，并精简连接说明。
• 内置自选股行情：组件顺序第一项默认包含小米与阿里；详情页支持中文名称、代码搜索和联想选择。PC 每 2 秒更新，通过 USB 发送到设备；需要保持客户端运行。价格与涨跌幅上涨红、下跌绿，日期在顶部统一显示。行情可能延迟，不支持交易。
• Windows 语音播放：修复同一段话逐字卡顿及设备拒绝音频帧的问题，保留双向收音和打断能力。
• 形象与语音输入：优化内置形象切换；系统提示音不再依赖形象，完成提示为四组、每组三声；Agent 输入框支持多次语音追加。
• AI 生成提示：区分生图和图生视频失败。平台明确拒绝真人素材时给出人像提示；也可使用有权使用的素材自行生成 MP4，再从「形象画廊 → 新建自定义形象 → 自定义上传视频」导入，在详情页补充其他动作。此方式不绕过服务商审核或素材授权要求。

下载与安装

平台 / 用途	文件
Apple silicon macOS	HachimoDock-Pet-Manager_0.1.79_macOS-arm64.dmg
Windows x64	HachimoDock-Pet-Manager_0.1.79_Windows-x64-setup.exe
P4 v1 新机 / 恢复出厂	HachimoDock-P4-v1_0.7.63-p4_Factory-Flasher.zip
P4 v3 新机 / 恢复出厂	HachimoDock-P4-v3_0.7.63-p4_Factory-Flasher.zip

公开包不内置 API Key、企业 CA 或固定代理地址。首次使用请在「API 配置」填写自己的服务凭据；智能家居需自行授权账号。公司网络需要的代理或可信 CA 请遵循所在网络的配置要求。

macOS 使用本地签名，尚未 Apple 公证；Windows 为未做商业签名的 x64 安装包。请先确认下载来源及 SHA256SUMS。macOS 若被隔离标记阻止，确认来源后可执行 xattr -cr "/Applications/Pet Manager.app"。Windows WebView2 首次安装可能需要联网。

v1 / v3 烧录须知

v1 与 v3 的烧录包不可互刷，具体版本可以咨询客服进行确认。 微雪 ESP32-P4-WIFI6-M 名称中的 M 不能用来判断芯片修订版本；每个芯片系列的同一固件同时兼容 Windows 和 macOS 客户端。

1. 日常更新优先使用 PC「固件升级」。完整出厂包只用于新设备或明确恢复出厂，会清除设备设置、形象和组件。
2. 安装 Python 3.10+，解压对应 ZIP。烧录脚本首次运行会创建独立环境，安装并核对 esptool 5.4.0，需要网络；无需安装 PlatformIO。
3. 关闭 Pet Manager，按包内接线说明连接 CH343 USB-UART。屏幕排线须接 DSI，不是 CSI，插拔排线前断电。
4. macOS 运行 tools/flash-macOS.command；Windows 运行 tools/flash-Windows.ps1。选择正确串口并输入 ERASE，工具先检查芯片和镜像版本，再擦除、从 0x0 写入并校验。不要加 --force。
5. 若连接失败，按住 BOOT、短按 RESET/EN，再松开 BOOT 重试。完成后重启，检查动画与 PC 连接。默认烧录速率 921600；日常通信为 4M，两者不同。

两份完整包均包含默认西高地形象、9 个内置组件、分段镜像和校验清单。源码编译工具版本见仓库 firmware/BUILD.md；固件内的构建标识是独立构建快照 ID，公开源码对应关系见 release-manifest.json。

特别说明与感谢：Xiaomi MiLoCo

Xiaomi MiLoCo —— 感谢 Xiaomi MiLoCo 团队开放智能家居能力。本项目家居控制云协议基于其开源 SDK miloco-miot 适配为 Rust 实现，安装包不直接分发完整 Python SDK。

相关 MiLoCo 授权作品的版权归小米所有，适用 Xiaomi Miloco License；版权标识、免责声明和许可证副本随相关实现一并保留。其非商业使用及用途范围限制仍适用，本项目不向第三方授予额外的商业、再许可或商标权限。完整来源和条款见随包及仓库的 THIRD_PARTY_NOTICES.md。

同时感谢 Espressif、DeskBot V2 及其他上游项目。各依赖遵循自身许可证；FFmpeg 对应源码与许可随本次 Release 提供。

验证范围

通过客户端 611 项测试（另 1 项跳过）、Agent 桥接 188 项测试、固件主机侧 134 项测试及 5 项子测试，并完成两端编译、安装包解包/挂载、固件范围与哈希、公开资源隐私检查。实际 Windows 驱动组合、v1/v3 声学环境和全场景硬件验收仍需分别验证，不将编译通过等同于全部实机功能已验收。

HachimoDock 0.1.58

HachimoDock 0.1.58

本次更新

• 修复部分形象播放一段时间、重复循环或切换状态后停在静止画面的问题，适用于 P4 v1 和 v3。
• 改善视频播放缓冲的复用，避免循环播放时破坏原始素材；界面、按键和原有交互不变。
• Mac 和 Windows 客户端均内置 0.7.53-p4 的 v1/v3 固件，按设备实际芯片版本选择。固件按芯片区分，不按电脑系统区分，两端继续共用 4M 运行串口配置。

下载哪个文件？

用途	下载文件
Apple silicon Mac	HachimoDock-Pet-Manager_0.1.58_macOS-arm64.dmg
Windows x64	HachimoDock-Pet-Manager_0.1.58_Windows-x64-setup.exe
v1 芯片：新设备或恢复出厂	HachimoDock-P4-v1_0.7.53-p4_Factory-Flasher.zip
v3.x 芯片：新设备或恢复出厂	HachimoDock-P4-v3_0.7.53-p4_Factory-Flasher.zip

v1 与 v3 的烧录包不可互刷，具体版本可以咨询客服进行确认。 微雪 ESP32-P4-WIFI6-M 的 M 不代表芯片版本，请按实际芯片修订版选择。

安装包不内置服务 Key。语音识别、形象生成等功能，请在“API 配置”中填写自己的 Key。

已有设备怎么升级？

安装新版客户端，连接设备后打开“固件升级”，升级到 0.7.53-p4。普通 OTA 保留形象、用户组件和配置；只更新电脑上的客户端，不会自动替代设备当前运行的固件。

如果提示无法确认芯片版本或固件不匹配，请先确认硬件，不要绕过检查。完整出厂镜像不能作为 OTA 应用文件上传。

安装客户端

macOS

1. 打开 DMG，将 Pet Manager 拖入“应用程序”。当前应用尚未经过 Apple 公证。

2. 下载安装 Mac 应用后，如果无法打开，请先确认下载来源和校验值，再在终端运行以下命令后打开：

   xattr -cr "/Applications/Pet Manager.app"

3. 首次使用会自动弹出授权提示。打开“系统设置 → 隐私与安全性 → 辅助功能”内的 Pet Manager 开关，开通设备语音输入、操控 Agent 的权限。

Windows

运行 x64 安装程序，安装后连接设备；不要只复制主程序 EXE。当前安装程序未进行 Authenticode 签名，可能出现 SmartScreen 提示，请确认下载来源并核对校验值。

新设备 / 恢复出厂烧录

完整烧录会清空设备设置、形象和组件，请先备份，仅用于新设备或明确恢复出厂。

1. 下载匹配芯片的 Factory-Flasher.zip，完整解压并阅读 README-FLASHING-CN.md。包内包含完整镜像、Bootloader、分区表、应用固件、OTA 元数据、西高地形象、8 个内置组件、资源资料、校验清单及烧录工具。

2. 关闭 Pet Manager，避免占用串口。微雪 ESP32-P4-WIFI6 的 USB 数据路径跳线保持断开，使 Type-C 连接 CH343 USB-UART；使用支持数据传输的 USB 线。

3. 屏幕排线接 DSI，不是 CSI。请断电后插拔排线。 摇杆连接后保持居中并重启，以完成启动校准。

4. 安装 Python 3.10+。包内脚本首次运行需要联网，自动安装并检查 esptool 5.4.0；已有旧工具环境也会更新。只烧录成品包不需要 PlatformIO 或 ESP-IDF。

5. macOS 双击 tools/flash-macOS.command。Windows 在解压目录打开 PowerShell，执行以下命令，把 COM5 换为实际串口：

   powershell -NoProfile -ExecutionPolicy Bypass -File .\tools\flash-Windows.ps1 -Port COM5

   执行策略参数仅影响本次进程。macOS 无法双击时，在终端输入 zsh ，把脚本拖入终端后回车。

6. 按提示选择串口，确认需要清空设备后输入 ERASE。工具会先读取芯片版本，与 Bootloader 和应用镜像都匹配后，才擦除、从 0x0 写入完整镜像并校验。

7. 完成后松开 BOOT，按 RESET/EN 或重新上电，再打开客户端检查设备连接、画面和固件版本。

连接失败时：按住 BOOT，短按 RESET/EN，松开 BOOT 后重试。Windows 在“设备管理器 → 端口”查看 COMx；macOS 查看 /dev/cu.wchusbserial*、/dev/cu.usbserial* 或 /dev/cu.usbmodem*。烧录不稳定时，可把脚本中的 921600 改为 460800；烧录速率与运行时 4M 不同。不要使用 --force 绕过检查。

官方工具：esptool 5.4.0。请保留包内的 flash_checked.py、p4_image_compat.py 并使用配套脚本。

自行编译与验证范围

源码位于 pc/、firmware/，克隆后运行 git lfs pull 获取二进制资源。固件编译使用 PlatformIO Core 6.1.19：v1 平台为 55.03.32 / ESP-IDF 5.5.1，v3 为 55.03.38-1 / ESP-IDF 5.5.4；详细命令见构建与烧录指南。不要在同一目录并行编译两种环境。

播放修复已在 v3.2 板完成保留数据升级和多状态持续播放验证。v1 已完成编译与共享播放代码回归，本版尚未完成 v1 实机及 Windows 全流程验收。

可使用 SHA256SUMS 核对附件：macOS 执行 shasum -a 256 <文件名>，Windows 执行 Get-FileHash <文件名> -Algorithm SHA256。附件同时提供版本清单、许可证及相应第三方材料。