project-tooling

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Project Tooling Skill

项目工具技能

Load with: base.md

Standard CLI tools for project infrastructure management.

加载文件：base.md

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

Required CLI Tools

必备CLI工具

Before starting any project, verify these tools are installed and authenticated:

启动任何项目前，请确认以下工具已安装并完成身份验证：

1. GitHub CLI (gh)

bash

undefined

bash

undefined

Verify installation

验证安装

gh --version

Verify authentication

验证身份验证状态

gh auth status

If not authenticated:

若未完成身份验证：

gh auth login

undefined

gh auth login

undefined

2. Vercel CLI

bash

undefined

bash

undefined

Verify installation

验证安装

vercel --version

Verify authentication

验证身份验证状态

vercel whoami

If not authenticated:

若未完成身份验证：

vercel login

undefined

vercel login

undefined

3. Supabase CLI

bash

undefined

bash

undefined

Verify installation

验证安装

supabase --version

Verify authentication (check if linked to a project or logged in)

验证身份验证状态（检查是否关联项目或已登录）

supabase projects list

If not authenticated:

若未完成身份验证：

supabase login

undefined

supabase login

undefined

4. Render CLI (optional - for Render deployments)

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

bash

undefined

bash

undefined

Verify installation

验证安装

render --version

If using Render API instead:

若使用Render API替代：

Ensure RENDER_API_KEY is set in environment

确保环境中已设置RENDER_API_KEY

---

---

Validation Script

验证脚本

Run this at project initialization to verify all tools:

bash

#!/bin/bash

项目初始化时运行以下脚本，验证所有工具状态：

bash

#!/bin/bash

scripts/verify-tooling.sh

set -e

echo "Verifying project tooling..."

set -e

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

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

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 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

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 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!"

---

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 Repository Setup

GitHub仓库配置

Create New Repository

创建新仓库

bash

undefined

bash

undefined

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

undefined

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

undefined

Connect Existing Repository

关联现有仓库

bash

undefined

bash

undefined

If repo exists on GitHub but not linked locally

若仓库已在GitHub上，但本地未关联

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

undefined

git remote add origin https://github.com/<owner>/<repo>.git git push -u origin main

undefined

Repository Settings

仓库设置

bash

undefined

bash

undefined

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

---

gh repo edit --default-branch main

---

Vercel Deployment

Vercel部署

Link Project

关联项目

bash

undefined

bash

undefined

Link current directory to Vercel project

将当前目录关联到Vercel项目

vercel link

Or create new project

或创建新项目

vercel

undefined

vercel

undefined

Environment Variables

环境变量

bash

undefined

bash

undefined

Add environment variable

添加环境变量

vercel env add ANTHROPIC_API_KEY production

Pull env vars to local .env

将环境变量拉取到本地.env文件

vercel env pull .env.local

undefined

vercel env pull .env.local

undefined

Deploy

部署

bash

undefined

bash

undefined

Deploy to preview

部署到预览环境

vercel

Deploy to production

部署到生产环境

vercel --prod

---

vercel --prod

---

Supabase Setup

Supabase配置

Create New Project

创建新项目

bash

undefined

bash

undefined

Create project (interactive)

创建项目（交互式）

supabase projects create <project-name> --org-id <org-id>

Link local to remote

关联本地与远程项目

supabase link --project-ref <project-ref>

undefined

supabase link --project-ref <project-ref>

undefined

Local Development

本地开发

bash

undefined

bash

undefined

Start local Supabase

启动本地Supabase

supabase start

Stop local Supabase

停止本地Supabase

supabase stop

Reset database (apply all migrations fresh)

重置数据库（重新应用所有迁移）

supabase db reset

undefined

supabase db reset

undefined

Migrations

数据库迁移

bash

undefined

bash

undefined

Create new migration

创建新迁移文件

supabase migration new <migration-name>

Apply migrations to remote

将迁移应用到远程数据库

supabase db push

Pull remote schema to local

将远程架构拉取到本地

supabase db pull

undefined

supabase db pull

undefined

Generate Types

生成类型定义

bash

undefined

bash

undefined

Generate TypeScript types from schema

从架构生成TypeScript类型

supabase gen types typescript --local > src/types/database.ts

Or from remote

或从远程生成

supabase gen types typescript --project-id <ref> > src/types/database.ts

---

supabase gen types typescript --project-id <ref> > src/types/database.ts

---

Render Setup (API-based)

Render配置（基于API）

Environment

环境设置

bash

undefined

bash

undefined

Set API key

设置API密钥

export RENDER_API_KEY=<your-api-key>

undefined

export RENDER_API_KEY=<your-api-key>

undefined

Common Operations via API

基于API的常见操作

bash

undefined

bash

undefined

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>

---

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

---

Package.json Scripts

Package.json脚本

Add these scripts for common operations:

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"
  }
}

添加以下脚本用于常见操作：

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 Integration

CI/CD集成

GitHub Actions with Vercel

Vercel与GitHub Actions集成

yaml

undefined

yaml

undefined

.github/workflows/deploy.yml

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' || '' }}

undefined

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' || '' }}

undefined

GitHub Actions with Supabase

Supabase与GitHub Actions集成

yaml

undefined

yaml

undefined

.github/workflows/migrate.yml

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 }}

---

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 }}

---

Deployment Platform Setup

部署平台配置

REQUIRED: When initializing a project, always create todos for deployment platform connection based on the stack.

必填项：初始化项目时，务必根据技术栈创建部署平台关联的待办事项。

Platform Selection by Stack

按技术栈选择平台

Stack	Default Platform	Action Required
Next.js / Node.js	Vercel	Connect Git repo to Vercel
Python (FastAPI, Flask)	Render	Connect Git repo to Render, get API key
Static sites	Vercel or Cloudflare Pages	Connect Git repo

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

Vercel: Connect Git Repository

Vercel：关联Git仓库

When Vercel is the deployment platform, create this todo:

TODO: Connect Git repository to Vercel for automatic deployments

Steps:

bash

undefined

当Vercel作为部署平台时，创建以下待办事项：

TODO: 将Git仓库关联到Vercel以实现自动部署

操作步骤：

bash

undefined

Option 1: Via CLI

选项1：通过CLI

vercel link vercel git connect

Option 2: Via Dashboard (recommended for first setup)

选项2：通过控制台（首次配置推荐）

1. Go to vercel.com/new

1. 访问vercel.com/new

2. Import Git repository

2. 导入Git仓库

3. Configure project settings

3. 配置项目设置

4. Deploy

4. 部署


After connecting:
- Push to `main` → Production deploy
- Push to other branches → Preview deploy
- PRs get deploy previews automatically


关联完成后：
- 推送到`main`分支 → 生产环境部署
- 推送到其他分支 → 预览环境部署
- 拉取请求会自动生成部署预览

Render: Connect Git Repository (Python)

Render：关联Git仓库（Python项目）

When Render is the deployment platform for Python projects:

Step 1: Ask user for Render API key

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.

Step 2: Create todos

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

Step 3: Connect via Dashboard (recommended)

bash

undefined

当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：通过控制台关联（推荐）

bash

undefined

1. Go to dashboard.render.com/create

1. 访问dashboard.render.com/create

2. Select "Web Service" for APIs, "Background Worker" for async

2. 为API选择“Web Service”，为异步任务选择“Background Worker”

3. Connect your GitHub/GitLab repository

3. 关联您的GitHub/GitLab仓库

4. Configure:

4. 配置：

- Name: <project-name>

- 名称：<project-name>

- Runtime: Python 3

- 运行时：Python 3

- Build Command: pip install -r requirements.txt

- 构建命令：pip install -r requirements.txt

- Start Command: uvicorn main:app --host 0.0.0.0 --port $PORT

- 启动命令：uvicorn main:app --host 0.0.0.0 --port $PORT


**Step 4: Store API key for CI/CD**
```bash


**步骤4：存储API密钥用于CI/CD**
```bash

Add to GitHub secrets for CI/CD

添加到GitHub Secrets用于CI/CD

gh secret set RENDER_API_KEY

Or add to local env

或添加到本地环境

echo "RENDER_API_KEY=<your-key>" >> .env


**Step 5: Configure render.yaml (optional - Infrastructure as Code)**
```yaml

echo "RENDER_API_KEY=<your-key>" >> .env


**步骤5：配置render.yaml（可选 - 基础设施即代码）**
```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

undefined

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

undefined

Deployment Checklist Template

部署检查清单模板

Add to project todos when setting up deployment:

markdown

undefined

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

markdown

undefined

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

---

创建Git仓库（gh repo create）
选择部署平台（Vercel/Render/其他）
将Git关联到部署平台
配置环境变量
设置CI/CD工作流
验证预览部署功能正常
配置生产环境域名

---

Tooling Anti-Patterns

工具使用反模式

❌ Hardcoded secrets - use CLI env management or GitHub secrets
❌ Manual deployments - automate via CI/CD
❌ Skipping local Supabase - always develop locally first
❌ Direct production database changes - use migrations
❌ No branch protection - require PR reviews and CI checks
❌ Missing environment separation - keep dev/staging/prod separate

❌ 硬编码密钥 - 使用CLI环境管理或GitHub Secrets
❌ 手动部署 - 通过CI/CD实现自动化
❌ 跳过本地Supabase开发 - 始终先在本地开发
❌ 直接修改生产数据库 - 使用迁移脚本
❌ 未启用分支保护 - 要求PR评审和CI检查
❌ 未区分环境 - 保持开发/预发布/生产环境分离