企业官网建设流程全解析

• 后端
• API网关
• MCP 服务
• dsh-plugin

本指南以 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_hint=True, destructive_hint=False, open_world_hint=False, idempotent_hint=True) # call 是诚实的例外：它中继调用方的任意请求到上游端点 _CALLS = ToolAnnotations(read_only_hint=False, destructive_hint=True, open_world_hint=True, idempotent_hint=False)

文件注释对语义定义得很清楚："Read-only 意味着不改变任何地方的状态；open-world 意味着可以改变公网上可见的状态；destructive 意味着存在无法撤销的效果。"这正是下文中每个工具逐条声明的判定标准。

五个工具，四类标注的完整清单

文档的核心是一份逐工具、逐字段的声明表，以下完整保留原文档的全部内容，并补充每个工具的真实实现位置与行为依据。

catalog_search：只读目录搜索

实现上，catalog_search(query, limit=8)通过_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：单端点详情查询

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 的行为建模，宁可过度警告，也不让客户端以为它承诺了无法承诺的安全。

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_via（overflow 中继披露），让代理能向人类解释扣费。

关于幂等的补充：call工具实际上支持idempotency_key参数——文档标注 Idempotent 为 False，指的是无法对任意上游承诺重复调用的幂等性；而idempotency_key只保证"同一 key 的未收到应答重试"会返回存储的答案且不二次扣费（结果带replayed: true），重试之外的重复调用仍是新调用（src/treg/mcp.py）。二者并不矛盾，恰恰是"不声称无法验证的安全"的具体化。

balance：只读余额查询

balance的实现（src/treg/mcp.py）先经/auth/me体系解析团队，再请求/orgs/{org_id}/balance，返回balance_usd、balance_micro、holds_micro。它还需要区分 OAuth 授权归属哪个团队（_whose_grant），保证多团队身份令牌不会把花费算到错误的团队头上。

my_tools：团队已注册工具清单

my_tools（src/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都挂_READS，call、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.py：test_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 工具提交中最值得借鉴的部分：

1. 只读与开放世界严格区分。凡是只读 treg 内部数据（目录、余额、团队工具清单）的工具，一律标 Read Only=True、Open World=False；凡是能触达外部系统的工具，一律 Open World=True，哪怕它的 HTTP 方法是 GET。
2. 不建模即不承诺。call无法看到上游端点内部，于是宁可把 Destructive 标 True、Idempotent 标 False，让客户端在调用前询问用户。源码注释的原话是："声称其它情况就是把猜测呈现为事实"。
3. 声明与实现用同一组常量绑定。标注不是写在提交表单里的孤立文本，而是 src/treg/mcp.py 中与实际工具装饰器绑定的代码，并由 tests/test_mcp.py 逐项断言。文档开篇强调"取自服务器实际声明的值（生产环境的tools/list），而非代码意图"——这保证审核者核对的与线上运行的完全一致。

如果你正在为 ChatGPT / Codex 插件目录编写类似的工具标注，treg 这份文档 + 源码 + 测试的组合是一个可以直接参考的模板：把每个工具的四类标注写成可核对的理由段落，把标注常量与工具定义绑定在同一个文件里，再用一个测试函数锁定"声明即行为"的契约。

• 后端
• API网关
• MCP 服务
• dsh-plugin