---
title: "Notification"
description: "Kasumi 通知插件的方法、权限申请和平台行为。"
---


> 理解 Notification 插件的短文本通知、Android 运行时授权和双端差异。

## 模块边界

Notification 插件只发送标题和正文通知，不提供点击路由、操作按钮、附件、图标管理、分组
或持久通知中心。通知权限和系统展示策略由宿主平台控制。

| 层级 | 入口 | 责任 |
| --- | --- | --- |
| 前端 API | `frontend/src/api/notification.ts` | 参数守卫和命令封装 |
| 协议清单 | `protocol/plugins.json` | `notification` 插件和命令归属 |
| Windows 插件 | `windows/src/plugins/ksm_notification_plugin.cpp` | Windows 通知服务 |
| Android 插件 | `KSMNotificationPlugin.kt` | Android 通知通道与权限 |

## 平台与权限

| 命令 | Windows | Android | 权限 | 返回 |
| --- | --- | --- | --- | --- |
| `notification.show` | 支持 | 支持 | `notification.show` | `{ shown }` |

Android 13 及以上需要先请求系统 `POST_NOTIFICATIONS` 权限。Windows 对已注册权限直接返回
granted，但系统通知策略仍可能影响可见性。

## 方法与配置

| 参数 | 类型 | 说明 |
| --- | --- | --- |
| `title` | string | 必填标题 |
| `body` | string | 必填正文 |

```ts
const permission = await KSM.permission.request('notification.show');
if (!permission.granted) {
  return;
}

await KSM.notification.show({
  title: 'Kasumi',
  body: '后台任务已完成'
});
```

`permission.request` 会更新宿主权限集合，但前端 `KSM.capabilities()` 缓存不会自动刷新。

## 安全与生命周期

- 通知正文不得包含密码、令牌、连接串或未脱敏用户数据。
- 业务高频进度不应逐条通知，优先合并状态。
- Android 页面销毁后，当前窗口请求由宿主取消，迟到响应不得投递。
- 通知点击行为不属于本插件，需要应用自行扩展原生宿主。

## 平台差异

| 项 | Windows | Android |
| --- | --- | --- |
| 权限模型 | 已注册权限 | Android 13+ 运行时权限 |
| 通知通道 | 系统宿主服务 | `kasumi` 通知通道 |
| 点击路由 | 不提供 | 不提供 |
| 持久化 | 不提供 | 不提供 |

## 错误行为

| 错误码 | 场景 |
| --- | --- |
| `INVALID_ARGS` | 标题或正文不是字符串 |
| `PERMISSION_DENIED` | 未授予通知权限 |
| `IO_ERROR` | 宿主通知服务拒绝发送 |
| `NOT_SUPPORTED` | 宿主未注册 Notification 插件 |
| `TIMEOUT` / `CANCELLED` | 请求超时或页面销毁 |

## 排查路径

1. 先调用 `KSM.permission.request('notification.show')`。
2. 检查 `capabilities.permissions` 和 `capabilities.commands`。
3. Android 检查系统通知总开关和应用通知权限。
4. 确认标题与正文不是空值，且正文已完成脱敏。
5. 通知未显示但返回 `shown: true` 时，检查平台通知策略而不是重试发送。