all-deploy

all-deploy

检测、审计项目，并将其部署到合适的托管平台，确保预览 → 生产环境的流程经过确认。其独特价值在于检测 → 审计 → 路由到合适的 CLI，而不是封装 CLI。

配置（编辑以下行以更改默认行为）

CONFIRMATION_MODE: ask_at_start
  # ask_at_start (default): the skill asks at the start of each cloud deploy
  #                         whether to run full-auto or step-by-step.
  # full_auto:              skip the question. Audit → preview → prod with a
  #                         5-second ESC window before prod.
  # always_ask:             skip the question. Require explicit "yes" before prod.
VISUAL_VERIFY: false           # true → screenshot preview via chrome-bridge-automation (frontend only)
ALLOW_DIRTY_TREE: false        # true → skip the "HEAD is clean" audit check

默认的 ask_at_start 适用于个人开发者和社区用户——模式选择会推迟到运行时。只有在将此技能封装到无法交互式回答问题的自动化流程中时，才有必要固定为 full_auto 或 always_ask。

硬性规则（绝不可违反——这是安全约定）

1. 绝不绕过或放宽审计。 在 full_auto 模式下，审计是用户意图与线上基础设施之间唯一的关卡。如果某项检查无法运行，这本身就是阻止部署的理由，而不是跳过检查的理由。
2. 预览未成功且健康检查未返回 2xx/3xx 状态码时，绝不部署到生产环境。 预览 → 摘要 → 生产环境。同一会话中，预览未通过就不得部署到生产环境。（某些静态目标没有预览环境——例如 GitHub Pages、浏览器上传。此时，通过对确切的发布目录运行 python3 -m http.server 并以相同方式进行健康检查，来验证本地构建产物。关卡仍是强制的；变化的只有托管位置。）
3. 绝不提交、打印或记录密钥。 如果在受版本控制的文件中发现密钥，立即停止，并引导用户单独批准后执行移除密钥及重写历史的步骤。摘要、日志或提交消息中绝不出现密钥值。
4. 绝不自动安装或自动验证第三方 CLI。 将命令（带 ! 前缀）交给用户，例如 ! vercel login、! railway login。
5. 绝不用隐藏标志的自定义脚本封装目标 CLI。 参考文件记录的都是真实命令，用户可以阅读并验证。
6. 修改代码以通过审计前，必须先展示差异。 .gitignore、.env.example、Dockerfile 脚手架、端口绑定修复——应用前都必须展示并获得批准。
7. 除非设置了 ALLOW_DIRTY_TREE: true，否则绝不从有未提交更改的工作树部署。 未提交的更改会让回滚变得复杂。
8. 尊重“等等”。 预览与生产部署之间，用户只要说出任何类似犹豫的表达（等等/停一下/停止/还没准备好/中止），就应干净利落地取消生产部署步骤。

两种模式

根据用户的措辞，预先决定模式：

• 云端部署（默认）——执行以下第 0 至 6 阶段。触发语句：“deploy”“ship”“push to prod”“get it online”“/all-deploy”。
• 本地运行——执行第 0、1、2 阶段，然后执行本地运行步骤。触发语句：“run it locally”“corre esto localmente”“/all-deploy local”“just run it”或 --local。

项目类别（在云端部署流程中判定，不是第三种模式）

云端部署涵盖两种类型，系统会自动检测类别——绝不询问：

• app（默认）——具有运行时、启动命令和端口的服务。
• static——网站：托管平台会将一组文件复制到 CDN 上。没有服务器、端口或运行时。在下方的第 0.0 阶段分类。第 0、2、3.2、4、4.5、5 和 6 阶段会有所调整；完整调整说明请参阅 references/static-sites.md。

在本地运行模式下，执行限定范围的审计——仅检查受版本控制文件中的密钥、启动命令是否存在，以及端口绑定是否合理。跳过：git-remote、clean HEAD、npm audit/pip-audit、.env.example 完整性，以及环境变量交付（没有远程服务可供交付）。随后，在前台执行检测到的启动命令（npm run dev / uvicorn main:app --reload --host 0.0.0.0 --port $PORT / docker compose up 等），并通过 Monitor 流式输出。如果用户还要求公开本地服务器，则接入 references/targets/cloudflared-tunnel.md。本文件其余内容均与云端部署有关。

云端部署工作流

模式选择（在 ask_at_start 模式下，于 Phase 0 之前运行）

确定本次运行的有效 CONFIRMATION_MODE：

1. 如果用户的调用中包含明确的模式标记，则采用该模式并跳过提问：

   • 触发 full_auto 的标记："auto"、"full auto"、"auto deploy"、"deploy auto"、"/all-deploy auto"、"yolo"。
   • 触发 always_ask 的标记："step"、"step by step"、"one at a time"、"confirm each step"、"paso a paso"、"/all-deploy step"。

2. 否则，如果上方配置块中的 CONFIRMATION_MODE 已固定为 full_auto 或 always_ask，则使用该值并跳过提问。

3. 否则（默认值为 ask_at_start），在 Phase 0 运行前询问用户一次：

   "开始之前——你希望我如何执行部署？

   1. 全自动——我会依次运行审计 → 预览 → 提升到生产环境。生产环境部署会在 5 秒的 ESC 窗口后启动。 2. 逐步执行——在审计、预览和生产环境部署之间，我会停下来等你确认。

   请回复 'auto' 或 'step'。"

所选模式仅适用于本次运行——下次调用时会再次询问（除非用户通过触发短语明确选择，或配置块中的模式已固定）。

任何时候输入 "Wait" / "stop" / "hold" 都会中止生产环境部署步骤（两种模式均适用，见硬性规则 8）。区别在于：生产环境命令运行前，full_auto 会提供 5 秒的 ESC 窗口，而 always_ask 则会暂停并明确要求用户回复 "yes"。

Phase 0.0 — 项目类型（首先运行，先于先决条件检查）

如果存在 HTML 文件（位于根目录或 dist/、_site/、public/、build/、out/、site/ 中），且根目录不存在 package.json、pyproject.toml、requirements.txt、Pipfile、Dockerfile、docker-compose.yml、Procfile、go.mod、Gemfile 中的任何一个，则设置 PROJECT_CLASS: static。否则设置 PROJECT_CLASS: app。

清单文件检查可确保同时含有 index.html 的 Vite/Next/Astro 仓库仍走应用流水线。如果是 static，现在就读取 references/static-sites.md；其中的阶段表决定以下所有操作。

此步骤特意安排在 Phase 0 之前。先检查先决条件曾导致纯 HTML 文件夹因缺少实际上并不需要的 Git 远程地址而被拒绝。

Phase 0 — 先决条件（与目标无关）

按顺序检查。每项检查失败时，都以 ! 命令停止并告知用户。

1. Git 仓库。 运行 git rev-parse --is-inside-work-tree。如果当前目录不是仓库，除非模式为 run locally（不需要 Git），或 PROJECT_CLASS: static，否则停止——静态站点可以从普通文件夹部署。说明当前没有仓库，然后继续；相关决策将在 Phase 3.2 做出。未经提示，绝不运行 git init。
2. Git 远程地址（仅限云部署）。运行 git remote -v。如果未配置远程地址，则停止，除非目标为 docker-vps（无需远程地址即可部署），或 PROJECT_CLASS: static 且目标不是 GitHub Pages 或 Render——Cloudflare Pages 直接上传和 Netlify Drop 完全不需要仓库。第二项条件会在 Phase 3 之后重新评估。
3. 语言范围。 v1 可识别 Node 和 Python。如果主要语言是 Go、Rust、Ruby、Elixir、Bun 或 Deno，则退出并提示：*"v1 仅检测 Node/Python 生态系统。请直接运行目标 CLI（vercel、railway、flyctl、docker）。计划在 v2 中支持此语言。"当 PROJECT_CLASS: static 时不适用——HTML/CSS/JS 始终在支持范围内，无论是否需要构建步骤。

目标 CLI 的身份验证将在下方的 Phase 3.5 中检查，即选定目标之后。

Phase 0.5 — 权限提示预设（仅首次运行）

告知用户："在此项目上运行一次 fewer-permission-prompts 技能，将部署允许列表写入 .claude/settings.json——否则每一步都会弹出提示。" 仅作提示。此处绝不编辑用户的设置。

阶段 1 — 检测

阅读 references/project-types.md（相对于技能的路径——Claude 会根据已安装的技能目录解析该路径），查看完整的特征指纹表。检查：

• 包管理器与清单文件： package.json、pnpm-lock.yaml、yarn.lock、package-lock.json、bun.lockb、pyproject.toml、requirements.txt、poetry.lock、uv.lock、Pipfile。
• 框架信号： next.config.*、vite.config.*、astro.config.*、remix.config.*、nuxt.config.*、svelte.config.*、app/ 与 pages/ 的区别、包含 FastAPI()、Flask()、app = FastAPI() 的 main.py、server.py、根目录下的 index.html。
• 运行时版本： .nvmrc、.node-version、package.json 中的 engines、.python-version、pyproject.toml 中的 python_version。如果选择了长时间运行的目标，但未固定运行时版本，审计会阻止操作。
• 数据库 / 有状态依赖： 查找 sqlalchemy、psycopg、prisma、mongoose、redis、ioredis、sqlmodel 的导入。如果发现这些依赖，显示 "this service needs a database — provision one before prod"，并附上 Railway 参考文档中的插件命令。
• 端口 + 启动命令： uvicorn、gunicorn、next start、node server.js、python -m ...。检查是否绑定 0.0.0.0，以及是否使用 $PORT。仅绑定 localhost 的目标会被阻止用于长时间运行的部署。
• Monorepo： pnpm-workspace.yaml、turbo.json、nx.json、lerna.json，或根目录 package.json 中的 "workspaces" → 列出各个包，并询问要部署哪一个。不要猜测。
• 库 / CLI（不是 Web 部署）： Node 信号——package.json 中存在 bin: 字段，或（存在 files: 数组、没有 scripts.start，且没有 express、fastify、hono、next、koa 等 HTTP 框架导入）。Python 信号——pyproject.toml 中存在 [project.scripts] / console_scripts，且声明的脚本或导入中没有 uvicorn/gunicorn/flask/fastapi。不要仅凭 main: 判断为库——几乎所有 Node Web 应用也会设置 main:。正常退出并提示："This looks like a package — /all-deploy targets web services, not npm/PyPI publishes."
• 现有部署配置： vercel.json、railway.toml、fly.toml、Dockerfile、render.yaml——应予以保留并审计，除非用户明确要求，否则不要重新生成。
• 现有项目关联： .vercel/project.json → 重用该 Vercel 项目 ID。railway.toml 中包含 project 字段 → 重用该项目。重新部署是常见情况；只有明确要求“从头开始”时才创建全新项目。

**当 PROJECT_CLASS: static 时，**跳过框架 / 运行时 / 端口 / 数据库 / Monorepo 特征检测。只检测三项：发布目录（存放 index.html 的文件夹——., dist/, _site/, public/, build/, out/, site/）、是否存在构建步骤，以及是否存在 git 仓库。发布目录表见 references/static-sites.md；判断错误是导致线上网站在 / 返回 404 的最常见原因。

输出：分类信息块，以及按优先级排序的候选目标列表，每个目标附一行理由。完整的目标排序规则见 references/project-types.md。

阶段 2 — 审计（严格阻断）

针对当前项目目录运行此技能随附的审计脚本（scripts/audit.py）。Claude 会在加载时解析技能路径 — 调用方式如下：

python3 <SKILL_DIR>/scripts/audit.py <project-path>

当 PROJECT_CLASS: static 时：

python3 <SKILL_DIR>/scripts/audit.py <project-path> --profile static --publish-dir <dir> [--target <name>]

这会跳过所有假定存在依赖树、启动命令、端口或 git 远程仓库的检查 — 在纯 HTML 文件夹上运行这些检查会产生误报的严重问题 — 并改为运行 scripts/static_check.py。如果选择的目标是 GitHub Pages，请传入 --target github-pages：它是唯一确实需要远程仓库的静态目标，也是唯一需要关注 .nojekyll 和根相对路径的目标。检查清单见 references/static-sites.md。

其中，<SKILL_DIR> 是技能的安装位置（通常为 ~/.claude/skills/all-deploy/），<project-path> 通常为 .。脚本会检查 references/audit-checklist.md 中的所有项目：受版本控制文件中的密钥、.gitignore 覆盖情况、锁文件合理性、.env.example 完整性（通过 scripts/env_extract.py）、构建／启动脚本是否存在、端口绑定、HEAD 是否干净、git 远程仓库是否匹配、npm audit --production --audit-level=high 或 pip-audit。

任何失败都会中止流程。对于每个问题，展示修复差异（如适用），并等待用户确认后再应用。自动模式不会绕过审计。

Git 历史中的密钥扫描由用户手动运行，不会自动执行。在审计输出中，将以下命令作为单独步骤提示：trufflehog git file://. 或 git log -p -S 'sk_' -S 'AKIA' -S 'ghp_'。此技能绝不会重写 git 历史。

阶段 3 — 选择目标

展示阶段 1 排名靠前的候选项，并分别用一句话说明理由。由用户选择，或回复“ok”接受首选项。此时才加载目标参考文档：

• references/targets/vercel.md — Next、Vite、Astro、Remix、Nuxt、SvelteKit、静态站点
• references/targets/railway.md — FastAPI、Flask、Express、Python 工作进程、MCP HTTP、Claude Agent SDK
• references/targets/docker-vps.md — 任意 Dockerfile、有状态工作负载、可自托管
• references/targets/cloudflared-tunnel.md — 暴露本地开发环境、快速演示
• references/targets/cloudflare-pages.md — 静态站点；有人因该页面获得报酬时的默认首选项
• references/targets/netlify.md — 需要表单的静态站点；拖放式部署
• references/targets/github-pages.md — 已托管在 GitHub 上的作品集、文档、演示
• references/targets/render.md — 静态站点、低流量

对于 PROJECT_CLASS: static，在展示候选项之前先阅读 references/static-hosting.md。该文档包含平台比较、免费套餐限制和商业用途矩阵 — 以及真正决定排名的问题：“是否有人会因为此页面而获得报酬？” 如果答案是肯定的，就不能选择 Vercel Hobby（根据其公平使用条款，“因创建、更新或托管网站而收取报酬”属于商业用途），通常也不能选择 GitHub Pages。

对于 Agent 类项目，还要加载 references/agents.md，了解针对不同 Agent 类型的调整（FastAPI／Flask HTTP、MCP stdio 与 HTTP、Claude Agent SDK 脚本、通用 Python 工作进程）。

阶段 3.2 — git 决策（静态项目、无仓库）

仅当 PROJECT_CLASS: static 且不存在 git 仓库时，才询问一次，并说明后果，因为这决定了哪些目标可用：

“你之后想通过推送更改来更新页面，还是只打算部署一次？”

• 想推送更新 → 需要创建仓库。展示 git init -b main、git add -A && git commit -m "Initial site" 和 gh repo create <NAME> --public --source=. --push。运行最后一条命令前必须确认 — 它会将代码发布到用户的 GitHub 账户下。如果 gh 尚未通过身份验证，则提示用户运行 ! gh auth login 并等待（硬性规则 4）。
• 只部署一次，或没有 GitHub 账户 → 引导用户使用 Cloudflare Pages 直接上传或 Netlify Drop，并明确说明之后更新时需要再次上传整个文件夹。不要等到部署完成后才让他们发现这一点。

阶段 3.5 — 已安装并完成身份验证的目标 CLI

选定目标后，验证其 CLI 是否已安装并完成身份验证。不要自动安装或登录——向用户提供命令，并在命令前加上 !。

• Vercel： vercel whoami（安装：npm i -g vercel；登录：! vercel login）。
• Railway： railway whoami（安装：npm i -g @railway/cli 或 brew install railway；登录：! railway login）。
• Docker + SSH： ssh -o BatchMode=yes <host> true（需要预先配置 SSH 密钥）；在本地运行 docker --version。
• cloudflared： cloudflared tunnel list（安装：brew install cloudflared；登录：! cloudflared tunnel login）。
• Cloudflare Pages： npx wrangler whoami（安装：! npm i -D wrangler@latest；登录：! npx wrangler login）。
• Netlify： netlify status（安装：! npm install -g netlify-cli；登录：! netlify login）。
• GitHub Pages： gh auth status（安装：! brew install gh；登录：! gh auth login）。
• Render： 使用控制面板或 render.yaml；CLI（render login）为可选项，且尚未验证是否可用于创建静态网站。

如果检查失败，请停止并告知安装或登录命令。用户完成后，从阶段 3.5 继续。

无 CLI 分支（静态类别）。 不要安装任何内容（硬性规则 4）。当 PROJECT_CLASS: static 且目标的 CLI 不在 PATH 中时，提供两种方案供用户选择，并默认推荐浏览器方案：

1. 自行安装 — 提供命令，并在命令前加上 !。
2. 使用浏览器 — 将发布文件夹拖到 Cloudflare Pages（Workers & Pages → Create → Pages → Upload assets）或 Netlify Drop，或者在 github.com 上传（Add file → Upload files，然后进入 Settings → Pages）。

除 Render 外，所有静态目标都提供完整的浏览器操作路径。没有终端的用户也不会受阻，只需选择方案 2 即可。

阶段 4 — 执行（始终先预览）+ 环境变量交付

遵循目标平台参考文档中的预览流程。第一轮始终使用预览／暂存环境——此阶段绝不使用 --prod。

处理长时间运行的命令。 部署命令需要 3–10 分钟；Bash 默认的 2 分钟超时会将其终止。

• 默认方式： 使用 Bash 工具运行部署命令，并设置 run_in_background: true。CLI 退出时，你会收到完成通知；此时 Read Bash 输出文件，以解析 URL 并检测错误。不要串联 sleep 循环。
• 需要提前获取一行输出时（例如，Railway 在运行过程中打印预览 URL，cloudflared 在完成启动前打印隧道 URL）：使用 Monitor 工具监视同一输出文件，并使用匹配 URL 格式和已知错误标记（Traceback、FAILED、error:）的正则表达式。Monitor 会在每次匹配时发出通知；Phase 4.5 会探测第一个匹配到的 URL。

环境变量交付（运行预览前）。以用户本地的 .env 为准（绝不提交）。将所需键推送到目标平台：

• Vercel： 执行 vercel env add <KEY> preview，然后执行 vercel env add <KEY> production（粘贴值，或通过管道传入——echo -n "$value" | vercel env add <KEY> <env>）。使用 vercel env ls 验证。
• Railway： 执行 railway variables --set "KEY=value"——每个键调用一次。没有批量导入选项；在 shell 中循环读取本地 .env（参见 references/targets/railway.md）。
• Docker+SSH： 执行 scp .env.production user@host:/app/.env，或使用 docker-compose.yml 中的 environment: 块。
• cloudflared： 继承本地环境；不需要远程变量。
• **静态类平台（Cloudflare Pages、Netlify、GitHub Pages、Render、Vercel static）：**跳过此阶段，并说明原因。 发布目录中的所有内容都会公开提供。构建时变量（VITE_*、PUBLIC_*、NEXT_PUBLIC_*）会在构建时内联到 JavaScript 包中——仓库设为私有也无济于事，因为实际提供的不是仓库。绝不要提出“把它放进环境变量，这样就能保密”；对于静态网站，这种说法是错误的。合法例外是设计上可公开发布的键（Stripe pk_、限制了引用来源的 Google Maps 键）以及公开的构建时值——可以发布，但要明确说明它们是公开的。其他任何内容都需要服务器：说明这一点，并切换到应用部署流程。详见 references/static-sites.md。

绝不打印值。只确认键。

阶段 4.5 — 预览健康检查（阻断性）

从部署 CLI 的标准输出中捕获预览 URL。 每个目标参考文档都说明了确切的解析步骤；示例：

• **Vercel：**预览 URL 会打印在标准输出最后一个非空行，格式类似 https://<project>-<hash>-<scope>.vercel.app。
• **Railway：**在 railway up 的输出中查找 Deployment live at <url>。
• **Docker+SSH：**URL 是用户配置的 http://<host>[:port]——技能必须询问用户，或根据 docker-compose.yml 端口映射推导。
• **cloudflared：**URL 会以 https://<random>.trycloudflare.com 或已配置的主机名形式打印。

将捕获的 URL 赋给 $PREVIEW_URL，然后进行探测：

curl -sSL -o /dev/null -w "%{http_code}" "$PREVIEW_URL"

（不要使用 -f——否则 HTTP 错误时会抑制 %{http_code} 的输出。-sSL 会让 curl 在成功时保持静默，但仍会报告传输错误并跟随重定向。）

静态类——还要探测入口页面引用的第一个样式表：

curl -sSL -o /dev/null -w "%{http_code}" "$PREVIEW_URL/<first-stylesheet-href>"

/ 返回 200，但 /estilo.css 返回 404，这正是文件名大小写错误在生产环境中的表现，而仅探测根路径会将该部署报告为成功。

状态为 2xx 或 3xx 时进入阶段 5。若状态为 4xx/5xx、输出为空（连接被拒绝、DNS 故障），或 curl 退出码非零 → 停止。使用目标对应的日志命令（vercel logs、railway logs、ssh ... 'docker compose logs'）报告故障端点。不要进入下一阶段。

可选的视觉验证。 如果 VISUAL_VERIFY: true 且项目是前端，请使用 chrome-bridge-automation 截取预览页面，并确认页面正常渲染（不是空白页，也不是错误页面）。curl 返回 2xx/3xx 仍是放行条件；截图只是额外验证。

阶段 5 — 发布到生产环境

在 full_auto 模式下，审核和预览健康检查都通过后：

1. 打印一个单屏摘要块：目标 URL、即将运行的确切命令、DNS 影响（如有）、费用影响。关于价格，优先使用实时 deep-research 查询 Vercel/Railway 当前定价。如果无法查询，请链接到提供商的定价页面。不要在此文件中硬编码套餐价格。
2. 打印：“5 秒后发布到生产环境——按 ESC 中断。” 然后通过 Bash 工具单独调用一次真正的 sleep 5。这不是做做样子——在这段休眠期间按 ESC 确实会停止本轮。如果用户中断，不要在恢复后执行生产命令；应询问用户想改为执行什么操作。
3. 休眠正常结束后，通过单独的 Bash 调用执行生产命令，并设置 run_in_background: true。等待完成通知，然后 Read Bash 输出文件以提取生产 URL。只有在需要 CLI 退出前解析 URL 时（Railway、cloudflared），才对同一输出文件使用 Monitor。

在 always_ask 模式下，跳过步骤 2–3；执行生产命令前必须在当前轮次获得明确的“是”。不执行休眠。

静态类——不支持从预览发布到生产环境的目标。 Cloudflare Pages（--branch）和 Netlify（--prod）行为正常。有三个目标不支持：

目标	实际情况
Vercel	暂停——但新项目的首次部署始终会部署到生产环境，即使没有 --prod 也是如此。执行前请说明这一点
GitHub Pages	一个分支对应一个站点。没有预览环境
Direct upload / Netlify Drop	上传本身就是生产部署

对于最后两个目标，为满足硬性规则 2，应在本地提供确切的发布目录并进行健康检查——无需安装，Python 自带：

python3 -m http.server -d <PUBLISH_DIR> 8000
curl -sSL -o /dev/null -w "%{http_code}" http://localhost:8000

提供发布目录，而不是项目根目录——提供项目根目录会掩盖这项检查旨在发现的“目录错误”问题。然后在常规确认后发布一次。

尊重用户在预览后的中断意图。 如果从预览到生产部署之间，用户输入任何类似犹豫的内容（wait/hold/stop/not yet/abort），不要继续发布到生产环境——将预览视为最后一个通过检查的状态，并等待用户明确指示。

阶段 6 — 部署后验证 + 展示回滚方式

• Curl 生产环境 URL；确认状态。
• 确认远程环境已设置环境变量（vercel env ls、railway variables、ssh ... 'docker compose config'）。
• 打印此目标的回滚方式（用户之后需要时可复制）：
  • Vercel：vercel rollback（交互式选择器）或 vercel rollback <previous-deployment-url> — 请确认当前 CLI 语法。
  • Railway：没有一流的 rollback 命令。重新部署之前的提交：git checkout <prev-sha> && railway up && git checkout -，或者在控制面板的 Deployments → 选择之前的构建并点击“Redeploy”。
  • Docker+SSH：重新标记之前的镜像后运行 ssh <host> 'docker compose up -d --no-deps <service>'，或者重新 rsync 之前的 SHA 并重新构建。两种流程请参阅 references/targets/docker-vps.md。
• 打印日志尾部命令：vercel logs <url> --follow、railway logs --follow、ssh <host> 'cd /app && docker compose logs -f'。

静态类。 与“之后要怎么修改”相比，回滚在这里没那么重要，而这才是这类用户真正会问的问题——两方面都要说明。Cloudflare Pages 和 Netlify 可在控制面板中回滚到之前的部署（两者都没有对应的 CLI 命令）。GitHub Pages 可通过 git revert <sha> && git push 回滚。直接上传或 Drop 则完全无法回滚，只能重新上传之前的文件夹——所以请告诉用户在发布前保留一份副本。 如果用户需要自定义域名，请提供 references/custom-domain.md，并明确说明托管免费，但域名不免费（每年约 10–15 美元）。

目标选择 — 排序标准（快速参考）

项目信号	首选方案	原因
纯 HTML/CSS/JS 文件夹、客户页面或任何付费项目	Cloudflare Pages	免费、没有商业用途限制、没有部署额度骤降问题
需要联系表单但没有后端的静态网站	Netlify	Netlify Forms 免费；请留意 300 点额度
已在 GitHub 上的作品集、文档或演示项目	GitHub Pages	无需新建账号；不适用于网上商店（有商业用途限制）
流量较低且已在 Render 上的静态网站	Render	这种规模下足够用——免费层每月有 5 GB
存在 next.config.*、vite.config.*、astro.config.*、SPA、SSG	Vercel	零配置、预览 URL、边缘网络。Hobby 仅限非商业用途
使用长时间运行服务器的 FastAPI / Flask / Express	Railway	部署简单、快速，可添加数据库
存在任何 Dockerfile，需要数据库/卷，偏好自托管	Docker + SSH VPS	完全掌控，适合有状态服务
本地开发服务正在运行，想要快速获得公开 URL	cloudflared 隧道	无需主机，即时可用
MCP 服务	Railway（HTTP 模式）或 Docker+SSH	请参阅 references/agents.md
Claude Agent SDK 脚本	Railway（worker 模式）或 cron	请参阅 references/agents.md

如果信号相互冲突，请说明理由，列出最优的两个方案并让用户选择。

随附资源

• scripts/audit.py — 确定性部署前审计。在阶段 2 中调用。
• scripts/env_extract.py — 扫描源代码中的环境变量用法，供审计验证 .env.example 是否完整。
• scripts/static_check.py — 静态网站检查。在调用 audit.py --profile static 时运行，也可以单独运行。
• references/project-types.md — 完整的框架特征识别表。
• references/audit-checklist.md — 逐条说明所有审计规则，并提供修复指引。
• references/env-mapping.md — 环境变量如何在本地 .env 与各目标之间传递。
• references/agents.md — 四种 Agent 形态及各类型对应的部署调整。
• references/static-sites.md — 静态项目类别：发布目录、阶段调整和静态检查。
• references/static-hosting.md — 对比五种免费的静态托管服务，包括商业用途矩阵。
• references/custom-domain.md — 各托管服务的 DNS 记录、顶级域名与 www 的区别，以及等待期间的注意事项。
• references/targets/*.md — 每个目标对应一份操作指南，仅在阶段 3 之后加载。
• assets/templates/ — Dockerfile.node、Dockerfile.python、docker-compose.example.yml、.env.example.template。

平台说明

• v1 仅支持 macOS 和 Linux。 Windows 社区用户应使用 WSL2，以确保路径和 Shell 兼容性。
• 所有命令均假设使用 bash/zsh。路径采用 POSIX 约定。
• 所有云端模式都需要网络；run locally 模式可离线运行。