---
title: "Store 插件"
description: "应用数据目录内的 JSON 键值存储。"
---


> 理解 Store 插件的 JSON 存储位置、容量限制、权限和并发边界。

## 模块边界

Store 插件保存小型 JSON 键值状态，写入应用私有数据目录
`app://data/.kasumi/store.json`。它不是数据库，不提供查询、索引、事务、迁移或跨设备同步。
需要关系查询时使用 SQL 插件，需要大文件时使用文件系统插件。

| 层级 | 入口 | 责任 |
| --- | --- | --- |
| 前端 API | `frontend/src/api/store.ts` | JSON 参数守卫和命令封装 |
| 协议清单 | `protocol/plugins.json` | 五个命令归属 `store` |
| Windows 插件 | `windows/src/plugins/ksm_store_plugin.cpp` | JSON 文件读写和进程内串行化 |
| Android 插件 | `KSMStorePlugin.kt` | 与 Windows 对齐的存储规则 |

## 方法

| 方法 | 参数 | 返回 |
| --- | --- | --- |
| `store.get` | `{ key }` | `{ found, value }` |
| `store.set` | `{ key, value }` | `{ updated: true }` |
| `store.delete` | `{ key }` | `{ deleted }` |
| `store.clear` | `{}` | `{ cleared: true }` |
| `store.keys` | `{}` | `{ keys }`，按字典序返回 |

## 存储规则

- 根值必须是 JSON 对象。
- key 长度为 1 到 256 字节。
- 单个值最大 1 MiB，整个存储文件最大 16 MiB。
- 值必须是 JSON 标量、数组或对象，不允许非有限数值。
- 同一插件实例内的操作串行执行，页面的多个调用不会并发覆盖同一个文件。
- `store.clear` 删除存储文件；之后读取未命中时返回 `found: false` 和 `value: null`。

## 示例

```ts
await KSM.store.set({
  key: 'profile',
  value: {
    theme: 'light',
    recent: ['home', 'settings']
  }
});

const result = await KSM.store.get({ key: 'profile' });
if (result.found) {
  console.info(result.value);
}

const keys = await KSM.store.keys();
await KSM.store.delete({ key: 'profile' });
```

## 平台差异

| 项 | Windows | Android |
| --- | --- | --- |
| 存储路径 | `app://data/.kasumi/store.json` | 同一虚拟路径 |
| 单值限制 | 1 MiB | 1 MiB |
| 总量限制 | 16 MiB | 16 MiB |
| 权限 | `store` | `store` |
| 持久化 | 应用数据目录 | 应用数据目录 |

## 错误行为

| 错误码 | 场景 |
| --- | --- |
| `INVALID_ARGS` | key 为空或超长、value 缺失、JSON 值非法或超过单值限制 |
| `PERMISSION_DENIED` | 当前请求没有 `store` 权限 |
| `IO_ERROR` | 存储文件损坏、读取失败、写入失败或总量超限 |
| `NOT_SUPPORTED` | 当前宿主没有注册 `store` 插件或文件系统服务 |
| `TIMEOUT` / `CANCELLED` | 请求被超时或取消链路终止 |

## 排查路径

1. 调用 `KSM.capabilities()` 确认 `store` 权限和命令存在。
2. 检查 key 是否超过 256 字节。
3. 检查单个 value 和整个存储是否超过大小限制。
4. 存储文件损坏时保留原始数据并修复写入方，不要静默覆盖。
5. 高频状态更新应先合并到业务内存，再按需写入，避免每次交互都落盘。