---
name: l1-kv-store
description: "L1 原子技能：键值对存取。基于本地 JSON 文件的持久化 Key-Value 存储，用于跨任务状态管理。"
layer: 1
domain: memory
keywords:
  - store
  - save
  - load
  - state
  - memory
  - key
  - value
  - persist
input_schema: "{ action: string, key: string, value?: any }"
output_schema: "{ success: boolean, value?: any }"
---

# L1: KV Store（键值存储原子技能）

## 能力

基于本地 JSON 文件的键值对存取，支持跨任务的状态持久化。

## 使用方法

存储文件路径：`~/.lemonape/kv_store.json`

### 写入 (SET)

```bash
python3 -c "
import json, os, sys

STORE = os.path.expanduser('~/.lemonape/kv_store.json')
os.makedirs(os.path.dirname(STORE), exist_ok=True)

# 读取现有数据
data = {}
if os.path.exists(STORE):
    with open(STORE, 'r') as f:
        data = json.load(f)

# 写入
key = sys.argv[1]
value = sys.argv[2]
data[key] = {'value': value, 'updated_at': __import__('datetime').datetime.now().isoformat()}

with open(STORE, 'w') as f:
    json.dump(data, f, indent=2, ensure_ascii=False)

print(f'OK: {key} = {value}')
" "<KEY>" "<VALUE>"
```

### 读取 (GET)

```bash
python3 -c "
import json, os, sys

STORE = os.path.expanduser('~/.lemonape/kv_store.json')
if not os.path.exists(STORE):
    print('NOT_FOUND'); sys.exit(1)

with open(STORE, 'r') as f:
    data = json.load(f)

key = sys.argv[1]
if key in data:
    print(data[key]['value'])
else:
    print('NOT_FOUND')
" "<KEY>"
```

### 删除 (DELETE)

```bash
python3 -c "
import json, os, sys

STORE = os.path.expanduser('~/.lemonape/kv_store.json')
if not os.path.exists(STORE):
    print('NOT_FOUND'); sys.exit(0)

with open(STORE, 'r') as f:
    data = json.load(f)

key = sys.argv[1]
if key in data:
    del data[key]
    with open(STORE, 'w') as f:
        json.dump(data, f, indent=2, ensure_ascii=False)
    print(f'DELETED: {key}')
else:
    print('NOT_FOUND')
" "<KEY>"
```

### 列出所有键 (LIST)

```bash
python3 -c "
import json, os

STORE = os.path.expanduser('~/.lemonape/kv_store.json')
if not os.path.exists(STORE):
    print('(empty)'); exit()

with open(STORE, 'r') as f:
    data = json.load(f)

for k, v in data.items():
    print(f'{k} = {v[\"value\"]} (updated: {v[\"updated_at\"]})')
"
```

## 输入

| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| action | string | ✅ | `set` / `get` / `delete` / `list` |
| key | string | ✅* | 键名（list 操作不需要） |
| value | any | ❌ | 值（仅 set 操作） |

## 输出

| 操作 | 输出 |
|------|------|
| set | `OK: key = value` |
| get | 值内容 或 `NOT_FOUND` |
| delete | `DELETED: key` 或 `NOT_FOUND` |
| list | 所有键值对列表 |

## 约束

- 存储文件：`~/.lemonape/kv_store.json`
- 单个 value 最大 10000 字符
- 不支持嵌套对象作为 value（请先 JSON.stringify）
- 并发安全性：单进程写入安全，不支持多进程并发写