coding-guidance

name	coding-guidance
description	本地模式实现指南

当用户在处理本地模式的时候，使用此指南

先遵守这个约束：

• 不要修改已安装的 Cursor 客户端代码、bundle 或 app 副本。
• 允许且推荐读取、搜索、比对和分析客户端 bundle、日志、协议与仓库代码。
• 如果用户提到“临时 patch 客户端做 e2e”，也要改成只读排查：核对实际运行副本、采集证据、对照仓库实现，然后把修复落在本仓库代码或输出明确结论。

如果问题已经涉及以下任一事项，请同时读取 ../cursor-client-e2e-debugging/SKILL.md：

• 需要只读核对已安装的 Cursor 客户端 bundle、日志或运行副本
• 需要确认当前到底是哪一个 app 副本在运行
• 需要同时排查客户端 bundle 与本仓库 forwarder 的协同问题
• 需要对照已安装客户端行为与本仓库实现差异

本地模式协议需要优先核对这些文件：

• proto/agent_v1.proto
• proto/aiserver_v1.proto 客户端是：/Users/leokun/Library/Application\ Support/Cursor 客户端 bundle 是：/Applications/Cursor.app/Contents/Resources/app/extensions/cursor-always-local/dist/main.js

可选抓包调试工具

仓库提供了独立的 Cursor 协议抓包调试器。开发者在手动排查协议问题时，可以运行：

go run ./cmd/cursor-proxy-debugger

默认代理地址是 http://127.0.0.1:9090，调试界面是 http://127.0.0.1:9091。该工具可以辅助查看：

• agent.v1.AgentService/RunSSE
• aiserver.v1.BidiService/BidiAppend
• Connect 帧、gzip 压缩内容、Protobuf 解码结果和原始二进制数据
• 同一 request_id 对应的上下行消息

开发者启动工具后，需要自行完成以下配置：

1. 在 Cursor 的代理设置中，将代理修改为工具启动时显示的代理地址，默认是 http://127.0.0.1:9090。
2. 在 Cursor 的 Network 设置中开启 HTTP/1.1。
3. 从 http://127.0.0.1:9091/api/ca.crt 下载代理 CA 证书，并确保 Cursor 信任该证书。

这只是供开发者手动使用的辅助工具，不属于自动化 Debug 流程。不要因为加载此指南就自动启动代理、修改 Cursor 或系统设置、安装证书，或操作 Cursor 发起请求。只有开发者明确表示已经启用抓包时，才把调试界面中的数据作为当前运行证据。调试结束后，提醒开发者恢复原来的 Cursor 代理和 Network 设置。

Cursor 客户端格式化快照

• 如果用户要求提取、格式化、刷新或规范化 Cursor.app 快照流程，使用 cursor-app-formatted skill。
• 如果本仓库存在 .cursor-app-formatted/，排查客户端 bundle 时优先读取这里的格式化副本。
• .cursor-app-formatted/ 是从 /Applications/Cursor.app/Contents/Resources/app 只读提取后格式化生成的本地快照；它不应写回、替换或影响已安装的 Cursor.app。
• 常用格式化路径：
  • .cursor-app-formatted/extensions/cursor-always-local/dist/main.js
  • .cursor-app-formatted/extensions/cursor-agent-exec/dist/main.js
  • .cursor-app-formatted/extensions/cursor-agent-worker/dist/main.js
  • .cursor-app-formatted/out/vs/workbench/workbench.desktop.main.js
  • .cursor-app-formatted/out/vs/workbench/api/node/extensionHostProcess.js
• 如果 .cursor-app-formatted/ 不存在、明显过期，或需要核对真实安装包 hash，再只读读取 /Applications/Cursor.app 原始 bundle。

本仓库已固定的会话承接规则

• 下一轮真实请求给 LLM 的历史承接，以 history/<conversationId>/state.json + history/<conversationId>/context.json 为持久化事实源。
• state.json 保存会话元数据和当前状态，例如 next_turn_seq、next_entry_seq、context_version、current_todos、current_plans、latest_request_prefix、last_provider_call。
• context.json.items 保存 append-only 的语义历史 entries；provider messages 不是主存储事实，而是由 ProjectPromptReplay() 从 entries 投影出来。
• 模型渠道唯一性不再由 modelID 决定；当前规范化渠道 ID 是 baseURL + modelID + apiKey + displayName + openAIEndpoint 的短 SHA-256 hash，resolver 仍兼容 legacy baseURL + modelID + apiKey + displayName。
• 可 replay 的历史应以 entry 顺序稳定追加，不能把已发送给模型且仍需保留的历史移动到新位置。
• 最新态、易变态，例如 active todo、current plan、最新编辑保护和动态 reminder，应优先作为 state.json 状态或本轮 latest-only suffix；不要无意持久化成会在后续轮次无限 replay 的历史。
• 新一轮 run_request 到来时，服务端应通过 LoadConversation() 读取 state.json + context.json，再由 projector 投影 prompt replay；客户端带回来的 checkpoint/replay 不参与历史承接真相判定。
• summary.json、replay.json、runtime.json、request.json、conversation.json、entries.jsonl、turns/ 和数字 turn 目录都属于旧持久化产物，会被 history maintenance 当 legacy artifact 清理。
• 如果发现请求历史与本地状态不一致，优先检查 context.json.items 是否缺失、重复、顺序异常，以及 state.json 的 next_entry_seq、next_turn_seq、context_version、当前状态字段是否与 entries 派生结果一致；不要再按旧 summary.json 路径排查。

已确认结论

1. AgentServerMessage 不是统一都要“回复完成”

要按 oneof message 分类看：

• exec_server_message
  • 这是服务端发给客户端的“执行请求”。
  • 客户端需要显式回 ExecClientMessage。
  • 流式/异常场景下还会回 ExecClientControlMessage，常见是：
    • stream_close
    • throw
    • heartbeat
• interaction_query
  • 这是服务端发给客户端的“交互请求”。
  • 客户端需要显式回 InteractionResponse。
• interaction_update
  • 这是展示/状态更新消息，通常不需要客户端回包。
• conversation_checkpoint_update
  • 这是 checkpoint 同步消息，通常不需要客户端回包。
• kv_server_message
  • 这是 KV 同步消息，通常不需要客户端回包。
• exec_server_control_message
  • 这是服务端对执行桥的控制消息（例如 abort），客户端要按控制语义处理，但不是通用“完成 ack”。

2. Cursor 客户端没有“收到任意 ServerMessage 自动回 ack”的通用层

在 cursor-always-local/dist/main.js 里，BidiTransport.startYieldingInputsToTheServer 只会把“客户端主动产出的消息”送到 BidiAppend：

• 它对输入 iterable 做 p.value.toBinary() 后 hex 编码，再发 BidiAppendRequest.data
• 说明只有客户端业务逻辑主动产出的 AgentClientMessage 才会上行
• 没有发现“收到一个 AgentServerMessage 就自动回 completed/ack”的统一机制

因此客户端是否回包，取决于上层业务逻辑有没有因为某个下行消息而主动构造新的 AgentClientMessage。

2.1 更具体的客户端侧结论

从 cursor-always-local/dist/main.js 里能直接确认：

• AgentServerMessage 的下行类型里有：
  • interaction_update
  • exec_server_message
  • exec_server_control_message
  • conversation_checkpoint_update
  • interaction_query
• AgentClientMessage 的上行类型里有：
  • run_request
  • exec_client_message
  • exec_client_control_message
  • interaction_response

这意味着本地模式不是“server message -> 通用 ack”模型，而是：

• exec_server_message -> 客户端执行本地工具 -> 产出 exec_client_message -> 以及可选 exec_client_control_message
• interaction_query -> 客户端展示或处理交互 -> 产出 interaction_response
• 其他下行消息 -> 一般只更新 UI / checkpoint /流状态 -> 不会自然地产生一个“完成 ack”

2.2 exec_server_message 常见的客户端回包形态

客户端协议模型里已确认这些回包类型：

• ExecClientMessage
  • 正常结果面
  • 包括 read_result / write_result / grep_result / ls_result / diagnostics_result / mcp_result / shell_stream 等
• ExecClientControlMessage
  • 控制面
  • 包括：
    • stream_close
    • throw
    • heartbeat

所以调查本地模式 exec 问题时，不要只盯 ExecClientMessage：

• 有些工具只回一次结果面消息
• shell 之类的流式工具会混合回：
  • 多次 shell_stream
  • 以及控制消息（例如 stream_close / heartbeat）

2.3 exec_server_message 的完整回包形态

事实依据：

• proto/agent_v1.proto
  • ExecServerMessage.oneof message
  • ExecClientMessage.oneof message
  • ExecClientControlMessage.oneof message
• cursor-always-local/dist/main.js
  • bundle 内含同名 proto 模型
  • BidiTransport.startYieldingInputsToTheServer 说明客户端上行消息来自业务逻辑主动构造，不存在通用自动 ack

结果面回包：ExecServerMessage -> ExecClientMessage

ExecServerMessage 的 message 分支与 ExecClientMessage 的 message 分支是一一对应的：

• shell_args -> shell_result
• write_args -> write_result
• delete_args -> delete_result
• grep_args -> grep_result
• read_args -> read_result
• ls_args -> ls_result
• diagnostics_args -> diagnostics_result
• request_context_args -> request_context_result
• mcp_args -> mcp_result
• shell_stream_args -> shell_stream
• background_shell_spawn_args -> background_shell_spawn_result
• list_mcp_resources_exec_args -> list_mcp_resources_exec_result
• read_mcp_resource_exec_args -> read_mcp_resource_exec_result
• fetch_args -> fetch_result
• record_screen_args -> record_screen_result
• computer_use_args -> computer_use_result
• write_shell_stdin_args -> write_shell_stdin_result
• execute_hook_args -> execute_hook_result
• subagent_args -> subagent_result

所有这些结果面回包都带：

• id
• exec_id

服务端匹配时通常优先用：

1. exec_id
2. id

控制面回包：ExecServerMessage -> ExecClientControlMessage

除了结果面回包外，客户端还可能回控制面消息：

• stream_close
  • 表示当前 exec 流已关闭
  • 只有 id
• throw
  • 表示执行异常
  • 只有 id + error + 可选 stack_trace
• heartbeat
  • 表示执行过程中的心跳
  • 只有 id

关键理解

• ExecClientControlMessage 不是某个单独 ExecServerMessage 分支的“专属结果类型”
• 它是跨 exec 通用的控制面回包
• 因此调查时必须同时看两类上行：
  • ExecClientMessage
  • ExecClientControlMessage

调查规则

对于任意 exec_server_message，至少要确认以下之一是否发生：

• 收到对应的 ExecClientMessage
• 或收到 ExecClientControlMessage.throw
• 对流式 exec，还要看：
  • 是否有多次增量 ExecClientMessage
  • 是否最终有 stream_close

如果只看到 started / pending，没有任何结果面或控制面回包，服务端 pending 大概率不会收口。

排查时优先搜索这些关键字：

3. forwarder 状态机实现规则

在本仓库修本地模式 forwarder 时，默认遵守下面这些稳定约束，避免再次引入“工具晚到污染当前轮”或“同一 request 在 [DONE] 后又续跑一轮”的问题。

3.1 resume 必须按 provider pass 隔离

• request_id 不是 provider 调用代次；同一个 request 可以合法包含多次 provider pass。
• scheduleProviderResume 不能只依赖 request 级布尔态（例如单个 ResumePending）。
• resume 请求必须带来源 pass，至少要能区分：
  • 当前 pass 的结果触发的合法续跑
  • 上一轮工具终态晚到造成的陈旧 resume
• driveProvider 开始与结束时都要显式清理上一轮的 resume 状态，不能让旧状态跨 pass 残留。

3.2 工具晚到是常态，只能影响所属 pass

• ExecClientMessage / ExecClientControlMessage 晚于 provider [DONE] 到达是正常现象。
• 晚到结果只能驱动其所属 pass 的 checkpoint / history / resume 判定，不能影响后续 pass。
• 非流式 exec 的 stream_close synthetic recovery 也必须沿用原工具的来源 pass，不能按 request 级全局状态续跑。

3.3 pending exec 必须严格按 id 匹配

• selectPendingExec / selectPendingExecByControl 只允许按：
  • exec_id
  • message_id 进行匹配。
• 不允许再用“当前只有一个 pending，就直接返回它”的兜底逻辑。
• 迟到的 result / stream_close / throw 如果 pending 已不存在：
  • 优先看 RecentCompletedExecs 做幂等忽略
  • 不要把它重新落到当前轮的 pending 上

3.4 看到这些现象时，优先怀疑 stale resume / stale exec

如果出现下面任一现象，先查 forwarder 状态机，不要先怪客户端：

• 同一个 request_id 在 [DONE] 后又出现新的 model_call_id
• turns/<n+1>/request.json 与 turns/<n>/request.json messages 几乎完全相同
• 上一轮工具 grepResult/readResult/... 晚于上一轮 [DONE]
• 晚到的 stream_close 恰好跨到下一轮 provider 已经启动之后

优先核对：

• ProviderPassCount

• resume 请求的来源 pass

• PendingExec.ProviderPass

• selectPendingExec 是否存在跨轮误匹配

• startYieldingInputsToTheServer

• bidiAppend({requestId:A,appendSeqno

• ExecServerMessage

• ExecClientMessage

• ExecClientControlMessage

• InteractionQuery

• InteractionResponse

3. 对本地模式最重要的协议理解

• exec_server_message / interaction_query 属于“请求型下行消息”
  • 如果客户端不回对应结果，服务端 pending 不会收口
  • 后续重连后可能出现 “No tool output found for function call ...” 这类 provider 400
• interaction_update / conversation_checkpoint_update 属于“通知型下行消息”
  • 它们用于 UI 展示、同一 backend 进程内的 live checkpoint 同步、状态同步
  • 一般不要求客户端再回一个“完成”消息

4. 调查本地模式时的优先顺序

1. 先确认收到的 AgentServerMessage 是哪一类
2. 如果是 exec_server_message
   • 查客户端是否回了 ExecClientMessage
   • 查是否只回了 stream_close 但没有真正结果
   • 查 exec_id / id 是否匹配
3. 如果是 interaction_query
   • 查客户端是否回了 InteractionResponse
4. 如果是 conversation_checkpoint_update
   • 重点查里面的 pending_tool_calls / root_prompt_messages_json / turns
   • 不要误以为它本身需要回 ack

5. 对服务端实现的直接要求

• 服务端必须区分“请求型下行”和“通知型下行”
• 服务端不能把 ServerMessage 统一建模成“发出去就等一个完成 ack”
• 对请求型消息，必须在本地状态机里维护 pending：
  • PendingExec
  • PendingInteraction
• 同一 backend 进程内的 RunSSE 重连，要优先看 checkpoint / pending_tool_calls 里的 live pending
• backend 重启后，不要把 checkpoint 当持久恢复点；跨轮承接与持久恢复只看 history/<conversationId>/state.json + history/<conversationId>/context.json

5.1 checkpoint 投影必须幂等且只有一个事实源

• 把 checkpoint 当作 state.json + context.json 的纯投影，不要把它写成第二套语义历史。
• 不要创建或维护 checkpoint.json、checkpoint history、独立 checkpoint entry 序列等持久化事实源。
• 允许在当前 stream 内存中保留 latest checkpoint 供 retry/resume 使用；进程重启后必须能从唯一事实源重新投影。
• 对同一份 semantic history 重复投影时，要求 state、turn 顺序、blob ID 和 blob 内容在语义上完全一致；投影函数不得修改输入 history。
• 把重复发送视为同一快照的幂等覆盖，不要追加一条新的会话历史；内容寻址 blob 的重复写入必须可安全忽略。
• 将 turns 投影为 UI 可恢复的完整结构，保留所有需要展示的 ThinkingMessage、ToolCall 和工具结果；不要为了模型 prompt 过滤而删除 UI step。
• 将 root_prompt_messages_json 单独投影为模型 replay；只在这条投影上应用 provider/context 过滤，不能反向改变 turns。
• 将工具完成结果合并回同一 ToolCall，保留开始态的 args、调用 ID 和开始时间，再补齐 result 与完成时间；不要制造协议不存在的独立 ToolResult step。
• 用 TDD 覆盖至少这些性质：重复投影相等、投影不修改 history、开始态字段在结果合并后仍存在、UI turns 保留思考/工具内容而模型 replay 仍遵守独立过滤规则。