foxcode-opencode-cache

为 OpenCode 提供 Foxcode 多渠道智能缓存优化，大幅降低 API 费用。

✨ 特性

• 🚀 多渠道支持: 自动识别并优化 Claude、Codex、Gemini 三种渠道
• 💰 节省费用: 通过缓存优化减少重复计算，降低 API 调用成本
• 🔧 即插即用: 一次配置，自动应用到所有支持的 provider
• 🎯 智能识别: 根据 provider 名称自动选择最佳缓存策略
• 📊 调试支持: 可选的详细日志输出

为什么需要

不同的 AI 服务商对缓存有不同的要求：

Claude 渠道

Foxcode 等中转服务的 AWS 渠道要求请求中必须包含 metadata.user_id 字段才能启用 Prompt 缓存。

没有此插件：每次请求都按全价计费
使用此插件：自动注入 user_id，启用缓存，节省费用

Codex 渠道

OpenAI Codex API 使用自动前缀缓存，但某些客户端会在每次请求中注入动态时间戳，导致前缀永远不匹配。

没有此插件：动态时间戳破坏缓存，每次全量计费
使用此插件：移除时间戳 + 注入稳定的 prompt_cache_key，提高缓存命中率

Gemini 渠道

Gemini 2.5+ 支持隐式缓存，同样需要移除动态时间戳以稳定缓存前缀。

没有此插件：时间戳导致缓存失效
使用此插件：自动移除时间戳，提高缓存效率

📦 安装

npm install -g foxcode-opencode-cache

🚀 快速开始

方式 1: 使用预置插件（推荐）

插件内置了常用 provider 的支持，只需在配置文件中添加插件名称：

{
  "plugin": ["foxcode-opencode-cache"]
}

这会自动启用以下 provider 的缓存优化：

• Claude 渠道: foxcode-aws, foxcode-droid, foxcode-super, foxcode-ultra, anthropic
• Codex 渠道: foxcode-codex, openai-codex
• Gemini 渠道: foxcode-gemini, google-gemini

方式 2: 自定义 provider

如果你的 provider 名称不在预置列表中，可以使用工厂函数创建自定义插件。

在项目根目录创建 opencode-cache-plugin.mjs：

import { createCachePlugin } from "foxcode-opencode-cache";

// 为你的自定义 provider 创建缓存插件
export default createCachePlugin("your-custom-provider-name");

然后在 opencode.json 中引用：

{
  "plugin": [
    "./opencode-cache-plugin.mjs"
  ]
}

🔧 配置示例

Claude Provider 配置

{
  "provider": {
    "foxcode-aws": {
      "npm": "@ai-sdk/anthropic",
      "options": {
        "baseURL": "https://code.newcli.com/claude/aws/v1",
        "litellmProxy": true
      },
      "models": {
        "claude-opus-4-5": { "name": "claude-opus-4-5" },
        "claude-sonnet-4-5": { "name": "claude-sonnet-4-5" }
      }
    },
    "foxcode-ultra": {
      "npm": "@ai-sdk/anthropic",
      "options": {
        "baseURL": "https://code.newcli.com/claude/ultra/v1",
        "apiKey": "your-api-key"
      },
      "models": {
        "claude-opus-4-5": { "name": "claude-opus-4-5" }
      }
    }
  },
  "plugin": ["foxcode-opencode-cache"]
}

Codex Provider 配置

{
  "provider": {
    "foxcode-codex": {
      "npm": "@ai-sdk/openai",
      "options": {
        "baseURL": "https://code.newcli.com/codex/v1",
        "apiKey": "your-api-key"
      },
      "models": {
        "gpt-4-turbo": { "name": "gpt-4-turbo" }
      }
    }
  },
  "plugin": ["foxcode-opencode-cache"]
}

Gemini Provider 配置

{
  "provider": {
    "foxcode-gemini": {
      "npm": "@ai-sdk/google",
      "options": {
        "baseURL": "https://code.newcli.com/gemini/v1",
        "apiKey": "your-api-key"
      },
      "models": {
        "gemini-2.5-pro": { "name": "gemini-2.5-pro" }
      }
    }
  },
  "plugin": ["foxcode-opencode-cache"]
}

🔍 工作原理

插件通过拦截 API 请求，根据 provider 类型自动应用不同的缓存优化策略：

Claude 渠道优化

自动注入 metadata.user_id 字段：

{
  "model": "claude-sonnet-4-5",
  "messages": [...],
  "metadata": {
    "user_id": "user_{projectId}_account__session_{sessionId}"
  }
}

Codex 渠道优化

1. 移除动态时间戳：从 instructions 和 messages 中移除时间戳
2. 注入缓存键：添加稳定的 prompt_cache_key

{
  "model": "gpt-4-turbo",
  "instructions": "...",  // 已移除时间戳
  "messages": [...],
  "prompt_cache_key": "user_{projectId}_account__session_{sessionId}"
}

Gemini 渠道优化

移除 system_instruction 和 contents 中的动态时间戳，使缓存前缀保持稳定。

📊 调试

设置环境变量启用详细日志：

OPENCODE_ANTHROPIC_CACHE_DEBUG=1 opencode

日志示例：

[anthropic-cache.fetch] Claude: Injected user_id for cache { user_id: 'user_proj123_account__session_abc' }
[anthropic-cache.cache-handlers] Codex: Removed timestamp from instructions { before: 16124, after: 16055 }
[anthropic-cache.cache-handlers] Codex: Injected prompt_cache_key { key: 'user_proj123_account__session_abc' }
[anthropic-cache.cache-handlers] Gemini: Removed timestamp from system_instruction

🎯 支持的 Provider

插件会根据 provider 名称自动识别类型并应用相应的缓存策略：

| Provider 类型 | 识别关键词 | 缓存策略 | |--------------|-----------|---------| | Claude | claude, anthropic, aws, droid, super, ultra | 注入 metadata.user_id | | Codex | codex, openai-codex | 移除时间戳 + 注入 prompt_cache_key | | Gemini | gemini, google | 移除时间戳 |

📚 API 参考

预置插件导出

// Claude providers
import {
  FoxcodeAwsCache,
  FoxcodeDroidCache,
  FoxcodeSuperCache,
  FoxcodeUltraCache,
  AnthropicCache
} from "foxcode-opencode-cache";

// Codex providers
import {
  FoxcodeCodexCache,
  OpenAICodexCache
} from "foxcode-opencode-cache";

// Gemini providers
import {
  FoxcodeGeminiCache,
  GoogleGeminiCache
} from "foxcode-opencode-cache";

工厂函数

import { createCachePlugin } from "foxcode-opencode-cache";

// 创建自定义 provider 的缓存插件
const MyCustomCache = createCachePlugin("my-custom-provider");
export default MyCustomCache;

💡 最佳实践

1. 统一配置：在 opencode.json 中添加一次插件配置，自动应用到所有 provider
2. 命名规范：provider 名称中包含 claude、codex 或 gemini 关键词，插件会自动识别
3. 调试优先：首次使用时启用调试日志，确认缓存优化正常工作
4. 监控效果：通过 API 响应中的 usage 字段查看缓存命中情况

🤝 贡献

欢迎提交 Issue 和 Pull Request！

📄 许可证

MIT License - 详见 LICENSE 文件

🙏 致谢

• foxcode-cache-proxy - 灵感来源
• OpenCode - 强大的 AI 编程助手平台

📧 联系

• 作者: fiyen
• Email: [email protected]
• GitHub: @fiyen

⭐ 如果这个项目对您有帮助，请给个 Star！