OneAlign / docs /v1.2 /app-integration.md
loveaa's picture
Publish Home Pulse v1.2 product documentation and App integration download
6d043e7 verified
|
Raw History Blame Contribute Delete
16.3 kB

A newer version of the Gradio SDK is available: 6.32.0

Upgrade

Home Pulse App 接入指南 v1.2

API 1.2.0 · 更新日期 2026-10-15

产品流程 · OpenAPI · 验收说明 · 下载完整联调包

交付文件

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 <token>,或 X-Home-Pulse-Workspace: <token>。

  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

{
  "name": "Home Pulse iOS",
  "platform": "ios",
  "appVersion": "1.2.0"
}

保存返回的 data.id 为 clientId。

POST /clients/{clientId}/heartbeat

{
  "foreground": true,
  "sdkReady": true
}

sdkReady 应来自实际 SDK 登录和连接状况。每 15 秒更新连接元数据;这不是取图频率。

POST /devices

{
  "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

{
  "clientId": "...",
  "online": true,
  "observedAt": "UTC ISO 时间",
  "viewChanged": false,
  "state": {}
}

每 15 秒上报。只有连接仍有效才能报 online=true。

SDK 外部手动移动了摄像头时,viewChanged=true;使用唯一 key 报告一次。

超过 45 秒没有有效心跳或设备状态,后端将来源视为中断。

POST /setups/draft

{
  "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 示例:

{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

{"viewRevision":1,"frames":[一至五张可用的 Frame]}

Frame:image、annotated、可选 pairImage、mediaTime、capturedAt、frameId、sourceId。

状态任务可用一张当前画面完成试观察。若提交多张,使用真实不同时间点,按 mediaTime 递增。

只有 passed=true 才显示可开始守护;失败时展示 checks 对应的补充方法。

POST /watches

{
  "setupId": "...",
  "confirmation": {
    "target": true,
    "rule": true
  },
  "remember": false
}

用户点击“开始守护”时调用。remember 由用户主动选择,默认 false。

返回 watchId 和当前运行条件。

POST /device-events

{
  "clientId": "...",
  "deviceId": "...",
  "eventId": "SDK事件唯一编号",
  "type": "motion",
  "occurredAt": "UTC ISO 时间",
  "summary": "SDK事件摘要"
}

先登记事件,按返回的 work 安排取证。duplicate=true 时不要新增取证。

没有 work 不代表“没有异常”;只表示这次不安排新观察。

POST /watches/{watchId}/observe

{"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

{
  "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 文档的固定三帧试观察与短秒级连续观察,以本节的事件策略为当前实现。