Cursor Rust 服务端实施与验收计划

项目说明

cursor-byok 是一个兼容 Cursor Agent 客户端协议的自托管服务端项目，用于把 Cursor 客户端接入用户指定的 LLM Provider。项目根据真实客户端流量和提取出的 protobuf 协议实现，不依赖 Cursor 原服务保存对话状态。

当前 Rust 服务 cursor-server 实现以下完整链路：

• 通过 RunSSE + BidiAppend 组成的双向协议与 Cursor 客户端通信。
• 将 OpenAI Chat、OpenAI Responses 和 Anthropic 的流式响应统一为内部 ResponseEvent。
• 运行无状态 LLM Loop：LLM → 客户端工具执行 → 结果追加 → 下一轮 LLM，直到 Turn 完成或被新 Run 打断。
• 以 append-only messages 作为上下文唯一事实源，保证相邻 LLM 请求的稳定前缀和可重复投射。
• 支持文本、thinking、tool start、参数增量、tool result、usage、model、rules、commands、skills、MCP 和 subagent 上下文。
• 使用 SQLite 持久化 messages、Run 状态、Blob CAS、引用边和 outbox。
• 使用不可变 Blob 对象图表达 Conversation、Turn、UserMessage 和 Steps；BlobID 为原始内容的 SHA-256。
• 在客户端确认 Blob 已存储后发布 checkpoint，并提供单工具粒度的历史回滚和未确认操作恢复。

运行时职责划分如下：Cursor 客户端负责真正执行本地工具并保存服务端同步的 Blob；cursor-server 负责 Loop 决策、上下文投射、Provider 调用、状态持久化和 checkpoint 构造。Todo/Plan 等业务状态不单独维护，而是从 messages 确定性推导。

协议与状态模型的抓包结论见 Cursor上下文与状态同步抓包分析.md。Rust 服务的启动方式和运行配置见 cursor-server/README.md。

目录硬约束

下列目录、文件名和职责是实现验收条件，不是建议。首版只允许一个 cursor-server crate；代码必须落在对应文件，不得用 core.rs、service.rs 等总入口替代，也不得提前创建 MCP/subagent 空模块。新增文件必须说明为何现有职责无法容纳；删除、改名或移动下列文件必须先同步修改本计划。

cursor-byok/
├── cursor-server/                 # 新 Rust 服务
│   ├── Cargo.toml
│   ├── build.rs                   # 从 cursor-proto/proto 生成 prost 类型
│   ├── README.md                  # 启动方式、架构和核心不变量
│   │
│   ├── migrations/
│   │   └── 0001_initial.sql       # Blob、messages、runs、outbox
│   │
│   ├── src/
│   │   ├── main.rs                # 进程入口
│   │   ├── lib.rs                 # 模块出口
│   │   ├── app.rs                 # 依赖组装、启动和关闭
│   │   ├── config.rs              # 地址、数据库、provider 配置
│   │   ├── error.rs               # 服务统一错误
│   │   │
│   │   ├── model/                 # 纯领域类型，不依赖 Cursor/provider
│   │   │   ├── mod.rs
│   │   │   ├── message.rs         # CanonicalMessage、Role、Origin
│   │   │   ├── runtime_tag.rs     # RuntimeEvent、exactly-once 约束
│   │   │   ├── conversation.rs    # Conversation、Turn、revision
│   │   │   ├── tool.rs            # ToolCall、ToolResult
│   │   │   └── usage.rs           # provider usage 与 Turn usage
│   │   │
│   │   ├── run/                   # Loop 引擎和一次 request 的状态机
│   │   │   ├── mod.rs
│   │   │   ├── registry.rs        # request_id → RunHandle
│   │   │   ├── actor.rs           # 每个 Run 一个 actor
│   │   │   ├── command.rs         # run_request、exec/KV result、abort
│   │   │   ├── inbox.rs           # append_seqno 排序、去重
│   │   │   ├── loop_engine.rs     # LLM → Tool → LLM 主循环
│   │   │   └── lifecycle.rs       # turn_ended/checkpoint/EndStream
│   │   │
│   │   ├── cursor/                # Cursor 协议适配器
│   │   │   ├── mod.rs
│   │   │   ├── proto.rs           # include prost 生成代码
│   │   │   ├── connect.rs         # 5-byte Connect envelope
│   │   │   ├── handlers.rs        # Axum 路由入口
│   │   │   ├── bidi_append.rs     # 上行 AgentClientMessage
│   │   │   ├── run_sse.rs         # 下行 AgentServerMessage
│   │   │   ├── interaction.rs     # 交互事件、Tool args 和 usage 投射
│   │   │   ├── exec.rs            # Exec 上行/下行解析
│   │   │   ├── pending.rs         # Exec/Interaction 的运行期 ID 关联
│   │   │   ├── tools.rs           # 唯一工具路由、本地工具和 Cursor step index
│   │   │   ├── tool_result.rs     # typed result、UI completion 和结果通道
│   │   │   ├── blob_sync.rs       # KV GET/SET、ACK、重试
│   │   │   └── checkpoint.rs      # Blob 图和 checkpoint 构造
│   │   │
│   │   ├── provider/              # LLM 端点适配器
│   │   │   ├── mod.rs             # Provider trait
│   │   │   ├── event.rs           # Canonical ResponseEvent
│   │   │   ├── openai_chat.rs     # 第一条可运行链路
│   │   │   ├── openai_responses.rs
│   │   │   └── anthropic.rs
│   │   │
│   │   ├── prompting/             # 模型请求编译
│   │   │   ├── mod.rs
│   │   │   ├── assets.rs          # 校验并嵌入根目录 prompt/
│   │   │   ├── compiler.rs        # messages + mode + tools
│   │   │   ├── projector.rs       # CanonicalMessage → provider 格式
│   │   │   └── derived_state.rs   # 从 messages fold Todo/Plan
│   │   │
│   │   └── store/                 # SQLite 持久化
│   │       ├── mod.rs
│   │       ├── sqlite.rs           # pool、事务、PRAGMA
│   │       ├── messages.rs         # append-only messages
│   │       ├── blobs.rs            # CAS 与引用边
│   │       ├── conversations.rs    # conversation head/revision
│   │       ├── runs.rs             # 活动 Run 和恢复信息
│   │       └── outbox.rs           # KV/checkpoint 待确认操作
│   │
│   └── tests/
│       ├── support/
│       │   ├── fake_provider.rs
│       │   ├── fake_cursor.rs
│       │   └── fixtures.rs
│       ├── text_turn.rs            # 纯文本完整 Turn
│       ├── tool_loop.rs            # LLM → Tool → LLM
│       ├── runtime_tag_once.rs      # Runtime tag 不重复追加
│       ├── prefix_stability.rs      # M(n) 是 M(n+1) 前缀
│       ├── checkpoint_recovery.rs   # 单 Tool 回滚
│       ├── interrupt.rs             # 新 Run 打断旧 Run
│       └── connect_wire.rs          # Connect 二进制兼容性
│
├── cursor-proto/                   # 现有 protobuf 提取和源文件
├── cursor-backend/                 # 现有 Go 抓包调试器
├── prompt/                         # 已复制的完整模式资产
└── docs/

按文件实施顺序与通过条件

1. Cargo.toml、build.rs、src/{main,lib,app,config,error}.rs：服务能加载配置、迁移数据库、生成 Cursor protobuf 并启动/优雅关闭。
2. src/model/*.rs、src/store/*.rs、migrations/0001_initial.sql：实现纯领域消息、runtime tag、tool/usage，以及 append-only messages、Blob CAS/引用边、revision、run 恢复与 outbox；tests/runtime_tag_once.rs 和 tests/prefix_stability.rs 必须通过。
3. src/cursor/{proto,connect,handlers,bidi_append,run_sse}.rs：实现抓包一致的 5-byte Connect envelope、二进制 RunSSE、BidiAppend 解码和 append_seqno 排序去重；tests/connect_wire.rs 必须通过。
4. src/provider/{event,openai_chat,openai_responses,anthropic}.rs、src/prompting/*.rs：三个端点统一为 canonical ResponseEvent；所有 mode 的 prompt/tool 资产可加载；messages 投射幂等且保持严格前缀。
5. src/run/*.rs、src/cursor/{tools,interaction,exec,pending,tool_result}.rs：一个 request 一个 RunActor；Loop 只处理统一 ToolCompletion，工具名称到 Exec/Interaction/Local 的唯一映射只存在于 cursor/tools.rs；完成 toolstart 占位、参数增量、客户端执行、打断与 usage。每个完成的工具必须原子追加 assistant(tool_call) → tool(result)，整批完成前不得进入下一次 LLM。
6. src/cursor/{blob_sync,checkpoint}.rs、src/store/{blobs,outbox}.rs：构造不可变 Blob 对象图，KV SET 未 ACK 前不得发布引用它的 checkpoint；checkpoint 达到单工具粒度，最终状态重复发布后再 EndStream；tests/checkpoint_recovery.rs 必须通过。
7. tests/{text_turn,tool_loop,interrupt}.rs 与 tests/support/*.rs：覆盖纯文本 Turn、完整工具循环、新 Run 打断旧 Run和恢复路径。最终验收命令固定为 cargo fmt --check、cargo clippy --all-targets -- -D warnings、cargo test --all-targets。

模块依赖方向固定为：

HTTP/Connect ↓ cursor adapter ↓ run actor ↓ model + prompting ↓ provider / client tools ↓ store + checkpoint

几个关键决定： model/ 不引用 Cursor protobuf，也不引用具体 provider。 cursor/ 只负责协议转换，不能包含 Loop 业务决策。 provider/ 只把不同端点转换为统一 ResponseEvent。 prompting/derived_state.rs 只 fold messages，不持久化 Todo/Plan。 store/messages.rs 是上下文唯一事实源。 store/outbox.rs 保存尚未确认的 Blob/checkpoint 操作。 MCP 和 subagent 暂时不建空目录：MCP 先作为动态 Tool 接入；subagent 复用 RunActor，需求落地时再加入 run/subagent.rs。

依赖建议：

tokio                异步运行时
axum + hyper         Connect HTTP 服务
prost + prost-build  protobuf
protoc-bin-vendored  避免系统 protoc 依赖
sqlx/sqlite          持久化和事务
reqwest              provider HTTP
eventsource-stream   provider SSE
serde/serde_json     模型和工具 JSON
sha2 + base64        BlobID
bytes                二进制载荷
tokio-util           CancellationToken
thiserror + tracing  错误和日志
include_dir          编译期嵌入 prompt/ 资产

Cursor上下文与状态同步抓包分析.md 来告诉你很多信息，你需要一次性读他

Users/leokun/Library/Application Support/cursor-byok/cursor-proxy-debugger.db 是cursor的原服务抓包信息，内容由/Users/leokun/Documents/cursor-byok/cursor-backend产生