接入指南

配置步骤

1. 1
   获取 API Key

   登录 RobotX 控制台，前往 设置 → API Key 页面，创建或复制您的 API Key。

2. 2
   配置 CI Secrets

   在 GitHub 或 Gitee 的 CI Secret 配置中，添加 ROBOTX_BASE_URL 与 ROBOTX_API_KEY。

3. 3
   GitHub: 添加 Workflow 文件

   在仓库根目录创建 .github/workflows/deploy.yml：

   yaml

   name: Deploy to RobotX
   on:
     push:
       branches: [main]
   
   jobs:
     deploy:
       runs-on: ubuntu-latest
       steps:
         - uses: actions/checkout@v4
         - uses: actions/setup-node@v4
           with:
             node-version: 20
   
         - name: Deploy to RobotX
           id: robotx
           uses: robotx-dev/cli@v0.3
           with:
             base-url: ${{ secrets.ROBOTX_BASE_URL }}
             api-key: ${{ secrets.ROBOTX_API_KEY }}
             project-path: .
             project-name: your-project
             local-build: "true"
             publish: "false"
             source-ref: "branch:${{ github.ref_name }}@${{ github.sha }}"
             extra-args: >-
               --install-command "npm ci"
               --build-command "npm run build"
               --output-dir dist
   
         - name: Print result
           run: |
             echo "project_id=${{ steps.robotx.outputs.project_id }}"
             echo "build_id=${{ steps.robotx.outputs.build_id }}"
             echo "status=${{ steps.robotx.outputs.status }}"

4. 4
   Gitee: 添加流水线 Shell 步骤

   在 Gitee CI 的部署步骤中执行以下命令：

   bash

   # 在 Gitee 流水线中执行（Shell 步骤）
   curl -fsSL https://raw.githubusercontent.com/robotx-dev/cli/main/scripts/install.sh | bash
   export PATH="$HOME/.local/bin:$PATH"
   
   robotx deploy . --name your-project   --base-url "$ROBOTX_BASE_URL"   --api-key "$ROBOTX_API_KEY"   --install-command "npm ci"   --build-command "npm run build"   --output-dir dist   --source-ref "branch:$GITEE_BRANCH@$GITEE_COMMIT"   --output json

5. 5
   推送并发布

   将配置提交并推送到主分支后，CI 会在 runner 本地完成安装、构建、产物上传和发布。

安装 Skill

# 在 Codex 对话中安装 robotx skill
$skill-installer install https://github.com/robotx-dev/cli/tree/main

# 若环境中尚未安装 robotx CLI，可直接安装二进制（无需 Go）
curl -fsSL https://raw.githubusercontent.com/robotx-dev/cli/main/scripts/install.sh | bash

将项目 SKILL.md 添加到 Agent

# 项目级（推荐，随仓库共享）
mkdir -p .agents/skills/robotx
cp ./SKILL.md .agents/skills/robotx/SKILL.md

# 旧版 Codex 兼容路径（可选）
mkdir -p ~/.codex/skills/robotx
cp ./SKILL.md ~/.codex/skills/robotx/SKILL.md

# 项目级（推荐，随仓库共享）
mkdir -p .claude/skills/robotx
cp ./SKILL.md .claude/skills/robotx/SKILL.md

# 个人级（仅本机用户生效）
mkdir -p ~/.claude/skills/robotx
cp ./SKILL.md ~/.claude/skills/robotx/SKILL.md

使用步骤

1. 1
   安装 Skill 与 CLI

   安装 robotx skill，并将项目的 SKILL.md 放入 Codex/Claude 对应 skill 目录。

2. 2
   配置凭据并做鉴权预检

   设置 ROBOTX_BASE_URL 与 ROBOTX_API_KEY，先执行 robotx projects --limit 1 --output json 验证凭据。若返回 401/403，可执行 robotx login --base-url https://robotx.xin 后重试。

3. 3
   构建并发布到 RobotX

   执行 deploy 命令，让 CLI 在本地工作区构建并上传产物，建议全程使用 JSON 输出：

   bash

   # 1. 配置 RobotX 凭据
   export ROBOTX_BASE_URL=https://api.robotx.xin
   export ROBOTX_API_KEY=<your-api-key>
   
   # 2. 鉴权预检（推荐）
   robotx projects --limit 1 --output json
   
   # 3. 部署（CLI 会在本地工作区构建并上传产物）
   robotx deploy . --name your-project   --install-command "npm ci"   --build-command "npm run build"   --output-dir dist   --output json
   
   # 4. 可选：查看项目或构建状态
   robotx status --project-id proj_123 --output json
   robotx status --build-id build_456 --output json

操作步骤

1. 1
   构建项目

   在本地执行构建命令，生成产物目录（通常为 dist/ 或 build/）。

2. 2
   打包为 zip

   将构建产物目录打包为 .zip 文件。确保 zip 根目录包含 index.html。

   bash

   # 示例：打包 dist 目录
   cd dist && zip -r ../my-project.zip . && cd ..

3. 3
   上传并发布

   前往 创建项目 页面，输入项目名称，选择「手动上传」后选择 zip 文件。系统将自动扫描、配置并部署。