Device

理解 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 转换。

示例

TypeScript

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`	请求超时或窗口销毁

排查路径

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

模块边界

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 转换。

示例

TypeScript

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
  );
}

错误码

场景

PERMISSION_DENIED

未授予 device.info

NOT_SUPPORTED

Windows 或宿主未注册 Device 插件

IO_ERROR

系统信息服务读取失败

TIMEOUT / CANCELLED

请求超时或窗口销毁

模块边界

平台与权限

返回字段

示例

隐私边界

平台差异

错误行为

排查路径

评论

On this page

模块边界

平台与权限

返回字段

示例

隐私边界

平台差异

错误行为

排查路径