cursor-byok/cursor-server

cursor-server

Cursor Agent 的 Rust 服务端。它实现 RunSSE + BidiAppend 通信、无状态 LLM loop、客户端工具执行、Blob/KV 同步和可恢复 checkpoint。

启动

首次运行需要安装 Rust stable 工具链。macOS 使用 Homebrew：

brew install rustup
export PATH="$(brew --prefix rustup)/bin:$PATH"
rustup default stable
cargo --version

rustup 是 keg-only；若要让后续 zsh 会话也能找到 cargo，将下面一行加入 ~/.zshrc，然后重新打开终端：

export PATH="$(brew --prefix rustup)/bin:$HOME/.cargo/bin:$PATH"

进入 cursor-server 后启动：

CURSOR_DATABASE_URL=sqlite://cursor-server.db \
CURSOR_PROVIDER=openai-chat \
CURSOR_PROVIDER_BASE_URL=http://127.0.0.1:8317/v1 \
CURSOR_PROVIDER_API_KEY=123456 \
CURSOR_MODEL=deepseek-v4-flash \
cargo run

默认监听 127.0.0.1:3000。完整环境变量见 src/config.rs。

不变量

• store/messages.rs 是上下文唯一事实源；消息只追加，不原地修改。
• Runtime tag 使用稳定事件 ID，事务内 exactly-once 追加。
• 每轮投射结果可复现，后一轮 messages 严格以前一轮为前缀。
• 工具每完成一个，就按实际完成顺序原子追加一组 assistant(tool_call) → tool(result)；投射给 LLM 的上下文没有悬空 tool call，整批完整后才继续调用 LLM。
• Blob 是 SHA-256(data) 的不可变 CAS；Blob 类型来自引用字段，不编码在 BlobID 中。
• 引用 Blob 的 checkpoint 只有在全部新 Blob 得到 KV SET ACK 后才能发布。
• checkpoint 以单个工具为恢复粒度；最终 checkpoint 在 EndStream 前可重复发送。
• 新 Run 通过 conversation revision 使旧 Run 的迟到事件失效。
• 每种工具只对应一个 Exec、Interaction 或 Local 通道；不存在级联 fallback。
• Loop 不保存工具名称路由；cursor/tools.rs 是唯一 transport dispatcher。
• Interaction approval 不是 ToolResult；只有 typed terminal result 才能进入持久化与 checkpoint。
• Pending 项存在即 Running，终态通过 take(id) 一次消费；不维护重复的 finished/closed 标志。
• prompt 资产编译进二进制并在启动时整体校验，不与运行时目录逐文件混用。

模块边界和目录是实现约束，必须与仓库根目录 README 保持一致。