核心用法
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 子域，若名称冲突或域名未续费可能导致意外行为