Download docs/v1.2/app-integration.md from loveaa/OneAlign: direct link, hf CLI and curl.
- Browser
- Download file 16.3 kB
-
https://huggingface.co/spaces/loveaa/OneAlign/resolve/main/docs/v1.2/app-integration.md
- Command line
-
hf download hf://spaces/loveaa/OneAlign/docs/v1.2/app-integration.md
-
curl -L -o app-integration.md https://huggingface.co/spaces/loveaa/OneAlign/resolve/main/docs/v1.2/app-integration.md
A newer version of the Gradio SDK is available: 6.32.0
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
统一前缀:/api/v1
在线规范:GET /api/v1/openapi.json
POST /api/v1/sessions,正文 {},返回 data.token、data.workspaceId。
将 token 保存到 Keychain 或 Android Keystore。它是 Home Pulse 空间凭据。
后续请求发送 Authorization: Bearer
<token>,或 X-Home-Pulse-Workspace:<token>。POST 另带 Idempotency-Key:
<持久保存的本次操作 UUID>。同一请求重试使用原 key 与原正文,不重新生成时间戳或 frameId。
不把 HF、Kimi 或 eufy 账号密钥放入 App 包;官方 SDK 登录态由 App 自己管理。
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 文档的固定三帧试观察与短秒级连续观察,以本节的事件策略为当前实现。