项目工具技能

加载基础.md

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

---

必需的CLI工具

在开始任何项目之前，请验证这些工具已安装并经过身份验证：

1. GitHub CLI (gh)

# 验证安装
gh --version

# 验证身份验证
gh auth status

# 如果未认证：
gh auth login

2. Vercel CLI

# 验证安装
vercel --version

# 验证身份验证
vercel whoami

# 如果未认证：
vercel login

3. Supabase CLI

# 验证安装
supabase --version

# 验证身份验证（检查是否链接到项目或已登录）
supabase projects list

# 如果未认证：
supabase login

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

# 验证安装
render --version

# 如果使用Render API代替：
# 确保RENDER_API_KEY在环境设置中

---

验证脚本

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

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

set -e

echo "验证项目工具..."

# GitHub CLI
if command -v gh &> /dev/null; then
  if gh auth status &> /dev/null; then
    echo "✓ GitHub CLI已认证"
  else
    echo "✗ GitHub CLI未认证。运行：gh auth login"
    exit 1
  fi
else
  echo "✗ GitHub CLI未安装。运行：brew install gh"
  exit 1
fi

# Vercel CLI
if command -v vercel &> /dev/null; then
  if vercel whoami &> /dev/null; then
    echo "✓ Vercel CLI已认证"
  else
    echo "✗ Vercel CLI未认证。运行：vercel login"
    exit 1
  fi
else
  echo "✗ Vercel CLI未安装。运行：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已认证"
  else
    echo "✗ Supabase CLI未认证。运行：supabase login"
    exit 1
  fi
else
  echo "✗ Supabase CLI未安装。运行：brew install supabase/tap/supabase"
  exit 1
fi

echo ""
echo "所有工具已验证！"

---

GitHub仓库设置

创建新仓库

# 一次性创建并推送
gh repo create <仓库名> --private --source=. --remote=origin --push

# 或公开：
gh repo create <仓库名> --public --source=. --remote=origin --push

连接现有仓库

# 如果仓库已存在于GitHub但未在本地链接
gh repo clone <所有者>/<仓库>

# 或向现有本地项目添加远程仓库
git remote add origin https://github.com/<所有者>/<仓库>.git
git push -u origin main

仓库设置

# 在main上启用分支保护
gh api repos/{所有者}/{仓库}/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}'

# 设置默认分支
gh repo edit --default-branch main

---

Vercel部署

链接项目

# 将当前目录链接到Vercel项目
vercel link

# 或创建新项目
vercel

环境变量

# 添加环境变量
vercel env add ANTHROPIC_API_KEY production

# 将环境变量拉取到本地.env
vercel env pull .env.local

部署

# 部署到预览
vercel

# 部署到生产
vercel --prod

---

Supabase设置

创建新项目

# 创建项目（交互式）
supabase projects create <项目名> --org-id <组织ID>

# 将本地链接到远程
supabase link --project-ref <项目引用>

本地开发

# 启动本地Supabase
supabase start

# 停止本地Supabase
supabase stop

# 重置数据库（重新应用所有迁移）
supabase db reset

迁移

# 创建新迁移
supabase migration new <迁移名>

# 将迁移应用到远程
supabase db push

# 从远程拉取架构到本地
supabase db pull

生成类型

# 从架构生成TypeScript类型
supabase gen types typescript --local > src/types/database.ts

# 或从远程
supabase gen types typescript --project-id <引用> > src/types/database.ts

---

Render设置（基于API）

环境

# 设置API密钥
export RENDER_API_KEY=<你的API密钥>

通过API进行常见操作

# 列出服务
curl -H "Authorization: Bearer $RENDER_API_KEY" \
  https://api.render.com/v1/services

# 触发部署
curl -X POST -H "Authorization: Bearer $RENDER_API_KEY" \
  https://api.render.com/v1/services/<服务ID>/deploys

# 获取部署状态
curl -H "Authorization: Bearer $RENDER_API_KEY" \
  https://api.render.com/v1/services/<服务ID>/deploys/<部署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集成

GitHub Actions与Vercel

# .github/workflows/deploy.yml
name: 部署

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

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

      - name: 部署到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' || '' }}

GitHub Actions与Supabase

# .github/workflows/migrate.yml
name: 数据库迁移

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

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

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

      - name: 推送迁移
        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: 将Git仓库连接到Vercel以实现自动部署

步骤：

# 选项1：通过CLI
vercel link
vercel git connect

# 选项2：通过仪表板（首次设置推荐）
# 1. 访问vercel.com/new
# 2. 导入Git仓库
# 3. 配置项目设置
# 4. 部署

连接后：

• 推送到main → 生产部署
• 推送到其他分支 → 预览部署
• PR自动获得部署预览

Render：连接Git仓库（Python）

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

步骤1：向用户请求Render API密钥

在继续之前，请提供您的Render API密钥。
从这里获取：https://dashboard.render.com/u/settings/api-keys

安全存储 - 我们将把它添加到您的环境。

步骤2：创建待办事项

TODO: 从用户那里获取Render API密钥
TODO: 将Git仓库连接到Render
TODO: 配置Render服务（Web服务或后台工作器）
TODO: 在Render上设置环境变量

步骤3：通过仪表板连接（推荐）

# 1. 访问dashboard.render.com/create
# 2. 选择"Web Service"用于APIs，"Background Worker"用于异步
# 3. 连接您的GitHub/GitLab仓库
# 4. 配置：
#    - 名称：<项目名>
#    - 运行时：Python 3
#    - 构建命令：pip install -r requirements.txt
#    - 启动命令：uvicorn main:app --host 0.0.0.0 --port $PORT

步骤4：存储CI/CD的API密钥

# 添加到GitHub secrets用于CI/CD
gh secret set RENDER_API_KEY

# 或添加到本地环境
echo "RENDER_API_KEY=<你的密钥>" >> .env

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

# render.yaml
services:
  - type: web
    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: <项目名>-db
          property: connectionString

databases:
  - name: <项目名>-db
    plan: free

部署检查表模板

在设置部署时添加到项目待办事项：

## 部署设置
- [ ] 创建Git仓库（gh repo create）
- [ ] 选择部署平台（Vercel/Render/其他）
- [ ] 将Git连接到部署平台
- [ ] 配置环境变量
- [ ] 设置CI/CD工作流
- [ ] 验证预览部署工作
- [ ] 配置生产域

---

工具反模式

• ❌ 硬编码密钥 - 使用CLI环境管理或GitHub secrets
• ❌ 手动部署 - 通过CI/CD自动化
• ❌ 跳过本地Supabase - 始终首先本地开发
• ❌ 直接生产数据库更改 - 使用迁移
• ❌ 无分支保护 - 需要PR审查和CI检查
• ❌ 缺少环境分离 - 保持开发/暂存/生产分开