Agent 变成了文件夹：Cursor Agent SDK 正式可用，提示词终于有了版本历史

2026 年 10 月 20 日，Cursor 把 Agent SDK 推到了正式可用（GA）。一句话概括它的野心：agent 不再是聊天框里的一段提示词，而是一个可以放进代码仓库、用 diff 评审、用测试卡住的文件夹。提示词写进 instructions.md，每个工具是一个有类型的文件，技能按需加载，消息渠道写进配置，部署就是一条命令。这一步的意义不在功能清单，而在工作方式的改变：agent 的行为第一次有了版本历史，也就有了可以追责、可以回滚、可以复现的形状。

这篇先把官方 changelog 里确认的事实讲清楚，再谈三处值得认真对待的判断：为什么“文件夹”这个形态比“提示词框”更重要，为什么 eval 是整套 SDK 里最值得抄走的部分，以及自托管与 Cursor 托管之间该怎么选。凡是官方没有给出的数字和价格，本文都不会替它补。

先说清楚：GA 的到底是什么

根据 Cursor 官方 changelog 的 Agent SDK 条目，SDK 允许开发者把一个 agent 定义为一个代码文件夹，用 eval 测试它，并部署到 Cursor 或自己的基础设施上。起手命令是 npx @cursor/agent-sdk init ./my-bot，随后用 agent-sdk dev 在本地 playground 里跑起来。模板包括安全评审员、负责人策略审批员、PR 自动修复器，以及 Linear / Jira 分流器——这四个模板本身就是一张选型表：SDK 第一批瞄准的不是“聊天机器人”，而是挂在开发流程节点上的干活 agent。

文件夹的结构值得逐项读一遍。instructions.md 是提示词，也就是 agent 的“宪法”；tools/ 里的每个文件是模型可以调用的一个有类型动作；skills/ 放按需加载的流程；mcp-connections/ 接 MCP 服务器带来的工具；channels/ 定义 bot 在哪里收发消息。agent-sdk validate 校验项目结构，agent-sdk info 打印它发现了什么。这套分层的好处很实际：改提示词是一次 diff，改工具是一次接口变更，加技能是一次按需加载的决策，而不是在某个管理后台里点几下、事后谁也说不清改了什么。

部署同样被压成了一条命令。agent-sdk deploy 从项目目录出发，构建 agent、给它一个 URL，并在 Cursor 的基础设施上跑起来；密钥与集成在 dashboard 里管理，但日志、eval 和 playground 与本地同一套。也就是说，本地调试和线上运行不再是两套行为：你在本地 playground 里看到的会话记录，线上同样留痕。对独立开发者来说，这降低了“从 demo 到值班”的门槛；对团队来说，它把 agent 纳入了已有的代码评审流程。

渠道：agent 在哪里醒来

Agent SDK 的渠道清单比很多人预期的宽。GitHub、GitLab 与 Bitbucket 的 PR、评论与 CI 事件可以唤醒它；Slack 的提及与私信也可以；任何来源的 webhook 与 cron 定时任务同样可以。值得注意的一句细节是：GitHub 事件走 Cursor 账号直通，不需要公开的 webhook URL。这对小团队很友好——不用为了接一个 PR 机器人再搭一套公网入口、再操心签名校验的边角。

每个会话都有自己的 session，并且保存每一条消息与每一次工具调用的完整记录。同一条 PR 或 Slack 线程里的后续消息会回到同一个 session。这句话在工程上很关键：它意味着 agent 的“记忆”不是一句营销话，而是一份可以翻查的审计记录。当 agent 做错事时，你能回答的第一个问题不再是“它为什么这么想”，而是“它在第几步调用了哪个工具、传了什么参数”。

但渠道越宽，权限边界就要越早划清。能回 PR 评论的 agent，理论上也能在错误配置下改错东西；能收 Slack 私信的 agent，理论上也能被一句精心构造的消息带偏。本文的建议是：先给 agent 一个只读的起点——评审、分类、打标签——跑两周、看日志，再逐步放开写操作。SDK 给了你 eval 和会话记录，恰好就是用来支撑这种渐进放权的。

最值得抄走的部分：eval

如果只从 Agent SDK 里偷一个做法，我会偷 eval。它的定义很朴素：给 bot 发一条固定消息，然后断言它做了什么——调用了哪些工具、传了什么输入、回复长什么样。本地跑 agent-sdk eval，或者放进 CI 里跑。更进一步，agent-sdk github replay <pr-url> 能把一个真实 PR 变成带签名的 webhook 负载发给 bot；加上 --dry-run --fixtures-dir fixtures/，还能把负载存成 eval 夹具。

为什么这比“写更好的提示词”重要？因为提示词的效果无法回归。改一句话，过去十个 case 是变好了还是变坏了，没有 eval 就只能凭感觉。而 eval 把 agent 的行为变成了可失败的测试：工具调用错了，测试红；回复格式变了，测试红；不该触发的动作被触发了，测试红。团队评审 agent 时，评审对象也从“这段提示词读起来怎么样”变成了“这组 eval 覆盖了哪些我们最怕的场景”。

写第一条 eval 时，别从“希望它答对”开始，从“最怕它做错”开始。如果 agent 能发邮件、能改记录，先写一条断言：收到无关消息时，这两个动作一个都不许触发。然后才是正常路径：安全评审模板收到含敏感信息的 diff 时，应当调用哪几个工具、按什么顺序。等 eval 有了十条左右，提示词的每一次修改就都有了刹车。

这里还有一个组织层面的含义。过去 agent 的知识存在某个人的聊天记录或管理后台里，人走了，知识就散了。现在 instructions.md 进仓库，eval 进 CI，新人接手时看到的是一份带测试的行为规格。Cursor 在 changelog 里没有明说这一点，但文件夹形态的真正红利正在这里：agent 从个人手艺变成了团队资产。

自托管还是 Cursor 托管：怎么选

官方给出的选项是两者皆可：部署到 Cursor，或者部署到自己的基础设施。选择时不必纠结“哪个更先进”，按三个问题判断就够了。第一，数据能不能出自己的边界？如果 agent 要读内部仓库、内部工单，合规要求可能直接排除托管选项。第二，值班成本谁来扛？自托管意味着自己管可用性、密钥轮换与日志留存；托管意味着把这部分交给 Cursor，但也要接受它的运行环境与定价规则。第三，渠道依赖有多深？如果主力渠道是 GitHub 与 Slack，托管的直通能力省事；如果主力是内部系统 webhook，自托管的网络位置可能更顺。

对大多数 vibe 项目而言，一个务实的顺序是：本地 playground 起步，模板里选一个最贴近自己流程的（比如 PR 自动修复器或分流器），写三到五条 eval，跑在真实 PR 上两周；确认行为稳定、日志可读，再决定托管方式。不要一上来就把 agent 接到全量 PR 或全员 Slack 频道——SDK 的能力越完整，灰度就越重要。

另外要提醒一句：changelog 没有公布价格与用量细节，本文也不推测。评估成本时，先看模板跑起来后的实际调用量，再对照 Cursor 当时的定价页；不要用“GA”两个字默认它免费或便宜。

三个容易踩的坑

第一个坑是把 instructions.md 写成散文。提示词越长，模型越容易在长上下文里丢掉关键约束。比较好的写法是：开头三行写清身份、禁区与成功标准，随后按“收到什么输入、按什么顺序调用哪些工具、输出必须包含哪些字段、什么情况下必须停手求助”分段。每一类约束只出现一次，重复的表述不是强调，而是给模型制造冲突的素材。validate 能校验结构，但校验不了提示词内部的自相矛盾，这一步只能人工读。

第二个坑是工具粒度失控。tools/ 里每个文件是一个动作，动作太粗，eval 就断言不住细节；动作太细，一次任务要调几十个工具，出错面反而变大。一个可用的经验法则是：一个工具只做一件“业务上可命名”的事，比如“给 PR 打标签”而不是“处理 PR”，“查工单状态”而不是“查 Jira”。工具命名本身就是给模型的操作手册，名字含糊，调用必然含糊。

第三个坑是把 eval 当成一次性验收。eval 的价值在回归：提示词改了、模型换了、工具加了，同一组 eval 必须重跑。建议把 eval 放进 PR 的必过检查，和单元测试同等地位；同时给 eval 本身留一条“过期”机制——业务流程变了，旧的断言要及时更新，否则团队迟早会开始忽略一片飘红的测试，而那正是 agent 失控的开始。

它改变了什么，又没改变什么

Agent SDK 改变的是 agent 的工程形态：从一段提示词变成一个可评审、可测试、可部署的项目。它没有改变的是判断责任。eval 能证明 agent 在固定输入下做了固定动作，但不能证明它在没见过的输入下一定做对；会话记录能帮你事后复盘，但不能替你在事前划好权限。把 agent 做成文件夹，只是让“管好它”变得可能，而不是自动完成。

放在 2026 年 10 月的工具格局里看，这一步的信号也很清楚：编辑器厂商正在把 agent 从“编辑器里的功能”变成“可以嵌进别人产品的基础设施”。Anthropic 有自己的 Agent SDK，Cursor 现在也有了自己的。对开发者来说，选边之前先看清楚一件事：你写的 agent 是不是被锁在某一家厂商的渠道与运行环境里？文件夹形态本身是开放的，但 tools、channels 与部署目标的具体实现，仍要逐项核对可移植性。

最后给一份最小上手清单。第一，init 一个模板项目，读一遍 instructions.md 与 tools/ 的分工。第二，写一条“最怕做错”的 eval 并让它在 CI 里变红再变绿。第三，用 github replay 把上周一个真实 PR 重放一遍，对照会话记录看工具调用。第四，只读运行两周，再谈写权限。走完这四步，你对 Agent SDK 的判断就不再来自 changelog 的形容词，而是来自自己的日志。

与站内已发内容的划界

站内此前发布过 Claude Code、Codex 等 agent 工具的资讯与 agent 工作流指南，但 Agent SDK 这篇讲的是另一件事：Cursor 在 2026 年 10 月 20 日把 agent 本身产品化为可部署的代码项目，重点在文件夹结构、eval 与渠道部署，而非某个模型的能力或某一次对话的技巧。把它当作“agent 工程化”的新节点来读，而不是又一篇“怎么更好地提示 agent”的文章。