From e874d68b79b49ec44ff7c883fbe5db6b7632a67e Mon Sep 17 00:00:00 2001 From: leokun Date: Fri, 28 Aug 2026 16:12:06 +0800 Subject: [PATCH] docs: update README and documentation to clarify model configuration and restart requirements - Enhanced instructions for restarting Cursor after upgrades or initial model configuration to ensure proper functionality. - Updated references from "Troubleshooting" to "Frequently Asked Questions" for better alignment with user needs. - Improved clarity in the installation and usage steps across multiple language versions. --- README-CN.md | 6 +- README.md | 5 +- apps/docs/app/[lang]/(home)/blog/page.tsx | 48 +++---- apps/docs/app/[lang]/(home)/page.tsx | 78 ++++++------ apps/docs/app/[lang]/layout.tsx | 4 +- apps/docs/content/blog/.gitkeep | 0 .../blog/2026-08-28-why-we-rebuilt.en.mdx | 117 ------------------ .../blog/2026-08-28-why-we-rebuilt.mdx | 117 ------------------ apps/docs/content/docs/faq.en.mdx | 90 ++++++++++++++ apps/docs/content/docs/faq.mdx | 90 ++++++++++++++ apps/docs/content/docs/index.en.mdx | 14 ++- apps/docs/content/docs/index.mdx | 14 ++- apps/docs/content/docs/installation.en.mdx | 20 ++- apps/docs/content/docs/installation.mdx | 20 ++- apps/docs/content/docs/meta.en.json | 2 +- apps/docs/content/docs/meta.json | 2 +- apps/docs/content/docs/troubleshooting.en.mdx | 83 ------------- apps/docs/content/docs/troubleshooting.mdx | 83 ------------- apps/docs/lib/layout.shared.tsx | 13 +- 19 files changed, 323 insertions(+), 483 deletions(-) create mode 100644 apps/docs/content/blog/.gitkeep delete mode 100644 apps/docs/content/blog/2026-08-28-why-we-rebuilt.en.mdx delete mode 100644 apps/docs/content/blog/2026-08-28-why-we-rebuilt.mdx create mode 100644 apps/docs/content/docs/faq.en.mdx create mode 100644 apps/docs/content/docs/faq.mdx delete mode 100644 apps/docs/content/docs/troubleshooting.en.mdx delete mode 100644 apps/docs/content/docs/troubleshooting.mdx diff --git a/README-CN.md b/README-CN.md index f842b2d..02c5a52 100644 --- a/README-CN.md +++ b/README-CN.md @@ -43,12 +43,12 @@ cursor-byok 是一个开源的本地模型网关。它在你的设备上运行 2. 启动 cursor-byok，打开 **Cursor 配置**，按提示初始化本地 CA（证书颁发机构）。 3. 在模型设置中添加模型，填写服务地址、API Key 和模型名称，然后保存并运行 **测试**。 4. 确认测试通过后，保持 cursor-byok 运行。 -5. 打开或重启 Cursor，在模型列表中选择已配置的模型，开始使用 Agent。 +5. **首次升级 Cursor 或首次配置模型后，完全退出并重新启动 Cursor，然后新开一个对话**。在模型列表中选择已配置的模型，开始使用 Agent。 -完整的安装步骤、配置说明和故障处理，请参阅[中文使用指南](https://docs.leokun.cn/zh/docs)。 +完整的安装步骤、配置说明和常见问题，请参阅[中文使用指南](https://docs.leokun.cn/zh/docs)。 > [!TIP] -> 首次完成配置后，建议完全退出并重新启动 Cursor，再新开一个对话。使用自定义模型时，请在模型列表中手动选择该模型，不要选择 **Auto**。 +> 首次升级 Cursor 或首次完成配置后，必须完全退出并重新启动 Cursor，再新开一个对话。配置前已经打开的对话不会加载新连接；使用自定义模型时，请在模型列表中手动选择该模型，不要选择 **Auto**。 ## 模型配置 diff --git a/README.md b/README.md index b860ac2..dcfb74f 100644 --- a/README.md +++ b/README.md @@ -45,9 +45,10 @@ You can connect OpenAI- and Anthropic-compatible services, customize endpoints, 1. Download the latest build for your platform from [GitHub Releases](https://github.com/leookun/cursor-byok/releases/latest). 2. Launch cursor-byok, open **Model Settings**, and enter the endpoint, API key, and model ID. 3. Test the model configuration. Once it passes, return to the dashboard and start the service. -4. Open Cursor, select the configured model, and start using Agent. +4. Test the model configuration. Once it passes, return to the dashboard and start the service. +5. After upgrading Cursor or configuring a model for the first time, quit Cursor completely and restart it, then start a new conversation and select the configured model. -For complete installation steps, system configuration, and troubleshooting, see the [User Guide](https://docs.leokun.cn). +For complete installation steps, system configuration, and Frequently Asked Questions, see the [User Guide](https://docs.leokun.cn). ## Model Management diff --git a/apps/docs/app/[lang]/(home)/blog/page.tsx b/apps/docs/app/[lang]/(home)/blog/page.tsx index 1956c09..760fdcd 100644 --- a/apps/docs/app/[lang]/(home)/blog/page.tsx +++ b/apps/docs/app/[lang]/(home)/blog/page.tsx @@ -5,16 +5,18 @@ import { ArrowRight } from 'lucide-react'; import { blogSource, formatBlogDate, sortBlogPages } from '@/lib/blog'; import { isLanguage, type Language } from '@/lib/i18n'; -const copy: Record = { +const copy: Record = { zh: { title: '开发者博客', description: 'Cursor Byok 的架构决策、协议实现与开发进展。', intro: '记录 Cursor Byok 的架构决策、协议实现和开发进展。', + empty: '文章正在准备中。', }, en: { title: 'Developer Blog', description: 'Architecture decisions, protocol work, and development progress of Cursor Byok.', intro: 'Notes on architecture decisions, protocol work, and development progress of Cursor Byok.', + empty: 'Articles are being prepared.', }, }; @@ -43,26 +45,30 @@ export default async function BlogPage(props: PageProps<'/[lang]/blog'>) {

{t.intro}

-
- {posts.map((post) => ( - - -
-

{post.data.title}

-

- {post.data.description} -

-
- - - ))} -
+ {posts.length > 0 ? ( +
+ {posts.map((post) => ( + + +
+

{post.data.title}

+

+ {post.data.description} +

+
+ + + ))} +
+ ) : ( +

{t.empty}

+ )} ); } diff --git a/apps/docs/app/[lang]/(home)/page.tsx b/apps/docs/app/[lang]/(home)/page.tsx index 729038d..ddc673d 100644 --- a/apps/docs/app/[lang]/(home)/page.tsx +++ b/apps/docs/app/[lang]/(home)/page.tsx @@ -57,9 +57,9 @@ const copy: Record< }, { icon: Wrench, - title: '故障排查', - description: '解决证书、连接和模型测试问题。', - href: '/docs/troubleshooting', + title: '常见问题', + description: '回答常见问题。', + href: '/docs/faq', }, ], blogEyebrow: 'DEVELOPER BLOG', @@ -91,9 +91,9 @@ const copy: Record< }, { icon: Wrench, - title: 'Troubleshooting', - description: 'Resolve certificate, connection, and model test issues.', - href: '/docs/troubleshooting', + title: 'Frequently Asked Questions', + description: 'Answer common questions.', + href: '/docs/faq', }, ], blogEyebrow: 'DEVELOPER BLOG', @@ -206,39 +206,43 @@ export default async function HomePage(props: PageProps<'/[lang]'>) { -
-
-
-
-

{t.blogEyebrow}

-

{t.blogTitle}

-
- - {t.viewAll} - - -
- -
- {posts.map((post) => ( - - -
-

{post.data.title}

-

{post.data.description}

-
- + {posts.length > 0 ? ( +
+
+
+
+

{t.blogEyebrow}

+

{t.blogTitle}

+
+ + {t.viewAll} + - ))} +
+ +
+ {posts.map((post) => ( + + +
+

{post.data.title}

+

+ {post.data.description} +

+
+ + + ))} +
-
-
+ + ) : null} ); } diff --git a/apps/docs/app/[lang]/layout.tsx b/apps/docs/app/[lang]/layout.tsx index ec9c0af..5174b29 100644 --- a/apps/docs/app/[lang]/layout.tsx +++ b/apps/docs/app/[lang]/layout.tsx @@ -18,7 +18,7 @@ export async function generateMetadata(props: LayoutProps<'/[lang]'>): Promise): Promise We have to admit that vibe coding brought huge advantages, but also a heavy burden. Everything except the code is now perfectly clear, so we decided to rebuild the codebase. - -The product direction, what users need, how the protocol works — all clear. The code itself had become the biggest obstacle. This post goes deep: what exactly was wrong with the old version, how each layer of the new architecture is designed, and which invariants hold it together. - -## v0.0.49: a monolith at its product ceiling - -The pre-rewrite version (preserved on [archive/v0.0.49](https://github.com/leookun/cursor-byok/tree/archive/v0.0.49)) was a Go monolith with a webview frontend: 17 packages under `internal/` — `mitm`, `certs`, `cursoraccount`, `modelchannel`, `backend`, `bridge`… The product model was **full replacement**: once started, it took over all of Cursor's backend traffic and substituted the login state with a generated fake account. - -That premise dictated everything: a start/stop switch, a fake account system to maintain, and official plugins and codebase indexing going dark while taken over. Users chose between the "official world" and the "local world". No patch could change the premise — mixing official and local models freely required a new one. - -Meanwhile, code grown through rapid iteration had no dedicated protocol layer: every Cursor client update (new task modes, multitask, checkpoints) meant poking holes throughout the business logic. Boundaries by convention, state scattered everywhere, regression by hand. That is what "a heavy burden" meant concretely. - -## The architecture after the rebuild - -The new version is a Rust workspace where the boundaries are the directories: - -```text -cursor-byok -├── server/src/ -│ ├── harness/ # Local CA and MITM proxy: first-stage traffic routing -│ ├── cursor/ # Cursor protocol layer: session actors, projection, prompt compiler, tool dispatch -│ ├── run/ # Agent loop engine: model cycles × tool rounds -│ ├── provider/ # Model adapters: three protocols normalized into one event stream -│ ├── store/ # SQLite: append-only revision DAG + content-addressed storage -│ └── web/ # Web retrieval -├── crates/ -│ ├── semble-core/ # Code indexing and hybrid retrieval -│ └── semble-mcp/ # Exposed as an MCP server -└── apps/desktop/ # Tauri + React desktop app -``` - -Let's walk through it along the lifecycle of a request. - -## Harness: "coexistence" is a two-stage routing decision - -The new version takes over exactly one thing — model calls. In code, that sentence is a precise two-stage decision: - -**Stage one, at the MITM proxy.** A local CA (a 3072-bit RSA root that never leaves your machine) lets the proxy inspect Cursor's HTTPS. Only `*.cursor.sh` traffic is ever TLS-intercepted (`is_cursor_host`); everything else is tunneled untouched. Within Cursor traffic, only a fixed path allowlist — agent runs (`AgentService/RunSSE`, `BidiService/BidiAppend`), model catalogs, account display endpoints — is rewritten to the local service. Sign-in, the plugin marketplace, codebase indexing, and the rest go straight to official servers. Tab completion follows the user's setting: "Direct" passes through; the public or self-hosted service routes out. - -**Stage two, at the local service.** Even for locally routed requests, the server decodes the first `AgentClientMessage` and looks up its `model_id` in the local model store. Found: handle locally (BYOK). Not found — the user picked an official model — buffer and forward the request back to `api2.cursor.sh`. A Cursor run is a pair of requests (upstream BidiAppend + a long-lived RunSSE stream), and both must take the same path, so a `wait_route` synchronization point blocks the SSE stream until the run is classified `Local` or `Upstream`. - -This is exactly how the fake account and the start/stop switch disappeared: Auto and official models keep flowing to official billing; only your configured models enter the local path — one login, one client, routed per request. - -## The protocol layer: Cursor's protocol behind one door - -`server/src/cursor/` translates Cursor's private protocol into neutral events the engine understands. When the client updates, this is the only layer that moves. A few designs worth unpacking: - -**One actor per request.** Each Cursor run gets a `CursorActor` holding a command mailbox, a cancellation token, and a replayable `OutputHub` — late SSE subscribers get all buffered frames replayed, so reconnects lose nothing. Upstream messages pass through an `OrderedInbox` keyed by sequence number: out-of-order arrivals are buffered, duplicates dropped. The protocol layer tolerates network nondeterminism by construction. - -**Projection is the heart of the layer.** Internally there is one canonical message type (`CanonicalMessage`); the checkpoints sent to Cursor and the requests sent to model providers are both **projections** of it. The Cursor-side checkpoint has a hard check: stable history may only grow. If re-projection finds that a previously generated root "changed" or "shrank", it errors out — failing loudly beats silently corrupting state. - -**Prompts are compiled.** Seven modes — Agent, Ask, Plan, Debug, Multitask, Subagent, Compaction — each built from a prompt template, a runtime template, and a tool manifest. The compiler substitutes placeholders, trims tools by model capability (no image generation → the tool is removed), and appends dynamic MCP tools in **deterministic order**. Determinism is not a style preference; the caching section below shows it is a correctness requirement. - -**Tools execute on the client.** Shell commands, file edits, and searches requested by the model are not executed by the server — they are encoded as instructions for the Cursor client to run in the user's environment, with results returned via BidiAppend. Concurrent edits to the same path are serialized by a scheduler, and streaming arguments are projected into live UI previews. - -## The loop engine: a minimal agent kernel - -`server/src/run/` is the execution kernel, fully independent of the Cursor protocol. A run is a loop: - -```text -loop { - project history → call model (consume_model_cycle) - ├── no tool calls → append final reply, finish - └── tool calls → execute tool round → commit results → continue -} -``` - -**The model cycle is a strict state machine.** `consume_model_cycle` consumes the normalized event stream and enforces protocol invariants: `Start` must come first, text/thinking/tool blocks must open and close in pairs, and the finish reason must agree with the presence of tool calls. On cancellation it cleanly closes any open blocks before exiting — otherwise Cursor would merge deltas from two different outputs. - -**Commit barriers.** Every state commit (initial messages, settled tool results, compaction, the final reply) waits for the Cursor checkpoint worker to acknowledge the write before the engine proceeds. Checkpoint publication is a hard synchronization point — the engine never runs ahead of published state. - -**Auto-compaction is an explicit prefix reset.** The engine calibrates token estimates with the latest real usage; when estimated input exceeds `context window − 10,000` reserved tokens, it compacts: retain **exactly one** latest request-context message, summarize the rest (capped at 4,096 output tokens, reasoning disabled), then rebuild the revision in deterministic order. If compaction is interrupted, a fallback summary of the most recent text keeps the loop going. - -**Cancellation and recovery.** Cancellation tokens propagate from the session all the way into the provider stream; activating a new run in the same conversation cancels the previous one. After a restart, an in-flight tool round can be reconstructed from the Cursor checkpoint and resumed (`RunAction::Resume`) — which is only possible because projection is bidirectional. - -## The invariant: prefix cache stability - -This is where "structure determines correctness" shows most clearly. Providers cache prompts by prefix, and the price difference can be 10×. To hit the cache, history must be an **append-only log**: everything sent to the model last turn must be a byte-level prefix of the next turn. - -Convention cannot defend that, so it is built into every layer: - -- **Storage**: history is an immutable revision DAG — each revision is a complete ordered message list identified by a SHA-256 content digest; appends create child revisions, identical appends reuse existing nodes, and the only "rewrite" is compaction, which branches from the root. Runtime events have unique identities; retries are idempotent, and reusing an identity with different content is a hard error. -- **Projection**: the system prompt and stable tool prefix are byte-stable when inputs are unchanged. Request context (rules, skills, MCP metadata) is separated from the per-turn runtime message: unchanged content is never re-appended; changed content appends a new message right before the runtime message — old ones are never rewritten. Context going A → B → A appends a third distinct A. -- **Provider**: tool-call IDs are normalized before leaving the server; thinking-block signatures (Anthropic's `signature`, OpenAI Responses' encrypted reasoning items) are preserved as replay state and replayed verbatim next turn. - -GPT-family cache hit rates staying consistently high is not luck — it is this entire chain. The repo even carries a dedicated engineering-constraint document (`.agents/skills/cursor-prefix-stability`); every change touching this chain goes through its checklist. - -## The provider layer: three protocols, one event stream - -Three adapters — Anthropic Messages, OpenAI Chat Completions, OpenAI Responses — emit one normalized event vocabulary (`Start`, open/delta/close for text, thinking and tool blocks, `Usage`, `Done`). The engine and protocol layer never know which upstream they are talking to — which is exactly why "pick OpenAI Chat for everything else" works architecturally. - -Every call is observable: sanitized request headers and body, streamed response chunks (buffered with limits), time to first token, token usage — fully replayable in detailed mode. The desktop app's call-details page reads precisely this data. - -## Ecosystem: the rebuild is more than code - -**The official ecosystem is preserved as-is.** The biggest ecosystem consequence of coexistence is "no subtraction": plugins, Skills, MCP, codebase indexing, and Tab completion all keep working once you sign in with your own account. The old version could not do this because it replaced the entire backend. - -**Semantic search is standalone and measurable.** semble implements code indexing and hybrid retrieval as an independent crate, exposed as an MCP server. It ships a reproducible benchmark (real React/Vue commits, queries hand-labeled to implementation lines): natural-language queries reach 95% Recall@5, literal and symbol queries reach 100% — with a public quality-gate file, so any retrieval regression fails CI. - -**The Tab service is open at three levels.** Public service (hosted by the author), Direct (your own account's official service), or self-hosted (`cursor-tab-server` lives on the archive branch) — switchable in system settings. - -**The engineering system is part of the ecosystem too.** The repo maintains domain-constraint documents (database schema, prefix-cache stability, release process, i18n…) shared by humans and AI working on the code; `make check` runs formatting, linting, the full test suite, and frontend type checks in one command. This documentation site — including the interactive demo on the homepage built from real desktop components and mock data — lives in the same repo and evolves with the product. - -**Direction is driven by community discussion.** Tab support, Gemini, image generation, all task modes, and codebase indexing from the roadmap have all landed in the rebuilt version, with more IDEs planned. - -## Was it worth it - -The rebuild consumed weeks that could have gone into features. In exchange: the product model no longer limits itself; protocol updates have a fixed landing place (only `cursor/` moves); correctness is guarded by types, invariants, and regression tests instead of memory; and every new capability grows on a product that already works. - -The problem used to be "everything is clear except the code" — now the code is clear too. Thoughts on the rebuild? Join the [Roadmap discussion](https://github.com/leookun/cursor-byok/discussions/32). diff --git a/apps/docs/content/blog/2026-08-28-why-we-rebuilt.mdx b/apps/docs/content/blog/2026-08-28-why-we-rebuilt.mdx deleted file mode 100644 index 329aaa1..0000000 --- a/apps/docs/content/blog/2026-08-28-why-we-rebuilt.mdx +++ /dev/null @@ -1,117 +0,0 @@ ---- -title: 为什么我们重构代码？ -description: 从 v0.0.49 的 Go 单体到 Rust 重写——harness、协议层、Agent 循环引擎、架构不变量与生态的深度解析。 ---- - -在 [v1.0 Roadmap](https://github.com/leookun/cursor-byok/discussions/32) 里我们写过这样一段话： - -> 不得不承认 vibe coding 带来了巨大的优势，但也带来了沉重的负担。现在我认为除了代码之外的一切内容都十分清晰，所以决定在近期重构代码。 - -产品方向、用户需要什么、协议怎么工作——这些都清楚，唯独代码本身成了继续前进的最大阻力。这篇文章把这次重构讲透：旧版到底哪里不行，新架构的每一层是怎么设计的，以及哪些不变量在支撑它。 - -## v0.0.49：一个走到产品上限的单体 - -重构前的版本（保留在 [archive/v0.0.49](https://github.com/leookun/cursor-byok/tree/archive/v0.0.49) 分支）是一个 Go 单体加 webview 前端：`internal/` 下 17 个包，`mitm`、`certs`、`cursoraccount`、`modelchannel`、`backend`、`bridge`……产品模式是**整体替换**——服务启动后接管 Cursor 的全部后端流量，用内置生成的 fake 账户顶替登录态。 - -这个前提决定了一切：需要「启动/停止服务」的开关，需要维护假账户体系，官方的插件、代码库索引在接管状态下全部失效。用户在「官方世界」和「本地世界」之间二选一。修补任何一处都动摇不了这个前提——想让官方模型和自己的模型自由混用，必须换前提。 - -同时，快速迭代长出来的代码没有独立的协议层：Cursor 客户端每次更新（新任务模式、multitask、checkpoint），都要在业务逻辑里到处开洞。模块边界靠约定、状态散落各处、回归靠人肉。这就是「沉重的负担」的具体含义。 - -## 重构后的架构 - -新版是一个 Rust workspace，边界即目录： - -```text -cursor-byok -├── server/src/ -│ ├── harness/ # 本地 CA 与 MITM 代理:流量的第一级路由 -│ ├── cursor/ # Cursor 协议层:会话 actor、投影、提示词编译、工具调度 -│ ├── run/ # Agent 循环引擎:模型周期 × 工具轮次 -│ ├── provider/ # 模型适配:三种协议归一化为统一事件流 -│ ├── store/ # SQLite:append-only 修订 DAG + 内容寻址存储 -│ └── web/ # 网页检索能力 -├── crates/ -│ ├── semble-core/ # 代码索引与混合检索 -│ └── semble-mcp/ # 以 MCP 服务形态暴露 -└── apps/desktop/ # Tauri + React 桌面端 -``` - -下面按请求的生命周期，逐层拆开。 - -## Harness：「并存」是一个两级路由决策 - -新版只接管一件事——模型调用。这句话在代码里是一个精确的两级决策： - -**第一级在 MITM 代理层。** 本地 CA（3072 位 RSA 根证书，只存在于你的机器）让代理能解析 Cursor 发出的 HTTPS。但只有 `*.cursor.sh` 的流量会被 TLS 解析（`is_cursor_host`），其余一律原样隧道。解析后再看路径：只有一个固定白名单——Agent 运行（`AgentService/RunSSE`、`BidiService/BidiAppend`）、模型目录、账号信息展示等——会被改写到本地服务；登录、插件市场、代码库索引等其余请求原封不动发往官方服务器。Tab 补全按用户设置：选「直连」就直通官方，选公益或自建才路由出去。 - -**第二级在本地服务层。** 即使请求进了本地，服务端解码首个 `AgentClientMessage` 后按 `model_id` 查本地模型配置：查到，本地处理（BYOK）；查不到——说明用户选的是官方模型——整个请求缓冲后转发回 `api2.cursor.sh`。Cursor 的运行由一对请求组成（上行 BidiAppend + 下行 RunSSE 流），两者必须走同一条路，所以有一个 `wait_route` 同步点：SSE 流会阻塞等待路由分类（`Local` 或 `Upstream`）后再跟随。 - -fake 账户、启停开关就是这样消失的：官方模型选 Auto 或官方型号照常走官方计费，选你配置的模型才进本地——同一个登录态，同一个客户端，逐请求分流。 - -## 协议层：把 Cursor 协议关进一个模块 - -`server/src/cursor/` 的职责是把 Cursor 的私有协议翻译成引擎能理解的中立事件，客户端更新时只有这一层需要动。几个值得展开的设计： - -**每个请求一个 actor。** 每个 Cursor 运行请求对应一个 `CursorActor`，持有命令信箱、取消令牌和一个可重放的输出中枢（`OutputHub`）——SSE 订阅者迟到时，缓冲的帧会全部重放，客户端断线重连不丢内容。上行消息经过一个按序号重排的 `OrderedInbox`：乱序到达缓冲，重复到达丢弃，协议层天然容忍网络的不确定性。 - -**投影（projection）是协议层的核心。** 服务端内部只有一种「规范消息」（`CanonicalMessage`），发给 Cursor 的检查点、发给模型服务商的请求，都是从规范消息**投影**出来的两种视图。Cursor 侧的检查点还有一条硬性校验：稳定历史只能追加，如果重投影时发现某个已生成的根「变了」或「变少了」，直接报错——宁可失败也不静默破坏状态。 - -**提示词是编译出来的。** Agent、Ask、Plan、Debug、Multitask、Subagent、Compaction 七种模式，每种由 prompt 模板 + runtime 模板 + 工具清单构成，编译器负责占位符替换、按模型能力裁剪工具（不支持图片生成就移除对应工具）、以确定性顺序追加动态 MCP 工具。确定性不是风格偏好，后面讲缓存时会看到它是正确性要求。 - -**工具在客户端执行。** 模型发起的 shell、读写文件、搜索，服务端并不亲自执行，而是编码成指令下发给 Cursor 客户端，由客户端在用户环境里跑，结果再经 BidiAppend 回传。同路径的并发编辑有串行化调度，流式参数还会被投影成 UI 的实时预览。 - -## Loop 引擎：Agent 循环的最小内核 - -`server/src/run/` 是与 Cursor 协议无关的执行内核。一次运行就是一个循环： - -```text -loop { - 投影历史 → 调用模型(consume_model_cycle) - ├── 无工具调用 → 追加最终回复,结束 - └── 有工具调用 → 执行工具轮次(tool_round) → 提交结果 → 继续循环 -} -``` - -**模型周期是严格的状态机。** `consume_model_cycle` 消费归一化事件流,校验协议不变量：必须先 Start、文本/思考/工具块必须成对开闭、`finish_reason` 与工具调用必须一致。取消发生时它会先干净地闭合未闭合的块再退出——否则 Cursor 端会把两次输出的增量拼在一起。 - -**提交屏障（commit barrier）。** 引擎每次提交状态（初始消息、工具结果落定、压缩、最终回复），都要等 Cursor 检查点工作线程确认写完才继续。检查点发布是引擎与协议层之间的硬同步点——引擎永远不会跑到已发布状态的前面。 - -**自动压缩是显式的前缀重置。** 引擎用最近一次真实用量校准 token 估算,当估算输入超过 `上下文窗口 − 10_000` 预留时触发压缩：保留**恰好一条**最新的 request-context 消息，其余历史交给模型摘要（上限 4096 token、关闭思考），然后以确定性顺序重建修订。压缩若被打断，退化为截取最近文本的兜底摘要，循环继续。 - -**取消与恢复。** 取消令牌从会话一路传到 provider 流；同一会话激活新运行会自动取消旧的。服务重启后，进行中的工具轮次能从 Cursor 检查点反解出来继续执行（`RunAction::Resume`）——这依赖投影是双向的。 - -## 不变量：前缀缓存稳定性 - -这是整次重构里最能体现「结构决定正确性」的部分。模型服务商的提示词缓存按前缀命中，收费差可达 10 倍。要吃到缓存，历史就必须是**只追加的日志**：上一轮发给模型的完整内容，必须是下一轮的字节级前缀。 - -约定守不住这件事，所以它被做进了每一层： - -- **存储层**：会话历史是不可变的修订 DAG——每个修订是完整的有序消息列表，由 SHA-256 内容摘要标识；追加产生子修订，内容相同的追加会复用已有节点；唯一能「改写」的操作是压缩，而它是从根分支出新链。运行时事件有唯一标识,重试幂等,内容不同的复用直接报错。 -- **投影层**：系统提示词与稳定工具前缀在输入不变时字节级稳定;规则/技能等请求上下文与当轮 runtime 消息分离,内容不变不重复追加,变了就在 runtime 消息前追加新的一条——从不改写旧的。上下文 A→B→A 会追加第三条 A,而不是复用第一条。 -- **provider 层**：工具调用 ID 在发给服务商前统一归一化;思考块的签名（Anthropic 的 signature、OpenAI Responses 的加密推理项）被原样保存为回放状态,下一轮逐字回放。 - -新版 GPT 系列缓存命中率能稳定在高位,靠的不是运气,是这一整条链。仓库里甚至有一份专门的工程约束文档(`.agents/skills/cursor-prefix-stability`),任何触碰这条链的改动都要过它的检查单。 - -## Provider 层：三种协议,一种事件流 - -Anthropic Messages、OpenAI Chat Completions、OpenAI Responses 三个适配器,输出统一的归一化事件（`Start`、文本/思考/工具块的开闭与增量、`Usage`、`Done`）。引擎和协议层完全不知道上游是谁——这就是「其他模型无脑选 OpenAI Chat」在架构上成立的原因。 - -每次调用都有观测：请求头体（脱敏）、逐块流式响应（带缓冲与限额）、首字延迟、token 用量,详细模式下可完整回放。桌面端的调用详情页读的就是这些数据。 - -## 生态：重构不只是代码 - -**官方生态原样保留。** 并存设计最大的生态意义是「不减法」：插件、Skills、MCP、代码库索引、Tab 补全,登录自己的账号后全部照常。旧版做不到,是因为它把整个后端都换掉了。 - -**语义搜索是独立的、可度量的。** semble 作为独立 crate 实现代码索引与混合检索,以 MCP 服务形态接入。它有一套可复现的对比基准（React/Vue 真实提交、人工标注到实现行）：自然语言查询 Recall@5 达 95%,字面与符号查询达 100%,并有公开的质量门槛文件——CI 里任何一次检索质量回退都会挡住合并。 - -**Tab 服务分层开放。** 公益服务（作者部署）、直连（自己账号的官方服务）、自建（`cursor-tab-server` 留在归档分支）三种模式,在系统设置里一键切换。 - -**工程体系也是生态。** 仓库里维护着一组领域约束文档（数据库 schema、前缀缓存稳定性、发布流程、i18n……）,人和 AI 协作时共用同一套检查单;`make check` 一条命令跑完格式、静态检查、全量测试和前端类型检查。这个文档站本身——包括首页那个用真实桌面组件加 mock 数据构建的可交互 demo——也在同一个仓库里,与产品同步演进。 - -**方向由社区讨论驱动。** Roadmap 里的 Tab 支持、Gemini、图片生成、全部任务模式、代码库索引都已在重构后的版本里落地,更多 IDE 的支持在计划中。 - -## 值得吗 - -重构耗掉了数周本可以用来加功能的时间。换来的是：产品模式不再自我设限;协议更新有了固定的落点（只动 `cursor/`）;正确性由类型、不变量和回归测试守护,而不是靠记忆;每个新能力都长在一个已经能工作的产品上。 - -「除了代码之外的一切都清晰」的问题,现在代码也清晰了。对这次重构有想法？欢迎到 [Roadmap 讨论区](https://github.com/leookun/cursor-byok/discussions/32) 聊聊。 diff --git a/apps/docs/content/docs/faq.en.mdx b/apps/docs/content/docs/faq.en.mdx new file mode 100644 index 0000000..16bb192 --- /dev/null +++ b/apps/docs/content/docs/faq.en.mdx @@ -0,0 +1,90 @@ +--- +title: Frequently Asked Questions +description: Answers to common Cursor Byok questions about setup, accounts, models, and TAB completion. +icon: Wrench +--- + +## Q: Why does Cursor show “not signed in,” omit the model, or show `An unexpected error occurred` after an upgrade or first setup? + +**A:** After upgrading Cursor or configuring a model for the first time, Cursor needs to establish a new connection. If you see the following error, run the complete restart sequence instead of continuing in the current conversation: + +```text +An unexpected error occurred. Request ID: 3871795e-2a93-4628-8308-c641047e9e43 +``` + +Complete these steps in order: + +1. Keep Cursor Byok running. +2. Quit Cursor completely, confirm the process has stopped, and restart it. +3. Start a new conversation instead of continuing one opened before setup or the switch. +4. Select your configured model from the model list. + +The same sequence is required after a first-time Cursor upgrade or model setup. Conversations created with the current version stay synchronized with official Cursor conversations and can continue with official models. + +## Q: Do I need to sign in to my own Cursor account when switching to the current version? + +**A:** No. You can use your own models without a Cursor account. Signing in to any Cursor account is recommended because it provides better access to official plugins, MCP, Skills, codebase indexing, and official models. Switching Cursor accounts does not require quitting Cursor Byok. + +## Q: Can I continue a conversation that was opened with the old version? + +**A:** Conversations created by the old assistant cannot be continued directly in the current version; start a new conversation. Conversations created with the current version synchronize with Cursor and can switch between your models and official models. + +## Q: Does the current version support official Cursor models? + +**A:** Yes. Official Cursor models and your configured local models can coexist. Auto, Composer, and other official models continue to use Cursor's official service, while your configured models are routed through Cursor Byok. + +## Q: Why does selecting Auto show a quota or account error? + +**A:** Auto uses only official Cursor models and does not automatically use your configured models. If your account has no official quota, select your own model manually from the model list. With official quota, you can switch freely between official and configured models. + +## Q: Can I still use Cursor plugins, MCP, Skills, and codebase indexing? + +**A:** Yes. The current version coexists with Cursor's official service. After signing in to any Cursor account, you can continue using official plugins, MCP, Skills, Auto, and codebase indexing. Codebase indexing uses Cursor's official indexing service, so upgrade Cursor to the latest version. + +## Q: Why is the first semantic search slow? + +**A:** The first semantic search call automatically downloads the embedding model. Later searches use the local model. Keep the network connection available and wait for the initial download to finish. + +## Q: Where do I configure TAB completion? + +**A:** Go to **System Settings → TAB Settings** in Cursor Byok and choose one of these modes: + +- **Direct connection**: connects to the official TAB service for the account signed in to Cursor. +- **Community service**: uses the free TAB service provided by the author. +- **Custom**: connects to a TAB completion service that you deploy separately. + +These TAB completion capabilities all come from Cursor's official service. Custom BYOK models are generally not suitable for code completion and are not used for TAB completion. After changing this setting, restart Cursor and start a new conversation. + +## Q: Why do Agent requests fail even though the model test passes? + +**A:** The model test verifies basic connectivity only. Agent requests also include longer context, tool definitions, and streaming responses. Check: + +- Whether the upstream model supports tool calling. +- Whether the context window and maximum output tokens fit the model's limits. +- Whether the model type, request protocol, and server address match. +- Whether custom headers and extra parameters follow the upstream protocol. +- The upstream status code and response body in **Call Statistics** or call details. + +## Q: What is the local CA, and what should I do if initialization fails? + +**A:** The local CA (certificate authority) allows Cursor Byok to inspect HTTPS requests from Cursor. Its files stay on your machine. Go to **Cursor Settings** and click **Initialize CA**. When the system asks for authorization, follow the app's terminal instructions to install and trust it, then return to the app and click **I have initialized, refresh**. + +If the status does not update, quit and restart Cursor Byok completely, then open Cursor Settings again. + +## Q: What should I do if the model connectivity test fails? + +**A:** Check the error category: + +- **Authentication error**: confirm the API key is valid and the account can access the target model. +- **Endpoint not found**: confirm the model type, request protocol, and server address match. +- **Model not found**: use **Fetch Models** to check the model identifiers returned by the upstream. +- **Invalid parameters**: temporarily remove custom headers and extra parameters, then test again. +- **Connection timeout**: check your network, system proxy, and upstream service status. + +## Q: What should I do about a fake account generated by the old version? + +**A:** Sign out of the fake account in Cursor, then sign in to any Cursor account, or remain signed out while using your own models. The current version does not require a fake account or a “stop service” workflow to switch between official and configured models. + +## Q: What information should I include when reporting another issue? + +**A:** Open a report on [GitHub Issues](https://github.com/leookun/cursor-byok/issues) with your operating system, Cursor Byok version, model type, request protocol, redacted server address, error message, and reproduction steps. Never share API keys or other credentials. diff --git a/apps/docs/content/docs/faq.mdx b/apps/docs/content/docs/faq.mdx new file mode 100644 index 0000000..47f5048 --- /dev/null +++ b/apps/docs/content/docs/faq.mdx @@ -0,0 +1,90 @@ +--- +title: 常见问题 +description: 以问答形式解答 Cursor Byok 的配置、账号、模型和 TAB 补全问题。 +icon: Wrench +--- + +## Q：首次升级或配置后，为什么 Cursor 提示“未登录”、看不到模型或出现 `An unexpected error occurred`？ + +**A：** 首次升级 Cursor 或首次配置模型后，Cursor 需要重新建立连接。遇到以下错误时，请先执行完整重启流程，而不是继续使用当前对话： + +```text +An unexpected error occurred. Request ID: 3871795e-2a93-4628-8308-c641047e9e43 +``` + +请按顺序完成以下操作： + +1. 保持 Cursor Byok 运行。 +2. 完全退出 Cursor，确认进程结束后重新启动。 +3. 新建一个对话，不要继续使用配置前或切换前已经打开的对话。 +4. 在模型列表中选择你配置的模型。 + +首次升级或首次配置模型后也需要执行这套流程。新版创建的对话会与 Cursor 官方对话同步，可以和官方模型继续衔接。 + +## Q：切换到新版需要登录自己的 Cursor 账号吗？ + +**A：** 不需要。新版可以在没有 Cursor 账号的情况下使用自己的模型；不过建议在 Cursor 中登录任意账号，这样可以更好地使用官方插件、MCP、Skills、代码库索引和官方模型等功能。切换 Cursor 账号时不需要退出 Cursor Byok。 + +## Q：旧版已经打开的对话可以继续使用吗？ + +**A：** 旧助手产生的对话无法直接在新版中续接，需要新开一个对话。新版产生的对话与 Cursor 官方同步，可以在新版和官方模型之间无缝切换或继续对话。 + +## Q：新版支持 Cursor 官方模型吗？ + +**A：** 支持。新版可以让 Cursor 官方模型与自己配置的本地模型同时存在，例如 Auto、Composer 等官方模型仍由 Cursor 官方服务处理，自己配置的模型则通过 Cursor Byok 转发。 + +## Q：为什么选择 Auto 会提示额度或账号错误？ + +**A：** Auto 只会使用 Cursor 官方模型，不会自动使用你配置的本地模型。账号没有官方额度时，请在模型列表中手动选择自己的模型；有官方额度时，可以在官方模型和自己的模型之间自由切换。 + +## Q：Cursor 的插件、MCP、Skills 和代码库索引还能使用吗？ + +**A：** 可以。新版与 Cursor 官方服务并存，登录任意 Cursor 账号后可以继续使用官方插件、MCP、Skills、Auto 模型和代码库索引。代码库索引使用 Cursor 官方索引服务，需要将 Cursor 升级到最新版。 + +## Q：语意搜索第一次使用为什么比较慢？ + +**A：** 首次调用语意搜索时，应用会自动下载 Embedding Model（文本向量模型）。下载完成后，后续搜索会直接使用本地模型。模型文件较大时，请保持网络连接并耐心等待首次下载完成。 + +## Q：TAB 补全在哪里设置？ + +**A：** 在 Cursor Byok 的 **系统设置 → TAB 设置** 中选择： + +- **直连**：连接你在 Cursor 中登录的账号对应的官方 TAB 服务。 +- **公益服务**：使用作者提供的免费 TAB 服务。 +- **自定义**：连接你自己额外部署的 TAB 补全服务。 + +这些 TAB 补全能力都来自 Cursor 官方服务。自定义的 BYOK 模型通常不适合处理代码补全，因此不会用于 TAB 补全。修改设置后，请重启 Cursor 并新建一个对话。 + +## Q：为什么模型测试通过了，Agent 请求仍然失败？ + +**A：** 模型测试只验证基础连接。Agent 请求还会包含更长的上下文、工具定义和流式响应，请检查： + +- 上游模型是否支持工具调用。 +- 上下文窗口和最大输出 Token 是否符合模型限制。 +- 模型类型、请求协议和服务地址是否匹配。 +- 自定义 Headers 和额外参数是否符合上游协议。 +- **调用统计**或调用详情中的上游状态码和响应内容。 + +## Q：本地 CA 是什么？初始化失败怎么办？ + +**A：** 本地 CA（证书颁发机构）用于让 Cursor Byok 解析 Cursor 发出的 HTTPS 请求，相关文件只保存在本机。进入 **Cursor 配置**，点击 **初始化 CA**；系统要求授权时，按照应用提示在终端中完成安装和信任，然后返回应用点击 **我已初始化，刷新**。 + +如果状态没有更新，请完全退出并重新启动 Cursor Byok，再次打开 Cursor 配置页面。 + +## Q：模型连通性测试失败怎么办？ + +**A：** 根据测试错误检查： + +- **认证错误**：确认 API Key 有效，并且账户有权访问目标模型。 +- **接口不存在**：确认模型类型、请求协议和服务器地址匹配。 +- **模型不存在**：使用 **获取模型** 检查上游返回的模型标识。 +- **参数错误**：暂时移除自定义 Headers 和额外参数，再重新测试。 +- **连接超时**：检查网络、系统代理和上游服务状态。 + +## Q：还在使用旧版生成的 fake 账户怎么办？ + +**A：** 在 Cursor 中退出旧版生成的 fake 账户，然后登录任意 Cursor 账号，或直接保持未登录状态使用自己的模型。新版不再需要 fake 账户，也不需要通过“停止服务”来切换官方服务和本地模型。 + +## Q：遇到其他问题时，需要提供什么信息？ + +**A：** 请在 [GitHub Issues](https://github.com/leookun/cursor-byok/issues) 提交问题，并附上操作系统、Cursor Byok 版本、模型类型、请求协议、已脱敏的服务地址、错误信息和复现步骤。请勿公开 API Key 或其他凭据。 diff --git a/apps/docs/content/docs/index.en.mdx b/apps/docs/content/docs/index.en.mdx index 086743f..3d02c12 100644 --- a/apps/docs/content/docs/index.en.mdx +++ b/apps/docs/content/docs/index.en.mdx @@ -10,6 +10,10 @@ Cursor Byok is a Cursor model gateway that runs on your machine. It receives Cur Cursor Byok is an independent open-source project and is not affiliated with Cursor or its developers. The software itself is free, but model providers may charge for usage. + +After upgrading Cursor or configuring a model for the first time, quit Cursor completely and restart it once, then start a new conversation before selecting the model. Existing conversations do not load the new connection settings and may show “not signed in,” omit the model, or show `An unexpected error occurred`. + + ## Install and configure @@ -44,17 +48,17 @@ See [Model Configuration](./model-configuration.mdx) for how to choose the type -### Restart Cursor after the first setup +### Restart Cursor after an upgrade or first setup -After completing the configuration for the first time, quit and restart Cursor once so the model list takes effect. +After upgrading Cursor or configuring a model for the first time, **quit Cursor completely and restart it once**. Closing only the window or continuing in the current conversation does not load the new connection settings. -### Use it in Cursor +### Start a new conversation and select the model -Keep Cursor Byok running, start a new conversation in Cursor, pick the model you just configured from the model list (do not pick Auto), and start using Agent. +Once Cursor has restarted, start a new conversation and select the model you just configured from the model list (do not select Auto). Do not continue a conversation that was already open before setup. @@ -75,7 +79,7 @@ The current design goal is coexistence with the official service — there is no - + ## How data flows diff --git a/apps/docs/content/docs/index.mdx b/apps/docs/content/docs/index.mdx index 85d4078..f731909 100644 --- a/apps/docs/content/docs/index.mdx +++ b/apps/docs/content/docs/index.mdx @@ -10,6 +10,10 @@ Cursor Byok 是运行在本机的 Cursor 模型网关。它接收 Cursor Agent Cursor Byok 是独立开源项目，与 Cursor 及其开发者没有关联。软件本身免费，但模型服务商可能按用量收费。 + +首次升级 Cursor 或首次配置模型后，请完全退出并重新启动一次 Cursor，然后新建一个对话再选择模型。现有对话不会加载新的连接配置，继续使用可能提示“未登录”、无法看到模型，或出现 `An unexpected error occurred`。 + + ## 安装与配置 @@ -44,17 +48,17 @@ Cursor Byok 是独立开源项目，与 Cursor 及其开发者没有关联。软 -### 首次配置后重启 Cursor +### 首次升级或配置后重启 Cursor -首次完成配置时，完全退出并重新启动一次 Cursor，让模型列表生效。 +首次升级 Cursor 或首次配置模型后，**必须完全退出 Cursor 并重新启动一次**。仅关闭窗口或继续使用当前对话，都不会加载新的连接配置。 -### 在 Cursor 中使用 +### 新建对话并选择模型 -保持 Cursor Byok 运行，在 Cursor 中新开一个对话，从模型列表中选择你刚配置的模型（不要选 Auto），开始使用 Agent。 +Cursor 重启完成后，点击新建对话，再从模型列表中选择你刚配置的模型（不要选 Auto）。请勿继续使用配置前已经打开的对话。 @@ -75,7 +79,7 @@ Cursor Byok 是独立开源项目，与 Cursor 及其开发者没有关联。软 - + ## 数据如何流转 diff --git a/apps/docs/content/docs/installation.en.mdx b/apps/docs/content/docs/installation.en.mdx index 4074cfb..a9efc1a 100644 --- a/apps/docs/content/docs/installation.en.mdx +++ b/apps/docs/content/docs/installation.en.mdx @@ -50,6 +50,22 @@ Click **Test** on the model. Once the test passes, the model appears in Cursor's + + +### Completely restart Cursor after an upgrade or first setup + +After upgrading Cursor or configuring a model for the first time, **quit Cursor completely and restart it once**. Closing only the window is not enough; make sure the Cursor process has stopped before opening it again. + + + + + +### Start a new conversation + +After Cursor restarts, start a new conversation and select your configured model from the model list. Do not continue a conversation opened before setup, and do not select **Auto**. + + + ## Verify the installation @@ -59,9 +75,11 @@ After configuration, confirm that: - The Cursor Settings page no longer shows the CA initialization prompt. - At least one model passes the connectivity test. - Cursor Byok stays running. +- Cursor has been quit completely and restarted once. +- You started a new conversation instead of continuing one opened before setup. - The configured display name shows up in Cursor's model list. -If any of these steps fail, head to [Troubleshooting](./troubleshooting.mdx). +If any of these steps fail, head to [Frequently Asked Questions](./faq.mdx). ## Updates diff --git a/apps/docs/content/docs/installation.mdx b/apps/docs/content/docs/installation.mdx index c07cfee..805d96d 100644 --- a/apps/docs/content/docs/installation.mdx +++ b/apps/docs/content/docs/installation.mdx @@ -50,6 +50,22 @@ icon: Download + + +### 首次升级或配置后完全重启 Cursor + +首次升级 Cursor 或首次配置模型后，**必须完全退出并重新启动一次 Cursor**。仅关闭窗口不等于退出；请确认 Cursor 进程已经结束后再重新打开。 + + + + + +### 新建对话 + +Cursor 重启后新建一个对话，再从模型列表中选择你配置的模型。不要继续使用配置前已打开的对话，也不要选择 **Auto**。 + + + ## 验证安装 @@ -59,9 +75,11 @@ icon: Download - Cursor 配置页面不再显示 CA 初始化提示。 - 至少一个模型的连通性测试成功。 - Cursor Byok 保持运行。 +- 已完全退出并重新启动一次 Cursor。 +- 已新建对话，而不是继续使用配置前打开的对话。 - Cursor 模型列表中能看到配置的显示名称。 -如果其中任何一步失败，请前往[故障排查](./troubleshooting.mdx)。 +如果其中任何一步失败，请前往[常见问题](./faq.mdx)。 ## 更新 diff --git a/apps/docs/content/docs/meta.en.json b/apps/docs/content/docs/meta.en.json index e1d2d61..dfb8bf9 100644 --- a/apps/docs/content/docs/meta.en.json +++ b/apps/docs/content/docs/meta.en.json @@ -1,5 +1,5 @@ { "title": "User Guide", "root": true, - "pages": ["index", "installation", "model-configuration", "tab-service", "troubleshooting"] + "pages": ["index", "installation", "model-configuration", "tab-service", "faq"] } diff --git a/apps/docs/content/docs/meta.json b/apps/docs/content/docs/meta.json index 2c0ec65..a178c17 100644 --- a/apps/docs/content/docs/meta.json +++ b/apps/docs/content/docs/meta.json @@ -1,5 +1,5 @@ { "title": "使用指南", "root": true, - "pages": ["index", "installation", "model-configuration", "tab-service", "troubleshooting"] + "pages": ["index", "installation", "model-configuration", "tab-service", "faq"] } diff --git a/apps/docs/content/docs/troubleshooting.en.mdx b/apps/docs/content/docs/troubleshooting.en.mdx deleted file mode 100644 index 5a332bd..0000000 --- a/apps/docs/content/docs/troubleshooting.en.mdx +++ /dev/null @@ -1,83 +0,0 @@ ---- -title: Troubleshooting -description: Resolve issues with the local CA, the management service, model connections, and Cursor's model list. -icon: Wrench ---- - -## Local CA needs to be initialized - -Go to **Cursor Settings** and click **Initialize CA**. The local CA stays on your machine and is used to inspect HTTPS requests from Cursor. - -## Local CA needs to be trusted by the system - -Click **Open terminal to install CA** and follow the terminal prompts to complete system authorization. When done, return to the app and click **I have initialized, refresh**. - -If the status does not update, quit Cursor Byok completely, restart it, and open the Cursor Settings page again. - -## Cannot connect to the local management service - -1. Quit and restart Cursor Byok completely. -2. Check whether security software is blocking local loopback connections. -3. If you changed the management service port, reset it to `0` so the app picks an available port at startup. -4. Launch the app again and refresh the page. - -## Model connectivity test fails - -Check based on the test error: - -- **Authentication error**: confirm the API key is valid and the account can access the target model. -- **Endpoint not found**: confirm the model type, request protocol, and server address match. -- **Model not found**: use **Fetch Models** to check the model identifiers returned by the upstream. -- **Invalid parameters**: temporarily remove custom headers and extra parameters, then test again. -- **Connection timeout**: check your network, system proxy, and the upstream service status. - -## Models do not show up in Cursor or do not take effect - -First confirm all of the following: - -1. The local CA status is healthy. -2. At least one model configuration is saved. -3. The model connectivity test passes. -4. Cursor Byok is running. - -If it still does not work, run the full restart sequence in order: - -1. Quit Cursor Byok completely from the tray and start it again. -2. Quit and restart Cursor completely. -3. Start a new conversation and refresh the model list. -4. Pick your own configured model — **do not pick Auto**. - -## Quota or account errors when picking Auto - -Auto only routes to official Cursor models and never uses your locally configured models. If your account has no official quota, picking Auto fails — select your configured model from the model list instead. - -If your account does have quota, official models and local models mix freely with no usage boundary. - -## Still using an old fake account - -The current design coexists with your official account — fake accounts and "stop the service" workflows are no longer needed: - -1. Sign out of the fake account generated by an old version in Cursor. -2. Sign in with your own Cursor account. - -Once signed in with your own account, Cursor features such as plugins and codebase indexing work as usual. - -## Requests fail even though the test passes - -The model test only verifies basic connectivity. Agent requests also involve longer context, tool definitions, and streaming responses. Check: - -- Whether the upstream model supports tool calling. -- Whether the context window and max output tokens fit the model's limits. -- Whether custom parameters are compatible with the actual protocol. -- The upstream status code and response body in the call details. - -## Report an issue - -If the problem persists, file an issue on [GitHub Issues](https://github.com/leookun/cursor-byok/issues) and include: - -- Your operating system and Cursor Byok version. -- The selected model type and request protocol. -- The redacted server address and error message. -- Steps to reproduce. - -Never share API keys or other credentials publicly. diff --git a/apps/docs/content/docs/troubleshooting.mdx b/apps/docs/content/docs/troubleshooting.mdx deleted file mode 100644 index 7f9a02a..0000000 --- a/apps/docs/content/docs/troubleshooting.mdx +++ /dev/null @@ -1,83 +0,0 @@ ---- -title: 故障排查 -description: 处理本地 CA、管理服务、模型连接和 Cursor 模型列表问题。 -icon: Wrench ---- - -## 需要先初始化本地 CA - -进入 **Cursor 配置**，点击 **初始化 CA**。本地 CA 只保存在本机，用于解析 Cursor 发出的 HTTPS 请求。 - -## 需要在系统中信任本地 CA - -点击 **打开终端安装 CA**，按照终端提示完成系统授权。完成后返回应用，点击 **我已初始化，刷新**。 - -如果状态没有更新，请完全退出后重新启动 Cursor Byok，再次打开 Cursor 配置页面。 - -## 无法连接本地管理服务 - -1. 完全退出并重新启动 Cursor Byok。 -2. 检查是否有安全软件拦截本地回环连接。 -3. 如果修改过管理服务端口，将端口恢复为 `0`，让应用在启动时自动选择可用端口。 -4. 再次启动应用并刷新页面。 - -## 模型连通性测试失败 - -按测试错误逐项检查： - -- **认证错误**：确认 API Key 有效，且账户有权访问目标模型。 -- **未找到接口**：确认模型类型、请求协议与服务器地址匹配。 -- **模型不存在**：使用 **获取模型** 检查上游返回的模型标识。 -- **参数错误**：暂时关闭自定义 Headers 和额外参数，再重新测试。 -- **连接超时**：检查网络、系统代理和上游服务状态。 - -## Cursor 中看不到模型或模型不生效 - -先确认以下条件全部满足： - -1. 本地 CA 状态正常。 -2. 已保存至少一个模型配置。 -3. 模型连通性测试成功。 -4. Cursor Byok 正在运行。 - -仍然不生效时，按顺序执行一遍完整的重启流程： - -1. 从托盘完全退出 Cursor Byok，重新启动。 -2. 完全退出并重新启动 Cursor。 -3. 新开一个对话，刷新模型列表。 -4. 选择你自己配置的模型，**不要选 Auto**。 - -## 选 Auto 时报额度或账户错误 - -Auto 只会路由到 Cursor 官方模型，不会使用你配置的本地模型。账号没有官方额度时选 Auto 就会报错——请在模型列表中手动选择你配置的模型。 - -如果账号本身有额度，官方模型和本地模型可以随意混用，没有使用上的边界。 - -## 还在使用旧版的 fake 账户 - -新版的设计是与官方账号并存，不再需要 fake 账户，也没有“关服务”之类的操作： - -1. 在 Cursor 中退出旧版生成的 fake 账户。 -2. 登录你自己的 Cursor 账号。 - -登录自己的账号后，插件、代码库索引等 Cursor 功能都可以正常使用。 - -## 请求失败但测试成功 - -模型测试只验证基础连接。Agent 请求还会包含更长上下文、工具定义和流式响应。请检查： - -- 上游模型是否支持工具调用。 -- 上下文窗口和最大输出 Token 是否符合模型限制。 -- 自定义参数是否与实际协议兼容。 -- 调用详情中的上游状态码和响应内容。 - -## 继续反馈 - -如果问题仍然存在，请在 [GitHub Issues](https://github.com/leookun/cursor-byok/issues) 提交问题，并附上： - -- 操作系统与 Cursor Byok 版本。 -- 选择的模型类型和请求协议。 -- 已脱敏的服务地址与错误信息。 -- 复现步骤。 - -请勿公开 API Key 或其他凭据。 diff --git a/apps/docs/lib/layout.shared.tsx b/apps/docs/lib/layout.shared.tsx index 2310bbe..5b51864 100644 --- a/apps/docs/lib/layout.shared.tsx +++ b/apps/docs/lib/layout.shared.tsx @@ -2,6 +2,7 @@ import Image from 'next/image'; import { zhCN } from '@fumadocs/language/zh-cn'; import type { BaseLayoutProps } from 'fumadocs-ui/layouts/shared'; import { uiTranslations } from 'fumadocs-ui/i18n'; +import { blogSource } from './blog'; import { i18n, type Language } from './i18n'; import { appName, gitConfig, releaseUrl } from './shared'; @@ -30,10 +31,14 @@ export function baseOptions(lang: Language): BaseLayoutProps { text: labels.docs, url: `${prefix}/docs`, }, - { - text: labels.blog, - url: `${prefix}/blog`, - }, + ...(blogSource.getPages(lang).length > 0 + ? [ + { + text: labels.blog, + url: `${prefix}/blog`, + }, + ] + : []), { text: labels.download, url: releaseUrl,