内容
# Treg（工具注册中心）
**停止在代理上下文和 Slack DMs 中粘贴 API 密钥和技能。** Treg 是您的团队共享的技能、CLI、端点和密钥的注册中心。代理直接调用 Stripe、PostHog、`gh` — 在服务器端注入身份验证，每次调用都记录。无需粘贴任何内容，无需泄露。
为 Superdesign 团队构建，目前在 [treg.superdesign.dev](https://treg.superdesign.dev) 上运行 - 任何人都可以自行托管。
- **工具** = 注册中心为您调用的带有组织凭证的东西。两种类型：
- **端点** - 上游 `base_url` + 凭证 **绑定**（每个绑定注入一个密钥到请求中；一个请求可以携带多个，例如 OAuth bearer 和 `developer-token` 头部）。
- **CLI** - 带有注入凭证的供应商二进制文件（`stripe`、`gh`、`vercel`，...）
- **技能 / 捆绑包** = 一个配方（`SKILL.md`）+ 其密钥 + 其工具，一起注册。
**唯一规则：** 代理 **中继，从不建模** 上游，并且 **在服务器端注入身份验证** - 因此它可以应对上游 API 更改，并且调用者永远不会持有密钥。
---
# 第 1 部分：使用注册中心
访问 [**treg.superdesign.dev**](https://treg.superdesign.dev) （托管在 Render 上）- 仪表板，登录和以下所有 URL 都在此处运行。
## 快速入门
与仪表板的 **入门** 指南相同的流程：
```bash
# 1. 安装 CLI - 同时将其指向注册中心
curl -fsSL https://treg.superdesign.dev/install.sh | sh
# 2. 登录（GitHub 默认 · --email 获取一次性代码 · --token 用于代理/CI）
treg login
# 3. 引导设置 - 共享您的技能和密钥，或连接到您的团队
treg onboard
# 然后调用共享工具 - 您的机器上没有密钥
treg call stripe v1/balance
```
您的令牌标识您每次调用（`X-Treg-Token` 头部），并且与所有工具相同。
发现您的团队已共享的内容：`treg tool ls` · 检查凭证健康状况：`treg health`.
## 共享和使用工具
零思考路径 - 将 treg 指向一个项目，它会找出可以共享的内容：
```bash
treg scan # 只读预览：上传的密钥、技能和 CLI 将注册
treg upload # 注册它们（服务器端加密）；幂等，--replace 更新
```
`treg upload` 扫描 `.env`（匹配约 80 个已知提供商的密钥），每个技能子目录和已安装的目录 CLI。 三种东西进入注册中心 - 以下介绍如何共享和使用每种：
### 1. 端点（HTTP API）
**共享** - 一个上游 URL 可与存储的密钥调用，或从 `.env` 批量共享：
```bash
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
```
**使用** - 代理原生方式：构建真正的上游请求并以代理为前缀。
treg 解析工具按主机，注入凭证，并忠实地中继其他所有内容
（您的 `X-Treg-Token` 在上游看到之前被剥离）：
```
真实请求： GET https://api.intercom.io/conversations?per_page=5
通过 treg： GET https://treg.superdesign.dev/call/https://api.intercom.io/conversations?per_page=5
头部： X-Treg-Token: <您的令牌>
```
或 CLI 简写 - 和 `treg calls` 用于审计日志：
```bash
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 **并注入组织的凭证**，因此您永远不会
持有密钥或登录：
```bash
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` 配方 + 其密钥 + 其工具），
一起注册，以便整个团队运行相同的技能，在一个地方维护：
```bash
treg upload skills --dir ~/.claude/skills --all # 一次注册一个技能文件夹
```
**使用** - 将任何共享的技能拉入您的代理；其 API 调用通过 treg 以及您的令牌进行，
因此密钥保留在保险库中，从不进入技能：
```bash
treg skill install seo-blog-writer # 写入 ./.claude/skills/ (--all 获取库)
```
### 手动注册 - 当启发式无法确定工具时
```bash
# 多凭证工具（例如 google-ads：OAuth bearer + developer-token 头部）
treg tool add google-ads --base-url https://googleads.googleapis.com \
--bind "secret=<oauth-id>,injector=oauth" \
--bind "secret=<dev-id>,name=developer-token,format={secret}"
# 一个技能，逐步
treg skill init --dir ./my-skill # 草拟 treg.json（猜测 base_url，找到密钥）
treg skill add --dir ./my-skill # 注册配方 + 密钥 + 工具，原子操作
# 通过浏览器进行 OAuth（颁发第一个令牌，treg 持有它并自动刷新）
treg oauth connect gsc --client-secret client_secret.json \
--scopes https://www.googleapis.com/auth/webmasters.readonly
```
每个命令的完整选项：[`USAGE.md`](USAGE.md).
## 团队
所有内容都限定在 **组织**：令牌 = `(用户，组织)` 成员资格，并且每个密钥，工具
和技能都属于活动的组织。 角色：**所有者 / 管理员 / 成员 / 查看者**。
```bash
treg org create "Acme" # 创建团队，成为所有者
treg org invite teammate@acme.com # 通过电子邮件邀请（选择角色 + 工具访问）
treg org join <code> --email you@acme.com # 接受邀请（如果新用户则创建）
treg org ls | use <slug> | members # 切换组织，查看团队成员
treg org access <member> --tools a,b # 按成员工具访问（管理员+）
```
## 更深入
- [`USAGE.md`](USAGE.md) - 完整的 `treg` CLI 参考。
- [`/llms.txt`](https://treg.superdesign.dev/llms.txt) - 代理入职文件：调用
协议，发现，身份验证，CLI，技能。 一个获取教会代理整个注册中心。
- **仪表板** 在 [treg.superdesign.dev](https://treg.superdesign.dev) - 完整的 CRUD，引导式
教程（帮助→教程）和代理的复制设置说明。
- **API** - 所有 CLI 操作都是纯 HTTP；交互式 OpenAPI 文档位于 `/docs`.
代理端点是 `/call/{...}`；所有端点都接受 `X-Treg-Token` 头部。
---
# 第 2 部分：自行托管和开发
## 在本地运行
一条命令（需要 `tmux` + [`uv`](https://docs.astral.sh/uv/)；它会同步 venv 本身）：
```bash
scripts/dev-local.sh up # 服务器位于 http://localhost:18790，开发安全设置
```
该命令在 tmux 中运行服务器，带有热重载，其自己的 sqlite DB（`treg-dev.db`），和电子邮件 OTP 开发
模式（登录代码显示在页面上 - 无需邮件发送器）。 日常：
```bash
scripts/dev-local.sh cli login # 沙盒 CLI：从不触及您真正的 ~/.treg/config.json
scripts/dev-local.sh logs # 服务器输出 · 状态 / 重启 / 关闭
scripts/dev-local.sh reset # 擦除开发 DB + CLI 沙盒以获得全新开始
```
或直接运行服务器，无需 tmux：
```bash
uv sync # 从 uv.lock 创建 venv（提取服务器依赖项以进行开发）
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` 命令用于
> 与现有注册中心通信。
团队实例托管在 **Render** （网络服务 + Postgres）上，位于 `treg.superdesign.dev`.
## 配置
环境变量（前缀 `TREG_`，从 `.env` 读取）：
| 变量 | 默认值 | 目的 |
| ----------------------------------------- | ------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `TREG_DATABASE_URL` | `sqlite+aiosqlite:///./treg.db` | 数据库 URL（开发环境使用 SQLite，生产环境使用 Postgres） |
| `TREG_SECRET_KEY` | *(空)* | 静态密钥，用于加密存储的密钥；为空时，会生成一个临时密钥（密钥不会在重启后存活）。 |
| `TREG_PUBLIC_URL` | `https://treg.superdesign.dev` | treg 的公共基准，用于构建 OAuth 回调 URI |
| `TREG_SESSION_SECRET` | *(空)* | 签名仪表板会话 cookie；默认为 `TREG_SECRET_KEY`. 在生产环境中设置一个真实值。 |
| `TREG_GITHUB_CLIENT_ID` / `_SECRET` | *(空)* | GitHub OAuth 登录（回调 `<public_url>/auth/github/callback`）；为空时隐藏按钮。 |
| `TREG_GOOGLE_CLIENT_ID` / `_SECRET` | *(空)* | Google OAuth 登录（重定向到 `<public_url>/auth/google/callback`）；为空时隐藏按钮。 |
| `TREG_RESEND_API_KEY` / `TREG_EMAIL_FROM` | *(空)* | 通过 Resend 发送交易邮件（OTP 代码 + 邀请）；发件人必须是 Resend 验证的发送者。 |
| `TREG_ADMIN_TOKEN` | *(空)* | 跨租户 **超级管理员** 承载者；授权所有 `/admin/*` 端点。为空时禁用环境路径（仅 `is_superadmin` 用户可访问 `/admin`）。请保持长且保密。 |
| `TREG_EMAIL_DEV_MODE` | `false` | 当为 true 时，`/auth/email/start` 在其响应中返回 OTP（无需邮件发送器）- **仅限开发/本地使用**，绝不能在生产环境中使用。 |
本地开发不需要 `.env` - 每个设置都有一个有效的默认值（临时密钥，sqlite）。
> **⚠️ 备份这些内容，然后再移动或重新部署：** Fernet 密钥（`TREG_SECRET_KEY`）和数据库
> （生产环境使用 Postgres；本地运行使用 `treg.db`）。如果丢失 Fernet 密钥，所有存储的密钥都将无法恢复。
## 架构
**调用 `/call` 的请求流程：** 解析工具（按 URL 主机 + 最长的 `base_url` 前缀，或按名称）→
解密其密钥（s）→ 应用每个绑定的注入器 → 流式传输到上游 → 异步审计记录。 代理不会执行任何业务逻辑，并且永远不会缓冲正文。
**模块映射** (`src/treg/`):
| 模块 | 角色 |
| ------------------------------------------ | ---------------------------------------------------------------------------------------------------------------- |
| `proxy.py` | `relay()` - 整个产品在一个函数中：忠实流式代理 |
| `injectors.py` | 身份验证形状的缝隙：`env`, `cli_auth`, `secret_file`, `oauth` 将密钥放入头部/查询 |
| `oauth.py` | 令牌新鲜度（单次刷新）+ 连接流程（同意 URL，代码交换） |
| `health.py` | 凭证健康状况：刷新 oauth，探测工具，通过 webhook 通知所有者任何故障 |
| `convert.py` | 将技能目录构建为可注册的捆绑包清单 |
| `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 加密 + 令牌 · 设置 · 异步 DB · 延迟审计写入 |
**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. 注入的凭证（s）。
**OAuth，三种获取第一个令牌的方式：** *手动上传*（放入 `token.json`）·
*自动刷新*（如果令牌带有 `refresh_token` + 客户端凭证，treg 使其保持新鲜，您永远不会
重新上传）· *托管连接流程*（`treg oauth connect` → 浏览器同意 → treg 捕获令牌本身）。
**健康检查：** 给工具一个可选的探针（`{method, path, expect_status}`）；定期运行
（按需或通过 cron）验证每个凭证，刷新 OAuth，并向所有者发出 webhook 通知，提示任何
故障。
深入设计位于 [`docs/context/`](docs/context/README.md)（按子系统片段）。
## 测试
```bash
uv run pytest -q # 521 个测试
```
覆盖范围：代理行走骨架，所有注入器形状，按用户身份验证 + CRUD + 审计，技能合成器，
URL 直通 + 忠实中继，OAuth 刷新 + 连接流程，健康检查，`treg run`/shell，
上传/扫描，组织 + 邀请，仪表板 API，CLI。
## 贡献与文档
```
tools-registry/
├── src/treg/ # 包（api, cli, proxy, injectors, oauth, health, convert, models, …）
│ └── web/ # 仪表板，登陆页面，教程，llms.txt，skill.md，install.sh
├── tests/ # 521 个测试
├── docs/
│ ├── context/ # 设计片段（代码映射系统）+ 生成的索引
│ └── 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`](LICENSE）：自由使用 - 包括商业用途，
在您自己的组织内（鼓励自行托管自己的注册中心）- 但不要将其作为托管/托管服务提供给第三方
或将其嵌入商业分发产品中，无需书面许可（`jason@superdesign.dev`）。
连接信息
猜你喜欢
暂无推荐服务器