treg 工具解析机制全解析URL 主机匹配 最长前缀如何决定 API 路由【免费下载链接】tregOpenRouter for agent tools. Join community here: https://discord.gg/6mQYYfFMAn项目地址: https://gitcode.com/GitHub_Trending/treg/treg如果你正在使用 treg 这个AI Agent 的工具网关一定好奇当你只输入一个 API 地址treg 是怎么知道该用哪个团队的凭据、该转发到哪个上游服务的答案就在它的目标解析机制里——先按 URL 主机host圈定候选工具再用最长 base_url 前缀longest prefix从中选出唯一赢家。这套机制藏在 resolve.py 中是 treg 被称为agent 工具的 OpenRouter的核心原因。为什么需要工具解析treg 的定位是让 AI Agent 不持有任何厂商密钥就能安全调用各家 APIAgent 只管发出请求treg 在转发途中注入凭据、审计、计费。关键问题在于Agent 只会说我要访问https://api.stripe.com/v1/charges它不知道 treg 内部的工具名。于是 treg 需要一种零词汇量的解析方式——你写的就是原生 API 地址路由由地址本身决定。两种请求形态URL 透传 vs 命名调用进入/call/的请求路由定义见 call.py共有两种形态形态长什么样解析方式URL 透传Agent 原生/call/https://api.intercom.io/me主机 最长前缀匹配命名CLI/遗留/call/my-tool/path直接按工具名精确查找本文的主角是第一种。它的完整流水线只有一句话解析 → 授权 → 扣费 → 忠实转发其中解析阶段就产出了ResolvedTarget(工具, 上游URL)这个结果。三步解析主机圈定 → 前缀筛选 → 最长者胜以下逻辑对应 resolve.py 中的_resolve_call函数第一步提取主机并命中索引把透传 URL 解析出 netloc主机名统一转小写然后按带索引的Tool.host字段查询——这是 models.py 中专门设计的一列注释写着netloc of base_url — indexed for URL-passthrough resolution。所有查询都限定在调用者自己的 org内两个团队即使注册了相同主机也不会互相干扰。第二步路径分段边界上的前缀匹配每个候选工具都有自己的base_url。匹配规则不是朴素的字符串前缀而是要求落在路径分段边界上✅.../v2匹配.../v2本身或.../v2/...❌.../v2绝不匹配.../v20/...这一条看似苛刻的规则防止了一个真实事故把 v2 的凭据错误注入到未注册的兄弟路径/v20上。第三步最长前缀胜出多个工具可能同时命中同一主机比如团队同时连接了同一供应商的多个 API 子域。此时比较去掉尾部斜杠后的base_url长度最长者获胜base_url https://api.example.com/v1 13 字符路径 ← 胜出 base_url https://api.example.com 更短 请求 https://api.example.com/v1/users比较前会先做rstrip(/)归一化所以.../v1和.../v1/算等长——这不是悄悄分出胜负而是会被如实判定为一次真正的冲突409。平局怎么破409 错误与注册表优先当最长前缀出现平局treg 的处理非常克制resolve.py注册表连接优先如果平局中只有一个工具绑定的是注册表 OAuth 凭据provider-backed直接选它。因为这种连接往往是用户刚刚授权、正在使用的活连接而手动注册的旧工具很可能拿着过期密钥——对永远不打工具名的 Agent 调用方来说409 是纯粹的打断。仍是平局 → 409返回target_ambiguous错误信息列出所有冲突的工具名并明确指示改用无歧义的/call/name/path形式。对应的行为测试见 test_passthrough.pytest_longest_prefix_wins验证最长前缀胜出test_ambiguous_host_409验证真正的平局返回 409。权限过滤先用 ACL 缩小候选集再比长短一个容易被忽略的顺序细节权限过滤发生在最长前缀比较之前proxy-model.md 中的 ACL-filtered candidates 一节。同主机所有工具 → 用 ACL项目范围 工具白名单过滤 → 剩下的人里才比前缀为什么顺序重要一个你根本看不见的同主机工具不应当让你收到 409——它不配参与你视野内的竞争。同时这个过滤只缩小候选集永远不放大任何解析结果之后仍会经过完整的访问策略闸门。由此还能区分两种失败403主机上有匹配工具但全被 ACL 过滤掉了 → 你有工具但没权限找管理员开404这个主机压根没有注册工具 → no registered tool for upstream ...403 的措辞只点出你输入的主机名绝不泄露被隐藏的工具内部名字。小结一张图看懂路由决策/call/https://api.x.com/v1/users │ ├─ 1. host api.x.com ──命中索引── 本 org 内同主机工具 │ ├─ 2. ACL 过滤看不见的不许参赛 │ ├─ 3. 路径分段边界前缀匹配 │ 无匹配 → 403被 ACL 挡/ 404不存在 │ ├─ 4. 最长 base_url 者胜去尾斜杠后比长度 │ 平局 → 注册表连接优先否则 409 │ └─ 5. 产出 ResolvedTarget → 授权 → 计费 → 忠实转发这套主机 最长前缀的设计本质是把 DNS 的最长标签匹配思想搬到了凭据路由上既让 Agent 零学习成本地直接喊出原生 API 地址又保证每一次注入都有唯一、可解释、可审计的依据。延伸阅读完整的代理与转发契约见 proxy-model.md凭据注入与忠实转发的规则也写在其中。【免费下载链接】tregOpenRouter for agent tools. Join community here: https://discord.gg/6mQYYfFMAn项目地址: https://gitcode.com/GitHub_Trending/treg/treg创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考