treg onboarding 演示团队机制解析：首次运行如何自动配置-平芜编程栈

treg onboarding 演示团队机制解析：首次运行如何自动配置

【免费下载链接】tregOpenRouter for agent tools. Join community here: https://discord.gg/6mQYYfFMAn项目地址: https://gitcode.com/GitHub_Trending/treg/treg

treg 是一个开源的「OpenRouter for agent tools」——用一把统一钥匙调用 2000+ 个数据与营销类 API 的工具网关，按调用计费。本文解析 treg 的 onboarding 演示团队机制：新用户首次登录时，系统如何自动配置好一个「演示团队」——内置 3 位不同角色的假队友、一把开箱即用的 echo 工具，让你在没有任何配置的情况下，一分钟体验到 treg「零密钥调用」的核心价值。

一键生成演示团队：/onboard/demo 端点

整个过程由一个 HTTP 端点驱动：POST /onboard/demo。它的核心逻辑在 src/treg/routers/onboard.py 中定义，真正的种子工作由 src/treg/application/onboard/demo.py 里的provision()完成，按顺序做六件事：

幂等检查：如果该用户已经拥有一个 demo 团队，直接复用，不重复创建（重复触发 onboarding 是安全的）；
创建真实团队：新建一个demo=True的 Org，默认名为 "Acme Design"，你可以自定义队名；
签发默认凭证：为 owner 成员确保一把默认的调用密钥；
注入假队友：写入 Ada（admin）、Ben（member）、Cora（viewer）三个用户行，完整展示 treg 的角色阶梯；
注册 echo 工具：指向 postman-echo.com，密钥以Bearer {secret}形式在服务端注入——调用方永远不持有密钥，这正是 treg 最核心的「aha 时刻」；
补上示例活动：写入 3 条 CallRecord，让 Activity 审计页不再是空白。

完成后用户被标记onboarded=True，onboarding 提示将不再自动出现。

种子数据一览

种子内容	作用
3 个假队友（admin / member / viewer）	直观展示 owner > admin > member > viewer 的完整权限体系
echo 工具 + echo-key 密钥	无需任何配置即可发起第一次成功调用
3 条示例 CallRecord	Activity 审计页开箱即有内容

一个巧妙的设计细节：假队友的邮箱全部位于demo.treg.local域名下（见 demo.py 第 26-43 行），而登录接口对该域名的邮箱一律拒绝登录——演示队友只能「被看见」，永远无法真的登录系统。

引导式流程：手动建队时的自动托底

除了「一键全托管」路线，treg 还保留了一条引导式路线：用户亲手建队、手动发邀请，treg 只在关键节点补位。

前端逻辑在 frontend/src/state/onboarding.js 的maybeOnboard()中：检测到一个尚未加入任何团队的全新用户时，弹出欢迎面板请他给团队起名字，还会从邮箱域名智能推荐队名（比如sam@acme.dev会建议 "Acme"）。

两个「托底」端点让体验闭环：

POST /onboard/seed-tool：把可用的 echo 工具预注入用户自己创建的团队，让后续「无密钥调用」演示零摩擦通过；
POST /onboard/accept-teammate：用户在引导中邀请了演示邮箱后，系统自动接受该邀请，队友立刻出现在花名册里——先体验「邀请」，再看见「闭环」。该端点仅限 admin 角色、且只接受演示域名的邮箱，普通邀请不受影响。

如果用户完全想跳过演示，POST /onboard/skip只做一件事：把onboarded标记置为 True，此后 onboarding 永不再自动弹出。

一键清理：/onboard/reset 不留痕迹

演示团队并非「粘上就撕不掉」。POST /onboard/reset（demo.py 的 reset()）执行彻底的清理：

级联删除该用户名下的所有 demo 团队；
把被邀请进真实团队的演示队友从花名册中移除；
清扫已无任何归属的孤儿演示用户（并先解除外键约束的拒绝规则，保证删除在 Postgres 下顺利执行）。

onboarding 用完即清，不留任何「演示垃圾」。

落地页沙箱：不登录也能开一个演示团队

treg 还有一层更激进的演示机制：落地页沙箱。POST /demo/sandbox端点（routers/onboard.py 第 107-117 行）为匿名访客铸造一个一次性团队——包含 starter 密钥、starter 端点和一个成员 token，浏览器和访客终端都能直接用，全程无需注册。

安全边界设计得很克制：

调用从不触网：沙箱内的调用走合成响应，而非真实转发；
按 IP 限流：数据库限流器（ratestore）限制每小时最多铸造 12 次；
TTL 过期后由垃圾回收器自动清场；
访客甚至能把自己在沙箱里搭好的配置导出成一个可分享的 skill。

沙箱铸造成功后，响应头里的authorization: Bearer …让访客直观看到：密钥是注册表在调用时注入的，调用方全程碰不到它。

关键文件导航

想深入源码？这几个入口按阅读顺序排列：

演示团队种子逻辑：src/treg/application/onboard/demo.py
onboarding 用例与事务边界：src/treg/application/onboard/init.py
落地页沙箱铸造与 GC：src/treg/application/onboard/sandbox.py
HTTP 端点路由（demo / skip / reset / seed-tool / accept-teammate）：src/treg/routers/onboard.py
前端首次运行引导状态机：frontend/src/state/onboarding.js
完整的仪表盘分步图文教程（含全套截图）：docs/DASHBOARD-TOUR.md
CLI 侧 onboarding 说明：docs/ONBOARDING.md
相关测试：tests/test_onboard.py