编码代理模板

这是一个用于构建 AI 驱动编码代理的模板，支持 Claude Code、OpenAI 的 Codex CLI、GitHub Copilot CLI、Cursor CLI、Google Gemini CLI 以及 opencode，并结合 Vercel Sandbox 自动在您的代码库上执行编码任务。

部署您自己的版本

您可以一键将编码代理模板部署到 Vercel：

部署过程中会发生什么：

• 自动数据库设置：会自动创建一个 Neon Postgres 数据库并连接到您的项目。
• 环境变量配置：系统会提示您提供所需的环境变量（Vercel 凭证和加密密钥）。
• OAuth 设置：部署完成后，您需要在项目设置中配置至少一个 OAuth 提供者（GitHub 或 Vercel），以便进行用户身份验证。

功能特性

• 多代理支持：可选择 Claude Code、OpenAI Codex CLI、GitHub Copilot CLI、Cursor CLI、Google Gemini CLI 或 opencode 来执行编码任务。
• 用户身份验证：通过 GitHub 或 Vercel OAuth 安全登录。
• 多用户支持：每个用户拥有独立的任务、API 密钥和 GitHub 连接。
• Vercel Sandbox：在隔离且安全的沙盒中运行代码（文档）。
• AI 网关集成：专为与 Vercel AI 网关 无缝集成而设计，实现模型路由和可观性。
• AI 生成分支名称：利用 AI SDK 5 和 AI 网关自动生成描述性的 Git 分支名称。
• 任务管理：实时更新任务进度。
• 持久化存储：任务存储在 Neon Postgres 数据库中。
• Git 集成：自动创建分支并提交更改。
• 现代化 UI：采用 Next.js 和 Tailwind CSS 构建的简洁、响应式界面。
• MCP 服务器支持：可将 MCP 服务器连接到 Claude Code，以扩展功能（仅限 Claude）。

快速入门

有关详细的设置说明，请参阅下方的 本地开发设置 部分。

简而言之：

1. 点击上方的“使用 Vercel 部署”按钮（自动设置数据库！）
2. 在项目设置中配置 OAuth（GitHub 或 Vercel）。
3. 用户登录并开始创建任务。

或者在本地运行：

git clone https://github.com/vercel-labs/coding-agent-template.git
cd coding-agent-template
pnpm install
# 设置 .env.local 文件，填入所需变量
pnpm db:push
pnpm dev

使用方法

1. 登录：使用 GitHub 或 Vercel 进行身份验证。
2. 创建任务：输入代码库 URL 并描述您希望 AI 执行的操作。
3. 监控进度：查看代理执行过程中的实时日志。
4. 审查结果：查看所做的更改及创建的分支。
5. 管理任务：在侧边栏中查看所有任务及其状态更新。

任务配置

最大时长

最大时长设置控制着 Vercel 沙盒从创建时刻起保持活跃的时间长度。您可以选择从 5 分钟到 5 小时不等的超时时间。

• 沙盒在任务开始时创建。
• 超时计时从沙盒创建时开始。
• 所有工作（代理执行、依赖项安装等）都在此时间内完成。
• 当达到超时时长时，沙盒会自动过期。

保持活跃设置

“保持活跃”设置决定了任务完成后沙盒的后续行为。

保持活跃关闭（默认）

当“保持活跃”关闭时，沙盒会在任务完成后立即关闭：

时间线：

1. 任务开始，沙盒创建（例如，设置 1 小时超时）。
2. 代理执行您的任务。
3. 任务成功完成（例如，10 分钟后）。
4. 更改被提交并推送到分支。
5. 沙盒立即关闭（销毁所有进程和环境）。
6. 任务标记为已完成。

建议在以下情况下关闭“保持活跃”：

• 您只需进行一次性代码更改，无需迭代。
• 您的任务简单且一次就能完成。
• 您希望最大限度地减少资源使用和成本。
• 您不需要在任务完成后对代码进行测试或手动交互。

保持活跃开启

当“保持活跃”开启时，沙盒会在任务完成后继续存活剩余时间：

时间线：

1. 任务开始，沙盒创建（例如，设置 1 小时超时）。
2. 代理执行您的任务。
3. 任务成功完成（例如，10 分钟后）。
4. 更改被提交并推送到分支。
5. 沙盒保持活跃，所有进程仍在运行。
6. 您可以在接下来的 50 分钟内发送后续消息（直到 1 小时超时结束）。
7. 如果项目中有开发服务器（例如 npm run dev），它会自动在后台启动。
8. 达到完整超时时长后，沙盒过期。

建议在以下情况下开启“保持活跃”：

• 您需要通过后续消息对代码进行迭代。
• 您希望在实时沙盒环境中测试更改。
• 您预计可能需要进一步优化或修复问题。
• 您希望在任务完成后手动运行命令或检查环境。
• 您正在开发 Web 应用程序，并希望看到其运行效果。

对比

设置	任务完成时间为 10 分钟	沙盒剩余时间	是否可以发送后续消息？	开发服务器是否启动？
保持活跃开启	沙盒保持活跃	50 分钟（直至超时）	是	是（如有可用）
保持活跃关闭	沙盒立即关闭	0 分钟	否	否

注意： 最大时长超时始终优先。如果您设置了 1 小时超时，无论“保持活跃”设置如何，沙盒都将在 1 小时后过期。因此，“保持活跃”仅决定沙盒是在任务完成后提前关闭，还是在超时前继续保持活跃。

工作原理

1. 任务创建：当你提交一个任务时，它会被存储在数据库中。
2. AI 分支名称生成：AI SDK 5 + AI Gateway 会根据你的任务自动生成一个描述性的分支名称（使用 Next.js 15 的 after() 实现非阻塞操作）。
3. 沙盒设置：系统会基于你的仓库创建一个 Vercel 沙盒。
4. 代理执行：你选择的编码代理（Claude Code、Codex CLI、GitHub Copilot CLI、Cursor CLI、Gemini CLI 或 opencode）会分析你的提示并进行更改。
5. Git 操作：更改会被提交并推送到由 AI 生成的分支上。
6. 清理：沙盒会被关闭以释放资源。

AI 分支名称生成

系统会使用 AI SDK 5 和 Vercel AI Gateway 自动为 Git 分支生成描述性名称。该功能具有以下特点：

• 非阻塞：利用 Next.js 15 的 after() 函数生成分支名称，不会延迟任务创建。
• 描述性强：能够生成如 feature/user-authentication-A1b2C3 或 fix/memory-leak-parser-X9y8Z7 等有意义的分支名称。
• 无冲突：通过添加 6 位字母数字哈希值来避免命名冲突。
• 回退机制：如果 AI 生成失败，会优雅地回退到基于时间戳的名称。
• 上下文感知：结合任务描述、仓库名称和代理上下文，生成更优质的分支名称。

分支名称示例

• feature/add-user-auth-K3mP9n（用于“添加 JWT 用户认证”）
• fix/resolve-memory-leak-B7xQ2w（用于“修复图像处理中的内存泄漏”）
• chore/update-deps-M4nR8s（用于“更新所有项目依赖”）
• docs/api-endpoints-F9tL5v（用于“记录 REST API 端点”）

技术栈

• 前端：Next.js 15、React 19、Tailwind CSS
• UI 组件：shadcn/ui
• 数据库：PostgreSQL 结合 Drizzle ORM
• AI SDK：AI SDK 5，集成 Vercel AI Gateway
• AI 代理：Claude Code、OpenAI Codex CLI、GitHub Copilot CLI、Cursor CLI、Google Gemini CLI、opencode
• 沙盒：Vercel 沙盒
• 认证：Next Auth（支持 GitHub/Vercel 的 OAuth 认证）
• Git：自动化分支与提交，采用 AI 生成的分支名称。

MCP 服务器支持

连接 MCP 服务器可以扩展 Claude Code 的工具和集成能力。目前仅支持 Claude Code 代理。

如何添加 MCP 服务器

1. 进入“Connectors”选项卡，点击“Add MCP Server”。
2. 输入服务器详细信息（名称、基础 URL，可选 OAuth 凭证）。
3. 如果使用 OAuth，请确保在环境变量中设置了 ENCRYPTION_KEY。

注意：当使用带有 OAuth 认证的 MCP 服务器时，ENCRYPTION_KEY 是必需的。

本地开发设置

1. 克隆仓库

git clone https://github.com/vercel-labs/coding-agent-template.git
cd coding-agent-template

2. 安装依赖

pnpm install

3. 设置环境变量

创建一个 .env.local 文件，并填写你的配置：

必需环境变量（应用基础设施）

这些变量由你（应用开发者）一次性设置，用于核心基础设施：

• POSTGRES_URL：你的 PostgreSQL 连接字符串（部署到 Vercel 时，Neon 集成会自动提供；本地开发则需手动设置）。
• SANDBOX_VERCEL_TOKEN：你的 Vercel API 令牌（用于创建沙盒）。
• SANDBOX_VERCEL_TEAM_ID：你的 Vercel 团队 ID（用于沙盒创建）。
• SANDBOX_VERCEL_PROJECT_ID：你的 Vercel 项目 ID（用于沙盒创建）。
• JWE_SECRET：用于会话加密的 Base64 编码密钥（可通过命令 openssl rand -base64 32 生成）。
• ENCRYPTION_KEY：用于加密用户 API 密钥和令牌的 32 字节十六进制字符串（可通过命令 openssl rand -hex 32 生成）。

注意：使用“Deploy with Vercel”按钮部署时，数据库会通过 Neon 自动 provision，POSTGRES_URL 也会为你设置好。而在本地开发环境中，则需要你自行提供数据库连接字符串。

用户认证（必填）

必须至少配置一种认证方式（Vercel 或 GitHub）：

配置启用的提供商

• NEXT_PUBLIC_AUTH_PROVIDERS：启用的认证提供商列表，用逗号分隔。
  • "github"：仅 GitHub（默认）。
  • "vercel"：仅 Vercel。
  • "github,vercel"：同时启用两种认证方式。

示例：

# 仅 GitHub 认证（默认）
NEXT_PUBLIC_AUTH_PROVIDERS=github

# 仅 Vercel 认证
NEXT_PUBLIC_AUTH_PROVIDERS=vercel

# 同时启用 GitHub 和 Vercel 认证
NEXT_PUBLIC_AUTH_PROVIDERS=github,vercel

提供商配置

选项 1：使用 Vercel 登录（若 vercel 在 NEXT_PUBLIC_AUTH_PROVIDERS 中）：

• NEXT_PUBLIC_VERCEL_CLIENT_ID：你的 Vercel OAuth 应用客户端 ID（暴露给客户端）。
• VERCEL_CLIENT_SECRET：你的 Vercel OAuth 应用客户端密钥。

选项 2：使用 GitHub 登录（若 github 在 NEXT_PUBLIC_AUTH_PROVIDERS 中）：

• NEXT_PUBLIC_GITHUB_CLIENT_ID：你的 GitHub OAuth 应用客户端 ID（暴露给客户端）。
• GITHUB_CLIENT_SECRET：你的 GitHub OAuth 应用客户端密钥。

注意：只有在 NEXT_PUBLIC_AUTH_PROVIDERS 中列出的提供商才会出现在登录对话框中。对于每个启用的提供商，你都必须提供相应的 OAuth 凭证。

API 密钥（可选，可按用户设置）

这些 API 密钥可以全局设置（作为所有用户的默认值），也可以不设置，从而要求用户各自提供自己的密钥：

• ANTHROPIC_API_KEY：Claude 代理的 Anthropic API 密钥（用户可在个人资料中覆盖）。
• AI_GATEWAY_API_KEY：用于分支名称生成和 Codex 的 AI Gateway API 密钥（用户可在个人资料中覆盖）。
• CURSOR_API_KEY：用于 Cursor 代理的支持（用户可在个人资料中覆盖）。
• GEMINI_API_KEY：用于 Google Gemini 代理的支持（用户可在个人资料中覆盖）。
• OPENAI_API_KEY：用于 Codex 和 OpenCode 代理的支持（用户可在个人资料中覆盖）。

注意：用户可以在个人资料中提供自己的 API 密钥，这些密钥将优先于全局环境变量。

GitHub 仓库访问权限

• GITHUB_TOKEN：已不再需要！ 用户现在通过自己的 GitHub 账户进行认证。
  • 使用 GitHub 登录的用户会通过其 OAuth 令牌直接获得仓库访问权限。
  • 使用 Vercel 登录的用户则需要在个人资料中绑定 GitHub 账户，才能访问仓库。

认证工作原理：

• GitHub 登录：用户通过其 GitHub OAuth 令牌立即获得仓库访问权限。
• Vercel 登录：用户需在个人资料中绑定 GitHub 账户，方可操作仓库。
• 身份合并：如果用户先使用 Vercel 登录，随后绑定 GitHub 账户，再直接使用 GitHub 登录，系统会识别为同一用户，不会产生重复账户。

可选环境变量

• NPM_TOKEN：用于私有 npm 包。
• MAX_SANDBOX_DURATION：沙盒的最大运行时长（分钟），默认为 300 分钟（即 5 小时）。
• MAX_MESSAGES_PER_DAY：每位用户每天允许的最大任务数及后续跟进次数，默认为 5。

4. 设置 OAuth 应用程序

根据你的 NEXT_PUBLIC_AUTH_PROVIDERS 配置，你需要创建 OAuth 应用程序：

GitHub OAuth 应用程序（如果使用 GitHub 身份验证）

1. 前往 GitHub 开发者设置
2. 点击“新建 OAuth 应用”
3. 填写详细信息：
   • 应用名称：你的应用名称（例如：“我的编码助手”）
   • 主页 URL：http://localhost:3000（或你的生产环境 URL）
   • 授权回调 URL：http://localhost:3000/api/auth/github/callback
4. 点击“注册应用”
5. 复制 客户端 ID → 用于 NEXT_PUBLIC_GITHUB_CLIENT_ID
6. 点击“生成新的客户端密钥”→ 复制并用于 GITHUB_CLIENT_SECRET

所需作用域：该应用将请求 repo 作用域以访问仓库。

Vercel OAuth 应用程序（如果使用 Vercel 身份验证）

1. 前往你的 Vercel 控制台
2. 导航到设置 → 集成 → 创建
3. 配置集成：
   • 重定向 URL：http://localhost:3000/api/auth/callback/vercel
4. 复制 客户端 ID → 用于 NEXT_PUBLIC_VERCEL_CLIENT_ID
5. 复制 客户端密钥 → 用于 VERCEL_CLIENT_SECRET

生产部署：记得在部署时添加生产环境的回调 URL（例如：https://yourdomain.com/api/auth/github/callback）

5. 设置数据库

生成并运行数据库迁移：

pnpm db:generate
pnpm db:push

6. 启动开发服务器

pnpm dev

在浏览器中打开 http://localhost:3000。

开发

数据库操作

# 生成迁移
pnpm db:generate

# 推送模式更改
pnpm db:push

# 打开 Drizzle Studio
pnpm db:studio

运行应用

# 开发
pnpm dev

# 构建生产环境
pnpm build

# 启动生产服务器
pnpm start

贡献

1. 分支仓库
2. 创建功能分支
3. 进行修改
4. 全面测试
5. 提交拉取请求

安全注意事项

• 环境变量：切勿将 .env 文件提交到版本控制中。所有敏感数据应存储在环境变量中。
• API 密钥：定期轮换 API 密钥，并遵循最小权限原则。
• 数据库访问：确保 PostgreSQL 数据库使用强凭据进行妥善保护。
• Vercel 沙盒：沙盒是隔离的，但请确保不要在日志或输出中暴露敏感数据。
• 用户身份验证：每个用户使用自己的 GitHub 令牌访问仓库——不共享凭据。
• 加密：所有敏感数据（令牌、API 密钥）均采用基于用户的加密技术进行静态加密。

更改记录

版本 2.0.0 - 重大更新：用户身份验证与安全性

此版本引入了 用户身份验证 和 重大安全改进，但包含需要现有部署迁移的 破坏性变更。

新特性

• 用户身份验证系统

  • 使用 Vercel 登录
  • 使用 GitHub 登录
  • 带有加密令牌的会话管理
  • 用户个人资料管理

• 多用户支持

  • 每个用户拥有自己的任务和连接器
  • 用户可以管理自己的 API 密钥（Anthropic、OpenAI、Cursor、Gemini、AI Gateway）
  • 可连接 GitHub 账户以访问仓库

• 安全增强

  • 基于用户的 GitHub 身份验证——每位用户使用自己的 GitHub 令牌，而非共享凭据
  • 所有敏感数据（令牌、API 密钥、环境变量）均采用静态加密
  • 基于会话的身份验证，使用 JWT 加密
  • 基于用户的授权——用户只能访问属于自己的资源

• 数据库增强

  • 新增 users 表，用于存储用户个人资料和 OAuth 账户
  • 新增 accounts 表，用于关联账户（例如，Vercel 用户连接 GitHub）
  • 新增 keys 表，用于存储用户提供的 API 密钥
  • 外键关系确保数据完整性
  • 支持软删除任务

破坏性变更

如果从 v1.x 升级，需采取以下措施：

1. 数据库模式变更

   • tasks 表现在需要 userId（外键指向 users.id）
   • connectors 表现在需要 userId（外键指向 users.id）
   • connectors.env 由 jsonb 改为加密的 text
   • 新增 tasks.deletedAt 字段，用于软删除

2. API 变更

   • 所有 API 端点现在都需要身份验证
   • 创建任务时，请求体中必须包含 userId
   • 任务现在按用户所有权进行筛选
   • 访问 GitHub API 时，使用用户自己的 GitHub 令牌（不再使用共享令牌作为备用）

3. 环境变量

   • 新增必填变量：

     • JWE_SECRET：Base64 编码的会话加密密钥（生成方法：openssl rand -base64 32）
     • ENCRYPTION_KEY：32 字节的十六进制字符串，用于加密敏感数据（生成方法：openssl rand -hex 32）
     • NEXT_PUBLIC_AUTH_PROVIDERS：配置启用哪些身份验证提供商（github、vercel，或两者同时）

   • 新增 OAuth 配置（至少需配置一项）：

     • GitHub：NEXT_PUBLIC_GITHUB_CLIENT_ID、GITHUB_CLIENT_SECRET
     • Vercel：NEXT_PUBLIC_VERCEL_CLIENT_ID、VERCEL_CLIENT_SECRET

   • 身份验证变更：

     • GITHUB_TOKEN 不再作为 API 路由中的备用令牌
     • 用户必须连接自己的 GitHub 账户才能访问仓库
     • 每个用户仅使用自己的 GitHub 令牌发起请求

4. 强制身份验证

   • 所有路由现在都需要用户身份验证
   • 不再允许匿名访问任务或 API 端点
   • 用户必须先使用 GitHub 或 Vercel 登录，才能创建任务

现有部署迁移指南

如果你要从 v1.x 升级到 v2.0.0，请按照以下步骤操作：

步骤 1：备份数据库

# 创建现有数据库的备份
pg_dump $POSTGRES_URL > backup-before-v2-migration.sql

步骤 2：添加必要的环境变量

将以下新变量添加到你的 .env.local 文件或 Vercel 项目设置中：

# 会话加密（必填）
JWE_SECRET=$(openssl rand -base64 32)
ENCRYPTION_KEY=$(openssl rand -hex 32)

# 配置身份验证提供商（必填——至少选择一个）
NEXT_PUBLIC_AUTH_PROVIDERS=github  # 或 "vercel" 或 "github,vercel"

# 如果使用 GitHub 身份验证
NEXT_PUBLIC_GITHUB_CLIENT_ID=your_github_client_id
GITHUB_CLIENT_SECRET=your_github_client_secret

# 如果使用 Vercel 身份验证
NEXT_PUBLIC_VERCEL_CLIENT_ID=your_vercel_client_id
VERCEL_CLIENT_SECRET=your_vercel_client_secret

步骤 3：设置 OAuth 应用程序

为所选的身份验证提供商创建 OAuth 应用程序。详细说明请参阅“本地开发设置”部分。

步骤 4：准备数据库迁移

在运行迁移之前，你需要处理现有数据：

选项 A：全新开始（建议用于开发环境）

如果你不需要保留生产数据：

# 删除现有表并从头开始
pnpm db:push --force

# 这将创建所有具有正确结构的新表

选项 B：保留现有数据（生产环境）

如果您需要保留现有的任务/连接器：

1. 先创建一个系统用户：

-- 连接到您的数据库并执行：
INSERT INTO users (id, provider, external_id, access_token, username, email, created_at, updated_at, last_login_at)
VALUES (
  'system-user-migration',
  'github',
  'system-migration',
  'encrypted-placeholder-token',  -- 您需要加密一个占位符令牌
  '系统迁移用户',
  NULL,
  NOW(),
  NOW(),
  NOW()
);

2. 更新现有记录：

-- 为现有任务添加 userId
ALTER TABLE tasks ADD COLUMN user_id TEXT;
UPDATE tasks SET user_id = 'system-user-migration' WHERE user_id IS NULL;
ALTER TABLE tasks ALTER COLUMN user_id SET NOT NULL;
ALTER TABLE tasks ADD CONSTRAINT tasks_user_id_fkey FOREIGN KEY (user_id) REFERENCES users(id) ON DELETE CASCADE;

-- 为现有连接器添加 userId
ALTER TABLE connectors ADD COLUMN user_id TEXT;
UPDATE connectors SET user_id = 'system-user-migration' WHERE user_id IS NULL;
ALTER TABLE connectors ALTER COLUMN user_id SET NOT NULL;
ALTER TABLE connectors ADD CONSTRAINT connectors_user_id_fkey FOREIGN KEY (user_id) REFERENCES users(id) ON DELETE CASCADE;

-- 将连接器的 env 从 jsonb 转换为加密文本（需要在应用层进行加密）
-- 注意：您需要使用 ENCRYPTION_KEY 手动加密现有的 env 值

3. 运行标准迁移：

pnpm db:generate
pnpm db:push

步骤 5：更新代码

拉取最新更改：

git pull origin main
pnpm install

步骤 6：测试认证

1. 启动开发服务器：pnpm dev
2. 访问 http://localhost:3000
3. 使用您配置的 OAuth 提供商登录
4. 验证您可以创建和查看任务

步骤 7：验证安全修复

确认以下内容：

• 用户只能查看自己的任务
• 文件差异/文件相关端点需要 GitHub 连接
• 没有 GitHub 连接的用户会看到“需要 GitHub 认证”的错误提示
• API 路由中未使用 GITHUB_TOKEN 备用机制

重要注意事项

• 所有用户在此升级后都需要登录——不再支持匿名访问。
• 使用选项 B 迁移时，现有任务将归系统用户所有。
• 如果用户之前通过 Vercel 登录，则必须连接 GitHub 才能访问仓库。
• API 密钥现在可以按用户设置——用户可以在个人资料中覆盖全局 API 密钥。
• API 的重大变更：如果有外部集成调用您的 API，它们需要更新以包含认证信息。

Coding Agent Template 快速上手指南

Coding Agent Template 是一个用于构建 AI 编程智能体的开源模板。它支持 Claude Code、OpenAI Codex CLI、GitHub Copilot CLI、Cursor CLI、Google Gemini CLI 和 opencode 等多种主流 AI 工具，并利用 Vercel Sandbox 在隔离的安全环境中自动执行代码任务。

环境准备

在开始之前，请确保您的开发环境满足以下要求：

• 操作系统: macOS, Linux 或 Windows (WSL2 推荐)
• Node.js: v18.17 或更高版本 (推荐 v20+)
• 包管理器: pnpm (项目首选，也可使用 npm/yarn 但需自行调整命令)
• 数据库: 本地开发需自备 PostgreSQL 实例，或使用 Vercel 部署时自动配置的 Neon Postgres。
• Vercel 账号: 用于获取 Sandbox 运行所需的 Team ID、Project ID 和 API Token。
• OAuth 应用: 需在 GitHub 或 Vercel 平台创建 OAuth App 以支持用户登录。

安装步骤

您可以选择一键部署到 Vercel（推荐新手）或在本地进行开发。

方式一：一键部署到 Vercel（推荐）

这是最快速的启动方式，会自动配置数据库和环境变量。

1. 点击下方的部署按钮：
2. 按照向导完成部署，系统会自动创建 Neon Postgres 数据库。
3. 重要：部署完成后，进入 Vercel 项目设置，配置至少一个 OAuth 提供商（GitHub 或 Vercel）以启用用户登录功能。

方式二：本地开发安装

如果您希望在本地运行和调试，请按以下步骤操作：

1. 克隆仓库

   git clone https://github.com/vercel-labs/coding-agent-template.git
   cd coding-agent-template
   

2. 安装依赖

   pnpm install
   

   提示：国内开发者若下载缓慢，可配置 .npmrc 使用淘宝镜像源：registry=https://registry.npmmirror.com

3. 配置环境变量 在项目根目录创建 .env.local 文件，并填入以下必要变量：

   # 数据库连接 (本地开发请填写本地 PG 地址，Vercel 部署会自动生成)
   POSTGRES_URL="postgresql://user:password@localhost:5432/dbname"
   
   # Vercel Sandbox 配置 (从 Vercel 账户设置中获取)
   SANDBOX_VERCEL_TOKEN="your_vercel_token"
   SANDBOX_VERCEL_TEAM_ID="your_team_id"
   SANDBOX_VERCEL_PROJECT_ID="your_project_id"
   
   # 加密密钥 (生成方法见下方说明)
   JWE_SECRET="base64_encoded_secret"
   ENCRYPTION_KEY="32_byte_hex_string"
   
   # 认证提供商配置 (至少启用一个)
   NEXT_PUBLIC_AUTH_PROVIDERS="github" 
   # 若启用 GitHub:
   NEXT_PUBLIC_GITHUB_CLIENT_ID="your_github_client_id"
   GITHUB_CLIENT_SECRET="your_github_client_secret"
   # 若启用 Vercel:
   # NEXT_PUBLIC_VERCEL_CLIENT_ID="..."
   # VERCEL_CLIENT_SECRET="..."
   

   密钥生成命令：

   # 生成 JWE_SECRET
   openssl rand -base64 32
   # 生成 ENCRYPTION_KEY
   openssl rand -hex 32
   

4. 初始化数据库

   pnpm db:push
   

5. 启动开发服务器

   pnpm dev
   

基本使用

启动成功后，访问 http://localhost:3000 (本地) 或您的 Vercel 部署域名。

1. 登录系统 使用已配置的 GitHub 或 Vercel 账号进行安全登录。

2. 创建任务

   • 在界面中输入目标代码仓库的 URL。
   • 在描述框中输入您希望 AI 完成的任务（例如："Add a user login page with JWT authentication"）。
   • 选择智能体：从下拉菜单中选择您偏好的 AI 工具（如 Claude Code, Cursor CLI 等）。
   • 配置超时与保活：
     • Maximum Duration: 设置沙箱最大运行时间（5 分钟至 5 小时）。
     • Keep Alive: 若需任务完成后继续交互或测试，请开启此选项；若仅需一次性修改，保持关闭以节省资源。

3. 监控进度 任务开始后，您可以在界面上实时查看 AI 智能体的执行日志、安装的依赖以及生成的代码变更。

4. 查看结果

   • 任务完成后，系统会自动创建一个描述性的 Git 分支（由 AI 自动生成名称，如 feature/add-login-A1b2C3）。
   • 您可以直接在界面上审查代码差异，或切换到该分支进行后续开发。

5. 管理任务 通过侧边栏查看所有历史任务的状态、日志及对应的分支链接。