智能体工具目录superdesigndev/treg

Treg（面向工具的 OpenRouter）

treg — 你的智能体的工具目录

OpenRouter，但面向的是智能体工具而非模型。 让智能体指向一个基础 URL、使用一个令牌，
它就能完成工作：涵盖 60+ 家提供商的 3,000+ 个编目端点 —— SEO 与外链、
社交与趋势、人物与公司信息丰富、广告、抓取、图像与视频生成 ——
按调用计费，低至一美分，
无需向提供商注册。此外还有你自己团队的密钥、技能和 CLI，每个队友的
智能体都可调用，而凭证永不离开服务器。

提出任务，而非工具。 你无需知道哪家供应商出售外链数据，也无需
在他们那里持有账户。搜索你想做的事，查看价格，然后调用。

为 Superdesign 团队打造，运行于 treg.to —— 任何人都可以自行托管。

为什么存在

智能体完成实际工作所需的工具，往往被订阅墙挡在门外——没人会为单次运行去购买——
Semrush $139/月、Moz $99/月、Crunchbase $99/月、Apollo $59/席位——或者被注册墙挡住，或者
根本没有公开 API（仅限邀请、仅限合作伙伴、仅限应用审核）。treg 持有这些账户，
并按每次调用几分之一美分的价格计费。

两类工具，一个令牌

- 目录 —— 外部端点，treg 可以用自己的密钥或通过无需提供商密钥的已验证公开
路由来提供服务。自有密钥调用使用团队的预付余额；匿名调用
免费。无需在提供商处拥有账户。新的已验证账户在创建符合条件的团队时，
一次性获得 $1.00 免费额度。
- 你自己的工具 —— 队友注册的任何东西：付费 API 账户、OAuth 连接、
供应商 CLI、SKILL.md。你自己的密钥始终优先于 treg 的，而且这些调用
从不计量。

后半部分的术语：

- tool（工具） = 注册表使用组织凭证为你调用的东西。两种：
- endpoint（端点） —— 一个上游 base_url + 凭证绑定（每个绑定将一个
密钥注入请求；一个请求可以携带多个，例如一个 OAuth bearer 和一个
developer-token 头）。
- CLI —— 一个供应商二进制文件（stripe、gh、vercel……），在注入凭证的情况下运行。
- skill / bundle（技能/捆绑包） = 一份配方（SKILL.md）+ 其密钥 + 其工具，一起注册。

唯一规则： 代理只中继，绝不建模上游，并且在服务端注入认证
—— 因此它能经受上游 API 变化，调用方也从不持有密钥。

第 1 部分 · 使用注册表

访问 treg.to（托管在 Render 上）—— 仪表盘、
登录以及下面的每个 URL 都在那里。

快速开始

与仪表盘的 Getting started 指南相同的流程：

1. 安装 CLI —— 同时将其指向注册表
curl -fsSL https://treg.to/install.sh | sh

2. 登录（默认 GitHub · --email 使用一次性验证码 · --token 用于智能体/CI）
treg login

3. 立即做点有用的事 —— 无需密钥，无需注册任何东西
treg catalog search "backlinks for a domain"     # 按功能查找工具
treg call tikhub.tiktok.user.profile --query uniqueId=tiktok
treg balance                                     # 精确查看该次调用的费用

（或使用 treg onboard 进行引导式演练）

目录工具的输入通过 treg catalog get  描述。标记为 strict_query 的工具会拒绝未声明或重复的查询参数、不支持的值以及请求体。

你的令牌在每次调用时标识你的身份（X-Treg-Token 请求头），并且对所有工具都相同。
查看你的团队共享了哪些内容：treg tool ls · 检查凭据健康状况：treg health。

或者将其安装为 Claude Code 插件

/plugin marketplace add superdesigndev/treg
/plugin install treg@treg

安装时无需令牌，也无需配置。该技能以 treg:treg 加载，并在首次运行时
引导你的 agent 完成其余步骤——CLI、登录，然后是 treg mcp install——这样你最终会同时拥有
命令行和 treg 的工具。其他 agent：npx skills add superdesigndev/treg -s treg
（-s 很重要——没有它，你还会得到此仓库的内部开发技能）。
参见 docs/CLAUDE-PLUGIN.md。MiniMax Code / MiniMax Agent 用户：同一
技能通过 MiniMax Plugin Marketplace 提供（docs/MINIMAX-PLUGIN.md）。

Claude.ai 连接器

Claude Connectors Directory 的接口是 https://treg.to/mcp/v2/。它仅暴露精选的
目录端点，并将读调用与写调用分离，以便 Claude 接收到准确的安全
信号。现有的 /mcp/ 接口仍可用于目录端点、团队自有工具
以及导入的技能。有关边界和实现，请参见 MCP 和 OAuth 架构，
有关发布门禁，请参见
提交运行手册。

调用你没有密钥的工具

目录按端点功能分组：关键词和排名跟踪、反向链接和权威度、
AI 可见性、趋势和发现、发布到社交平台、人物和公司信息丰富、广告
管理和创意、衡量。

treg catalog                                    # 每个平台，按繁忙程度排序
treg catalog search "find a work email"         # 按任务，而非供应商
treg catalog get hunter.people.email.find       # 参数、价格、示例响应
treg call hunter.people.email.find --query domain=reddit.com --query full_name="Alexis Ohanian"

目录化调用如何被服务——凭据阶梯，按顺序：

1. 你的团队为该提供商注册了自己的工具 → 使用该工具、该密钥；
2. 你的团队为该提供商存储了密钥 → 通过虚拟工具注入；
3. 两者都没有，且该端点有经过验证的公共路由 → 无需提供商密钥，免费；
4. 否则 → treg 自己的密钥，计入团队的预付余额。

匿名价格假定调用方不发送提供商凭据请求头。忠实的
relay 会保留调用方的请求头，因此调用方提供的提供商密钥可以使用该密钥的额度。
你自己的凭据始终优先于 treg 的凭据，所以连接一个你已经在付费的密钥，可以让这些调用
不消耗余额，而不是重复计费。对于 treg 没有公布价格的端点，会被拒绝，而不是免费提供——
系统会提示你改为连接自己的密钥。当多个提供商提供同一项能力时，treg catalog search 会
将它们与价格并排展示；选择权在你——treg 不会替你静默挑选或在提供商之间故障转移。
（当 treg 自己在某个提供商的账户余额耗尽时，它可能会通过 treg 拥有的 relay 账户提供同一个
端点，并在响应中披露；团队可以选择退出。）你主动选择的例外：treg. 路由端点，
此时 treg 会替你挑选提供商并指明是哪一家。

treg balance          # 剩余额度、进行中的调用、近期支出
treg topup            # 充值，或设置自动充值

余额不足会返回 HTTP 402，并携带 balance_micro、estimated_cost_micro 和 topup_url，
因此 agent 无需阅读文字说明即可据此采取行动。

Enrich Arena 位于 /enrich-arena，在仪表盘之外。可以比较各供应商的富集答案及其成本与速度，
一键为最佳答案投票，或观看顺序瀑布流。浏览是公开的；提交需要登录，可计费的尝试会使用你团队的
额度。参见 Arena 指南。

分享并使用你自己的工具

零思考路径——把 treg 指向一个项目，它会自行判断哪些内容可以分享：

treg scan     # 只读预览：上传时会注册的密钥、技能和 CLI
treg upload   # 注册它们（服务端加密）；幂等，使用 --replace 更新

treg upload 会扫描 .env（将密钥与约 80 个已知提供商匹配）、每个技能子目录，以及已安装的
目录 CLI。有三类内容会进入注册表——以下是分享和使用每一类的方法：

1. 端点（HTTP API）

分享——一个可用存储密钥调用的上游 URL，或从 .env 批量导入：

treg secret add STRIPE_KEY --value sk_live_123
treg add stripe --base-url https://api.stripe.com --secret STRIPE_KEY

treg upload env --select openai,stripe,resend     # 或直接从 .env 导入

使用——agent 原生方式：构建真实的上游请求，并在前面加上代理前缀。
treg 会按主机解析工具、注入凭据，并原样转发其他所有内容
（你的 X-Treg-Token 会在上游看到之前被剥离）：

真实请求：   GET https://api.intercom.io/conversations?per_page=5
通过 treg：   GET https://treg.to/call/https://api.intercom.io/conversations?per_page=5
header:  X-Treg-Token:

或者使用 CLI 简写——并用 treg calls 查看审计日志：

treg call intercom conversations --query per_page=5
treg call stripe v1/balance

2. CLI
共享 — 自动：treg upload 会检测已安装的目录 CLI（stripe、gh、vercel……）
并注册它们；仅含 recipe 的目录 CLI 技能（例如 stripe-cli）也会自动变为可运行。

使用 — treg run 执行供应商 CLI 时注入组织的凭证，因此你无需
持有密钥或登录：

treg run stripe -- get /v1/balance
treg run gh -- pr list
treg run --server agentmail-cli inboxes list   # 在注册表服务器上运行：密钥永远不会到达你这里

--local（默认）在你的机器上运行；--server 在注册表上运行并将输出流式传回。
对于整个会话，treg shell start 会打开一个子 shell，其中每个已注册的 CLI 都会自动注入
——只需正常使用 stripe、gh……；exit 即可还原。treg runs 是审计日志。

3. 技能

共享 — 一个技能就是一整项能力（SKILL.md recipe + 其密钥 + 其工具），
一起注册，使整个团队运行相同的技能，并在一处维护：

treg upload skills --dir ~/.claude/skills --all   # 一次性注册一个技能文件夹

使用 — 将任何共享技能拉取到你的 agent 中；其 API 调用会携带你的 token 通过 treg，
因此密钥留在服务器上，绝不会出现在技能中：

treg skill install seo-blog-writer      # 写入 ./.claude/skills/  （--all 用于整个库）

手动注册 — 当启发式规则无法识别某个工具时

多凭证工具（例如 google-ads：OAuth bearer + 一个 developer-token 头）
treg tool add google-ads --base-url https://googleads.googleapis.com \
--bind "secret=,injector=oauth" \
--bind "secret=,name=developer-token,format={secret}"

一个技能，逐步操作
treg skill init --dir ./my-skill          # 起草 treg.json（猜测 base_url，查找密钥）
treg skill add  --dir ./my-skill          # 原子性地注册 recipe + 密钥 + 工具

通过浏览器进行 OAuth（生成第一个 token，treg 持有它并自动刷新）
treg oauth connect gsc --client-secret client_secret.json \
--scopes https://www.googleapis.com/auth/webmasters.readonly

每个命令的完整选项：USAGE.md。

使用 treg.to 时，CLI 会向 PostHog 发送匿名命令使用情况（不包含参数或凭证）。
可通过 TREG_TELEMETRY=0 或 DO_NOT_TRACK=1 禁用。
参见分析详情。

团队

一个账户最多可拥有 10 个团队。作为成员加入其他团队不计入此限制。

一切都以组织为范围：一个 token = 一个 (user, org) 成员关系，并且每个密钥、工具
和技能都属于当前活动组织。角色：owner / admin / member / viewer。

treg org create "Acme"                        # 创建一个团队，成为 owner
treg org invite teammate@acme.com             # 通过电子邮件邀请（选择角色 + 工具访问权限）
treg org join  --email you@acme.com     # 接受邀请（如果是新用户则创建你）
treg org ls | use  | members            # 切换组织，查看成员名单
treg org access  --tools a,b          # 按成员设置工具访问权限（管理员及以上）

深入了解

- 反馈： treg feedback submit friction "The pagination example is unclear."
分享问题或建议，请勿包含隐私信息。参见反馈说明。
- 评价： treg review CALL_ID useful
在使用受邀目录调用的结果后对其进行评分；not_sure 也可以。请勿包含隐私数据，并继续执行任务。

- USAGE.md — 完整的 treg CLI 参考。
- /llms.txt — 面向智能体的入门文件：调用
协议、发现、认证、CLI、技能。一次获取即可让智能体了解整个注册表。
- 仪表盘位于 treg.to — 完整的增删改查、引导式
教程（帮助 → 教程），以及可复制到你的智能体的设置说明。
- API — CLI 所做的一切都是纯 HTTP；交互式 OpenAPI 文档位于 /docs。
代理端点为 /call/{...}；所有端点都接受 X-Treg-Token 请求头。

第 2 部分 · 自托管与开发

在本地运行

一条命令（需要 tmux + uv；它会自行同步 venv）：
bash
scripts/dev-local.sh up        # 服务器运行在 http://localhost:18790，开发安全设置

这会在 tmux 中运行服务器，支持热重载，使用自己的 sqlite 数据库（treg-dev.db），并启用邮件 OTP 开发
模式（登录验证码显示在页面上——无需邮件发送器）。日常使用：
bash
scripts/dev-local.sh cli login   # 沙箱化 CLI：绝不会触碰你真实的 ~/.treg/config.json
scripts/dev-local.sh logs        # 服务器输出          · status / restart / down
scripts/dev-local.sh reset       # 清除开发数据库 + CLI 沙箱，重新开始

或者直接运行服务器，不使用 tmux：
bash
uv sync                        # 根据 uv.lock 创建 venv（为开发拉取服务器依赖）
uv run python -m treg upgrade  # 准备数据库架构并运行幂等的发布任务，但不启动服务
uv run python -m treg          # 在 0.0.0.0:18790 上提供服务（开发时添加 --reload）
uv run python -m treg keygen   # 为 TREG_SECRET_KEY 打印一个新的 Fernet 密钥

安装以运行服务器（而非从源码运行）： 基础包仅包含 CLI。要运行
注册表，请安装服务器附加项——pip install "tools-registry[server]"——它会添加 FastAPI、
数据库驱动和加密功能。仅 pip install tools-registry 只提供 treg 命令，用于
与现有注册表通信。

官方托管服务位于 treg.to。其生产拓扑和实时设置
维护在私有的运维手册中。

配置

环境变量（前缀 TREG_，从 .env 读取）：
| 变量                                    | 默认值                          | 用途                                                                                                                                                                       |
| ----------------------------------------- | ------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| TREG_DATABASE_URL                       | sqlite+aiosqlite:///./treg.db | 数据库 URL（开发环境用 SQLite，生产环境用 Postgres）                                                                                                                       |
| TREG_SECRET_KEY                         | （空）                        | 用于静态加密密钥的 Fernet 密钥；为空 → 会生成一个临时密钥（密钥在重启后不会保留）                                                                                          |
| TREG_PUBLIC_URL                         | https://treg.to  | treg 的公开基础地址，用于构建 OAuth 回调 URI                                                                                                                               |
| TREG_SESSION_SECRET                     | （空）                        | 用于签名仪表盘会话 cookie；回退到 TREG_SECRET_KEY。在生产环境中请设置一个真实值                                                                                          |
| TREG_GITHUB_CLIENT_ID / _SECRET       | （空）                        | GitHub OAuth 登录（回调 /auth/github/callback）；为空则隐藏该按钮                                                                                            |
| TREG_GOOGLE_CLIENT_ID / _SECRET       | （空）                        | Google OAuth 登录（重定向 /auth/google/callback）；为空则隐藏该按钮                                                                                          |
| TREG_INSTAGRAM_CLIENT_ID / _SECRET    | （空）                        | 用于直接 Instagram 登录的 Instagram App ID 和密钥（重定向 /oauth/callback）                                                                                  |
| TREG_META_CLIENT_ID / _SECRET         | （空）                        | 用于 Facebook Pages、Meta Ads 以及可选 Instagram page-tools 的 Meta 应用凭据                                                                                             |
| TREG_OAUTH_REVIEW_PENDING               | instagram-login,page-messages | 以逗号分隔的注册表审核键，其能力必须保持受限；托管审核状态会私下维护。                                                                                                     |
| TREG_RESEND_API_KEY / TREG_EMAIL_FROM | （空）                       | 通过 Resend 发送事务性邮件（OTP 验证码 + 邀请）；发件人必须是 Resend 已验证的发件人                                                                                |
| TREG_BLOCKED_EMAIL_DOMAINS              | （空）                       | 以逗号分隔的电子邮件域名，在每个注册/登录入口以及团队创建时都会被拒绝（包括子域名，不区分大小写）。留空则不阻止任何内容——代码中不附带任何列表 |
| TREG_ADMIN_TOKEN                        | （空）                       | 跨租户的 超级管理员 bearer；授权所有 /admin/ 端点。留空则禁用该环境变量路径（只有 is_superadmin 用户能访问 /admin）。请保持其足够长且保密。 |
| TREG_EMAIL_DEV_MODE                     | false                         | 当为 true 时，/auth/email/start 会在其响应中返回 OTP（无需邮件发送器）——仅限开发/本地环境，切勿用于生产环境。                                                |
| TREG_KV_URL                             | （空）*                       | 共享键值存储（Redis 协议），用于所有 worker 必须达成一致的计数器，目前是每个团队的评审邀请预算。留空 = 使用进程内回退方案，适用于单个 worker |

本地开发不需要 .env——每个设置都有可用的默认值（临时密钥、sqlite）。

⚠️ 在迁移或重新部署之前请备份这些内容： Fernet 密钥（TREG_SECRET_KEY）和
数据库（生产环境为 Postgres；本地 sqlite 运行为 treg.db）。丢失 Fernet 密钥后，所有
已存储的密钥都将无法恢复。

架构

/call 的请求流程： 解析工具（通过 URL 主机 + 最长的 base_url 前缀，或通过名称）→
解密其密钥 → 应用每个绑定的注入器 → 流式传输到上游 → 即发即忘的
审计记录。基础设施中继仅流式传输字节，不包含业务逻辑。需要结算或所有权证据的调用应用会缓冲
响应，最多 8 MiB；更大的响应会返回 502
而不计费，而不是返回被截断的成功响应。无需正文
证据的已授权免费最终下载会完整流式传输，自有密钥和自有工具响应也是如此。

模块映射（src/treg/）：

| 模块                                     | 角色                                                                                                             |
| ------------------------------------------ | ---------------------------------------------------------------------------------------------------------------- |
| proxy.py                                 | relay()——整个产品集于一个函数：一个忠实的流式代理                                        |
| injectors.py                             | 认证形态接缝：env、cli_auth、secret_file、oauth 将密钥放入 header/query                |
| oauth.py                                 | token 新鲜度（单飞刷新）+ 连接流程（授权 URL、代码交换）                          |
| health.py                                | 凭据健康：刷新 oauth、探测工具、对任何损坏项的所有者发送 webhook 通知                              |
| convert.py                               | 将技能目录脚手架化为可注册的 bundle 清单                                                   |
| api.py                                   | API——唯一的大脑；CLI + 技能是构建于其上的瘦客户端                                                   |
| cli.py                                   | treg CLI                                                                                                   |
| models.py                                | SQLModel 表：Org、User、Membership、Invite、Secret、Tool、Bundle、PendingOAuth、CallRecord |
| crypto.py config.py db.py audit.py | Fernet 加密 + 令牌 · 设置 · 异步数据库 · 延迟审计写入器                                         |

4 种认证形态（按绑定 injector）：env（纯字符串 / API 密钥）· secret_file（一个
JSON 令牌文件，提取某个字段）· oauth（一个 JSON OAuth 令牌，若可刷新则自动刷新）·
cli_auth（从 CLI 的钥匙串中提取的凭据材料）。

忠实中继契约： 代理仅改动三样东西，其余一切都原样保留：

1. 逐跳传输头（每跳重新推导），
2. treg 自身的控制 + 边缘转发头（x-treg-token、x-treg-org、
ngrok-skip-browser-warning、x-forwarded-、via、……）以及 treg 的会话 cookie——全部剥离，
绝不泄漏到上游，
3. 注入的凭据。

OAuth，获取首个令牌的三种方式： 手动上传（放入一个 token.json）·
自动刷新（若令牌带有 refresh_token + 客户端凭据，treg 会保持其新鲜，你无需
重新上传）· 托管连接流程（treg oauth connect → 浏览器授权 → treg 自行捕获
令牌）。

健康检查： 为工具提供一个可选的探测（{method, path, expect_status}）；周期性运行
（按需或通过 cron）会验证每个凭据、刷新 OAuth，并对任何损坏项的所有者发送 webhook 通知。

深入设计位于 docs/context/（按子系统拆分的片段）。

测试
bash
uv run --with pytest-xdist pytest -n auto -q   # 每日本地默认（与 CI 形态相同）
uv run --frozen python -m pytest -q            # 串行：调试单个测试，或顺序

覆盖范围：代理走查骨架、所有注入器形态、按用户认证 + CRUD + 审计、技能组合器、
URL 透传 + 忠实中继、OAuth 刷新 + 连接流程、健康检查、treg run/shell、
上传/扫描、组织 + 邀请、仪表盘 API、CLI。

贡献与文档

treg/
├── src/treg/            # 包（api、cli、proxy、injectors、oauth、health、convert、models、……）
│   └── web/             # 仪表盘、落地页、教程、llms.txt、skill.md、install.sh
├── tests/               # pytest 测试套件（CI + 本地默认：pytest-xdist -n auto）
├── docs/
│   ├── context/         # 设计片段（codemap 系统）+ 生成的索引
│   └── ONBOARDING.md    # 首次引导
├── USAGE.md             # 完整的 treg CLI 参考
└── pyproject.toml

各子系统的设计文档是 docs/context/ 中的片段，每个片段都引用其对应的 src/treg/
源码。在这个仓库中使用 AI 智能体工作？/tools-registry-context 技能会针对你正在处理的内容
加载正确的片段，并保持文档同步——推送前运行
/tools-registry-context sync。

路线图： MCP 支持 · 更细粒度的权限层级 · 静态密钥管理加固 · 可能的
Loopni 合并。

许可证

Apache 2.0 附加条款（LICENSE）：可自由使用——包括商业用途，
在你自己的组织内部使用（鼓励自托管你自己的注册表）。限制：未经书面
许可（jason@superdesign.dev），不得将代码作为竞争性的托管/管理注册表服务重新分发给第三方。
在你自己的产品中使用托管的 treg.to API——
通过 X-Treg-Meta 和 usage/by-tag 进行透传计费——是允许的，无需许可；
那是调用我们的 API，而不是重新分发我们的软件。