用途:引导新用户从零完成 TrueFoundry 设置,包括账号创建、凭证配置和首次成功 API 调用。
适用场景:用户还没有 TrueFoundry 账号;用户说“get started”“set up”“register”“onboard”或“I'm new to TrueFoundry”;缺少 TFY_BASE_URL、TFY_API_KEY 且从未配置;用户询问如何创建账号或获取 API key。
不适用:已有凭证想查状态(用 status 技能)、管理已有 token(用 access-tokens 技能)、部署工作负载(需 TrueFoundry Enterprise 账号与已连接集群,见 https://truefoundry.com)、列出工作区(用 workspaces 技能)。
主要流程:
- 先检测当前状态,例如 echo "TFY_BASE_URL: ${TFY_BASE_URL:-(not set)}"、echo "TFY_HOST: ${TFY_HOST:-(not set)}"、echo "TFY_API_KEY: ${TFY_API_KEY:+(set)}${TFY_API_KEY:-(not set)}",并检查 .env。若已配置则跳到验证连接。
- 无账号时注册:tfy register;若未安装 CLI,用 uv run --from truefoundry tfy register。该命令为完全交互式,需用户手动输入,不要管道或自动化提示。向导包括账号信息(租户名 3-15 字符小写字母数字加连字符、工作邮箱、密码至少 8 字符并确认两次)、主要用途(ai gateway 或 llm ops)、确认条款、可能的人工验证(浏览器 CAPTCHA)、创建账号与邮箱验证。
- 配置凭证。环境变量:export TFY_BASE_URL="https://your-org.truefoundry.cloud"、export TFY_API_KEY="tfy-..."、export TFY_HOST="${TFY_BASE_URL}";或写 .env 文件。切勿把含 API key 的 .env 提交到 Git,确保加入 .gitignore。
- 可选安装 CLI:pip install 'truefoundry==0.5.0';使用 CLI 且设置了 TFY_API_KEY 时,需同时设置 TFY_HOST。
- 验证连接:用轻量 API 调用,如 scripts/tfy-api.sh GET '/api/svc/v1/workspaces?limit=1',确认 Base URL、API Key、连接均正常。
- 后续可转向 ai-gateway、guardrails、mcp-servers、workspaces、logs、status、access-tokens、docs 等技能;部署需企业账号与已连接集群。
限制与说明:注册需邮箱验证并可能需人工验证;API key 可从租户页面 Settings → Access → Personal Access Tokens 生成,参见 https://docs.truefoundry.com/docs/generate-api-key;401 通常表示 key 无效或过期;连接失败需检查 URL、网络与末尾斜杠;.env 必须位于当前工作目录,变量名精确匹配,且由 tfy-api.sh 解析,不要用 source .env;CLI 报 TFY_HOST 未设置时需补设。所有凭证不应被日志、回显或存储。