名称： raysurfer
描述： "通过 Raysurfer 缓存和复用先前 AI 智能体执行的代码。先搜索，成功后再上传。"
argument-hint: "[搜索查询或 \"upload\"]"
允许工具：
- Bash
- Read
- Write
- Edit
- Grep
- Glob

Raysurfer 代码缓存技能

你可以使用 Raysurfer，这是一个用于存储和检索先前 AI 智能体执行代码的缓存系统。在编写新代码前，务必先检查缓存，并在成功后上传结果。

环境

• API 基础 URL: https://api.raysurfer.com
• 认证: 通过 RAYSURFER_API_KEY 环境变量使用 Bearer Token
• 所有 API 调用均使用 Content-Type: application/json

工作流程

针对每个编码任务，请遵循以下步骤：

步骤 1：搜索缓存

在编写任何代码之前，先搜索现有的缓存解决方案。

如需同时包含社区公开代码片段（从 GitHub 爬取），请添加 X-Raysurfer-Public-Snips: true 请求头。

curl -s -X POST https://api.raysurfer.com/api/retrieve/search \
  -H "Authorization: Bearer $RAYSURFER_API_KEY" \
  -H "Content-Type: application/json" \
  -H "X-Raysurfer-Public-Snips: true" \
  -d '{"task": "<在此处描述任务>", "top_k": 5, "min_verdict_score": 0.3}'

响应内容包含：

{
  "matches": [
    {
      "code_block": {
        "id": "uuid",
        "name": "描述性名称",
        "description": "此代码的功能",
        "source": "实际的代码内容",
        "language": "python"
      },
      "combined_score": 0.85,
      "filename": "suggested_filename.py",
      "thumbs_up": 12,
      "thumbs_down": 1
    }
  ],
  "total_found": 3,
  "cache_hit": true
}

决策逻辑：
- 如果 total_found > 0 且最佳匹配的 combined_score >= 0.7 且投票比例良好（thumbs_up > thumbs_down），则使用缓存的代码。
- 如果存在匹配项但分数较低，则以其为基础进行修改和适配。
- 如果没有匹配项，则从头开始生成代码。

步骤 2a：使用缓存代码（缓存命中）

当找到良好的缓存命中时：
1. 从最佳匹配的 code_block 中提取 source 字段。
2. 将其写入适当的文件。
3. 根据需要调整路径、变量名或配置以适应当前项目。
4. 运行代码以验证其正常工作。
5. 进入步骤 3（投票）。

步骤 2b：生成代码（缓存未命中）

当没有合适的缓存命中时：
1. 像往常一样编写代码。
2. 运行代码以验证其正常工作。
3. 进入步骤 4（上传）。

步骤 3：对缓存代码投票

使用缓存代码后，报告其是否有效：

curl -s -X POST https://api.raysurfer.com/api/store/cache-usage \
  -H "Authorization: Bearer $RAYSURFER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"code_block_id": "<来自匹配项的id>", "code_block_name": "<来自匹配项的name>", "code_block_description": "<来自匹配项的description>", "succeeded": true, "task": "<任务描述>"}'

如果代码运行正确，将 succeeded 设置为 true；如果失败或需要重大修改，则设置为 false。

步骤 4：上传新代码

成功生成并运行新代码（缓存未命中）后，将其上传以供将来复用：

curl -s -X POST https://api.raysurfer.com/api/store/execution-result \
  -H "Authorization: Bearer $RAYSURFER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "task": "<描述此代码的功能>",
    "file_written": {"path": "relative/path/to/file.py", "content": "<完整的文件内容>"},
    "succeeded": true
  }'

仅上传成功执行的代码。默认启用 AI 投票。

参数处理

• 如果调用时附带搜索查询（例如 /raysurfer parse CSV and generate chart），则使用该查询作为任务描述执行步骤 1。
• 如果调用时附带 upload（例如 /raysurfer upload），则为对话中最近生成的代码执行步骤 4。
• 如果调用时没有参数，则显示工作流程摘要并询问用户想要做什么。

当提供 $ARGUMENTS 时，将其用作：$ARGUMENTS

可运行脚本

此技能目录中提供了可直接运行的脚本。需要设置 RAYSURFER_API_KEY。

搜索

python search.py "Parse a CSV and plot a chart"
bun search.ts "Parse a CSV and plot a chart"
bash search.sh "Parse a CSV and plot a chart"

上传

python upload.py "Generate a bar chart" chart.py
bun upload.ts "Generate a bar chart" chart.py
bash upload.sh "Generate a bar chart" chart.py

指南

• 在进行 API 调用前，务必验证 RAYSURFER_API_KEY 是否已设置。如果未设置，请通知用户并跳过缓存操作。
• 编写描述性的 task 字符串，说明代码的功能，而非实现方式（例如，使用“解析 CSV 文件并使用 matplotlib 生成条形图”，而不是“运行 pandas read_csv 和 plt.bar”）。
• 切勿在任何命令或文件中硬编码 API 密钥。
• 如果 API 无法访问，请继续正常生成代码，不要阻塞用户。
• 尽可能保持上传的代码自包含，以最大化其可复用性。

快速参考

完整的请求和响应模式请参阅 references/api-reference.md。