---
title: "Store API"
description: "TypeScript JSON 键值存储 API。"
---


> 在 TypeScript 中读写应用私有目录内的 JSON 键值状态。

## 模块边界

`KSM.store` 封装 Store 插件，适合主题、偏好和少量结构化状态。它不是数据库，不提供查询、
索引、事务或迁移。复杂关系数据使用 `KSM.sql`，大文件使用 `KSM.fs`。

实现入口是 `frontend/src/api/store.ts` 和 `frontend/src/api/guards.ts`。

## 平台支持

| 能力 | Windows | Android |
| --- | --- | --- |
| 五个 Store 命令 | 支持 | 支持 |
| 存储位置 | `app://data/.kasumi/store.json` | 同一虚拟路径 |

## 方法

### `get({ key })`

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

未命中返回 `{ found: false, value: null }`。

### `set({ key, value })`

```ts
await KSM.store.set({
  key: 'profile',
  value: { theme: 'light', compact: true }
});
```

key 最大 256 字节，单个 value 最大 1 MiB。value 必须是合法 JSON 值。

### `delete({ key })`、`clear()`、`keys()`

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

`keys()` 按字典序返回键名。`clear()` 删除整个存储文件。

## 限制

- 整个存储文件最大 16 MiB。
- 同一插件实例内的操作串行执行。
- 存储文件损坏时返回 `IO_ERROR`，不会自动丢弃原始内容。
- 不提供跨设备同步或服务端备份。

## 错误行为

| 错误码 | 场景 |
| --- | --- |
| `INVALID_ARGS` | key、value 或大小非法 |
| `PERMISSION_DENIED` | 没有 `store` 权限 |
| `IO_ERROR` | 读取失败、写入失败、文件损坏或总量超限 |
| `NOT_SUPPORTED` | 宿主未注册 Store 插件 |
| `TIMEOUT` / `CANCELLED` | 请求被超时或取消 |

## 相关

- [Store 插件规则](/docs/kasumi/plugins/store)
- [SQL API](/docs/kasumi/api/sql)
- [共享类型](/docs/kasumi/api/types)

## 排查路径

1. 确认 key 和 JSON value 大小。
2. 确认 `capabilities.query` 返回 Store 命令和 `store` 权限。
3. 高频更新时先在业务层合并状态，再写入 Store。
4. 存储损坏时检查写入方是否绕过了插件。