feat(desktop): embed BoosAPI Desktop client as a subproject
Vendor the rebranded BoosAPI Desktop client (Tauri + Vue) into metapi as a monorepo subdirectory under desktop/. Source only — node_modules, dist, Cargo target and the upstream .git history are excluded. desktop/ keeps its own independent Cargo workspace (desktop/src-tauri with crates/*); it is not part of the backend boosapi crate, so a `cargo check` at the metapi root still compiles only the backend. Build the desktop app from desktop/src-tauri per desktop/README.md. Note: app icons are still placeholder assets pending the final BoosAPI logo. The updater signing keys live outside the repo and are not included.
This commit is contained in:
boos
@@ -0,0 +1,204 @@
|
||||
# API 网关
|
||||
|
||||
## 什么是 API 网关？
|
||||
|
||||
BoosApi 内置了一个本地 API 网关服务器，可以将你在 BoosApi 中配置的 AI 服务商统一暴露为标准 API 接口。其他工具和客户端（如 Claude Code、Codex CLI、Cursor 等）可以通过这个网关访问你的所有模型，无需为每个工具分别配置 API 密钥。
|
||||
|
||||
网关支持以下兼容格式：
|
||||
|
||||
- **OpenAI 兼容** — `/v1/chat/completions`
|
||||
- **Claude 原生** — Anthropic API 格式
|
||||
- **Gemini 原生** — Google AI API 格式
|
||||
|
||||
::: tip 使用场景
|
||||
如果你已经在 BoosApi 中配置了多个服务商和密钥，API 网关可以让其他开发工具直接复用这些配置，省去重复配置的麻烦。同时，网关提供统一的用量统计和访问控制。
|
||||
:::
|
||||
|
||||
## 快速上手
|
||||
|
||||
### 启用网关
|
||||
|
||||
1. 进入 **设置 → API 网关**
|
||||
2. 开启网关开关
|
||||
3. 配置监听参数：
|
||||
- **端口** — 网关监听的端口号，默认 `8080`
|
||||
- **主机** — 监听地址，默认 `127.0.0.1`（仅本机访问）
|
||||
|
||||
::: warning 网络安全
|
||||
如果将主机设置为 `0.0.0.0`，网关将对所有网络接口开放。请确保你了解其安全风险，并配合 API 密钥和防火墙使用。
|
||||
:::
|
||||
|
||||
### 测试连通性
|
||||
|
||||
网关启动后，可以用 `curl` 快速验证：
|
||||
|
||||
```bash
|
||||
curl http://127.0.0.1:8080/v1/models \
|
||||
-H "Authorization: Bearer your-gateway-api-key"
|
||||
```
|
||||
|
||||
如果返回了模型列表，说明网关运行正常。
|
||||
|
||||
## API 密钥管理
|
||||
|
||||
网关使用独立的 API 密钥体系来控制访问权限。
|
||||
|
||||
### 生成新密钥
|
||||
|
||||
1. 在 **API 网关** 页面中找到 **密钥管理** 区域
|
||||
2. 点击 **生成密钥**
|
||||
3. 为密钥添加描述备注（如 "Claude Code 专用"、"团队共享"）
|
||||
4. 复制并妥善保存生成的密钥
|
||||
|
||||
::: danger 密钥安全
|
||||
密钥仅在创建时完整显示一次。请立即复制保存，之后只能看到密钥前缀。
|
||||
:::
|
||||
|
||||
### 撤销 / 停用密钥
|
||||
|
||||
- **停用** — 暂时禁用密钥，可随时重新启用
|
||||
- **删除** — 永久撤销密钥，使用该密钥的所有客户端将立即失去访问权限
|
||||
|
||||
### 描述备注
|
||||
|
||||
为每个密钥添加描述可以帮助你管理多个客户端的访问。例如区分不同工具或团队成员使用的密钥。
|
||||
|
||||
## SSL/TLS
|
||||
|
||||
网关支持 HTTPS 加密通信，部分工具（如 Claude Code）要求使用 HTTPS 连接。
|
||||
|
||||
### 自动自签名证书
|
||||
|
||||
启用 SSL 后，BoosApi 会自动生成自签名证书，无需手动操作。证书文件存储在：
|
||||
|
||||
```
|
||||
~/.boosapi/ssl/
|
||||
├── cert.pem # 自签名证书
|
||||
└── key.pem # 私钥（Unix 系统权限 0600）
|
||||
```
|
||||
|
||||
### 自定义证书
|
||||
|
||||
如果你有自己的 SSL 证书（如 Let's Encrypt 签发的证书），可以在网关设置中指定证书和私钥的路径。
|
||||
|
||||
### 配置选项
|
||||
|
||||
| 选项 | 说明 |
|
||||
|------|------|
|
||||
| 启用 SSL | 是否开启 HTTPS |
|
||||
| SSL 端口 | HTTPS 监听端口 |
|
||||
| 证书路径 | cert.pem 文件路径 |
|
||||
| 私钥路径 | key.pem 文件路径 |
|
||||
| 强制 SSL | 是否将所有 HTTP 请求重定向到 HTTPS |
|
||||
|
||||
::: info 自签名证书信任
|
||||
使用自签名证书时，客户端可能会报告证书不受信任的警告。大部分 CLI 工具可以通过设置环境变量来跳过证书验证（见下方配置模板）。
|
||||
:::
|
||||
|
||||
## 用量统计
|
||||
|
||||
网关提供详细的用量统计面板，帮助你了解 API 的使用情况。
|
||||
|
||||
### 请求量面板
|
||||
|
||||
实时显示网关处理的请求总量、成功率和错误率。
|
||||
|
||||
### Token 用量
|
||||
|
||||
按不同维度查看 Token 消耗：
|
||||
|
||||
- **按密钥** — 每个 API 密钥使用了多少 Token
|
||||
- **按服务商** — 每个后端服务商处理了多少请求和 Token
|
||||
- **按日期** — 每日的 Token 使用趋势
|
||||
|
||||
::: tip
|
||||
通过用量统计，你可以了解哪个工具消耗最多资源，合理分配 API 配额。
|
||||
:::
|
||||
|
||||
## 请求日志
|
||||
|
||||
网关记录所有经过它的 API 请求，方便调试和审计。
|
||||
|
||||
每条日志包含以下信息：
|
||||
|
||||
| 字段 | 说明 |
|
||||
|------|------|
|
||||
| 时间 | 请求的时间戳 |
|
||||
| 方法 | HTTP 方法（GET、POST 等） |
|
||||
| 路径 | 请求路径 |
|
||||
| 模型 | 请求使用的模型 |
|
||||
| 服务商 | 转发到的后端服务商 |
|
||||
| 状态码 | HTTP 响应状态码 |
|
||||
| Token | 输入/输出 Token 数量 |
|
||||
| 延迟 | 请求处理耗时 |
|
||||
|
||||
支持按时间范围、状态码、模型等条件过滤日志。
|
||||
|
||||
## 配置模板
|
||||
|
||||
BoosApi 内置了常见开发工具的配置模板，帮助你快速接入。以下是一些常用工具的配置方式：
|
||||
|
||||
### Claude Code CLI
|
||||
|
||||
```bash
|
||||
export ANTHROPIC_BASE_URL=https://127.0.0.1:8443
|
||||
export ANTHROPIC_API_KEY=your-gateway-api-key
|
||||
export NODE_TLS_REJECT_UNAUTHORIZED=0
|
||||
|
||||
claude
|
||||
```
|
||||
|
||||
::: tip
|
||||
`NODE_TLS_REJECT_UNAUTHORIZED=0` 用于跳过自签名证书验证。如果你使用了受信任的证书，可以移除此设置。
|
||||
:::
|
||||
|
||||
### OpenAI Codex CLI
|
||||
|
||||
```bash
|
||||
export OPENAI_BASE_URL=http://127.0.0.1:8080/v1
|
||||
export OPENAI_API_KEY=your-gateway-api-key
|
||||
|
||||
codex
|
||||
```
|
||||
|
||||
### OpenCode
|
||||
|
||||
```bash
|
||||
export OPENAI_BASE_URL=http://127.0.0.1:8080/v1
|
||||
export OPENAI_API_KEY=your-gateway-api-key
|
||||
|
||||
opencode
|
||||
```
|
||||
|
||||
### Gemini CLI
|
||||
|
||||
```bash
|
||||
export GEMINI_API_KEY=your-gateway-api-key
|
||||
export GEMINI_BASE_URL=http://127.0.0.1:8080
|
||||
|
||||
gemini
|
||||
```
|
||||
|
||||
### 自定义客户端
|
||||
|
||||
对于任何支持 OpenAI 兼容 API 的客户端，使用以下配置：
|
||||
|
||||
- **Base URL**: `http://127.0.0.1:8080/v1`
|
||||
- **API Key**: 你的网关 API 密钥
|
||||
- **模型**: 通过 `/v1/models` 接口查询可用模型
|
||||
|
||||
## 接入外部工具
|
||||
|
||||
除 CLI 工具外，许多图形化工具也支持自定义 API 端点。通用配置方式：
|
||||
|
||||
1. 在工具的设置中找到 API 配置或自定义端点选项
|
||||
2. 将 Base URL 设置为 BoosApi 网关地址
|
||||
3. 将 API Key 设置为网关密钥
|
||||
4. 保存后即可使用 BoosApi 配置的所有模型
|
||||
|
||||
::: tip 统一管理的优势
|
||||
通过 API 网关统一管理，你可以：
|
||||
- 在 BoosApi 中集中管理所有服务商密钥，其他工具只需一个网关密钥
|
||||
- 在用量统计中查看所有工具的使用情况
|
||||
- 利用多密钥轮询提高可靠性
|
||||
:::
|
||||
@@ -0,0 +1,212 @@
|
||||
# 快速开始
|
||||
|
||||
本指南将帮助你在几分钟内完成 BoosApi 的安装、配置和首次对话。
|
||||
|
||||
## 安装
|
||||
|
||||
前往 [下载页面](/zh/download) 获取最新安装包，选择与你系统匹配的版本。
|
||||
|
||||
### macOS
|
||||
|
||||
BoosApi 提供两种架构的 `.dmg` 安装包：
|
||||
|
||||
- **Apple Silicon**（M1/M2/M3/M4）— `BoosApi_x.x.x_aarch64.dmg`
|
||||
- **Intel** — `BoosApi_x.x.x_x64.dmg`
|
||||
|
||||
下载后双击 `.dmg` 文件，将 BoosApi 拖入「应用程序」文件夹即可。
|
||||
|
||||
::: warning macOS 安全提示
|
||||
由于 BoosApi 尚未进行 Apple 公证签名，首次打开时系统可能弹出以下提示：
|
||||
|
||||
- **"BoosApi 已损坏，无法打开"** 或 **"无法验证开发者"**
|
||||
|
||||
请在终端中执行以下命令后重新打开：
|
||||
|
||||
```bash
|
||||
xattr -cr /Applications/BoosApi.app
|
||||
```
|
||||
|
||||
该命令会移除系统添加的隔离属性，不会影响应用本身。
|
||||
:::
|
||||
|
||||
### Windows
|
||||
|
||||
- **x64** — `BoosApi_x.x.x_x64-setup.exe`
|
||||
- **ARM64** — `BoosApi_x.x.x_arm64-setup.exe`
|
||||
|
||||
双击安装程序并按照向导完成安装。系统要求 Windows 10（1803）或更高版本。
|
||||
|
||||
### Linux
|
||||
|
||||
根据你的发行版和架构选择：
|
||||
|
||||
| 格式 | 架构 | 适用场景 |
|
||||
|------|------|---------|
|
||||
| `.deb` | amd64 / arm64 | Debian、Ubuntu 及其衍生版 |
|
||||
| `.rpm` | x86_64 / aarch64 | Fedora、openSUSE 等 |
|
||||
| `.AppImage` | x86_64 / aarch64 | 任意发行版，无需安装 |
|
||||
|
||||
`.deb` 安装示例：
|
||||
|
||||
```bash
|
||||
sudo dpkg -i BoosApi_x.x.x_amd64.deb
|
||||
```
|
||||
|
||||
`.AppImage` 需要先赋予执行权限：
|
||||
|
||||
```bash
|
||||
chmod +x BoosApi_x.x.x_amd64.AppImage
|
||||
./BoosApi_x.x.x_amd64.AppImage
|
||||
```
|
||||
|
||||
## 首次配置
|
||||
|
||||
安装完成后，按照以下步骤完成初始配置。
|
||||
|
||||
### 1. 进入设置
|
||||
|
||||
启动 BoosApi 后，点击左侧边栏底部的齿轮图标进入 **设置** 页面。
|
||||
|
||||
### 2. 添加服务商
|
||||
|
||||
进入 **设置 → 服务商**，点击左下角的 **+** 按钮添加一个服务商。以 OpenAI 为例：
|
||||
|
||||
1. 输入服务商名称，如 `OpenAI`
|
||||
2. 选择服务商类型为 **OpenAI**
|
||||
3. 填入你的 **API Key**
|
||||
4. **Base URL** 保持默认 `https://api.openai.com`，若使用第三方中转服务则填写其地址
|
||||
|
||||
::: tip 获取 API Key
|
||||
前往 [OpenAI API Keys](https://platform.openai.com/api-keys) 页面创建密钥。其他服务商的密钥获取方式请参考各自官方文档。
|
||||
:::
|
||||
|
||||
### 3. 获取模型
|
||||
|
||||
服务商添加完成后，点击 **获取模型** 按钮，BoosApi 会自动从 API 拉取可用模型列表。你也可以在模型 ID 输入框中手动添加模型。
|
||||
|
||||
### 4. 配置默认模型
|
||||
|
||||
进入 **设置 → 默认模型**，选择你最常用的模型作为默认助手模型和话题命名模型。新建对话时将自动使用默认模型。
|
||||
|
||||
## 开始第一次对话
|
||||
|
||||
### 新建对话
|
||||
|
||||
点击左侧边栏顶部的 **新建对话** 按钮，或使用快捷键 `Cmd/Ctrl+N`。
|
||||
|
||||
### 选择模型
|
||||
|
||||
在对话顶部的模型选择器中选取你想使用的模型。如果你已经设置了默认模型，会自动填充。
|
||||
|
||||
### 发送消息
|
||||
|
||||
在底部输入框中输入你的问题，按 `Enter` 发送。BoosApi 使用流式输出，你会看到模型的回答逐字呈现。
|
||||
|
||||
::: info 关于 Thinking 块
|
||||
部分模型（如 Claude、DeepSeek R1）支持输出推理过程。当模型包含 thinking 块时，BoosApi 会将其折叠显示，点击即可展开查看完整推理链。
|
||||
:::
|
||||
|
||||
## 核心概念
|
||||
|
||||
### 对话分支
|
||||
|
||||
BoosApi 支持对话分支功能。当你在某条消息基础上重新生成或编辑提问时，系统会创建一个新的分支而非覆盖原内容。你可以随时在不同分支之间切换，对比不同的对话走向。
|
||||
|
||||
### 消息版本
|
||||
|
||||
每条消息可以拥有多个版本。重新生成助手回复时，新版本会自动添加到同一消息位置。通过消息旁的左右箭头可以在版本间快速切换。
|
||||
|
||||
### 上下文挂载
|
||||
|
||||
在对话中，你可以通过附件功能挂载额外的上下文信息：
|
||||
|
||||
- **文件** — 上传图片或文档作为对话上下文
|
||||
- **搜索** — 关联本地知识库搜索结果
|
||||
- **工具** — 启用 MCP 工具让模型调用外部能力
|
||||
|
||||
## 快捷键
|
||||
|
||||
BoosApi 内置了一套常用快捷键，提升操作效率：
|
||||
|
||||
| 快捷键 | 功能 |
|
||||
|-------|------|
|
||||
| `CmdOrCtrl+Shift+A` | 显示/隐藏当前窗口 |
|
||||
| `CmdOrCtrl+Shift+Z` | 显示/隐藏所有窗口 |
|
||||
| `Cmd/Ctrl+N` | 新建对话 |
|
||||
| `Cmd/Ctrl+,` | 打开设置 |
|
||||
| `Cmd/Ctrl+F` | 搜索对话 |
|
||||
|
||||
::: tip 自定义快捷键
|
||||
以上快捷键均可在 **设置 → 快捷键** 中自定义修改，包括全局快捷键和应用内快捷键。
|
||||
:::
|
||||
|
||||
## 桌面设置
|
||||
|
||||
在 **设置** 中可以调整各项桌面偏好：
|
||||
|
||||
### 外观
|
||||
|
||||
- **主题** — 支持深色、浅色和跟随系统三种模式
|
||||
- **主题色** — 从 12 种预设色中选择，也支持自定义颜色
|
||||
- **字体** — 可调整字体大小（12–20px）、字重和字体家族
|
||||
|
||||
### 语言
|
||||
|
||||
支持简体中文和英文界面切换，在 **设置 → 通用** 中修改。
|
||||
|
||||
### 系统行为
|
||||
|
||||
- **系统托盘** — 关闭窗口后保持在系统托盘运行
|
||||
- **开机自启** — 设置系统登录时自动启动 BoosApi
|
||||
- **窗口置顶** — 将 BoosApi 窗口始终置于最前
|
||||
|
||||
### 代理配置
|
||||
|
||||
如果你需要通过代理访问 API，在 **设置 → 代理** 中配置：
|
||||
|
||||
- **代理类型** — 支持 HTTP 和 SOCKS5
|
||||
- **代理地址** — 代理服务器的 IP 或域名
|
||||
- **代理端口** — 默认为 7890
|
||||
|
||||
配置完成后可以点击 **测试** 按钮验证连通性，会显示延迟结果。
|
||||
|
||||
## 数据与备份
|
||||
|
||||
### 数据目录
|
||||
|
||||
BoosApi 使用两个目录分别存储不同类型的数据：
|
||||
|
||||
| 目录 | 用途 |
|
||||
|------|------|
|
||||
| `~/.boosapi/` | 应用状态：数据库、加密密钥、向量数据库、SSL 证书 |
|
||||
| `~/Documents/boosapi/` | 用户文件：图片、文档附件、备份 |
|
||||
|
||||
### 自动备份
|
||||
|
||||
在 **设置 → 备份** 中开启自动备份。支持三种备份目标：
|
||||
|
||||
- **本地** — 默认保存到 `~/Documents/boosapi/backups/`
|
||||
- **WebDAV** — 同步到支持 WebDAV 的网盘（如坚果云）
|
||||
|
||||
可配置备份间隔（小时）和保留的最大备份数量。
|
||||
|
||||
### 手动备份与恢复
|
||||
|
||||
随时可以通过 **设置 → 备份** 手动触发完整备份。恢复时选择备份文件即可还原所有数据。
|
||||
|
||||
### 对话导出
|
||||
|
||||
在对话页面中，可以将当前对话导出为多种格式：
|
||||
|
||||
- **PNG** — 长图截图，适合分享
|
||||
- **Markdown** — 结构化文本，方便二次编辑
|
||||
- **纯文本** — 简洁格式
|
||||
- **JSON** — 包含完整元数据，方便程序处理
|
||||
|
||||
## 下一步
|
||||
|
||||
基础配置完成后，你可以继续探索 BoosApi 的进阶功能：
|
||||
|
||||
- [配置服务商](./providers) — 多服务商、多密钥、自定义端点
|
||||
- [MCP 服务器](./mcp) — 连接外部工具扩展 AI 能力
|
||||
- [API 网关](./gateway) — 将 BoosApi 作为 API 代理服务器
|
||||
@@ -0,0 +1,199 @@
|
||||
# MCP 服务器
|
||||
|
||||
## 什么是 MCP？
|
||||
|
||||
[Model Context Protocol（MCP）](https://modelcontextprotocol.io/)是一种开放协议，让 AI 模型能够与外部工具和数据源交互。通过 MCP，模型可以在对话中调用文件操作、网页抓取、数据库查询等各种工具，大幅扩展 AI 的实际能力。
|
||||
|
||||
BoosApi 内置了 MCP 客户端，你可以连接各种 MCP 服务器来为 AI 对话增加工具调用能力。
|
||||
|
||||
## 传输协议
|
||||
|
||||
BoosApi 支持三种 MCP 传输协议，适用于不同的部署场景：
|
||||
|
||||
| 协议 | 连接方式 | 适用场景 | 配置参数 |
|
||||
|------|---------|---------|---------|
|
||||
| **Stdio** | 本地子进程 | 通过 `npx`、`uvx`、自定义命令启动的本地工具 | `command` + `args` |
|
||||
| **SSE** | Server-Sent Events | 远程托管的 MCP 服务器 | `url` |
|
||||
| **StreamableHTTP** | HTTP 流式传输 | 远程 HTTP 服务器，支持双向流 | `url` |
|
||||
|
||||
::: info Stdio vs 远程
|
||||
大部分 MCP 服务器以 Stdio 模式运行——BoosApi 在本地启动一个进程并通过标准输入/输出通信。如果你连接的是远程部署的服务器，则使用 SSE 或 StreamableHTTP 协议。
|
||||
:::
|
||||
|
||||
## 添加 MCP 服务器
|
||||
|
||||
### 表单创建
|
||||
|
||||
1. 进入 **设置 → MCP 服务器**
|
||||
2. 点击 **添加 MCP 服务器**
|
||||
3. 填写基本信息：
|
||||
- **名称** — 为服务器取一个易识别的名称
|
||||
- **传输协议** — 选择 Stdio、SSE 或 StreamableHTTP
|
||||
4. 根据所选协议填写相应配置：
|
||||
- **Stdio**：填写启动命令（如 `npx`、`uvx`）和参数
|
||||
- **SSE / StreamableHTTP**：填写服务器 URL
|
||||
5. 保存后 BoosApi 会自动连接并获取可用工具列表
|
||||
|
||||
### JSON 导入
|
||||
|
||||
如果你有现成的 MCP 配置（如从其他工具导出），可以直接粘贴 JSON 快速导入。BoosApi 支持标准的 `mcpServers` 配置格式。
|
||||
|
||||
#### Stdio 协议格式
|
||||
|
||||
```json
|
||||
{
|
||||
"mcpServers": {
|
||||
"my-tool": {
|
||||
"command": "npx",
|
||||
"args": ["-y", "@some/mcp-server"],
|
||||
"env": {
|
||||
"API_KEY": "your-key"
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
#### SSE 协议格式
|
||||
|
||||
```json
|
||||
{
|
||||
"mcpServers": {
|
||||
"remote-server": {
|
||||
"type": "sse",
|
||||
"url": "https://example.com/sse"
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
#### StreamableHTTP 协议格式
|
||||
|
||||
```json
|
||||
{
|
||||
"mcpServers": {
|
||||
"http-server": {
|
||||
"type": "streamablehttp",
|
||||
"url": "https://example.com/mcp"
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
::: tip 批量导入
|
||||
你可以在一个 JSON 中包含多个服务器，BoosApi 会一次性全部导入。
|
||||
:::
|
||||
|
||||
## 配置示例
|
||||
|
||||
以下是一些常用 MCP 服务器的配置示例。
|
||||
|
||||
### 网页抓取 — mcp-server-fetch
|
||||
|
||||
使用 `uvx` 启动网页抓取工具，让 AI 能够读取网页内容：
|
||||
|
||||
```json
|
||||
{
|
||||
"mcpServers": {
|
||||
"fetch": {
|
||||
"command": "uvx",
|
||||
"args": ["mcp-server-fetch"]
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### 文件系统操作 — filesystem server
|
||||
|
||||
使用 `npx` 启动文件系统服务器，允许 AI 读写指定目录的文件：
|
||||
|
||||
```json
|
||||
{
|
||||
"mcpServers": {
|
||||
"filesystem": {
|
||||
"command": "npx",
|
||||
"args": [
|
||||
"-y",
|
||||
"@modelcontextprotocol/server-filesystem",
|
||||
"/Users/你的用户名/Documents"
|
||||
]
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
::: warning 安全提示
|
||||
文件系统服务器会授予 AI 对指定目录的读写权限。请只暴露必要的目录路径，避免将根目录或敏感目录暴露给模型。
|
||||
:::
|
||||
|
||||
### 远程 SSE 服务器
|
||||
|
||||
连接远程部署的 MCP 服务器：
|
||||
|
||||
```json
|
||||
{
|
||||
"mcpServers": {
|
||||
"remote-tools": {
|
||||
"type": "sse",
|
||||
"url": "https://mcp.example.com/sse"
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### 自定义 Stdio 服务器（带环境变量）
|
||||
|
||||
运行自定义的 MCP 服务器，通过环境变量传递配置：
|
||||
|
||||
```json
|
||||
{
|
||||
"mcpServers": {
|
||||
"custom-tool": {
|
||||
"command": "python",
|
||||
"args": ["/path/to/your/server.py"],
|
||||
"env": {
|
||||
"DATABASE_URL": "postgres://localhost:5432/mydb",
|
||||
"API_TOKEN": "your-token"
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## 内置工具
|
||||
|
||||
BoosApi 开箱即用地提供了一些内置 MCP 工具服务器，无需额外安装：
|
||||
|
||||
### @boosapi/fetch — 网页抓取
|
||||
|
||||
| 工具 | 说明 |
|
||||
|------|------|
|
||||
| `fetch_url` | 抓取指定 URL 的页面内容，提取文本 |
|
||||
| `fetch_markdown` | 抓取指定 URL 并转换为 Markdown 格式 |
|
||||
|
||||
### @boosapi/search-file — 文件操作
|
||||
|
||||
| 工具 | 说明 |
|
||||
|------|------|
|
||||
| `read_file` | 读取指定路径的文件内容 |
|
||||
| `list_directory` | 列出指定目录下的文件和文件夹 |
|
||||
| `search_files` | 按模式搜索匹配的文件 |
|
||||
|
||||
::: tip
|
||||
内置工具服务器在 MCP 服务器列表中默认显示，可以直接在对话中启用使用，无需任何额外配置。
|
||||
:::
|
||||
|
||||
## 工具循环上限
|
||||
|
||||
在 设置 -> 对话 中，MCP 工具调用最大轮次 用于限制单次回复中模型连续调用工具的轮数。较低数值可减少耗时和成本，较高数值适合更长的自动化工具流程。
|
||||
|
||||
## 工具执行面板
|
||||
|
||||
当模型在对话中调用 MCP 工具时，BoosApi 会在消息中显示工具执行面板，其中包含：
|
||||
|
||||
- **工具名称** — 被调用的工具和所属服务器
|
||||
- **输入参数** — 模型传给工具的参数
|
||||
- **执行状态** — 等待确认、执行中、已完成或失败
|
||||
- **返回结果** — 工具执行后返回的数据
|
||||
|
||||
点击面板可以展开查看完整的输入和输出信息，方便调试和了解 AI 的工具使用行为。
|
||||
@@ -0,0 +1,243 @@
|
||||
# 配置服务商
|
||||
|
||||
BoosApi 支持接入多种 AI 服务商，你可以同时配置多个服务商并在对话中自由切换。
|
||||
|
||||
## 支持的服务商
|
||||
|
||||
BoosApi 内置以下服务商类型，并支持任何兼容 OpenAI API 格式的自定义端点：
|
||||
|
||||
| 服务商 | 代表模型 | 说明 |
|
||||
|-------|---------|------|
|
||||
| **OpenAI** | GPT-4o、GPT-4、o3、o4-mini | 最广泛支持的 API 格式 |
|
||||
| **Anthropic** | Claude 4 Sonnet/Opus、Claude 3.5 Sonnet | 原生 Claude API |
|
||||
| **Google** | Gemini 2.5 Pro/Flash、Gemini 2.0 | Google AI Studio 或 Vertex |
|
||||
| **DeepSeek** | DeepSeek-V3、DeepSeek-R1 | 高性价比推理模型 |
|
||||
| **阿里云通义千问** | Qwen-Max、Qwen-Plus、Qwen-Turbo | 兼容 OpenAI 格式 |
|
||||
| **智谱 GLM** | GLM-4、GLM-4-Flash | 国产大模型 |
|
||||
| **xAI** | Grok-3、Grok-3-mini | xAI 出品 |
|
||||
| **OpenAI 兼容** | 任意模型 | 适配所有兼容 OpenAI 格式的第三方服务 |
|
||||
|
||||
## 添加服务商
|
||||
|
||||
### 基本步骤
|
||||
|
||||
1. 进入 **设置 → 服务商**
|
||||
2. 点击左下角的 **+** 按钮
|
||||
3. 填写以下信息：
|
||||
- **名称** — 自定义名称，用于在界面中区分不同服务商
|
||||
- **类型** — 选择对应的服务商类型（如 OpenAI、Anthropic 等）
|
||||
- **图标** — 可选，为服务商选择一个显示图标
|
||||
4. 点击确认创建
|
||||
|
||||
### 配置 API
|
||||
|
||||
创建服务商后，需要填写 API 连接信息：
|
||||
|
||||
#### API 密钥
|
||||
|
||||
填入从服务商处获取的 API Key。例如 OpenAI 的密钥格式为 `sk-...`。
|
||||
|
||||
::: tip 密钥安全
|
||||
BoosApi 使用 AES-256 加密存储所有 API 密钥，密钥数据保存在本地 `~/.boosapi/boosapi.db` 中，不会上传到任何外部服务器。
|
||||
:::
|
||||
|
||||
#### Base URL
|
||||
|
||||
API 的基础地址。各服务商的官方地址：
|
||||
|
||||
| 服务商 | 官方 Base URL |
|
||||
|-------|--------------|
|
||||
| OpenAI | `https://api.openai.com` |
|
||||
| Anthropic | `https://api.anthropic.com` |
|
||||
| Google | `https://generativelanguage.googleapis.com` |
|
||||
| DeepSeek | `https://api.deepseek.com` |
|
||||
| 阿里云通义 | `https://dashscope.aliyuncs.com/compatible-mode` |
|
||||
| 智谱 GLM | `https://open.bigmodel.cn` |
|
||||
| xAI | `https://api.x.ai` |
|
||||
|
||||
如果你使用第三方中转服务或自建代理，将 Base URL 替换为中转地址即可。
|
||||
|
||||
#### API 路径
|
||||
|
||||
API 请求的路径部分，默认为 `/v1/chat/completions`。一般情况下无需修改，除非服务商使用了非标准路径。
|
||||
|
||||
## 从网页链接导入服务商
|
||||
|
||||
服务商官网、中转服务后台、私有模型平台或本地网关页面，可以提供一个 **在 BoosApi 中打开** 的链接。用户点击后，浏览器会拉起 BoosApi 桌面端，BoosApi 会进入 **设置 → 服务商**，弹出确认框，并在用户确认后导入服务商配置。
|
||||
|
||||
### 用户使用流程
|
||||
|
||||
1. 安装并打开支持服务商链接导入的 BoosApi 版本。
|
||||
2. 在浏览器中点击服务商页面提供的 **在 BoosApi 中打开** 链接。
|
||||
3. 在 BoosApi 确认框中检查服务商名称、Base URL、服务商类型和 API Key 前缀。
|
||||
4. 点击确认后，BoosApi 会按 **Base URL + 类型** 复用已有服务商；如果不存在则新建服务商，并在密钥不存在时追加 API Key。
|
||||
|
||||
BoosApi 不会自动验证 API Key，也不会自动同步模型列表。导入后你可以点击 **获取模型**，或手动添加模型 ID。
|
||||
|
||||
### 链接格式
|
||||
|
||||
```text
|
||||
boosapi://providers?name=<name>&baseurl=<base-url>&apikey=<api-key>&type=<provider-type>
|
||||
```
|
||||
|
||||
示例：
|
||||
|
||||
```text
|
||||
boosapi://providers?name=OpenAI&baseurl=https%3A%2F%2Fapi.openai.com&apikey=sk-xxx&type=openai
|
||||
```
|
||||
|
||||
### 参数说明
|
||||
|
||||
| 参数 | 必填 | 说明 |
|
||||
|------|------|------|
|
||||
| `name` | 是 | 服务商显示名称，例如 `OpenAI`、`我的中转服务` |
|
||||
| `baseurl` | 是 | 服务商 Base URL，需要 URL 编码；仅允许 `http` / `https`，不允许 query 或 hash |
|
||||
| `apikey` | 是 | 要保存到 BoosApi 的 API Key；确认框只展示前缀，不展示完整密钥 |
|
||||
| `type` | 是 | 服务商类型；可选值：`openai`、`openai_responses`、`anthropic`、`gemini`、`custom` |
|
||||
|
||||
`baseurl` 支持 BoosApi 既有的强制后缀语义，例如 `https://example.com!`。通过链接导入时不会设置 `api_path`，BoosApi 会继续按所选服务商类型使用默认路径逻辑。
|
||||
|
||||
### 官网/后台页面如何配置链接
|
||||
|
||||
对所有动态值使用 `encodeURIComponent` 或 `URLSearchParams` 进行编码：
|
||||
|
||||
```html
|
||||
<a id="open-boosapi" href="#">在 BoosApi 中打开</a>
|
||||
|
||||
<script>
|
||||
const provider = {
|
||||
name: '我的中转服务',
|
||||
baseurl: 'https://api.example.com',
|
||||
apikey: 'sk-user-key',
|
||||
type: 'openai',
|
||||
};
|
||||
|
||||
const params = new URLSearchParams({
|
||||
name: provider.name,
|
||||
baseurl: provider.baseurl,
|
||||
apikey: provider.apikey,
|
||||
type: provider.type,
|
||||
});
|
||||
|
||||
document.getElementById('open-boosapi').href = `boosapi://providers?${params.toString()}`;
|
||||
</script>
|
||||
```
|
||||
|
||||
如果你的服务支持在线生成 API Key，建议只在用户登录后、并且明确选择或创建密钥后再生成这个链接。
|
||||
|
||||
::: warning 安全提醒
|
||||
URL 中携带 API Key 可能被浏览器历史、日志、浏览器扩展或统计脚本记录。不要把真实密钥写在公开页面、静态 HTML 或第三方跳转链接中；推荐在用户私有后台页面中按需生成，并让用户主动点击。
|
||||
:::
|
||||
|
||||
::: tip 测试提示
|
||||
`boosapi://` 是桌面应用注册到系统的自定义协议。仅运行官网或 Vite 开发服务不会注册协议；如果点击后没有拉起 BoosApi，请先安装或重新构建最新 BoosApi 桌面端。
|
||||
:::
|
||||
|
||||
## 从 CC Switch 导入
|
||||
|
||||
在 设置 -> 服务商 中，BoosApi 可以扫描 CC Switch 的服务商配置。你可以逐条检查候选项，选择可导入记录后，把服务商、Base URL、API Key 和模型列表导入 BoosApi。OAuth-only 或没有可复用密钥的记录会被跳过并显示原因。
|
||||
|
||||
## 高级模型请求体
|
||||
|
||||
每个模型都可以配置 extra_body，这是一个 JSON 对象，会平铺追加到 OpenAI 兼容 Chat Completions 请求体中。它适合 enable_thinking 等厂商私有参数。BoosApi 会校验 JSON，并阻止覆盖 model、messages、stream、tools 和基础采样字段。
|
||||
|
||||
## 多密钥轮询
|
||||
|
||||
BoosApi 支持为同一个服务商配置多个 API 密钥，实现自动轮换：
|
||||
|
||||
### 添加多个密钥
|
||||
|
||||
在服务商配置页面的 API 密钥区域，可以添加多个密钥。所有密钥共享同一个 Base URL 和配置。
|
||||
|
||||
### 自动轮换机制
|
||||
|
||||
当配置了多个密钥时，BoosApi 会在每次请求时自动轮换使用不同的密钥。
|
||||
|
||||
### 限流分散
|
||||
|
||||
多密钥轮询的一个重要用途是分散 API 限流。每个密钥有独立的速率配额，使用多个密钥可以有效提高整体吞吐量，降低单个密钥触发限流的概率。
|
||||
|
||||
::: tip 适用场景
|
||||
如果你有团队共享的多个 API 密钥，或者单个密钥的速率限制无法满足需求，多密钥轮询是一个简单高效的解决方案。
|
||||
:::
|
||||
|
||||
## 模型管理
|
||||
|
||||
### 远程拉取模型列表
|
||||
|
||||
点击 **获取模型** 按钮，BoosApi 会调用服务商的模型列表 API，自动拉取当前可用的全部模型。拉取后的模型会显示在列表中供你选择。
|
||||
|
||||
### 手动添加模型
|
||||
|
||||
如果服务商的模型列表 API 不完整或你需要添加特定模型，可以手动输入模型 ID 进行添加。例如：
|
||||
|
||||
- `gpt-4o`
|
||||
- `claude-sonnet-4-20250514`
|
||||
- `gemini-2.5-pro`
|
||||
|
||||
### 模型参数
|
||||
|
||||
每个模型可以独立配置以下默认参数：
|
||||
|
||||
| 参数 | 说明 | 典型范围 |
|
||||
|-----|------|---------|
|
||||
| **温度 (Temperature)** | 控制输出的随机性，值越高越有创意 | 0 – 2 |
|
||||
| **最大 Token (Max Tokens)** | 限制单次回复的最大长度 | 1 – 模型上限 |
|
||||
| **Top-P** | 核采样概率阈值，与温度配合使用 | 0 – 1 |
|
||||
| **频率惩罚 (Frequency Penalty)** | 降低已出现词汇的重复概率 | -2 – 2 |
|
||||
| **存在惩罚 (Presence Penalty)** | 鼓励模型讨论新话题 | -2 – 2 |
|
||||
|
||||
::: info 参数建议
|
||||
对于日常对话，保持默认参数即可。如果需要更有创意的输出，可以适当提高温度；需要精确回答时，降低温度到 0–0.3。
|
||||
:::
|
||||
|
||||
## 自定义/本地端点
|
||||
|
||||
BoosApi 支持连接任何兼容 OpenAI API 格式的服务，以下是常见场景的配置示例。
|
||||
|
||||
### Ollama
|
||||
|
||||
[Ollama](https://ollama.ai/) 可以在本地运行开源大模型。配置方法：
|
||||
|
||||
1. 添加服务商，类型选择 **OpenAI**
|
||||
2. Base URL 填写 `http://localhost:11434`
|
||||
3. API Key 留空或填写任意值
|
||||
4. 点击 **获取模型** 拉取本地已下载的模型
|
||||
|
||||
::: warning 注意
|
||||
请确保 Ollama 服务已启动。部分 Ollama 版本可能需要设置 `OLLAMA_ORIGINS=*` 环境变量以允许跨域请求。
|
||||
:::
|
||||
|
||||
### vLLM / TGI
|
||||
|
||||
如果你使用 vLLM 或 Text Generation Inference 部署了自己的模型：
|
||||
|
||||
1. 添加服务商，类型选择 **OpenAI**
|
||||
2. Base URL 填写你的部署地址，如 `http://your-server:8000`
|
||||
3. API Key 根据你的服务配置填写
|
||||
4. 手动添加你部署的模型 ID
|
||||
|
||||
### API 中转服务
|
||||
|
||||
很多第三方提供 OpenAI 兼容的 API 中转服务，配置方法相同：
|
||||
|
||||
1. 添加服务商，类型选择 **OpenAI**
|
||||
2. Base URL 填写中转服务提供的地址
|
||||
3. API Key 填写中转服务提供的密钥
|
||||
4. 获取或手动添加模型
|
||||
|
||||
## 默认模型设置
|
||||
|
||||
BoosApi 支持为不同用途设置默认模型，在 **设置 → 默认模型** 中配置：
|
||||
|
||||
### 全局默认助手模型
|
||||
|
||||
新建对话时自动使用的模型。建议选择你最常用的模型，例如 `gpt-4o` 或 `claude-sonnet-4-20250514`。
|
||||
|
||||
### 默认话题命名模型
|
||||
|
||||
用于自动为对话生成标题的模型。这个模型不需要很强大，选择一个响应快且便宜的模型即可，如 `gpt-4o-mini` 或 `gemini-2.0-flash`。
|
||||
|
||||
::: tip
|
||||
默认模型设置是可选的。如果不设置，每次新建对话时需要手动选择模型。
|
||||
:::
|
||||
Reference in New Issue
Block a user