wishforge-ide/docs/reference/provider-proxy.md
eust-w b4ece6057c fix: let the console build, and stop runs that cannot afford the next model request
Building the web image showed that `next build` failed.
- The console imported runtime values from the contracts entry point.
- Turbopack cannot follow the NodeNext `.js` imports inside that entry,
  which also carries zod and every schema into the browser.
- Only `next dev` had ever run before, and the console used to import
  types only.

The fix:
- The executor catalog moves to an entry without imports, exported as
  @wishforge/contracts/providers. The console takes its values from
  there.
- providerBaseUrl moves to its own module.
- A test keeps value imports of the entry point out of the console.

With the console's default budget of 50,000 tokens, every Codex run
stopped after one model request:
- The proxy reserves one token per request byte, and a Codex request is
  already about 50 KB.
- The executor then reported a bare 429 as a provider failure.

The fix:
- A request the remaining budget cannot cover now puts the run into the
  `budget` wait, with what it needs and what remains.
- The console defaults to 300,000 tokens and explains the reservation.

The run page also marked the stage a successful run ended in as not yet
done; it now shows it as complete.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-20 05:20:27 +08:00

52 lines
5.7 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

# 运行级 Codex 模型代理
生产中的执行环境拿到的是代理令牌,而不是租户长期有效的 OpenAI API Key;只有控制面(经 Vault)能解密原始密钥。
- **上游**:代理自己构造上游地址,POST 只能到 `<上游>/responses`,GET 只能到 `<上游>/models`。上游默认是 `https://api.openai.com/v1`,运维可以用 `WF_OPENAI_BASE_URL` 换成 OpenAI 兼容的模型网关(必须支持 Responses 接口)。
- **拒绝**:客户端指定的上游地址、重定向、任意请求头与其他 API 路由一律拒绝。
## 配置
| 变量 | 说明 |
|---|---|
| `WF_PROVIDER_PROXY_PUBLIC_URL` | 代理的公开基址,以 `/provider-proxy/v1` 结尾;生产必须是 HTTPS,开发可以是本机 HTTP |
| `WF_PROVIDER_PROXY_SIGNING_KEY` | 独立的签名密钥,至少 32 字符 |
| `WF_PROVIDER_PROXY_ALLOWED_MODELS` | 运维批准的模型 ID,逗号分隔 |
| `WF_PROVIDER_PROXY_ENABLED=true` | 开发模式下启用代理(生产始终启用) |
| `WF_CODEX_DEFAULT_MODEL` | Agent 配置没有指定模型时使用的默认模型;使用网关时应设为网关提供的模型 |
| `WF_OPENAI_BASE_URL` | 可选,OpenAI 兼容网关的基址(如 `https://ai-gateway.example/v1`),必须是 HTTPS 且不含凭据;只由运维配置,租户无法指定 |
生产中解密原始密钥使用外部 Vault Transit(`VAULT_ADDR`、`VAULT_TOKEN`、`VAULT_TRANSIT_KEY`)。CodeBuddy 与 Claude Code 在生产中保持禁用,直到有同等的代理协议(`providerCatalog` 中的 `proxied`)。
## 令牌与绑定
executor 通过运行上下文得到 `{ apiKey: 代理令牌, baseUrl, expiresAt, metering: 'proxy' }`。代理令牌有独立的 issuer 与 audience,有效期不超过剩余执行预算且不超过一小时,绑定租户、运行、执行代次、租约 token、worker 身份与凭据连接的确切版本。每个请求都重新校验这些绑定;流式响应期间至少每秒复核一次,发现取消、租约过期、代次更替或凭据撤销时中止上游读取。复核有间隔,不是瞬时断网,已经发出的请求在中止后仍可能产生用量。
`/provider-proxy/v1/*` 路由不经过普通的 OIDC 或内部服务鉴权,由代理自己验证令牌。凭据带有 `metering: proxy`,执行器上报的 token 不会再计费一次。
## 请求与预算
- 每个运行同一时间只允许一个上游请求。发出前在租户事务中先记录请求;请求以「运行、代次、租约、连接、幂等键」为键,同一个键换了请求体会被拒绝。只有 `Idempotency-Key` 头算幂等键:Codex 的 `x-client-request-id` 是它的会话 ID,同一会话的每个请求都一样;没有幂等键时用请求体摘要。已完成的有界响应可以重放,不再请求上游。
- 支持自包含的文本、本地 `function`/`custom` 工具以及只包含这两类工具的命名空间;拒绝会话与历史响应引用、存储的提示模板、远程 MCP 与托管工具、后台执行、多模态与文件输入以及未经核实的顶层参数。代理强制 `store: false`、默认服务等级,以及按租户与运行区分的缓存和安全标识。
- 输入预留按序列化后的文本字节加上保守的协议开销估算(一个字节记一个 token),`max_output_tokens` 不超过运行剩余的预留。这是准入估算,不是精确的分词或报价。Codex 一次请求带着指令与工具定义,约 5 万字节并逐轮增长,所以运行预算要留出这部分余量。剩余预算不够下一次请求的预留时,代理拒绝该请求,并让运行进入 `budget` 等待,写明需要与剩余的数量。
- 实际用量只采信上游 JSON 或 Responses SSE 结束事件中的 usage(`input_tokens + output_tokens == total_tokens`),每个请求只记账一次。实际用量超出剩余预算时按实际记录,并停止后续执行。
- SSE 帧跨字节与 CRLF 边界解析、限长并在转发与缓存前脱敏;不转发上游的鉴权与错误头,非成功响应体替换为通用错误,避免回显密钥。限制:请求 2 MiB、单帧 1 MiB、响应 16 MiB、重放缓存 2 MiB、单次上游调用 120 秒。
## 结果未知时
POST 请求超时、流在没有可信用量的情况下结束、或客户端断开时,请求记录变为 `unknown`:保留它的预留额度,运行进入 `ambiguous_execution` 等待,之后的请求(包括新租约下的请求)都不会盲目重发。代理进程本身丢失、请求超过 15 分钟仍处于进行中时,后台维护循环同样把它标记为 `unknown`。
解除方式(需要 owner/admin 在 Web 中操作):
1. `GET /v1/runs/:id/provider-requests` 查看该运行的模型请求及状态。
2. `POST /v1/runs/:id/provider-requests/reconcile`,body `{"requestId": "...", "usageTokens": 1234}`:按服务商后台查到的实际用量结算;不知道实际用量时省略 `usageTokens`,按该请求的预留额度结算。
3. 结算后运行可以继续,模型请求恢复可用。
请求记录中不保存原始提示词与原始凭据;重放数据属于租户的模型输出,受平台的保留策略约束。
参考:[Responses create](https://developers.openai.com/api/reference/resources/responses/methods/create)、[streaming Responses](https://developers.openai.com/api/docs/guides/streaming-responses)。
## 测试
`tests/provider-proxy.test.ts` 使用注入的本地假上游,覆盖 audience 隔离、租户/租约/代次/连接绑定、SSE 分块、密钥脱敏、一次性计量、路由/工具/模型拒绝、取消、凭据轮换、预算准入、结果未知与人工对账。`WF_CODEX_SDK_INTEGRATION=1 npx vitest run tests/integration/codex-sdk.test.ts` 让固定版本的 Codex SDK/CLI 经真实代理访问本地假上游,不会调用真实模型。