mirror of
https://wget.la/https://github.com/leookun/cursor-byok
synced 2026-10-06 21:52:51 +08:00
feat(docs): add documentation site and demo features
- Introduced a new documentation site for Cursor BYOK using Next.js and Fumadocs. - Added a product demo page with a corresponding Vite configuration. - Implemented a demo API to simulate LLM calls and responses. - Enhanced the Makefile to include new build and development commands for the documentation. - Updated package.json scripts for building and running the documentation site. - Created various components and layouts for the documentation structure, including blog and user documentation sections. - Added styling for the new components and layouts to ensure a cohesive design. - Included a README and other necessary files for local development and deployment.
This commit is contained in:
leokun
@@ -0,0 +1,37 @@
|
||||
---
|
||||
title: 为什么我们建立新的文档站
|
||||
description: 将用户指南和开发过程放回代码仓库，让文档与产品一起演进。
|
||||
---
|
||||
|
||||
cursor-byok 的功能已经从单一模型转发扩展到多协议模型配置、工具调用、会话观测和跨平台桌面应用。散落在发布说明与讨论区中的信息，已经不足以支持第一次使用产品的人，也不利于开发者理解系统边界。
|
||||
|
||||
## 文档也是产品的一部分
|
||||
|
||||
新的文档站与应用代码放在同一个仓库中：
|
||||
|
||||
```text
|
||||
apps/
|
||||
├── desktop/ # 桌面应用
|
||||
└── docs/ # 文档站
|
||||
├── content/docs/
|
||||
└── content/blog/
|
||||
```
|
||||
|
||||
用户文档负责回答“如何使用”，开发者博客负责记录“为什么这样设计”。两类内容分开维护，但使用同一套构建和审查流程。
|
||||
|
||||
## 为什么选择 Fumadocs
|
||||
|
||||
Fumadocs 提供了文档布局、全文搜索、代码高亮、目录和 MDX 内容层，我们只需要维护产品信息与视觉样式，不必重新实现通用文档能力。
|
||||
|
||||
文档应用保持独立，桌面端不会引入 Next.js 或 Fumadocs 依赖。开发、构建和部署也可以分别进行。
|
||||
|
||||
## 接下来会记录什么
|
||||
|
||||
开发者博客将持续记录：
|
||||
|
||||
- Cursor 协议适配与模型兼容性设计。
|
||||
- Agent 工具调用和多轮会话的实现取舍。
|
||||
- 本地存储、可观测性与性能优化。
|
||||
- 桌面端跨平台开发和发布过程。
|
||||
|
||||
这些文章以当前代码为准，不为已经删除的旧实现保留兼容说明。
|
||||
@@ -0,0 +1,64 @@
|
||||
---
|
||||
title: 快速开始
|
||||
description: 安装 cursor-byok，并让 Cursor 使用你自己的模型 API。
|
||||
icon: Rocket
|
||||
---
|
||||
|
||||
cursor-byok 是运行在本机的 Cursor 模型网关。它接收 Cursor Agent 请求，将请求转换后发送到你配置的 OpenAI 或 Anthropic 兼容服务。
|
||||
|
||||
<Callout type="warn" title="使用前须知">
|
||||
cursor-byok 是独立开源项目，与 Cursor 及其开发者没有关联。软件本身免费，但模型服务商可能按用量收费。
|
||||
</Callout>
|
||||
|
||||
## 三步开始使用
|
||||
|
||||
<Steps>
|
||||
|
||||
<Step>
|
||||
|
||||
### 下载并启动
|
||||
|
||||
从 [GitHub Releases](https://github.com/leookun/cursor-byok/releases/latest) 下载与你的操作系统对应的最新版本，然后启动 cursor-byok。
|
||||
|
||||
</Step>
|
||||
|
||||
<Step>
|
||||
|
||||
### 初始化并配置模型
|
||||
|
||||
打开 **Cursor 配置**，按界面提示初始化本地 CA，然后添加模型。填写服务地址、API Key 和模型名称，并运行连通性测试。
|
||||
|
||||
</Step>
|
||||
|
||||
<Step>
|
||||
|
||||
### 在 Cursor 中使用
|
||||
|
||||
保持 cursor-byok 运行，打开 Cursor，在模型列表中选择刚刚配置的模型，然后开始使用 Agent。
|
||||
|
||||
</Step>
|
||||
|
||||
</Steps>
|
||||
|
||||
## 接下来
|
||||
|
||||
<Cards>
|
||||
<Card title="安装指南" description="下载、初始化和首次运行。" href="/docs/installation" />
|
||||
<Card title="模型配置" description="选择协议并填写上游模型参数。" href="/docs/model-configuration" />
|
||||
<Card title="故障排查" description="处理证书、连接与模型测试问题。" href="/docs/troubleshooting" />
|
||||
<Card title="查看源码" description="了解实现或参与项目开发。" href="https://github.com/leookun/cursor-byok" external />
|
||||
</Cards>
|
||||
|
||||
## 数据如何流转
|
||||
|
||||
```text
|
||||
Cursor 客户端
|
||||
│ Agent 请求与工具结果
|
||||
▼
|
||||
cursor-byok 本地服务
|
||||
│ OpenAI / Anthropic 兼容请求
|
||||
▼
|
||||
你配置的模型 API
|
||||
```
|
||||
|
||||
API Key、模型配置和应用设置保存在本机。模型请求仍会发送到你选择的上游服务商。
|
||||
@@ -0,0 +1,68 @@
|
||||
---
|
||||
title: 安装指南
|
||||
description: 下载 cursor-byok，完成本地初始化并验证运行状态。
|
||||
icon: Download
|
||||
---
|
||||
|
||||
## 下载应用
|
||||
|
||||
前往 [最新版本页面](https://github.com/leookun/cursor-byok/releases/latest)，下载适用于 macOS、Windows 或 Linux 的安装包。
|
||||
|
||||
<Callout type="info">
|
||||
优先使用最新正式版本。发行页面会列出该版本包含的安装包和更新说明。
|
||||
</Callout>
|
||||
|
||||
## 首次启动
|
||||
|
||||
<Steps>
|
||||
|
||||
<Step>
|
||||
|
||||
### 打开 Cursor 配置
|
||||
|
||||
启动应用后进入 **Cursor 配置**。如果本地 CA 尚未初始化，页面会显示初始化入口。
|
||||
|
||||
</Step>
|
||||
|
||||
<Step>
|
||||
|
||||
### 初始化本地 CA
|
||||
|
||||
点击 **初始化 CA**。本地 CA 用于在你的设备上解析 Cursor 发出的 HTTPS 请求，其文件只保存在本机。
|
||||
|
||||
系统要求授权时，按照应用显示的说明在终端中完成信任操作，然后返回应用点击 **我已初始化，刷新**。
|
||||
|
||||
</Step>
|
||||
|
||||
<Step>
|
||||
|
||||
### 添加第一个模型
|
||||
|
||||
点击 **添加模型**，选择 OpenAI 或 Anthropic 类型，填写上游服务参数并保存。详细字段说明见[模型配置](./model-configuration.mdx)。
|
||||
|
||||
</Step>
|
||||
|
||||
<Step>
|
||||
|
||||
### 运行连通性测试
|
||||
|
||||
点击模型的 **测试**。测试成功后，该模型即可出现在 Cursor 的模型列表中。
|
||||
|
||||
</Step>
|
||||
|
||||
</Steps>
|
||||
|
||||
## 验证安装
|
||||
|
||||
完成配置后，请确认：
|
||||
|
||||
- Cursor 配置页面不再显示 CA 初始化提示。
|
||||
- 至少一个模型的连通性测试成功。
|
||||
- cursor-byok 保持运行。
|
||||
- Cursor 模型列表中能看到配置的显示名称。
|
||||
|
||||
如果其中任何一步失败，请前往[故障排查](./troubleshooting.mdx)。
|
||||
|
||||
## 更新
|
||||
|
||||
在应用设置中检查新版本，或直接访问 [GitHub Releases](https://github.com/leookun/cursor-byok/releases/latest)。更新前无需删除现有模型配置。
|
||||
@@ -0,0 +1,5 @@
|
||||
{
|
||||
"title": "使用指南",
|
||||
"root": true,
|
||||
"pages": ["index", "installation", "model-configuration", "troubleshooting"]
|
||||
}
|
||||
@@ -0,0 +1,67 @@
|
||||
---
|
||||
title: 模型配置
|
||||
description: 配置模型协议、服务地址、凭据与生成参数。
|
||||
icon: Settings2
|
||||
---
|
||||
|
||||
每个模型配置都是一个独立的上游通道，可以使用不同服务商、协议、凭据和生成参数。
|
||||
|
||||
## 必填字段
|
||||
|
||||
### 模型类型
|
||||
|
||||
选择上游接口格式：
|
||||
|
||||
- **OpenAI**：支持 Responses API 和 Chat Completions API。
|
||||
- **Anthropic**：支持 Messages API 兼容服务。
|
||||
|
||||
### 请求协议
|
||||
|
||||
OpenAI 类型需要继续选择 **Responses API** 或 **Chat Completions API**。该选项决定请求和响应格式，不会单独改变你填写的服务地址。
|
||||
|
||||
### 服务器地址
|
||||
|
||||
可以填写服务商的基础地址，也可以选择使用完整请求 URL：
|
||||
|
||||
- 使用基础地址时，cursor-byok 会根据协议追加标准端点路径。
|
||||
- 使用完整请求 URL 时，cursor-byok 会原样使用该地址。
|
||||
|
||||
优先使用界面中的常用服务商预设，减少协议与端点不匹配的情况。
|
||||
|
||||
### API Key
|
||||
|
||||
填写上游服务要求的访问密钥。密钥保存在本机，用于发送模型请求。
|
||||
|
||||
### 模型名称
|
||||
|
||||
填写服务商接口接受的模型标识。你也可以点击 **获取模型** 读取接口返回的模型列表。
|
||||
|
||||
## 展示信息
|
||||
|
||||
- **显示名称**：Cursor 模型列表中看到的名称，不会改变发送给上游的模型标识。
|
||||
- **备注**：显示在 Cursor 的模型说明中。
|
||||
|
||||
## 可选参数
|
||||
|
||||
按模型能力填写以下字段；留空时使用应用或上游的默认值：
|
||||
|
||||
- 上下文窗口 Token
|
||||
- 最大输出 Token
|
||||
- 推理强度或思考强度
|
||||
- 自定义 Headers
|
||||
- OpenAI 或 Anthropic 额外参数
|
||||
|
||||
<Callout type="warn" title="额外参数格式">
|
||||
自定义 Headers 和额外参数必须是 JSON 对象。额外参数会直接影响上游请求，只添加服务商明确支持的字段。
|
||||
</Callout>
|
||||
|
||||
## 测试配置
|
||||
|
||||
保存后运行 **测试**。结果会显示首字延迟、生成速度、总耗时和模型输出，便于确认：
|
||||
|
||||
1. 地址和协议是否匹配。
|
||||
2. API Key 是否有效。
|
||||
3. 模型标识是否存在且可访问。
|
||||
4. 上游是否能正常返回流式内容。
|
||||
|
||||
测试通过后再前往 Cursor 使用该模型。
|
||||
@@ -0,0 +1,62 @@
|
||||
---
|
||||
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 正在运行。
|
||||
5. 重启 Cursor 后重新打开模型列表。
|
||||
|
||||
## 请求失败但测试成功
|
||||
|
||||
模型测试只验证基础连接。Agent 请求还会包含更长上下文、工具定义和流式响应。请检查：
|
||||
|
||||
- 上游模型是否支持工具调用。
|
||||
- 上下文窗口和最大输出 Token 是否符合模型限制。
|
||||
- 自定义参数是否与实际协议兼容。
|
||||
- 调用详情中的上游状态码和响应内容。
|
||||
|
||||
## 继续反馈
|
||||
|
||||
如果问题仍然存在，请在 [GitHub Issues](https://github.com/leookun/cursor-byok/issues) 提交问题，并附上：
|
||||
|
||||
- 操作系统与 cursor-byok 版本。
|
||||
- 选择的模型类型和请求协议。
|
||||
- 已脱敏的服务地址与错误信息。
|
||||
- 复现步骤。
|
||||
|
||||
请勿公开 API Key 或其他凭据。
|
||||
Reference in New Issue
Block a user