netlify-agent-runner

Netlify Agent Runner

在 Netlify 基础设施上远程运行 AI 编码 Agent（Claude、Codex、Gemini），以自动执行网站开发任务。

前提条件

• 网站必须已关联到 Netlify 项目（通过 netlify link 或 netlify init）。
• **或者完全跳过关联：**直接向 netlify agents:create 传入 --project <name>（项目 ID 或名称），即可指定任意 Netlify 网站，无需先进行关联。
• 必须已安装 Netlify CLI 并完成身份验证
• Agent 运行会消耗计划额度。如果账户没有可用额度，或已达到 Agent/AI 使用上限，netlify agents:create 将被阻止，任务也不会启动。这是账户/计划状态问题，应告知用户，而不是尝试绕过限制。

仅使用有文档说明的 CLI 接口

仅通过有文档说明的 netlify agents:* 命令（以及 netlify --help 和公开的 CLI 参考）与 Agent 任务交互。不要绕过 CLI：

• 不要使用 curl https://api.netlify.com/... 来获取、创建或停止任务——这些端点的格式不属于公开契约。
• 当有文档说明的命令失败时，不要运行 netlify api <method> 作为补救手段。
• 不要从 ~/Library/Preferences/netlify/config.json（或磁盘上的任何位置）读取身份验证令牌来进行旁路调用。

如果有文档说明的命令失败，请向用户报告确切的错误及上下文，然后停止——不要编造未公开说明的方式来访问任务。

Agent 任务的运行方式

创建任务前请先阅读此处——Agent 任务的运行方式与本地运行 Agent 不同，这些差异很容易被忽略。

• 远程运行，而非本地运行。 任务在 Netlify 基础设施上运行，而不是在你的计算机上运行。它们操作的是网站的已连接代码库，而非本地工作树。远程 Agent 只能看到已推送到远程端的内容——看不到尚未提交或推送的更改。
• 基于分支。 默认情况下，任务针对生产分支（main 或 master）运行。若要选择 Agent 的其他基础分支，请使用 -b <branch>，并确保该分支已先推送到远程端，否则 Agent 使用的代码在远程端并不存在。-b 设置的是基础（起始）分支——不是写入结果的分支（请参阅下一项）。
• 输出会写入新分支，而非原地修改。 Agent 不会将更改提交到你选择的基础分支。它会将工作推送到一个带有独立 Deploy Preview 的新分支，因此不会覆盖现有分支（或 main）。请在该新分支或 Deploy Preview 中查看任务结果——不要期待基础分支会直接改变。
• 异步运行。 netlify agents:create 在任务排队后立即返回——不会等待工作完成。命令返回时，任务仍在远程运行。
• 没有 Webhook 或回调。 任务状态变化或完成时不会通知你。若要了解进度，必须通过 netlify agents:show <task-id> 或 netlify agents:list 轮询。
• 状态分为终态与非终态。 任务状态依次为 new → running → done、error 或 cancelled。请持续轮询，直到状态变为最后三者之一，再处理结果。

典型工作流

1. 创建任务：netlify agents:create "<prompt>" -a <agent>。记下返回的任务 ID（使用 --json 可可靠地获取该 ID）。
2. 轮询状态：netlify agents:show <task-id>。定期重复执行——不会收到完成通知——直到状态变为 done、error 或 cancelled。
3. 查看结果：任务状态变为 done 后查看结果（若状态为 error，则检查失败信息）。

创建 Agent 任务

# Run a prompt with the default agent
netlify agents:create "Add a contact form"

# Choose a specific agent: claude, codex, or gemini
netlify agents:create --prompt "Add dark mode" --agent claude
netlify agents:create -p "Update the README" -a codex
netlify agents:create -p "Write unit tests" -a gemini

# Target a specific branch
netlify agents:create -p "Fix the login bug" -a claude -b feature-branch

# Specify a project by name (if not in a linked directory)
netlify agents:create "Add tests" --project my-site-name

# Output result as JSON
netlify agents:create "Add a footer" --json

选项

标志	描述
-a, --agent <agent>	Agent 类型：claude、codex 或 gemini
-p, --prompt <prompt>	要由 Agent 执行的提示词
-b, --branch <branch>	要操作的 Git 分支
-m, --model <model>	Agent 使用的模型
--project <project>	项目 ID 或名称
--json	以 JSON 格式输出结果

管理 Agent 任务

所有 netlify agents:* 命令都限定于单个项目——它们只对一个项目执行操作（即当前目录关联的项目，或通过 --project <name> 指定的项目），而不是对整个团队执行操作。netlify agents:list 仅显示该项目的任务；没有可以列出所有站点任务的团队级命令。若要查看其他站点的任务，请在其关联目录中运行命令，或为该站点传入 --project <name>。

列出任务

# List all tasks for the current site
netlify agents:list

# Filter by status
netlify agents:list --status running
netlify agents:list --status done
netlify agents:list --status error

# Output as JSON
netlify agents:list --json

状态值：new、running、done、error、cancelled。

查看任务详情

netlify agents:show <task-id>
netlify agents:show <task-id> --json

停止正在运行的任务

netlify agents:stop <task-id>

使用场景

使用 Agent Runners 可以完成的众多任务包括：

类别	示例提示词
原型开发 / 内部工具	"为我们的人力资源团队构建一个内部仪表板"
代码审查	"以全新的视角审查代码，并找出可改进之处"
安全审计	"深入审计我们的代码库，找出任何潜在问题"
功能建议	"根据我们当前的代码库和文档，接下来应该构建什么？"
性能改进	"扫描我们的代码库，找出性能瓶颈并提出改进建议"
遥测与分析	"有哪些分析数据是我们没有跟踪，但可能应该跟踪的？"
SEO 审计	"审查我们的网站，找出 SEO 问题——缺失的元标签、失效的链接、加载缓慢的页面、缺失的替代文本"
文案改进	"重写我们的落地页文案，让内容更有吸引力并更注重转化"
无障碍性	"执行无障碍审计，并修复所有 WCAG 2.1 AA 违规问题"
移动设备适配	"改进移动设备适配性——审查每个页面在小视口下的表现"
端到端测试	"使用 Playwright 为我们的关键用户流程添加端到端测试"
单元测试	"为尚未测试的实用函数生成单元测试"
文档	"根据我们的代码库生成 README 和贡献指南"
错误处理	"在整个应用中添加恰当的错误边界、日志记录和便于用户理解的错误状态"
UX 润色	"添加加载状态、骨架屏和过渡效果，提升用户感知的性能"
表单加固	"为我们的联系表单添加表单验证、速率限制和垃圾信息防护"
Edge Functions	"为我们的落地页添加边缘函数，以进行 A/B 测试"

作为 Agent 使用

如果你是 AI Agent，可以使用 netlify agents:create 将工作委派给在 Netlify 上远程运行的 Agent，例如，让不同的模型提供第二种意见。

重要 — 请先征求许可，并将其作为单独的确认步骤。 Agent 任务在 Netlify 基础设施上运行，会消耗用户的额度，因此必须设置真正的审批关卡。在运行任何 netlify agents:create 命令之前，都要获得明确许可——并将其视为单独的一轮对话，与用户最初的请求分开。听起来像指令的提示（“开始一个任务……”“使用 claude agent 并指定 Opus”）本身并不代表已获批准：它说明了用户的意图，但在用户明确同意之前，仍不得运行会产生费用的命令。

征求许可时，要提出具体方案，而不是列出选项：

• 填写完整的确切命令——例如 netlify agents:create -p "<the real prompt>" -a codex，不能使用 <placeholder>，也不能罗列多个 Agent 供用户选择。
• 预先选定一个 Agent——确定单个 -a 值，并说明选择理由（“针对身份验证逻辑征求第二种意见，因此选择 codex”），而不是把 claude、codex、gemini 当作可互换的选项。
• 说明原因，以及用户同意后会发生什么：任务以异步方式运行——agents:create 会在任务进入队列后立即返回，不会提供回调；你需要通过 netlify agents:show <task-id> 轮询结果。
• 即使缺少前置条件（尚未完成身份验证、尚未关联站点、还不是 git 仓库），也要展示待条件满足后将运行的确切命令和选定的 Agent——既要指出阻碍，也要提出具体方案，不能只说明阻碍。

未经用户批准，绝不要运行这些命令。

委派之前，先了解你要交付的内容（参见上文的Agent 任务如何运行）：

• 任务会在远程环境中针对已推送的分支运行，而不是针对你的本地工作。 远程 Agent 只能看到已提交并推送的代码。不要委派依赖本地未完成更改的工作；远程 Agent 看不到这些更改，只能基于过时的代码开展工作。如果任务需要使用你当前的更改，请先提交并推送这些更改，或者自行完成工作。
• 任务以异步方式运行——委派不会阻止你继续工作。 任务会在远程运行，同时你可以继续处理其他工作。但由于没有回调，你必须轮询（netlify agents:show <task-id>）才能获知结果。不要以为委派后任务就已经完成——在依赖或描述结果之前，先检查任务状态。
• 这是一个独立且完整的任务，并非当前会话的延续。 远程 Agent 会根据仓库和你提供的提示词重新开始。它没有你的对话上下文，因此请编写完整、独立的提示词。

适用于：

• 交叉验证 — 请不同的模型对你的实现提供第二种意见
• 发现边缘情况 — 其他模型可能会发现你遗漏的问题
• 探索替代方案 — 看看不同的模型会如何解决同一个问题
• 并行工作 — 在你继续处理其他工作的同时，在远程启动一个独立任务，然后轮询查看结果