---
title: "Clipboard"
description: "Kasumi 剪贴板插件的调用方式、权限与数据边界。"
---


> 理解 Clipboard 插件的文本读写命令、权限、平台行为和失败边界。

## 模块边界

Clipboard 插件只处理 UTF-8 文本，不提供图片、HTML、文件、富文本或自定义 MIME 类型。
读取失败按空文本处理，写入失败才返回错误。

| 层级 | 入口 | 责任 |
| --- | --- | --- |
| 前端 API | `frontend/src/api/clipboard.ts` | 参数守卫和命令封装 |
| 协议清单 | `protocol/plugins.json` | `clipboard` 插件和两个命令归属 |
| Windows 插件 | `windows/src/plugins/ksm_clipboard_plugin.cpp` | Win32 Unicode 剪贴板 |
| Android 插件 | `KSMClipboardPlugin.kt` | Android `ClipboardManager` |

## 平台与权限

| 命令 | Windows | Android | 权限 | 返回 |
| --- | --- | --- | --- | --- |
| `clipboard.readText` | 支持 | 支持 | `clipboard.read` | `{ text }` |
| `clipboard.writeText` | 支持 | 支持 | `clipboard.write` | `{ written }` |

## 方法与配置

```ts
await KSM.clipboard.writeText('Kasumi');

const { text } = await KSM.clipboard.readText();
console.info(text);
```

`writeText` 接收位置参数，不是 `{ text }` 对象。宿主不需要额外配置。

## 安全与数据边界

- 不记录剪贴板内容到日志、Store 或网络。
- 业务代码不应把读取结果直接写入持久存储，除非用户明确要求。
- 前端只校验参数形状，宿主仍检查当前窗口权限。
- 剪贴板内容是系统共享数据，其他应用可能在任意时间修改。

## 平台差异

| 项 | Windows | Android |
| --- | --- | --- |
| 读取 | `CF_UNICODETEXT` | 首个 item 的 `coerceToText` |
| 写入 | 清空后写入 Unicode 文本 | `ClipData.newPlainText` |
| 无内容 | 返回 `{ text: '' }` | 返回 `{ text: '' }` |
| 权限失败 | `PERMISSION_DENIED` | `PERMISSION_DENIED` |

## 错误行为

| 错误码 | 场景 |
| --- | --- |
| `INVALID_ARGS` | 写入文本不是字符串 |
| `PERMISSION_DENIED` | 当前窗口未授予读写权限 |
| `IO_ERROR` | 系统剪贴板拒绝写入 |
| `NOT_SUPPORTED` | 宿主未注册 Clipboard 插件 |
| `TIMEOUT` / `CANCELLED` | 请求超时或页面重载取消 |

## 排查路径

1. 确认 `capabilities.commands` 包含对应命令。
2. 确认 `capabilities.permissions` 包含 `clipboard.read` 或 `clipboard.write`。
3. 检查调用形式是否为 `writeText('text')`。
4. 读取空文本不等于平台错误，检查系统剪贴板当前是否包含文本。
5. 页面离开后不要用旧 Promise 结果更新新页面状态。