跳转到内容

行为契约

这些是 ProxAI 承诺的行为。破坏其中任何一条都是破坏性变更,需要提升主版本号并附迁移说明(见 C30)。它们比字段名或配置默认值更稳定。

C1

严格加载配置

config.toml 缺失必填字段一定启动失败。ProxAI 永远不会用隐式默认启动到部分有效的运行时状态。

源码归属

src/config.rs

失败模式

Proxy 在缺少 provider、route、protocol 或 timeout 数据时仍启动。

建议测试
  • 配置加载/default 测试
  • 启动校验测试
C2

生成本地示例

首次运行一定在 app 目录生成 config.example.toml 作为本地参考。

源码归属

src/paths.rs 和配置 bootstrap 代码

失败模式

新用户无法发现本地配置形态。

建议测试
  • Generated app-directory defaults 测试
C3

仓库示例是权威示例

仓库中被跟踪的 config.example.toml 是权威示例。ProxAI 运行时从不覆盖它。

源码归属

config.example.toml 和配置 bootstrap 代码

失败模式

运行时生成逻辑修改了仓库文档事实来源。

建议测试
  • 配置示例生成测试
  • Docs config coverage check
C4

工具调用超时必须有效

[tool_calls].timeout_secs 必须大于 0,否则 ProxAI 启动失败。

源码归属

src/config.rs

失败模式

工具调用语义卡顿可能无限挂起。

建议测试
  • 配置校验测试
  • Streaming tool-call timeout 测试
C5

MCP 保持本地监听

MCP listener 始终绑定本地地址(默认 127.0.0.1),ProxAI 自身永远不会把它暴露到外网。

源码归属

Listener setup 和配置默认值

失败模式

控制面被暴露到本机之外。

建议测试
  • Listener default tests
C6

MCP 不是模型请求通道

MCP 只是控制面。模型请求走 Proxy listener,永远不走 MCP。

源码归属

HTTP routing/listener setup

失败模式

模型流量进入控制 endpoint。

建议测试
  • Route/listener separation tests
C7

显式路由优先

只有在没有显式 route 命中时才使用默认 provider。命中的 route 永远优先于默认。

源码归属

src/routing/

失败模式

默认 provider 抢走已命中 route 的流量。

建议测试
  • Route matching tests
  • Proxy e2e route tests
C8

不支持的转换对显式失败

未实现的转换对一定显式失败。当 route 命中但协议对不支持时,ProxAI 永远不会静默 fallthrough 到默认 provider。

源码归属

src/translation/ 和 routing dispatch

失败模式

不支持的转换静默路由到其他 provider。

建议测试
  • 兼容性矩阵覆盖
  • Unsupported pair e2e tests
C9

Provider protocol 是语义标识

Provider protocol 是语义标识。Provider 名字只是用户标签,永远不会改变 wire 行为。

源码归属

src/config.rssrc/provider/src/translation/

失败模式

Provider name 意外改变 serialization 或 response parsing。

建议测试
  • Provider protocol dispatch tests
C10

Request protocol guard 严格生效

如果 route 设置了 request_protocol,并且模型命中但入站协议不同,ProxAI 会返回配置错误,而不是继续路由。

源码归属

src/routing/

失败模式

Endpoint-specific routes 静默 fall through。

建议测试
  • Protocol-aware route matching tests
C11

OpenAI provider 认证由 ProxAI 控制

Provider api_key 一定会发给上游。对 OpenAI provider(openai_responsesopenai_chat_completions),以 Authorization: Bearer <key> 发送,并忽略客户端传入的任何 Authorization header。

源码归属

src/provider/*/transport

失败模式

客户端凭据泄露到上游,或 provider 凭据未使用。

建议测试
  • Provider transport header tests
C12

Anthropic provider 使用 x-api-key

对 Anthropic Messages provider,key 以 x-api-key 发送。

源码归属

src/provider/*/transport

失败模式

Anthropic-compatible 上游拒绝认证或收到错误 header。

建议测试
  • Anthropic transport header tests
C13

Content-Type 由出站协议决定

响应 Content-Type 由 outbound 协议决定,不透传上游的。

源码归属

src/http_support/ 和 response translation

失败模式

客户端收到与入站协议不兼容的上游 content type。

建议测试
  • Response reconstruction tests
C14

Header 会被过滤

Upstream headers 在转发前会经过过滤。可转发的集合由 ProxAI 显式控制,永远不会原样复制全部上游 headers。

源码归属

src/http_support/

失败模式

私有或协议不兼容的上游 headers 泄露给客户端。

建议测试
  • Header filtering tests
C15

保留真实上游诊断 header

对非 2xx 上游响应,ProxAI 在上游确实提供时保留有用的诊断 headers:Retry-After、上游 request id、rate-limit headers。永远不会伪造这些 headers。

源码归属

src/error/ 和 upstream response handling

失败模式

客户端丢失可操作 retry/rate-limit 信息,或收到伪造数据。

建议测试
  • Upstream error projection tests
C16

客户端错误 payload 包含 status

面向客户端的错误一定在 payload 内包含数字 status 字段。这对 SSE error event 尤其重要,因为流式开始后无法再修改 HTTP status。

源码归属

src/error/render.rs

失败模式

SSE error events 丢失 status 上下文。

建议测试
  • HTTP and SSE error rendering tests
C17

内部错误分类不外泄

ProxAI 永远不会原样暴露内部强类型 error taxonomy。面向客户端的 type 取值是固定的稳定枚举,且仅以加法扩展。

源码归属

src/error/

失败模式

内部 Rust error 名称变成 public API。

建议测试
  • Error type projection tests
  • Docs checker error type coverage
C18

不伪造上游 code 和 param

ProxAI 永远不会伪造上游 codeparam 取值。只有上游确实提供时才保留。

源码归属

src/error/

失败模式

客户端基于伪造上游 metadata 做决策。

建议测试
  • Upstream error body shape tests
C19

流必须观测终止事件

SSE 流一定被检测 terminal event。只有收到预期 terminal event(response.completed[DONE]message_stop)才认为流完整。

源码归属

SSE scanner 和 streaming translation modules

失败模式

客户端把语义不完整的流当作成功。

建议测试
  • Terminal event tests
  • Incomplete stream tests
C20

工具调用卡顿可预期关闭

卡住的 tool-call argument 流一定在 [tool_calls].timeout_secs 内关闭。ProxAI 永远不会让客户端在工具调用参数开始后无限挂起。

源码归属

Streaming state machines 和 tool-call timeout handling

失败模式

客户端在部分工具参数之后永远挂起。

建议测试
  • Tool-call stall tests
C21

SSE 载体被保留

SSE bytes 和 text/event-stream content type 在翻译过程中被保留。

源码归属

src/http_support/、SSE translation modules

失败模式

Streaming 客户端收到非 SSE carrier 数据。

建议测试
  • SSE carrier tests
C22

读取超时是 idle-based

read_idle_timeout_secs 是 idle-read 超时,不是整条请求的总时长上限。它只在配置窗口内没有新上游 bytes 到达时触发。

源码归属

Provider transport/upstream read handling

失败模式

长但活跃的 stream 被错误截断。

建议测试
  • Idle timeout tests
C23

不日志私有请求数据

ProxAI 永远不日志请求 body、Authorization header、API key 或私有 prompt。

源码归属

src/observe/ 和 logging call sites

失败模式

私有 prompts 或凭据出现在默认日志中。

建议测试
  • Logging redaction review
  • Request hint tests
C24

Capture 保持本地

Capture artifact 仅是 app 目录下的本地文件,永远不会被 ProxAI 自身传输。

源码归属

src/observe/ capture writers

失败模式

Capture artifacts 自动离开本机。

建议测试
  • Capture writer tests
C25

Capture 路径固定

Capture 路径固定,不可配置,避免误写到任意位置。

源码归属

src/observe/ 和 paths code

失败模式

用户提供路径把私有 captures 写到不安全位置。

建议测试
  • Capture path tests
C26

转换在 carrier 边界保持纯粹

转换在 HTTP 载体边界保持纯函数。它接收 protocol 值和 payload/stream carrier,不接收 HTTP Response/Body、路由细节、模型重写细节或 provider 私有结构。

源码归属

src/translation/

失败模式

Translation 依赖 HTTP/provider internals,无法按 pair 推理。

建议测试
  • Boundary-focused conversion tests
C27

不原样 round-trip 上游结构

ProxAI 永远不在转换 pair 之间原样 round-trip 上游结构。每个方向独立翻译成目标协议的类型。

源码归属

src/translation/

失败模式

目标协议收到 provider-private structures。

建议测试
  • Pair-specific response conversion tests
C28

Provider 怪癖留在 provider 代码

Provider-local normalization 属于 provider/。通用跨协议 shape 改写属于 translation/。Provider 代码不得隐藏协议到协议的转换。

源码归属

src/provider/src/translation/

失败模式

协议转换逻辑隐藏在 provider-specific adapters 中。

建议测试
  • Provider/request and translation boundary review
C29

客户端错误 type 只加法扩展

面向客户端的 type 取值仅以加法扩展。已有取值永远不会被重命名或删除,除非主版本号升级。

源码归属

src/error/render.rs 和 reference docs

失败模式

既有客户端因错误 type 重命名或删除而破坏。

建议测试
  • Error type coverage checker
C30

破坏契约需要主版本升级

破坏本页任何契约(C1–C30)都是破坏性变更,需要主版本号升级并附迁移说明。

源码归属

Release process 和 docs

失败模式

用户可见破坏行为以 minor/patch 发布。

建议测试
  • Release checklist review