Anthropic Provider¶

修正说明(2026-04-10):本文档已移除虚构内容(不存在的 beta header,文件路径). 定价数据来自 core/docs/capabilities-baseline.json.

1. 定位¶

Anthropic 是 Flyto 的首选商业模型 Provider,提供 Claude 系列模型.优势在于: - 业界领先的推理能力(Claude Opus 4.6) - 完整的 Extended Thinking 支持 - Prompt Caching 降低上下文成本 - 严格的工具调用结构化输出

2. 支持的模型¶

模型	Context Window	Max Output	Input $/1M	Output $/1M	备注
claude-opus-4-6	200K	32K	$5	$25	最强智能
claude-sonnet-4-6	200K	64K	$3	$15	性价比首选
claude-haiku-4-5	200K	8K	$0.8	$4	快速任务

数据来源:core/docs/capabilities-baseline.json(probed 2026-04-10)

3. 配置示例¶

import "git.flytoex.net/yuanwei/git.flytoex.net/yuanwei/flyto-agent/pkg/providers/anthropic"

p := anthropic.New(anthropic.Config{
    APIKey:    os.Getenv("ANTHROPIC_API_KEY"),
    BaseURL:   "https://api.anthropic.com",  // 可覆盖
    ThinkingBudget: 16000,                    // Extended thinking token 上限
    EnableCaching: true,                      // 启用 Prompt Caching
    BearerAuth: false,                        // 默认 x-api-key，可选 Bearer
    Timeout:   60 * time.Second,              // 可选,ResponseHeaderTimeout (见 §3.1)
})

3.1 Timeout (P1 契约加固, 2026-04-13)¶

问题: Go 标准库 http.Client{} 的零值 Timeout=0 意思是无限等待.消费者忘了注入带 timeout 的 HTTPClient,生产环境下服务端不响应会导致调用方死等.

解法: Config.Timeout 字段,通过 http.Transport.ResponseHeaderTimeout 实现,只约束"从请求发出到收到响应首字节"的时间,不影响 SSE 流式响应的后续 body 读取.LLM 流式回复 2-5 分钟照常工作.

陷阱警告: 不要误用 http.Client.Timeout -- 那是"整个请求总时长"包括流式 body 读取,设 60s 会直接砍死长流式调用.这是 Go 标准库最常被误用的 API 之一.

行为:

场景	Config 字段	行为
默认 (都不设)	`HTTPClient=nil, Timeout=0`	使用 `defaultTimeout=60s` 作为 ResponseHeaderTimeout
显式 Timeout	`HTTPClient=nil, Timeout=Xs`	使用 `Xs` 作为 ResponseHeaderTimeout
自定义 client	`HTTPClient=&http.Client{...}`	完全交给消费者,`Timeout` 字段被忽略 (silent)

默认值依据: 60s 对 Anthropic 云端合理 -- 正常情况下模型在 < 10s 开始响应,60s 为网络抖动 / 排队 / 服务降级提供缓冲.消费者可通过 Timeout 字段针对业务场景调整 (比如生产 SLA 严格场景设 30s).

与 flyto.Request.Capabilities 的关系: 无关.Timeout 是 HTTP 层超时,Capabilities 是模型能力.两者独立配置.

ThinkingBudget 建议¶

任务类型	建议值
简单问答	0(关闭)
代码生成	8000
复杂分析	16000
超长推理	32000(仅 Opus)

4. 认证方式¶

默认: x-api-key: <API_KEY> Header

可选 Bearer: Authorization: Bearer <API_KEY>

anthropic.New(anthropic.Config{
    APIKey:     "sk-ant-...",
    BearerAuth: false,  // true = 用 Bearer 格式
})

API Key 获取: Anthropic Console

5. 能力矩阵(实测)¶

能力	支持	备注
Streaming	✓	text_delta 增量推送
Tool Use	✓	128 tools max
Extended Thinking	✓	ThinkingBudget=0 关闭
Prompt Caching	✓	cache_control 自动标记
Vision	✓	图片输入
PDF	✓	文档输入
Batch API	✓	批处理模式
Parallel Tool Calls	✓	自动并发
Structured Output	✓	json_object 模式
strict_json	✗	不支持

Cache 定价(来自 capabilities-baseline.json probe): - Claude Sonnet 4.6: in=9 cr=3603 rd=3603(~3600 token cache hit) - Claude Haiku 4.5: in=9 cr=0 rd=7202(无 cache,R/U 比例 ~800x)

6. 已知 quirks¶

Schema 约束裁剪¶

实现位置:core/internal/wire/schema.go 中的 AdaptSchema(schema, "anthropic").

Anthropic 不支持部分 JSON Schema 约束关键字,引擎自动递归裁剪并将约束信息写入 description, 保证模型仍能"读懂"约束.被裁剪的关键字:minimum / maximum / exclusiveMinimum / exclusiveMaximum / multipleOf / minLength / maxLength / pattern.

Tool 数量上限检查¶

CheckToolCount 在发送前验证工具数量.实现位置:core/internal/wire/tools.go.

Haiku JSON 输出 fence strip¶

Haiku 的 json_object 模式会在响应外包裹 markdown fence.Anthropic provider 通过 wrapFenceStrip goroutine 自动去除 ```json ``` 包装. 实现位置:core/pkg/providers/anthropic/provider.go.

无 /models 端点¶

Anthropic 没有公开的模型列表 API.provider 使用静态模型表 + Config.ModelOverrides 扩展.

Beta Headers¶

实际发送的 beta header 由 core/internal/transport/client.go 根据 api.BetaFeatures 字段动态组装(例如 prompt-caching 在 EnableCaching: true 时启用).不要引用固定的 beta header 列表--具体内容随 request 配置变化,且 Anthropic 的 beta 命名随版本升级.

7. 错误处理¶

状态码	含义	处理建议
401	API Key 无效或过期	检查 Key
429	请求频率超限	等待后重试,使用 `/compact` 减少 token
400 `invalid_request`	请求格式错误	检查 thinking_budget 是否过大
400 `model_not_found`	模型不可用	换用默认模型
529	服务过载	等待后重试

8. 成本估算示例¶

一次典型代码审查会话(约 2000 input tokens,500 output tokens):

Input:  2000 tokens × $3/1M     = $0.006
Output:  500 tokens × $15/1M    = $0.0075
Total:                           ≈ $0.0135

启用 Caching（80% cache hit）:
Input:  400 tokens × $3/1M      = $0.0012
Cache: 1600 tokens × $3*0.1/1M = $0.0005  (cache 价格为 10%)
Output:  500 tokens × $15/1M    = $0.0075
Total:                           ≈ $0.0092

节省约 32%.

9. 数据驱动能力(Capabilities)¶

参见 docs/architecture/data-driven-capabilities-rfc.md 了解整体机制.PR1/PR2(2026-04)起全部 7 个 provider 都按此模式工作.

本 provider 的能力决策来自 req.Capabilities(由 engine 从 ModelRegistry 注入,registry 数据由 capability-probe 实测填充).包内静态表/const 降级为兜底安全值--registry 有数据时优先使用,没有时走包内兜底.

本 provider 的决策路径:

路径	helper	兜底策略
`MaxTools` + `MaxToolsExhaustive`	`buildRequest` 内联 registry-first	`modelMaxTools(model)` 查静态表(当前 anthropic 模型均为 0 = 无硬上限)
`SupportsThinking`	`resolveThinkingSupport`	`modelSupportsThinking(model)` 查静态表
`SupportsCaching`	`resolveCachingSupport`	兜底 true(静态表所有模型均支持)
`CachingMinTokens`	`resolveCachingMinTokens`	`cachingMinTokens(model)` 查静态表;`int + 0 哨兵` 语义(trip-wire 注释标记)

双开关协议(want × can):用户 want 某能力(如 Config.EnableCaching=true / Config.ThinkingBudget>0 / req.NeedsThinking=true / SystemBlocks[].CacheScope != "")但模型 can=false(registry 显式声明不支持)时,能力不启用,provider 在流开头 emit WarningEvent{Code:"feature_unsupported"},让消费者(engine / observer / TUI)看到 silent disable.

anthropic 特殊 caching 细节:系统提示 token 长度 ≥ 阈值触发的自动 caching 不发 warning(那是引擎自动优化,非用户显式期望);只有 Config.EnableCaching=true 或 SystemBlocks.CacheScope != "" 才是用户 want 信号.