Skip to content

imp 协议 #42

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
syureyi merged 1 commit into from
Nov 27, 2025
Merged

imp 协议 #42

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
65 changes: 61 additions & 4 deletions docs/xrobot/mcp/hardware-mcp.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -11,13 +11,19 @@ MCP（Model Context Protocol）是新一代推荐用于物联网控制的协议
## 目录

- [概述](#概述)
- [目录](#目录)
Copy link
Contributor

@gemini-code-assist gemini-code-assist bot Nov 27, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

medium

目录中存在一个指向自身的重复链接 [目录](#目录)。这会造成困惑，建议移除此多余条目。

- [典型使用流程](#典型使用流程)
- [流程图](#流程图)
- [协议格式规范](#协议格式规范)
- [整体消息结构](#整体消息结构)
- [JSON-RPC 2.0字段说明](#json-rpc-20字段说明)
- [详细交互流程](#详细交互流程)
- [连接建立与能力通告](#连接建立与能力通告)
- [初始化MCP会话](#初始化mcp会话)
- [发现设备工具列表](#发现设备工具列表)
- [调用设备工具](#调用设备工具)
- [步骤1：连接建立与能力通告](#步骤1连接建立与能力通告)
- [步骤2：初始化MCP会话](#步骤2初始化mcp会话)
- [步骤3：发现设备工具列表](#步骤3发现设备工具列表)
- [响应格式一：标准工具列表（向后兼容）](#响应格式一标准工具列表向后兼容)
- [响应格式二：带类型标识的工具列表（推荐）](#响应格式二带类型标识的工具列表推荐)
- [步骤4：调用设备工具](#步骤4调用设备工具)
- [设备端工具注册方法](#设备端工具注册方法)
- [AddTool方法说明](#addtool方法说明)
- [典型注册示例](#典型注册示例)
Expand Down Expand Up @@ -211,6 +217,8 @@ MCP协议的交互主要围绕客户端（灵矽AI平台）发现和调用设备

**📨 设备端 → 灵矽平台**

#### 响应格式一：标准工具列表（向后兼容）

```json
{
"jsonrpc": "2.0",
Expand Down Expand Up @@ -249,6 +257,55 @@ MCP协议的交互主要围绕客户端（灵矽AI平台）发现和调用设备
}
```

#### 响应格式二：带类型标识的工具列表（推荐）

为了同时支持标准工具（tool）和 RPC 函数调用（rpc），新增 `type` 字段用于区分工具类型：

```json
{
"jsonrpc": "2.0",
"id": 2, // 匹配请求 ID
"result": {
"tools": [ // 工具对象列表
{
"name": "self.get_device_status",
"description": "获取设备当前状态信息",
"type": <int>, // 函数类型，0 表示 tool 函数，1 表示 rpc 函数
Copy link
Contributor

@gemini-code-assist gemini-code-assist bot Nov 27, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

medium

在响应格式二的 JSON 示例中，type 字段的值为 <int>，这是一个占位符，不是有效的 JSON 值。为了使示例清晰且可直接使用，建议将其替换为一个具体的示例值，例如 1。

Suggested change
"type": <int>, // 函数类型，0 表示 tool 函数，1 表示 rpc 函数
"type": 1, // 函数类型，0 表示 tool 函数，1 表示 rpc 函数

Copy link

@xgopilot xgopilot bot Nov 27, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Invalid JSON Syntax

The placeholder <int> is not valid JSON. This should be replaced with an actual integer value to make the example valid and copy-paste friendly.

Suggested change
"type": <int>, // 函数类型，0 表示 tool 函数，1 表示 rpc 函数
"type": 0, // 函数类型,0 表示 tool 函数,1 表示 rpc 函数

"inputSchema": {
"type": "object",
"properties": {},
"required": []
}
},
{
"name": "self.audio_speaker.set_volume",
"description": "设置音箱音量",
"type": 0, // 函数类型，0 表示 tool 函数
"inputSchema": {
"type": "object",
"properties": {
"volume": {
"type": "integer",
"minimum": 0,
"maximum": 100,
"description": "音量大小，范围0-100"
}
},
"required": ["volume"]
}
}
// ... 更多工具
],
"nextCursor": null // 如果列表很大需要分页，这里会包含下一个请求的 cursor 值
}
}
```

**字段说明**：

- `type`：函数类型标识，0 表示 tool 函数，1 表示 rpc 函数
- 其他字段与标准 MCP 工具定义保持一致

**分页处理**：如果 `nextCursor` 字段非空，客户端需要再次发送 `tools/list` 请求，并在 `params` 中带上这个 cursor 值以获取下一页工具。

### 步骤4：调用设备工具
Expand Down
8 changes: 8 additions & 0 deletions docs/xrobot/platform/websocket.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -399,6 +399,14 @@ WebSocket 支持 **🎵 音频数据帧**（二进制方式）以及 **文本帧
}
```

##### 5. Notify 消息
Copy link

@xgopilot xgopilot bot Nov 27, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Incomplete Notify Message Documentation

The Notify message section lacks critical information:

  1. Missing session_id field - All other server messages include this field for consistency
  2. No validation guidance - How should devices authenticate/validate this notification?
  3. Missing connection management strategy - When should devices reconnect? Should they use exponential backoff to prevent thundering herd issues?
  4. No field documentation - What other event types exist besides config_updated?

Recommendations:

  • Add session_id field for consistency with other messages
  • Document reconnection strategy (complete active sessions first, use exponential backoff)
  • Add a table documenting the event field possible values
  • Include security validation requirements

```json
{
"type": "notify",
"event": "config_updated" // 智能体配置已更新，建议设备重新连接生效
}
```

### 2. MCP 相关消息

MCP（Model Control Protocol）是物联网控制的新一代协议，用于设备能力发现、状态同步和控制指令。
Expand Down