后端API网关MCP 服务dsh-plugin【免费下载链接】tregOpenRouter for agent tools. Join community here: https://discord.gg/6mQYYfFMAn项目地址https://gitcode.com/GitHub_Trending/treg/treg点击查看免费下载本篇指南面向「想把 treg 集成进自己产品」的开发者你作为 treg 的客户为你的用户提供约 2,600 个外部 API 工具SEO、SERP、外链、社媒、企业数据、广告、爬虫等由 treg 持有并注入上游厂商凭据你按自己的客户用量向其收费。读完本文你将掌握 treg 的三种集成形态HTTP / MCP / CLI、每次调用的客户归属X-Treg-Meta标签、按标签设置的预算上限、基于账本ledger的开票数据源以及上线前必须落实的幂等、余额监控与错误转发策略。在动手写任何管道代码之前请先完整读完计费一节——计费模型决定管道怎么搭先写管道再改计费等于重写。treg 是什么一条 URL、一枚令牌、约 2,600 个端点从集成视角看treg 的核心事实只有三个一个 base URL 一个 token即可触达约2,600 个外部 API 端点分布在约40 家提供商外加你们团队自行注册的工具覆盖 SEO、SERP、backlinks、social、enrichment、ads、scraping 等品类凭据由 treg 服务端持有并注入你的调用方构造请求treg 注入厂商凭据后代为发出真实的上游请求把厂商的原始响应原样返回给你计量与零加价跑在 treg 自有 key 上的调用按次从预付余额中计量扣费0% 加价原文档原话为 0% markup。本文档讨论的场景是你的产品是 treg 的客户你的用户是你的客户——你向 treg 付费再向你的用户收费。配套的调用与计费契约定义可继续阅读 接口文档 与 CLI 文档也可以直接参考 llms.txt 中面向 Agent 的机器可读摘要。1. 选择集成方式HTTP / MCP / CLI三条门路同一个 token同一套行为。按你现有代码的落点选择方式适用场景形态HTTPPOST {BASE}/call/endpoint-id你的后端本来就在发 HTTP 请求——产品的默认选择你构造请求treg 注入凭据并转发MCP{BASE}/mcp/你的 Agent 运行时讲 MCP想白拿工具发现能力catalog_search→catalog_get→callCLItreg脚本、CI、开发机——通常不做产品集成同一 API 的薄客户端从源码看HTTP 路由/call/{rest:path}同时接受GET/POST/PUT/PATCH/DELETE/HEAD/OPTIONS六种方法见 routers/call.py所以 catalog 端点既可用curl --get发查询型 GET也可按端点契约发任意方法另有/catalog/call/{rest:path}这一条受开关控制的同构入口routers/call.py走完全相同的策略、计费、审计与转发路径。1.1 HTTP产品集成首选一个真实调用长这样scrapecreators.x.v1-facebook-group是 catalog 中的一个端点 idcurl --get {BASE}/call/scrapecreators.x.v1-facebook-group \ --data-urlencode urlhttps://www.facebook.com/groups/366190054572553/about \ -H X-Treg-Token: $TREG_TOKEN \ -H X-Treg-Meta: customercust_8123先查目录再调端点查目录无需鉴权GET {BASE}/catalog/search?qfacebookgroup # 有什么以及每个端点多少钱 GET {BASE}/catalog/endpoints/id # 参数、方法、示例每次调用必须关注两个响应头X-Treg-Cost-Micro—— 本次调用的实际成本整数微美元1e-6 USD。只在计量的调用上出现缺失说明该调用跑在团队自有 key 上、未被计费。X-Treg-Call-Id—— 本次调用的稳定 id。务必在你的侧保存它。它是你日后把 treg 记录与自己记录关联的 join key并且可通过GET {BASE}/calls/id解析到单次调用详情。在源码中它同时被写进 ledger 的call_id列并回填到审计行见 models.py、routers/call.py这正是它「两边可对上账」的机制基础。这两个头都不存在于厂商返回的 body 中——body 是 treg 原样转发的包括厂商自己的错误。因此上游厂商返回的 4xx/5xx 不计费。当你带着预算转售时还有一个请求头很关键X-Treg-Route-Max-Cost: usd—— 单次调用的硬性费用上限。若预扣reserve会超过该值treg 返回402error: route_max_cost带max_cost_micro与estimated_cost_micro且分文不扣。直连调用默认没有上限只有这个头能封顶reserve.py 实现了该拒绝在 catalog 路由类端点上该上限的默认值为 $1.00见 route.py 与 catalog.py。关于 catalog 的~$/call定价语义这是默认页大小下的估算值。per_result定价且unit: row时价格随你的limit缩放unit: target/domain/keyword时按请求命名的对象数量缩放一个 target 就是一个单位。X-Treg-Cost-Micro才是结算后的唯一事实来源。1.2 MCPAgent 运行时免发现把客户端指向{BASE}/mcp/携带Authorization: Bearer token。可用的工具为catalog_search、catalog_get、call、balance、my_tools其中call的返回结果携带cost_usd。对应的实现位于 mcp.pycatalog_search(query, limit8)L609负责按「想做的事」而不是厂商名找端点catalog_get(endpoint_id)L855返回参数、价格与实测可靠性并按之排序call(endpoint_id, params)L932完成实际调用并把X-Treg-Cost-Micro换算成cost_usd带回mcp.py。推荐的 Agent 工作流是catalog_search描述需求→catalog_get看参数与价→call执行与 MCP 面板在 界面文档 中的说明一致。1.3 Auth 与那个陷阱token 分两种区别足以浪费你一个下午Org 级treg org agent-new name—— 属于某一个团队可作裸 bearer 使用。产品集成用它。身份级treg login—— 属于某个自然人该人可能在多个团队。较新版本把它钉在当前活跃团队上、同样可以裸用旧的或未钉住的版本会回答400 choose an org (send X-Treg-Org)。若遇到该错误要么发送X-Treg-Org: slug要么改铸一个 org 级 token。2. 给每次调用打上客户标签——这是整个计费模型从你的后端在每次调用上发送X-Treg-Meta最多 5 个keyvalue对X-Treg-Meta: customercust_8123, workspacews_9, featurelead-enrichment值约束只能包含字母、数字与. _ - :≤128 字符且不能长得像邮箱——这些值会成为追加式账本append-only ledger中的存储键所以 treg 拒绝任何无法安全存放的东西。畸形标签包会在转发前直接返回422因此不计费。源码层面对这套约束的实现非常严格见 intake.py头总长上限512 字节_META_MAX_HEADERL32超限即422 metadata_invalidkey 为 1-32 个字符的[a-z0-9_]L95值经由 budgets.py 的_validate_tag_pair校验key 重复同样 422最多5 个 key_META_MAX_KEYS 5budgets.py默认主维度是customerDEFAULT_PRIMARY_DIMbudgets.py即预算与报告的默认分组键设计原则是拒绝而非修复REFUSES rather than repairs被静默丢弃或截断的标签意味着用量悄悄溜出你的账单被截断的 id 还可能把两个用户合并成一行——所以超长值是 422绝不是[:128]。2.1 在代码里设标签永远别放在 prompt 里不要把标签暴露成让 LLM 填写的参数。模型在长链路中总会在某处漏掉它而一个无法对账的数字比没有数字更糟。你的后端本来就知道某个请求属于哪个用户、本来就在同一处设置Authorization——就在那个调用点设置标签// 你的产品与 treg 通信的“唯一入口” async function tregCall(path: string, ctx: { customerId: string; workspaceId?: string }) { const tags [customer${ctx.customerId}]; if (ctx.workspaceId) tags.push(workspace${ctx.workspaceId}); const r await fetch(${TREG_BASE}/call/${path}, { headers: { X-Treg-Token: process.env.TREG_TOKEN!, X-Treg-Meta: tags.join(, ), }, }); // 以 treg 返回的 id 为键把成本记到 YOUR 客户的账上 await db.usage.insert({ customerId: ctx.customerId, tregCallId: r.headers.get(X-Treg-Call-Id), costMicro: Number(r.headers.get(X-Treg-Cost-Micro) ?? 0), }); return r; }让所有 treg 调用都走这样一个函数。如果两个调用点对「该打给谁」有分歧迟早有一天它们会分歧。这正对应源码里CallMeta的设计动机——Built ONCE per request and read by everyone……A second parse site would be a second chance to disagree about who paysintake.py标签解析在每个请求中只发生一次幂等作用域、预算、账本与审计行全部复用同一份解析结果。3. 限制单个客户的消费接口PUT {BASE}/orgs/org_id/budgets/dim/value需要 admin token。# 给一个客户封顶 $5/天 curl -X PUT {BASE}/orgs/1/budgets/customer/cust_8123 \ -H X-Treg-Token: $TREG_TOKEN -H content-type: application/json \ -d {daily_cap_micro: 5000000} # 给“没有单独覆盖值的每个客户”一个默认值省略 value curl -X PUT {BASE}/orgs/1/budgets/customer ... -d {daily_cap_micro: 1000000} # 拉黑某人他的各上限在封禁后依然存活 curl -X PUT {BASE}/orgs/1/budgets/customer/cust_8123 ... -d {status:blocked}要点不设就是无限。直到你设置之前一切不受限。给某个 key 设置第一个上限时也同时声明了该维度dimension——最多3 个因为每个维度都要在每次调用上被检查。上限会叠加一个同时携带workspace与customer的调用两道上限同时生效拒绝响应会指名是哪个维度被触发。除daily_cap_micro与status: blocked外维度还支持按天调用次数上限calls_per_day实现于 reserve.py触发时返回429 tag_call_cap_reached以及月消费上限monthly_cap_micro——日、月两个消费累计值在花费 pass 中逐一检查reserve.py。从实现上看每次调用有两道预算检查闸口见 reserve.py预检pre-flightpassadd_micro is None检查blocked状态与每日调用次数calls_per_day。它跑在幂等重放之前因此被拉黑的用户既拿不到锁、也不会被分发到拉黑之前缓存的答案花费spendpass带add_micro需要费用估算因此跑在_platform_reserve内部检查daily_cap_micro日上限与monthly_cap_micro月上限两个累计值。多个维度按声明顺序检查先触发的先拒绝——这让预算叠加时的结果具有确定性。另外注意维度默认值由一次索引查询同时取回自身覆盖值或维度默认值reserve.py给默认值机制加上了不增加调用路径成本的设计。3.1 你的用户可能会看到的拒绝这些响应不携带任何关于你 treg 账户的信息——没有余额、没有充值链接——因此可以安全地透传给用户403 {error:tag_blocked,dim:customer,val:cust_8123,message:…} 429 {error:tag_spend_cap_reached,dim:customer,val:cust_8123, spent_micro:5000000,cap_micro:5000000,period:day,message:…}源码证实了它们的分工reserve.py 在status blocked时抛tag_blocked403reserve.py 在spent add_micro cap时抛tag_spend_cap_reached429并带上spent_micro、cap_micro、periodday 或 month按次上限触发时是429 tag_call_cap_reachedreserve.py。代码注释还特意说明这类拒绝故意不采用org 级 402/429 的错误形状因为那个形状携带团队余额与充值链接而 tag 级响应是「你要渲染给自己终端用户的那一个」reserve.py。绝不盲目转发 treg 错误体给你的终端用户。团队级的402 insufficient_balance、429 platform_daily_cap_reached包含你的余额与充值 URL必须由你自己处理。源码中insufficient_balance的消息还会按是否开启自动充值给出不同的指引reserve.py。按客户设的上限是建议性的不是精确闸门。它基于聚合值检查因此并发调用可能以「每个在途请求约一个调用的估算值」的幅度超限reserve.py 的注释把话说得很明白per-tag 总量是对行的聚合N 个并发调用各自读到合规数字、合起来却可能超限之所以可接受是因为硬闸门在它后面——团队余额与平台日上限。你的预付余额才是硬上限。不要把这种上限当作精确 cap 卖给用户。4. 给你的客户开发票接口GET {BASE}/orgs/org_id/usage/by-tag?keycustomerdays30响应{key:customer,days:30, rows:[{value:cust_8123,charged_micro:41234,charged_usd:0.041234,calls:22}], attributed_micro:41234, unattributed_micro:1880, total_micro:43114}三条铁律也是源码实现直白写出的设计意图钱从账本ledger来不从调用日志来。审计行audit rows是 fire-and-forget 的负载高时会被丢弃——这恰恰是成长型产品产生的流量形态。任何你要用来开票的数字都必须出自这里。GET /calls只用于调试永不用于发票。实现见 orgs.py 的注释MONEY COMES FROM THE LEDGER, never fromCallRecord……an invoice built on them would under-bill silently and unrecoverably调用次数才从审计表来那里丢一行只是计数略低。attributed unattributed total对每个 key 都成立。若不等先停下排查不要直接发出发票。路由实现显式返回了unattributed_micro而不是悄悄丢弃它orgs.py——开票方对自己账本对账时必须能看到无法归属给任何人的花费否则两套账本会在无人察觉的情况下开始不一致。days参数被钳制在 1–365orgs.py。unattributed_micro是你无法归属的开销——那些没有携带该 key 值的调用。把它对到零剩下任何数都意味着有一个调用点忘了打标签。一次调用被全额计入它的每一个标签按customer分组与按workspace分组各自都能独立对到同一总额。永远不要将两个分组相加。这从计数的实现也可见一斑calls计数来自 ledger 的 tag 行而不是CallRecord——因为CallRecord只保存主维度若在那里计数每个非主 key 的报告都会是 0而金额列却是对的一份自相矛盾的报告比承认自身粒度的报告更糟orgs.py。CLI 侧也有对应的treg org usage by-tag命令cli.py。5. 隔离当标签不够用时标签是你的后端断言的标签——当只有你自己的预算与报告在触碰它时这没问题。但如果一枚凭据要跑在你自己客户的机器上就改铸一枚钉到该客户身上的 tokentreg org agent-new cust-8123-bot --pin customercust_8123这枚 token只能为cust_8123计费试图给别的客户命名会得到403源码中为metadata_pin_mismatchintake.pya token handed to one customers machine must not be able to bill another customer. Naming a different value for a pinned dimension is a 403 rather than a silent override——集成方排查问题时要能看见这种分歧而不是一个月后在一堆错归属的发票里才发现。口诀标签用于计数token 用于控制。让所有人都先走标签再为少数真正需要隔离的人升级成钉 token。--pin参数可重复指定--pin dimvalue见 cli.py未携带X-Treg-Meta的钉 token 调用会自动归属到它的 pinintake.py所以「发一枚作用域 token 出去、完全不用碰 header」也是合法用法。6. 上线前的检查清单一个函数包裹所有 treg 调用并从请求上下文设置X-Treg-Meta。X-Treg-Call-Id已存入你的 usage 行。你的发票数据来自usage/by-tag并断言attributed unattributed total。unattributed_micro为零——或者你确切知道是哪个调用点没打标签。团队级402/429错误体由你自己处理绝不转发给用户。自动充值已开启或你在监控GET /orgs/id/balance——余额归零会让所有调用失败。重试携带Idempotency-Key重放会返回已存答案且分文不扣。如何分辨错误到底是谁的厂商自己的错误会原样转发给你所以一个4xx/5xx可能是厂商的、不是 treg 的。treg 只在自己的拒绝上打X-Treg-Error: 1头——按这个头分支不要按状态码分支该标记由 bootstrap_handlers.py 统一加盖CLI 也用它区分treg 拒绝了调用与厂商应答了、treg 原样转发两种情形见 cli.py。失败到底计不计费上游调用失败不计费per_call定价的端点若 4xx 是你自己的错误输入造成的则会计费但由凭据或配额问题导致的 4xx从不计费。6.1 幂等重试的正确姿势源码级清单最后一项值得展开。幂等的实现位于 idempotency.py头名Idempotency-KeyL26窗口24 小时IDEMPOTENCY_WINDOW_S 24 * 3600L25存储键按主标签分区_scoped_idempotency_keyL43-L68你作为转售方会让所有用户共用一个 token两个用户都可能用retry-1这个 key——若不分区第二个用户会拿到第一个用户的缓存响应体这正是「跨租户泄漏」的隐患同一 key 用于不同请求会得到422 idempotency_mismatch——指纹包含 method、路径、query string与 body 的 SHA-256L76-L96因为大部分 catalog 调用是 GET、参数全在 query 里当初漏掉 query 会让整个检查几乎失效重放时不会再次触达上游L99-L106merely skipping the second CHARGE would still make the second upstream call, which means still paying the provider and simply absorbing the double cost ourselves——这正是幂等的全部意义并返回X-Treg-Idempotent-Replay: true、X-Treg-Cost-Micro重放实际扣费额与X-Treg-Call-Id首次调用的 id见 service.py。6.2 余额与自动充值余额是硬上限。若不希望余额归零导致全站调用失败二选一开启自动充值treg topup --auto on --threshold 5 --amount 20阈值 $5、每次充 $20上限与冷却期在 application/billing.py 的autotopup_prefs中体现为threshold_micro、amount_micro、monthly_cap_micro冷却间隔由平台设置控制或监控GET /orgs/id/balance在低于阈值时人工/程序化充值。团队级402 insufficient_balance的响应体里也会按是否开启自动充值给出差异化提示reserve.py已开启时它会提示是冷却/月上限在拦截、而不是缺卡未开启时给出treg topup --auto on的直接建议。结语计费模型决定管道把本文的三条主线串起来X-Treg-Meta打标签决定谁买单→PUT /orgs/id/budgets/...设上限决定每人花多少软上限、可叠加、拒绝可安全透传→GET /orgs/id/usage/by-tag出账只信 ledger不信 call log逐 key 对平attributed unattributed total。三者共用同一个「每次请求解析一次」的标签包加上幂等键的标签分区构成一个可对账、可隔离、可重试的转售管道。先把这个模型装进脑子再写那一个包裹全部调用的函数——管道就能一次搭对。赞分享后端API网关MCP 服务dsh-plugin【免费下载链接】tregOpenRouter for agent tools. Join community here: https://discord.gg/6mQYYfFMAn项目地址https://gitcode.com/GitHub_Trending/treg/treg点击查看免费下载相关推荐mistral.rs HTTP 服务器 MCP 客户端集成实战通过 OpenAI API 自动调用外部工具mistral.rs HTTP 服务器 MCP 客户端集成实战通过 OpenAI API 自动调用外部工具 导读 本文基于 mistral.rs 官方示例完推理引擎模型推理服务AI Agent多模态WeKnora MCP 集成全指南作为 MCP 客户端接入外部工具与作为 MCP Server 对外提供 31 个工具WeKnora MCP 集成全指南作为 MCP 客户端接入外部工具与作为 MCP Server 对外提供 31 个工具 MCPModel Context P人工智能大模型RAGAI Agent后端前端MCP 服务知识库dsh-plugin工具调用将 MCP 客户端接入 OpenMedstdio 与 Streamable HTTP 的完整实战指南将 MCP 客户端接入 OpenMedstdio 与 Streamable HTTP 的完整实战指南 OpenMed 通过 Model Context Pro人工智能NLP医疗健康数据脱敏本地部署大模型AI 应用MCP 服务联邦学习上一篇GitHub汉化插件终极上手10分钟告别全英文界面效率立翻倍下一篇Blender 3MF插件从踩坑到顺手一位打印爱好者的格式迁移实录创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
