C.R.A.B Deploy Agent

核心用法

deploy-agent 是一款面向全栈应用的多阶段部署自动化工具，采用「人工审批制」工作流，将复杂的部署流程拆解为 5 个可控步骤：设计初始化 → 本地构建 → 本地测试 → GitHub 推送 → Cloudflare Pages 部署。用户通过 init/build/test/push/deploy 命令逐步推进，每完成一个阶段需人工确认后才进入下一阶段，有效避免误操作导致的生产事故。

工具内置状态管理（~/.clawdbot/skills/deploy-agent/state/），支持跨会话持久化，可随时通过 status 查看进度、continue 获取下一步指引、cancel 安全中止。特别针对 Next.js + Cloudflare D1 场景提供了详尽的部署指南，涵盖版本锁定、适配器配置、Edge Runtime 声明、构建命令等关键配置，并附带常见问题修复方案。

显著优点

1. 分阶段人工把控：不同于全自动 CI/CD，每个关键节点强制人工确认，适合对稳定性要求高的场景
2. 开箱即用的 D1 支持：深度适配 Cloudflare 生态，尤其针对 Next.js + D1 的常见陷阱（版本兼容、Edge Runtime、getRequestContext 模式）提供一站式解决方案
3. 状态持久化：本地 JSON 状态文件记录完整部署链路，支持中断后继续
4. 清晰的命令语义：命令设计符合直觉（init/build/test/push/deploy），学习成本低

潜在缺点与局限性

• 依赖外部 CLI 生态：强制依赖 gh（GitHub CLI）、wrangler（Cloudflare）、git、jq，任一工具缺失或版本不兼容将导致失败
• 单点部署目标：目前仅支持 Cloudflare Pages，不支持 Vercel/Netlify/AWS 等其他平台
• 人工审批的代价：适合小团队/个人项目，大规模团队协作可能成为瓶颈
• Next.js 版本锁定：D1 适配章节明确要求 next@15.5.2，新版本兼容性存疑
• 安全凭证本地管理：Cloudflare token 存储于 ~/.wrangler.toml，存在本地泄露风险

适合人群

• 个人开发者快速上线全栈项目
• 小团队寻求比纯手动部署更规范、比全自动 CI/CD 更可控的中间方案
• 使用 Cloudflare 生态（Pages + D1）的 Next.js 开发者

常规风险

1. 凭证安全：wrangler.toml 中的 API token 若未妥善设置权限（建议最小权限原则），可能导致账户被接管
2. 状态文件污染：本地 JSON 状态文件损坏可能导致部署状态混乱，建议定期备份或清理
3. GitHub 仓库权限：gh CLI 的认证状态决定仓库创建权限，需确保已登录且具备组织仓库创建权限（如适用）
4. 域名接管：默认使用 {name}.sheraj.org 子域，若名称冲突或域名未续费可能导致意外行为

核心用法

deploy-agent 是一个命令行驱动的多阶段部署工作流管理器，专为全栈应用（特别是 Next.js + Cloudflare D1 架构）设计。核心交互模式采用"状态机 + 人工审批"设计：

1. 初始化 (deploy-agent init <name>) - 创建部署状态，进入设计阶段
2. 构建 (deploy-agent build <name>) - 本地编译，需确认后进入测试
3. 测试 (deploy-agent test <name>) - 本地验证运行状态
4. 推送 (deploy-agent push <name> [repo]) - 自动创建 GitHub 仓库并推送
5. 部署 (deploy-agent deploy <name> [domain]) - 通过 Wrangler 部署至 Cloudflare Pages

状态持久化存储于 ~/.clawdbot/skills/deploy-agent/state/，支持跨会话恢复。工具深度集成 gh CLI 与 wrangler，对外部服务的调用均通过受信二进制间接完成。

显著优点

• 分阶段安全闸门：每个关键步骤强制人工确认，避免误操作导致的生产事故
• 零配置感知：自动检测 Next.js 版本、Cloudflare 适配器、D1 绑定等常见配置陷阱，内置修复指南
• 状态可追溯：JSON 格式的状态文件记录完整部署链路（创建时间、仓库地址、域名）
• 供应链精简：无 npm/pip 依赖，仅依赖系统级可信工具（git/gh/wrangler/jq）
• 边缘运行时原生支持：针对 Cloudflare Pages 的 Edge Runtime 提供显式配置模板

潜在局限

• T3 来源可信度：社区项目（sherajdev），无 GitHub 仓库背书，无法验证作者历史信誉
• 输入验证薄弱：应用名称仅做空值检查，未限制特殊字符或路径遍历序列（../）
• 许可证缺失：未声明开源许可证，存在法律合规盲区
• 错误处理待完善：网络中断或 CLI 工具未认证场景缺乏重试与引导机制
• 平台锁定：深度绑定 Cloudflare Pages 与 GitHub，迁移成本较高

适合人群

• 需要结构化部署流程的个人开发者或小型团队
• 使用 Next.js + Cloudflare D1 技术栈的全栈开发者
• 偏好命令行工作流、追求部署过程可控性的用户
• 已配置 gh 与 wrangler 认证、熟悉基础 DevOps 流程的技术人员

常规风险

| 风险类别 | 具体表现 | 缓解措施 |

|---------|---------|---------|

| 路径遍历 | 恶意构造的 `<name>` 参数可能越界写入 | 自行添加正则验证 `^[a-zA-Z0-9_-]+$` |

| 凭证泄露 | `~/.wrangler.toml` 中的 Cloudflare Token 权限过大 | 使用最小权限 Token，定期轮换 |

| 供应链攻击 | `gh`/`wrangler` 二进制被篡改 | 通过官方渠道安装，校验签名 |

| 部署中断 | 网络波动导致 `wrangler deploy` 失败 | 工具内无自动重试，需手动 `continue` |

总体评估：功能与声明一致，代码结构清晰，无恶意行为迹象，适合在可控环境下用于个人项目或内部工具链。建议在生产使用前完成输入验证加固与许可证声明补充。