buddy

Buddy Platform

通过 bdy CLI 按需使用云基础设施。运行 bdy <command> --help 查看标志详情。

身份验证

如果任何命令返回 Token not provided 或 Not logged in：请用户在单独的终端中运行 bdy login（AI 无法执行交互式 OAuth）。运行 bdy whoami 可检查用户是否已登录。

沙箱（bdy sandbox|sb）

用于动态应用（服务器、数据库、后台进程）的云环境。

重要规则

• 沙箱必须位于项目中。运行 sandbox create 前，检查 bdy whoami 中的项目上下文和 BUDDY_PROJECT 环境变量。如果两者都未设置，请使用 AskUserQuestion 询问用户是否要创建新项目，然后运行 bdy proj link -p <project> 将其关联。
• 应用必须绑定到 0.0.0.0（而非 127.0.0.1），端点才能正常工作。
• 复制项目时始终使用 --ignore "node_modules/**" ".git/**" — 应改为在沙箱中安装依赖。
• Ubuntu 24.04 预装：Node.js 24、Python 3.12、Go 1.25、Git、curl、jq、ripgrep

工作流

1. 创建：bdy sandbox create -i <name> --resources 2x4 --wait-for-running
2. 复制文件：bdy sandbox cp ./src <name>:/app --ignore "node_modules/**" ".git/**" > /dev/null
3. 安装依赖：bdy sandbox exec command <name> "cd /app && npm install" --wait
4. 通过 app add 启动应用（不要使用 exec — 这样可以查看状态、日志并重启）： bdy sandbox app add <name> "cd /app && npm start -- -H 0.0.0.0"
5. 检查应用：bdy sandbox app status <name> <app-id> 和 bdy sandbox app logs <name> <app-id>
6. 添加端点：bdy sandbox endpoint add <name> -n web -e <port>
7. 向用户展示公共端点 URL，然后通过 AskUserQuestion 询问是否要绑定自定义域名。选项：注册 Buddy 提供的免费域名、购买新域名，或重复使用其工作区中已有的域名。选项标签要简短 — 不要在其中填写 CLI 命令。用户选择后，运行相应的 bdy domain 命令，并通过 bdy distro route create 配置路由。

提示

• 使用 app add 启动服务 — 不要使用 exec command。应用由 systemd 服务管理，可查看状态和日志，也可停止、启动和重启。
• bdy sandbox app list <name> 会显示正在运行的应用及其 ID。
• 在本地编写配置文件，然后使用 sandbox cp — 避免在 exec 中处理 heredoc 转义问题。
• 使用 sandbox snapshot 保存或恢复沙箱状态。
• 使用 bdy distro route create 配置自定义域名路由和 CDN。

构件（bdy artifact|art）

构件分为两种类型：

• BUCKET（默认）— 带版本管理且具有公共 URL 的文件托管。适用于静态站点、构建产物和可下载文件。
• CONTAINER — Docker 镜像仓库。适用于 Docker 镜像。请用户在单独的终端中运行 bdy artifact docker login（AI 无法处理交互式凭据），然后使用标准 docker 命令推送或拉取。

BUCKET 工作流

1. 如有需要，先构建：npm run build
2. 创建构件：bdy artifact create <name>（默认类型为 BUCKET）
   • 身份验证在创建时设置，而非按版本设置 — 先询问用户选择哪种身份验证方式（HTTP Basic -a / Buddy -b / 无）
3. 发布并指定版本：bdy artifact publish <name>@1.0.0 ./dist
   • 不指定版本：bdy artifact publish <name> ./dist → 创建 latest 版本
4. 获取 URL：bdy artifact version get <name> <version>
5. 向用户展示已发布的 URL，然后通过 AskUserQuestion 询问是否要绑定自定义域名。选项：注册 Buddy 提供的免费域名、购买新域名，或重复使用其工作区中已有的域名。选项标签要简短 — 不要在其中填写 CLI 命令。用户选择后，运行相应的 bdy domain 命令，并通过 bdy distro route create 配置路由。

重要规则

• 主 HTML 文件必须命名为 index.html（否则会显示目录列表）。
• 使用 @ 或 : 作为版本分隔符：[email protected] 或 my-site:1.0.0
• 使用 --force 覆盖现有版本。
• 使用 --create 一步创建构件并发布：bdy artifact publish -c <name>@1.0.0 ./dist

提示

• 使用 bdy distro route create 配置自定义域名路由和 CDN

隧道（bdy tunnel）

通过安全隧道将本地服务暴露到互联网。

关键规则（必须遵守）

• 运行隧道命令时，始终使用 run_in_background: true——这些命令会阻塞执行
• 创建 HTTP 隧道前，始终通过 AskUserQuestion 询问是否需要身份验证：
  • HTTP Basic Auth → -a
  • Buddy Auth → --buddy
  • 不需要身份验证 → 不添加标志
• 对于 Docker：确认应用绑定到 0.0.0.0

提示

• 保存隧道配置：bdy tunnel config add http <name> localhost:<port>
• 启动已保存的隧道：bdy tunnel start <name>

域名（bdy domain）

搜索、购买和管理自定义域名。

bdy domain search <query>     # Search available domains
bdy domain buy <name>         # Purchase a domain
bdy domain list               # List owned domains

运行 bdy domain --help 查看完整选项（TLD 筛选、排序等）。

流量分发（bdy distro）

通过自定义规则和域名在各项服务之间分配流量。

路由类型

• PROXY / PROXY_NO_CACHE — 将流量反向代理到后端。URL 显示 distro 域名，真实路径（/foo/bar）可见并会被转发。适用于在真实应用前部署 CDN/边缘节点。
• REDIRECT — HTTP 3xx 重定向到另一个 URL。浏览器会跳转离开；最终 URL 显示目标域名。
• CLOAKING — distro 域名提供一个嵌入目标页面的全页 iframe。无论 iframe 内如何导航，地址栏始终显示 distro 域名，因此真实路径/子页面永远不可见

bdy distro create -i <name>                          # Create distribution
bdy distro route create <name> -t PROXY -d <domain>  # Add route
bdy distro route list <name>                          # List routes

运行 bdy distro --help 查看完整选项。

流水线（bdy pipeline|pip）

用于构建、测试和部署自动化的 CI/CD 流水线。

bdy pipeline list                          # List pipelines
bdy pipeline run start <identifier>        # Run a pipeline
bdy pipeline run status <identifier> <id>  # Check run status
bdy pipeline run logs <identifier> <id> <action-id>  # View logs

运行 bdy pipeline --help 查看完整选项（变量、调度、YAML 配置等）。