name: Dev & Deploy slug: dev-deploy version: 1.4.0 description: 快速建立並部署 Web 應用到 Cloudflare Pages；包含檔案覆蓋、Git推送與系統修改的安全確認機制。 metadata: {"clawdbot":{"emoji":"🚀","requires":{"bins":["node","git","gh","wrangler"],"env":["CLOUDFLARE_API_TOKEN"]},"os":["darwin","linux","win32"]}}

Dev & Deploy Skill

快速開發並部署 Web 應用到 Cloudflare Pages，可選推送到 GitHub。

目標與範圍

• 建立專案（基礎頁面 / 自定義 / 複用已有目錄）
• 可選建立並推送 GitHub 倉庫
• 可選部署到 Cloudflare Pages
• 訪問測試與基礎重試

AI 執行原則與安全限制（重要）

為避免破壞性行為和資料丟失，Agent 在執行此工作流時必須遵守以下確認流程，嚴禁在未獲明確授權時進行高危自動化操作：

1. 執行計劃確認：在呼叫 deploy.js 之前，必須簡要向用戶說明將要執行的引數和動作，並徵得使用者同意。
2. 專案名稱 (--name) 必填：指令碼強制要求提供 --name 引數。如果使用者未提供，Agent 必須先向使用者詢問，不能隨意編造或假定專案名稱。
3. 覆蓋與檔案修改：如果目標目錄已存在，或使用了 --in-place、--source 可能導致現有檔案被覆蓋，必須先向使用者發出明確警告並獲取授權。
4. 遠端推送與建立倉庫：在進行 Git 提交、推送遠端倉庫或使用 GitHub CLI 建立倉庫前，必須徵求使用者同意。若未經明確同意，必須加上 --skip-github。
5. 部署許可權：需要部署但未設定 CLOUDFLARE_API_TOKEN 時，必須暫停並請求使用者提供或由使用者執行授權。
6. 重要安全限制：需要使用 brew 或 npm install -g 安裝全域性依賴（如 gh, wrangler）時，必須先向使用者申請許可權，禁止在未授權時悄悄篡改系統環境。

失敗恢復策略

1. 讀取錯誤資訊並定位缺失項（依賴、登入、許可權、引數）。
2. 自動補齊後立即重試原命令。
3. 連續失敗時給出“最小下一步動作”，再請求使用者輸入。

前置檢查與自動補齊

按需檢查（不是所有命令都必須執行）：

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/

快速步驟：

1. 開啟 Token 管理頁，點選 Create Token。
2. 選擇可用於 Pages/Wrangler 部署的模板（如 Edit Cloudflare Workers），或自定義最小許可權。
3. 資源範圍限制到目標賬號。
4. 建立後複製 token（通常只顯示一次）。
5. 在當前終端注入：

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

引數說明

配置優先順序

命令列引數 > 環境變數 > 配置檔案 > 預設值

環境變數：

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 必須嚴格遵循安全確認）

1. 解析目標與引數：識別是否需要 GitHub / Cloudflare，明確必要的引數（如 --name）。
2. 計劃確認：向用戶展示計劃執行的命令及可能產生的檔案/環境變更，等待使用者授權。
3. 環境檢查與授權依賴安裝：在徵得同意的前提下，安裝缺失的依賴。
4. 執行 deploy.js：根據授權的引數執行指令碼。
5. 異常處理：失敗則按報錯提示使用者或在授權範圍內重試。
6. 返回結果：輸出本地路徑、線上 URL 及後續的未完成項（若有）。

常見錯誤 -> 立即動作

7w4.net小蔥技能。

• wrangler: command not found -> npm install -g wrangler
• gh: 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

整體質量較好。文件非常詳細，使用說明清晰易懂；安全確認機制做得很到位，執行危險操作前會主動提示確認，不用擔心被誤操作；配置方式靈活，可以適應不同使用習慣；錯誤提示也比較友好。不足之處是部署指令碼功能較多但沒有拆分，長期使用和維護可能存在隱患。適合需要頻繁部署專案到 Cloudflare Pages 的使用者使用。