严格加载配置
config.toml 缺失必填字段一定启动失败。ProxAI 永远不会用隐式默认启动到部分有效的运行时状态。
src/config.rs
Proxy 在缺少 provider、route、protocol 或 timeout 数据时仍启动。
- 配置加载/default 测试
- 启动校验测试
这些是 ProxAI 承诺的行为。破坏其中任何一条都是破坏性变更,需要提升主版本号并附迁移说明(见 C30)。它们比字段名或配置默认值更稳定。
config.toml 缺失必填字段一定启动失败。ProxAI 永远不会用隐式默认启动到部分有效的运行时状态。
src/config.rs
Proxy 在缺少 provider、route、protocol 或 timeout 数据时仍启动。
首次运行一定在 app 目录生成 config.example.toml 作为本地参考。
src/paths.rs 和配置 bootstrap 代码
新用户无法发现本地配置形态。
仓库中被跟踪的 config.example.toml 是权威示例。ProxAI 运行时从不覆盖它。
config.example.toml 和配置 bootstrap 代码
运行时生成逻辑修改了仓库文档事实来源。
[tool_calls].timeout_secs 必须大于 0,否则 ProxAI 启动失败。
src/config.rs
工具调用语义卡顿可能无限挂起。
MCP listener 始终绑定本地地址(默认 127.0.0.1),ProxAI 自身永远不会把它暴露到外网。
Listener setup 和配置默认值
控制面被暴露到本机之外。
MCP 只是控制面。模型请求走 Proxy listener,永远不走 MCP。
HTTP routing/listener setup
模型流量进入控制 endpoint。
只有在没有显式 route 命中时才使用默认 provider。命中的 route 永远优先于默认。
src/routing/
默认 provider 抢走已命中 route 的流量。
未实现的转换对一定显式失败。当 route 命中但协议对不支持时,ProxAI 永远不会静默 fallthrough 到默认 provider。
src/translation/ 和 routing dispatch
不支持的转换静默路由到其他 provider。
Provider protocol 是语义标识。Provider 名字只是用户标签,永远不会改变 wire 行为。
src/config.rs、src/provider/、src/translation/
Provider name 意外改变 serialization 或 response parsing。
如果 route 设置了 request_protocol,并且模型命中但入站协议不同,ProxAI 会返回配置错误,而不是继续路由。
src/routing/
Endpoint-specific routes 静默 fall through。
Provider api_key 一定会发给上游。对 OpenAI provider(openai_responses、openai_chat_completions),以 Authorization: Bearer <key> 发送,并忽略客户端传入的任何 Authorization header。
src/provider/*/transport
客户端凭据泄露到上游,或 provider 凭据未使用。
对 Anthropic Messages provider,key 以 x-api-key 发送。
src/provider/*/transport
Anthropic-compatible 上游拒绝认证或收到错误 header。
响应 Content-Type 由 outbound 协议决定,不透传上游的。
src/http_support/ 和 response translation
客户端收到与入站协议不兼容的上游 content type。
Upstream headers 在转发前会经过过滤。可转发的集合由 ProxAI 显式控制,永远不会原样复制全部上游 headers。
src/http_support/
私有或协议不兼容的上游 headers 泄露给客户端。
对非 2xx 上游响应,ProxAI 在上游确实提供时保留有用的诊断 headers:Retry-After、上游 request id、rate-limit headers。永远不会伪造这些 headers。
src/error/ 和 upstream response handling
客户端丢失可操作 retry/rate-limit 信息,或收到伪造数据。
面向客户端的错误一定在 payload 内包含数字 status 字段。这对 SSE error event 尤其重要,因为流式开始后无法再修改 HTTP status。
src/error/render.rs
SSE error events 丢失 status 上下文。
ProxAI 永远不会原样暴露内部强类型 error taxonomy。面向客户端的 type 取值是固定的稳定枚举,且仅以加法扩展。
src/error/
内部 Rust error 名称变成 public API。
ProxAI 永远不会伪造上游 code 或 param 取值。只有上游确实提供时才保留。
src/error/
客户端基于伪造上游 metadata 做决策。
SSE 流一定被检测 terminal event。只有收到预期 terminal event(response.completed、[DONE] 或 message_stop)才认为流完整。
SSE scanner 和 streaming translation modules
客户端把语义不完整的流当作成功。
卡住的 tool-call argument 流一定在 [tool_calls].timeout_secs 内关闭。ProxAI 永远不会让客户端在工具调用参数开始后无限挂起。
Streaming state machines 和 tool-call timeout handling
客户端在部分工具参数之后永远挂起。
SSE bytes 和 text/event-stream content type 在翻译过程中被保留。
src/http_support/、SSE translation modules
Streaming 客户端收到非 SSE carrier 数据。
read_idle_timeout_secs 是 idle-read 超时,不是整条请求的总时长上限。它只在配置窗口内没有新上游 bytes 到达时触发。
Provider transport/upstream read handling
长但活跃的 stream 被错误截断。
ProxAI 永远不日志请求 body、Authorization header、API key 或私有 prompt。
src/observe/ 和 logging call sites
私有 prompts 或凭据出现在默认日志中。
Capture artifact 仅是 app 目录下的本地文件,永远不会被 ProxAI 自身传输。
src/observe/ capture writers
Capture artifacts 自动离开本机。
Capture 路径固定,不可配置,避免误写到任意位置。
src/observe/ 和 paths code
用户提供路径把私有 captures 写到不安全位置。
转换在 HTTP 载体边界保持纯函数。它接收 protocol 值和 payload/stream carrier,不接收 HTTP Response/Body、路由细节、模型重写细节或 provider 私有结构。
src/translation/
Translation 依赖 HTTP/provider internals,无法按 pair 推理。
ProxAI 永远不在转换 pair 之间原样 round-trip 上游结构。每个方向独立翻译成目标协议的类型。
src/translation/
目标协议收到 provider-private structures。
Provider-local normalization 属于 provider/。通用跨协议 shape 改写属于 translation/。Provider 代码不得隐藏协议到协议的转换。
src/provider/ 和 src/translation/
协议转换逻辑隐藏在 provider-specific adapters 中。
面向客户端的 type 取值仅以加法扩展。已有取值永远不会被重命名或删除,除非主版本号升级。
src/error/render.rs 和 reference docs
既有客户端因错误 type 重命名或删除而破坏。
破坏本页任何契约(C1–C30)都是破坏性变更,需要主版本号升级并附迁移说明。
Release process 和 docs
用户可见破坏行为以 minor/patch 发布。