code-cache

AI 代理的语义代码缓存。缓存、检索和重用先前代理执行的代码。

# Code Cache - Semantic Code Caching for AI Agents

This skill enables semantic code caching via the [Raysurfer](https://raysurfer.com) API.

## What It Does

When your agent generates and executes code, Code Cache stores it. When a similar task comes up later, the agent can retrieve and run the cached code instead of regenerating it—saving time and tokens.

## Setup

Get your API key from the [Raysurfer dashboard](https://raysurfer.com/dashboard/api-keys) and configure it:

```bash
# Via environment variable
export RAYSURFER_API_KEY=your_api_key_here

# Or via OpenClaw config
openclaw config set skills.entries.code-cache.apiKey "your_api_key_here"
```

## Available Commands

### Search for cached code

```
/code-cache search <task description> [--top-k N] [--min-score FLOAT] [--show-code]
```

Search for cached code snippets that match a natural language task description.

**Options:**
- `--top-k N` — Maximum number of results (default: 5)
- `--min-score FLOAT` — Minimum verdict score filter (default: 0.3)
- `--show-code` — Display the source code of the top match

**Example:**
```
/code-cache search "Generate a quarterly revenue report"
/code-cache search "Fetch GitHub trending repos" --top-k 3 --show-code
```

### Get code files for a task

```
/code-cache files <task description> [--top-k N] [--cache-dir DIR]
```

Retrieve code files ready for execution, with a pre-formatted prompt addition for your LLM.

**Options:**
- `--top-k N` — Maximum number of files (default: 5)
- `--cache-dir DIR` — Output directory (default: `.code_cache`)

**Example:**
```
/code-cache files "Fetch GitHub trending repos"
/code-cache files "Build a chart" --cache-dir ./cached_code
```

### Upload code to cache

```
/code-cache upload <task> --files <path> [<path>...] [--failed] [--no-auto-vote]
```

Upload code from an execution to the cache for future reuse.

**Options:**
- `--files, -f` — Files to upload (required, can specify multiple)
- `--failed` — Mark the execution as failed (default: succeeded)
- `--no-auto-vote` — Disable automatic voting on stored code blocks

**Example:**
```
/code-cache upload "Build a chart" --files chart.py
/code-cache upload "Data pipeline" -f extract.py transform.py load.py
/code-cache upload "Failed attempt" --files broken.py --failed
```

### Vote on cached code

```
/code-cache vote <code_block_id> [--up|--down] [--task TEXT] [--name TEXT] [--description TEXT]
```

Vote on whether cached code was useful. This improves retrieval quality over time.

**Options:**
- `--up` — Upvote / thumbs up (default)
- `--down` — Downvote / thumbs down
- `--task` — Original task description (optional)
- `--name` — Code block name (optional)
- `--description` — Code block description (optional)

**Example:**
```
/code-cache vote abc123 --up
/code-cache vote xyz789 --down --task "Generate report"
```

## How It Works

1. **Cache Hit**: When you ask for code similar to something previously executed, Code Cache returns the cached version instantly
2. **Cache Miss**: When no match exists, your agent generates code normally, then Code Cache stores it for future use
3. **Verdict Scoring**: Code that works gets 👍, code that fails gets 👎—retrieval improves over time

## API Reference

The skill wraps these Raysurfer API methods:

| Method | Description |
|--------|-------------|
| `search(task, top_k, min_verdict_score)` | Unified search for cached code snippets |
| `get_code_files(task, top_k, cache_dir)` | Get code files ready for sandbox execution |
| `upload_new_code_snips(task, files_written, succeeded, auto_vote)` | Store new code after execution |
| `vote_code_snip(task, code_block_id, code_block_name, code_block_description, succeeded)` | Vote on snippet usefulness |

## Why Code Caching?

LLM agents repeat the same patterns constantly. Instead of regenerating code every time:

- **30x faster**: Retrieve proven code instead of waiting for generation
- **Lower costs**: Reduce token usage by reusing cached solutions  
- **Higher quality**: Cached code has been validated and voted on
- **Consistent output**: Same task = same proven solution

Learn more at [raysurfer.com](https://raysurfer.com) or read the [documentation](https://docs.raysurfer.com).

---

## 中文说明

# Code Cache —— 面向 AI 智能体的语义代码缓存

本技能通过 [Raysurfer](https://raysurfer.com) API 实现语义代码缓存。

## 它的作用

当你的智能体生成并执行代码时，Code Cache 会将其存储下来。当之后出现类似任务时，智能体可以检索并直接运行缓存的代码，而无需重新生成 —— 从而节省时间和 token。

## 设置

从 [Raysurfer dashboard](https://raysurfer.com/dashboard/api-keys) 获取你的 API 密钥并进行配置：

```bash
# Via environment variable
export RAYSURFER_API_KEY=your_api_key_here

# Or via OpenClaw config
openclaw config set skills.entries.code-cache.apiKey "your_api_key_here"
```

## 可用命令

### 搜索缓存的代码

```
/code-cache search <task description> [--top-k N] [--min-score FLOAT] [--show-code]
```

根据自然语言任务描述搜索匹配的缓存代码片段。

**选项：**
- `--top-k N` — 最大结果数（默认：5）
- `--min-score FLOAT` — 最低评判分数过滤阈值（默认：0.3）
- `--show-code` — 显示最佳匹配项的源代码

**示例：**
```
/code-cache search "Generate a quarterly revenue report"
/code-cache search "Fetch GitHub trending repos" --top-k 3 --show-code
```

### 获取某任务的代码文件

```
/code-cache files <task description> [--top-k N] [--cache-dir DIR]
```

检索可直接执行的代码文件，并附带为你的 LLM 预格式化的提示词补充内容。

**选项：**
- `--top-k N` — 最大文件数（默认：5）
- `--cache-dir DIR` — 输出目录（默认：`.code_cache`）

**示例：**
```
/code-cache files "Fetch GitHub trending repos"
/code-cache files "Build a chart" --cache-dir ./cached_code
```

### 上传代码到缓存

```
/code-cache upload <task> --files <path> [<path>...] [--failed] [--no-auto-vote]
```

将一次执行中产生的代码上传到缓存，以供将来复用。

**选项：**
- `--files, -f` — 要上传的文件（必填，可指定多个）
- `--failed` — 将该次执行标记为失败（默认：成功）
- `--no-auto-vote` — 禁用对已存储代码块的自动投票

**示例：**
```
/code-cache upload "Build a chart" --files chart.py
/code-cache upload "Data pipeline" -f extract.py transform.py load.py
/code-cache upload "Failed attempt" --files broken.py --failed
```

### 为缓存的代码投票

```
/code-cache vote <code_block_id> [--up|--down] [--task TEXT] [--name TEXT] [--description TEXT]
```

对缓存的代码是否有用进行投票。这能随时间提升检索质量。

**选项：**
- `--up` — 点赞 / 赞成（默认）
- `--down` — 点踩 / 反对
- `--task` — 原始任务描述（可选）
- `--name` — 代码块名称（可选）
- `--description` — 代码块描述（可选）

**示例：**
```
/code-cache vote abc123 --up
/code-cache vote xyz789 --down --task "Generate report"
```

## 工作原理

1. **缓存命中（Cache Hit）**：当你请求与此前执行过的代码相似的代码时，Code Cache 会立即返回缓存版本
2. **缓存未命中（Cache Miss）**：当不存在匹配项时，你的智能体正常生成代码，随后 Code Cache 将其存储以供将来使用
3. **评判评分（Verdict Scoring）**：有效的代码得 👍，失败的代码得 👎 —— 检索质量随时间不断提升

## API 参考

本技能封装了以下 Raysurfer API 方法：

| 方法 | 说明 |
|--------|-------------|
| `search(task, top_k, min_verdict_score)` | 对缓存代码片段进行统一搜索 |
| `get_code_files(task, top_k, cache_dir)` | 获取可用于沙箱执行的代码文件 |
| `upload_new_code_snips(task, files_written, succeeded, auto_vote)` | 在执行后存储新代码 |
| `vote_code_snip(task, code_block_id, code_block_name, code_block_description, succeeded)` | 对代码片段的有用程度投票 |

## 为什么要做代码缓存？

LLM 智能体会不断重复相同的模式。与其每次都重新生成代码：

- **快 30 倍**：检索经过验证的代码，而非等待生成
- **更低成本**：通过复用缓存方案减少 token 用量
- **更高质量**：缓存代码已经过验证和投票
- **输出一致**：相同任务 = 相同的经过验证的方案

了解更多请访问 [raysurfer.com](https://raysurfer.com) 或阅读[文档](https://docs.raysurfer.com)。