用 Anthropic SDK 接入 JBB：Messages、缓存与工具调用边界

CONTRACT

兼容的是 Messages 请求形状，不是 Anthropic 控制面的复制

JBB 接受 Claude Messages 风格的 URL、认证头和 JSON 字段，使 Anthropic SDK 更容易迁移；模型来源、可用分组、价格、缓存计费和具体高级能力仍由 JBB 当前配置与上游共同决定。

ENDPOINT EVIDENCE

路由已确认，模型成功仍需带 Key 实测

2026-07-15 的生产探测与当前源码确认了 Messages 路由、认证头和请求字段；本轮没有使用有效 Key 发起收费模型调用，因此不把 401 写成端到端成功。

证据口径：401 只证明请求到达认证边界。当前公开 /api/pricing 的 Claude 条目仍标记为 OpenAI endpoint；如果目标模型没有 Messages 实测记录，优先使用OpenAI-compatible 路由。协议字段参考 Claude Platform Messages。

SDK SETUP

Base URL 使用站点 origin，不要预先追加 /v1

Anthropic SDK 会自行请求 /v1/messages。把 JBB Key 放在服务端环境变量中，并使用已经确认支持 Messages 的模型 ID。

export JBB_API_KEY="<YOUR_API_KEY>"
export JBB_BASE_URL="https://downstream.jbbtoken.cn"
export JBB_MODEL="<MESSAGES_TESTED_MODEL_ID>"

curl "$JBB_BASE_URL/v1/messages" \
  -H "x-api-key: $JBB_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "content-type: application/json" \
  -d '{
    "model": "'"$JBB_MODEL"'",
    "max_tokens": 256,
    "messages": [{"role": "user", "content": "Reply with OK"}]
  }'

import os
from anthropic import Anthropic

client = Anthropic(
    api_key=os.environ["JBB_API_KEY"],
    base_url=os.getenv(
        "JBB_BASE_URL",
        "https://downstream.jbbtoken.cn",
    ),
)

message = client.messages.create(
    model=os.environ["JBB_MODEL"],
    max_tokens=256,
    messages=[{"role": "user", "content": "Reply with OK"}],
)
print(message.content[0].text)

import Anthropic from "@anthropic-ai/sdk";

const client = new Anthropic({
  apiKey: process.env.JBB_API_KEY,
  baseURL: process.env.JBB_BASE_URL ??
    "https://downstream.jbbtoken.cn",
});

const message = await client.messages.create({
  model: process.env.JBB_MODEL,
  max_tokens: 256,
  messages: [{ role: "user", content: "Reply with OK" }],
});
console.log(message.content[0].text);

PROMPT CACHING

cache_control 可以进入请求，但命中与计费不能预设

服务端 Claude DTO 接受 cache_control。这只证明请求形状可以进入处理链；目标模型是否支持、缓存是否命中、TTL、usage 字段与费用必须以实际响应和当前价格配置为准。

{
  "model": "<MESSAGES_TESTED_MODEL_ID>",
  "max_tokens": 256,
  "system": [{
    "type": "text",
    "text": "<LONG_STABLE_CONTEXT>",
    "cache_control": {"type": "ephemeral"}
  }],
  "messages": [{"role": "user", "content": "Summarize the context"}]
}

• 同一模型、相同前缀连续发送两次，分别保存完整 usage。
• 核对 cache creation / cache read 字段是否真实出现，不只看 HTTP 200。
• 同时核对 JBB 当前 CacheRatio 与 CreateCacheRatio，不要套用官方价格。
• 模型、分组、上下文或路由变化后重新验证缓存命中。

协议参考：Claude Platform Prompt Caching。JBB 的实际缓存与计费结果以站点响应和价格配置为准。

TOOL USE

工具定义可进入请求，工具循环仍由应用负责

当前 Claude DTO 接受 tools 与 tool_choice。模型可能返回 tool_use block；你的服务端需要校验参数、执行工具，再用对应的 tool_result 继续对话。

{
  "model": "<MESSAGES_TESTED_MODEL_ID>",
  "max_tokens": 256,
  "messages": [{"role": "user", "content": "上海现在几点？"}],
  "tools": [{
    "name": "get_time",
    "description": "Return local time for an IANA timezone",
    "input_schema": {
      "type": "object",
      "properties": {"timezone": {"type": "string"}},
      "required": ["timezone"]
    }
  }],
  "tool_choice": {"type": "auto"}
}

• 确认返回内容中确实存在 tool_use，并验证 name 与 input。
• 工具参数视为不可信输入；执行前做 Schema、权限、超时和大小限制。
• 工具调用失败时返回可解释的 tool_result，禁止无限工具循环。
• 并行工具、强制工具、Web Search 与 Beta 工具逐模型单独测试。

协议参考：Claude Platform Tool Use。

DIFFERENCES

请求协议相近，模型、账单与 Beta 能力仍是 JBB 运行时事实

• 凭证

  使用 JBB 生成的 API Key；Anthropic 官方 Key、余额、组织和 Workspace 不会自动带入。

• 模型 ID

  只使用当前 JBB Key 实际可用且已通过 Messages 测试的 ID。公开目录目前不会替你证明 Anthropic endpoint 支持。

• 版本与 Beta

  显式发送 anthropic-version: 2023-06-01；anthropic-beta 虽可转发，但不能据此推断 Beta 功能可用。

• 缓存与计费

  缓存写入、读取、倍率、失败扣费和 usage 以 JBB 当前配置与实际账单为准。

• 工具与内容块

  工具、图片、Thinking、引用和其他内容块可能因上游或转换链不同而变化。

• SDK 版本

  SDK 新增端点不代表 JBB 已同步注册；当前 count_tokens 就是明确的 404 边界。

ERRORS & RETRIES

先判断协议、模型还是上游，再决定是否重试

• 401
  认证失败

  检查 x-api-key、JBB Key 状态、额度和环境变量；401 不代表模型已调用。

• 404
  路径或能力不存在

  确认 SDK Base URL 没有多余 /v1；count_tokens 当前就是 404。

• 400
  请求形状或模型不接受

  检查 max_tokens、Messages 内容块、工具 Schema、缓存字段和模型 ID。

• 429
  额度或频率受限

  核对余额、Key 限额和分组；只对可重试请求采用有上限的指数退避与 jitter。

• 5xx
  运行时或上游失败

  保存请求 ID 和错误正文；设置超时与有限重试，禁止无限轮询模型或账号。

PRODUCTION GATE

上线前完成八项检查

• JBB Key 只存于服务端环境变量或 Secret Manager。
• SDK Base URL 固定为 https://downstream.jbbtoken.cn，不预加 /v1。
• 显式发送 anthropic-version: 2023-06-01。
• 目标模型与分组已经用 POST /v1/messages 做小额度端到端验证。
• Prompt Caching 同时核对 usage、命中、CacheRatio 与 CreateCacheRatio。
• Tool Use 校验工具参数、权限、超时、循环上限与失败路径。
• 429、5xx 与网络超时使用有限重试、指数退避和 jitter。
• 记录请求 ID、HTTP 状态、模型、关键字段与实际计费结果。