joshuaswarren/pyskylight

# pyskylight    非官方的 Python 客户端和 `skylight` CLI，适用于 [Skylight Calendar](https://www.skylightframe.com/) / Buddy 系列设备。 Skylight **没有官方或公开的 API。** 本库与社区逆向工程得出的同一私有 应用 API (`app.ourskylight.com`) 进行通信。它仅供 **针对您个人帐户的自用** — 请参阅 [法律声明](#legal)。 ## 功能 - 通过应用的 OAuth2 (PKCE) 流程进行邮箱/密码登录，支持 token 缓存 + 刷新。 - **近乎完整覆盖了私有 API** — 包含约 150 个客户端方法和约 145 个 `skylight` CLI 命令，涵盖智能相框、日历（活动、搜索、倒计时、连接/源 日历、webcal 订阅、Google 关联流程）、**Meals**（食谱 + 计划 "sittings" + instances）、家务、列表 & 列表项、类别/配置文件、**奖励**、 **照片/消息/相册”、每月回顾、**设备 & Buddy 闹钟”、家庭 成员 & 配置、日常例程、task-box、天气/地理定位，以及 AI Sidekick （自动创建意图）。请参阅[命令参考](#command-reference)。 - 适配 JSON-first 的 CLI，适合编写脚本或由 agent 驱动（每个命令均输出 JSON）。 - 支持 1Password：凭据可以是运行时解析的 `op://` 引用。 - 诚实地对待不确定性：少数写入请求体是基于逆向工程的，并接受 `--json` / `**extra` 透传，因此即使在 API 实际环境状态得到确认后，它们也能继续正常工作。 ## 安装 ``` # 在它发布到 PyPI 之前，请从 git 安装： pip install "git+https://github.com/joshuaswarren/pyskylight" # （PyPI，一旦发布：pip install pyskylight） # 或者从源码安装： pip install -e ".[dev]" ``` 要求 Python 3.11+。 ## 快速开始 ### CLI ``` export SKYLIGHT_EMAIL="you@example.com" export SKYLIGHT_PASSWORD="…" # or an op:// reference skylight login # caches the session token skylight frames # find your frame (household) id export SKYLIGHT_FRAME_ID=123456 skylight meal-categories # Breakfast / Lunch / Dinner ids skylight recipes # list recipes skylight create-recipe --summary "Tacos" --description "Tuesday classic" skylight plan-add --date 2026-06-20 --meal-category-id 42 --recipe-id 99 ``` 每个命令均输出 JSON。 ### 库 ``` from pyskylight import SkylightClient with SkylightClient.login("you@example.com", "…") as sky: frame = sky.list_frames()[0] for recipe in sky.list_recipes(frame.id): print(recipe.id, recipe.summary) sky.create_sitting(frame.id, date="2026-06-20", meal_category_id="42", meal_recipe_id="99") ``` ## 命令参考 运行 `skylight --help` 或 `skylight --help` 查看参数。在需要指定家庭的地方，每个命令都可以使用 `--frame`（或使用 `SKYLIGHT_FRAME_ID`）。 | 区域 | 命令 | |---|---| | **认证 / 身份** | `login`, `logout`, `whoami` | | **相框 (Frames)** | `frames`, `frame`, `frame-rename`, `frame-settings`, `frame-hide`, `frame-activation-code` | | **日历活动** | `events`, `events-search`, `countdowns`, `event-invitees`, `event-add`, `event-update`, `event-delete`, `event-notifications`, `event-notifications-update`, `reminder-notification`, `reminder-notification-update` | | **关联日历** | `calendars`, `calendar-account`, `calendar-account-update`, `calendar-link`, `webcals`, `webcal-add`, `source-calendars`, `source-calendar`, `source-calendar-update`, `source-calendar-delete`, `source-calendar-default`, `source-calendar-categorize`, `category-categorize` | | **Meals — 食谱** | `recipes`, `recipe`, `create-recipe`, `update-recipe`, `delete-recipe`, `grocery-add`, `meal-categories`, `update-meal-category` | | **Meals — 计划 (sittings)** | `plan`, `plan-show`, `plan-add`, `plan-update`, `plan-remove`, `plan-instances`, `plan-instance-update` | | **家务** | `chores`, `chore-add`, `chore-add-multiple`, `chore-update`, `chore-complete`, `chore-delete` | | **列表 & 列表项** | `lists`, `list-show`, `list-items`, `list-create`, `list-update`, `list-delete`, `list-add`, `list-item-update`, `list-item-complete`, `list-item-delete`, `list-items-delete`, `list-item-move`, `list-items-section` | | **类别 / 配置文件** | `categories`, `category`, `category-add`, `category-find-or-create`, `category-update`, `category-delete` | | **奖励** | `rewards`, `reward`, `reward-add`, `reward-update`, `reward-delete`, `reward-redeem`, `reward-unredeem`, `reward-points`, `reward-points-set` | | **照片 / 消息** | `messages`, `message`, `message-delete`, `messages-delete`, `messages-copy`, `message-caption`, `message-likes`, `message-like`, `message-unlike`, `message-comments`, `message-comment-add`, `message-comment-delete`, `photo-upload`, `upload-credentials` | | **相册** | `albums`, `album-add`, `album-update`, `album-delete`, `album-messages`, `album-message-ids`, `album-add-photos`, `album-remove-photos` | | **设备 & 闹钟 (Buddy)** | `devices`, `device`, `device-update`, `device-delete`, `device-activation-code`, `device-reset`, `alarms`, `alarm-add`, `alarm-update`, `alarm-delete` | | **家庭** | `members`, `member-invite`, `member-approve`, `member-remove`, `member-update`, `household-config`, `household-config-update`, `plus-status` | | **日常例程 / task-box** | `routines`, `routine-add`, `routine-update`, `routine-delete`, `routines-reorder`, `task-box`, `task-box-add`, `task-box-update`, `task-box-delete` | | **AI Sidekick** | `ai-intents`, `ai-intent`, `ai-intent-create`, `ai-intent-approve`, `ai-intent-retry`, `ai-intent-undo`, `ai-intent-items` | | **参考 / 杂项** | `avatars`, `colors`, `activities`, `month-in-review`, `month-in-reviews`, `weather`, `geolocation`, `share-link` | ## 配置 | 变量 | 用途 | |---|---| | `SKYLIGHT_EMAIL` | 帐户邮箱（或 `op://vault/item/field`） | | `SKYLIGHT_PASSWORD` | 帐户密码（或 `op://…`） | | `SKYLIGHT_FRAME_ID` | 默认的相框 ID，设置后即可省略 `--frame` | | `SKYLIGHT_TIMEZONE` | 用于日历查询的默认 IANA 时区 | | `SKYLIGHT_BASE_URL` | 覆盖 API 基础 URL | 会话 token 缓存在 `${XDG_CACHE_HOME:-~/.cache}/pyskylight/token.json` (模式 `0600`)。`skylight logout` 会将其清除。 ## 认证说明 登录使用应用的 **OAuth2 Authorization-Code + PKCE** 流程 (`/oauth/authorize` → `/auth/session` → `/oauth/token`) 并存储生成的 `access_token` / `refresh_token`；后续请求会发送 `Authorization: Bearer `。 当 token 过期时，客户端会自动刷新（或重新登录）。 ## 开发 ``` pip install -e ".[dev]" pytest # full suite + coverage (fails under 90%) pre-commit run --all-files # black, isort, flake8, mypy ``` ## 相关项目 - **openclaw-skylight** — 驱动此 CLI 的 OpenClaw skill。 - **plantoeat-skylight-sync** — 将 Plan to Eat 膳食计划同步到 Skylight Meals。 为本客户端开发提供参考的现有成果：[bryanmig/skylight-calendar-api](https://github.com/bryanmig/skylight-calendar-api)、 [kylebjordahl/skylight-calendar-home-assistant](https://github.com/kylebjordahl/skylight-calendar-home-assistant) 以及 [kylejfrost/skylight-api-cli](https://github.com/kylejfrost/skylight-api-cli)。 ## 法律声明 本产品为非官方版本，不附属于 Skylight，也未获得其认可或支持。该 API 可能会在不另行通知的情况下发生变更。请仅使用您自己的帐户和数据；切勿在此基础上构建 多租户或商业服务。在 [MIT License](LICENSE) 下按“原样”提供。

标签：API客户端, Homebrew安装, Python, 云资产清单, 文档结构分析, 无后门, 智能家居, 物联网, 逆向工具, 逆向工程