Dev & Deploy Skill
快速开发并部署 Web 应用到 Cloudflare Pages，可选推送到 GitHub。
目标与范围
- 创建项目（基础页面 / 自定义 / 复用已有目录）
- 可选创建并推送 GitHub 仓库
- 可选部署到 Cloudflare Pages
- 访问测试与基础重试
AI 执行原则与安全限制（重要）
为避免破坏性行为和数据丢失，Agent 在执行此工作流时必须遵守以下确认流程，严禁在未获明确授权时进行高危自动化操作：
- 执行计划确认：在调用
deploy.js之前，必须简要向用户说明将要执行的参数和动作，并征得用户同意。 - 项目名称 (
--name) 必填：脚本强制要求提供--name参数。如果用户未提供，Agent 必须先向用户询问，不能随意编造或假定项目名称。 - 覆盖与文件修改：如果目标目录已存在，或使用了
--in-place、--source可能导致现有文件被覆盖，必须先向用户发出明确警告并获取授权。 - 远程推送与创建仓库：在进行 Git 提交、推送远程仓库或使用 GitHub CLI 创建仓库前，必须征求用户同意。若未经明确同意，必须加上
--skip-github。 - 部署权限：需要部署但未设置
CLOUDFLARE_API_TOKEN时，必须暂停并请求用户提供或由用户执行授权。 - 重要安全限制：需要使用
brew或npm install -g安装全局依赖（如gh,wrangler）时，必须先向用户申请权限，禁止在未授权时悄悄篡改系统环境。
失败恢复策略
- 读取错误信息并定位缺失项（依赖、登录、权限、参数）。
- 自动补齐后立即重试原命令。
- 连续失败时给出“最小下一步动作”，再请求用户输入。
前置检查与自动补齐
按需检查（不是所有命令都必须执行）：
node -v
git --version
gh --version
wrangler --version
gh auth status
wrangler whoami
安装指引（缺什么装什么，但在执行系统级安装前必须征求用户同意）：
# macOS
brew install node
brew install git
brew install gh
npm install -g wrangler
Cloudflare Token 指引（部署时必看）
- Token 管理页：https://dash.cloudflare.com/profile/api-tokens
- 官方文档：https://developers.cloudflare.com/fundamentals/api/get-started/create-token/
快速步骤：
- 打开 Token 管理页，点击
Create Token。 - 选择可用于 Pages/Wrangler 部署的模板（如
Edit Cloudflare Workers），或自定义最小权限。 - 资源范围限制到目标账号。
- 创建后复制 token（通常只显示一次）。
- 在当前终端注入：
export CLOUDFLARE_API_TOKEN=your_token_here
注意：在脚本、CI、AI Agent 等非交互环境中，即使执行过
wrangler login，也仍可能需要CLOUDFLARE_API_TOKEN。
使用方法
1) 自定义开发
node dev_deploy/deploy.js --name my-app --custom
2) 部署已有项目（复制到默认目录）
node dev_deploy/deploy.js --name my-app --source ./existing-project
3) 原地部署已有项目
node dev_deploy/deploy.js --name my-app --source ./existing-project --in-place
参数说明
| 参数 | 说明 | 示例 |
|---|---|---|
--name | 项目名称（必填，小写字母/数字/短横线） | todo-app |
--custom | 自定义开发模式 | - |
--source | 已有项目目录 | ./my-project |
--in-place | 原地部署（不复制） | - |
--projects-dir | 默认项目目录 | ~/projects |
--config | 配置文件路径 | ~/.config/dev-deploy/config.json |
--branch | Git 分支名 | main |
--public | 创建公开仓库（默认私有） | - |
--skip-test | 跳过访问测试 | - |
--skip-github | 跳过 GitHub 创建和推送 | - |
--skip-deploy | 跳过 Cloudflare 部署 | - |
配置优先级
命令行参数 > 环境变量 > 配置文件 > 默认值
环境变量：
export CLOUDFLARE_API_TOKEN=your_token_here
export PROJECTS_DIR=~/projects
export TEST_DELAY=5000
export MAX_RETRIES=3
export DEFAULT_DOMAIN=pages.dev
export DEFAULT_BRANCH=main
export PAGES_BUILD_OUTPUT_DIR=.
export DEV_DEPLOY_CONFIG=~/.config/dev-deploy/config.json
配置文件默认路径（取首个存在的）：
~/.config/dev-deploy/config.json~/.dev-deploy.json
标准执行流程（AI 必须严格遵循安全确认）
- 解析目标与参数：识别是否需要 GitHub / Cloudflare，明确必要的参数（如
--name）。 - 计划确认：向用户展示计划执行的命令及可能产生的文件/环境变更，等待用户授权。
- 环境检查与授权依赖安装：在征得同意的前提下，安装缺失的依赖。
- 执行
deploy.js：根据授权的参数执行脚本。 - 异常处理：失败则按报错提示用户或在授权范围内重试。
- 返回结果：输出本地路径、线上 URL 及后续的未完成项（若有）。
常见错误 -> 立即动作
wrangler: command not found->npm install -g wranglergh: command not found->brew install gh（或跳过 GitHub）non-interactive environment ... CLOUDFLARE_API_TOKEN-> 注入CLOUDFLARE_API_TOKEN后重试gh auth status失败 ->gh auth login后重试- 访问测试失败 -> 增大
TEST_DELAY或MAX_RETRIES