cloudflare-pages-ops

cloudflare-pages-ops

概述

此技能让 Agent 优先使用 CLI（Wrangler CLI）执行 Cloudflare Pages 操作，并在必要时通过 Cloudflare 官方 API 回退到 REST——不使用 SDK。Wrangler 是便捷的常用路径（创建项目、部署构建目录）；REST API 则涵盖更全面的其他操作（自定义域名、部署状态、项目／部署／域名管理），其依据是打包的 Pages OpenAPI 片段，通过端点索引和 $ref 解析器进行查询，因此不会将规范加载到上下文中。Agent 使用调用方注入的 account_id 和令牌，选择 Wrangler 命令或 REST 操作，执行后解析结果。它面向 Cloudflare Pages 的静态／JAMstack 和无服务器功能，不用于全栈容器托管。

何时启用

• ✅ 创建 Pages 项目，或向其部署构建目录（Direct Upload）。
• ✅ 添加／列出自定义域名，或读取部署状态（阶段状态机）。
• ✅ 列出／检查／删除项目、部署（重试／回滚）或域名。

以下情况请勿启用：

• 需要全栈容器／应用托管（Render、Fly.io、Railway、Vercel SSR-as-PaaS）——此处的 Cloudflare Pages 仅用于静态／JAMstack 和无服务器托管。
• 只需设置凭据——凭据由调用方提供；此技能不会配置或解析凭据，也绝不会运行 wrangler login（参见 references/credentials.md）。

工作流

步骤 1 — 接收注入的凭据

调用方已解析账户并注入此操作所需的信息——请直接使用，不要查找记录或登录。你会从上下文中收到：

• account_id（非机密的纯上下文值——导出为 CLOUDFLARE_ACCOUNT_ID 并插入 REST 路径）和能力（web-hosting）。
• 令牌，按有序加载规则获取：上下文中会提供该变量的名称。若项目级 .env 文件存在且定义了该变量，则使用其中的值；否则使用同名的环境变量（优先使用项目 .env）。令牌值不会出现在上下文说明中——其中只有变量名。不要进行任何作用域解析或目录遍历；使用项目 .env，而非 .envrc。

将其传入 CLOUDFLARE_API_TOKEN（Bearer）和 CLOUDFLARE_ACCOUNT_ID。绝不要运行 wrangler login。完整约定：references/credentials.md。

步骤 2 — 选择常用路径（Wrangler）或其他操作（REST）

• **Wrangler（常用路径）：**在 assets/cli-index.md 中查找 pages project create、pages deploy、pages project list、pages deployment list/tail。详情：references/wrangler.md。
• **REST（其他操作）：**在 assets/endpoint-index.md 中查找，然后运行 python3 scripts/endpoint.py <operationId>，解析参数、请求正文和 curl 命令框架。详情：references/rest-api.md。绝不要将打包的片段加载到上下文中。

步骤 3 — 执行

打包的四个脚本涵盖优先操作：

• create-project.sh <name> [branch] — wrangler pages project create … --production-branch …（Direct-Upload 项目）。
• deploy.sh <project> <dir> [branch] — wrangler pages deploy … --commit-dirty true（上传构建目录）。
• add-custom-domain.sh <project> <domain> — REST POST …/domains（Wrangler 没有域名命令）。
• deployment-status.sh <project> <deployment-id> — REST get-deployment-info（阶段状态机）。

其他操作：使用 cli-index.md 中的 Wrangler 命令，或针对已解析的 REST 操作发起 curl 请求。

步骤 4 — 处理响应

• 先获取部署 ID。 deploy.sh（Wrangler）只会输出文本，不会输出 deployment-status.sh 所需的 ID；请用 wrangler pages deployment list --project-name <name> --json | jq -r '.[0].Id' 获取（deployment list --json 返回的表格键首字母大写，因此应使用 .Id，而不是 .id）。
• 部署是异步且分阶段进行的。 部署会依次经过 latest_stage.name ∈ queued/initialize/clone_repo/build/deploy，且 status ∈ success/idle/active/failure/canceled。轮询 deployment-status.sh，直到 deploy 阶段达到 status: success（完成）或任何阶段出现 failure。
• 检查响应封装内容，而不只是 HTTP 状态。 每个 REST 响应的格式都是 {success, errors, messages, result}——即使状态码为 200，也可能包含 success: false；请读取 errors[].code/message。
• 自定义域名 ≠ DNS。 添加域名时，必须先将其添加到 Cloudflare 区域，并将 DNS 指向该项目。
• **限制：**每位用户每 5 分钟 1,200 次请求 → HTTP 429。

规则

硬性规则（绝不违反）：

• 绝不要运行 wrangler login。 身份验证使用注入的 CLOUDFLARE_API_TOKEN + CLOUDFLARE_ACCOUNT_ID；Wrangler 以无头模式运行。缺少 token/account_id 是调用方错误，不能因此尝试登录。
• 绝不要读取或打印 token 值。 只能通过 $CLOUDFLARE_API_TOKEN 引用它（环境变量 / Bearer）；子进程会从环境中读取它。token 只存放在 .env（已加入 gitignore）或环境变量中。account_id 是非机密上下文，不是秘密。
• 使用 Wrangler 部署目录，不要使用 curl。 REST create-deployment 的请求体是 multipart/form-data；绝不要用 curl 手动拼装目录部署请求。
• 先解析，再构造 REST 调用。 根据通过 $ref 解析的架构（endpoint.py）构建请求体/参数——不要猜测字段集合。
• 检查 success，而不只是 HTTP 状态。 success:false 的 200 响应表示失败——请读取 errors[]。
• 此技能绝不写入凭据。 凭据由调用方提供。

偏好（可覆盖）：

• 对 wrangler pages project list / deployment list 传入 --json，以获取机器可读的输出。
• 从有未提交更改的工作树部署时，使用 --commit-dirty true。
• 自定义域名和单个部署的状态使用 REST（Wrangler 没有对应命令）。

注意事项

• 不要登录。 当 token“无法使用”时尝试运行 wrangler login 违反了约定——错误的 token/account_id 应作为错误报告，而不是触发登录。
• 无头模式下必须提供 CLOUDFLARE_ACCOUNT_ID。 Wrangler 除 token 外还需要该值；缺少 account id 是 CI 中最常见的故障。
• 部署使用 multipart。 REST 部署端点采用 multipart/form-data（二进制部分）——请使用 wrangler pages deploy <dir>；不要以 JSON 方式 POST 部署请求。
• Direct Upload 与 Git-connected。 wrangler pages deploy 适用于 Direct-Upload 项目；Git-connected 项目通过 git push 部署，Wrangler 不会部署该项目。（Direct-Upload 项目之后无法切换为 Git。）
• 响应封装可能隐藏失败。 {success:false} 可能出现在状态码为 200 的响应中；务必检查。
• 自定义域名需要 DNS——API 不会创建 DNS 记录。 add-custom-domain.sh 只会注册域名（status: initializing）；REST POST /domains 不会创建 DNS 记录，即使区域属于同一账户也不会（只有控制面板会自动创建）。在区域中创建 CNAME <domain> -> <project>.pages.dev 记录之前，验证会一直处于待处理状态（“CNAME record not set”）；而 Pages 范围的 token 无法创建该记录（需要 Zone DNS:Edit），因此调用方须在其他途径添加记录。
• pages deploy <dir> 只会上传，不会构建。 请传入已构建的输出目录（dist/build/…）；Wrangler 不会运行你的框架构建流程。
• 速率限制。 每位用户每 5 分钟累计最多 1,200 次请求；遇到 429 时请退避重试。

反模式

• 运行 wrangler login。 禁止——契约会注入令牌；切勿自行处理身份验证，也不要提示用户登录。
• 回显令牌。 切勿运行 echo $CLOUDFLARE_API_TOKEN，切勿将其粘贴到打印出的命令中，也切勿将其值写入文件。仅引用环境变量。（account_id 不是机密，可以出现在路径中。）
• 通过 REST 手动实现目录部署。 部署采用 multipart 格式——请使用 Wrangler。
• 猜测 REST 请求体。 使用 endpoint.py 解析 create-project / add-domain——不要凭记忆手写请求体。
• 仅凭 HTTP 状态码判断。 200 且 success:false 表示失败——请读取 errors[]。
• 加载整个规范。 不要 cat 打包的切片——扫描索引，解析一个操作。（也绝不要获取完整的 10 MB Cloudflare OpenAPI。）

输出

此技能会产生 CLI/API 副作用（请求的 Cloudflare Pages 操作），并将解析后的结果返回给调用 Agent。它不会自行写入文件（只会 使用 调用方注入的凭据）。对于部署，它会报告部署 ID、URL 和终态状态；对于项目，它会报告项目名称/ID 和 URL；对于读取操作，它会返回请求的 result。抽象的使用者是需要执行网站托管操作的调用 Agent（或子 Agent）；机密绝不会出现在输出中。

相关内容

• references/credentials.md — 凭据契约（来自上下文的 account_id + 按名称提供的令牌 → CLOUDFLARE_API_TOKEN、有序加载规则、禁止登录）。
• references/wrangler.md — Wrangler Pages 功能范围及其未涵盖的内容。
• references/rest-api.md — REST 长尾功能、封装结构、部署阶段状态机、限制。
• 这是 github-cli-ops 的 CLI 优先版本，也是 atlassian-rest-ops / netlify-ops 的 OpenAPI 驱动版本，均遵循按提供商划分的服务技能模式。

渐进式披露

大量内容存放在子文件夹中，仅按需加载：

• references/credentials.md — 调用方注入的 account_id + 令牌、有序加载规则、Bearer 转接、禁止登录。在步骤 1 加载。
• references/wrangler.md — Wrangler 命令、直接上传与 Git 规则，以及 CLI 注意事项。在步骤 2–3 加载。
• references/rest-api.md — REST 模式、优先操作表、封装结构、部署阶段状态机、限制。用于 REST 长尾功能。
• references/sources.md — 来源（打包的 Pages 切片 + 官方文档）以及“确认实时状态”事项。
• assets/cli-index.md — Wrangler 快速命令列表（步骤 2）。
• assets/endpoint-index.md — 每个 REST 操作各占一行。
• assets/cloudflare-pages-openapi.json — 打包的 Pages OpenAPI 切片（通过解析器查询，绝不整体加载）。
• scripts/endpoint.py + .validation.md — python3 $ref 解析器（步骤 2）。
• scripts/{create-project,deploy,add-custom-domain,deployment-status}.sh + .validation.md — 四个经过验证的优先操作脚本。

独立使用（可选，非必需）

这是为在 Agent 工作流之外手动运行此技能的人类提供的便利方式——它不是此技能的依赖项。此技能的规范契约是由调用方注入（步骤 1）；本附录仅用于衔接手动操作。

如需手动运行，请创建一个作用域令牌（My Profile → API Tokens → Create Token，Cloudflare Pages: Edit），将其值存储在已加入 Git 忽略规则的 .env 文件中，安装 Wrangler（npm i -g wrangler），然后自行填入变量：

set -a; source .env; set +a                 # loads $CLOUDFLARE_PAGES_TOKEN, never prints it
export CLOUDFLARE_ACCOUNT_ID="<account-id>"
export CLOUDFLARE_API_TOKEN="$CLOUDFLARE_PAGES_TOKEN"
bash scripts/create-project.sh my-site main
bash scripts/deploy.sh my-site ./dist

令牌值仅按名称引用，绝不打印。建议使用可撤销、有效期短且作用域受限的令牌。

正文预算

• description ≤ 1,024 个字符（agentskills.io 上限）。
• 正文 ≤ 约 500 行 / 5,000 个 token——每轮都会保留在上下文中；Wrangler/REST 详情放在 references/ 中。
• assets/cloudflare-pages-openapi.json 是 Pages 子集（在磁盘上查询，从不加载到上下文中）。