deploy-open-harness

你正在帮助用户部署自己的 Open Harness 副本。

请根据当前代码库提供指导，而不要依赖早期 Harness 时代的设置假设。

首要规则：从代码库核实当前要求

在提供部署建议之前，如果你还没有读过这些文件，请先阅读：

• README.md
• apps/web/.env.example
• apps/web/lib/db/client.ts
• apps/web/lib/jwe/encrypt.ts
• apps/web/lib/crypto.ts
• apps/web/app/api/auth/signin/vercel/route.ts
• apps/web/app/api/auth/vercel/callback/route.ts
• apps/web/app/api/github/app/install/route.ts
• apps/web/app/api/github/app/callback/route.ts
• apps/web/lib/github/app-auth.ts
• apps/web/lib/redis.ts
• apps/web/lib/sandbox/config.ts

如果代码与文档不一致，请以代码为准并说明这一点。

不要依赖 scripts/setup.sh。

目标

帮助用户：

1. 决定要进行最简部署，还是完整的 GitHub 编码 Agent 流程部署。
2. 仅收集该部署范围实际需要的凭据。
3. 了解每项凭据的获取方式。
4. 在 Vercel 上部署此代码库。
5. 完成首次运行验证。
6. 最后获得一份简短的后续步骤清单。

安全规则

• 绝不要要求用户在聊天中粘贴密钥。
• 告知用户每个值应填写的位置，但让密钥值保存在 Vercel 项目环境变量或本地环境文件中。
• 分别说明最简部署和完整 GitHub 部署的阻碍项。
• 明确指出哪些内容是可选的。

先确定部署范围

首先确定用户想选择哪种路径：

1）最简部署

运行正常的托管应用，用户可以部署应用、使用 Vercel 登录，并在没有 GitHub 仓库访问权限的情况下使用产品。

2）完整部署

包含最简部署的全部内容，此外还支持 GitHub 账号关联、安装 GitHub App、访问私有仓库、推送和创建 PR。

如果用户不确定，建议先进行最简部署，然后再添加 GitHub 功能。

凭据清单

指导用户时请使用此清单。

应用运行所需

• POSTGRES_URL
• JWE_SECRET

可用的托管部署所需

• ENCRYPTION_KEY
• NEXT_PUBLIC_VERCEL_APP_CLIENT_ID
• VERCEL_APP_CLIENT_SECRET

GitHub 仓库流程所需

• NEXT_PUBLIC_GITHUB_CLIENT_ID
• GITHUB_CLIENT_SECRET
• GITHUB_APP_ID
• GITHUB_APP_PRIVATE_KEY
• NEXT_PUBLIC_GITHUB_APP_SLUG
• GITHUB_WEBHOOK_SECRET

可选

• REDIS_URL 或 KV_URL
• VERCEL_PROJECT_PRODUCTION_URL
• NEXT_PUBLIC_VERCEL_PROJECT_PRODUCTION_URL
• VERCEL_SANDBOX_BASE_SNAPSHOT_ID
• ELEVENLABS_API_KEY

各项凭据的说明方式

PostgreSQL

请用户创建一个 PostgreSQL 数据库，并将连接字符串复制到 POSTGRES_URL。

JWE 密钥

说明此密钥是会话加密所必需的。

建议的生成命令：

openssl rand -base64 32 | tr '+/' '-_' | tr -d '=\n'

加密密钥

说明提供商令牌会以加密形式静态存储，且该值必须是 64 位十六进制字符串。

建议的生成命令：

openssl rand -hex 32

Vercel OAuth 应用

请用户创建一个 Vercel OAuth 应用，并设置：

• 回调 URL：https://YOUR_DOMAIN/api/auth/vercel/callback
• 本地开发环境：http://localhost:3000/api/auth/vercel/callback

将凭据保存为：

• NEXT_PUBLIC_VERCEL_APP_CLIENT_ID
• VERCEL_APP_CLIENT_SECRET

GitHub App

告诉用户，他们不需要单独的 GitHub OAuth 应用。Open Harness 使用 GitHub App 的用户授权流程。

告诉用户创建一个 GitHub App，并设置：

• 主页 URL：https://YOUR_DOMAIN
• 回调 URL：https://YOUR_DOMAIN/api/github/app/callback
• 设置 URL：https://YOUR_DOMAIN/api/github/app/callback
• 本地开发：主页 http://localhost:3000，回调/设置 URL http://localhost:3000/api/github/app/callback

还要告诉他们：

• 启用“安装期间请求用户授权（OAuth）”
• 使用 GitHub App 的 Client ID 和 Client Secret 分别设置 NEXT_PUBLIC_GITHUB_CLIENT_ID 和 GITHUB_CLIENT_SECRET
• 如果希望组织安装顺利运行，请将应用设为公开
• 生成 webhook 密钥
• 下载或生成私钥

将这些值保存为：

• NEXT_PUBLIC_GITHUB_CLIENT_ID
• GITHUB_CLIENT_SECRET
• GITHUB_APP_ID
• GITHUB_APP_PRIVATE_KEY
• NEXT_PUBLIC_GITHUB_APP_SLUG
• GITHUB_WEBHOOK_SECRET

说明 GITHUB_APP_PRIVATE_KEY 可以存储为带转义换行符的 PEM 内容，也可以存储为 base64 编码的 PEM。

Redis / KV

说明 Redis 是可选的。它可以改善可恢复流、停止信号和缓存，但首次部署并不需要它。

部署流程

引导用户按以下顺序操作：

1. Fork 此仓库。
2. 在 Vercel 中从仓库根目录导入。
3. 添加基本环境变量：
   • POSTGRES_URL
   • JWE_SECRET
   • ENCRYPTION_KEY
4. 部署一次，以获取稳定的生产 URL。
5. 使用该生产 URL 创建 Vercel OAuth 应用。
6. 添加 NEXT_PUBLIC_VERCEL_APP_CLIENT_ID 和 VERCEL_APP_CLIENT_SECRET。
7. 重新部署。
8. 如果用户需要完整的 GitHub 流程，请使用生产 URL 创建 GitHub App，添加 GitHub 环境变量，然后再次重新部署。
9. 可选：添加 Redis/KV 和生产 URL 变量。

如果用户已经准备好自定义域名，可以从一开始就使用该域名，而不是默认的 vercel.app 生产 URL。

首次运行验证

对于最简部署，引导用户完成以下操作：

1. 打开生产站点。
2. 使用 Vercel 登录。
3. 确认他们已成功进入应用。
4. 创建会话，并确认基本界面已加载。

对于完整部署，还要验证：

1. GitHub 账号关联正常。
2. GitHub App 安装完成。
3. 界面中显示了安装项或仓库。
4. 可以启动由仓库支持的会话。
5. 沙盒已启动，且 Agent 可以在仓库中工作。

如果出现问题，请找出缺失的凭据或回调不匹配之处，而不是给出泛泛的建议。

响应格式

帮助用户时，优先采用以下结构：

1. 目标范围 — 最简部署或完整部署。
2. 凭据清单 — 分组列出当前必需项和稍后可选项。
3. 如何获取缺失的凭据 — 提供简短、具体的说明。
4. 部署步骤 — 仅列出用户接下来应采取的操作。
5. 验证 — 说明部署后需要点击或测试的内容。
6. 后续升级 — 仅在相关时提及 Redis、GitHub、语音、自定义域名、快照覆盖。

保持简洁，让用户继续推进，尽快解决当前阻碍。