企业官网建设流程全解析

如何读懂 treg 溢出中继：X-Treg-Served-Via 披露机制完整指南

【免费下载链接】tregOpenRouter for agent tools. Join community here: https://discord.gg/6mQYYfFMAn项目地址: https://gitcode.com/GitHub_Trending/treg/treg

treg 是一个开源的"OpenRouter for agent tools"——用一把统一密钥调用 2000+ 种 API 工具，按次计费。它的**溢出中继（overflow relay）**是一层可靠性兜底：当 treg 自己的平台账户余额耗尽或触发限流时，请求会经由 treg 自有的聚合商账户中继完成同一接口调用，并通过响应头X-Treg-Served-Via向调用方如实披露"这次应答来自溢出中继"。读懂这个机制，你就能准确理解账单里每一笔费用的真实来源。

溢出中继解决什么问题？

平台调用（platform 凭证层）默认走 treg 自己的供应商账户。当这个账户出现以下情况时，调用可能失败：

此时溢出中继"接力"：用 treg 自有的聚合商账户，把完全相同的供应商请求包进聚合商信封发出，再把供应商的原生响应取出来返回给你——同样的请求、同样的响应结构，只是换了付费通道。

X-Treg-Served-Via 如何工作？

披露有三个层次，覆盖 REST 调用、MCP 客户端和价格预估三种场景：

1. 响应头：溢出中继成功时，响应携带X-Treg-Served-Via: overflow:<聚合商名称>，与X-Treg-Cost-Micro（本次实际花费）和X-Treg-Call-Id（调用追踪 ID）一起返回。头部缺省 = 平台账户直接完成，调用方无需猜测。
2. MCP 结果字段：MCPcall结果中该头被转成served_via字段并附带提示文案，方便 Agent 程序化读取。
3. 事前报价：catalog_get在部署支持中继的接口上提前展示overflow_price_usd，让调用方能引用中继价格做成本预估，而不是事后才发现。

注入点分别在 src/treg/application/call/service.py 与 src/treg/mcp.py。

计费规则：聚合商真实价格，0% 加价

• 子调用按聚合商上报的真实价格结算，treg 不加价；
• 每个聚合商有独立每日预算（默认 20 美元，见 src/treg/config.py），超出当日的溢出请求会被跳过；
• 模式三态overflow_mode：
  • off（默认）：从不触发；
  • shadow：静默探测聚合商、记录状态与成本，但调用方仍收到供应商原始错误，不被计费——用于灰度验证；
  • on：返回中继应答并打上X-Treg-Served-Via。

失败边界：一跳到底，绝不换第二家

• 只走一跳：聚合商失败不会接力到第二家，避免级联；
• 聚合商故障会被标记不健康 15 分钟，调用方收到带备选接口列表的类型化 503，且不产生任何费用；
• 永不触发场景：使用团队自有密钥的调用、调用方参数错误导致的 4xx、超时、PUT/PATCH/DELETE 方法；
• 团队可用treg org overflow off整体退出溢出中继，其请求永远不会被转到聚合商。

在控制台中可以像普通调用一样查看溢出子调用的活动记录与费用：

相关代码与文档路径

• 溢出主逻辑（子调用循环、预算预留、结算）：src/treg/application/call/overflow.py
• 聚合商信封适配器（请求包装与应答解析）：src/treg/infra/upstream/aggregators/
• 溢出路由与花费账本的数据迁移：src/treg/alembic/versions/0006_overflow_route.py、src/treg/alembic/versions/0007_overflow_spend.py
• 面向 Agent 的官方说明（含中继披露条款）：src/treg/web/llms.txt
• 回归测试：tests/test_capacity_overflow.py、tests/test_influencersclub_overflow.py

一句话总结

treg 溢出中继让平台账户的"钱荒"不再等于服务中断，而X-Treg-Served-Via让每一次中继都可观测、可计费、可审计——这是 treg 作为开源 API 工具网关在可靠性与透明度之间给出的工程答案。

【免费下载链接】tregOpenRouter for agent tools. Join community here: https://discord.gg/6mQYYfFMAn项目地址: https://gitcode.com/GitHub_Trending/treg/treg