[opencode 请求流程分析] OpenCode 请求流程与请求 Header 分析(2026-08-10)

[github-actions]

本次变更提示

近 20 条同步提交(stats 回退、config 字段容错、UI 修复、i18n 等)与请求流程/Header 无直接关联。

---

1. 请求流程(时序)

sequenceDiagram
    participant S as Session/Prompt
    participant C as LLMClient (client.ts)
    participant P as Protocol (anthropic-messages 等)
    participant T as HttpTransport (transport/http.ts)
    participant A as Auth (auth.ts)
    participant E as RequestExecutor (executor.ts)
    participant LLM as LLM Provider

    S->>C: stream(request) / generate(request)
    C->>C: resolveRequestOptions() 合并 defaults
    C->>C: applyCachePolicy()
    C->>P: route.body.from(request) 构造 body
    P-->>C: validated body
    C->>T: route.prepareTransport(body, request)
    T->>T: jsonRequestParts() 渲染 URL & headers
    T->>A: Auth.toEffect()(authInput) 注入凭据
    A-->>T: headers (含鉴权 header)
    T-->>C: HttpPrepared { request, framing }
    C->>E: RequestExecutor.execute(httpRequest)
    E->>LLM: POST /endpoint
    LLM-->>E: SSE/HTTP stream
    E->>E: retryStatusFailures() 最多重试 2 次
    E-->>S: Stream<LLMEvent>

Loading

分步说明

步骤	关键环节	文件 & 符号
1	调用入口	route/client.ts → LLMClient.stream() / generate()
2	Options 合并	client.ts → resolveRequestOptions()
3	缓存策略	src/cache-policy.ts → applyCachePolicy()
4	Body 构造	protocols/*/ → protocol.body.from()
5	Body 验证	client.ts:compile() → Schema.decodeUnknownEffect
6	HTTP 准备	transport/http.ts → jsonRequestParts()
7	Auth 注入	route/auth.ts → Auth.toEffect()
8	传输发送	route/executor.ts → RequestExecutor.execute()
9	错误重试	executor.ts → retryStatusFailures() (429/503/504/529, 最多 2 次)
10	流解析	client.ts → route.streamPrepared() → Protocol 状态机

---

2. 请求 Header 明细

content-type: application/json 由 protocols/shared.ts:322 的 jsonPost() 对所有 provider 统一设置。

Anthropic (protocols/anthropic-messages.ts)

Header	取值来源	说明
content-type	shared.ts:322	application/json
x-api-key	providers/anthropic.ts:14–19	API Key(apiKey 选项或 ANTHROPIC_API_KEY 环境变量)
anthropic-version	protocols/anthropic-messages.ts:852	固定 2023-06-01
anthropic-beta	opencode/provider.ts:174–177	interleaved-thinking-2025-05-14,fine-grained-tool-streaming-2025-05-14

OpenAI (protocols/openai-chat.ts / openai-responses.ts)

Header	取值来源	说明
content-type	shared.ts:322	application/json
Authorization	providers/openai.ts → AuthOptions.bearer()	Bearer <OPENAI_API_KEY>

Amazon Bedrock (protocols/bedrock-converse.ts)

Header	取值来源	说明
content-type	bedrock-auth.ts:37	签名前显式设置
Authorization	protocols/utils/bedrock-auth.ts → AwsV4Signer	AWS SigV4 签名串
x-amz-date	AwsV4Signer 自动生成	请求时间戳
x-amz-security-token	AwsV4Signer(含 sessionToken 时)	STS 临时 session token
(Bearer 模式) Authorization	providers/amazon-bedrock.ts:39	Bearer <apiKey>(配置了 apiKey 时)

Google Gemini (protocols/gemini.ts)

Header	取值来源	说明
content-type	shared.ts:322	application/json
x-goog-api-key	providers/google.ts:14–19	API Key(GOOGLE_GENERATIVE_AI_API_KEY)

Azure OpenAI (providers/azure.ts)

Header	取值来源	说明
content-type	shared.ts:322	application/json
api-key	providers/azure.ts:61–66	Azure API Key(AZURE_OPENAI_API_KEY); 移除了 Authorization
(query) api-version	providers/azure.ts:75–79	API 版本查询参数

GitHub Copilot (providers/github-copilot.ts)

Header	取值来源	说明
content-type	shared.ts:322	application/json
Authorization	providers/github-copilot.ts:44–48	Bearer <copilot-oauth-token>

OpenRouter / OpenAI-Compatible

Header	取值来源	说明
content-type	shared.ts:322	application/json
Authorization	providers/openrouter.ts:85 / openai-compatible.ts:26	Bearer <API_KEY>(OPENROUTER_API_KEY)
HTTP-Referer	opencode/provider.ts:458,470,479,490,601	`(opencode.ai/redacted)
X-Title	opencode/provider.ts:459,471,492,603	opencode
X-Source	opencode/provider.ts:472	opencode(llmgateway)
X-BILLING-INVOKE-ORIGIN	opencode/provider.ts:483	OpenCode(nvidia)

Google Vertex AI

Header	取值来源	说明
Authorization	opencode/provider.ts:538–541	Bearer (gcloud_access_token)(ADC 动态获取)

GitLab AI Gateway

Header	取值来源	说明
User-Agent	opencode/provider.ts:621	opencode/(ver) gitlab-ai-provider/(ver) ((os))
anthropic-beta	opencode/provider.ts:622	context-1m-2025-08-07
PRIVATE-TOKEN / Authorization	opencode/provider.ts:669	API key 用 PRIVATE-TOKEN,OAuth token 用 Bearer

---

3. 鉴权机制

Provider	鉴权方式	关键代码位置
Anthropic	API Key → x-api-key	providers/anthropic.ts:9–19
OpenAI	API Key → Authorization: Bearer	route/auth-options.ts:43–52
Bedrock (SigV4)	AWS 凭据 → SigV4 签名	protocols/utils/bedrock-auth.ts → AwsV4Signer
Bedrock (Bearer)	API Key → Authorization: Bearer	providers/amazon-bedrock.ts:39
Google Gemini	API Key → x-goog-api-key	providers/google.ts:14–19
Azure OpenAI	API Key → api-key	providers/azure.ts:61–66
GitHub Copilot	OAuth token → Authorization: Bearer	providers/github-copilot.ts:44–48
OpenRouter	API Key → Authorization: Bearer	providers/openrouter.ts:85
Google Vertex	ADC access token → Authorization: Bearer	opencode/provider.ts:532–541
GitLab	OAuth(Bearer) 或 PAT(PRIVATE-TOKEN)	opencode/provider.ts:669

凭据解析优先级(以 Anthropic 为例):

1. 显式 auth: Auth 对象
2. 显式 apiKey
3. 环境变量(如 ANTHROPIC_API_KEY)
4. 缺失 → MissingCredentialError → LLMError(AuthenticationReason)

---

4. 关键代码位置索引

文件	说明
packages/llm/src/route/client.ts	核心编排:compile(), resolveRequestOptions()
packages/llm/src/route/auth.ts	鉴权抽象:Auth, bearer(), header(), custom()
packages/llm/src/route/auth-options.ts	AuthOptions.bearer() 封装
packages/llm/src/route/transport/http.ts	jsonRequestParts(), httpJson()
packages/llm/src/route/executor.ts	HTTP 执行与重试
packages/llm/src/protocols/anthropic-messages.ts:852	anthropic-version: 2023-06-01
packages/llm/src/protocols/openai-chat.ts:497–503	OpenAI Chat route
packages/llm/src/protocols/bedrock-converse.ts:658–672	Bedrock Converse route
packages/llm/src/protocols/utils/bedrock-auth.ts	AWS SigV4 实现
packages/llm/src/protocols/gemini.ts:500–509	Gemini route
packages/llm/src/protocols/shared.ts:314–323	jsonPost() 统一设置 content-type
packages/llm/src/providers/anthropic.ts	Anthropic facade
packages/llm/src/providers/azure.ts	Azure facade,api-key header
packages/llm/src/providers/openrouter.ts	OpenRouter facade
packages/opencode/src/provider/provider.ts	opencode 层 headers/fetch 定制(beta flags, Referer, User-Agent, GoogleAuth)

Generated by Daily Upstream Sync + Request-Flow Analysis · 93 AIC · ⌖ 7 AIC · ⊞ 5.9K · ◷