cursor-byok/README.md

# 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](./Cursor上下文与状态同步抓包分析.md)。Rust 服务的启动方式和运行配置见 [cursor-server/README.md](./cursor-server/README.md)。

## 目录硬约束

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

```text
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产生