デバイス診断

# デバイス診断

デバイスの動作がおかしいときは、サーバー側の2つの事実から確認を始めます。デバイスの正規の状態と、デバイスが属するプロジェクト環境の開発者向けの安全なログです。どちらもControl APIから取得し、デバイス自体に問い合わせることはありません。同じ手順は、自分のサーバーからでも、[MCPガイド](MCP_GUIDE.md)を通じてAIクライアントからでも実行できます。

## 必要なもの

- デバイスのID（`dev_…`）、そのプロジェクトのIDと環境のID。
- そのプロジェクト環境で`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`がtrueの間は次のページを取得します。各エントリには、イベント、重大度、時刻、レイテンシ、関係するリソースの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`）を受け取ります。返すのは1つのオブジェクトで、`getDevice`にデバイスの正規の状態、`listDeveloperLogs`にログ1ページ分が入ります。
- `onesay.logs.timeline`は、それらのログにある`request_id`を受け取ります。
- `diagnose_device`プロンプトは、このページを使ってクライアントにこれらの手順を案内します。

どちらのツールもR1です。トークンが必要で、何も変更しません。

## この手順で扱わないこと

ボードのハードウェア、ファームウェア、無線の品質は、プラットフォームではなく、デバイスのOSとボードベンダーが診断します。デバイスのランタイムが送信しない限り、デバイス自身のローカルログがOneSayに届くことはありません。