一个Token调3000个接口：Treg“零词汇量路由“背后的最长前缀博弈

一个Token调3000个接口：Treg"零词汇量路由"背后的最长前缀博弈

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

把 OpenAI 的模型网关逻辑搬到一个"工具网关"上会是什么样？treg 给出的答案是：Agent 只拿一个 base URL 加一个 token，就能按需调用 60+ 供应商的 3000+ 真实业务端点——从 SEO 关键词到 TikTok 用户画像，从邮箱富集到广告库检索，全部按调用计费、最低一分钱起。但"一个 URL 通吃三千个接口"这句话背后藏着一个真正的工程难题：当 Agent 在请求里直接写下游供应商的原始 URL 时，网关凭什么知道该把哪一把密钥注入进去？

这就是 treg 所谓的"零词汇量路由"——调用方不需要记住任何 treg 内部的工具命名，不需要tool_name字典，只要把真实的上游 URL 原样扔给网关，路由就发生在 URL 自身。而支撑它的，是一套从主机名筛选、到分段边界前缀匹配、再到 ACL 预过滤和 OAuth 优先级仲裁的多层决策链。这篇文章基于 treg 仓库源码（核心实现在 src/treg/application/call/resolve.py）与 tests/test_passthrough.py 的测试用例，拆解这条决策链的每一环，以及它为了"可审计"付出了什么代价。

从主机名筛选到分段边界的决策链

URL-passthrough 的调用形态在 docs/context/reference/glossary.md 里有精确定义："prefix the real upstream URL with…/call/instead of naming a tool + path"。也就是说，Agent 请求/call/https://api.intercom.io/me，网关要自己把api.intercom.io解析成某个注册工具，再把me这条路径拼到该工具上。

解析的第一步是主机名索引。Tool模型里有一个专门为这个场景建的字段（见 src/treg/models.py）：

host: str = Field(default="", index=True) # netloc of base_url — indexed for URL-passthrough resolution

_resolve_call首先用urlsplit(norm).netloc.lower()取出请求 URL 的主机名，然后做一次按 org 隔离的索引查询：select(Tool).where(Tool.host == host, Tool.org_id == org_id)。这一步同时回答了三个问题：这个主机有没有人注册过？是不是我这个团队注册的？是不是还能被这个调用者使用？两个团队可以各自注册同一个上游主机而互不干扰，这正是多租户隔离在路由层的体现。

主机命中之后，才轮到路径匹配。关键在下面这段（src/treg/application/call/resolve.py）：

def _prefix_match(base: str) -> bool: b = base.rstrip("/") return norm == b or norm.startswith(b + "/")

注意这不是一个朴素的字符串startswith，而是一个分段边界（path-segment boundary）匹配：base_url为.../v2的工具，只匹配请求.../v2/anything或恰好.../v2，但绝不匹配.../v20/...。为什么这么较真？因为如果按裸前缀匹配，/v20/会命中v2工具的凭据绑定——等于把 v2 的密钥悄悄注入到了一个它从未注册过的兄弟路径上，这是凭证错配，不是路由效率问题。仓库在注释里直接点明了这个动机："that would inject v2's credential onto an unregistered sibling path"。

多主机候选都命中后，进入最长前缀决胜：longest = max(len(t.base_url.rstrip("/")) for t in matches)，再取所有长度相等的工具。这里有个容易被忽略的细节：长度比较前先rstrip("/")，目的在注释里写得很清楚——.../v1和.../v1/在语义上是同一个 base，如果有一个工具注册时手滑多写了一个斜杠，它不应该"静默地更长"从而悄悄赢下路由；它应该被视为平局，走平局仲裁逻辑。

最长前缀匹配的边界与冲突场景

平局仲裁是整条决策链里最有意思的一段。当两个工具的主机相同、规范化后 base_url 长度相同，路由就撞上了。仓库给出了两个完全不同性质的冲突场景，处理方式也完全不同。

场景一：手注册工具 vs 注册表自动供给工具。同一个 API 往往先被人手动注册过（treg tool add ...，通常还绑着一个过期的旧密钥），后来用户又通过 OAuth connect 走注册表流程，系统自动供给（auto-provision）了一个新工具。两个都是真实工具，谁的 base_url 都不"更长"。此时如果返回 409，被坑的恰恰是 URL-passthrough 的目标用户——那些从来不输入工具名的 Agent。所以 resolve.py 里有一条优先级规则：优先选择 provider-backed 工具——即绑定里含有带provider标记的 Secret 的那个。判断逻辑是检查工具绑定指向的 Secret 是否org_id匹配且带provider字段，如果恰好只有一个 provider-owned 工具，就直接返回它，把"活着的 OAuth 连接"放在"可能已经过期的旧手注册"前面。

场景二：真正无法消解的歧义。如果两个工具都不是 provider-owned，或者两个都是，就只剩 409 一条路——但这条 409 不是干巴巴的错误，它把所有调用者可用的冲突工具名列出来，并指引调用者改用无歧义的命名形态/call/<name>/<path>。测试 tests/test_passthrough.py 钉死了这个契约：

async def test_ambiguous_host_409(clients: AsyncClient): await _register(clients, "g1", "https://api.same.com") await _register(clients, "g2", "https://api.same.com") # identical base -> tie r = await clients.get("/call/https://api.same.com/echo") assert r.status_code == 409 detail = r.json()["detail"] assert "'g1'" in detail and "'g2'" in detail assert "/call/<name>/<path>" in detail

而"最长前缀赢"的基本盘由 test_longest_prefix_wins 钉死：https://api.g2.com（broad）和https://api.g2.com/v2（narrow）同时注册时，请求/call/https://api.g2.com/v2/echo必须注入 NARROW 密钥，断言auth == "Bearer NARROW"。前缀越具体，密钥越准确——这是整个零词汇量路由的信任基础：调用者写下的路径越深，网关越敢断定它想要的是那个更专门的工具。

ACL预过滤与OAuth优先级如何影响路由

最长前缀匹配本身是纯文本博弈，但 treg 在它前面加了一道"人员博弈"的过滤，而且顺序是刻意设计过的。看 src/treg/application/call/resolve.py 的解析逻辑：候选集在进入_prefix_match之前，先被_tool_usable(caller, t)过滤了一遍。_tool_usable是两道 ACL 的 AND 组合（src/treg/domain/governance/access.py）：

def _tool_usable(caller: Caller, tool: Tool) -> bool: return _tool_allowed(caller, tool.name) and _project_allowed(caller, tool)

即：成员级 per-tool 名单（tool_access，NULL 表示全部）+ 项目级 scope（project_access，NULL 表示整个 org）。owner 永远不受限。为什么过滤必须发生在最长前缀决胜之前？注释给出的理由非常尖锐：一个与调用者同主机、但调用者无权使用的工具，"must not be able to cause a 409——or win the tiebreak——for someone who can't even see it inlist_tools"。换句话说，不可见的工具不能参与可见性博弈——否则一个团队里某成员无权使用的工具会污染路由结果，甚至让一个本来能解析的请求变成 409。ACL 只收窄候选集，从不扩大——不管怎么过滤，最终解析出的工具仍然要再过一遍_require_tool_use权限门，所以这层预过滤不可能成为越权通道。

更精细的是 404 与 403 的区分：_resolve_call保留了未过滤的主机命中集，如果前缀匹配在过滤后一个都不剩、但在未过滤集里存在——说明"工具明明注册了，只是不是你的"——此时返回 403 而不是 404，且错误信息只提调用者输入的主机名，绝不泄露被 ACL 隐藏的工具内部名。注释点破这个取舍："a 404 here would send an admin hunting for a registration that already exists"。

OAuth 优先级则出现在另一个层面。一是上面说的平局仲裁里 provider-backed 工具优先；二是注册表对上游主机的强约束：OAuthProvider.catalog_targets是"可执行的策略"而非目录数据——一个 catalog YAML 里的host只能从这份 HTTPS 精确批准清单里挑一个，profile_for_catalog_host会校验 scheme、netloc、hostname 精确一致，杜绝任何 query/fragment/用户名密码注入（src/treg/oauth_providers.py）。注释直言："a catalog edit cannot redirect an injected team or platform credential to an arbitrary host"。再加上legacy_base_urls：供应商迁移 base_url 后，旧主机上的注册工具仍然有效（tier 1 优先），deny 规则也同时按新旧主机各查一遍——路由优先级与安全策略在主机迁移这件事上达成了同步。

零词汇量调用下可审计性的代价

路由省掉了词汇表，但审计不能省。零词汇量模式的代价，恰恰是"网关替调用者做了太多决定"，因此每一层决定都必须留下可追溯的证据。

先看请求侧。忠实中继（faithful relay）是 src/treg/infra/upstream/relay.py 的承诺：除了五类东西，其他全部原样转发——hop-by-hop 传输头重新推导、x-treg-*控制头与边缘转发头剥离、绑定注入的凭据只覆盖自己的目标位置、共享密钥下的幂等键按 org 重作用域、共享密钥下的 UA 换成 treg 自己的。注意"凭据只覆盖自己的目标位置"：env_injector在注入 query 参数时会把同名的调用者参数替换掉，防止调用者把自己的密钥与网关密钥同时传到上游造成混淆。这个"只动自己那一格"的纪律，就是可审计性的第一层：上游收到的请求，除了凭据位之外，就是调用者发出的请求。

路由层的审计证据集中在三处。第一，解析失败的分类语义：409（真歧义，列出全部冲突工具名）、403（ACL 排除，只提主机）、404（无注册工具）、400（畸形 URL）。第二，调用后的诊断头：X-Treg-Served-By直接告诉你这次到底是谁接的单，X-Treg-Error: 1让调用方区分"treg 没找到工具"和"供应商返回 404"——测试 tests/test_passthrough.py 专门断言了这一点："A caller cannot otherwise tell treg's 404 from the vendor's own 404——both are a status and some JSON"。第三，每次 relay 后_audit记录 attempt，Provider 身份取 catalog provider 或自有工具的上游主机，analytics 里带 outcome/status/timing/cost/call reference，但永远不带 params 和 bodies（docs/context/architecture/proxy-model.md）。

那么代价到底是什么？至少可以数出三笔。第一笔是错误信息的精度：零词汇量路由把"工具名"这个稳定标识藏起来了，所以 404/403/409 的每条错误都得更用力地自解释——403 要解释"不是你的"，409 要列出全部候选并把用户导向命名形态。第二笔是平局仲裁的复杂度：文本上等长的 base_url 并不等于语义上等权，于是引入了 provider-backed 优先、rstrip 规范化、legacy host 兼容这一整套优先级规则——它们都不是路由算法本身，而是为"少一次 409"付出的工程税。第三笔也是最本质的：信任转移。零词汇量模式把"写对工具名"的责任从调用者转嫁给了 URL 自身——调用者写下的 URL 就是全部意图。这意味着 URL 越具体、路径越深，路由越安全；而网关能做的只是把每条路径都变成可审计的记录，把每一次"猜"都变成明文的served_by。

这或许就是"零词汇量路由"最反直觉的地方：它省掉的是调用方的词汇表，不是网关自己的决策表。恰恰因为 Agent 不用学任何工具名，网关才必须在主机、前缀、边界、ACL、OAuth 归属之间做更多、更精细、也更昂贵的博弈——而这一切博弈的每一回合，都被写进了审计日志。一个 Token 调 3000 个接口的浪漫背后，是一张以"宁可 409 也不猜错密钥"为底线的决策网。

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