C.R.A.B Deploy Agent

# deploy-agent

通过多步骤工作流程部署全栈应用程序，每个阶段都需要人工批准。

## 快速开始

```bash # Install via ClawdHub clawdhub install deploy-agent

# Initialize a new deployment deploy-agent init my-app

# Check status deploy-agent status my-app

# Continue through steps deploy-agent continue my-app ```

## 工作流步骤

| 步骤 | 命令 | 描述 | 需要批准 | |------|---------|-------------|-------------------| | 1 | `deploy-agent init <name>` | 开始部署 | ✅ 设计阶段 | | 2 | `deploy-agent build <name>` | 构建应用 | ✅ 测试之前 | | 3 | `deploy-agent test <name>` | 本地测试 | ✅ 推送到 GitHub 之前 | | 4 | `deploy-agent push <name>` | 推送到 GitHub | ✅ 部署到 Cloudflare 之前 | | 5 | `deploy-agent deploy <name>` | 部署到 Cloudflare | ✅ 最终确认 |

## 命令

### 初始化部署 ```bash deploy-agent init my-app ``` 创建新的部署状态并等待设计输入。

### 检查状态 ```bash deploy-agent status my-app ``` 显示当前步骤、批准情况和部署信息。

### 继续 ```bash deploy-agent continue my-app ``` 获取当前步骤下一步操作的指导。

### 构建（步骤 2） ```bash deploy-agent build my-app ``` 使用 C.R.A.B 完成设计后，运行此命令构建应用。

### 测试（步骤 3） ```bash deploy-agent test my-app ``` 在推送之前验证应用是否在本地运行。

### 推送到 GitHub（步骤 4） ```bash deploy-agent push my-app [repo-name] ``` 创建 GitHub 仓库并推送代码。默认仓库名 = 应用名称。

### 部署到 Cloudflare（步骤 5） ```bash deploy-agent deploy my-app [custom-domain] ``` 部署到 Cloudflare Pages。默认域名：`{name}.sheraj.org`

### 取消 ```bash deploy-agent cancel my-app ``` 中止并清理部署。

### 列表 ```bash deploy-agent list ``` 显示所有活动的部署。

## 示例会话

```bash # Start new deployment $ deploy-agent init my-blog 🚀 Deployment initialized: my-blog Step 1: Design your app with C.R.A.B

# ... design phase with C.R.A.B ...

$ deploy-agent build my-blog 🚀 Build complete! Step 2: Local Testing Start dev server: cd my-blog && npm run dev

# ... test locally ...

$ deploy-agent push my-blog 🚀 GitHub repository ready! Say 'deploy-agent deploy my-blog' to deploy to Cloudflare

$ deploy-agent deploy my-blog my-blog.sheraj.org 🎉 Deployment complete! App live at: https://my-blog.sheraj.org ```

## 状态管理

状态存储于：`~/.clawdbot/skills/deploy-agent/state/{deployment-name}.json`

```json { "name": "my-blog", "step": 5, "status": "deployed", "created_at": "2026-01-18T08:00:00Z", "repo_url": "https://github.com/user/my-blog", "domain": "https://my-blog.sheraj.org" } ```

## 环境要求

| 工具 | 用途 | |------|---------| | `gh` | GitHub 仓库创建和管理 | | `wrangler` | Cloudflare Pages 部署 | | `git` | 版本控制 | | `jq` | JSON 解析（用于状态管理） |

## 配置

Cloudflare 令牌应在 `~/.wrangler.toml` 中配置： ```toml [account] api_token = "your-cloudflare-token" ```

## 注意事项

- 每个部署都是独立的 - 状态在会话之间持久保存 - 每个主要步骤都需要人工批准 - 随时可以使用 "cancel" 命令中止

---

## Next.js + Cloudflare D1 部署指南

本节介绍了在 Cloudflare Pages 上部署使用 D1 的 Next.js 应用时的常见陷阱和修复方法。

### 部署前检查清单

| 检查项 | 命令 | 失败时的修复方法 | |-------|---------|---------------| | Next.js 版本 | `npm list next` | `npm install [email protected]` | | Package lock 同步 | `rm -rf node_modules package-lock.json && npm install` | 提交 lock 文件 | | Cloudflare 适配器 | `npm list @cloudflare/next-on-pages` | `npm install -D @cloudflare/next-on-pages` | | wrangler 已安装 | `npm list wrangler` | `npm install -D wrangler` |

### 必需配置

**1. package.json** ```json { "dependencies": { "next": "15.5.2", "react": "^18.3.1", "react-dom": "^18.3.1" }, "devDependencies": { "@cloudflare/next-on-pages": "^1.13.16", "wrangler": "^4.x" } } ```

**2. wrangler.toml** ```toml name = "my-app" compatibility_date = "2026-01-18" compatibility_flags = ["nodejs_compat"]

[[d1_databases]] binding = "DB" database_name = "my-db" database_id = "your-db-id" ```

**3. API 路由（每个文件）** ```typescript import { getRequestContext } from '@cloudflare/next-on-pages';

export const runtime = 'edge';

export async function GET() { const { env } = getRequestContext(); const { results } = await env.DB.prepare("SELECT * FROM tasks").all(); return Response.json({ data: results }); } ```

### Cloudflare Pages 构建设置

| 设置 | 值 | |---------|-------| | 构建命令 | `npx @cloudflare/next-on-pages` | | 输出目录 | `.vercel/output/static` | | 函数 | 启用（用于 D1 API 路由） |

### 常见问题与修复

| 问题 | 错误 | 修复方法 | |-------|-------|-----| | Lock 文件不匹配 | `npm ci can only install packages when your package.json and package-lock.json are in sync` | `rm -rf node_modules package-lock.json && npm install && git add package-lock.json` | | Next.js 版本 | `peer next@">=14.3.0 && <=15.5.2"` 来自 @cloudflare/next-on-pages | 降级到 `next: "15.5.2"` | | API 路由未配置 Edge | `The following routes were not configured to run with the Edge Runtime` | 添加 `export const runtime = 'edge';` | | D1 访问模式 | 使用 `context.env.DB` | 使用 `getRequestContext().env.DB` | | 类型缺失 | D1 绑定的 TypeScript 错误 | 创建包含 CloudflareEnv 接口的 `env.d.ts` |

### CSS 修复（滚动条闪烁） ```css html { overflow-x: hidden; scrollbar-gutter: stable; } body { overflow-x: hidden; } ```

### 部署后

1. Cloudflare 仪表盘 → 设置 → 函数 2. 添加 D1 绑定：变量名 `DB` → 选择您的数据库

### 参考文档

- 完整指南：`docs/issues/nextjs-cloudflare-d1-deployment.md` - Cloudflare 文档：https://developers.cloudflare.com/pages/framework-guides/nextjs/