Cursor Cookbook：把 Cursor AI 编码智能体装进你的工作流

从 IDE 到任何地方：Cursor 的野心不只是编辑器

如果你用过 Cursor编辑器（那个接入了 AI 的 VS Code 分支），大概率会被它的代码补全、多行编辑和对话式编程能力所折服。但 Cursor 团队的野心显然不止于"更好的编辑器"——他们想把 AI 编码智能体的能力，解耦成一套可编程的 SDK，让任何人都能在自己的应用、脚本和自动化流水线里，调用Cursor背后那套 AI 编码大脑。

Cursor Cookbook 正是这个战略的官方示例仓库。它不是一个完整产品，而是由官方维护的"菜谱集"：从零到一的快速上手、DAG 任务编排、云端自托管部署……每个示例都配源码，开箱即跑。目前在 GitHub 已收获 3896 Stars，成为 Cursor SDK 生态最热门的参考项目之一。

Cursor SDK 是什么：把你的应用变成 AI 编程助手

Cursor SDK 是这个仓库的核心产品。它是一套 TypeScript API，允许开发者在自己的应用、脚本和工作流中，创建、运行和管理 Cursor 的 AI 编码智能体（Agent）。

打个比方：如果 Cursor 编辑器是"给人类用的 AI 编程工具"，Cursor SDK 就是"给程序用的 AI 编程工具包"。开发者可以在任何 Node.js 环境里，导入 SDK，创建一个 Agent 实例，然后向它发送自然语言指令——Agent 会像在 Cursor 编辑器里一样，理解需求、读写文件、执行命令、调用工具。

SDK 支持两种运行模式：本地模式（Agent 直接在本地工作区运行）和云端模式（Agent 运行在 Cursor 的云端，事件流返回给调用方）。无论哪种模式，API 接口完全一致，切换只需改一行配置。

Quickstart：30 行代码体验完整流程

最快上手方式，只需 30 行 TypeScript 代码：创建 Agent → 发送 prompt → 流式接收响应并打印。每个步骤都有注释，适合作为第一个接入示例。

App Builder：对话式生成带预览的 Web 应用

这个示例展示了更复杂的上层应用：集成一个 Chat UI + 一个 iframe 沙箱，内嵌 AI 生成应用的可视化预览。用户通过对话描述需求，Agent 实时生成代码，预览页面在 iframe 中热重载，形成完整的"需求 → 代码 → 预览"闭环。

技术栈：Next.js 16 + React 19 + shadcn/ui + Tailwind CSS。代码量不大，但覆盖了 SDK 的流式事件处理、沙箱工作区管理和多轮对话状态持久化。

Agent Kanban：把 Linear 的看板变成 AI 任务分发台

Linear 是一个以键盘快捷键闻名的项目管理工具。Agent Kanban 把 Cursor Cloud Agents 的任务状态映射到 Linear 风格的看板界面上：每个 Agent 实例是一张卡片，展示状态、所属仓库/分支、最新活动时间、关联 PR 链接，以及 Agent 生成的 Artifact 预览。

这个示例演示了 SDK 的云端 Agent 管理能力：列表查询、分组筛选、状态同步，以及通过 Agent.create({ cloud: { repos } }) 接口从看板直接创建新的云端 Agent。

DAG Task Runner：把复杂任务分解为并行子任务图

如果说前几个示例是单 Agent 使用场景，DAG Task Runner 则展示了多 Agent 协作的可能性。它把一个复杂任务按依赖关系分解为 JSON DAG（拓扑图），然后按拓扑序并行调度多个本地 Subagent，每个 Subagent 独立运行，最终状态实时写入 Cursor Canvas（热重载数据面板）。

亮点：DAG 状态变化会触发 Canvas 自动刷新，开发者可以在 IDE 里实时观察 PENDING → RUNNING → FINISHED/ERROR 的任务进展。代码同时发布为可安装的 Cursor Skill，直接导入 Cursor 编辑器使用。

Coding Agent CLI：终端里的 AI 编程搭档

一个用 Bun 运行的命令行工具，提供两种模式：一次性指令模式（直接执行单个 prompt）和 TUI 交互模式（实时对话）。后者使用 OpenTUI 渲染，支持在本地和云端 Agent 之间切换执行环境。

Bun-only 的原因是 OpenTUI 的原生渲染依赖 bun:ffi 接口。

Self-Hosted Cloud Agents：把 Cursor 云端 Agent 部署到你的 AWS 账户

Cookbook 的另一大板块是自托管云端 Agent 实验室。标准 Cursor Cloud Agents 运行在 Cursor 的服务器上——这对很多企业来说是不可接受的：代码不能出境、数据必须留在内网、需要自定义网络策略。

Cursor 提供了在客户自有的 AWS 基础设施上运行 Cloud Agent Worker 的方案。Cookbook 提供了三种部署模式的完整参考：

Worker 以 Docker 容器运行，通过公网 HTTPS 主动连接 Cursor 云端进行通信。不需要开放入站端口，安全性更高。Dockerfile 基于 Ubuntu 24.04，预装了 AWS CLI 和 Cursor Agent CLI，支持 amd64/arm64 双架构。

技术架构：TypeScript-first，API 设计清晰

仓库整体采用 pnpm monorepo 结构，根目录管理共享配置，各子项目独立运行。技术选型非常统一：

• 语言：TypeScript（所有示例均为 TS，无 Python/Go）
• 运行时：Node.js >= 22（Bun 仅在 coding-agent-cli 中使用）
• 包管理：pnpm 10.9.0
• Web 框架：Next.js 16（App Builder、Agent Kanban）
• 样式：Tailwind CSS + shadcn/ui
• AI 集成：@cursor/sdk 包（版本 1.0.7），封装所有 Agent 通信逻辑

代码质量方面，仓库配置了 ESLint + TypeScript 严格类型检查，测试覆盖率和文档质量均处于较高水准。

上手难度与部署

局限与注意事项

1. Cursor API Key 必需：所有 SDK 示例都需要从 Cursor 集成面板 获取 API Key，暂不支持离线或本地模型替代。
2. 云端模式数据出境：即使使用自托管 Worker，Agent 编排和模型推理仍由 Cursor 云端负责，代码不会出境的承诺仅限于 Worker 执行层。
3. Bun 独占限制：Coding Agent CLI 依赖 bun:ffi，不支持 Node.js 或 Deno 运行。
4. 文档语言：Cookbook 所有内容为英文，对中文开发者有一定门槛。

行业意义：AI 编程工具的 SDK 化趋势

Cursor Cookbook 的出现，折射出一个更宏大的趋势：AI 编程工具正在从"专用 IDE"进化为"可编程平台"。类似 OpenAI 把 GPT 模型封装为 API，Cursor 正在把 AI 编码智能体封装为 SDK，让它可以嵌入任何工作流——Jupyter 笔记本、CI/CD 流水线、数据科学脚本、企业内部工具。

这种 SDK 化的意义在于：它让 AI 编码能力从"编辑器内的功能"变成了"可组合的基础设施单元"。开发者可以像搭积木一样，把 Agent 组合成 DAG 工作流，或者嵌入现有的项目管理工具。从长远看，这意味着 AI 编程能力可以像 REST API 一样被调用、被组合、被商业化。

如果你对 AI 辅助编程有兴趣，或者正在构建需要代码生成/修改能力的产品，Cursor Cookbook 是一个值得收藏的参考仓库。