feat(docs): enhance documentation site with internationalization and layout updates

- Updated the demo API to support locale-based content rendering.
- Refactored the main layout to accommodate language-specific metadata and routing.
- Introduced new components for blog and documentation pages, ensuring proper language handling.
- Added styles for improved UI consistency across different sections.
- Removed deprecated layout files and streamlined the structure for better maintainability.
This commit is contained in:
leookun
2026-08-28 00:35:31 +08:00
parent 6c758f2b44
commit eca063e424
55 changed files with 6700 additions and 407 deletions
@@ -0,0 +1,37 @@
---
title: Why We Built a New Documentation Site
description: Bringing the user guide and development notes back into the repository so docs evolve with the product.
---
cursor-byok has grown from simple model forwarding into multi-protocol model configuration, tool calling, session observability, and a cross-platform desktop app. Information scattered across release notes and discussion threads is no longer enough for first-time users, and it makes it harder for developers to understand the system's boundaries.
## Documentation is part of the product
The new documentation site lives in the same repository as the application code:
```text
apps/
├── desktop/ # Desktop app
└── docs/ # Documentation site
├── content/docs/
└── content/blog/
```
The user guide answers "how do I use it", while the developer blog records "why it is designed this way". The two kinds of content are maintained separately but share the same build and review pipeline.
## Why Fumadocs
Fumadocs provides the documentation layout, full-text search, code highlighting, table of contents, and the MDX content layer. We only need to maintain product information and visual styling instead of reimplementing generic documentation features.
The docs app stays independent: the desktop app does not take on Next.js or Fumadocs dependencies, and development, builds, and deployments remain separate.
## What we will write about
The developer blog will keep covering:
- Cursor protocol adaptation and model compatibility design.
- Trade-offs in Agent tool calling and multi-turn conversations.
- Local storage, observability, and performance work.
- Cross-platform desktop development and the release process.
These posts describe the current code. We do not keep compatibility notes for implementations that have been removed.
+93
View File
@@ -0,0 +1,93 @@
---
title: Quick Start
description: Install cursor-byok and let Cursor use your own model APIs.
icon: Rocket
---
cursor-byok is a Cursor model gateway that runs on your machine. It receives Cursor Agent requests, converts them, and forwards them to the OpenAI- or Anthropic-compatible service you configure.
<Callout type="warn" title="Before you start">
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.
</Callout>
## Install and configure
<Steps>
<Step>
### Update Cursor
Download the latest official Cursor from [cursor.com](https://cursor.com) and install it over your existing copy, so the client stays up to date.
</Step>
<Step>
### Download and launch cursor-byok
Download the latest release for your operating system from [GitHub Releases](https://github.com/leookun/cursor-byok/releases/latest), then launch cursor-byok.
</Step>
<Step>
### Initialize and configure a model
Open **Cursor Configuration**, follow the prompts to initialize the local CA, then add a model. Fill in the server address, API key, and model name, and run the connectivity test until it passes.
![Cursor Configuration page](/images/docs/cursor-config-en.png)
See [Model Configuration](./model-configuration.mdx) for how to choose the type and protocol for different models.
</Step>
<Step>
### Restart Cursor after the first setup
After completing the configuration for the first time, quit and restart Cursor once so the model list takes effect.
</Step>
<Step>
### Use it in Cursor
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.
</Step>
</Steps>
## Coexists with your official account
The current design goal is coexistence with the official service — there is no more "stop the service" or account juggling:
- Sign in to Cursor with your own account. If you previously used a fake account generated by an old version, sign out of it first, then sign in with your own.
- If your account has official quota, there is no boundary between official models and your local models — switch and mix freely.
- **Auto always routes to official models**: picking Auto without quota results in an error, so select your configured model instead.
- Cursor features such as plugins and codebase indexing keep working as usual.
## Next steps
<Cards>
<Card title="Installation" description="Download, initialize, and run for the first time." href="/docs/installation" />
<Card title="Model Configuration" description="Choose a protocol and fill in upstream model parameters." href="/docs/model-configuration" />
<Card title="TAB Service" description="Choose how Cursor connects to Tab completion endpoints." href="/docs/tab-service" />
<Card title="Troubleshooting" description="Resolve certificate, connection, and model test issues." href="/docs/troubleshooting" />
</Cards>
## How data flows
```text
Cursor client
│ Agent requests and tool results
▼
cursor-byok local service
│ OpenAI- / Anthropic-compatible requests
▼
Your model API
```
API keys, model configurations, and app settings are stored on your machine. Model requests are still sent to the upstream provider you choose.
+34 -5
View File
@@ -10,13 +10,21 @@ cursor-byok 是运行在本机的 Cursor 模型网关。它接收 Cursor Agent
cursor-byok 是独立开源项目,与 Cursor 及其开发者没有关联。软件本身免费,但模型服务商可能按用量收费。
</Callout>
## 三步开始使用
## 安装与配置
<Steps>
<Step>
### 下载并启动
### 更新 Cursor
从 [cursor.com](https://cursor.com) 下载官方最新版 Cursor,直接覆盖安装,保持客户端为最新版本。
</Step>
<Step>
### 下载并启动 cursor-byok
从 [GitHub Releases](https://github.com/leookun/cursor-byok/releases/latest) 下载与你的操作系统对应的最新版本,然后启动 cursor-byok。
@@ -26,7 +34,19 @@ cursor-byok 是独立开源项目,与 Cursor 及其开发者没有关联。软
### 初始化并配置模型
打开 **Cursor 配置**,按界面提示初始化本地 CA,然后添加模型。填写服务地址、API Key 和模型名称,并运行连通性测试。
打开 **Cursor 配置**,按界面提示初始化本地 CA,然后添加模型。填写服务地址、API Key 和模型名称,并运行连通性测试,测试通过即可。
![Cursor 配置页面](/images/docs/cursor-config-zh.png)
不同模型如何选择类型与协议,见[模型配置](./model-configuration.mdx)。
</Step>
<Step>
### 首次配置后重启 Cursor
首次完成配置时,完全退出并重新启动一次 Cursor,让模型列表生效。
</Step>
@@ -34,19 +54,28 @@ cursor-byok 是独立开源项目,与 Cursor 及其开发者没有关联。软
### 在 Cursor 中使用
保持 cursor-byok 运行,打开 Cursor,在模型列表中选择刚刚配置的模型,然后开始使用 Agent。
保持 cursor-byok 运行,在 Cursor 中新开一个对话,从模型列表中选择你刚配置的模型(不要选 Auto),开始使用 Agent。
</Step>
</Steps>
## 与官方账号并存
新版的设计目标是与官方服务并存,不再需要“关服务”“切账号”之类的操作:
- 直接在 Cursor 中登录你自己的账号。如果之前用过旧版生成的 fake 账户,先退出它,再登录自己的账号。
- 账号有官方额度时,官方模型和本地模型没有使用上的边界,可以随时切换混用。
- **Auto 走的是官方模型**:账号没有额度时选 Auto 会报错,请手动选择你配置的模型。
- 插件、代码库索引等 Cursor 功能都可以正常使用。
## 接下来
<Cards>
<Card title="安装指南" description="下载、初始化和首次运行。" href="/docs/installation" />
<Card title="模型配置" description="选择协议并填写上游模型参数。" href="/docs/model-configuration" />
<Card title="TAB 服务" description="选择 Cursor Tab 补全接口的连接方式。" href="/docs/tab-service" />
<Card title="故障排查" description="处理证书、连接与模型测试问题。" href="/docs/troubleshooting" />
<Card title="查看源码" description="了解实现或参与项目开发。" href="https://github.com/leookun/cursor-byok" external />
</Cards>
## 数据如何流转
@@ -0,0 +1,68 @@
---
title: Installation
description: Download cursor-byok, complete local initialization, and verify it is running.
icon: Download
---
## Download the app
Go to the [latest release page](https://github.com/leookun/cursor-byok/releases/latest) and download the installer for macOS, Windows, or Linux.
<Callout type="info">
Prefer the latest stable release. The release page lists the installers and release notes for each version.
</Callout>
## First launch
<Steps>
<Step>
### Open Cursor Settings
After launching the app, go to **Cursor Settings**. If the local CA has not been initialized, the page shows an initialization entry.
</Step>
<Step>
### Initialize the local CA
Click **Initialize CA**. The local CA is used to inspect HTTPS requests from Cursor on your device; its files never leave your machine.
When the system asks for authorization, follow the instructions shown in the app to complete the trust step in your terminal, then return to the app and click **I have initialized, refresh**.
</Step>
<Step>
### Add your first model
Click **Add Model**, choose the OpenAI or Anthropic type, fill in the upstream service parameters, and save. See [Model Configuration](./model-configuration.mdx) for details on each field.
</Step>
<Step>
### Run the connectivity test
Click **Test** on the model. Once the test passes, the model appears in Cursor's model list.
</Step>
</Steps>
## Verify the installation
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.
- The configured display name shows up in Cursor's model list.
If any of these steps fail, head to [Troubleshooting](./troubleshooting.mdx).
## Updates
Check for new versions in the app settings, or visit [GitHub Releases](https://github.com/leookun/cursor-byok/releases/latest) directly. You do not need to delete existing model configurations before updating.
+5
View File
@@ -0,0 +1,5 @@
{
"title": "User Guide",
"root": true,
"pages": ["index", "installation", "model-configuration", "tab-service", "troubleshooting"]
}
+1 -1
View File
@@ -1,5 +1,5 @@
{
"title": "使用指南",
"root": true,
"pages": ["index", "installation", "model-configuration", "troubleshooting"]
"pages": ["index", "installation", "model-configuration", "tab-service", "troubleshooting"]
}
@@ -0,0 +1,83 @@
---
title: Model Configuration
description: Configure the model protocol, server address, credentials, and generation parameters.
icon: Settings2
---
Each model configuration is an independent upstream channel that can use a different provider, protocol, credentials, and generation parameters.
![Edit model dialog](/images/docs/model-edit-en.png)
## Choosing the type and protocol
Picking by model family avoids most compatibility issues:
| Model family | Model type | Request protocol |
| --- | --- | --- |
| Claude family | **Anthropic** | — |
| GPT / OpenAI family | **OpenAI** | **Responses API** |
| Everything else | **OpenAI** | **Chat Completions API** |
<Callout type="warn" title="Always use the Responses API for GPT models">
Running GPT models through Chat Completions loses prompt caching, which makes them noticeably slower and more expensive.
</Callout>
## Required fields
### Model type
Choose the upstream interface format:
- **OpenAI**: supports the Responses API and the Chat Completions API.
- **Anthropic**: supports Messages API-compatible services.
### Request protocol
For the OpenAI type, also choose **Responses API** or **Chat Completions API**. This option determines the request and response format; it does not change the server address you entered.
### Server address
You can enter the provider's base URL, or choose to use a full request URL:
- With a base URL, cursor-byok appends the standard endpoint path for the chosen protocol.
- With a full request URL, cursor-byok uses the address as-is.
Prefer the built-in provider presets in the UI to avoid protocol and endpoint mismatches.
### API key
Enter the access key required by the upstream service. The key is stored on your machine and used to send model requests.
### Model name
Enter the model identifier accepted by the provider's API. You can also click **Fetch Models** to load the model list returned by the API.
## Display information
- **Display name**: the name shown in Cursor's model list; it does not change the model identifier sent upstream.
- **Notes**: shown in Cursor's model description.
## Optional parameters
Fill in the following fields based on the model's capabilities; when left empty, the app or upstream defaults are used:
- Context window tokens
- Max output tokens
- Reasoning or thinking effort
- Custom headers
- Extra OpenAI or Anthropic parameters
<Callout type="warn" title="Extra parameter format">
Custom headers and extra parameters must be JSON objects. Extra parameters directly affect upstream requests, so only add fields the provider explicitly supports.
</Callout>
## Test the configuration
Run **Test** after saving. The result shows time to first token, generation speed, total duration, and the model output, which helps you confirm:
1. The address and protocol match.
2. The API key is valid.
3. The model identifier exists and is accessible.
4. The upstream returns streamed content correctly.
Once the test passes, switch to Cursor and start using the model.
@@ -6,6 +6,22 @@ icon: Settings2
每个模型配置都是一个独立的上游通道,可以使用不同服务商、协议、凭据和生成参数。
![编辑模型弹窗](/images/docs/model-edit-zh.png)
## 如何选择类型与协议
按上游模型系列选择,可以避免绝大多数兼容性问题:
| 模型系列 | 模型类型 | 请求协议 |
| --- | --- | --- |
| Claude 系列 | **Anthropic** | — |
| GPT / OpenAI 系列 | **OpenAI** | **Responses API** |
| 其他所有模型 | **OpenAI** | **Chat Completions API** |
<Callout type="warn" title="GPT 系列务必用 Responses API">
GPT 系列走 Chat Completions 会丢失提示词缓存,速度和费用都会明显变差。
</Callout>
## 必填字段
### 模型类型
+27
View File
@@ -0,0 +1,27 @@
---
title: TAB Service
description: Choose how Cursor connects to Tab completion endpoints.
icon: Zap
---
Cursor's Tab completion does not go through model channels — it is handled by a separate Tab service. cursor-byok offers three connection modes under **System settings → TAB settings**.
![TAB settings in System settings](/images/docs/tab-settings-en.png)
## The three modes
### Use public service (default)
Uses the public Tab service hosted by the project author. Works out of the box with no configuration.
### Direct
Connects directly to the official Tab service of the account signed in to your Cursor client. Suitable if your account has official quota.
### Custom
Deploy your own [cursor-tab-server](https://github.com/leookun/cursor-byok/tree/archive/v0.0.49/cursor-tab-server), then enter your service URL in **TAB service address**. The original endpoint path is appended to that address.
<Callout type="info">
After changing TAB settings, restart Cursor and start a new conversation to make sure the connection mode takes effect.
</Callout>
+27
View File
@@ -0,0 +1,27 @@
---
title: TAB 服务
description: 选择 Cursor Tab 补全接口的连接方式。
icon: Zap
---
Cursor 的 Tab 补全不走模型通道,而是由单独的 Tab 服务处理。cursor-byok 在 **系统设置 → TAB 设置** 中提供三种连接方式。
![系统设置中的 TAB 设置](/images/docs/tab-settings-zh.png)
## 三种模式
### 使用公益服务(默认)
使用由项目作者部署的公共 Tab 服务,开箱即用,无需任何配置。
### 直连
直接使用你在 Cursor 客户端中登录账号的官方 Tab 服务。适合账号本身有官方额度的用户。
### 自定义
自行部署 [cursor-tab-server](https://github.com/leookun/cursor-byok/tree/archive/v0.0.49/cursor-tab-server),然后在 **TAB 服务地址** 中填入你的服务地址。原接口路径会追加到该地址之后。
<Callout type="info">
修改 TAB 设置后,建议重启 Cursor 并新开一个对话,确保连接方式生效。
</Callout>
@@ -0,0 +1,83 @@
---
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.
+24 -3
View File
@@ -31,15 +31,36 @@ icon: Wrench
- **参数错误**:暂时关闭自定义 Headers 和额外参数,再重新测试。
- **连接超时**:检查网络、系统代理和上游服务状态。
## Cursor 中看不到模型
## Cursor 中看不到模型或模型不生效
确认以下条件全部满足:
先确认以下条件全部满足:
1. 本地 CA 状态正常。
2. 已保存至少一个模型配置。
3. 模型连通性测试成功。
4. cursor-byok 正在运行。
5. 重启 Cursor 后重新打开模型列表。
仍然不生效时,按顺序执行一遍完整的重启流程:
1. 从托盘完全退出 cursor-byok,重新启动。
2. 完全退出并重新启动 Cursor。
3. 新开一个对话,刷新模型列表。
4. 选择你自己配置的模型,**不要选 Auto**。
## 选 Auto 时报额度或账户错误
Auto 只会路由到 Cursor 官方模型,不会使用你配置的本地模型。账号没有官方额度时选 Auto 就会报错——请在模型列表中手动选择你配置的模型。
如果账号本身有额度,官方模型和本地模型可以随意混用,没有使用上的边界。
## 还在使用旧版的 fake 账户
新版的设计是与官方账号并存,不再需要 fake 账户,也没有“关服务”之类的操作:
1. 在 Cursor 中退出旧版生成的 fake 账户。
2. 登录你自己的 Cursor 账号。
登录自己的账号后,插件、代码库索引等 Cursor 功能都可以正常使用。
## 请求失败但测试成功