用途：把自写的长期运行应用（轮询器、监控等）部署为 Home Assistant OS 本地插件，在树莓派上 7×24 小时运行，避免依赖会休眠的工作站。仅适用于 HAOS 或 Supervised 安装；Container/Core 没有 Supervisor、没有 /addons、没有 ha CLI，不适用。资料基于树莓派 4（aarch64）、HAOS 17.x–18.1 实机验证。
主要能力与步骤： 一、仓库布局。HA 相关文件放 haos/ 目录，交付时打平，含 config.yaml（name/slug/version/arch/startup/boot/map/init/options/schema）、Dockerfile、run.sh、.dockerignore。改代码后需提升 version 才会被检测为更新。/data 为持久化卷。基础镜像：纯 Python 用 python:3.12-alpine，依赖 onnxruntime/opencv/numpy 等须用 python:3.12-slim。 二、代码投递。设备不克隆仓库，由工作站推送。默认用已提交树：git archive --format=tar HEAD 经 ssh 解包到 /addons/<slug>；也可直接投递工作树做热修，但要显式指定所需路径，且 tar 不读 .dockerignore。部署目录须扁平自包含。特别注意：两个目录不得声明同一 slug，否则 Supervisor 递归扫描时胜出方不确定，会表现为版本不更新、构建旧代码，且 reload、重启、重装均无效。 三、安装：ha store reload && ha apps install local_<slug>；首次构建需数分钟。 四、配置：ha apps 无 options 子命令，可用 HA 网页 Configuration 页或 Supervisor REST API POST http://supervisor/addons/local_<slug>/options。该 POST 是整体替换而非补丁，须先 GET 完整对象再合并回传；password 类型字段会以明文返回，相关文件应 chmod 600。 五、启动与验证：ha apps start、ha apps logs。可在容器内用 docker exec 手动触发测试。
限制与注意事项：ha CLI / Supervisor API 调用需登录 shell 以加载 SUPERVISOR_TOKEN，多步操作须用 bash -l -s heredoc 并在嵌套 ssh 时加 -n；失败只写 stderr，仅取 stdout 会误判为空。SSH 插件 Protection mode 须关闭。禁止同一应用在两台机器同时运行，避免重复请求与令牌互踢。单卡树莓派无冗余，操作前先做完整备份并下载到卡外。容器名前缀（app_ 与 addon_）不应硬编码，须运行时解析。