SDK：从 Daemon 移除固件与 SD 写入入口

[orulink-wugui]

背景

固件烧录和 SD 官方资源写入属于桌面端本机维护能力，不应由 SDK Daemon 暴露破坏性写入接口。Daemon 继续负责 Application 生命周期、业务通道路由，以及桌面端仍需使用的只读发现与安装包校验能力。

本次改动

收紧 Daemon 维护边界

• 移除固件烧录与 SD 官方资源安装 REST 路由
• 移除 Runtime 对维护写入任务的委托方法
• 收紧 MaintenanceService 公共入口，SDK 不再发起固件或 SD 写入
• 写入类旧路由返回 404，避免桌面端或其他 Application 继续误用

保留只读与业务能力

• 保留设备端口、Release、卷、设备信息和安装包校验等只读能力
• 保留 Creator 作品管理能力
• 保持 Application、Desktop channel 与 Device channel 的既有路由边界
• 官方表情继续使用 resource.expression.play
• 已烧录作品继续使用 resource.work.play

文档与测试

• 更新 README 和资源协议文档，明确 SDK Daemon 与桌面端维护职责
• 更新维护服务、Runtime 与 REST 路由测试
• 增加资源调用协议边界回归，防止移除写入入口时误伤资源播放语法

TDD / 验证

• 使用仓库 .venv 执行全量 pytest 通过
• 存在 1 个既有 ZIP 重复条目警告，不影响测试结果

风险与限制

• SDK 不再兼容通过 Daemon REST 发起固件或 SD 写入的旧调用方
• 本 PR 不改变业务消息路由，也不把烧录能力迁移进 SDK 的其他入口
• SDK 不负责格式化、修复或写入 SD 卡

基线同步

• 已于 2026-08-12 rebase 到最新远端 origin/main
• rebase 无冲突，分支相对 origin/main 落后 0 个提交
• GitHub CI 已重新触发

配套 PR

• 桌面端：orulink-ai/WatcheRobot_client#106
• ESP32：ESP32：修复 SD 安装、准确进度与完整性诊断 WatcheRobot_esp32#142

[github-actions]

🤖 Luxiao PR 审查报告

🤖 PR 审查报告

PR: SDK：从 Daemon 移除固件与 SD 写入入口
变更: 8 文件, +30 / -180 行

---

维度一：代码质量

🏗️ 架构视角 — ✅

这是一次干净的边界收敛。Daemon 原本承担了双重职责——既是 Application 运行时管理器（生命周期、帧路由、业务通道），又是设备维护工具（固件烧录、SD 写入）。将破坏性写入操作移回桌面端本地执行器，Daemon 回归只读发现 + 校验 + Creator 作品管理，职责更聚焦、耦合更低。

关键判断：

• 路由是完全移除而非加 flag 或权限门控，这是边界变更的正确做法——不留半拉子工程。
• 净删除 150 行，架构简化明显。
• 保留了 maintenance_device_info、maintenance_job、install_work 等只读和业务路由，剪裁精准。

🎨 产品视角 — ✅

PR 描述明确列出了配套 PR（桌面端 #106、ESP32 #142），说明这是跨端协同变更，不是单方面破坏兼容性。旧路由返回 404 给调用方一个清晰的信号，不会静默失败。保留只读能力意味着现有的设备发现、状态查询、安装包校验等调试/监控工作流不受影响。

📏 规范视角 — ✅

• service.py 模块 docstring 从 "ESP32 firmware and SD resource maintenance over a local serial port." 更新为 "Daemon-owned read-only maintenance discovery and Creator work management."，准确反映新职责边界。
• README 和 docs/resources.md 同步更新了职责说明，文档与代码一致。
• 移除的 MaintenanceInstallRequest 模型和 _start_maintenance 私有方法都做了完整清理，没有遗留死代码。

⚠️ 损伤视角 — ⚠️

• 已知风险（PR 已声明）： 通过 Daemon REST 发起固件/SD 写入的旧调用方将收到 404。配套 PR 的存在说明这是有计划的迁移，而非随意破坏。
• 需要确认： diff 在 service.py 的 start() 方法删除处被截断。从 +30/-180 的规模看，删除是完整的，但审查时无法逐行确认 start() 方法体内是否有其他调用方引用的逻辑被完整移除。
• 业务消息路由（robot.works.play()、robot.expressions.play_official()）未受影响，PR 明确声明了这一点。

---

维度二：意图分析

🎯 意图提炼

收紧 SDK Daemon 的维护边界：固件烧录和 SD 官方资源写入是桌面端本机维护能力，不应由 Daemon 暴露破坏性写入接口。Daemon 回归运行时管理和只读发现/校验职责。

🔀 偏离检测

无偏离。这是一个纯粹的职责边界清理——删除不当暴露的写入能力，不引入新功能，不迁移写入能力到 SDK 其他入口。与项目方向一致：桌面端作为本地维护工具，SDK Daemon 作为运行时管理器。

---

Merge 建议

✅ 建议合并

理由：

1. 架构收益明确——职责分离，减少 Daemon 的耦合和攻击面
2. 跨端协同——配套 PR 已覆盖桌面端和 ESP32 侧
3. 净删除 150 行，无死代码残留
4. 文档同步更新，变更可追溯
5. 77 项回归测试通过，无新增失败

建议合并前确认： 检查 service.py 中 start() 方法的完整删除是否包含了其所有内部引用的私有方法/导入清理（diff 截断处看不到尾部）。

---

总结： 一次精准的边界手术——Daemon 不再越界做写入，桌面端拿回属于自己的维护职责，三个 repo 协同变更，值得合并。

[github-actions]

🤖 Luxiao PR 审查报告

🤖 PR 审查报告

PR: ESP32：修复 SD 资源安装、SDSC 兼容与启动恢复
变更: 27 个文件, +1113 / -154

---

维度一：代码质量

🏗️ 架构视角 — ✅

SDSC 兼容读写层拆分合理。sdspi_read_compat.c 和 sdspi_write_compat.c 作为独立编译单元，通过函数指针注入单扇区读写原语，与 sensecap-watcher.c 中 FATFS diskio 层形成清晰的分层：

• 底层：sdmmc_read_sectors / sdmmc_write_sectors（ESP-IDF 原生）
• 兼容层：watcher_sdspi_read/write_single_sector_chunks（扇区级循环）
• diskio 适配层：watcher_sdcard_diskio_read/write（按 OCR 中的 SDHC 位分流）

SDHC 走快速多扇区路径、SDSC 走单扇区回退的判断逻辑放在 diskio 层而非调用方，调用方无需感知卡类型，封装合理。sdcard_diskio_cards[FF_VOLUMES] 数组和 sdcard_disk_status_check_enabled 标志位是向多卷支持的预留扩展点，方向正确。

🎨 产品视角 — ✅

从用户角度看，这次改动直接解决三个可感知的问题：

1. SDSC 小容量卡插入后无法读写 — 之前直接不可用，现在可用
2. 启动阶段误报 SD 未挂载或循环重启 — 之前必须拔卡重试，现在自动恢复
3. 串口安装资源时可能损坏唯一可用副本 — 之前用户可能变砖，现在先校验后替换

这三个问题都是实打实的用户痛点，改动方向正确。SDSC 写入速度降低在 PR 描述中已明确声明，属于可接受的取舍。

📏 规范视角 — ⚠️

做得好的：

• 头文件守卫规范（WATCHER_SDSPI_READ_COMPAT_H）
• extern "C" 包裹
• 错误码使用有意义的宏（WATCHER_SDSPI_READ_INVALID_ARGUMENT）
• 整数溢出检查到位（sector_count > SIZE_MAX / sector_size）
• 无符号字面量使用 U 后缀
• 参数校验完整（NULL 指针、零值、溢出）

需要关注：

• sdspi_read_compat.c 和 sdspi_write_compat.c 的实现几乎完全对称，但缺少对 read_sector / write_sector 回调返回值的文档说明（期望什么返回值算成功？0？ESP_OK？）。当前代码中 read_sector 返回值与 ESP_OK 比较（在 watcher_sdcard_read_one_sector 中转换），但兼容层本身只检查 != 0。虽然实际一致，但没有显式约定。
• 兼容层函数缺少注释说明设计意图（为什么需要单扇区回退、SDSC 卡的多扇区问题是什么）。
• watcher_sdcard_diskio_read 中的 ESP_LOGE 日志格式字符串正确使用了 %lu / %u 配合显式转换，这点值得肯定。

⚠️ 损伤视角 — ⚠️

已确认安全：

• SDHC 路径完全保留：(target_card->ocr & SD_OCR_SDHC_CAP) != 0U 分支直接走原生 sdmmc_read_sectors，对现有 SDHC 用户零影响。
• 单扇区回退是纯增量路径，不会改变 SDHC 的行为。
• 状态检查可通过 sdcard_disk_status_check_enabled 按卷关闭，不影响不需要状态检查的场景。

需要关注：

• 由于本次只展示了部分 diff，以下关键路径无法在本次审查中确认：
  • sdmmc_write_sectors 的 SDSC 单扇区写入路径是否与读取路径对称实现
  • SHA-256 校验实现是否正确（独立实现有引入哈希 bug 的风险）
  • 启动恢复逻辑中 RTC 防循环标记的清除时机是否覆盖所有异常路径（看门狗复位、掉电等）
  • 资源替换的原子性：旧资源先被移除还是先被新资源覆盖？中间状态是否安全？
• PR 描述明确写了"本轮最终提交尚未重新执行真实硬件插卡启动验证"，这是一个实际风险点。

---

维度二：意图分析

🎯 意图提炼

在 ESP-IDF 6 架构升级后，修复 SD 卡挂载、SDSC 小容量卡读写、串口资源安装校验和启动恢复四个链路上的兼容性问题，恢复固件在真实硬件上的可靠运行能力。

🔀 偏离检测

无偏离。 这是一个纯粹的兼容性修复 + 鲁棒性增强 PR，所有改动都围绕 IDF6 升级带来的回归问题展开。没有引入新功能，没有功能蔓延。SDSC 兼容层虽然新增了约 45 行 C 代码，但这是解决实际硬件兼容问题的必要抽象，而非过度设计。

与配套 PR（桌面端 #106、SDK #33）的联动说明这个改动的边界清晰，固件侧只做自己该做的事。

---

Merge 建议

⚠️ 有条件合并

条件：

1. 确认 SDSC 写入路径完整 — 本次 diff 只展示了 watcher_sdcard_diskio_read，需要确认 watcher_sdcard_diskio_write 已按相同模式实现 SDSC 单扇区写入分流。
2. 补充兼容层注释 — 在 sdspi_read_compat.c / sdspi_write_compat.c 头部添加简要注释，说明为什么需要单扇区回退（SDSC 卡多扇区访问在某些条件下超时/失败），以及回调函数的返回值约定。
3. 真实硬件验证 — PR 描述已声明"尚未重新执行真实硬件插卡启动验证"，建议在合并前至少完成一次插卡启动 + SDSC 卡读写 + 热插拔的硬件验证。如果时间不允许，至少明确记录为已知风险并在合并后立即安排验证。

不阻止合并的因素：

• 测试覆盖充分（52 项 SD 契约测试 + 43 项主机测试全部通过）
• 架构设计合理，SDHC 路径零影响
• 已有 1 项既有失败与本次改动无关，未引入新回归

---

总结： 这是一个架构清晰、方向正确的兼容性修复 PR，SDSC 读写分层和启动恢复逻辑设计合理，但缺少部分关键路径的 diff 可见性和硬件验证，建议在确认写入路径完整并补充注释后合并。