caveman-setup

用途

caveman-setup 是一套用于把代码仓库接入 Caveman 网关的操作规程。Caveman 被描述为一个保持字节不变的 LLM 代理：在记录模式下，它只度量应用发送了什么、成本是多少，除此之外不做任何改变。该技能的目标是最小化、可验证的集成，而非重构。

使用方式

触发本技能时会提供四个值：

GATEWAY —— 网关基础 URL（例如 https://gateway.caveman.so 或 http://127.0.0.1:8787）
CAVE_API_KEY —— 网关鉴权密钥（仅放在环境变量，绝不提交、绝不完整打印）
PROVIDER_KEYS —— stored（供应商密钥加密存储在 Caveman Cloud）或 byok（应用每次请求自带密钥）
DASHBOARD —— 仪表盘基础 URL（例如 https://app.caveman.so）

若任一值缺失就停止并索取，不猜测 URL 也不自行生成密钥。

集成步骤：

定位所有活跃 LLM 调用点：阅读依赖文件并检索源码中的 LLM 客户端（openai、@anthropic-ai/sdk、anthropic、ai + @ai-sdk/、langchain、litellm、google-genai / @google/genai、crewai、pydantic_ai、openai-agents / agents），以及直连 api.openai.com、api.anthropic.com、generativelanguage.googleapis.com 的原生 HTTP，和已有的 base-URL 环境变量（OPENAI_BASE_URL、OPENAI_API_BASE、ANTHROPIC_BASE_URL、GEMINI_BASE_URL、GOOGLE_GEMINI_BASE_URL）。逐一列出文件与行号后再做修改。若找不到调用点，则停止并报告“nothing to wire”。
选择应用 slug：格式为 GATEWAY/w/<app>，小写 [a-z0-9] 开头，后续 [a-z0-9._-]，最长 64 字符。该应用的全部开销归入该 slug。
接线每个调用点：把 base URL 指向网关的 /w/<app>，加上鉴权头。网关鉴权使用 x-cave-api-key: CAVE_API_KEY（在头不方便处也可用 Authorization: Bearer CAVE_API_KEY）。若 PROVIDER_KEYS 为 byok，还需发送 x-cave-upstream-key: <应用已有的供应商密钥>。文档给出各框架的具体写法：
- OpenAI SDK（TS）使用 baseURL ${process.env.CAVE_GATEWAY_URL}/w/<app>/openai/v1，apiKey 在 byok 下不变、stored 下用 CAVE_API_KEY，defaultHeaders 含 x-cave-api-key（byok 另加 x-cave-upstream-key）。
- OpenAI SDK（Python）同形：base_url=f"{gw}/w/<app>/openai/v1"，default_headers={...}。
- Anthropic SDK（TS/Python）：SDK 自身追加 /v1/messages，base_url 为 ${gw}/w/<app>，两种模式下都必需 x-cave-api-key 头（该 SDK 的 key 参数走 x-api-key，不是网关鉴权头）。
- Vercel AI SDK：createOpenAICompatible({ baseURL: ${gw}/w/<app>/openai/v1, headers: { "x-cave-api-key": ... } })；Anthropic 模型经由 createAnthropic。
- LangChain / LangGraph：ChatOpenAI(base_url=f"{gw}/w/<app>/openai/v1", default_headers={...})；ChatAnthropic(base_url=f"{gw}/w/<app>", default_headers={...})。
- 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 协议），加上相应请求头。
环境文件新增：CAVE_GATEWAY_URL=<GATEWAY>、CAVE_API_KEY=<CAVE_API_KEY>，代码中引用而非写字面量。CAVE_API_KEY 放入仓库已有 env 文件；若该文件未加入 .gitignore，则添加并说明。
用一个真实请求验证：用最便宜的路径或 curl 发送一次最小请求（max_tokens ≤ 32），OpenAI 协议与 Anthropic 协议各有示例命令。成功 = HTTP 200 且带 usage 块；其他情况对应失败模板。这是一次真实计费的供应商请求。
报告：按固定格式说明接线了多少调用点与文件、应用 slug、验证结果（HTTP 200、模型、输入/输出 token 数、一次真实请求）、模式为 record（仅计量、未启用优化、经验证的节省为 $0）。

限制与约束

仅限记录模式：不启用任何优化，不声称任何节省；除非显式打开优化器并通过其评测门，否则经验证的节省为 $0。
密钥只放环境变量，绝不硬编码到源码。
只报告实际观察到的内容：最终报告须给出真实验证响应的 HTTP 状态与用量数字，绝不假设成功。
供应商密钥与本技能无关：stored 模式下不可见；byok 模式下应用已有供应商密钥保持原位。
直连 API 的具体框架（google-genai、crewai、pydantic-ai、openai-agents）需查阅对应集成文档。
未提供关于收费、价格、性能效果的信息。

技能介绍

用途

使用方式

限制与约束