netlify-ops

netlify-ops

概述

此技能让 Agent 能够 优先使用 CLI（netlify CLI）执行 Netlify 托管操作，并在需要时回退到 Netlify 官方 API 的 REST API——不使用 SDK。CLI 是常用且便捷的路径（创建站点、部署目录、读取状态）；REST API 则涵盖更全面的长尾操作（自定义域名、精细读取、DNS），其依据是随附的 OpenAPI，通过端点索引和 $ref 解析器实现覆盖，因此无需将规范加载到上下文中。Agent 使用调用方注入的令牌，选择 CLI 命令或 REST 操作，执行后解析 JSON。它支持 Netlify 的静态/JAMstack 和无服务器功能，不支持全栈容器托管。

何时启用

• ✅ 创建 Netlify 站点，或向站点部署构建产物（草稿/预览部署或使用 --prod）。
• ✅ 设置并验证自定义域名，或配置站点的 DNS。
• ✅ 读取部署状态（state 字段），或列出/检查站点和部署。

以下情况请勿启用：

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

工作流

步骤 1 — 接收注入的凭据

调用方已解析账户并注入令牌——请使用该令牌；不要查找记录或登录。Netlify 没有非机密记录字段（主机固定；没有账户 ID/电子邮件）。你会从上下文中获得能力（web-hosting）以及令牌的变量名。先将该名称解析为项目级 .env 值（如果该文件存在且定义了此变量），否则解析为同名的环境变量（优先使用项目 .env）。令牌值不会出现在上下文文本中——只有其变量名。不要进行任何作用域解析或目录遍历；使用项目 .env，而非 .envrc。

将令牌传入 NETLIFY_AUTH_TOKEN（CLI 会读取此变量；REST 回退路径会发送 Authorization: Bearer）。绝不要运行 netlify login/logout。完整约定：references/credentials.md。

步骤 2 — 选择常用路径（CLI）或长尾路径（REST）

• CLI（常用路径）： 查看 assets/cli-index.md 中的 sites:create、deploy、status、sites:list，以及 netlify api <operationId> --data 备用入口。详情：references/cli-reference.md。
• REST（长尾路径）： 查看 assets/endpoint-index.md（每个操作占一行），然后运行 python3 scripts/endpoint.py <operationId>，以解析参数、请求体和 curl 命令框架。详情：references/rest-api.md。绝不要将约 690 KB 的规范加载到上下文中。

步骤 3 — 执行

随附的四个脚本涵盖优先操作：

• create-site.sh <name> [account-slug] — netlify sites:create … --json（返回站点；其 ID 是 id 字段——--json 使用 id 作为键，而非 site_id——部署时将该 ID 作为 --site 传入）。
• deploy.sh <site-id> <dir> [--prod] — netlify deploy --dir … --site … --json（默认进行草稿部署；--prod 会发布）。
• set-custom-domain.sh <site-id> <domain> — REST PATCH updateSite（custom_domain）。
• deploy-status.sh <site-id> <deploy-id> — getSiteDeploy（state 字段）。

其他操作：使用 cli-index.md 中的 CLI 命令，或针对已解析的 REST 操作执行 curl。

步骤 4 — 处理响应

• 部署是异步且分多个阶段。 从 deploy.sh 的 --json 输出中提取部署 ID（deploy_id / id 字段），并传给 deploy-status.sh。部署状态依次为 building → uploading → processing → ready（或 error）。轮询 deploy-status.sh（或 getSiteDeploy），直到 state 进入终态；草稿部署有唯一的预览 URL，--prod 会将更改发布到正式站点。
• 自定义域名 ≠ DNS。 设置 custom_domain 并不会使其解析——还需配置 DNS（configureDNSForSite / dns_zones 记录）。
• **错误 / 限制：**非 2xx JSON；常规速率限制为 500 req/min，部署限制为 3/min · 100/day——遵守 X-RateLimit-* 标头。401 表示令牌缺失或已过期。

规则

硬性规则（绝不违反）：

• **绝不运行 netlify login / netlify logout。**身份验证使用注入的令牌，通过 NETLIFY_AUTH_TOKEN（或 --auth）提供；CLI 以无头模式运行。令牌缺失是调用方的错误，不是登录提示。
• **绝不读取或打印令牌值。**仅将其引用为 $NETLIFY_AUTH_TOKEN（CLI 环境变量）或 Bearer $NETLIFY_AUTH_TOKEN（REST）；子进程会从环境中读取它。令牌只存放在 .env（已加入 gitignore）或环境变量中。
• **构造 REST 调用前先解析。**根据通过 $ref 解析的架构（endpoint.py）构建请求正文 / 参数——绝不要猜测字段集。
• **使用已知的 site_id 和 --site 进行部署。**全新检出中没有 .netlify/state.json；绝不要依赖链接状态，也不要使用 --allow-anonymous。
• **优先使用 CLI，REST 用于后续操作。**使用 CLI 创建、部署和查看状态；自定义域名、DNS 和精细化读取操作则使用 REST。
• **此技能绝不写入凭据。**凭据由调用方提供。

偏好（可覆盖）：

• 非交互式使用 CLI 时传入 --json（机器可读输出）和 --force（跳过提示）。
• 对于携带请求正文的 REST 写入操作（updateSite、createSiteDeploy），优先使用纯 curl，而不是 netlify api 变通方案（该变通方案的请求正文键名约定尚未验证）；仅对只需路径参数的操作使用该变通方案。
• 优先使用 CLI 的 netlify deploy --dir，而不是手动实现摘要协议——它会为你完成 SHA1 差异计算和上传。

注意事项

• **不要登录。**最严重的契约违规是令牌“无法使用”时尝试运行 netlify login。无效令牌应作为错误报告，而不是通过登录处理。
• **使用 --no-build，而不是 --build。**CLI 默认会构建；不存在 --build 标志——要跳过构建，请使用 --no-build。
• **草稿与正式环境。**省略 --prod 会创建草稿 / 预览部署（拥有唯一 URL，不影响生产环境）。只有 --prod 才会将更改发布到正式站点。
• 关键是 site_id。--name / --account-slug 是面向用户的标识；每个 API 操作都以不透明的 site_id 为键（链接后位于 .netlify/state.json 中）。注意：sites:create --json 在 id 下返回此 ID，而不是 site_id（创建时 .site_id 为 null）——从创建输出中读取 .id，并将其传给 --site。
• **摘要部署必须处理所需文件。**手动实现 REST createSiteDeploy 会返回一个 required 数组，其中包含 SHA1 值，之后必须上传对应文件——若跳过此步骤，部署将无法进入 ready 状态。CLI 会处理这些步骤。
• 自定义域名需要 DNS。updateSite 会设置 custom_domain；只有配置 DNS 后，域名才会解析。
• **部署容易触及速率限制。**每分钟 3 次部署，每天 100 次——当 X-RateLimit-Remaining: 0 时应退避。
• **state 是自由字符串。**规范并未列出部署状态；应将文档中的状态列表视为参考，并通过实际部署确认。

反模式

• 运行 netlify login。 禁止——契约会注入令牌；不要自行处理身份验证，也不要提示用户登录。
• 回显令牌。 绝不要执行 echo $NETLIFY_AUTH_TOKEN，绝不要将其粘贴到打印的命令中，也绝不要将其值写入文件。只能引用环境变量。
• 猜测 REST 请求体。 使用 endpoint.py 解析 updateSite / createSiteDeploy——不要凭记忆手写请求体。
• 部署时不传 --site。 在全新检出中依赖链接状态会悄悄部署到错误的网站（或根本不会部署）。务必传入 site_id。
• 使用 --allow-anonymous。 这会创建一个无需身份验证、可供认领的网站——这不属于此技能的操作路径；务必使用注入的令牌部署到已知网站。
• 加载整个规范。 不要用 cat 读取约 690 KB 的 OpenAPI 文件——扫描索引，然后解析一个操作。

输出

此技能会产生 CLI/API 副作用（执行请求的 Netlify 操作），并将解析后的 JSON 返回给调用方 Agent。它不会写入任何文件（只会 使用 调用方注入的令牌）。对于部署，它会报告部署 ID、URL 和最终 state；对于网站，它会报告 site_id 和 URL；对于读取操作，它会返回请求的 JSON。抽象的使用者是需要执行网站托管操作的调用方 Agent（或子 Agent）；机密绝不会出现在该输出中。

相关内容

• references/credentials.md — 凭据契约（按名称提供令牌 → NETLIFY_AUTH_TOKEN、有序加载规则、禁止登录）。
• references/cli-reference.md — netlify CLI 功能和 netlify api 备用方案。
• references/rest-api.md — REST API 的其他内容、摘要部署协议、状态和限制。
• 这是 github-cli-ops 的 CLI 优先姊妹技能，也是 atlassian-rest-ops 的 OpenAPI 支撑姊妹技能，二者均遵循按服务提供商划分的技能模式。

渐进式披露

较大的内容位于子文件夹中，仅按需加载：

• references/credentials.md — 调用方注入的令牌、有序加载规则、Bearer 转接、禁止登录。在步骤 1 中加载。
• references/cli-reference.md — CLI 命令、备用方案和 CLI 注意事项。在步骤 2–3 中加载。
• references/rest-api.md — REST 模式、优先操作表、摘要部署协议、状态和限制。在处理 REST 的其他内容时加载。
• references/sources.md — 来源（官方 OpenAPI、CLI/API 文档和两个源技能）及“确认实时状态”事项。
• assets/cli-index.md — CLI 快速命令列表（步骤 2）。
• assets/endpoint-index.md — 每个 REST 操作一行。
• assets/netlify-openapi.json — 附带的规范（Swagger 2.0；通过解析器查询，绝不整体加载）。
• scripts/endpoint.py + .validation.md — python3 $ref 解析器（步骤 2）。
• scripts/{create-site,deploy,set-custom-domain,deploy-status}.sh + .validation.md — 四个经过验证的优先操作脚本。

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

这是为在 Agent 流程之外手动运行此技能的用户提供的便利方式，并非此技能的依赖项。此技能的规范性契约要求由调用方注入（步骤 1）；本附录仅用于衔接手动操作。

若要手动运行，请创建 Netlify PAT（User → Applications → Personal access tokens），将其值存储在被 git 忽略的 .env 文件中，安装 CLI（npm i -g netlify-cli），然后自行设置该变量：

set -a; source .env; set +a                 # loads $NETLIFY_PROD_TOKEN, never prints it
export NETLIFY_AUTH_TOKEN="$NETLIFY_PROD_TOKEN"
bash scripts/create-site.sh my-site
bash scripts/deploy.sh <site-id> ./dist --prod

令牌仅按名称引用，绝不打印。建议使用可撤销的短期 PAT。

正文限制

• description ≤ 1,024 个字符（agentskills.io 上限）。
• 正文 ≤ 约 500 行 / 5,000 个 token——每轮都会保留在上下文中；CLI/REST 细节位于 references/ 中。
• assets/netlify-openapi.json 文件较大（在磁盘上查询，绝不加载到上下文中）。