联犀开发者文档

AI工具与设备执行

约 1778 字大约 6 分钟

2026-10-16

本页包含已接线核心流程及可选扩展；具体子能力必须按设备、平台与用户授权求交集。参见支持范围、场景索引和命令手册。图中S编号只用于本文定位，不放入实际JSON。

前置条件

AI 通话内音乐、广播及视频播放另见 支持范围，复用 S15/S16/S18；持续播放不以一次 actionReply 表示全部生命周期结束。

已有 established 的 AI 会话，且已收到respCreated(tool-reply,input-tool)；工具授权与物模型权限均已通过。以下 MCP/RPC 是内部示意，不是新增设备命令。

图中P代表经鉴权的平台业务控制器和媒体节点，不要求同一进程；A是用户应用，D是设备。控制图描述一种合法顺序，跨通道不承诺严格同序。

完整时序

报文索引

编号按图阅读；编号保留历史引用，不要求数值连续。字段定义以命令链接为准。

编号发送→接收Topic/接口方法及契约应答/等待状态或作用
S04-M01P→DMSG↓toolCallStart—；不等待模型工具意图，不代表执行已成功。
S04-M03P→TINTERNALMCP.invokeMCP.result；工具配置超时模型工具调用进入 MCP；参数经权限校验。
S04-M04T→PINTERNALActionSendActionSendResult；RPC超时服务端从已授权工具上下文解析目标设备。
S04-M05P→TINTERNALActionSendResult—；不等待受理不等于拍照成功。
S04-M06P→DACT↓actionactionReply；产品动作超时拍照并上传，图片不走 MQTT。
S04-M07D→PACT↑actionReply—；不等待以原 token 关联，校验产品输出类型。
S04-M08T→PINTERNALActionGetOneActionGetOneResult；RPC超时工具查询关联回执。
S04-M09P→TINTERNALActionGetOneResult—；不等待返回可信设备输出。
S04-M10T→PINTERNALMCP.result—；不等待回注模型，不自动授予视觉读图权限。
S04-M11P→DMSG↓toolCallResult—；不等待成功需可信 actionReply；超时且设备可能已执行时用 unknown。注入播报不能证明模型原生工具选择。
S04-M12P→DMSG↓respTextDone—；不等待最终完整文本取代增量；不是播放完成。
S04-M14P→DMSG↓respDone应答或事件，无ACK核对补齐，不以受理替代完成
S04-M13P→DMSG↓toolCallResult—；不等待成功需可信 actionReply；超时且设备可能已执行时用 unknown。注入播报不能证明模型原生工具选择。
S04-M15P→DMSG↓respDone应答或事件，无ACK核对补齐，不以受理替代完成

逐条JSON

S04-M01 · toolCallStart

{
  "msgToken": "s04-57",
  "method": "toolCallStart",
  "sessionId": "s04-session",
  "messageSeq": 1,
  "data": {
    "respId": "tool-reply",
    "toolCallId": "tool-1",
    "name": "deviceTakePhoto",
    "arguments": {}
  }
}

S04-M03 · MCP.invoke

{
  "toolCallId": "tool-1",
  "name": "deviceTakePhoto",
  "arguments": {}
}

S04-M04 · ActionSend

{
  "actionID": "takePhoto",
  "params": {},
  "isAsync": true
}

S04-M05 · ActionSendResult

{
  "msgToken": "photo-tool-1",
  "accepted": true
}

S04-M06 · action

{
  "msgToken": "photo-tool-1",
  "method": "action",
  "actionID": "takePhoto",
  "params": {}
}

S04-M07 · actionReply

{
  "msgToken": "photo-tool-1",
  "method": "actionReply",
  "actionID": "takePhoto",
  "code": 200,
  "msg": "success",
  "data": {
    "fileUri": "<file-uri>"
  }
}

S04-M08 · ActionGetOne

{
  "msgToken": "photo-tool-1"
}

S04-M09 · ActionGetOneResult

{
  "msgToken": "photo-tool-1",
  "code": 200,
  "outputParams": {
    "fileUri": "<file-uri>"
  }
}

S04-M10 · MCP.result

{
  "toolCallId": "tool-1",
  "success": true,
  "fileUri": "<file-uri>"
}

S04-M11 · toolCallResult

{
  "msgToken": "s04-59",
  "method": "toolCallResult",
  "sessionId": "s04-session",
  "messageSeq": 2,
  "data": {
    "respId": "tool-reply",
    "toolCallId": "tool-1",
    "state": "succeeded",
    "result": {
      "fileUri": "<file-uri>"
    }
  }
}

S04-M12 · respTextDone

{
  "msgToken": "s04-60",
  "method": "respTextDone",
  "sessionId": "s04-session",
  "messageSeq": 3,
  "data": {
    "respId": "tool-reply",
    "contentIndex": 0,
    "text": "拍照成功。"
  }
}

S04-M14 · respDone

{
  "method": "respDone",
  "msgToken": "s04-audit-1",
  "sessionId": "s04-session",
  "messageSeq": 4,
  "data": {
    "respId": "tool-reply",
    "inputId": "input-tool",
    "status": "completed",
    "contentCount": 1,
    "audioState": "sent"
  }
}

S04-M13 · toolCallResult

{
  "msgToken": "s04-61",
  "method": "toolCallResult",
  "sessionId": "s04-session",
  "messageSeq": 5,
  "data": {
    "respId": "tool-reply",
    "toolCallId": "tool-1",
    "state": "unknown",
    "result": {
      "reason": "actionTimeout"
    }
  }
}

S04-M15 · respDone

{
  "method": "respDone",
  "msgToken": "s04-audit-2",
  "sessionId": "s04-session",
  "messageSeq": 6,
  "data": {
    "respId": "tool-reply",
    "inputId": "input-tool",
    "status": "failed",
    "contentCount": 0,
    "audioState": "none",
    "reason": "actionTimeout"
  }
}

媒体与本地动作

编号路径格式与约束
S04-R01P→D已协商 UDP Opus 或 WebRTC 音轨；结果播报不等于工具选择能力已验证。

异常、状态与资源释放

以下JSON仅为报文正文；编号、方向、说明不发送。loop下一轮需分配新token/inputId；同一次请求重试必须沿用原token。字段以命令手册为准。

路由缩写均展开于公共约定。ACT/PROP超时以产品配置为准；内部工具以工具超时为准，不套用10秒设备统一信令超时。

工具结束不关闭主 AI 会话；关闭使用 S01 sessionEnd。action 的 token 与工具 ID 分开映射。同 token 不重复执行；超时不可换新 token 盲重试写操作。设备晚到回执仅更新原动作记录，不能重新启动被取消的播报。

能力不支持、无权限、设备拒绝、协商失败、断网、重复请求、过期会话及迟到媒体按S11共通失败流程和公共错误表处理。业务专属分支以本页为准，不因错误静默打开额外能力。

验证入口

检查本场景对应的支持范围，以及公共流程。示例可解析不等于网络、权限或硬件运行已验证。

更新日志

2026/10/16 16:04
查看所有更新日志
  • fe3a7-docs(AI与音视频): 按场景整理完整接入流程与命令契约于