project-tooling

项目工具技能

用于项目基础设施管理的标准 CLI 工具。

---

必需的 CLI 工具

开始任何项目之前，请确认已安装并完成身份验证的工具：

1. GitHub CLI (gh)

# Verify installation
gh --version

# Verify authentication
gh auth status

# If not authenticated:
gh auth login

2. Vercel CLI

# Verify installation
vercel --version

# Verify authentication
vercel whoami

# If not authenticated:
vercel login

3. Supabase CLI

# Verify installation
supabase --version

# Verify authentication (check if linked to a project or logged in)
supabase projects list

# If not authenticated:
supabase login

4. Render CLI（可选——用于 Render 部署）

# Verify installation
render --version

# If using Render API instead:
# Ensure RENDER_API_KEY is set in environment

---

验证脚本

在项目初始化时运行此脚本，验证所有工具：

#!/bin/bash
# scripts/verify-tooling.sh

set -e

echo "Verifying project tooling..."

# GitHub CLI
if command -v gh &> /dev/null; then
  if gh auth status &> /dev/null; then
    echo "✓ GitHub CLI authenticated"
  else
    echo "✗ GitHub CLI not authenticated. Run: gh auth login"
    exit 1
  fi
else
  echo "✗ GitHub CLI not installed. Run: brew install gh"
  exit 1
fi

# Vercel CLI
if command -v vercel &> /dev/null; then
  if vercel whoami &> /dev/null; then
    echo "✓ Vercel CLI authenticated"
  else
    echo "✗ Vercel CLI not authenticated. Run: vercel login"
    exit 1
  fi
else
  echo "✗ Vercel CLI not installed. Run: npm i -g vercel"
  exit 1
fi

# Supabase CLI
if command -v supabase &> /dev/null; then
  if supabase projects list &> /dev/null; then
    echo "✓ Supabase CLI authenticated"
  else
    echo "✗ Supabase CLI not authenticated. Run: supabase login"
    exit 1
  fi
else
  echo "✗ Supabase CLI not installed. Run: brew install supabase/tap/supabase"
  exit 1
fi

echo ""
echo "All tools verified!"

---

GitHub 仓库设置

创建新仓库

# Create and push in one command
gh repo create <repo-name> --private --source=. --remote=origin --push

# Or public:
gh repo create <repo-name> --public --source=. --remote=origin --push

关联现有仓库

# If repo exists on GitHub but not linked locally
gh repo clone <owner>/<repo>

# Or add remote to existing local project
git remote add origin https://github.com/<owner>/<repo>.git
git push -u origin main

仓库设置

# Enable branch protection on main
gh api repos/{owner}/{repo}/branches/main/protection -X PUT \
  -F required_status_checks='{"strict":true,"contexts":["quality"]}' \
  -F enforce_admins=false \
  -F required_pull_request_reviews='{"required_approving_review_count":1}'

# Set default branch
gh repo edit --default-branch main

---

Vercel 部署

关联项目

# Link current directory to Vercel project
vercel link

# Or create new project
vercel

环境变量

# Add environment variable
vercel env add ANTHROPIC_API_KEY production

# Pull env vars to local .env
vercel env pull .env.local

部署

# Deploy to preview
vercel

# Deploy to production
vercel --prod

---

Supabase 设置

创建新项目

# Create project (interactive)
supabase projects create <project-name> --org-id <org-id>

# Link local to remote
supabase link --project-ref <project-ref>

本地开发

# Start local Supabase
supabase start

# Stop local Supabase
supabase stop

# Reset database (apply all migrations fresh)
supabase db reset

迁移

# Create new migration
supabase migration new <migration-name>

# Apply migrations to remote
supabase db push

# Pull remote schema to local
supabase db pull

生成类型

# Generate TypeScript types from schema
supabase gen types typescript --local > src/types/database.ts

# Or from remote
supabase gen types typescript --project-id <ref> > src/types/database.ts

---

Render 设置（基于 API）

环境

# Set API key
export RENDER_API_KEY=<your-api-key>

通过 API 执行的常见操作

# List services
curl -H "Authorization: Bearer $RENDER_API_KEY" \
  https://api.render.com/v1/services

# Trigger deploy
curl -X POST -H "Authorization: Bearer $RENDER_API_KEY" \
  https://api.render.com/v1/services/<service-id>/deploys

# Get deploy status
curl -H "Authorization: Bearer $RENDER_API_KEY" \
  https://api.render.com/v1/services/<service-id>/deploys/<deploy-id>

---

Package.json 脚本

添加这些常见操作脚本：

{
  "scripts": {
    "verify-tools": "./scripts/verify-tooling.sh",
    "deploy:preview": "vercel",
    "deploy:prod": "vercel --prod",
    "db:start": "supabase start",
    "db:stop": "supabase stop",
    "db:reset": "supabase db reset",
    "db:migrate": "supabase db push",
    "db:types": "supabase gen types typescript --local > src/types/database.ts"
  }
}

---

CI/CD 集成

使用 Vercel 的 GitHub Actions

# .github/workflows/deploy.yml
name: Deploy

on:
  push:
    branches: [main]
  pull_request:
    branches: [main]

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Deploy to Vercel
        uses: amondnet/vercel-action@v25
        with:
          vercel-token: ${{ secrets.VERCEL_TOKEN }}
          vercel-org-id: ${{ secrets.VERCEL_ORG_ID }}
          vercel-project-id: ${{ secrets.VERCEL_PROJECT_ID }}
          vercel-args: ${{ github.ref == 'refs/heads/main' && '--prod' || '' }}

使用 Supabase 的 GitHub Actions

# .github/workflows/migrate.yml
name: Migrate Database

on:
  push:
    branches: [main]
    paths:
      - 'supabase/migrations/**'

jobs:
  migrate:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Setup Supabase CLI
        uses: supabase/setup-cli@v1
        with:
          version: latest

      - name: Push migrations
        run: supabase db push
        env:
          SUPABASE_ACCESS_TOKEN: ${{ secrets.SUPABASE_ACCESS_TOKEN }}
          SUPABASE_DB_PASSWORD: ${{ secrets.SUPABASE_DB_PASSWORD }}

---

部署平台设置

必需：初始化项目时，始终根据技术栈创建部署平台连接待办事项。

按技术栈选择平台

技术栈	默认平台	所需操作
Next.js / Node.js	Vercel	将 Git 仓库连接到 Vercel
Python (FastAPI, Flask)	Render	将 Git 仓库连接到 Render，并获取 API 密钥
静态网站	Vercel 或 Cloudflare Pages	连接 Git 仓库

Vercel：连接 Git 仓库

当 Vercel 是部署平台时，创建此待办事项：

TODO: Connect Git repository to Vercel for automatic deployments

步骤：

# Option 1: Via CLI
vercel link
vercel git connect

# Option 2: Via Dashboard (recommended for first setup)
# 1. Go to vercel.com/new
# 2. Import Git repository
# 3. Configure project settings
# 4. Deploy

连接后：

• 推送到 main → 部署到生产环境
• 推送到其他分支 → 预览部署
• PR 会自动生成部署预览

Render：连接 Git 仓库（Python）

当 Render 是 Python 项目的部署平台时：

步骤 1：向用户索取 Render API 密钥

Before proceeding, please provide your Render API key.
Get it from: https://dashboard.render.com/u/settings/api-keys

Store it securely - we'll add it to your environment.

步骤 2：创建待办事项

TODO: Get Render API key from user
TODO: Connect Git repository to Render
TODO: Configure Render service (web service or background worker)
TODO: Set environment variables on Render

步骤 3：通过控制面板连接（推荐）

# 1. Go to dashboard.render.com/create
# 2. Select "Web Service" for APIs, "Background Worker" for async
# 3. Connect your GitHub/GitLab repository
# 4. Configure:
#    - Name: <project-name>
#    - Runtime: Python 3
#    - Build Command: pip install -r requirements.txt
#    - Start Command: uvicorn main:app --host 0.0.0.0 --port $PORT

步骤 4：存储 API 密钥以供 CI/CD 使用

# Add to GitHub secrets for CI/CD
gh secret set RENDER_API_KEY

# Or add to local env
echo "RENDER_API_KEY=<your-key>" >> .env

步骤 5：配置 render.yaml（可选——基础设施即代码）

# render.yaml
services:
  - type: web
    name: <project-name>-api
    runtime: python
    buildCommand: pip install -r requirements.txt
    startCommand: uvicorn main:app --host 0.0.0.0 --port $PORT
    envVars:
      - key: PYTHON_VERSION
        value: "3.11"
      - key: DATABASE_URL
        fromDatabase:
          name: <project-name>-db
          property: connectionString

databases:
  - name: <project-name>-db
    plan: free

部署检查清单模板

设置部署时，将以下内容添加到项目待办事项中：

## Deployment Setup
- [ ] Create Git repository (gh repo create)
- [ ] Choose deployment platform (Vercel/Render/other)
- [ ] Connect Git to deployment platform
- [ ] Configure environment variables
- [ ] Set up CI/CD workflow
- [ ] Verify preview deployments work
- [ ] Configure production domain

---

工具反模式

• ❌ 将密钥硬编码——使用 CLI 环境变量管理或 GitHub 密钥
• ❌ 手动部署——通过 CI/CD 自动化
• ❌ 跳过本地 Supabase——始终先在本地开发
• ❌ 直接更改生产数据库——使用迁移
• ❌ 未设置分支保护——要求 PR 审查和 CI 检查
• ❌ 缺少环境隔离——将开发、预发布和生产环境分开