---
title: "OS 插件"
description: "非持久操作系统和运行时信息。"
---


> 理解 OS 插件的系统信息字段、隐私边界和平台差异。

## 模块边界

OS 插件返回当前运行时和宿主应用的非持久系统信息。它不读取主机名、用户名、序列号、
设备标识、硬件指纹或其他可用于长期追踪的字段。

| 层级 | 入口 | 责任 |
| --- | --- | --- |
| 前端 API | `frontend/src/api/os.ts` | 命令封装 |
| 协议清单 | `protocol/plugins.json` | `os.getInfo` 归属 `os` |
| Windows 插件 | `windows/src/plugins/ksm_os_plugin.cpp` | 读取宿主系统服务 |
| Android 插件 | `KSMOperatingSystemPlugin.kt` | 读取 Android `Build` 和时区 |

## 返回字段

| 字段 | 类型 | 说明 |
| --- | --- | --- |
| `platform` | `windows` / `android` | 当前宿主平台 |
| `architecture` | string | 首选 CPU 架构 |
| `version` | string | 操作系统版本 |
| `locale` | string | 当前语言标签 |
| `timezone` | string | 当前时区 ID |
| `appVersion` | string | 宿主应用版本 |

## 示例

```ts
const info = await KSM.os.getInfo();
console.info(info.platform, info.version, info.appVersion);
```

## 隐私边界

- 不返回 Android ID、IMEI、序列号、广告 ID 或持久设备标识。
- 不返回主机名、用户名、硬件序列号或完整文件路径。
- 结果只用于兼容性、展示和诊断，不应作为用户身份。
- 需要设备型号等 Android 专属字段时使用 `KSM.device.getInfo()`。

## 平台差异

| 项 | Windows | Android |
| --- | --- | --- |
| 命令支持 | 支持 | 支持 |
| 架构来源 | 宿主系统服务 | `Build.SUPPORTED_ABIS` 首选值 |
| 版本来源 | Windows 版本信息 | `Build.VERSION.RELEASE` |
| 时区来源 | 宿主运行时 | `TimeZone.getDefault().id` |

## 错误行为

| 错误码 | 场景 |
| --- | --- |
| `PERMISSION_DENIED` | 当前请求没有 `os.info` 权限 |
| `NOT_SUPPORTED` | 宿主没有注册 `os` 插件或没有系统信息服务 |
| `TIMEOUT` / `CANCELLED` | 请求被超时或取消链路终止 |

## 排查路径

1. 确认 `capabilities.query` 返回 `os.getInfo` 和 `os.info`。
2. 确认宿主实现了系统信息服务。
3. 确认应用 allowlist 包含 `os.getInfo`。
4. 需要设备型号时改用 Android 的 `device.getInfo`，不要把 OS 信息扩展成设备指纹。