在 Netlify 上远程运行 AI…

当需要把开发任务远程委派给 AI 代理、或让另一个模型对代码给出第二意见时，用 Netlify CLI 的 agents 命令在云端运行代理。

适用场景

解决思路

1. 确认前置条件：站点已通过 `netlify link` 或 `netlify init` 链接到 Netlify 项目；或跳过链接，直接在 `netlify agents:create` 上传 `--project <name>`（项目 ID 或名称）来指定任意 Netlify 站点。
2. 确保 Netlify CLI 已安装并完成认证。
3. 注意代理运行会消耗套餐额度；若账户无可用额度或已达代理/AI 使用上限，`netlify agents:create` 会被阻止，需向用户说明这是账户/套餐状态问题，不要绕过。
4. 只使用官方文档化的 `netlify agents:*` 命令（以及 `netlify --help` 和公开 CLI 参考）与代理任务交互。
5. 不要用 curl 访问 `https://api.netlify.com/...` 来获取、创建或停止任务——这些端点不属于公开契约。
6. 不要在文档化命令失败时用 `netlify api <method>` 作为补救手段。
7. 不要从 `~/Library/Preferences/netlify/config.json`（或磁盘任何位置）读取认证 token 来做旁路调用。
8. 若文档化命令失败，向用户报告确切错误和上下文并停止，不要发明未文档化的方式去访问任务。
9. 理解代理任务特性：任务在 Netlify 基础设施上远程运行，作用于站点连接仓库而非本地工作树，只能看到已推送到远端的代码，看不到未提交或未推送的更改。
10. 理解分支机制：默认针对生产分支（`main` 或 `master`）运行；用 `-b <branch>` 选择代理起始的基分支，且该分支必须已推送到远端，否则代理会基于远端不存在的代码工作；`-b` 设置的是基（起始）分支，不是结果写入位置。
11. 理解输出位置：代理不会把更改提交到所选基分支，而是推送到一个带独立 Deploy Preview 的新分支，原分支（或 `main`）不会被覆盖；在該新分支/Deploy Preview 上审查结果。
12. 理解异步性：`netlify agents:create` 在任务入队后立即返回，不会阻塞到工作完成；命令返回时任务仍在远程运行。
13. 理解无 webhook/回调：任务状态变化或完成时不会有通知，必须用 `netlify agents:show <task-id>` 或 `netlify agents:list` 轮询。
14. 理解状态机：任务经历 `new` → `running` → `done`/`error`/`cancelled`；持续轮询直到状态为后三者之一再对结果采取行动。
15. 典型工作流第 1 步——创建任务：`netlify agents:create "<prompt>" -a <agent>`，记录返回的任务 ID（用 `--json` 可靠捕获）。
16. 典型工作流第 2 步——轮询状态：`netlify agents:show <task-id>`，周期性重复（无完成通知），直到状态为 `done`、`error` 或 `cancelled`。
17. 典型工作流第 3 步——审查结果：任务到达 `done` 后审查结果，或在 `error` 时检查失败原因。
18. 创建任务示例：`netlify agents:create "Add a contact form"`（默认代理）；`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`；`netlify agents:create -p "Fix the login bug" -a claude -b feature-branch`；`netlify agents:create "Add tests" --project my-site-name`；`netlify agents:create "Add a footer" --json`。
19. 创建任务选项：`-a, --agent <agent>` 代理类型（`claude`、`codex` 或 `gemini`）；`-p, --prompt <prompt>` 代理执行的提示词；`-b, --branch <branch>` 工作的 Git 分支；`-m, --model <model>` 代理使用的模型；`--project <project>` 项目 ID 或名称；`--json` 以 JSON 输出结果。
20. 注意所有 `netlify agents:*` 命令都是项目作用域的——只作用于单个项目（当前目录链接的项目，或 `--project <name>` 指定的项目），不是整个团队；`netlify agents:list` 只显示该项目的任务，没有跨所有站点的团队级命令；要查看其他站点的任务，需从其链接目录运行或传 `--project <name>`。
21. 列出任务：`netlify agents:list`；按状态过滤 `netlify agents:list --status running`、`--status done`、`--status error`；JSON 输出 `netlify agents:list --json`。状态值：`new`、`running`、`done`、`error`、`cancelled`。
22. 查看任务详情：`netlify agents:show <task-id>` 或 `netlify agents:show <task-id> --json`。
23. 停止运行中的任务：`netlify agents:stop <task-id>`。
24. 可用场景示例：原型/内部工具（"Build an internal dashboard for our HR team"）；代码审查（"Audit the code with fresh eyes and identify areas for improvement"）；安全审计（"Do a deep security audit of our codebase to identify any potential issues"）；功能建议（"Based on our current codebase & docs, what should we build next?"）；性能改进（"Scan our codebase for performance bottlenecks and suggest improvements"）；遥测与分析（"What analytics things are we not tracking but probably should"）；SEO 审计（"Audit our site for SEO issues — missing meta tags, broken links, slow pages, missing alt text"）；文案改进（"Rewrite our landing page copy to be more compelling and conversion-focused"）；无障碍（"Run an accessibility audit and fix all WCAG 2.1 AA violations"）；移动端响应式（"Improve the mobile responsiveness — audit every page on small viewports"）；端到端测试（"Add end-to-end tests for our critical user flows using Playwright"）；单元测试（"Generate unit tests for our untested utility functions"）；文档（"Generate a README and contributing guide based on our codebase"）；错误处理（"Add proper error boundaries, logging, and user-friendly error states throughout the app"）；UX 打磨（"Add loading states, skeleton screens, & transitions to improve perceived performance"）；表单加固（"Add form validation, rate limiting, and spam protection to our contact form"）；Edge Functions（"Add an edge function for A/B testing on our landing page"）。
25. 若你是 AI 代理，可用 `netlify agents:create` 把工作委派给 Netlify 上远程运行的代理，例如从不同模型获取第二意见。
26. 重要——先请求许可，作为独立的确认步骤：代理任务在 Netlify 基础设施上运行并消耗用户额度，必须有真正的审批门；在运行任何 `netlify agents:create` 命令前获得明确许可，并将其视为独立于用户原始请求的一轮；指令式提示（"start a task…"、"use the claude agent and pin it to Opus"）本身不是批准——它说明用户想要什么，但计费命令仍需等待确认。
27. 让许可请求成为具体提案而非菜单：给出填好的确切命令（如 `netlify agents:create -p "<the real prompt>" -a codex`），不要用 `<placeholder>` 或让用户从代理列表中挑选。
28. 只选一个代理并说明理由（如 "codex for a second opinion on the auth logic"），不要把 claude/codex/gemini 作为可互换选项列出。
29. 说明原因以及"同意"后会发生什么：运行是异步的——`agents:create` 在任务入队后立即返回，没有回调，你将轮询 `netlify agents:show <task-id>` 获取结果。
30. 即使缺少前置条件（未认证、未链接站点、还不是 git 仓库），仍要展示解决后将运行的确切命令和所选代理——同时呈现阻塞项和具体提案，而不是只描述阻塞项。
31. 永远不要在未经用户批准的情况下运行这些命令。
32. 委派前理解交接内容：它针对已推送分支远程运行，不是你的本地工作；远程代理只能看到已提交并推送的代码；不要委派依赖本地进行中更改的工作，远程代理看不到它们会基于陈旧代码工作；若任务需要当前更改，先提交并推送（或自己完成工作）。
33. 它是异步的——委派不会阻塞你；任务在远程运行而你可继续工作；但由于没有回调，必须轮询（`netlify agents:show <task-id>`）才能得知结果；不要因为已委派就假设任务完成——在依赖或描述其结果前检查状态。
34. 它是独立自包含的任务，不是会话的延续；远程代理从仓库和你给的提示词全新开始，没有你的对话上下文，所以要写完整、独立的提示词。
35. 适用场景：交叉验证——从不同模型获取对实现的第二意见；边界情况发现——另一个模型可能发现你遗漏的问题；替代方案——看不同模型如何解决同一问题；并行工作——在继续其他工作时远程启动独立任务，然后轮询其结果。

适用边界 · 注意事项

• 账户无可用额度或已达代理/AI 使用上限时，`netlify agents:create` 会被阻止，这是账户/套餐状态问题，不应绕过。
• 任务依赖本地未提交或未推送的更改时不要委派，远程代理看不到这些更改，会基于陈旧代码工作。
• 文档化命令失败时不要用 curl 访问 API、`netlify api <method>` 或读取认证 token 等未文档化方式绕过。