联犀开发者文档

客户端工具执行与回传

约 2100 字大约 7 分钟

2026-10-16

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

前置条件

工具名、交互类型和schemaRevision必须匹配平台已审核的工具目录。当前审核工具为set_local_display_theme，interactionType=action、schemaRevision=1，参数及成功结果均为{"theme":"light"}或{"theme":"dark"}；form为扩展设计，不能提交给当前严格入口；端不得上报任意脚本或自授表单schema。下面展示None文字会话的声明与创建，其他建立、输入、回复和关闭步骤沿用快速接入。UDP／WebRTC把同一frontendTools子集加入各自真实能力和创建请求，不改变原媒体参数。

{
  "msgToken": "s22-cap",
  "method": "capabilityReport",
  "params": {
    "revision": 1,
    "purposes": [
      "aiConversation"
    ],
    "transports": [
      "none"
    ],
    "features": [],
    "inputModalities": [
      "text"
    ],
    "outputModalities": [
      "text"
    ],
    "frontendTools": [
      {
        "name": "set_local_display_theme",
        "interactionType": "action",
        "schemaRevision": 1
      }
    ]
  }
}

等待成功requestAck，result.acceptedRevision等于1，再创建：

{
  "msgToken": "s22-create",
  "method": "sessionCreate",
  "params": {
    "purpose": "aiConversation",
    "transport": "none",
    "tracks": [],
    "inputModalities": [
      "text"
    ],
    "outputModalities": [
      "text"
    ],
    "frontendTools": [
      {
        "name": "set_local_display_theme",
        "interactionType": "action",
        "schemaRevision": 1
      }
    ]
  }
}

保存sessionCreated的实际sessionId，等sessionEstablished后才能提交输入。下文s22-session、reply-1、tool-1和executionToken均替换为本轮实际返回值；不能自行调用模型或生成executionToken来触发本例。

会话已established且已有respCreated(reply-1,input-1)；客户端已上报frontendTools并通过白名单校验。本页与S04后端MCP执行互斥选路，不能同一个toolCallId两端执行。应用分支是独立调用，不重复执行设备分支。

完整时序

报文索引

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

编号发送→接收Topic/接口方法及契约应答/等待状态或作用
S22-M01P→DMSG↓toolCallExecute见命令；事件无ACK按对应契约更新本调用状态
S22-M02D→PMSG↑toolCallSubmitrequestAck；10秒按对应契约更新本调用状态
S22-M03P→DMSG↓requestAck—；事件无ACK按对应契约更新本调用状态
S22-M04P→DMSG↓respTextDone见命令；事件无ACK按对应契约更新本调用状态
S22-M05P→DMSG↓respDone—；事件无ACK按对应契约更新本调用状态
S22-M06D→PSIG↑respCancel见命令；10秒按对应契约更新本调用状态
S22-M07P→DSIG↓requestAck见命令；事件无ACK按对应契约更新本调用状态
S22-M08P→DMSG↓respDone—；事件无ACK按对应契约更新本调用状态
S22-M09P→DMSG↓requestAck—；事件无ACK失败不产生新副作用
S22-M10P→DMSG↓respDone—；事件无ACK按对应契约更新本调用状态
S22-M11P→AAPP↓interaction.message—；事件无ACK按对应契约更新本调用状态
S22-M12A→PAPP↑interaction.control见命令；10秒按对应契约更新本调用状态
S22-M13P→AAPP↓interaction.result见命令；事件无ACK按对应契约更新本调用状态

逐条JSON

S22-M01 · toolCallExecute

{
  "msgToken": "s22-1",
  "method": "toolCallExecute",
  "sessionId": "s22-session",
  "messageSeq": 1,
  "data": {
    "respId": "reply-1",
    "toolCallId": "tool-1",
    "name": "set_local_display_theme",
    "arguments": {
      "theme": "dark"
    },
    "isFrontend": true,
    "interactionType": "action",
    "executionToken": "<scoped-single-call-token>",
    "expiresAt": 1900000000000
  }
}

S22-M02 · toolCallSubmit

{
  "msgToken": "s22-2",
  "method": "toolCallSubmit",
  "sessionId": "s22-session",
  "params": {
    "respId": "reply-1",
    "toolCallId": "tool-1",
    "executionToken": "<scoped-single-call-token>",
    "status": "succeeded",
    "result": {
      "theme": "dark"
    }
  }
}

S22-M03 · requestAck

{
  "msgToken": "s22-2",
  "method": "requestAck",
  "sessionId": "s22-session",
  "code": 200,
  "data": {
    "requestMethod": "toolCallSubmit",
    "result": {
      "respId": "reply-1",
      "toolCallId": "tool-1",
      "state": "accepted",
      "continuation": "accepted"
    }
  }
}

S22-M04 · respTextDone

{
  "msgToken": "s22-4",
  "method": "respTextDone",
  "sessionId": "s22-session",
  "messageSeq": 2,
  "data": {
    "respId": "reply-1",
    "contentIndex": 0,
    "text": "已收到你的确认。"
  }
}

S22-M05 · respDone

{
  "msgToken": "s22-5",
  "method": "respDone",
  "sessionId": "s22-session",
  "messageSeq": 3,
  "data": {
    "respId": "reply-1",
    "inputId": "input-1",
    "status": "completed",
    "contentCount": 1,
    "audioState": "none"
  }
}

S22-M06 · respCancel

{
  "msgToken": "s22-6",
  "method": "respCancel",
  "sessionId": "s22-session",
  "params": {
    "respId": "reply-1"
  }
}

S22-M07 · requestAck

{
  "msgToken": "s22-6",
  "method": "requestAck",
  "sessionId": "s22-session",
  "code": 200,
  "data": {
    "requestMethod": "respCancel",
    "result": {
      "respId": "reply-1",
      "state": "cancelled"
    }
  }
}

S22-M08 · respDone

{
  "msgToken": "s22-8",
  "method": "respDone",
  "sessionId": "s22-session",
  "messageSeq": 4,
  "data": {
    "respId": "reply-1",
    "inputId": "input-1",
    "status": "cancelled",
    "reason": "userCancelled",
    "contentCount": 0,
    "audioState": "none"
  }
}

S22-M09 · requestAck

{
  "msgToken": "s22-2",
  "method": "requestAck",
  "sessionId": "s22-session",
  "code": 409,
  "data": {
    "requestMethod": "toolCallSubmit",
    "reason": "toolCallExpired"
  }
}

S22-M10 · respDone

{
  "msgToken": "s22-10",
  "method": "respDone",
  "sessionId": "s22-session",
  "messageSeq": 5,
  "data": {
    "respId": "reply-1",
    "inputId": "input-1",
    "status": "failed",
    "reason": "toolTimeout",
    "contentCount": 0,
    "audioState": "none"
  }
}

S22-M11 · interaction.message

{
  "msgToken": "s22-11",
  "method": "interaction.message",
  "sessionId": "s22-session",
  "messageSeq": 6,
  "data": {
    "command": "toolCallExecute",
    "result": {
      "respId": "app-reply",
      "toolCallId": "app-tool",
      "name": "set_local_display_theme",
      "arguments": {
        "theme": "dark"
      },
      "isFrontend": true,
      "interactionType": "action",
      "executionToken": "<app-endpoint-token>",
      "expiresAt": 1900000000000
    }
  }
}

S22-M12 · interaction.control

{
  "msgToken": "s22-12",
  "method": "interaction.control",
  "sessionId": "s22-session",
  "params": {
    "command": "toolCallSubmit",
    "arguments": {
      "respId": "app-reply",
      "toolCallId": "app-tool",
      "executionToken": "<app-endpoint-token>",
      "status": "succeeded",
      "result": {
        "theme": "dark"
      }
    }
  }
}

S22-M13 · interaction.result

{
  "msgToken": "s22-12",
  "method": "interaction.result",
  "sessionId": "s22-session",
  "code": 200,
  "data": {
    "operation": "interaction.control",
    "state": "accepted",
    "result": {
      "respId": "app-reply",
      "toolCallId": "app-tool",
      "state": "accepted",
      "continuation": "accepted"
    }
  }
}

媒体与本地动作

本场景没有新增连续媒体箭头；文件引用或既有媒体会话按前置条件处理。

异常、状态与资源释放

requestAck(requestMethod=toolCallSubmit)的result.state=accepted只确认收到结果，模型续答仍可能失败；成功后同样等待respDone。取消终态与成功终态竞争时只允许一个胜出，重复终态不重复播报。应用M13只是结果受理，后续还必须收到interaction.message包裹的respTextDone/respDone；与设备M04/M05正文同构，不以HTTP202或M13冒充回复完成。工具超时可回注可验证的失败让模型解释；图中M10是无可用续答时的失败终态。

可选 result.continuation=accepted 只证明原 AISVR 已明确接纳此次结果；unknown、缺省或不认识的值均不证明续答成功，不触发重新执行或另建模型轮次。客户端继续按原 respId 消费内容／终态，未声明对应能力的端可忽略该字段；同 token 重试保持原 msgToken、requestMethod、toolCallId 和 ACK 字节。即使 state=accepted、continuation=unknown，已持久端结果也不能改成另一成功／失败结果或自动补投。

所有步骤使用公共错误和重试规则与S11：能力不足422、无权403、冲突/过期409、断线先sessionSync，终态不复活。未知执行结果不自动重试；会话结束释放等待者、令牌和本地UI。方法字段及迟到处理唯一来源是命令08。

验证入口

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

更新日志

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