米执事 · Mi Butler

把小米云台摄像头变成家里的值班管家。

没人时看家，有人时照看，养宠时记录。
画面在本机分析，有事才叫你。

三种场景 · 怎样工作 · 调度 · 快速开始 · 回复指令 · 开源组件 · 代码架构 · 常见问题

米执事（caregiving-eye）是一套在家里电脑上运行的视觉照护工具。它接入小米云台摄像头，同时分析画面和声音，并根据家里有没有人切换值班重点：没人时防火防盗；有人时留意跌倒、突发不适和孩子的安全；养宠物时记录它一天去了哪里、活动了多久。

不刷固件，不改硬件。视频和声音只在局域网内传输、在本机分析；登录和连接摄像头时，仍需向米家云端换取流密钥。

三种场景，执事都在做什么

所有模式都会把事件写进本地记录，重要事件附快照和前后约 25 秒的短视频。运行 python main.py report 可以生成日报，内容包括当天事件、宠物与家人的活动总结和热力图。各模式具体启用哪些能力，见 接入指南。

所有判断都由规则和开源模型组合完成，需要按自家机位标定区域、校准阈值，可能误报或漏报。它不能替代专业监护设备或消防报警设备。

执事怎样工作

摄像头的画面和声音经局域网进入家里的电脑，先由“看”和“听”两路模型识别，再交给各项能力判断。能力只上报信号，最后由研判层决定要不要提醒你。

%%{init: {"theme": "base", "themeVariables": {"fontFamily": "PingFang SC, Microsoft YaHei, sans-serif", "fontSize": "15px", "lineColor": "#9C8B7A", "primaryTextColor": "#302923", "clusterBkg": "#FBF8F4", "clusterBorder": "#D8CCBE", "edgeLabelBackground": "#FFFFFF"}, "flowchart": {"nodeSpacing": 30, "rankSpacing": 34, "padding": 14}}}%%
flowchart TB
    cam(["📷 小米云台摄像头<br/>画面 + 声音"])
    cloud(["☁️ 米家云端<br/>只用于登录、换密钥"])

    subgraph PC["💻 家里的电脑"]
        direction TB
        bridge["🔌 拉流桥<br/>go2rtc + onvif<br/>取画面、控制云台"]
        brain["🧠 调度<br/>按警觉等级分配算力"]
        see["👁️ 看<br/>人、猫狗<br/>姿态、烟火"]
        hear["👂 听<br/>报警器、碎裂<br/>哭喊、嘶叫"]
        skill["🧩 能力<br/>跌倒、不适、儿童<br/>入侵、宠物活动"]
        butler{{"🎩 研判<br/>合并、升级<br/>催办、学误报"}}
        bridge --> see & hear
        brain -.-> see & hear
        see & hear --> skill
        skill -- 信号 --> butler
    end

    log["📒 本地记录<br/>快照、短视频、日报"]
    bot["📱 手机提醒（可选）<br/>飞书 / 微信 / QQ<br/>可回复指令"]

    cam == 局域网 ==> bridge
    cloud -.-> bridge
    butler --> log
    butler -. 转发 .-> bot

    classDef device fill:#F3EEE7,stroke:#BAA58D,stroke-width:1.5px,color:#302923
    classDef cloudc fill:#FFFFFF,stroke:#BAA58D,stroke-dasharray:4 3,color:#7A6A5A
    classDef step fill:#FFFFFF,stroke:#C9B9A6,stroke-width:1.2px,color:#302923
    classDef core fill:#742A38,stroke:#5A1F2B,stroke-width:2px,color:#FFFFFF
    classDef gate fill:#FBF3E4,stroke:#B08D57,stroke-width:1.5px,color:#302923
    classDef result fill:#EAF0EB,stroke:#819888,stroke-width:1.2px,color:#23352B
    classDef optional fill:#FFFFFF,stroke:#819888,stroke-dasharray:4 3,color:#4E6556

    class cam device
    class cloud cloudc
    class bridge,see,hear,skill step
    class brain gate
    class butler core
    class log result
    class bot optional

调度：省算力，长期跑

能力一多，就要决定每一刻跑哪些模型、跑多快。这部分由调度层（mibutler/brain/）负责：

完整的值班表和设计说明见 执事的大脑。

值班模式自动切换

执事根据画面里有没有人、有没有宠物自动换班，也可以按日程（如 23:00–07:00 夜间）或一条指令切换。优先级是：指令 > 日程 > 自动。自动切换带防抖，不会因为一两帧画面来回切。

%%{init: {"theme": "base", "themeVariables": {"fontFamily": "PingFang SC, Microsoft YaHei, sans-serif", "fontSize": "14px", "lineColor": "#9C8B7A", "primaryColor": "#F3EEE7", "primaryBorderColor": "#BAA58D", "primaryTextColor": "#302923"}}}%%
stateDiagram-v2
    direction LR
    state "🧓 在家照护" as HOME
    state "🛡️ 无人值守" as AWAY
    state "🐱 宠物模式" as PET
    state "🌙 夜间加强" as NIGHT
    [*] --> HOME
    HOME --> AWAY: 10 分钟没看到人
    HOME --> PET: 10 分钟只剩宠物
    AWAY --> HOME: 有人出现 2 分钟
    PET --> HOME: 有人出现 2 分钟
    AWAY --> PET: 只看到宠物
    HOME --> NIGHT: 到达夜间日程
    NIGHT --> HOME: 日程结束

    classDef away fill:#43566B,stroke:#2F3D4C,color:#FFFFFF
    classDef home fill:#742A38,stroke:#5A1F2B,color:#FFFFFF
    classDef pet fill:#B08D57,stroke:#8A6C3F,color:#FFFFFF
    classDef night fill:#302923,stroke:#1E1915,color:#F3EEE7
    class AWAY away
    class HOME home
    class PET pet
    class NIGHT night

提醒分级

同一个人的跌倒、久卧、不适会合并成一个事件，只在级别升高时再提醒；急报没人回复时，每 3 分钟催一次。火情、突发不适这类判断要多个信号互相印证才升级，以减少误报：

%%{init: {"theme": "base", "themeVariables": {"fontFamily": "PingFang SC, Microsoft YaHei, sans-serif", "fontSize": "13px", "lineColor": "#9C8B7A"}}}%%
flowchart LR
    v1["画面：持续出现烟火"]:::sig --> q1{同时听到<br/>报警器声？}:::gate
    v1 --> q2{持续<br/>15 秒以上？}:::gate
    q1 -- 是 --> crit(["〔急报〕火情"]):::crit
    q2 -- 是 --> crit
    q1 -- 否 --> guard(["〔值守〕疑似烟火<br/>继续观察"]):::guard
    a1["声音：烟雾报警器"]:::sig --> crit2(["〔急报〕听到报警器"]):::crit

    classDef sig fill:#FFFFFF,stroke:#C9B9A6,color:#302923
    classDef gate fill:#F3EEE7,stroke:#BAA58D,color:#302923
    classDef crit fill:#742A38,stroke:#5A1F2B,color:#FFFFFF
    classDef guard fill:#EAF0EB,stroke:#819888,color:#23352B

快速开始

[!TIP] 建议交给自己电脑上的本地 AI agent（如 Claude Code、Codex、OpenClaw 等）来部署：把本项目链接 https://github.com/JuneYaooo/caregiving-eye 发给它，它会自己读文档、检查环境、安装依赖并完成接入。整个过程需要访问本机文件、局域网摄像头和米家账号，所以要用跑在本机的 agent，不要用云端的。

运行 agent 的这台电脑要和摄像头连在同一个局域网（同一个路由器 / Wi-Fi）下：拉视频流、转云台、扫描摄像头 IP 都只在局域网内进行，不在同一网络时 agent 找不到摄像头。

已实测设备：小米智能摄像机 3 云台版，其他机型和固件版本还需要验证。完整的接入流程按 Windows x64 + Python 3.9+ 编写。

依赖、模型和 RTSP 视频流准备好以后，在仓库根目录运行：

# 1. 先确认视频流和模型正常：读几十帧，打印帧率和检测结果
python main.py check --source rtsp://127.0.0.1:8554/living

# 2. 启动执事（启动日志会列出值班表和实际启用的能力）
python main.py run --source rtsp://127.0.0.1:8554/living

# 也可以用自家录像回放来校准区域和阈值
python main.py run --source my_living_room.mp4

# 3. 随时生成今天的日报：事件 + 宠物 / 家人活动 + 热力图
python main.py report

调好以后改用守护模式长期值守：python main.py serve 会连同 go2rtc、云台桥一起拉起，任何一个崩溃或卡死都会自动重启并通知你；scripts\windows\install_autostart.ps1 可以设成开机自启。详见 长期运行。

火焰烟雾、声音事件和 ByteTrack 跟踪是可选能力：放好对应模型或装好依赖就会自动启用，缺了就跳过，不影响其他功能。下载方式见 可选模型。

main.py             命令行入口：run / serve / health / check / login / devices / ptz / report / cmd
mibutler/
  app.py            组装：模型、服务、能力；信号交给研判层；主循环
  duties/           值班任务（值班表在 duties/__init__.py）
  brain/            调度、拉流、警觉等级、事件研判、云台、保养、守护
  abilities/        能力：跌倒、不适、儿童、火焰、声音、活动、作息、存证
  vision/           YOLO 推理、跟踪器
  camera/           米家登录、设备查询、局域网发现、ONVIF 云台
  butler.py         值班模式、提醒措辞、推送、主人指令
  report.py         日报
scripts/            跌倒模型训练、Windows 启动与自启脚本

提醒和回复

提醒默认只写进本地记录 events/alerts.jsonl。如果想在手机上收到提醒，可以配合 OpenClaw、Hermes、WorkBuddy、ZCode、Claude Code、Codex 等 AI 工具，读取这个文件并转发到飞书、微信或 QQ。本项目不内置这些平台的机器人，接入方式参考 OpenClaw 消息渠道 和 Hermes 消息网关，细节见 接入指南。

执事运行时会在本机开一个指令入口 http://127.0.0.1:8766/command，只监听本机，不对局域网开放，并且必须带口令：首次启动时自动生成在仓库根目录的 .command_token（已被 Git 忽略），也可以在 .env 里用 COMMAND_TOKEN 指定。这样你打开的网页无法偷偷发“是我”“静音”把提醒关掉。机器人收到你的回复后带上口令转发到这里即可，也可以在命令行里直接发（会自动带口令）：

python main.py cmd 没事        # 记为误报，同一位置误报多了会自动降级
python main.py cmd 收到        # 停止催办
python main.py cmd 属实        # 确认是真事件（跌倒样本会标为真跌倒，用于再训练）
python main.py cmd 是我        # 解除入侵提醒，切到在家照护
curl -H "X-Butler-Token: $(cat .command_token)" -d "状态" http://127.0.0.1:8766/command

其他指令：看看（立即抓拍）、静音2小时、模式 away、日报。

越用越准：事后才发现的误报、漏报也能补上，执事会记住：

python main.py cmd 没事 09:30              # 那条是误报：计入误报学习（同一位置多了会降一级），跌倒样本标为误报
python main.py cmd 属实 14:20              # 那次是真的：撤销之前的误报记录，跌倒样本标为真跌倒
python main.py cmd 漏报 15:00 有人进来没报   # 有事没提醒：记下来，每周复盘时分析原因

执事没在运行时，这几条会直接写进记录，下次启动生效。这些记录和家庭知识都只存在本机的 events/ 里，不会进 Git。参与开发时建议执行一次 git config core.hooksPath .githooks，开启提交前隐私检查：家里的数据、照片、米家凭据、局域网 IP 一旦被误加进提交，就会被拦下。家里的固定情况（哪里有雕像、门口拍不拍得到、几点起床）记在 events/household.json，标成静物的区域执事立即不再当人看。学习只会让提醒降级，不会让它消失；火情永远不降级。端口由 .env 里的 COMMAND_PORT 设置，设为 0 则关闭入口。

问 AI “今天家里发生了什么”

仓库自带一个 AI skill：.claude/skills/home-review/。在仓库目录里用 Claude Code 直接问即可，它会自动启用；OpenClaw、Hermes 等支持 SKILL.md 的工具，把 skill 目录指到这里就能用。它按问题类型挑方法：

• 总览“今天发生了什么”：先把当天记录压成一页时间线，同一件事的催办合并成一行，并标出误报、属实或未确认，只对没确认的提醒去看快照。
• 核实“那条跌倒是真的吗”：只看那一条的快照和录像。
• 找变化“东西什么时候被动过”：先用进出记录把时间缩到有人在的那几段，再比较前后画面（比纹理不比亮度，不受光线影响），有录像时先粗扫、再二分定位到秒。
• 作息“老人今天起床了吗”：只读活动统计，不看图。
• 复盘“这周怎么样、怎么更准”：统计哪里老误报、哪些没人确认、漏报了什么，给出建议，你同意后它才去改；你在对话里纠正它的话，也会写回补标和家庭知识。

两个脚本也能单独用：scripts/day_digest.py（一页时间线）、scripts/scene_diff.py（画面比对 / 粗扫 / 二分）。图片和记录只在本机处理，未经你同意不会发给外部服务。

用到的开源项目

本项目代码采用 MIT 许可证；模型权重和数据集遵循各自上游的许可证，商用前请自行确认。

实测记录

下表来自项目已有的单设备测试记录，不代表检测准确率，也不代表所有网络环境下的性能。火焰烟雾、声音、儿童、突发不适、宠物活动和调度层目前只用合成画面验证过流程，还没有在真实画面上实测。

使用边界与隐私

• 需要联网取密钥：每次连接摄像头都要向米家云端换取流密钥，目前不是完全离线的方案。
• 不能替代专业设备：火情以烟雾报警器为准，照护以专业监护设备为准。
• 提醒按需接入：默认只记录在本地；接入外部机器人时，可以只转发事件文字，不转发画面。
• 只在可信网络中使用：不要把 RTSP、go2rtc 或 ONVIF 控制端口直接暴露到公网。
• 家庭数据留在本地：账号、凭据、设备清单、家庭画面、录像和区域配置都保存在本机；只在自己家中，或已获得明确同意的场合使用。
• 先校准再使用：遮挡、光线、拍摄角度和云台转动都会影响判断；云台转动后需要重新标定区域。

还没做的：双向对讲（需要带扬声器的摄像头）。设计思路见 能力设计 和 算法设计。

跌倒骨架模型需要在本机训练一次（约 40 分钟，CPU 即可）。训练用的 UR Fall 数据集只允许非商业使用，所以仓库不附带训练好的权重，步骤见 算法设计。不训练也能用，跌倒判断会退回只用姿态规则。