Cursor SDK：用 TypeScript 声明式构建可调试、可复用的 AI Agent

weixin_30369041

399人浏览 · 2026-06-20 10:19:40

weixin_30369041 · 2026-06-20 10:19:40 发布

1. 项目概述：这不是又一个“AI编程插件”，而是一套可嵌入、可编排、可调试的 Agent 构建范式

“Cursor SDK：用写代码的方式写 Agent”——这句话乍看像营销话术，但在我连续三个月深度嵌入 Cursor Pro 环境、从零搭建 7 个生产级 Agent 工作流后，我确认它精准击中了当前 AI 编程落地最痛的盲区：我们缺的不是更聪明的大模型，而是让开发者能像写 React 组件一样定义 Agent 行为、像调试 Node.js 服务一样追踪 Agent 执行、像发布 npm 包一样复用 Agent 能力的工程化基础设施。这正是 Cursor SDK 的核心价值。它不封装你，不替你决策，也不强制你用某套 DSL；它提供一组类型安全、可组合、带完整生命周期钩子的 TypeScript 接口，让你在熟悉的 VS Code 类编辑器里，用 const agent = new Agent({...}) 这样的语法，直接声明一个具备记忆、工具调用、多步推理、错误恢复能力的智能体。关键词“Cursor SDK”“TypeScript”“Agent”“SDK”“编程”在此不是并列标签，而是构成技术栈的四根支柱：Cursor 是运行时载体，TypeScript 是契约语言，Agent 是抽象目标，SDK 是实现桥梁。它解决的不是“怎么调 API”，而是“怎么把 AI 能力真正变成你代码库中可测试、可版本化、可协作的一等公民”。适合三类人：前端/全栈工程师想快速接入 AI 能力但拒绝黑盒 SDK；AI 应用开发者需要精细控制 LLM 调用链路与状态流转；以及技术负责人正在评估如何将 AI 原生能力系统性融入现有研发流程。这不是玩具，是我在给客户做自动化文档生成系统时，把原来需要 3 个微服务+1 套规则引擎的逻辑，压缩进 200 行可单测的 TypeScript 文件里的关键工具。

2. 核心设计思路拆解：为什么必须是“写代码”而非“配流程”？

2.1 拒绝低代码陷阱：从可视化编排到声明式编程的范式跃迁

市面上多数 Agent 框架（包括部分开源方案）依赖图形化流程图或 YAML 配置来定义行为。我试过用某知名低代码平台搭建一个带条件分支的客服对话 Agent，结果在第 5 次修改“用户说‘不满意’后跳转逻辑”时崩溃了——UI 拖拽界面卡顿，配置项含义模糊，错误提示只显示“节点执行失败”，根本无法定位是 JSON Schema 校验失败还是工具函数超时。Cursor SDK 的根本破局点在于： 它把 Agent 定义权彻底交还给程序员的 IDE 和键盘。 你不再面对一堆抽象图标，而是直接写：

const researchAgent = new Agent({
  name: "research-assistant",
  description: "Search and summarize technical documentation",
  tools: [searchTool, extractSectionTool],
  systemPrompt: `You are a senior dev advocate. Prioritize accuracy over speed.`,
  // 关键：用 TypeScript 类型约束输入输出
  inputSchema: z.object({
    query: z.string().describe("Technical question to research"),
    context: z.array(z.string()).optional()
  }),
  // 执行逻辑即普通 TS 函数，可断点、可单元测试
  execute: async ({ query, context }) => {
    const results = await searchTool.invoke({ query });
    return await extractSectionTool.invoke({ 
      content: results[0].body,
      section: "API Reference" 
    });
  }
});

这个写法背后有三层深意：第一， 类型即文档 。 inputSchema 不是配置项，而是运行时校验 + IDE 自动补全 + 生成 OpenAPI 文档的源头；第二， 逻辑即函数 。 execute 是标准异步函数，你能加 console.log 、设断点、mock 依赖、写 Jest 测试用例；第三， 组合即导入 。 researchAgent 可被另一个 reportingAgent 直接 import 并作为工具调用，形成真正的代码复用，而非复制粘贴配置。这比任何可视化编排都更符合工程师的直觉和工作流。

2.2 TypeScript 作为事实标准：从“能跑就行”到“编译即验证”

热词中反复出现的 “typescript” 和 “选项‘baseurl’已弃用” 并非偶然。Cursor SDK 的 TypeScript 支持不是“锦上添花”，而是架构基石。它利用 TS 的高级类型特性（如 infer 、模板字面量类型、递归类型）实现了三重保障：

工具签名强一致 ：当你注册一个 searchTool ，SDK 会自动推导其 inputSchema 和 outputSchema ，并在 Agent 调用时进行静态检查。如果 searchTool 返回 string[] ，而你在 execute 中试图 .map() 一个 number ，TS 编译器立刻报错，而不是等到运行时报 Cannot read property 'map' of undefined 。
状态机类型安全 ：Agent 的内部状态（如 memory 、 history ）被定义为泛型接口 AgentState<T> ，其中 T 是你自定义的状态结构。这意味着 agent.state.lastQuery 的类型是 string | undefined ，而非 any 。我在开发一个会议纪要 Agent 时，曾因状态字段名拼写错误（ lastQeury ）导致数据丢失，TS 在保存文件瞬间就标红了该行。
渐进式迁移友好 ：SDK 提供 @cursor/sdk/legacy 兼容层，允许你将旧的 JavaScript Agent 逐步迁入 TS 类型体系。我团队有个遗留的 Python 脚本驱动的 QA Agent，我们先用 // @ts-ignore 绕过类型检查，再逐个函数添加 JSDoc 类型注释，最后替换为纯 TS 实现——整个过程零停机，且每一步都有明确的类型收敛路径。

提示：“baseurl 已弃用”这类警告恰恰说明 TS 生态的成熟——它不再容忍模糊配置。Cursor SDK 的 AgentConfig 接口强制要求 baseUrl 字段，但同时提供 resolveBaseUrl() 工具函数，自动从环境变量或 package.json 中读取，既满足新规范，又避免硬编码。

2.3 SDK 定位：不是替代框架，而是“胶水层”与“加速器”

很多人误以为 Cursor SDK 是一个独立 Agent 框架（类似 LangChain 或 LlamaIndex）。这是最大误解。它的本质是 Cursor 编辑器与外部 AI 服务之间的标准化适配层 。你可以把它理解成“React 的 ReactDOM”：React 定义组件抽象，ReactDOM 负责把虚拟 DOM 渲染到真实浏览器；同理，Cursor SDK 定义 Agent 抽象（ Agent 、 Tool 、 Memory ），而 Cursor 编辑器负责把它们调度到本地 Ollama、远程 DeepSeek API 或企业私有模型集群。这种分层带来两个关键优势：

模型无关性 ：你的 researchAgent 代码完全不关心底层是调用 deepseek-coder-32b 还是 qwen2-72b 。只需在 Cursor 设置中切换模型端点，Agent 行为逻辑零修改。我在为客户做金融合规检查 Agent 时，前期用本地 Qwen2-7B 快速验证流程，上线前无缝切换到 Azure 托管的 GPT-4o，仅改了 1 行配置。
能力可插拔 ：SDK 不预设“必须用 RAG”或“必须支持多模态”。它提供 Tool 接口，你传入任何符合签名的函数即可。我曾用 fetch 封装一个股票行情查询工具，用 child_process.exec 封装一个本地 git diff 分析工具，甚至用 WebAssembly 加载一个 Rust 编写的 PDF 解析模块——它们在 SDK 眼里都是平等的 Tool 实例。这种开放性让 SDK 成为连接各种技术栈的“瑞士军刀”，而非封闭生态。

3. 核心细节与实操要点：从初始化到生产部署的完整链路

3.1 环境准备：避开那些没人提的“默认陷阱”

Cursor SDK 的安装看似简单（ npm install @cursor/sdk ），但实际部署中 80% 的问题源于环境配置。我踩过的坑和解决方案如下：

Node.js 版本陷阱 ：SDK 要求 Node.js ≥ 18.17.0，但 macOS 用户常通过 Homebrew 安装 node@18 ，其默认版本是 18.16.0 。运行 cursor-sdk init 时会静默失败，IDE 无报错，仅在终端看到 Error: Cannot find module 'node:fs/promises' 。解决方案：

# 升级到确切支持版本
brew upgrade node@18
# 验证
node -v # 必须输出 v18.17.0 或更高

TypeScript 配置陷阱 ：热词中“linux 安装 typescript”高频出现，但很多人忽略 tsconfig.json 的关键配置。SDK 依赖 moduleResolution: "bundler" 和 verbatimModuleSyntax: true 。若你沿用旧项目配置（ moduleResolution: "node" ），会出现 Cannot find module '@cursor/sdk' 错误。正确配置片段：

{
  "compilerOptions": {
    "target": "ES2020",
    "module": "ESNext",
    "lib": ["ES2020", "DOM"],
    "moduleResolution": "bundler", // 关键！非 "node"
    "verbatimModuleSyntax": true,  // 关键！启用精确导入解析
    "skipLibCheck": true,
    "forceConsistentCasingInFileNames": true,
    "strict": true,
    "noUncheckedIndexedAccess": true,
    "esModuleInterop": true,
    "resolveJsonModule": true,
    "allowSyntheticDefaultImports": true,
    "outDir": "./dist",
    "rootDir": "./src"
  }
}

Cursor 编辑器权限陷阱 ：在 macOS 上，首次运行 Agent 时可能弹出“此应用需要访问辅助功能”的系统提示。若用户点击“不允许”，后续所有 Agent.execute() 调用将静默返回空结果，且无日志。解决方案：

打开 系统设置 > 隐私与安全性 > 辅助功能
点击左下角锁图标解锁
点击 + 添加 /Applications/Cursor.app
重启 Cursor

注意：此步骤不可跳过，且必须在 Cursor 启动前完成。我曾为此排查 3 小时，最终发现是 macOS 的 SIP（系统完整性保护）拦截了 SDK 的进程注入机制。

3.2 Agent 构建核心：从 `new Agent()` 到可交付产品的五步法

构建一个生产可用 Agent 不是写完 execute 函数就结束。基于我交付的 7 个 Agent 项目，总结出标准化五步法：

第一步：定义最小可行输入（MVI）
不要一上来就设计复杂 schema。以“会议纪要生成 Agent”为例，MVI 就是 z.object({ transcript: z.string() }) 。用 zod 定义后，在 Cursor 中输入 agent.invoke({ transcript: "..." }) ，SDK 会自动校验字符串长度、JSON 格式等。我坚持先跑通 MVI，再逐步增加 meetingDate 、 attendees 等字段，避免早期陷入 schema 设计泥潭。

第二步：工具链原子化封装
每个 Tool 必须满足：单一职责、可独立测试、有明确超时。例如封装 web-search 工具：

import { Tool } from "@cursor/sdk";
import axios from "axios";

export const searchTool = new Tool({
  name: "web-search",
  description: "Search the web for up-to-date information",
  // 输入必须严格限定，避免 LLM 乱传参数
  inputSchema: z.object({
    query: z.string().min(2).max(200),
    numResults: z.number().int().min(1).max(5).default(3)
  }),
  // 执行函数内必须处理所有异常，返回结构化错误
  execute: async (input) => {
    try {
      const res = await axios.get("https://api.example.com/search", {
        params: { q: input.query, num: input.numResults },
        timeout: 8000 // 强制 8 秒超时
      });
      return res.data.results;
    } catch (err) {
      throw new Error(`Search failed: ${err instanceof Error ? err.message : 'Unknown error'}`);
    }
  }
});

关键点： timeout 是生命线，未设超时的工具会导致整个 Agent 卡死； throw new Error 是唯一错误传递方式，SDK 会捕获并注入到 LLM 的上下文。

第三步：状态管理策略选择
SDK 提供三种内存模式： InMemoryMemory （开发用）、 FileMemory （单机持久化）、 RedisMemory （分布式）。选择逻辑：

个人项目/POC：用 InMemoryMemory ，启动快，无依赖
团队协作/CI/CD：必须用 FileMemory ，指定 filePath: "./.cursor/memory.json" ，确保不同成员运行同一 Agent 时状态一致
多实例部署： RedisMemory ，需配置 REDIS_URL 环境变量
我在做“代码审查 Agent”时，初期用 InMemoryMemory ，上线前发现 PR 评论触发多次，导致重复审查。切换 FileMemory 后，通过文件锁机制保证同一 PR 只审查一次。

第四步：执行逻辑分层设计
execute 函数不是大杂烩。我采用三层结构：

预处理层 ：清洗输入、补充默认值、格式转换（如 transcript 转 segments[] ）
核心逻辑层 ：调用工具链、处理中间结果、执行业务规则（如“若检测到 PII 信息，必须脱敏”）
后处理层 ：格式化输出、添加元数据（如 generatedAt: new Date().toISOString() ）、触发 Webhook
这种分层让代码可读性提升 300%，且每层可单独单元测试。

第五步：可观测性埋点
生产环境必须添加日志和指标。SDK 提供 onStepStart 、 onStepEnd 、 onError 钩子：

const agent = new Agent({
  // ...其他配置
  hooks: {
    onStepStart: (step) => {
      console.log(`[AGENT] Step ${step.id} started: ${step.name}`);
      // 推送到 Datadog
      datadogMetrics.increment("agent.step.start", { name: step.name });
    },
    onError: (error, step) => {
      console.error(`[AGENT] Error in step ${step?.name}:`, error);
      // 发送告警
      alertService.send(`Agent ${agent.name} failed at ${step?.name}`);
    }
  }
});

没有这些钩子，Agent 就是黑盒。我在金融项目中，靠 onError 日志定位到某次模型响应格式突变（从 {"answer":"text"} 变为 {"response":"text"} ），30 分钟内修复。

3.3 高级技巧：让 Agent 真正“活”起来的三个实战模式

模式一：动态工具路由（Dynamic Tool Routing）
当 Agent 需要根据用户输入实时决定调用哪个工具时，静态 tools: [] 数组不够用。解决方案：用 getTools() 函数动态返回工具列表：

const dynamicAgent = new Agent({
  // ...其他配置
  getTools: async ({ input }) => {
    // 根据输入内容判断领域
    const domain = await classifyDomain(input.query); // 调用分类模型
    switch (domain) {
      case "finance": return [stockTool, newsTool];
      case "tech": return [searchTool, githubTool];
      default: return [searchTool];
    }
  }
});

此模式让单个 Agent 具备跨领域能力，避免为每个领域建独立 Agent。我在客户项目中用它统一处理“产品咨询”和“技术故障”两类请求，代码量减少 60%。

模式二：多 Agent 协作流水线（Swarm Pattern）
一个复杂任务（如“生成季度技术报告”）需多个 Agent 协作。SDK 支持 Agent 作为 Tool 注册：

// 定义子 Agent
const dataAgent = new Agent({ /* 数据提取 */ });
const analysisAgent = new Agent({ /* 趋势分析 */ });

// 主 Agent 注册子 Agent 为工具
const reportAgent = new Agent({
  tools: [
    // 将子 Agent 包装为 Tool
    new Tool({
      name: "extract-data",
      description: "Extract metrics from raw logs",
      inputSchema: z.object({ logs: z.string() }),
      execute: (input) => dataAgent.invoke(input) // 直接调用
    }),
    new Tool({
      name: "analyze-trends",
      description: "Analyze extracted metrics for trends",
      inputSchema: z.object({ metrics: z.record(z.number()) }),
      execute: (input) => analysisAgent.invoke(input)
    })
  ],
  execute: async ({ rawLogs }) => {
    const metrics = await this.tools["extract-data"].invoke({ rawLogs });
    return await this.tools["analyze-trends"].invoke({ metrics });
  }
});

这种模式天然支持水平扩展—— dataAgent 和 analysisAgent 可部署在不同服务器，主 Agent 通过 HTTP 调用。我在处理 TB 级日志分析时，用此模式将数据提取（CPU 密集）和趋势分析（GPU 密集）分离部署。

模式三：人类反馈闭环（Human-in-the-Loop）
对关键决策（如“是否批准高危代码变更”），必须引入人工审核。SDK 的 waitForHumanInput 钩子完美支持：

const securityAgent = new Agent({
  // ...其他配置
  hooks: {
    beforeExecute: async ({ input }) => {
      if (input.codeChange.includes("eval(")) {
        // 触发人工审核
        const approval = await waitForHumanInput({
          prompt: `Critical security risk detected: 'eval()' usage in ${input.file}. Approve?`,
          options: ["APPROVE", "REJECT", "REQUEST_MORE_INFO"]
        });
        if (approval !== "APPROVE") {
          throw new Error(`Human rejected: ${approval}`);
        }
      }
    }
  }
});

此模式已在我们客户的 CI/CD 流程中落地，所有含 eval 、 Function 构造的 PR 都需安全团队二次确认，误报率降为 0。

4. 实操过程详解：从零搭建一个“PR 自动化审查 Agent”

4.1 项目初始化与依赖安装

创建新项目目录，初始化 npm：

mkdir pr-review-agent && cd pr-review-agent
npm init -y
npm install @cursor/sdk zod axios @types/node
npm install -D typescript ts-node @types/axios

关键点： @types/node 是必须的，否则 fs.promises 等 API 无类型定义； ts-node 用于本地快速测试，无需每次 tsc 编译。

创建 tsconfig.json ，采用前文所述的严格配置。特别注意 "moduleResolution": "bundler" 和 "verbatimModuleSyntax": true 。

4.2 核心工具开发： `github-pr-tool.ts`

封装 GitHub API 调用，专注 PR 内容获取：

import { Tool } from "@cursor/sdk";
import axios from "axios";
import { z } from "zod";

// 定义输入 Schema，强制要求 owner/repo 和 PR number
export const githubPrTool = new Tool({
  name: "get-pr-diff",
  description: "Fetch the code diff of a GitHub Pull Request",
  inputSchema: z.object({
    owner: z.string().describe("GitHub organization or username"),
    repo: z.string().describe("Repository name"),
    prNumber: z.number().int().positive().describe("Pull Request number")
  }),
  execute: async (input) => {
    try {
      // 使用 GitHub Token 认证（从环境变量读取）
      const token = process.env.GITHUB_TOKEN;
      if (!token) throw new Error("GITHUB_TOKEN not set");

      const response = await axios.get(
        `https://api.github.com/repos/${input.owner}/${input.repo}/pulls/${input.prNumber}`,
        {
          headers: {
            "Authorization": `Bearer ${token}`,
            "Accept": "application/vnd.github.v3.diff"
          },
          timeout: 10000
        }
      );

      // GitHub API 返回的是纯文本 diff，需解析
      const diffText = response.data;
      const files = parseDiff(diffText); // 自定义解析函数

      return {
        prTitle: response.data.title,
        prDescription: response.data.body,
        changedFiles: files.map(f => ({
          filename: f.filename,
          additions: f.additions,
          deletions: f.deletions,
          diff: f.diff
        }))
      };
    } catch (error) {
      throw new Error(`Failed to fetch PR ${input.prNumber}: ${error instanceof Error ? error.message : 'Unknown'}`);
    }
  }
});

// 简单的 diff 解析（生产环境建议用专用库如 diff-match-patch）
function parseDiff(diffText: string): Array<{ filename: string; additions: number; deletions: number; diff: string }> {
  const lines = diffText.split("\n");
  const files: Array<{ filename: string; additions: number; deletions: number; diff: string }> = [];
  let currentFile: { filename: string; additions: number; deletions: number; diff: string } | null = null;

  for (const line of lines) {
    if (line.startsWith("diff --git")) {
      if (currentFile) files.push(currentFile);
      const match = line.match(/a\/(.+) b\/\1/);
      currentFile = match ? { 
        filename: match[1], 
        additions: 0, 
        deletions: 0, 
        diff: "" 
      } : null;
    } else if (currentFile && line.startsWith("@@")) {
      // 提取行号信息（简化版）
      const hunkMatch = line.match(/@@ -\d+,\d+ \+(\d+),(\d+) @@/);
      if (hunkMatch) {
        currentFile.additions += parseInt(hunkMatch[2]);
      }
    } else if (currentFile) {
      currentFile.diff += line + "\n";
      if (line.startsWith("+")) currentFile.additions++;
      if (line.startsWith("-")) currentFile.deletions++;
    }
  }
  if (currentFile) files.push(currentFile);
  return files;
}

此工具的关键设计：

强认证 ： GITHUB_TOKEN 从环境变量读取，避免硬编码
强超时 ：10 秒超时，防止 GitHub API 延迟拖垮整个 Agent
结构化输出 ：返回 changedFiles 数组，每个文件包含 additions / deletions ，为后续安全扫描提供量化依据

4.3 安全扫描工具： `security-scan-tool.ts`

基于规则的静态分析，识别高危模式：

import { Tool } from "@cursor/sdk";
import { z } from "zod";

export const securityScanTool = new Tool({
  name: "scan-for-security-risks",
  description: "Scan code changes for common security vulnerabilities",
  inputSchema: z.object({
    changedFiles: z.array(z.object({
      filename: z.string(),
      diff: z.string()
    }))
  }),
  execute: async (input) => {
    const risks: Array<{ 
      file: string; 
      line: number; 
      pattern: string; 
      severity: "CRITICAL" | "HIGH" | "MEDIUM" 
    }> = [];

    // 定义高危模式（生产环境应使用更完善的规则引擎）
    const patterns = [
      { regex: /eval\s*\(/gi, pattern: "eval()", severity: "CRITICAL" as const },
      { regex: /new\s+Function\s*\(/gi, pattern: "new Function()", severity: "CRITICAL" as const },
      { regex: /process\.env\.(\w+)/gi, pattern: "process.env.*", severity: "HIGH" as const },
      { regex: /console\.log\s*\(/gi, pattern: "console.log", severity: "MEDIUM" as const }
    ];

    for (const file of input.changedFiles) {
      const lines = file.diff.split("\n");
      for (let i = 0; i < lines.length; i++) {
        const line = lines[i];
        for (const { regex, pattern, severity } of patterns) {
          if (regex.test(line)) {
            // 计算在原始文件中的行号（简化：假设 + 行是新增）
            const originalLine = line.startsWith("+") ? i + 1 : i;
            risks.push({
              file: file.filename,
              line: originalLine,
              pattern,
              severity
            });
          }
        }
      }
    }

    return {
      totalRisks: risks.length,
      criticalRisks: risks.filter(r => r.severity === "CRITICAL").length,
      risks
    };
  }
});

此工具体现 SDK 的核心优势： 规则可编程、可测试、可迭代 。当客户提出“新增检测 JWT 密钥硬编码”需求时，我只需在 patterns 数组中加一行正则，3 分钟完成上线。

4.4 主 Agent 实现： `pr-review-agent.ts`

整合工具，定义审查逻辑：

import { Agent } from "@cursor/sdk";
import { z } from "zod";
import { githubPrTool } from "./github-pr-tool";
import { securityScanTool } from "./security-scan-tool";

// 定义 Agent 输入 Schema
const PrReviewInput = z.object({
  githubOwner: z.string(),
  githubRepo: z.string(),
  prNumber: z.number().int().positive()
});

export const prReviewAgent = new Agent({
  name: "pr-reviewer",
  description: "Automatically review GitHub Pull Requests for security and quality issues",
  inputSchema: PrReviewInput,
  tools: [githubPrTool, securityScanTool],
  systemPrompt: `
You are an expert senior developer reviewing PRs.
- Focus on security risks first (CRITICAL/HIGH severity).
- For CRITICAL risks, recommend immediate rejection.
- For HIGH risks, suggest fixes.
- For MEDIUM risks, note for awareness.
- Always cite exact file and line number.
- Output in concise markdown.
  `,
  execute: async ({ githubOwner, githubRepo, prNumber }) => {
    // 步骤1：获取 PR 详情
    const prData = await githubPrTool.invoke({ 
      owner: githubOwner, 
      repo: githubRepo, 
      prNumber 
    });

    // 步骤2：扫描安全风险
    const scanResult = await securityScanTool.invoke({ 
      changedFiles: prData.changedFiles 
    });

    // 步骤3：生成审查结论（此处可替换为 LLM 调用，但为演示简洁性，用规则生成）
    let conclusion = `## PR Review Summary for #${prNumber}\n\n`;
    conclusion += `**Title**: ${prData.prTitle}\n`;
    conclusion += `**Files Changed**: ${prData.changedFiles.length}\n`;
    conclusion += `**Security Risks**: ${scanResult.totalRisks} (CRITICAL: ${scanResult.criticalRisks})\n\n`;

    if (scanResult.criticalRisks > 0) {
      conclusion += "### ⚠️ CRITICAL ISSUES DETECTED - REJECT REQUIRED\n\n";
      for (const risk of scanResult.risks.filter(r => r.severity === "CRITICAL")) {
        conclusion += `- \`${risk.file}\` line ${risk.line}: **${risk.pattern}**\n`;
      }
      conclusion += "\n**Action**: This PR must be rejected and fixed before merging.\n";
    } else if (scanResult.totalRisks > 0) {
      conclusion += "### 🔍 HIGH/MEDIUM ISSUES TO ADDRESS\n\n";
      for (const risk of scanResult.risks) {
        conclusion += `- \`${risk.file}\` line ${risk.line}: **${risk.pattern}** (${risk.severity})\n`;
      }
      conclusion += "\n**Action**: Address HIGH severity issues before merging.\n";
    } else {
      conclusion += "### ✅ NO SECURITY ISSUES FOUND\n\n";
      conclusion += "This PR appears secure from known vulnerability patterns.";
    }

    return conclusion;
  }
});

此 Agent 的精妙之处在于：

输入即契约 ： PrReviewInput Schema 确保调用者必须传 githubOwner / repo / prNumber ，缺失任一字段编译即报错
工具即服务 ： githubPrTool 和 securityScanTool 是独立模块，可被其他 Agent 复用
输出即交付物 ：返回 Markdown 格式，可直接粘贴到 GitHub PR 评论区，或通过 Webhook 自动发布

4.5 本地测试与调试：用真实数据验证

创建 test.ts 进行端到端测试：

import { prReviewAgent } from "./pr-review-agent";

// 模拟真实输入（从你自己的一个 PR 获取）
const testInput = {
  githubOwner: "your-org",
  githubRepo: "your-repo",
  prNumber: 123
};

// 启用详细日志
prReviewAgent.hooks = {
  onStepStart: (step) => console.log(`[STEP START] ${step.name}`),
  onStepEnd: (step) => console.log(`[STEP END] ${step.name} took ${step.durationMs}ms`),
  onError: (err) => console.error("[ERROR]", err)
};

// 执行测试
async function runTest() {
  try {
    const result = await prReviewAgent.invoke(testInput);
    console.log("✅ Review Result:\n", result);
  } catch (error) {
    console.error("❌ Test Failed:", error);
  }
}

runTest();

运行命令：

# 设置环境变量
export GITHUB_TOKEN="your-personal-access-token"
# 运行测试
npx ts-node test.ts

调试技巧：在 VS Code 中按 F5 启动调试，可在 execute 函数内设断点，查看 prData 和 scanResult 的实时结构，比任何日志都直观。

4.6 生产部署：集成到 GitHub Actions

创建 .github/workflows/pr-review.yml ：

name: PR Review Automation
on:
  pull_request:
    types: [opened, synchronize]

jobs:
  review:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Setup Node.js
        uses: actions/setup-node@v4
        with:
          node-version: '18'
      - name: Install dependencies
        run: npm ci
      - name: Run PR Review Agent
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
        run: npx ts-node ./src/pr-review-agent.ts \
          --owner ${{ github.repository_owner }} \
          --repo ${{ github.event.repository.name }} \
          --pr-number ${{ github.event.pull_request.number }}

关键点： secrets.GITHUB_TOKEN 是 GitHub Actions 自动提供的，无需手动配置； npx ts-node 直接运行 TS 文件，省去编译步骤，加快 CI 时间。

5. 常见问题与排查技巧实录：来自真实战场的 12 个高频问题

5.1 连接超时与网络问题

问题现象	根本原因	解决方案
`Agent.invoke()` 报错 `Timeout awaiting 'request' for 8000ms`	SDK 默认 8 秒超时，但某些模型 API（如私有部署的 Qwen）响应慢	在 `Agent` 配置中显式设置 `timeoutMs: 30000` ；或在 `Tool` 的 `execute` 函数中用 `axios` 的 `timeout` 参数覆盖
`Error: connect ECONNREFUSED 127.0.0.1:11434`	本地 Ollama 服务未启动，或端口被占用	运行 `ollama serve` 启动服务；用 `lsof -i :11434` 查看端口占用进程并 `kill`
`Request failed with status code 401`	`GITHUB_TOKEN` 过期或权限不足	重新生成 Personal Access Token，勾选 `public_repo` 和 `workflow` 权限

实操心得：我建立了一个 health-check.ts 脚本，每次部署前运行它测试所有依赖服务（Ollama、Redis、GitHub API）的连通性，5 分钟内定位 90% 的环境问题。

5.2 TypeScript 类型错误

问题现象	根本原因	解决方案
`Property 'invoke' does not exist on type 'Agent<...>'`	`@cursor/sdk` 类型定义未被正确加载	删除 `node_modules` 和 `package-lock.json` ，重新 `npm install` ；检查 `tsconfig.json` 中 `typeRoots` 是否包含 `node_modules/@cursor/sdk`
`Type 'string' is not assignable to type 'never'`	`inputSchema` 中字段名拼写错误，TS 无法推导类型	在 `inputSchema` 对象上按 `Ctrl+Space` 触发 IDE 补全，或打开 `node_modules/@cursor/sdk/index.d.ts` 查看接口定义
`Argument of type '{...}' is not assignable to parameter of type 'InferInputSchema<...>'`	传入 `invoke()` 的参数对象缺少 `inputSchema` 中定义的必填字段	使用 `zod` 的 `safeParse()` 先校验： `const result = PrReviewInput.safeParse(input); if (!result.success) throw new Error(result.error.message);`