追踪 Cursor 会话

在 LangSmith 中捕获 Cursor agent 轮次、工具调用、模型元数据、token 使用量、附件和子 agent。

在 LangSmith 中追踪 Cursor agent 会话，使用 Cursor hooks。每个轮次成为一个追踪，并按 Cursor 对话分组为一个线程，捕获提示、模型响应、工具调用、token 使用量和子 agent 活动。使用追踪来调试 agent 行为、审计工具调用、跟踪每轮 token 花费并比较 Cursor 运行。

插件源代码位于 langchain-ai/langsmith-cursor-plugins。

前置条件

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

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

安装并启用插件

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

1. 打开 Cursor > Settings > Plugins。
2. 将 https://github.com/langchain-ai/langsmith-cursor-plugins 粘贴到插件链接字段中。
3. 确认添加 LangSmith Tracing for Cursor。

这是推荐路径：它安装 hooks 时无需克隆或构建步骤，因为仓库附带预编译的 bundle。

WARNING

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

替代方案：从本地克隆安装

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

node scripts/install.mjs

要将 hooks 限定到单个项目，请从项目目录运行安装程序：

node scripts/install.mjs --project

要预览 hook 配置而不写入，请运行：

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_REDACT	true	设置为 "false" 以禁用机密脱敏。
LANGSMITH_CURSOR_REDACT_EXTRA	-	额外 { pattern, replace } 脱敏规则的 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	覆盖 hook 日志文件。
LANGSMITH_CURSOR_DEBUG	false	设置为 "true" 以启用详细 hook 日志记录。

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

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

要验证 hook 活动，请跟踪日志文件：

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 目标。
redact	LANGSMITH_CURSOR_REDACT、LANGSMITH_REDACT	true	设置为 false 以禁用机密脱敏。
redact_extra_rules	LANGSMITH_CURSOR_REDACT_EXTRA、LANGSMITH_REDACT_EXTRA	-	在内置规则之后应用的额外 { pattern, replace } 规则。
attachments	LANGSMITH_CURSOR_ATTACHMENTS	true	设置为 false 以跳过使用 Cursor 本地数据库中的图像和文件附件字节来丰富轮次。
cursor_db_path	LANGSMITH_CURSOR_DB_PATH	平台默认值	覆盖用于附件的 Cursor state.vscdb 路径。

请勿将包含 API key 的配置文件纳入版本控制。

密钥脱敏

插件会在将检测到的密钥从运行输入、输出、错误和元数据上传到 LangSmith 之前对其进行脱敏。脱敏默认开启。

脱敏在上传前于你的机器上运行，因此未脱敏的内容永远不会到达 LangSmith。副本目标接收相同的脱敏负载。

检测涵盖提供程序 API 密钥前缀、JSON Web Token 和 PEM 私钥块。它还涵盖上下文形态，例如 API_KEY=<value>、Authorization header 以及嵌入 URL 的密码。每个匹配项都会替换为 [SECRET_DETECTED]。有关规则列表，请参阅从追踪中脱敏密钥。

脱敏匹配已知的凭据形态，因此请将其视为安全网而非保证。格式无法识别的凭据仍会到达 LangSmith，附件、运行名称和标签不会经过匿名器。已脱敏的追踪仍保留构建它时使用的提示、文件内容和工具结果，因此请限制谁可以读取追踪项目。

附件完全绕过脱敏。插件从 Cursor 的本地数据库恢复图像和文件附件并发送它们的字节，匿名化器从不会检查这些内容。将 LANGSMITH_CURSOR_ATTACHMENTS 设置为 "false" 以停止发送它们。

要关闭脱敏，请将 LANGSMITH_CURSOR_REDACT 设置为 false、0、no 或 off，或在配置文件中设置 "redact": false。

要脱敏其他模式，请将 LANGSMITH_CURSOR_REDACT_EXTRA 设置为 { "pattern": ..., "replace": ... } 规则的 JSON 数组，或在配置文件中设置 redact_extra_rules。每个 pattern 是正则表达式字符串，以全局且区分大小写的方式应用。replace 是可选的，回退到 [redacted]。额外规则在内置规则之后运行。

{
  "enabled": true,
  "project": "cursor",
  "redact": true,
  "redact_extra_rules": [{ "pattern": "ACME-[A-Z0-9]{16}", "replace": "[REDACTED_ACME_KEY]" }]
}

将 redact_extra_rules 设置为 [] 会清除从较低优先级来源继承的规则。一个正则表达式无效的规则会丢弃该文件中的所有设置，因此请保持模式简单，并在提交前验证它们。

由于项目级 .cursor/langsmith.json 可以将 redact 设置为 false，在你无法控制的仓库中启用追踪之前，请检查该文件。

追踪内容

该插件监听 Cursor hooks，并为每个 agent 轮次组装一个追踪：

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

NOTE

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

WARNING

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

追踪元数据

每次运行都会在 run.extra.metadata 上携带共享的 coding-agent-v1 元数据契约，这使得来自任何编码 agent（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（暂定）。
仅子 agent 运行	ls_subagent_id、ls_subagent_type。
仅工具运行	ls_tool_name（仅当运行名称与原生工具名称不同时发出）。
仅模型和工具运行	ls_provider、ls_model_name、ls_invocation_params、usage_metadata。

Cursor 的 hooks 不暴露 user_id、sandbox_type 或 approval_policy 的稳定来源，因此省略这些键。

在 LangSmith 中查看追踪

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

Cursor Turn N (chain)
├── <provider> (llm)   model and provider, token usage, assistant text
├── Read / Shell / ... (tool)
└── Task (tool)        subagent (type and task)

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

已知限制

• 子 agent token 使用量：Cursor 不通过 hooks 或其本地数据库暴露每个子 agent 的使用量明细，因此子 agent 的 Task 运行会携带其工具调用，但没有 token 计数。

故障排查

如果追踪未出现在 LangSmith 中：

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

---