# Home Pulse App 接入指南 v1.2 API 1.2.0 · 更新日期 2026-10-15 [产品流程](./product-flow.md) · [OpenAPI](./openapi.json) · [验收说明](./verification.md) · [下载完整联调包](https://huggingface.co/spaces/loveaa/OneAlign/resolve/main/releases/home-pulse-app-integration-v1.2.zip?download=true) ### 交付文件 openapi.json:请求与主要返回对象,可导入 Apifox、Postman 或代码生成工具。 home-pulse-client.mjs:HTTP 客户端,适合 Web、React Native 或作为原生网络层参考。 device-executor.mjs:设备动作执行与 App 重启恢复参考,adapter 接官方 SDK。 本说明:接入顺序、字段语义、执行状态和验证方法。 real-model-app-flow.json:通过新接口进行真实 Kimi 与本机 jev 调用的页面流程验收记录。 软件回归记录:用于验证协议和状态机,不代表真实摄像头识别准确率。 ## 一 基地址与认证 云端:https://loveaa-onealign.hf.space 本地:http://127.0.0.1:7101 统一前缀:/api/v1 在线规范:GET /api/v1/openapi.json 1. POST /api/v1/sessions,正文 {},返回 data.token、data.workspaceId。 2. 将 token 保存到 Keychain 或 Android Keystore。它是 Home Pulse 空间凭据。 3. 后续请求发送 Authorization: Bearer ``,或 X-Home-Pulse-Workspace: ``。 4. POST 另带 Idempotency-Key: `<持久保存的本次操作 UUID>`。 5. 同一请求重试使用原 key 与原正文,不重新生成时间戳或 frameId。 6. 不把 HF、Kimi 或 eufy 账号密钥放入 App 包;官方 SDK 登录态由 App 自己管理。 7. App 与网页共享空间凭据才会读取同一份后端资料。新建 session 会创建独立空间。 当前凭据代表空间,不是完整的用户账户与家庭角色系统;clientId 代表安装实例。 正式成员登录可在此基础上接身份服务。不要将 clientId 显示为“已认证的某位家庭成员”。 在 HF 上,旧网页的 X-Home-Pulse-Workspace 令牌也可访问对应 App API 空间。 旧网页创建的关注需要重新绑定实际 SDK 来源;App 新建关注的列表以 GET /watches 为准。 本地旧网页历史数据与 App 空间独立。不要假设手机的 127.0.0.1 能访问电脑。 ## 二 最短调用顺序 ### `POST /clients` ```json { "name": "Home Pulse iOS", "platform": "ios", "appVersion": "1.2.0" } ``` 保存返回的 data.id 为 clientId。 ### `POST /clients/{clientId}/heartbeat` ```json { "foreground": true, "sdkReady": true } ``` sdkReady 应来自实际 SDK 登录和连接状况。每 15 秒更新连接元数据;这不是取图频率。 ### `POST /devices` ```json { "deviceId": "SDK返回的设备编号", "clientId": "上一步的安装实例编号", "name": "客厅摄像头", "model": "T8171", "capabilities": { "live": true, "frames": true, "events": true, "scheduledCapture": false, "actions": [ "night_vision.set", "ptz.preset.goto" ], "nightVisionModes": [ { "key": 7, "label": "示例模式 使用SDK实际返回值" } ], "presetIndices": [ 1 ], "detectionTypes": [], "alarmTypes": [] } } ``` 示例 key 与预置位不可直接复制为固定常量,必须使用 SDK 当前查询结果。 返回 viewRevision,后续图像和设置均携带当前值。 ### `POST /devices/{deviceId}/status` ```json { "clientId": "...", "online": true, "observedAt": "UTC ISO 时间", "viewChanged": false, "state": {} } ``` 每 15 秒上报。只有连接仍有效才能报 online=true。 SDK 外部手动移动了摄像头时,viewChanged=true;使用唯一 key 报告一次。 超过 45 秒没有有效心跳或设备状态,后端将来源视为中断。 ### `POST /setups/draft` ```json { "request": "帮我盯着 Buddy 是否出了围栏", "image": "data:image/jpeg;base64,...", "source": { "id": "设备编号", "name": "客厅摄像头", "camera": "客厅", "url": "", "type": "live" }, "viewRevision": 1 } ``` 返回 draft.targetBox、regionBox、questions 和 recommendation。 recommendation 包含 capturePolicy、category、attentionLevel、reasonZh;小狗位置任务另有 locationAlerts。 模型先理解用户需求与已登记的实际设备能力,推荐观察和提醒方式。用户再确认或调整。 框为空时让用户圈选;必要问题聚焦对象、范围和语义,避免让用户填写底层模型参数。 ### `POST /setups/prepare` 提交用户最终确认的 binding、answers、taskKind、notification、confirmed、viewRevision、capturePolicy。 小狗位置任务还提交 locationAlerts;recommendationReason 保留最初建议理由用于追溯。 capturePolicy={mode:"event",intervalSeconds:300,comparisonMaxAgeSeconds:86400}。 mode 可为 event/manual/scheduled;intervalSeconds 仅在 scheduled 模式决定检查间隔。 event 不创建取图定时器;manual 由用户发起;scheduled 只有真实支持定时取图的接入端才能启用。 scheduledCapture 默认 false,不能根据设备能播放视频就填 true。 支持 scheduled 的 App/Hub 根据已确认的 policy 安排检查;网页素材端不声明这一能力。 locationAlerts 示例: ```text {notSeen:{enabled:true,confirmations:2,attentionLevel:2}, outside:{enabled:true,confirmations:1,attentionLevel:3},excludeCarried:true} ``` 两类独立启停、独立确认次数、独立注意力等级;全局 attentionLevel 不覆盖它们。 binding 的必需字段见 OpenAPI。可带 category 与 attentionLevel 0 至 4。 参考图 annotatedReference:目标红框、观察区域绿框。 当前观察 annotated:只保留观察区域,不能把目标旧位置当成当前目标位置。 targetCrop 是用户圈定对象的真实裁图。 返回 setupId。GET /setups/{id} 可以恢复这一步。 ### `POST /setups/{setupId}/trial` ```text {"viewRevision":1,"frames":[一至五张可用的 Frame]} ``` Frame:image、annotated、可选 pairImage、mediaTime、capturedAt、frameId、sourceId。 状态任务可用一张当前画面完成试观察。若提交多张,使用真实不同时间点,按 mediaTime 递增。 只有 passed=true 才显示可开始守护;失败时展示 checks 对应的补充方法。 ### `POST /watches` ```json { "setupId": "...", "confirmation": { "target": true, "rule": true }, "remember": false } ``` 用户点击“开始守护”时调用。remember 由用户主动选择,默认 false。 返回 watchId 和当前运行条件。 ### `POST /device-events` ```json { "clientId": "...", "deviceId": "...", "eventId": "SDK事件唯一编号", "type": "motion", "occurredAt": "UTC ISO 时间", "summary": "SDK事件摘要" } ``` 先登记事件,按返回的 work 安排取证。duplicate=true 时不要新增取证。 没有 work 不代表“没有异常”;只表示这次不安排新观察。 ### `POST /watches/{watchId}/observe` ```text {"clientId":"...","viewRevision":1,"frame":Frame,"manual":false,"signals":[]} ``` 同一关注不并发。图像超过 120 秒或来源/视野版本不符将被拒绝。 manual=true 表示仅主动查看;用户出门检查使用实际用户触发的 away 信号。 按事件使用已有事件图或设备当次可用图,不强制每 1–3 秒唤醒摄像头。 稀疏画面可以比较前后位置;不能证明两张图之间持续发生了什么。 连续时长要求未被覆盖时,prepare 返回 needs_clarification;不得静默改写为持续异常。 媒体播放和连接心跳本身不触发 observe。 ### `GET /watches、GET /watches/{id}、GET /events、GET /memories、GET /metrics` 分别供首页与关注列表、关注详情、通知与事件、对象记忆、运行记录消费。 attentionLevel 是 App 的 0 至 4 注意力字段;不要用旧 plan.rules.level 替代。 L0 只记录,L1 轻量卡片,L2 主动提醒,L3 优先关注,L4 立即处理。 手机推送是否接通以 bootstrap.phonePushConnected 为准,当前为 false。 ## 三 设备操作 创建:POST /commands。 确认:POST /commands/{id}/decision,decision=confirm,带 expectedRevision。 领取:POST /commands/{id}/claim,由登记的设备接入 App 执行。 回执:POST /commands/{id}/receipt,outcome=succeeded / failed / unknown。 验证:POST /commands/{id}/verify,提交操作后的真实读回状态。 模型和后端只提出操作。用户未确认时不能领取。 App 在调用 SDK 前,必须安全保存 commandId、executionToken 和执行阶段。 网络失败时重发回执,不能重做物理动作。device-executor.mjs 展示这一流程。 默认命令有效 60 秒,可选 10 至 120 秒;领取后的执行窗口最长 15 秒。 过期或取消不能领取;回执丢失进入 result_unknown,先读回实际设备状态。 SDK success 对应 awaiting_verification;只有读回匹配才对应 verified。 verification_failed 结束本次验证;如需再次操作,先查看状态,再由用户新建确认。 ### action 与 SDK 的映射 night_vision.set {modeKey} → NightVisionAPI.setMode(key) 用 getModeOptions 获取 key;用 getMode 读回。verify.state.nightVisionModeKey 填真实结果。 ptz.preset.goto {index} → LiveStreamAPI.jumpToPreset(index, settingState=0) 用 supportsPreset 和 queryPresetPositions 检查;不使用强制转动。 命令被领取后,旧视野即标记为失效。获取新画面、重新圈选并 trial;verify 提交 setupId、targetConfirmed=true。 然后通过 /watches/{id}/replace 用新设置替换旧关注。 alarm.set {enabled,type} → LiveStreamAPI.triggerAlarm(AlarmType, enabled) type 只可使用设备实际支持的 SOUND_ONLY、LIGHT_ONLY、SOUND_AND_LIGHT。 有可读物模型状态时再提交 alarmEnabled、alarmType;无法读回时保留待确认。 light.set {enabled} → LiveStreamAPI.toggleLight(enabled) 支持时读取 lightEnabled;当前文档中 T8171 不提供灯光能力,T8214 按实际能力查询。 motion_detection.set {types} → MotionDetectionAPI.setActiveTypes(types) 先 getSupportedTypes,再 getActiveTypes 读回。PET 可能伴随启用 FACE/BODY,展示实际返回列表。 实际 SDK 的对象创建、包名和 iOS/Android 调用包装沿用赛事 Demo。 后端不携带移动 SDK 二进制。App 团队负责该适配模块,前端页面消费本 API。 每种动作至少进行一次真机验证,再把对应 action 上报为可用。 ## 四 事件处理 ### `POST /events/{id}/actions` ```json { "clientId": "...", "action": "take_over", "expectedRevision": 1, "note": "" } ``` action 可为 read、take_over、user_completed、dismiss、reopen。 打开页面只发送 read。user_completed 不填写 visualRecoveryAt。 后续规则确认恢复时,后端更新原事件的 visualRecoveryAt,不新建一条同样提醒。 发生 revision 冲突先重新 GET /events 再操作。 ## 五 失败和重试 所有 POST 的相同 key 在保留期内重放原结果。参数变化需要新 key。 明确收到 422/409 后,按 error.code 处理;不要用无限重试。 因网络超时未拿到响应,保留原请求与 key,重新发送一次以恢复结果。 已返回模型失败但需要新一次尝试时,重新取得新鲜图像并使用新 key。 设备 result_unknown 或 RESULT_UNKNOWN 时,查询原命令和实际状态;禁止自动再次执行。 建议 HTTP 超时 240 秒;UI 显示本次仍在观察。应用进后台是否继续由实际系统行为决定。 ## 六 保存和删除 ### `GET /privacy 返回实际 App API 保存策略。` 观察图片每关注最多三张、最长24小时;设备事件与去重信息24小时。 已结束的事件和动作记录保留30天;进行中的事件、结果未明的指令另行处理。 ### `POST /watches/{id}/delete:confirmed=true,可选择 deleteMemory。` ### `POST /memories/{id}/delete:confirmed=true;存在依赖时先列出关注,再由用户选择 cascade。` 删除会使旧请求缓存失效,防止重复请求重新取回已删除资料。 摄像头自己的录像、用户导入的媒体和模型服务的数据策略另行管理。 HF 当前为临时磁盘。正式长期使用前接入持久存储,并设计账户、配对和权限。 ## 七 联调完成标准 先完成一台设备的一条主线:登记→指认→试观察→启用→取帧→事件→用户处理→恢复。 再完成一个可读回设备动作:用户确认→领取→SDK执行→回执→状态验证。 最后测试断网、迟到数据、重复请求、App重启、视野变化和删除依赖。 API 已实现不等于真机 SDK 已接通;协议回归、模型素材验收和真机验收分别记录。 ### 处理 UI 的原则 显示当前事实、具体缺口与下一步;模型名、原始错误码和毫秒明细放运行记录。 动作已执行与效果已确认分开;用户处理完成与画面确认恢复分开。 来源断开时保留上次状态与最近确认时间,不能继续显示全部正常。 当前产品流程与文案标准见《Home Pulse 产品流程与提醒标准 v1.2》。 ## 八 当前 App 模拟页与事件策略 /app:手机界面模拟;/workspace:桌面工作台。两者使用相同 /api/v1 与空间凭据。 /app/agent:说出关注→指认对象/补充必要条件→模型推荐与用户调整→试观察→最终确认。 /app/watch/{id}:查看最近状态与画面。素材端“检查这次事件”模拟 SDK motion 事件,取得 work 后提交一张图。 /app/devices:设备能力、关联关注及操作;联调摄像头是可明确选择的协议模拟端。 /app/metrics:实际采集、模型请求、未知结果、耗时、失败与指令回执。 ### 小狗位置语义 inside:在围栏内,或身体仍有部分在内。 not_seen:围栏相关内部清晰可见,却未看到目标,当前视野其他位置也没明确认出它。 outside:目标整个身体明确出现在围栏外。这个判断描述当前位置,不推断离开路径。 carried:看见有人抱着目标。excludeCarried=true 时不触发在围栏外提醒。 unknown:遮挡、画面模糊、目标身份或边界无法确认;不计作暂未看到。 confirmation_frames 在事件策略下表示有效观察次数。未知画面打断尚未完成的连续确认, 间隔超过 comparisonMaxAgeSeconds 后重新建立比较基线。 同一帧重试不会重复计数;一次清晰在外可以按用户选定的一次确认提醒。 位置异常事件只有 inside 证据满足恢复条件才写 visualRecoveryAt。 用户点击处理完成,只写 userCompletedAt;没有新画面不能自动判为回到围栏。 observationStatus:recently_checked(最近更新)、waiting_event(等设备事件)、 ready_for_check(按需检查)、waiting_schedule(等已支持的定时检查)、 needs_reconfirmation(视野需要重新确认)、connection_interrupted(接入中断)、paused/replaced。 lastObservedAt 是最近图像时间,lastConfirmedAt 是最近有效确认时间。无新事件保留上次状态。 例:用户说“帮我留意小狗有没有跑出去”。模型先确认哪只狗、哪个围栏, 建议“有动静时检查;暂未看到连续两次再普通提醒,明确在外一次看清后优先关注;当前看见被人抱着时不提醒”。 用户可以只保留在外提醒,或者把暂未看到改成首页卡片。最终约定保存后再启用。 原 v1.1 文档的固定三帧试观察与短秒级连续观察,以本节的事件策略为当前实现。