Homebase

一款统一的家庭助手，以 OpenClaw 技能形式运行。专为希望将日历、餐食计划、购物清单、学校收件箱和晨间流程集中管理的家庭而设计——无需为每个家庭编写任何代码。

功能

• 晨间简报 — 每日早上 7 点推送天气 + 日程 + 孩子早餐/午餐 + 学校小食摘要；含起飞前健康检查、输出验证、30 天可靠性追踪器。
• 日历 — 支持 Google Calendar 同步 + 自然语言创建事件。
• 儿童餐食 — 基于配置的按儿童定制的早/午/小食轮换方案，支持过敏原与食物质地规则；自动规避历史中重复出现相同餐食的模式。
• 周度餐食规划器 — 每周六晚 6 点生成初稿，家庭成员可通过回复修订，周日晚 9 点自动锁定；最多允许 2 次修订，之后强制自动锁定。
• 学校邮件监控器 — 在上课时段每 2 小时扫描 Gmail，解析学校通知邮件及 PDF 附件，去重后高亮重要事项。
• 收据与媒体监控器 — 发送至 WhatsApp 的收据照片将根据图注关键词分类，再由 OpenClaw agent 的原生视觉能力识别，并记录至按餐厅划分的评分账本中。
• 购物清单 — 按门店（如 “Costco”、“Indian”、“Target”）分组的条目列表，支持原子写入。
• 健康追踪器 — 按儿童记录泰诺/布洛芬用药剂量，内置基于体重的安全剂量上限与最小用药间隔强制校验。
• 行程检测器 — 扫描日历中的即将出行安排，自动分类目的地类型（山区/海滩/沙漠/城市），拉取当地天气，并结合每位儿童的个人档案生成出行准备提示。
• Club Studio 监控器（可选，需在 config.json 中启用 club_studio.enabled）— 每 15 分钟轮询 Gmail，识别 Club Studio Fitness 的课程预约/取消/候补邮件，向已配置的 WhatsApp 群组广播通知，并同步更新本地日历条目。另有一个独立的推荐/爬虫组件（features/club_studio/scraper.py）使用 Playwright 浏览器自动化访问 clubstudiofitness.com 的公开课程表页面以推荐课程——该站点为真实第三方网站，不在下方所述 Google/Open-Meteo 范围内；详见“密钥处理”章节。

架构

Python 工具仅返回 数据。OpenClaw agent（模型无关——Claude、Gemma、GPT、Llama 或任意 OpenClaw 当前配置的模型）负责组合并投递所有面向用户的响应消息。Python 本身从不发送 WhatsApp 消息，也绝不调用任何 LLM。所有 Python 状态文件均采用原子写入方式（通过 tempfile + fsync + rename），确保写入中途崩溃不会遗留损坏的 JSON 文件。Cron 入口点均包裹顶层 try/except，使任何崩溃均会输出可解析的状态对象，而非静默吞没执行过程。

密钥处理

本技能需依赖 Google OAuth 凭据（GOOGLE_CLIENT_ID、GOOGLE_CLIENT_SECRET、GOOGLE_REFRESH_TOKEN）读取您的 Google 日历与学校 Gmail。除此之外，无需其他 API 密钥、LLM 密钥或第三方令牌。

凭据从环境变量读取。在 macOS 上，您可选择通过 migrate_to_keychain.py 将其迁移至系统 Keychain，并随后从 .env 中移除。本技能仅通过 google-auth-oauthlib 将凭据发送至 Google 官方 OAuth 端点，绝不会传输至任何其他位置。

本技能发起的出站网络请求包括：

• Google OAuth + Gmail + Calendar API（*.googleapis.com）：用于日历同步、学校邮件监控、Club Studio Gmail 监控及凭据刷新
• Open-Meteo（api.open-meteo.com）：为晨间简报与行程检测器提供天气预报——无需 API 密钥、无需注册账户、不发送任何 PII 信息
• clubstudiofitness.com — 仅当 club_studio.enabled 为 true 时启用。推荐器（features/club_studio/scraper.py）使用 Playwright 加载其公开课程表页面。其自身 docstring 明确说明此操作“旨在绕过机器人防护”——这是明确披露的能力，非隐藏行为：即在独立的系统级 Python 解释器下，对第三方网站执行浏览器自动化操作。若您不希望启用该功能，请保持 club_studio.enabled: false（默认值）。

本技能不含任何遥测、分析、第三方追踪功能，亦不向上述三个域名以外的任何其他域名发起请求。

Shell / 子进程调用：features/briefing/briefing_preflight.py 调用 osascript 发送本地 macOS 通知（尽力而为，失败被静默忽略）。setup_check.py 和 migrate_to_keychain.py 是您手动运行的一次性设置脚本。get_cron_health_digest（位于 tools.py）读取 ~/.openclaw/cron/runs/*.jsonl —— 此为 OpenClaw 自身的 cron 日志目录，仅用于汇总 本技能自身 的任务结果，生成每日所有者简报；它仅读取该共享主机级目录中已可见的文件名，不访问其他技能的数据。

全部家庭状态（日历缓存、餐食历史、健康日志、儿童档案、餐厅评分、购物清单、简报可靠性追踪器）均以本地 JSON 文件形式存储于 household/ 和 calendar_data/ 目录中。无任何数据离开您的设备。

文件权限：.env 文件应设为 chmod 600（所附 setup_check.py 会校验此项）。household/ 与 calendar_data/ 下的 JSON 文件继承您的用户 umask —— 它们归属于运行 OpenClaw 的用户，在默认 macOS 或 Linux 配置下对其他本地用户不可访问。若您处于多用户系统，请审计这些路径。

关于 launchd plist

本仓库中的 com.openclaw.daemon.plist 是 OpenClaw 网关守护进程的模板，而非 Homebase 代码的启动配置。该 plist 执行 /usr/local/bin/openclaw start --foreground，以确保 WhatsApp 桥接服务在用户登录会话之间持续存活。它 并不直接运行任何 Homebase Python 代码。

该配置为可选。仅当您希望 WhatsApp 投递能力在登出或重启后仍保持有效时才需要它。若不启用，OpenClaw 仅在其终端会话活跃期间运行。如启用，该 plist 将存放于 ~/Library/LaunchAgents/com.openclaw.daemon.plist，您可随时通过 launchctl unload 卸载。

要求

• Python 3.12+
• 已启用 Gmail 与 Calendar API 的 Google Cloud 项目
• 通过 OpenClaw 实现 WhatsApp 投递（本技能不包含直接集成）
• 图像视觉能力由 OpenClaw agent 的原生能力提供——本技能无本地 LLM 依赖
• Playwright（仅当 club_studio.enabled: true 时需要）——用于 Club Studio 课程表爬虫的浏览器自动化依赖，运行于独立的系统级 Python 解释器下

设置

1. cp config.example.json config.json，并填写您家庭的相关配置。
2. 在环境中设置 GOOGLE_CLIENT_ID / GOOGLE_CLIENT_SECRET / GOOGLE_REFRESH_TOKEN，或通过 python migrate_to_keychain.py 迁移至 macOS Keychain。
3. pip install -e .（依据 pyproject.toml）。
4. python -m pytest 应报告全部测试通过。
5. python setup_check.py 执行配置与认证的合理性检查。

限制

• macOS Keychain 集成仅在 macOS 平台上尽力实现；其他平台回退至环境变量方式。
• 每日简报假设仅使用一个 Google Calendar；目前尚不支持多日历合并。

故障排查

• 简报中缺失天气信息 — Open-Meteo 请求频率限制所致。household/briefing_reliability.json 中的可靠性追踪器将当日标记为 degraded。
• Gmail 认证错误 — 运行 python core/reauth_google.py 重新生成 refresh token。学校邮件监控器将在发生此事时，通过 WhatsApp 向您精确发送一次通知，此后将静默等待问题修复。
• JSON 文件损坏 — 原子写入机制在正常运行中可防止此类问题。若仍发生（例如磁盘已满），请删除该文件；加载器将自动重建一个空文件。

许可证

MIT