---
title: "Device"
description: "Kasumi 设备信息插件的方法、字段边界与隐私约束。"
---


> 理解 Device 插件的 Android 设备字段、显示单位、隐私边界和平台差异。

## 模块边界

Device 插件只提供适配布局、语言和诊断所需的非持久设备信息。它不返回 Android ID、IMEI、
序列号、广告 ID、MAC 地址或其他可用于跨会话追踪的标识。

| 层级 | 入口 | 责任 |
| --- | --- | --- |
| 前端 API | `frontend/src/api/device.ts` | `KSM.device.getInfo` 封装 |
| 协议清单 | `protocol/plugins.json` | `device` 插件和命令归属 |
| Android 实现 | `KSMAndroidHostServices.kt` | 从 `Build`、窗口度量和资源读取 |
| Windows | 不注册 | 调用返回 `NOT_SUPPORTED` |

## 平台与权限

| 命令 | Windows | Android | 权限 | 返回 |
| --- | --- | --- | --- | --- |
| `device.getInfo` | 不支持 | 支持 | `device.info` | `KSMDeviceInfo` |

## 返回字段

| 字段 | 类型 | 说明 |
| --- | --- | --- |
| `platform` | `"android"` | 固定平台值 |
| `osVersion` | string | Android 版本字符串 |
| `model` | string | `Build.MODEL` |
| `manufacturer` | string | `Build.MANUFACTURER` |
| `appVersion` | string | 宿主应用版本 |
| `language` | string | 当前语言标签 |
| `screenWidth` | number | 当前窗口度量的物理像素宽度 |
| `screenHeight` | number | 当前窗口度量的物理像素高度 |
| `density` | number | Android 显示密度 |
| `deviceName` | string | 系统设备名，读取失败时回退到 `Build.MODEL` |
| `timezone` | string | 当前时区 ID |
| `architecture` | string | `Build.SUPPORTED_ABIS` 首选值 |

屏幕尺寸不是 CSS 像素。需要逻辑尺寸时，使用浏览器布局信息或根据 `density` 转换。

## 示例

```ts
const capabilities = await KSM.capabilities();
if (capabilities.commands.includes('device.getInfo')) {
  const info = await KSM.device.getInfo();
  console.info(
    `${info.manufacturer} ${info.model}`,
    `${info.screenWidth}x${info.screenHeight}@${info.density}`,
    info.timezone
  );
}
```

## 隐私边界

- 字段只用于界面适配、兼容性和诊断。
- 不返回持久设备标识。
- 不把 manufacturer、model 或 deviceName 组合成设备指纹。
- 需要普通系统版本、架构、语言和时区时优先使用 OS 插件。

## 平台差异

该插件只在 Android 注册。旋转、分屏或多窗口变化后，`screenWidth` 和 `screenHeight`
可能变化。`deviceName` 依赖厂商系统实现，可能为空或返回通用名称。

## 错误行为

| 错误码 | 场景 |
| --- | --- |
| `PERMISSION_DENIED` | 未授予 `device.info` |
| `NOT_SUPPORTED` | Windows 或宿主未注册 Device 插件 |
| `IO_ERROR` | 系统信息服务读取失败 |
| `TIMEOUT` / `CANCELLED` | 请求超时或窗口销毁 |

## 排查路径

1. 确认当前平台是 Android，能力列表包含 `device.getInfo`。
2. 确认当前窗口拥有 `device.info`。
3. 旋转或分屏后重新读取，不要长期缓存窗口像素尺寸。
4. 设备名为空时确认已回退到 `Build.MODEL`。
5. 不要把返回值用于持久设备识别或风控指纹。