cursor-byok/.agents/skills/cursor-client-e2e-debugging/references/search-patterns.md

搜索词与判断树

先判断层级

history + logs / id 反查层

当现象是“用户只给了一个 id”“需要判断它是 conversationId、requestId、modelCallId、toolCallId”“要从本地 history 和日志追状态”：

优先搜索：

• state.json
• context.json
• usage.json
• logs/app.log
• conversation_id
• current_request_id
• request_id
• model_call_id
• tool_call_id
• latest_request_prefix
• last_provider_call
• current_loop_status
• context_version
• next_entry_seq
• next_turn_seq
• LoadConversation
• CreateConversation
• SaveConversationWithEntries
• AppendEntries
• UpdateConversationMeta
• ReplaceEntries
• ProjectPromptReplay
• UsageFileStore
• UpsertEvent
• LookupEvent

不要再优先搜索或依赖：

• data.sqlite
• protocol_traces
• agent_request_runs
• conversation.json
• entries.jsonl
• turns/<n>
• request.json
• sse.jsonl
• summary.json

这些是旧实现或 legacy artifact 相关线索，只在排查迁移/清理逻辑时作为历史背景。

cursor-agent-exec / cursor-agent-worker 层

当现象涉及 agent 主循环、模型桥接、InteractionUpdate 映射、工具 started/completed、session/provider 状态：

优先在已安装客户端 split bundle 中搜索：

• /Applications/Cursor.app/Contents/Resources/app/extensions/cursor-agent-exec/dist/main.js
• /Applications/Cursor.app/Contents/Resources/app/extensions/cursor-agent-exec/dist/*.js
• /Applications/Cursor.app/Contents/Resources/app/extensions/cursor-agent-worker/dist/main.js

优先搜索：

• registerAgentProvider
• CursorAgentProvider
• CursorAgentProviderHandle
• ClaudeSDKClient
• streamInteractionUpdates
• handlePartialMessage
• AnthropicProxy
• getAnthropicProxyPort
• getAnthropicProxyAuthToken
• ANTHROPIC_BASE_URL
• ANTHROPIC_API_KEY
• InteractionUpdate
• checkpoint

旧路径 /Applications/Cursor.app/Contents/Resources/app/extensions/cursor-agent/dist/main.js 可能不存在。先确认实际 extensions/ 结构，再按 cursor-agent-exec / cursor-agent-worker / cursor-always-local 分层排查。

agent window / conversation metadata UI 层

当现象涉及 agent window 标题、窗口信息、titlebar 按钮、是否可点击修改、会话名/metadata 更新：

优先在已安装客户端主 UI 和 split bundle 中搜索：

• /Applications/Cursor.app/Contents/Resources/app/out/vs/workbench/workbench.desktop.main.js
• /Applications/Cursor.app/Contents/Resources/app/extensions/cursor-agent-exec/dist/main.js
• /Applications/Cursor.app/Contents/Resources/app/extensions/cursor-agent-exec/dist/*.js
• /Applications/Cursor.app/Contents/Resources/app/extensions/cursor-always-local/dist/main.js

优先搜索：

• shouldShowAgentWindowTitleHelperText
• glass_open_agents_titlebar_button
• open_agent_window_top
• open_agent_window_bottom_convo
• glass.enable_open_agent_in_window
• NameAgentRequest
• NameAgentResponse
• UpdateConversationMetadataRequest
• UpdateConversationMetadataResponse
• CreateTranscriptOverviewRequest
• createTranscriptOverview
• updateConversationMetadata
• conversation_checkpoint_update

判断规则：

• ConversationStateStructure / conversation_checkpoint_update 是 UI 同步快照，不应作为持久化修改入口。
• 如果客户端调用 UpdateConversationMetadata / NameAgent，要继续确认本地后端是否显式注册对应 /agent.v1.AgentService/* 路由；不能只看 proto message 存在。
• 本地模式修改会话名/metadata 时，应落到 history/<conversationId>/state.json 或等价持久化会话元数据，再 publish checkpoint 同步 UI。

cursor-always-local / 协议层

当现象涉及本地模式、客户端没有回包、pending 不收口、同一 backend 进程内的 live checkpoint 重连错乱：

优先搜索：

• BidiTransport
• startYieldingInputsToTheServer
• BidiAppend
• RunSSE
• AgentServerMessage
• AgentClientMessage
• ExecServerMessage
• ExecClientMessage
• ExecClientControlMessage
• InteractionQuery
• InteractionResponse
• conversation_checkpoint_update

本仓库 forwarder 层

当现象涉及本地后端收发、provider 继续/暂停、exec/interaction 桥接、history 投影：

优先搜索：

• handleRunIntent
• driveProvider
• startStreamActor
• streamCommandEnvelope
• handleToolInvocation
• handleExecResult
• handleExecControl
• publishCheckpoint
• CheckpointConversation
• snapshotCheckpointConversation
• appendConversationEntries
• OpenExec
• OpenQuery
• StartStream
• deriveConversationLoopState
• historyEntryToolCallID
• recordProviderUsage
• recordTurnUsage

provider / 模型适配层

当现象是 provider 400/500、thinking/reasoning、tool_call_id、OpenAI/Anthropic 请求形状、usage/cache 不对：

优先搜索：

• StartStream
• StreamRequest
• ResolvedChannelID
• ResolvedChannelName
• ProviderModelID
• ThinkingEnabled
• buildAnthropicThinkingConfig
• normalizeAnthropicProviderMessages
• normalizeOpenAIProviderMessages
• normalizeOpenAIResponsesInput
• reasoning_content
• ReasoningContent
• ReasoningSignature
• RecordLLMRequest
• RecordLLMSummary
• http_error
• namespaceToolCallID

快速判断规则

• 如果问题是“给你一个 id，让你先判断是什么 ID，再找日志”，先看 history/<id>/state.json 是否存在，再扫 history/*/state.json、history/*/context.json 和 logs/app.log。
• 如果问题是“模型输出语义不对”，先看 context.json.items 到 ProjectPromptReplay() 的投影，再看 provider request normalization。
• 如果问题是“provider 报 400/参数错误”，先看模型适配层请求构造、state.latest_request_prefix、state.last_provider_call、logs/app.log。
• 如果问题是“客户端没回某个工具结果 / pending 不收口”，先看 cursor-always-local 与 forwarder，同时核对同一 turn_seq 是否有 tool_result 或控制面错误 entry。
• 如果问题是“backend 重启后为什么 checkpoint 没法继续恢复 pending”，不要找磁盘 checkpoint；checkpoint 是 live state，重启后的事实源是 state.json + context.json。
• 如果问题是“为什么同一个 modelID 还能出现多个渠道”，先检查渠道 ID：规范化后 baseURL + modelID + apiKey + displayName + openAIEndpoint 的短 SHA-256；resolver 仍兼容 legacy baseURL + modelID + apiKey + displayName。
• 如果问题是“只想桥接到其他 LLM”，优先看模型桥接层，不要默认深入整套 local runtime。
• 如果问题是“已安装 app 行为和仓库代码不一致”，先核对实际运行 bundle，再做只读比对；不要 patch 客户端。

协议关键词

上行：

• run_request
• exec_client_message
• exec_client_control_message
• interaction_response

下行：

• interaction_update
• exec_server_message
• exec_server_control_message
• interaction_query
• conversation_checkpoint_update

如果只看到下行请求，没有对应上行结果或控制消息，优先排查：

• exec_id
• id
• tool_call_id
• request_id
• model_call_id
• pending 收口逻辑

如果用户给的是一个裸 id，不要直接把它当成 request_id。先同时查：

• history/<id>/state.json
• history/*/state.json 的 current_request_id、latest_request_prefix、last_provider_call
• history/*/context.json 的 items[].request_id、items[].tool_call_id、items[].payload
• history/usage.json 的 event_index / recent_events
• logs/app.log