cursor-byok/.agents/skills/cursor-client-e2e-debugging/SKILL.md

name, description

name

description

cursor-client-e2e-debugging

Use when debugging Cursor client agent/local-mode/tool/backend-store/provider-replay failures in this repo, especially after the state/context history-store refactor, when triaging installed app bundles read-only, correlating installed-client behavior with repo code, mapping a user-provided id to conversation/request/model-call evidence, replaying provider requests from debug logs, or locating the current client/backend/protocol/log files quickly.

当用户反馈 Cursor agent、本地模式、工具调用、协议桥接、客户端 bundle 行为异常，或需要只读核对已安装客户端与仓库实现/日志差异时，使用此技能。

当用户只给一个 UUID / id，希望反查它是 conversationId、requestId、modelCallId、toolCallId 还是其它运行期 id，并继续定位对应的会话 history、provider 调用状态或协议日志时，也使用此技能。

当用户遇到 provider 400/参数错误、SSE event: error、需要从 debug/provider.jsonl 抽取最终 provider body 并用 curl 独立复现时，也使用此技能。

首要约束

• 不要修改已安装的 Cursor 客户端代码、bundle、签名或 app 副本。
• 允许且推荐读取、搜索、比对和分析客户端 bundle、日志、协议事件与本仓库实现。
• 如果本仓库存在 .cursor-app-formatted/，优先读取这个格式化快照来搜索和引用客户端 bundle；只有在快照缺失、过期或需要 hash/真实性核对时，才只读读取 /Applications/Cursor.app。
• 如果用户要求提取、格式化、刷新或规范化 Cursor.app 快照流程，使用 cursor-app-formatted skill；调查时可以读格式化代码，但不要 patch 格式化快照里的 bundle 代码。
• 如果用户要求 patch 客户端做 e2e，要改成只读证据采集与差异定位，不执行客户端修改。
• 当前本仓库已经重构为 state.json + context.json history-store；不要沿用旧 data.sqlite、conversation.json、turns/<n>/request.json|sse.jsonl|summary.json 排查路径。

先做路由判断

• history + logs 反查层
  • 现象：用户发来一个 id，要判断它是 conversationId、requestId、modelCallId、toolCallId；需要从 history/<conversationId>/state.json 与 history/<conversationId>/context.json 追运行状态和语义历史。
  • 先读 references/backend-store-log-tracing.md
• provider replay / debug 层
  • 现象：provider 返回 400/参数错误、SSE event: error、需要验证最终出站 provider body 是否能被独立 curl 复现。
  • 先读 references/provider-replay-debugging.md，必要时使用 scripts/provider-replay.sh
• cursor-agent 层
  • 现象：CursorAgentProvider、ClaudeSDKClient、AnthropicProxy、registerAgentProvider、InteractionUpdate 映射、模型桥接异常。
  • 先读 references/file-map.md 和 references/search-patterns.md
• cursor-always-local / 本地模式协议层
  • 现象：BidiAppend、RunSSE、AgentServerMessage、ExecClientMessage、InteractionResponse、live checkpoint / pending 收口异常。
  • 先读 references/file-map.md 和 references/search-patterns.md
• 客户端 bundle 只读定位层
  • 现象：需要核对已安装 app bundle、确认实际运行副本、只读验证行为是否命中，并判断差异来自客户端还是本仓库。
  • 先读 references/installed-client-readonly-validation.md

如果问题同时涉及多层，优先从最靠近故障表象的一层开始，不要一开始就同时追所有链路。

当前工作流

1. 如果用户给了一个 id，先用 history/ 目录、context.json.items、state.json 和 logs/app.log 判断它属于哪类 id；不要假设它一定是 requestId。
2. 一旦拿到 conversationId，同时看两份事实源：
   • history/<conversationId>/state.json：会话元数据和当前状态，例如 loop、token、current todo/plan、latest_request_prefix、last_provider_call。
   • history/<conversationId>/context.json：append-only 的语义历史 entries；prompt replay 由 ProjectPromptReplay() 从这里投影。
3. 不要去找旧 provider 调用工件：当前 RecordLLMRequest 不再落 request.json，AppendLLMResponseChunk 是 no-op，RecordLLMSummary 只补齐内存态并更新 state.latest_request_prefix / usage。
4. 再确认故障主要落在 cursor-agent、cursor-always-local，还是本仓库 internal/backend 的协议兼容层。
5. 用 references 里的固定搜索词快速找到入口函数、协议消息和桥接点。
6. 如果 provider 返回 400/参数错误、SSE event: error，或需要验证最终出站 provider body：
   • 先读 references/provider-replay-debugging.md。
   • 通过 id 反查拿到 conversationId、requestId、modelCallId，再定位 history/<conversationId>/debug/provider.jsonl。
   • 必要时运行 scripts/provider-replay.sh，只保存 replay 产物，不把 API key 或完整 request body 写进技能/回复。
7. 如果用户要核对 prefix cache / cache hit：
   • 优先运行 go run ./scripts/historymetrics [conversationId|path]
   • 它读取当前 history/<conversationId>/state.json 与 history/<conversationId>/context.json，并结合 history/usage.json 统计。
   • 关注 cache_read_tokens / prompt_tokens_total，并检查 context.json.items 是否缺失、重复或顺序异常。
8. 如果需要对照已安装 app 与仓库行为：
   • 只做只读核对与证据采集，不修改客户端 bundle / app 副本 / 签名。
   • 优先用 .cursor-app-formatted/ 中的格式化副本定位符号、行号和控制流；再按需只读核对 /Applications/Cursor.app 原始文件 hash 或运行副本。
   • 先确认实际运行的 app 副本和目标 bundle 路径。
   • 再读取 bundle 内容、日志、端口与 history 状态，并与本仓库实现对照。
9. 如果证据显示问题更像是客户端 bundle 行为差异：
   • 记录具体文件、符号、日志和协议证据链。
   • 继续判断本仓库是否可以兼容、绕过，或直接输出分析结论。
   • 不要对已安装 Cursor 客户端做 patch、重签名、替换文件或写入式验证。

约束

• 不要修改已安装的 Cursor 客户端代码、bundle、签名或 app 副本。
• 不要默认复刻整套 Cursor backend；先确认是不是只需要改模型桥接层。
• 不要先假设用户给的是 requestId；必须同时考虑 conversationId、requestId、modelCallId、toolCallId。
• 不要把 history/<conversationId>/state.json 和 history/<conversationId>/context.json 混为一谈：前者是元数据与当前状态，后者是 replayable 语义历史。
• 不要再依赖 agent_request_runs、agent_conversations、agent_history_entries、protocol_traces、data.sqlite；当前实现已经不支持 DB-backed store / trace debug UI。
• 不要把当前排查进度、临时结论、一次性的 request_id / 端口 / token 写进技能。
• 技能里只保留稳定流程、固定入口、可复用搜索词和只读验证规则。

模型渠道规则

• 模型渠道唯一性不再由 modelID 决定。
• 当前规范化渠道 ID 是 baseURL + modelID + apiKey + displayName + openAIEndpoint 的短 SHA-256 hash（前 16 个十六进制字符）。
• resolver 仍兼容 legacy 渠道 ID：baseURL + modelID + apiKey + displayName。
• modelID 只表示 provider model；排查选择器、默认模型和命中渠道时，要优先看渠道 ID 和 openAIEndpoint。

参考加载规则

• history + logs 路径、id 反查、state/context 生成链路：读 references/backend-store-log-tracing.md
• provider 400/参数错误、SSE event: error、最终出站 provider body curl 重放：读 references/provider-replay-debugging.md
• 文件地图：读 references/file-map.md
• 搜索词与判断树：读 references/search-patterns.md
• 已安装客户端的只读核对、进程确认、行为验证：读 references/installed-client-readonly-validation.md

自带脚本

• 统计 prefix cache / cache hit：运行 go run ./scripts/historymetrics [conversationId|path]
• 兼容壳脚本：运行 scripts/cache-hit-rate.mjs
• provider curl 重放：运行 scripts/provider-replay.sh，必填 REQUEST_LOG、REQUEST_ID、MODEL_CALL_ID