物模型控制与工具边界
约 1683 字大约 6 分钟
2026-10-16
本页按 Topic、method 和方向定义完整契约。字段表与JSON中的可选扩展不等于当前全部启用，实际接入前请查支持范围；应用REST封装见应用接入。
物模型消息契约
DeviceSignaling/ControlSourceTrack为内部gRPC，不是设备MQTT method或公开应用API。输入subject:string为已授权设备主体，payload:bytes为原trackControl JSON信封（不带平台eventSeq）；企业及服务身份来自调用上下文，不在参数中自报。只允许已有已建立IPC Owner的授权轨，源控制重新核验主人、设备连接与能力；普通观看者只能沿用自身订阅控制。
输出accepted:bool仅确认持久受理，实际结果必须由原token trackState与真实媒体事实证明；原token重试不重投／不续期。代码在.proto维护并生成客户端和服务接口，AllInOne imdirect复用同一权限逻辑；关闭或旧服务未实现时明确拒绝，不改走旧Topic或直接发布。错误类别为PermissionDenied（身份）、InvalidArgument（格式）、FailedPrecondition（正文/状态冲突）及Unavailable（运行时不可用或结果未知），内部错误不携带SQL、媒体密钥或原报文。协议字段仍以轨控制契约为唯一来源；当前真实C++源控制E2E尚未验收。
具体Topic全称见公共约定，但这里沿用物模型既有信封，不新增sessionId、eventSeq或统一信令版本。
| method / 方向 | 字段、类型与必填 | 应答、超时、幂等与状态 |
|---|---|---|
| action / ACT↓ | msgToken:string、actionID:string、params:object必填 | actionReply原token；按产品动作超时；命令下发不代表执行成功 |
| actionReply / ACT↑ | msgToken:string、actionID:string、code:int必填；成功data:object按产品输出，msg:string为提示 | 不等待额外ACK；以原设备和action token关联，迟到回执只更新原动作 |
| control / PROP↓ | msgToken:string、params:object必填，属性类型按产品定义 | controlReply原token；按属性控制超时；重复请求不能绕过状态校验 |
| controlReply / PROP↑ | msgToken:string、code:int必填；data:object和msg:string按实际设备回执 | 接收成功不代替实际属性状态；应用不得据此假报硬件停流 |
| report / PROP↑ | msgToken:string、params:object必填，包含实际属性值 | 沿用现有属性上报应答，不套用新signaling命令；隐私状态驱动撤销相关媒体 |
| event/report / 事件Topic | 事件ID、参数与既有产品事件上报结构一致 | 不新增会话事件外层；物模型告警由现有事件处理器受理，不建立会话或自动分享画面 |
正式 ActionSend 为每次新动作生成 128 位随机值的 32 字符小写 hex msgToken，避免短循环计数器与永久唯一账本冲突；其他旧方法的 token 生成器不变。固件只按原字符串关联并回显，不转整数、不按长度判断接入路径。平台唯一受理成功后才缓存请求及发布；极罕见 token 碰撞或熵源失败均拒绝，不能覆盖原操作者、请求或终态后重发。
明确的 actionReply(code=504,msg="resultUnknown") 表示原动作已受理但结果未知，不是可安全重试的失败，也不是成功。同步 RPC 保留原 token 和该回执，MCP 保留未知提示及原 token 供只读查询；不得因结果未知自动换新 token 再执行。其他设备错误仍按原错误行为处理；旧 Topic、信封字段及字符串类型不变。
公开同步 ActionSend 遇该明确未知仍返回原 DeviceResp 外层错误，不以外层成功码包装；旧客户端及兼容网关只检查外层码时也不能误确认成功。异步受理和 ActionGetOne 原只读未知响应不改。设备没有回执时，已持久受理后的原 DeviceTimeOut 可通过内部标准 gRPC ErrorInfo 携带唯一原 token，业务错误码和本地化文案不变；MCP 严格检查固定类型、原因、域及 token 格式后仅提示只读查询，不重新执行。这不是新增设备报文或公开字段。若客户端连接先断开或 RPC 预算先耗尽，详情可能无法送达，仍沿原 RPC 错误路径，不能确认动作未执行，也不能编造原关联。
摄像头产品输入与输出
| action/属性 | 类型与值 | 边界 |
|---|---|---|
| takePhoto | params={}；成功data.fileUri:string | 已有动作通道，返回授权文件引用，不含图像Base64 |
| ptzMove | direction:left/right/up/down；speed:number(0,1]；durationMs:int(0,3000] | 扩展产品动作，三字段必填；设备必须按durationMs自动停 |
| ptzStop | params={}；data.stopped:boolean | 扩展产品动作，幂等；即使已停止也确认成功 |
| ptzPreset | operation:goto/save/delete；presetId:string | 扩展产品动作；保存/删除比预览需要更高管理权限 |
| privacyMode | boolean | 按产品实际注册属性；当前准入核最新有效值，true拒绝新预览／对讲。已有本节点活相机停流入口见下文；跨节点、撤权触发及AI帧撤销仍须独立验收 |
| nightVision | off/on/auto | 扩展产品属性，与预览会话无绑定 |
| recordingPolicy | off/continuous/motion | 扩展产品属性；配置录像不建立播放会话 |
| 检测告警 | 产品物模型event参数 | 不把告警payload塞入sessionError，不因事件自动开摄像头 |
以上样例见S08的每条JSON。输入不合法或无动作权限沿用物模型错误回执，不将本协议reason强行写回已有设备。具体产品可使用不同标识，但必须以实际注册的物模型为准，不仅靠文档名称支持。
MCP与设备执行边界
平台负责MCP工具选择、设备权限、动作下发和结果续答。固件只实现产品物模型的action/actionReply，不调用平台内部gRPC，也不自报用户身份。客户端工具则按工具执行独立声明并提交结果，不能和MCP重复执行。
动作结果未知时只回查原token，不自动换token再执行。取消语音回复不回滚已执行的动作；预览、接听和工具名都不授予门锁或摄像头管理权限。
更新日志
2026/10/16 16:04
查看所有更新日志
fe3a7-docs(AI与音视频): 按场景整理完整接入流程与命令契约于