设备诊断

# 设备诊断

设备出现异常时，先看服务端的两项事实：设备的服务端状态，以及它所属项目环境中可供开发者查看的脱敏日志。两者都来自Control API，不会查询设备本身。这些步骤既可以从你自己的服务器执行，也可以由AI客户端按[MCP指南](MCP_GUIDE.md)执行。

## 准备工作

- 设备ID（`dev_…`），以及它的项目ID和环境ID。
- 你账号的访问Token，并且在该项目环境中拥有`device.read`和`logs.read`授权。

## 读取设备的服务端状态

`GET /v1/devices/{device_id}`返回OneSay记录的设备信息。这一状态的来源是Control API，而不是设备：即使设备连不上OneSay，这里仍保留它最后一次记录的状态。

## 搜索脱敏日志

`GET /v1/logs?project_id=…&environment_id=…`按页列出该项目环境的脱敏日志：把`next_cursor`作为`cursor`传回以获取下一页，直到`has_more`为false。每条日志包含事件、严重级别、时间、延迟、相关资源的ID（在其中查找你的`device_id`），以及`error_code`等安全字段。日志绝不包含音频、转写文本或凭据。

每条日志都带有`request_id`（`req_…`）。`GET /v1/logs/{request_id}`返回该请求的时间线，从中可以看出失败的调用停在了哪一步。

## 使用AI客户端

- `onesay.devices.diagnose`接收`device_id`、`project_id`和`environment_id`（以及可选的`cursor`和`limit`），返回一个对象：`getDevice`下是设备的服务端状态，`listDeveloperLogs`下是一页日志。
- `onesay.logs.timeline`接收上述日志中的`request_id`。
- `diagnose_device`提示词会参照本页，引导客户端完成这些步骤。

这两个工具都属于R1：需要Token，不做任何更改。

## 这些步骤不涵盖的内容

开发板硬件、固件和无线射频质量由设备的OS和开发板厂商诊断，不归平台负责。设备自身的本地日志不会到达OneSay，除非设备运行时主动上报。