treg

npx add-mcp 'https://treg.to/mcp/v2/'

Treg（適用於工具的 OpenRouter）

就像 OpenRouter，但服務的是代理工具，而不是模型。 只要將代理指向一個基底 URL，並提供一個權杖， 就能開始工作：精選目錄涵蓋多家供應商的數千個端點 — SEO 與反向連結、 社群與趨勢、人物與公司資料補充、廣告、網頁擷取、圖片與影片生成 — 按次計費，每次低至一美分， 無須註冊供應商帳戶。此外，團隊自己的金鑰、技能與 CLI 也能供每位隊友的 代理呼叫，且憑證永遠不會離開伺服器。

描述任務，而不是工具。 你不必知道哪家供應商販售反向連結資料，也不必 在他們那裡持有帳戶。搜尋你想做的事、查看價格，然後呼叫即可。

為 Superdesign 團隊打造，現已上線於 treg.to — 任何人都可以自行託管。

為何打造

代理完成實際工作所需的工具，往往藏在沒人會為單次執行購買的訂閱方案後面 — Semrush 每月 $139、Moz 每月 $99、Crunchbase 每月 $99、Apollo 每席每月 $59 — 或是註冊牆後面，甚至根本沒有公開 API（僅限邀請、合作夥伴或通過應用程式審核）。 treg 提供這些帳戶，並按次收取不到一美分的費用。

兩種工具，一個權杖

• 目錄 — treg 可透過自己的金鑰，或經由無須供應商金鑰的已驗證公開路徑提供的外部端點。使用自有金鑰的呼叫會扣除團隊預付餘額；匿名呼叫免費。無須持有供應商帳戶。新驗證帳戶在建立符合資格的團隊時，可獲得一次 $1.00 免費額度。
• 你自己的工具 — 隊友註冊的任何工具：付費 API 帳戶、OAuth 連線、供應商 CLI、SKILL.md。你自己的金鑰永遠優先於 treg 的金鑰，而且這些呼叫絕不計費。

第二部分使用的詞彙：

• 工具 = 登錄庫使用組織憑證代你呼叫的項目。分為兩種：
  • 端點 — 上游 base_url + 憑證綁定（每個綁定會將一個密鑰注入請求；一個請求可以帶有多個密鑰，例如 OAuth bearer 以及 developer-token 標頭）。
  • CLI — 使用注入憑證執行的供應商二進位檔（stripe、gh、vercel 等）。
• 技能 / 套件 = 配方（SKILL.md）+ 其密鑰 + 其工具，註冊在一起。

唯一規則：代理伺服器只會轉送，不會模擬上游，並且會在伺服器端注入驗證資訊 — 因此上游 API 變更時仍可正常運作，呼叫端也永遠不會持有金鑰。

---

第 1 部分 · 使用登錄庫

造訪 treg.to（託管於 Render）— 儀表板、 登入，以及下方所有 URL 都位於此處。

快速入門

流程與儀表板的 Getting started 指南相同：

# 1. install the CLI — also points it at the registry
curl -fsSL https://treg.to/install.sh | sh

# 2. sign in (GitHub default · --email for a one-time code · --token for agents/CI)
treg login

# 3. do something useful immediately — no key, nothing registered
treg catalog search "backlinks for a domain"     # find a tool by what it DOES
treg call tikhub.tiktok.user.profile --query uniqueId=tiktok
treg balance                                     # exactly what that cost

# (or `treg onboard` for the guided walkthrough)

Fish Audio 提供 S2.1 Pro 語音、公開語音探索，以及私人語音複製。 語音輸出是二進位資料，因此請重新導向至檔案。探索到的語音 _id 或團隊語音 ID 是 TTS 的 reference_id；在 treg 的 Fish 帳戶上建立的語音是持久的團隊資源：

treg call fishaudio.tts.s2-1-pro --method POST --header model=s2.1-pro \
  --data '{"text":"Hello from treg","format":"mp3"}' > speech.mp3
treg call fishaudio.voices.discover --query self=false --query licensed=false --query language=en
treg resources list --provider fishaudio --kind voice

使用自己的 Fish 金鑰時，請求仍是不限使用量、不計費的上游轉送，帳戶界線由 Fish 管理。

目錄工具的輸入由 treg catalog get <id> 說明。標記為 strict_query 的工具會拒絕未宣告或重複的查詢參數、不支援的值及請求本文。每個已宣告的單值參數只傳送一次；像 limit 這樣的列數，則須以整數形式傳送，且不得超過其指定上限：執行此驗證的工具會回覆 400 catalog_parameter_invalid，指出參數名稱，且不會收取任何費用。

每次呼叫都會透過 X-Treg-Token 標頭識別你的身分，而且所有工具共用同一個權杖。 查看團隊分享的內容：treg tool ls · 檢查憑證狀態：treg health。

或安裝為 Claude Code 外掛程式

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

無須權杖或設定，即可安裝 treg 技能與 treg 工具。執行 /mcp，選擇 treg 並登入；之後工具就會出現。其他代理：npx skills add superdesigndev/treg -s treg （或參閱工作流程技能，了解其他技能）。 請參閱 docs/CLAUDE-PLUGIN.md。MiniMax Code / MiniMax Agent 使用者：同一項 技能也可透過 MiniMax Plugin Marketplace 安裝（docs/MINIMAX-PLUGIN.md）。

工作流程技能

可直接使用的配方，讓代理透過 treg 從頭到尾執行每次呼叫：

技能	代理可以做什麼
treg	在目錄中尋找並呼叫任何工具，也包括你自己的工具
web-access	當代理自己的網頁工具不敷使用時，不透過本機爬蟲讀取即時網頁：先使用免費搜尋與頁面讀取，再為社群、商店、評論、地圖與論文選擇合適的平台工作；若供應商失敗，treg 會改用下一家
lead-signals	根據公開訊號（抱怨、工作變動、招募、融資、工具採用）尋找有意向的買家，並監控主題、競爭對手或帳戶清單以找出這些買家（treg.to/leads-signals）
recruit	將 LinkedIn 職缺轉成排序後的候選名單：從職缺擷取條件、搜尋人物、附上理由篩選、用一句話說明每位候選人的適配原因，並在每位候選人的支出上限內提供引用證據（貼文、GitHub、演講、任職時間、工作變動），接著查證個人電子郵件與電話，並產生執行檔案，列出每位候選人的數量、證據與供應商歷程
make-ugc	製作 AI UGC 影片：熱門開場、主持人、對話式影片片段、字幕（treg.to/ugc）
jev-memory	為 Claude Code 加入記憶：一個 Claude Code 模組，由 Jev 在每輪結束後評估每個提示，並保留你長期適用的偏好；可直接安裝現成版本，也可用一個提示詞建立（該模組）

install.sh 只會安裝 treg，並在一行中列出其他技能；登入並完成第一次呼叫後，代理會提供這些技能。使用 sh -s -- --skills lead-signals,recruit 指定你想要的技能（或 --skills all；選擇加入的 jev-memory 和 rea-growth 絕不會包含在該集合中）。在 Claude Code 中，每項技能也都是 treg 市集中的獨立外掛程式：/plugin install recruit@treg，或從 /plugin 中選擇。若要將技能加入現有代理（使用 skills.sh CLI）：

npx skills add superdesigndev/treg                        # every public skill
npx skills add superdesigndev/treg --skill lead-signals   # just one
treg skill bootstrap --skills all                         # the installer's set, with the treg CLI you already have

工作流程技能在 treg 上執行，因此請先完成設定（使用上方的快速入門，或將代理指向 treg.to/llms.txt）。

Claude.ai 連接器

Claude Connectors Directory 的介面為 https://treg.to/mcp/v2/。它只公開精選的 目錄端點，不包含圖片、影片或音訊生成，並將讀取呼叫與寫入呼叫分開，讓 Claude 能收到準確的安全訊號。現有的 /mcp/ 介面仍可用於目錄端點、團隊自有工具 及匯入的技能。請參閱 MCP 與 OAuth 架構 了解界線與實作方式，並參閱 提交作業手冊了解發布檢查項目。

呼叫沒有金鑰的工具

目錄依端點的用途分類：關鍵字與排名追蹤、反向連結與權威度、 AI 能見度、趨勢與探索、社群發布、人物與公司資料補充、廣告 管理與創意、成效衡量。

treg catalog                                    # every platform, busiest first
treg catalog search "find a work email"         # by the job, not the vendor
treg catalog search --new                       # tools added in the last 30 days, newest first
treg catalog get hunter.people.email.find       # params, PRICE, example response
treg call hunter.people.email.find --query domain=reddit.com --query full_name="Alexis Ohanian"

目錄呼叫的服務方式 — 憑證依下列順序選用：

1. 你的團隊已為該供應商註冊自有工具 → 使用該工具及其金鑰；
2. 你的團隊已儲存該供應商的密鑰 → 透過虛擬工具注入；
3. 兩者皆無，且端點有已驗證的公開路徑 → 不需要供應商金鑰，免費；
4. 否則 → 使用 treg 自有金鑰，費用從團隊預付餘額扣除。

匿名價格假設呼叫端不會傳送供應商憑證標頭。忠實轉送會保留呼叫端標頭，因此呼叫端提供的供應商金鑰可能會使用該金鑰的額度。 你自己的憑證永遠優先於 treg 的憑證，因此連結你已付費使用的金鑰，就能讓這些呼叫不扣除餘額，而不是重複付費。若 treg 沒有公布某個端點的價格，該端點會被拒絕，而非免費提供 — 系統會提示你連結自己的金鑰。若多家供應商提供同一項功能，treg catalog search 會並列顯示各家供應商與價格；由你自行選擇 — treg 不會暗中替你選擇供應商，也不會在供應商之間自動切換。（若 treg 自有的供應商帳戶額度用盡，可能會透過 treg 自有的轉送帳戶提供相同端點，並在回應中揭露；團隊可以選擇退出。）你可以選擇啟用的例外是：treg.<capability> 路由端點，由 treg 替你選擇供應商並告知你使用哪一家。常見工作（擷取網頁、網頁搜尋、Google 搜尋結果、尋找電子郵件）請從路由端點開始，例如 treg.web.extract 或 treg.web.search，而不是選擇你記得名稱的特定供應商。在 treg.people.email.find 和 treg.people.phone.find 上，X-Treg-Route-Verify: true 也會在同一次呼叫中查驗找到的地址或電話號碼，並另行收費，同時說明查驗結果。

treg balance          # credit left, calls in flight, recent spend
treg topup            # add funds, or set up automatic top-ups

餘額不足時會收到 HTTP 402 error: insufficient_balance，其中包含 balance_micro、estimated_cost_micro 和 topup_url， 讓代理無須閱讀文字說明即可採取行動。

Enrich Arena 位於 /enrich-arena，不在儀表板內。比較各供應商的資料補充結果、費用與速度， 一鍵投票選出最佳答案，或查看依序執行的瀑布流程。符合功能需求的非同步供應商也會參與；Arena 會在內部處理提交與輪詢。瀏覽內容 公開；提交則須登入，且可計費的嘗試會使用團隊額度。請參閱 Arena 指南。

Web Arena 在 /web-arena 比較 Web Search、Web Fetch 和 Sitemap 供應商。 Battle 會使用相同輸入呼叫所選供應商；Waterfall 則依序嘗試。即時排行榜會彙整直接供應商呼叫的命中率與回應時間，以及經過檢查的 Web Arena 品質結果，並採用最近 30 天的滾動期間。啟用此功能後即可開啟相關頁面。請參閱 Web Arena 指南。

分享與使用自己的工具

最省心的方式 — 將 treg 指向專案，它就會判斷哪些內容可以分享：

treg scan     # read-only preview: the keys, skills & CLIs upload would register
treg upload   # register them (encrypted server-side); idempotent, --replace to update

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     # or straight from the .env

使用 — 適合代理的方式：建立真正的上游請求，並在前面加上代理前綴。 treg 會依主機解析工具、注入憑證，並忠實轉送其他所有內容 （你的 X-Treg-Token 會在上游收到請求前移除）：

Real request:   GET https://api.intercom.io/conversations?per_page=5
Through treg:   GET https://treg.to/call/https://api.intercom.io/conversations?per_page=5
                    header:  X-Treg-Token: <your 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、…） 並註冊；只有配方的目錄 CLI 技能（例如 stripe-cli）也會自動變成可執行項目。

使用 — treg run 會注入組織憑證後執行供應商 CLI，因此你永遠 不必持有金鑰或登入：

treg run stripe -- get /v1/balance
treg run gh -- pr list

--local（預設）會在你的電腦上執行。伺服器端 CLI 執行（--server）已全域停用。 treg runs 是稽核記錄。

3. 技能

分享 — 技能是一項完整能力（SKILL.md 配方 + 其密鑰 + 其工具）， 會一併註冊，讓整個團隊使用同一項技能，並集中維護：

treg upload skills --dir ~/.claude/skills --all   # register a folder of skills in one pass

使用 — 將任何已分享的技能載入代理；其 API 呼叫會透過 treg 並使用你的權杖， 因此金鑰會留在伺服器上，絕不會放進技能中：

treg skill install seo-blog-writer      # writes into ./.claude/skills/  (--all for the library)

手動註冊 — 當啟發式判斷無法辨識工具時

# multi-credential tool (e.g. google-ads: OAuth bearer + a developer-token header)
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}"

# one skill, step by step
treg skill init --dir ./my-skill          # drafts treg.json (guesses base_url, finds secrets)
treg skill add  --dir ./my-skill          # registers recipe + secrets + tool, atomically

# OAuth via the browser (mints the first token, treg holds it and auto-refreshes)
treg oauth connect gsc --client-secret client_secret.json \
  --scopes https://www.googleapis.com/auth/webmasters.readonly

所有指令的完整選項：USAGE.md。 CLI 及其安裝程式在使用 treg.to（沒有引數或憑證）時，會將匿名使用資料傳送至 PostHog。 使用 TREG_TELEMETRY=0 或 DO_NOT_TRACK=1 停用。 請參閱分析詳細資訊。

團隊

一個帳戶最多可擁有 10 個團隊。以成員身分加入其他團隊不計入此上限。

所有內容都以 org 為範圍：一個 token = 一個 (user, org) 成員資格，而每個密鑰、工具 和技能都屬於目前啟用的 org。角色：owner / admin / member / viewer。

treg org create "Acme"                        # make a team, become owner
treg org invite teammate@acme.com             # invite by email (pick role + tool access)
treg org join <code>                          # accept an invite (sign in as the invited email first)
treg org ls | use <slug> | members            # switch orgs, see the roster
treg org access <member> --tools a,b          # per-member tool access (admin+)

團隊擁有者可以在儀表板的 Team → SSO 分頁啟用企業 SSO。WorkOS 會連接公司的 身分識別提供者；擁有者可以邀請 IT 管理員完成設定。員工可以在任何登入對話方塊輸入工作電子郵件，或使用團隊的直接登入連結。treg 會保留其團隊角色和 API 金鑰。Directory Sync 方案會移除已停用員工的團隊存取權。請參閱 企業 SSO 設定。

深入了解

• 意見回饋： treg feedback submit friction "The pagination example is unclear." 分享問題或建議，請勿提供私人資訊。請參閱意見回饋說明。

• 審查： treg review CALL_ID useful 使用受邀目錄呼叫的結果後，為其評分；not_sure 即可。請勿提供私人資料，並繼續執行工作。

• USAGE.md — 完整的 treg CLI 參考資料。

• /llms.txt：代理程式的入門指南，採用 llms.txt 格式：介紹 treg、各類代理程式的設定、搜尋－讀取－呼叫循環及相關規則，其他內容請參閱 /skill.md，即操作指南。

• 儀表板位於 treg.to — 完整的 CRUD、引導式 教學課程（Help → Tutorial），以及可複製的代理程式設定說明。

• API — CLI 執行的所有操作都是純 HTTP；互動式 OpenAPI 文件位於 /docs。 Proxy 端點為 /call/{...}；所有端點都需要 X-Treg-Token 標頭。

---

第 2 部分 · 自行託管與開發

在本機執行

一個命令即可（需要 tmux + uv；會自行同步 venv）：

scripts/dev-local.sh up        # server on http://localhost:18790, dev-safe settings

這會在 tmux 中以熱重載模式執行伺服器，使用專屬的 sqlite DB（treg-dev.db），並啟用電子郵件 OTP 開發模式 （登入代碼會顯示在頁面上 — 不需要郵件寄送服務）。日常使用：

scripts/dev-local.sh cli login   # sandboxed CLI: never touches your real ~/.treg/config.json
scripts/dev-local.sh logs        # server output          · status / restart / down
scripts/dev-local.sh reset       # wipe the dev DB + CLI sandbox for a fresh start

或者直接執行伺服器，不使用 tmux：

bash scripts/build-dashboard.sh # Node 22.12+ and npm; build the Dashboard
uv sync                        # create the venv from uv.lock (pulls the server deps for dev)
uv run python -m treg upgrade  # prepare schema + run idempotent release tasks without serving
uv run python -m treg          # serve on 0.0.0.0:18790 (add --reload for dev)
uv run python -m treg keygen   # print a fresh Fernet key for TREG_SECRET_KEY

安裝以執行伺服器（非從原始碼執行）： 基礎套件只有 CLI。若要執行 registry，請安裝伺服器額外套件 — pip install "tools-registry[server]" — 其中包含 FastAPI、 資料庫驅動程式和加密功能。單獨安裝 pip install tools-registry 只會提供用來 與現有 registry 通訊的 treg 命令。

官方託管服務位於 treg.to。其正式環境拓撲和即時設定 維護於私人營運手冊。

設定

環境變數（前綴為 TREG_，從 .env 讀取）：

變數	預設值	用途
TREG_DATABASE_URL	sqlite+aiosqlite:///./treg.db	DB URL（開發環境使用 SQLite，正式環境使用 Postgres）
TREG_READ_DATABASE_URL	(空白)	選用的 SQLite / PostgreSQL 讀取資料來源；空白時重用主要資料來源。需要呼叫端選擇啟用；現有查詢不變。請參閱讀取資料來源設定。
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 登入（回呼 <public_url>/auth/github/callback）；空白時隱藏按鈕
TREG_GOOGLE_CLIENT_ID / _SECRET	(空白)	Google OAuth 登入（重新導向 <public_url>/auth/google/callback）；空白時隱藏按鈕
TREG_WORKOS_API_KEY / _CLIENT_ID / _WEBHOOK_SECRET	(空白)	WorkOS 企業 SSO；依照企業 SSO 設定所述設定回呼和已簽署的目錄 webhook
TREG_ENTERPRISE_SSO_BUNDLE_ONLY	true	預設只顯示 SSO + Directory Sync 方案；設為 false 即可提供兩種月繳方案。
TREG_ENTERPRISE_SSO_BUNDLE_PRICE_ID / TREG_ENTERPRISE_SSO_ONLY_PRICE_ID	(空白)	與 TREG_STRIPE_SECRET_KEY 位於同一帳戶的可重複使用月繳 Stripe Price ID；未設定或無法使用的 Price 會隱藏其方案。Stripe 的 Price 會提供顯示金額和 Checkout 收費金額。
TREG_ENTERPRISE_SSO_BUNDLE_MIN_PRICE_USD / TREG_ENTERPRISE_SSO_ONLY_MIN_PRICE_USD	0	每個月繳 Stripe Price 的選用整數美元最低價；低於此價格的項目會隱藏，並在 Checkout 時拒絕。
TREG_INSTAGRAM_CLIENT_ID / _SECRET	(空白)	用於直接 Instagram Login 的 Instagram App ID 和密鑰（重新導向 <public_url>/oauth/callback）
TREG_META_CLIENT_ID / _SECRET	(空白)	用於 Facebook Pages、Meta Ads，以及選用 Instagram page-tools 的 Meta 應用程式憑證
TREG_OAUTH_REVIEW_PENDING	instagram-login,page-messages	以逗號分隔的 registry 審查金鑰，其功能必須維持受限；託管環境的審查狀態由私人方式維護。
TREG_RESEND_API_KEY / TREG_EMAIL_FROM	(空白)	透過 Resend 傳送交易郵件（OTP 代碼 + 邀請）；寄件者必須是 Resend 已驗證的寄件者
TREG_BLOCKED_EMAIL_DOMAINS	(空白)	以逗號分隔的電子郵件網域，在所有註冊／登入入口及建立團隊時拒絕這些網域（包含子網域，不區分大小寫）。空白表示不封鎖任何網域 — 程式碼中沒有內建清單
TREG_CLIENT_IP_HEADER	(空白)	只有你的 edge 能設定的標頭，用作每個 IP 限制的用戶端位址（Cloudflare 後方的 cf-connecting-ip）
TREG_TRUSTED_PROXY_HOPS	1	未提供該標頭時：從 RIGHT 起算第 X-Forwarded-For 個項目（最近的 proxy 附加的項目）；用戶端直接連線時使用 0。第一個項目由用戶端提供，絕不信任
TREG_RATE_LIMIT_EXEMPT_IPS	(空白)	以逗號分隔的位址或 CIDR 區塊，豁免所有每 IP 限制（例如授權的安全測試、監控探測）；每電子郵件、每使用者及部署範圍的限制仍然適用。格式錯誤的項目會導致無法啟動
TREG_REQUIRED_EXTENSIONS	(空白)	以逗號分隔的政策擴充功能（treg.extensions 進入點），必須安裝，否則啟動會失敗。treg.to 以此方式執行私人濫用防範政策擴充功能；它只能施加限制（政策擴充功能）
TREG_TURNSTILE_SITE_KEY / _SECRET	(空白)	在所有電子郵件登入表單，以及新地址首次使用 GitHub/Google 登入時啟用 Cloudflare Turnstile；任一項為空白即停用。網站金鑰會提供於 /captcha.js，密鑰只會傳送至 siteverify
TREG_TURNSTILE_MODE	observe	observe 會記錄每次結果且不改變任何行為；enforce 會拒絕向缺少或無效 token 的請求傳送代碼、在 Cloudflare 無法回應時不提供註冊額度，並且只有通過檢查的新 GitHub/Google 使用者才能取得註冊額度
TREG_TURNSTILE_SOCIAL	true	false 會略過新地址首次使用 GitHub/Google 登入時的檢查，該使用者隨後會像未使用小工具一樣取得註冊額度；電子郵件入口不受影響
TREG_TURNSTILE_HOSTNAMES	(空白)	以逗號分隔的主機清單，token 必須在這些主機上完成驗證；空白表示使用 TREG_PUBLIC_URL 主機（及其已知別名）
TREG_ADMIN_TOKEN	(空白)	跨租戶 super-admin bearer；授權所有 /admin/* 端點。空白時停用環境變數路徑（只有 is_superadmin 使用者能存取 /admin）。請使用長且保密的值。
TREG_EMAIL_DEV_MODE	false	為 true 時，/auth/email/start 會在回應中傳回 OTP（不需要郵件寄送服務）— 僅限開發／本機環境，絕不可用於正式環境。
TREG_KV_URL	(空白)	共用的鍵值儲存區（Redis 通訊協定），供所有工作者共用計數器；目前用於每團隊的審查邀請額度。空白時使用程序內備援方案，適用於單一工作者

本機開發不需要 .env — 每項設定都有可用的預設值（臨時金鑰、sqlite）。

⚠️ 搬遷或重新部署前請先備份： Fernet 金鑰（TREG_SECRET_KEY）和 資料庫（正式環境使用 Postgres；本機 sqlite 執行時使用 treg.db）。若遺失 Fernet 金鑰，所有 已儲存的密鑰都將無法復原。

架構

/call 的請求流程： 解析工具（依 URL 主機 + 最長的 base_url 前綴，或依名稱）→ 解密其密鑰 → 套用每個繫結的注入器 → 串流至上游 → 以非同步方式寫入 稽核記錄。基礎架構 relay 會串流位元組，不執行商業邏輯。呼叫應用程式會緩衝需要結算或所有權證據的 回應，最多 8 MiB；較大的回應會傳回 502 且不收費，而非傳回遭截斷的成功回應。會內嵌媒體的端點（Gemini 圖片） 會宣告 spooled_response：其計量答案會改為讀取至暫存檔，依回報的用量結算，並完整轉送。無需本文 證據的授權免費最終下載會完整串流，自有金鑰和自有工具的回應亦同。

模組對照表（src/treg/）：

模組	角色
proxy.py	relay() — 用一個函式呈現完整產品：忠實的串流代理
injectors.py	驗證形狀的接縫：env、cli_auth、secret_file、oauth 將密鑰放入標頭／查詢參數
oauth.py	Token 新鮮度（single-flight refresh）+ 連線流程（同意 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 加密 + Token · 設定 · 非同步 DB · 延後寫入的稽核記錄器

4 種驗證形狀（每個綁定 injector）：env（純字串／API 金鑰）· secret_file（ JSON Token 檔案，擷取其中一個欄位）· oauth（JSON OAuth Token，可更新時自動更新）· cli_auth（從 CLI 的金鑰鏈擷取的資料）。

忠實轉送契約：代理只會變更三項內容，其餘一律原樣轉送：

1. 逐跳重新衍生的逐跳傳輸標頭，
2. treg 自有的控制與邊緣轉送標頭（x-treg-token、x-treg-org、 ngrok-skip-browser-warning、x-forwarded-*、via、…）以及 treg 的工作階段 Cookie — 全部移除， 絕不洩漏至上游，
3. 注入的憑證。

**OAuth，取得第一個 Token 的三種方式：**手動上傳（放入 token.json）· 自動更新（若 Token 帶有 refresh_token + 用戶端憑證，treg 會持續更新，無須重新 上傳）· 代管連線流程（treg oauth connect → 瀏覽器同意 → treg 自行擷取 Token）。

**健康檢查：**為工具提供選用的探測項目（{method, path, expect_status}）；定期執行 （手動觸發或透過 cron）會驗證每項憑證、更新 OAuth，並透過 webhook 通知任何故障項目的擁有者。

深入設計請見 docs/context/（各子系統的片段）。

測試

uv run --with pytest-xdist pytest -n auto -q   # daily local default (same shape as CI)
uv run --frozen python -m pytest -q            # serial: debugging one test, or order

涵蓋範圍：代理基本骨架、所有注入器形狀、每位使用者的驗證 + CRUD + 稽核、技能組合器、 URL 直通 + 忠實轉送、OAuth 更新 + 連線流程、健康檢查、treg run/shell、 上傳／掃描、組織 + 邀請、儀表板 API、CLI。

貢獻與文件

treg/
├── src/treg/            # the package (api, cli, proxy, injectors, oauth, health, convert, models, …)
│   └── web/             # dashboard, landing, tutorial, llms.txt, skill.md, install.sh
├── tests/               # pytest suite (CI + local default: pytest-xdist -n auto)
├── docs/
│   └── context/         # design fragments (codemap system) + generated index
├── USAGE.md             # full treg CLI reference
└── 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，而非重新散布我們的軟體。

固定的客戶讀取範圍

對於受限的客戶代理，treg org agent-new bot --pin customer=cust_A 會強制執行歸屬要求， 並將呼叫／執行歷史、封存結果及共享提供者的非同步擁有權限制在該固定項目範圍內。 外部或未標示歸屬的 ID 會回傳 404；未固定的操作人員仍可檢視整個組織的資料及共享 餘額。BYOK 帳戶存取權與公開媒體 URL 維持現有權限。多個固定項目、遷移及重播行為請參閱 多租戶契約。