📖 教程 ⏱ 约 22 分钟阅读

Cursor Agent SDK 公测×Clash：CI 里跑 Agent 的 API 域名分流实测（2026）

当讨论从「IDE 里点 Agent」延伸到「流水线里跑 Cursor Agent SDK（@cursor/sdk）」时，失败日志里最刺眼的不一定是模型，而是握手超时、间歇 5xx 与证书链校验——它们共享同一条根因：出口与 DNS 叙事不一致。自托管 Runner、公司内网 GitLab、或装着安全扫描证书的构建机，都会把「我本地 IDE 好好的」翻译成「CI 里 cloud Agent 起不来」。本文把热点落到可复现实操：在 Clash／Mihomo 侧用最小 API 分流与 DNS（含 fake-ip）对齐，配合 Job 内显式 HTTP(S)_PROXY，用连接日志把「网络没通」和「密钥／仓库权限错了」分开——不空谈公测噱头，只谈你怎么把 CI/CD 跑稳。

公测与 SDK：为什么 CI 场景更「挑」网络

Cursor Agent SDK让你在脚本、服务或 CI/CD 里调用 Agent.prompt、Agent.create + agent.send，或 Agent.resume 续跑历史会话（详见官方 TypeScript 文档）。与桌面 Agent 不同，流水线里常见三类脆弱点：无图形界面的代理写入（Runner 根本不理会托盘里的「系统代理」）、并发扇出更低容忍（一次 job 可能同时拉起鉴权、会话、Git 远程与制品拉取）、以及组织安全基线（HTTPS 检查、透明代理、Split-Horizon DNS）。

因此要把「稳定访问云端 API」写成工程习惯：不是再找一颗「最快节点」，而是让主机名—策略组—解析路径三者可以在日志里对齐。你若刚改完 IDE 侧体验，可以并行阅读Cursor 3 多 Agent 与 Clash Verge Rev一文的桌面段落；本文则专注 Runner 与 @cursor/sdk 的环境契约。

先把 runtime 选清点：local 与 cloud 对分流表的影响

SDK 同时支持本地 runtime与云端 runtime。若你省略 cloud: { repos } 却期待 VM 里代为克隆仓库，常在排障里绕圈——因为默认会落回本地执行器。对网络规划而言：local意味着出口主要是 Runner 到 Cursor 控制面／API，外加工作区只读网络；cloud还会引入托管方访问 Git 远程、写分支与开 PR 的流量面，主机名集合更大，也更依赖你把 GitHub 分流与 Cursor 规则合并维护，而不是各抄一段互斥模板。

提醒：云端任务若额外挂载 MCP，只接受对 CI 可见的 HTTP 入口；别把仅能本机访问的 localhost MCP 指给 cloud job，否则日志会像「偶发超时」一样难读。

第一步：在 Clash 侧固定「唯一写栈」的出口

与桌面相同，CI 机器上也忌多代理抢栈：公司 VPN、容器侧车、宿主机 Clash 网关同时生效时，最先坏掉的是 DNS 一致性。若你在自托管 Runner 的宿主机跑 Clash，请在 Job 开始前确认：监听端口稳定、profile 已激活、且没有第二个服务改写 iptables。对 Kubernetes 侧车模式，文档化「Pod 必须指向哪台 http:// 前置代理」比在事后猜路由更快。

需要轻量覆写而非替换整份订阅时，继续沿用 Mixin／Profile 覆写的心智：远端给节点与通用规则，你在本地层补 prepend-rules 与 DNS 补丁。CI 场景下尤忌一次性导入巨型 GEOIP 合集——它们会稀释你对「Agent API 主机名」的定位能力。

第二步：把「控制面／API」写进 prepend，而不是靠 GEOIP 兜底

实践里更有效的做法是维护可解释的最小前缀表：私有地址空间与 RFC1918 段永远在前；再追加与 Cursor 相关的后缀与你环境测得的 SN。具体主机名会随版本漂移，应以一次失败任务的真实连接日志增量回填；下面 YAML 仅示范结构，第三列策略组名必须与你合并后的 YAML 一致：

# Example only — replace PROXY_GROUP / DIRECT with your merged profile reality
prepend-rules:
  - DOMAIN-SUFFIX,cursor.com,PROXY_GROUP
  - DOMAIN-SUFFIX,cursor.sh,PROXY_GROUP
  - DOMAIN,api.cursor.com,PROXY_GROUP
  # Remove or edit lines above if your trace shows different SNIs; keep list minimal.
  - DOMAIN-SUFFIX,github.com,PROXY_GROUP
  - DOMAIN-SUFFIX,githubusercontent.com,PROXY_GROUP
  - DOMAIN-SUFFIX,ghcr.io,PROXY_GROUP

若你同时托管在自建 Git，请把对应域也提前，而不是指望后置「直连大陆」类规则碰巧放行。自定义规则教程里对 proxy-groups 命名对齐有逐项说明，CI 里拼错一个字节会在高峰期才爆雷。

第三步：DNS 与 fake-ip——把解析当成第一条分流

DNS在 CI 里常被忽略：Runner 默认走 systemd-resolved 或容器内置 forwarder，与 Clash 的 enhanced-mode 不在同一叙事里时，会出现「规则写走代理，但解析已经在 OS 侧翻车」。保持 fake-ip 时，检查 IP-CIDR 是否该带 no-resolve；不要在覆写层用全新 dns: 树覆盖远端，而是只补缺的 nameserver 行。需要 CLI 对照方法论时，可参考Claude Code CLI 与 DNS 分流一文里「先抓取证据、再补丁」的顺序，它同样适用于 Node SDK。

出现「TLS 握手很慢但偶发成功」时，多半不是线路「时快时慢」，而是解析路径抖动或策略命中漂移；此时应冻结节点组，打开连接视图对齐 SN，而不是立刻切换到更大的全局隧道。

第四步：Runner 里的 Node——请显式注入代理变量

无头环境不会自动继承 macOS／Windows 的「系统代理」设置。对 @cursor/sdk 而言，常见最小集是向 Job 注入 HTTP_PROXY、HTTPS_PROXY，视工具链加 ALL_PROXY，并用 NO_PROXY 放行内网 registry、artifact 与 metadata 服务。若你只在浏览器验证「能上网」却在同一台机器跑 Node，仍会得到 CursorAgentError 一类启动失败——这与「run 已创建但结果 error」是两类问题，需要分开记录退出码与告警。

在 shell 步骤里临时打印（脱敏）环境、再用 curl -vI 对目标 API 主机做一次最小 TLS 探活，往往比反复重拍整个 workflow 便宜。记得别在公开日志里回显 CURSOR_API_KEY；密钥应走 secret store。

第五步：把错误日志翻译成网络表——CursorAgentError vs run status

集成时建议统一观测：抛错且 run 未创建时优先查鉴权与网络（空白密钥、错位环境、出口拒绝）；run 已创建但失败时优先查指令、工具权限与仓库状态。对可复制文本的 SDK 文档与示例，请参阅 cursor.com 文档站点的 SDK 章节；本文不替你拷贝 API 表面，只强调判责顺序别搞反。

如果你启用流式 run.stream()，仍应在末尾 await run.wait()，否则既无法判定完成态，也可能泄漏 Watchers——长会话 CI 尤忌。完整生命周期还可复习官方建议的 await agent[Symbol.asyncDispose]() 模式，避免自托管 Runner 上堆积句柄。

第六步：一条可重复的压测清单（建议在 staging Runner 先做）

  1. 基线：停掉无关 VPN，仅保留计划内 Clash 出口；确认监听端口与订阅刷新完毕。
  2. tls：对追加过的核心域运行 curl -vI https://…，确认链路走预期代理而非意外直连污染。
  3. 最小 SDK：用 Agent.prompt 跑一次短指令，验证密钥、runtime 与超时；再换 Agent.create().send().wait()。
  4. cloud 增量：若启用远端仓库，在只读分支上验证 clone／fetch，再放开写权限。
  5. 回放：保留连接日志与 workflow trace，记录失败窗口对应的主机名，回填 prepend。
  6. 回滚：任何步骤引入「全局巨型规则集」后若排障变难，立即回退到最小集，避免调试摩擦指数上升。

这套顺序与Clash 使用教程强调的「先定位层、后动手」一致：日志是单一事实来源，不是社交平台上某个「万能节点名」。

常见问题

自托管 Runner 在 kvm／docker 里还要开 TUN 吗？

不一定。若 Node 已明确走 HTTP(S)_PROXY 且 Clash 提供稳定 MITM-free 前置，很多 job 不必 TUN。TUN 更适合进程不听话或协议栈复杂的宿主；开 TUN 前请核对公司安全政策与 cgroup 权限。

能否把 Cursor 与 Hugging Face／Copilot 混在一个自动测速组？

技术上可以，但不建议：不同业务的 RTT 与丢包容忍不同，混组往往表现为「看起来随机」的节点切换。为 Agent API 单独留一个低抖动手动组更利于 CI 复现。

没有桌面 Verge 时怎么验证 fake-ip？

在网关宿主上看内核日志与连接跟踪；对纯 headless，可用 mihomo API 或第三方 exporter 抓取活跃连接，再用失败窗口对齐 SN。关键是别用浏览器结果替代 Node 结果。

小结

Cursor Agent SDK把 Agent 带进 CI/CD，也把你对网络栈的「懒惰假设」一次性揭穿：API 分流、DNS 与前缀规则不在同一故事线时，云端会话会在重试里耗尽时限。把任务拆成runtime 选型 → prepend 域 → DNS 对齐 → 代理环境变量 → 日志判责，就能把「玄学超时」还原成可修的配置问题。

相比之下，部分传统「加速器」用封闭规则云包裹出口，难以及时覆盖 IDE／SDK 的长尾主机名；一旦上游滞后，你的流水线只能被动等待服务商发版。而 Clash 路线允许你在订阅之外本地 prepend、细粒度调 fake-ip 与策略边界，让自动化团队按主机名迭代，而不是把所有流量绑死在同一条黑盒隧道里。若你希望在桌面与 CI 两端保持一致的内核与客户端来源，可从本站下载页获取适合你系统的构建，并结合教程索引把订阅与分流打底；当最小清单跑通后再逐步放开 cloud 能力，通常比来回换节点省时得多。→ 前往下载页获取 Clash 客户端。