后端API网关MCP 服务dsh-plugin【免费下载链接】tregOpenRouter for agent tools. Join community here: https://discord.gg/6mQYYfFMAn项目地址https://gitcode.com/GitHub_Trending/treg/treg点击查看免费下载本指南以 treg 仓库中 docs/PLUGIN-TOOL-JUSTIFICATIONS.md 为骨架结合 src/treg/mcp.py 的实际工具实现与 tests/test_mcp.py 的审核测试逐条拆解 treg 提交给插件目录的五个 MCP 工具catalog_search、catalog_get、call、balance、my_tools所声明的四类标注——Read Only、Open World、Destructive、Idempotent。读完本文你将掌握这些标注的业务语义、它们为何如此填写的设计理由以及如何用仓库源码与测试验证声明与实际行为的一致性。背景插件提交需要一份工具能做什么的诚实声明当 treg 以 ChatGPT 插件或 Codex 插件、Claude connector的形式提交时审核方要求对每个工具填写四类布尔标注只读Read Only、开放世界Open World、破坏性Destructive、幂等Idempotent。模型在调用工具前会查阅这些标注来决定是否向用户确认因此标注必须与真实行为一致——写错了要么模型拒绝执行本可安全执行的操作要么在没有用户确认的情况下执行了有副作用的调用。treg 的这五份声明有一个显著特点它们不是从代码意图推断的而是取自生产环境tools/list实际下发的值文档开篇明确说明。这意味着声明对应的就是服务器真正发送的内容审核者核对的就是线上行为。在 src/treg/mcp.py 中这些标注被集中定义为两组常量并直接挂在 MCP 工具装饰器的annotations参数上# 只读、闭世界、无破坏、幂等 —— 四个纯读工具共用 _READS ToolAnnotations(read_only_hintTrue, destructive_hintFalse, open_world_hintFalse, idempotent_hintTrue) # call 是诚实的例外它中继调用方的任意请求到上游端点 _CALLS ToolAnnotations(read_only_hintFalse, destructive_hintTrue, open_world_hintTrue, idempotent_hintFalse)文件注释对语义定义得很清楚Read-only 意味着不改变任何地方的状态open-world 意味着可以改变公网上可见的状态destructive 意味着存在无法撤销的效果。这正是下文中每个工具逐条声明的判定标准。五个工具四类标注的完整清单文档的核心是一份逐工具、逐字段的声明表以下完整保留原文档的全部内容并补充每个工具的真实实现位置与行为依据。catalog_search只读目录搜索标注声明值文档理由Read OnlyTrue只搜索 treg 自有的 API 端点目录返回名称、描述和价格。不创建、不修改、不消费任何东西运行一百次账户状态也不变。Open WorldFalse只读 treg 内部目录——一个由 treg 策展并随产品发布的固定数据集。不触碰任何第三方 API、不跟随 URL、不接受调用方传入的 host。DestructiveFalse没有任何写入。目录是只读数据工具对其没有写路径无从删除、覆盖或取消。实现上catalog_search(query, limit8)通过_catalog_search_impl直接从内存中的catalog_store.load()读取并排序src/treg/mcp.py、src/treg/mcp.py返回每个端点的endpoint_id、provider、usd_per_call以及是否可免密钥调用no_key_needed。文档所述的目录是固定数据集与源码中从 catalog_store 直接读、不走 API的性能路径约 1ms 内存应答完全吻合且工具本身仍是需要凭据的——传输层会在到达任何工具前拒绝无凭据调用src/treg/mcp.py。catalog_get单端点详情查询标注声明值文档理由Read OnlyTrue返回单条目录条目的完整详情参数、每次调用的精确价格、文档链接、treg 观测到的可靠性。无副作用的查找不动钱。Open WorldFalse读的是与 catalog_search 相同的固定内部目录。调用方传入的是 treg 已发布的 endpoint ID而非 URL无法指向任意主机。DestructiveFalse只读查找无写路径不能删除或修改任何东西。catalog_get(endpoint_id)走的是 HTTP 路由/catalog/endpoints/{id}而非内存存储因为该路由会附带数据库中的观测可靠性与同能力候选src/treg/mcp.py。值得一提的细节它把overflow_price_usd、overflow_price_unit、overflow_via提升到结果里src/treg/mcp.py因为源码记录了一个真实事故——2026-09-08 发现 apollo.people.search 目录标价 free却通过 overflow 中继按每次 $0.002 计费了 8810 次而界面上毫无提示。这正是文档精确价格声明背后要堵住的洞。call诚实标注的危险工具call是五份声明中唯一四类标注全非安全值的工具也是文档提示审核者应重点阅读的部分这些是刻意谨慎的四项。它的理由是treg 代表用户中继到第三方 API但 treg 不对上游 API 的行为建模宁可过度警告也不让客户端以为它承诺了无法承诺的安全。标注声明值文档理由Read OnlyFalse对第三方供应商执行真实 API 调用可能从团队预付余额中扣钱。两件事发生变化上游执行了该端点做的事余额被扣减。两者都不是读。Open WorldTrue这是该工具存在的全部意义可调用约 2600 个目录端点来自众多独立供应商也可调用用户团队自行注册的任意 URL 端点。它能触达的系统集合是开放的不由 treg 限定。DestructiveTruetreg 看不到被调用端点的内部。目录包含在第三方系统上创建、更新、取消、删除的端点treg 中继调用方请求的一切。声称安全就是把猜测当事实因此取谨慎标注让客户端先询问用户。treg 本身从不删除用户数据被标记的风险是上游 API 的。IdempotentFalse重复调用会再次扣费并可能在上游重复副作用。部分目录端点是纯查询但很多不是treg 无法可靠区分因此不声称无法验证的安全。call(endpoint_id, params, method, idempotency_key, ...)的实现src/treg/mcp.py完全印证这些理由它把请求原样组装后经httpx.ASGITransport进程内转发到与 CLI 相同的/call/{rest}路由src/treg/mcp.py由该路由统一执行成员级工具 ACL、拒绝规则、双重每日上限、余额预留与结算——规则只有一份实现因此 MCP 面与 HTTP 面不可能出现一处执行一处不执行的分裂。结果中还会携带cost_usd按X-Treg-Cost-Micro头折算与served_viaoverflow 中继披露让代理能向人类解释扣费。关于幂等的补充call工具实际上支持idempotency_key参数——文档标注 Idempotent 为 False指的是无法对任意上游承诺重复调用的幂等性而idempotency_key只保证同一 key 的未收到应答重试会返回存储的答案且不二次扣费结果带replayed: true重试之外的重复调用仍是新调用src/treg/mcp.py。二者并不矛盾恰恰是不声称无法验证的安全的具体化。balance只读余额查询标注声明值文档理由Read OnlyTrue报告团队预付余额及在途消费。读账本不写任何东西。不能加钱、转账或退款。Open WorldFalse只读 treg 自己的数据库不联系任何第三方系统。DestructiveFalse报告一个数字不改变任何东西此工具到账本没有写路径。balance的实现src/treg/mcp.py先经/auth/me体系解析团队再请求/orgs/{org_id}/balance返回balance_usd、balance_micro、holds_micro。它还需要区分 OAuth 授权归属哪个团队_whose_grant保证多团队身份令牌不会把花费算到错误的团队头上。my_tools团队已注册工具清单标注声明值文档理由Read OnlyTrue列出用户团队已在 treg 注册的 API 工具让模型知道可以调用什么。是目录列表不创建、修改、删除任何东西不泄露凭据——只有名称和 base URL。Open WorldFalse只读 treg 自己的数据库且限定在用户授权时选择的团队范围内。不联系外部系统。DestructiveFalse只读列表无写路径不能注销工具或改动凭据。my_toolssrc/treg/mcp.py请求/tools路由返回的每条记录仅含name、base_url、description三个字段——刻意不返回任何凭据信息与文档不泄露 credential只暴露名称与 base URL的声明一一对应。它与call配合形成闭环call既接受目录端点 ID也接受团队自有工具的tool-name/path形式src/treg/mcp.py且团队自有工具优先于目录匹配、永不计量扣费。源码中的标注契约一组常量一处校验_READS与_CALLS两组标注是共享的catalog_search、catalog_get、resources_list、balance、my_tools都挂_READScall、call_media都挂_CALLS。而从代码结构看团队 MCP 服务器与目录审核版服务器directory_mcp各有自己的标注集目录版将call拆分为catalog_call_read只允许 GET/HEAD/OPTIONS标注为只读开放世界与catalog_call_write允许 POST/PUT/PATCH/DELETE标注为非只读破坏性开放世界两版都不声称幂等src/treg/mcp.py。也就是说对方法分级后读端点可以声明只读写端点保留全部警告——这与文档中treg 无法可靠区分查询与非查询端点的谨慎立场是一脉相承的两种实现策略。审核这一契约的测试位于 tests/test_mcp.pytest_every_tool_declares_what_it_can_do遍历server.list_tools()返回的注解断言五个读工具read_only_hint is True且destructive/open_world均为 False断言call、call_media的read_only_hint is False且destructive/open_world均为 True并单独校验catalog_request在 treg 自身写一行记录但不触达上游、不花钱为非只读、非破坏、闭世界。这个测试把文档中的每一条声明变成了可执行的机器校验——声明不是口头承诺而是会被 CI 持续盯住的真实行为。声明背后的设计原则宁过分谨慎不虚假承诺纵观五份声明可以提炼出三条贯穿始终的原则这也是读者在自己的插件/Agent 工具提交中最值得借鉴的部分只读与开放世界严格区分。凡是只读 treg 内部数据目录、余额、团队工具清单的工具一律标 Read OnlyTrue、Open WorldFalse凡是能触达外部系统的工具一律 Open WorldTrue哪怕它的 HTTP 方法是 GET。不建模即不承诺。call无法看到上游端点内部于是宁可把 Destructive 标 True、Idempotent 标 False让客户端在调用前询问用户。源码注释的原话是声称其它情况就是把猜测呈现为事实。声明与实现用同一组常量绑定。标注不是写在提交表单里的孤立文本而是 src/treg/mcp.py 中与实际工具装饰器绑定的代码并由 tests/test_mcp.py 逐项断言。文档开篇强调取自服务器实际声明的值生产环境的tools/list而非代码意图——这保证审核者核对的与线上运行的完全一致。如果你正在为 ChatGPT / Codex 插件目录编写类似的工具标注treg 这份文档 源码 测试的组合是一个可以直接参考的模板把每个工具的四类标注写成可核对的理由段落把标注常量与工具定义绑定在同一个文件里再用一个测试函数锁定声明即行为的契约。赞分享后端API网关MCP 服务dsh-plugin【免费下载链接】tregOpenRouter for agent tools. Join community here: https://discord.gg/6mQYYfFMAn项目地址https://gitcode.com/GitHub_Trending/treg/treg点击查看免费下载相关推荐如何快速上手uds-c零基础搭建汽车诊断系统的完整指南如何快速上手uds c零基础搭建汽车诊断系统的完整指南 uds c是一款功能强大的汽车诊断系统开发库专为Unified Diagnostics Servic通信嵌入式基于 lark-cli Plugin SDK 编写可运行插件audit-observer 审计插件与 readonly-policy 只读策略插件实战解析基于 lark cli Plugin SDK 编写可运行插件audit observer 审计插件与 readonly policy 只读策略插件实战解析 本CLIAI 技能Paper2GUI 插件审核标准确保插件质量与安全的要求Paper2GUI 插件审核标准确保插件质量与安全的要求 你是否曾遇到过功能残缺的AI工具是否担心下载的插件存在安全隐患本文将详细介绍Paper2GUI插人工智能AI 应用桌面应用创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考