追踪 Cursor 会话

使用 Cursor 钩子在 LangSmith 中追踪 Cursor 代理会话。每个轮次都将成为一个追踪，并按每个 Cursor 对话归类到一个线程中，其中捕获了提示、模型响应、工具调用、令牌用量和子代理活动。利用这些追踪来调试代理行为、审计工具调用、跟踪每个轮次的令牌消耗，以及比较不同的 Cursor 运行。插件源代码位于 langchain-ai/langsmith-cursor-plugins。

先决条件

在设置追踪之前，请确保您已具备：

已安装 Cursor。
Node.js 22.13 或更高版本。钩子使用内置的 node:sqlite 模块从 Cursor 的本地数据库中恢复附件。
一个 LangSmith API 密钥。

安装并启用插件

直接在 Cursor 的设置中从 GitHub 仓库安装插件：

打开 Cursor → 设置 → 插件。
将 https://github.com/langchain-ai/langsmith-cursor-plugins 粘贴到插件链接字段。
确认添加 LangSmith Tracing for Cursor。

这是推荐的方式：它无需克隆或构建步骤即可安装钩子，因为该仓库提供了一个预编译的 bundle。

安装后请完全重启 Cursor，以便它重新加载 hooks.json。

备选方案：从本地克隆安装

从 langsmith-cursor-plugins 的本地克隆安装钩子。这会为所有 Cursor 项目写入 ~/.cursor/hooks.json：

node scripts/install.mjs

要将钩子范围限定为单个项目，请从项目目录运行安装程序：

node scripts/install.mjs --project

要预览钩子配置而不写入文件，请运行：

node scripts/install.mjs --print

安装程序会将其条目与现有的 hooks.json 合并。仓库中提交的 bundle/ 意味着这些命令无需运行 pnpm install 或 pnpm build —— 仅在向 TypeScript 源代码贡献更改时才需要这些步骤。安装后请重启 Cursor，以便它重新加载 hooks.json。

配置追踪

在设置 enabled (或 TRACE_TO_LANGSMITH=true) 和 API 密钥之前，追踪处于禁用状态。使用环境变量、JSON 配置文件或两者同时来配置凭据。

环境变量

每个 LANGSMITH_CURSOR_* 变量也接受较短的 LANGSMITH_* 形式。当两者都设置时，LANGSMITH_CURSOR_* 优先。

变量	默认值	描述
`TRACE_TO_LANGSMITH`	`false`	设置为 `"true"` 以启用追踪。
`LANGSMITH_CURSOR_API_KEY`	-	LangSmith API 密钥。如果未设置，则回退到 `LANGSMITH_API_KEY`。
`LANGSMITH_CURSOR_ENDPOINT`	`https://api.smith.langchain.com`	LangSmith API URL。如果未设置，则回退到 `LANGSMITH_ENDPOINT`。
`LANGSMITH_CURSOR_PROJECT`	`cursor`	LangSmith 项目名称。如果未设置，则回退到 `LANGSMITH_PROJECT`。
`LANGSMITH_CURSOR_METADATA`	-	合并到根追踪元数据中的 JSON 对象。
`LANGSMITH_CURSOR_RUNS_ENDPOINTS`	-	用于副本的目标 JSON 数组。
`LANGSMITH_CURSOR_ATTACHMENTS`	`true`	设置为 `"false"` 以禁用附件数据增强。
`LANGSMITH_CURSOR_DB_PATH`	平台默认值	覆盖用于附件的 Cursor `state.vscdb` 路径。
`LANGSMITH_CURSOR_STATE_FILE`	`~/.cursor/langsmith-state.json`	覆盖磁盘上的事件缓冲状态文件。
`LANGSMITH_CURSOR_LOG_FILE`	`~/.cursor/langsmith-hook.log`	覆盖钩子日志文件。
`LANGSMITH_CURSOR_DEBUG`	`false`	设置为 `"true"` 以启用详细的钩子日志记录。

将变量添加到您的 shell 配置文件（~/.zshrc、~/.bashrc 或 ~/.bash_profile）中：

export TRACE_TO_LANGSMITH="true"
export LANGSMITH_CURSOR_API_KEY="<your-langsmith-api-key>"
export LANGSMITH_CURSOR_PROJECT="cursor"

要验证钩子活动，请查看日志文件的末尾：

tail -f ~/.cursor/langsmith-hook.log

配置文件

使用 ~/.cursor/langsmith.json 进行全局默认设置，或使用 ./.cursor/langsmith.json 进行项目级设置。设置按以下顺序解析，后面的源覆盖前面的源：默认值、全局配置、项目配置、环境变量。

{
  "enabled": true,
  "api_key": "<your-langsmith-api-key>",
  "api_url": "https://api.smith.langchain.com",
  "project": "cursor"
}

字段	环境变量	默认值	描述
`enabled`	`TRACE_TO_LANGSMITH`	`false`	设置为 `true` 以启用追踪。
`api_key`	`LANGSMITH_CURSOR_API_KEY`, `LANGSMITH_API_KEY`	-	LangSmith API 密钥。
`api_url`	`LANGSMITH_CURSOR_ENDPOINT`, `LANGSMITH_ENDPOINT`	`https://api.smith.langchain.com`	LangSmith API URL。
`project`	`LANGSMITH_CURSOR_PROJECT`, `LANGSMITH_PROJECT`	`cursor`	LangSmith 项目名称。
`metadata`	`LANGSMITH_CURSOR_METADATA`, `LANGSMITH_METADATA`	-	合并到根追踪元数据中的对象。
`replicas`	`LANGSMITH_CURSOR_RUNS_ENDPOINTS`, `LANGSMITH_RUNS_ENDPOINTS`	-	用于复制追踪的其他 LangSmith 目标。
`attachments`	`LANGSMITH_CURSOR_ATTACHMENTS`	`true`	设置为 `false` 以跳过使用来自 Cursor 本地数据库的图像和文件附件字节来增强轮次。
`cursor_db_path`	`LANGSMITH_CURSOR_DB_PATH`	平台默认值	覆盖用于附件的 Cursor `state.vscdb` 路径。

请将包含 API 密钥的配置文件排除在版本控制之外。

追踪内容

该插件监听 Cursor 钩子，并为每个代理轮次组装一个追踪：

轮次：每个轮次都成为其自己的追踪，使用 thread_id = Cursor 的 conversation_id 归类到一个线程中。该追踪将模型运行以及任何工具或子代理运行嵌套在轮次之下。
令牌用量：模型运行上的每个轮次 usage_metadata。
模型和提供商：ls_model_name 和 ls_provider，从 Cursor 的模型标签规范化为规范的提供商 ID（例如，claude-4.6-sonnet 变为 claude-sonnet-4-6）。自动模式报告 default，提供商为 cursor。
工具调用：包括成功调用和失败的工具运行，附带输入和输出。
附件：从 Cursor 的本地数据库恢复的图像和文件附件，并在用户消息中内联渲染。将 attachments 设置为 false 可跳过此步骤。
子代理：每个子代理显示为一个嵌套的链运行，下面有自己的工具调用，并链接到父轮次。

该插件不在本地计算成本。因为 ls_model_name 被规范化为规范 ID 且 usage_metadata 携带了令牌细分，LangSmith 的服务器端模型价格表会在 UI 中渲染成本。自动模式报告 default，LangSmith 无法为其定价。

该插件上传 Cursor 对话数据，包括提示、模型响应、工具输入和输出，以及恢复的附件。请不要为包含您不希望存储在 LangSmith 中的数据的会话启用追踪。

追踪元数据

每个运行在 run.extra.metadata 上都携带共享的 coding-agent-v1 元数据契约，这使得来自任何编码代理（Claude Code、Codex、Cursor）的追踪可以被识别并使用相同的稳定键进行分组。

范围	键
始终存在	`ls_agent_type` (`"root"`, `"subagent"`, `"middleware"`, 或 `"compaction"`), `ls_agent_purpose` (`"coding"`), `ls_integration` (`"cursor"`), `ls_agent_runtime` (`"Cursor"`), `ls_trace_schema_version` (`"coding-agent-v1"`), `thread_id` (= Cursor 的 `conversation_id`).
已知时存在	`ls_integration_version`, `ls_agent_runtime_version` (Cursor 的 `cursor_version`), `turn_id` (= Cursor 的 `generation_id`), `turn_number`, `repository_url`, `repository_provider`, `repository_name`, `git_branch`, `git_commit_sha`, `cwd`.
上下文相关	`local_username`, `user_email` (临时).
仅限子代理运行	`ls_subagent_id`, `ls_subagent_type`.
仅限工具运行	`ls_tool_name` (仅当运行名称与原生工具名称不同时发出).
仅限模型和工具运行	`ls_provider`, `ls_model_name`, `ls_invocation_params`, `usage_metadata`.

Cursor 的钩子不暴露用于 user_id、sandbox_type 或 approval_policy 的稳定来源，因此省略了这些键。

在 LangSmith 中查看追踪

打开配置的 LangSmith 项目（默认为 cursor）并完成一个 Cursor 轮次。该插件上传每个轮次的一个追踪，结构如下：

Cursor 轮次 N (链)
├── <提供商> (大语言模型)   模型和提供商，令牌用量，助手文本
├── 读取 / Shell / ... (工具)
└── 任务 (工具)        子代理（类型和任务）

要将相关的轮次分组，请在项目的 Threads 选项卡中按 thread_id 进行过滤。

已知限制

子代理令牌用量：Cursor 不通过钩子或其本地数据库公开每个子代理的用量细分，因此子代理的 Task 运行包含其工具调用，但不包含令牌计数。

故障排除

如果追踪未出现在 LangSmith 中：

确认在 Cursor 进程可见的配置文件中设置了 TRACE_TO_LANGSMITH=true 或 "enabled": true。
确认 LANGSMITH_CURSOR_API_KEY 或 LANGSMITH_API_KEY 已设置且有效。
确认在安装钩子后已完全重启 Cursor。
查看钩子日志中的错误：tail -f ~/.cursor/langsmith-hook.log。
使用 LANGSMITH_CURSOR_DEBUG=true 启用详细日志记录并重新检查日志。
如果运行结果出现在错误的项目中，请设置 LANGSMITH_CURSOR_PROJECT 或 project 配置键。

Connect these docs to Claude, VSCode, and more via MCP for real-time answers.

Edit this page on GitHub or file an issue.

Tracing setup

Configuration & troubleshooting

先决条件

安装并启用插件

备选方案：从本地克隆安装

配置追踪

环境变量

配置文件

追踪内容

追踪元数据

在 LangSmith 中查看追踪

已知限制

故障排除

​先决条件

​安装并启用插件

​备选方案：从本地克隆安装

​配置追踪

​环境变量

​配置文件

​追踪内容

​追踪元数据

​在 LangSmith 中查看追踪

​已知限制

​故障排除

先决条件

安装并启用插件

备选方案：从本地克隆安装

配置追踪

环境变量

配置文件

追踪内容

追踪元数据

在 LangSmith 中查看追踪

已知限制

故障排除