JuliusBrussee/caveman-setup

您正在将此仓库连接到 Caveman 网关。Caveman 是一个保持字节不变的 LLM 代理：在记录模式下，它仅测量您应用发送的内容及其成本，不更改任何其他内容。您的工作是进行最小化、可验证的集成，而非重构。

发送此提示的上下文提供了四个值。请按如下方式引用它们：

• GATEWAY — 网关基础 URL（例如 https://gateway.caveman.so 或 http://127.0.0.1:8787）
• CAVE_API_KEY — 网关认证密钥（与任何 API 密钥一样对待：仅作为环境变量，绝不提交或完整打印）
• PROVIDER_KEYS — stored（提供者密钥以加密形式存储在 Caveman Cloud 中）或 byok（此应用在每次请求中自行发送提供者密钥）
• DASHBOARD — 仪表盘基础 URL（例如 https://app.caveman.so）

如果缺少任何值，请停止并要求提供。不要猜测 URL 或生成密钥。

规则（不可协商）

1. 连贯集成。 通过现有配置和负责的接缝连接每个活跃的 LLM 调用点。仅修改需要正确性所涉及的层。不要进行附带的重构或格式化清理；仅在需要明确所有权或降低生命周期成本时添加抽象。
2. 秘密仅存于环境变量。 CAVE_API_KEY 将放入仓库已有的环境文件（如 .env、.env.local 等）。如果该文件未被 gitignore，则将其添加到 .gitignore 并说明。绝不在源代码中硬编码密钥。
3. 仅报告您观察到的内容。 最终报告必须陈述来自真实验证响应的 HTTP 状态和用量数字，绝不假设成功。如果验证失败，则报告匹配的失败模板。
4. 仅记录模式。 您仅在添加测量。您不会启用任何优化，也不声称任何节省——在经过明确启用并通过评估门控的优化器之前，验证节省为 $0。
5. 提供者密钥与您无关。 在 PROVIDER_KEYS: stored 模式下，您绝不会看到提供者密钥。在 byok 模式下，应用现有的提供者密钥保持在其原有的位置。

步骤 1 — 查找每个活跃的 LLM 调用点

读取依赖文件（package.json、requirements.txt、pyproject.toml、go.mod、lockfiles）并搜索源代码中的 LLM 客户端：

• SDK 导入：openai、@anthropic-ai/sdk、anthropic、ai + @ai-sdk/*（Vercel）、langchain*、litellm、google-genai / @google/genai、crewai、pydantic_ai、openai-agents / agents
• 对 api.openai.com、api.anthropic.com、generativelanguage.googleapis.com 的原始 HTTP 请求
• 现有的基础 URL 环境变量：OPENAI_BASE_URL、OPENAI_API_BASE、ANTHROPIC_BASE_URL、GEMINI_BASE_URL、GOOGLE_GEMINI_BASE_URL

在修改任何内容之前，列出您找到的内容（每个调用点的文件:行数）。如果未找到任何 LLM 调用点，请停止并报告本文档末尾的“无需连接”模板——不要自行创建集成。

步骤 2 — 选择应用标识

一个标识用于在网关路径中命名此应用：GATEWAY/w/<app>。根据包/模块名称派生（例如 support-bot、acme-api）。语法：首字符为小写 [a-z0-9]，后续字符为 [a-z0-9._-]，最长 64 个字符。此整个应用的支出将按该标识在仪表盘上分组。

步骤 3 — 连接每个调用点

模式始终相同：将基础 URL 替换为网关地址，加上 /w/<app>，并添加一个认证头。 网关认证头为 x-cave-api-key: CAVE_API_KEY（在头不方便的位置，Authorization: Bearer CAVE_API_KEY 同样有效）。在 PROVIDER_KEYS: byok 模式下，还需发送 x-cave-upstream-key: <应用已使用的提供者密钥>。

有两个事实确保此次连接的安全性（两者均由网关强制实施，并非主观期望）：网关会从头构建上游认证头，因此客户端的 Authorization/x-api-key 值绝不会转发给提供者；在 stored 模式下，上游认证来自服务器端的加密连接。因此，在 stored 模式下，如果某个 SDK 强制要求提供 api-key 参数，则将其设置为 Cave 密钥——它仅用于认证网关，不会继续传递。

精确形式（根据每个调用点选择匹配的项——以下是产品已发布的配方，而非建议）：

OpenAI SDK (TS) — Chat Completions 和 Responses 均通过以下方式路由：

const client = new OpenAI({
  baseURL: `${process.env.CAVE_GATEWAY_URL}/w/<app>/openai/v1`,
  apiKey: process.env.OPENAI_API_KEY,           // byok: 保持不变 · stored: 使用 CAVE_API_KEY
  defaultHeaders: {
    "x-cave-api-key": process.env.CAVE_API_KEY!,
    // 仅 byok:
    "x-cave-upstream-key": process.env.OPENAI_API_KEY!,
  },
});

OpenAI SDK (Python) — 相同形式：base_url=f"{gw}/w/<app>/openai/v1"，default_headers={"x-cave-api-key": ..., "x-cave-upstream-key": ...}。

Anthropic SDK (TS/Python) — SDK 会自动追加 /v1/messages。此处的 x-cave-api-key 头在两种模式下都是必需的（该 SDK 自身的密钥参数通过 x-api-key 传递，并非网关认证头）：

client = anthropic.Anthropic(
    base_url=f"{os.environ['CAVE_GATEWAY_URL']}/w/<app>",
    api_key=os.environ["ANTHROPIC_API_KEY"],      # byok: 保持不变 · stored: 使用 CAVE_API_KEY
    default_headers={
        "x-cave-api-key": os.environ["CAVE_API_KEY"],
        # 仅 byok:
        "x-cave-upstream-key": os.environ["ANTHROPIC_API_KEY"],
    },
)

Vercel AI SDK — createOpenAICompatible({ baseURL: ${gw}/w//openai/v1, headers: { "x-cave-api-key": ... } })；Anthropic 模型通过 createAnthropic({ baseURL: ${gw}/w//v1, headers: { ... } })。

LangChain / LangGraph — ChatOpenAI(base_url=f"{gw}/w/<app>/openai/v1", default_headers={...})；ChatAnthropic(base_url=f"{gw}/w/<app>", default_headers={...})。LangGraph 会继承您传递的模型。

LiteLLM — 每次调用使用 api_base=f"{gw}/w/<app>/openai/v1" + extra_headers={...}，或在 LiteLLM 代理的 config.yaml 中全局设置。

原始 HTTP / 其他 — 替换主机，保留提供者的本地路径：GATEWAY/w/<app>/v1/chat/completions（OpenAI 协议）或 GATEWAY/w/<app>/v1/messages（Anthropic 协议），并添加相应的头。

具体来说，对于标识 support-bot 和托管网关，OpenAI SDK 的基础 URL 为 https://gateway.caveman.so/w/support-bot/openai/v1。在 stored 模式下，完全删除所有 x-cave-upstream-key 行——该行仅用于 byok 模式。

对于未列出的框架（google-genai、crewai、pydantic-ai、openai-agents），请获取此技能来源相同域名下的 <docs origin>/docs/integrations/ 对应页面，并按说明操作。

在仓库的环境文件中添加（代码中引用该变量——不要使用字面量）：

CAVE_GATEWAY_URL=<GATEWAY>
CAVE_API_KEY=<CAVE_API_KEY>

步骤 4 — 通过一次真实请求验证

用户粘贴此设置提示以授权执行以下操作：一次小型验证请求。立即发送——不要暂停请求许可。因为您的犹豫而导致集成未经验证，比发送一次小型请求更糟糕；自主完成验证和报告正是本技能的核心目的。

通过您刚刚建立的连接发送一次最小请求——如果仓库有针对性的脚本，则使用其最便宜的路径；否则使用 curl，路径与您刚刚连接的协议相匹配，使用仓库自己的模型并设置一个小上限（max_tokens ≤ 32）：

# OpenAI 协议连接：
curl -sS "$CAVE_GATEWAY_URL/w/<app>/v1/chat/completions" \
  -H "x-cave-api-key: $CAVE_API_KEY" \
  -H "content-type: application/json" \
  -d '{"model":"<仓库已使用的模型>","max_tokens":16,"messages":[{"role":"user","content":"ping"}]}'

# Anthropic 协议连接：
curl -sS "$CAVE_GATEWAY_URL/w/<app>/v1/messages" \
  -H "x-cave-api-key: $CAVE_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "content-type: application/json" \
  -d '{"model":"<仓库已使用的模型>","max_tokens":16,"messages":[{"role":"user","content":"ping"}]}'

（byok 模式：添加 -H "x-cave-upstream-key: $PROVIDER_KEY"。）这是一次真实、需付费的提供者请求——这正是关键：真实的流量，真实的测量。

读取响应。成功 = HTTP 200 并包含 usage 块。其他情况 = 下方对应的失败模板。

步骤 5 — 报告

最终以完全相同的格式结束，根据您实际执行和观察到的内容填写：

## Caveman 已在此仓库中激活

已连接：<n> 个调用点，分布在 <n> 个文件中
  - <文件> — <一行说明更改了什么>
应用标识：<app> — 此应用的支出将按此标识分组
已验证：HTTP 200 · 模型 <model> · <in> 输入 / <out> 输出 token（一次真实请求）
模式：记录——仅测量。未更改任何模型可见的字节，未启用任何优化。
验证节省为 $0，直到您开启优化器并通过评估门控。这种诚实正是产品的价值所在。

查看支出：<DASHBOARD>/traces — 您的请求位于顶部行，价格来自公开目录。
<DASHBOARD>/getting-started 将变为“已收到首个请求”。

希望按工作流（如 support-reply 与 nightly-digest）而非仅按应用拆分支出？请说“发现工作流”——我将获取 <docs origin>/docs/discover-workflows.md 并按每个调用点所执行的任务进行标记。

失败模板（逐字使用并填写，切勿软化）

• 无需连接：“我在此仓库中未找到任何 LLM 调用点（已搜索 SDK、原始提供者 HTTP、基础 URL 环境变量）。如果此仓库运行的是编码代理而非提供 LLM 代码，请改用 caveman wrap <agent>——请参阅 /getting-started。”
• 网关不可达：“验证请求无法到达 GATEWAY（<错误>）。连接已就位但未经验证——在网关可达之前，不会测量任何内容。请检查 URL 和网络，然后重新运行上述验证 curl。”
• 401 cave_invalid_api_key：“网关拒绝了 CAVE_API_KEY。请在 /getting-started 生成新密钥并更新环境文件；连接本身无需更改。”
• 404 cave_route_not_found：“网关未匹配到任何路由——通常是 /w/ 标识格式错误（首字符小写 [a-z0-9]，后续字符 [a-z0-9._-]，最长 64 个字符）或路径与 SDK 协议不匹配。请修复 URL 后重新验证。”
• 提供者错误（通过网关返回 4xx/5xx）：报告状态和响应正文原文；网关可达且认证通过，上游调用失败——通常是应用内的提供者密钥或模型名称问题。

切勿将以上任何情况报告为成功。未经验证的集成应以“未经验证”状态报告。