opensource/proxycast
3
0
Fork 0
mirror of https://github.com/aiclientproxy/proxycast.git synced 2026-09-24 23:10:56 +08:00
Code Issues Packages Projects Releases Wiki Activity

feat: add documentation system with Docus framework

Browse Source 
- Add complete documentation structure with 25+ markdown files
- Add introduction, user guide, provider configs, API reference
- Add troubleshooting and development guides
- Add disclaimer for legal use
- Add GitHub Actions workflow for auto-deploying docs to GitHub Pages
- Bump version to v0.11.0
This commit is contained in:
coso
2025-12-17 13:10:58 +08:00
parent 117085e597
commit 267bbf75e3
40 changed files with 4879 additions and 4 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/app.config.ts
+41
View File
@@ -0,0 +1,41 @@
export default {
docus: {
title: "ProxyCast",
description: "把你的 AI 客户端额度用到任何地方",
url: "https://aiclientproxy.github.io/proxycast",
image: "/images/logo-banner.svg",
socials: {
github: "aiclientproxy/proxycast",
},
header: {
logo: true,
title: "ProxyCast",
showLinkIcon: true,
},
aside: {
level: 0,
collapsed: false,
exclude: [],
},
footer: {
credits: {
icon: "",
text: "Made with 💜 by ProxyCast Team",
href: "https://github.com/aiclientproxy",
},
textLinks: [
{
text: "GitHub",
href: "https://github.com/aiclientproxy/proxycast",
target: "_blank",
},
],
iconLinks: [],
},
},
};
docs/content/01.introduction/1.overview.md
+73
View File
@@ -0,0 +1,73 @@
---
title: 概述
description: ProxyCast 项目介绍和核心价值
navigation:
icon: i-heroicons-home
---
# ProxyCast 概述
ProxyCast 是一款基于 Tauri 2.0 的跨平台桌面应用，让你可以**把 AI 客户端的订阅额度用到任何地方**。
::alert{type="warning"}
**免责声明**: 本工具仅限于个人合法使用，严禁用于非法盈利目的。初衷是帮助用户充分利用已订阅的 AI 服务 Token。[查看完整声明](/legal/disclaimer)
::
## 核心价值
你是否有以下困扰？
- 订阅了 Kiro、Claude Code 等 AI 编程助手，但只能在特定 IDE 中使用
- 想在其他工具（如 Cursor、Continue、自定义脚本）中使用已有的 AI 额度
- 需要管理多个 AI 服务的凭证，频繁切换很麻烦
ProxyCast 解决这些问题：将你的 AI 客户端凭证转换为标准的 OpenAI/Claude 兼容 API，让任何支持 OpenAI 接口的工具都能使用你的订阅额度。
## 支持的 Provider
| Provider | 类型 | 认证方式 | 说明 |
|----------|------|----------|------|
| Kiro Claude | OAuth | 自动刷新 | AWS Kiro IDE 的 Claude 凭证 |
| Gemini CLI | OAuth | 自动刷新 | Google Gemini CLI 凭证 |
| Qwen (通义千问) | OAuth | 自动刷新 | 阿里云通义千问凭证 |
| OpenAI Custom | API Key | 手动配置 | 自定义 OpenAI 兼容服务 |
| Claude Custom | API Key | 手动配置 | 自定义 Claude 兼容服务 |
## 核心特性
### 🔑 凭证池管理
- 支持多个 Provider 凭证的统一管理
- 自动检测和加载本地凭证文件
- OAuth Token 自动刷新机制
### ⚖️ 智能路由
- 基于模型名称的请求路由
- 负载均衡和优先级配置
- 健康检查和自动故障转移
### 🛡️ 容错机制
- 可配置的重试策略
- 超时控制和熔断器
- 多 Provider 故障转移
### 🔄 协议转换
- OpenAI Chat Completions API 兼容
- Claude Messages API 兼容
- 自动格式转换
### 📊 监控统计
- 实时请求统计
- Token 使用追踪
- 详细的请求日志
## 使用场景
1. **IDE 集成**: 在 Cursor、Continue 等编辑器中使用 Kiro/Claude Code 额度
2. **脚本调用**: 在 Python/Node.js 脚本中调用 AI API
3. **多账户管理**: 统一管理多个 AI 服务账户
4. **团队共享**: 通过配置导出分享 Provider 设置
## 下一步
- [安装指南](/introduction/installation) - 下载并安装 ProxyCast
- [快速开始](/introduction/quickstart) - 5 分钟内完成首次 API 调用
docs/content/01.introduction/2.installation.md
+78
View File
@@ -0,0 +1,78 @@
---
title: 安装指南
description: 下载并安装 ProxyCast
navigation:
icon: i-heroicons-arrow-down-tray
---
# 安装指南
## 系统要求
| 平台 | 最低版本 | 架构 |
|------|----------|------|
| macOS | 11.0 (Big Sur) | Apple Silicon (arm64) |
| Windows | 10 | x64 |
## 下载
从 GitHub Releases 下载最新版本：
::button-link
---
to: https://github.com/aiclientproxy/proxycast/releases
target: _blank
icon: i-simple-icons-github
---
下载 ProxyCast
::
### 安装包
| 平台 | 文件名 | 说明 |
|------|--------|------|
| macOS | `ProxyCast_x.x.x_aarch64.dmg` | Apple Silicon Mac |
| Windows | `ProxyCast_x.x.x_x64-setup.exe` | Windows 64位 |
## macOS 安装
1. 下载 `.dmg` 文件
2. 双击打开 DMG 镜像
3. 将 ProxyCast 拖入 Applications 文件夹
4. 首次运行时，右键点击应用选择"打开"（绕过 Gatekeeper）
::alert{type="info"}
如果提示"无法验证开发者"，请在系统偏好设置 > 安全性与隐私中点击"仍要打开"。
::
## Windows 安装
1. 下载 `.exe` 安装程序
2. 双击运行安装程序
3. 按照安装向导完成安装
4. 从开始菜单启动 ProxyCast
## 验证安装
启动 ProxyCast 后，你应该看到：
1. 系统托盘图标出现
2. 主窗口显示仪表盘
3. 服务状态显示"已停止"（首次启动）
## 常见安装问题
### macOS: "应用已损坏"
```bash
# 移除隔离属性
xattr -cr /Applications/ProxyCast.app
```
### Windows: SmartScreen 警告
点击"更多信息" > "仍要运行"即可继续安装。
## 下一步
安装完成后，继续阅读 [快速开始](/introduction/quickstart) 配置你的第一个 Provider。
docs/content/01.introduction/3.quickstart.md
+116
View File
@@ -0,0 +1,116 @@
---
title: 快速开始
description: 5 分钟内完成首次 API 调用
navigation:
icon: i-heroicons-rocket-launch
---
# 快速开始
本指南帮助你在 5 分钟内完成 ProxyCast 的基本配置和首次 API 调用。
## 前置准备
确保你已经：
- [x] 安装了 ProxyCast
- [x] 拥有至少一个 AI 客户端的有效订阅（Kiro、Gemini CLI、Qwen 等）
## 步骤 1: 启动 ProxyCast
1. 启动 ProxyCast 应用
2. 主窗口会显示仪表盘界面
## 步骤 2: 加载凭证
ProxyCast 会自动检测本地的 AI 客户端凭证文件。
### 凭证文件位置
| Provider | 凭证路径 |
|----------|----------|
| Kiro Claude | `~/.kiro/credentials.json` |
| Gemini CLI | `~/.config/gemini-cli/oauth_creds.json` |
| Qwen | `~/.config/qwen/credentials.json` |
### 手动添加凭证
如果自动检测未找到凭证：
1. 进入 **凭证池** 页面
2. 点击 **添加凭证**
3. 选择 Provider 类型
4. 输入凭证信息或选择凭证文件
## 步骤 3: 启动 API Server
1. 在仪表盘点击 **启动服务**
2. 服务状态变为"运行中"
3. 记下 API 地址（默认 `http://127.0.0.1:9090`）
## 步骤 4: 测试 API
### 使用内置测试面板
1. 在仪表盘找到 **API 测试** 区域
2. 输入测试消息
3. 点击发送，查看响应
### 使用 curl 测试
**OpenAI 格式:**
```bash
curl http://127.0.0.1:9090/v1/chat/completions \
-H "Content-Type: application/json" \
-H "Authorization: Bearer your-api-key" \
-d '{
"model": "claude-sonnet-4-20250514",
"messages": [{"role": "user", "content": "Hello!"}]
}'
```
**Claude 格式:**
```bash
curl http://127.0.0.1:9090/v1/messages \
-H "Content-Type: application/json" \
-H "x-api-key: your-api-key" \
-H "anthropic-version: 2023-06-01" \
-d '{
"model": "claude-sonnet-4-20250514",
"max_tokens": 1024,
"messages": [{"role": "user", "content": "Hello!"}]
}'
```
## 步骤 5: 集成到其他工具
### Cursor 配置
在 Cursor 设置中配置 OpenAI API：
- API Base URL: `http://127.0.0.1:9090/v1`
- API Key: 你在 ProxyCast 中设置的 API Key
### Continue 配置
编辑 `~/.continue/config.json`:
```json
{
"models": [{
"title": "ProxyCast Claude",
"provider": "openai",
"model": "claude-sonnet-4-20250514",
"apiBase": "http://127.0.0.1:9090/v1",
"apiKey": "your-api-key"
}]
}
```
## 下一步
- [仪表盘](/user-guide/dashboard) - 了解仪表盘功能
- [凭证池](/user-guide/credential-pool) - 管理多个凭证
- [智能路由](/user-guide/smart-routing) - 配置请求路由规则
docs/content/02.user-guide/1.dashboard.md
+75
View File
@@ -0,0 +1,75 @@
---
title: 仪表盘
description: 监控和控制代理服务
navigation:
icon: i-heroicons-chart-bar
---
# 仪表盘
仪表盘是 ProxyCast 的主界面，提供服务状态监控和快速操作入口。
## 服务状态
仪表盘顶部显示当前服务状态：
| 状态 | 说明 |
|------|------|
| 🟢 运行中 | API Server 正在运行，可以接收请求 |
| 🔴 已停止 | API Server 未启动 |
| 🟡 启动中 | 服务正在初始化 |
## 控制按钮
- **启动服务**: 启动 API Server
- **停止服务**: 停止 API Server
- **重启服务**: 重新启动服务
## API 信息
服务运行时显示：
- **API 地址**: 本地 API 端点（如 `http://127.0.0.1:9090`）
- **API Key**: 当前配置的访问密钥
- **复制按钮**: 一键复制 API 地址或 Key
## API 测试面板
内置的 API 测试工具：
1. **消息输入**: 输入测试消息
2. **模型选择**: 选择要使用的模型
3. **发送请求**: 点击发送测试请求
4. **响应显示**: 查看 AI 响应结果
### 测试示例
```
用户: Hello, how are you?
助手: I'm doing well, thank you for asking! How can I help you today?
```
## 请求统计
实时统计信息：
- **总请求数**: 累计处理的请求数量
- **成功率**: 请求成功百分比
- **平均延迟**: 请求平均响应时间
- **Token 使用**: 累计 Token 消耗
## 凭证状态
显示当前可用的凭证：
| 字段 | 说明 |
|------|------|
| Provider | 凭证类型 |
| 状态 | 有效/过期/错误 |
| 剩余额度 | 可用额度（如支持） |
## 快捷操作
- **打开设置**: 进入设置页面
- **查看日志**: 打开请求日志
- **刷新凭证**: 重新加载凭证文件
docs/content/02.user-guide/10.prompts.md
+150
View File
@@ -0,0 +1,150 @@
---
title: Prompts 管理
description: 提示词存储和管理
navigation:
icon: i-heroicons-document-text
---
# Prompts 管理
Prompts 功能帮助你存储、组织和复用常用的提示词模板。
## 提示词存储
### 创建提示词
1. 进入 **Prompts** 页面
2. 点击 **新建提示词**
3. 填写提示词信息：
| 字段 | 说明 |
|------|------|
| 名称 | 提示词标识名称 |
| 描述 | 提示词用途说明 |
| 内容 | 提示词正文 |
| 标签 | 分类标签 |
### 提示词示例
```yaml
name: "代码审查"
description: "审查代码质量和最佳实践"
content: |
请审查以下代码，关注：
1. 代码质量和可读性
2. 潜在的 bug 和安全问题
3. 性能优化建议
4. 最佳实践遵循情况
请提供具体的改进建议。
tags:
- 代码
- 审查
```
## 组织方式
### 文件夹分类
创建文件夹组织提示词：
- 📁 代码相关
- 代码审查
- 代码重构
- 单元测试
- 📁 写作相关
- 文档撰写
- 邮件回复
- 📁 翻译相关
- 中英翻译
- 技术翻译
### 标签系统
使用标签快速筛选：
- `#代码` - 代码相关提示词
- `#写作` - 写作相关提示词
- `#常用` - 常用提示词
### 搜索功能
支持按以下条件搜索：
- 名称
- 描述
- 内容
- 标签
## 注入请求
### 系统提示词
将提示词作为系统消息注入：
```json
{
"model": "claude-sonnet-4-20250514",
"messages": [
{"role": "system", "content": "你是一个代码审查专家..."},
{"role": "user", "content": "请审查这段代码..."}
]
}
```
### 使用方式
1. **手动复制**: 复制提示词内容到请求
2. **快捷插入**: 在 API 测试面板选择提示词
3. **自动注入**: 配置默认系统提示词
### 配置默认提示词
1. 进入 **设置** > **API Server**
2. 选择 **默认系统提示词**
3. 所有请求自动注入该提示词
## 变量支持
### 定义变量
在提示词中使用变量：
```
请将以下 {{source_lang}} 文本翻译成 {{target_lang}}：
{{content}}
```
### 使用变量
调用时替换变量值：
```json
{
"prompt": "翻译模板",
"variables": {
"source_lang": "英文",
"target_lang": "中文",
"content": "Hello, world!"
}
}
```
## 导入导出
### 导出提示词
1. 选择要导出的提示词
2. 点击 **导出**
3. 保存为 `.json` 或 `.yaml` 文件
### 导入提示词
1. 点击 **导入**
2. 选择提示词文件
3. 确认导入
### 分享提示词
导出的提示词文件可以分享给他人使用。
docs/content/02.user-guide/11.skills.md
+171
View File
@@ -0,0 +1,171 @@
---
title: Skills 技能
description: 可扩展的技能模块系统
navigation:
icon: i-heroicons-sparkles
---
# Skills 技能
Skills 是预定义的 AI 交互模式，封装了特定任务的提示词、参数和工具配置。
## 技能定义
### 什么是技能
技能是一个完整的 AI 交互配置包，包含：
- 系统提示词
- 参数配置
- 工具绑定
- 输出格式
### 技能示例
```yaml
name: "代码解释器"
description: "解释代码功能和逻辑"
system_prompt: |
你是一个代码解释专家。请详细解释用户提供的代码：
1. 代码的整体功能
2. 关键逻辑的解释
3. 使用的设计模式
4. 潜在的改进点
parameters:
temperature: 0.3
max_tokens: 2000
output_format: markdown
```
## 创建技能
### 新建技能
1. 进入 **Skills** 页面
2. 点击 **新建技能**
3. 配置技能信息
### 配置选项
| 字段 | 说明 |
|------|------|
| 名称 | 技能标识名称 |
| 描述 | 技能用途说明 |
| 系统提示词 | 技能的核心提示词 |
| 参数 | 模型参数配置 |
| 工具 | 绑定的 MCP 工具 |
| 输出格式 | 期望的输出格式 |
## 参数配置
### 模型参数
| 参数 | 说明 | 默认值 |
|------|------|--------|
| temperature | 创造性程度 | 0.7 |
| max_tokens | 最大输出长度 | 4096 |
| top_p | 采样范围 | 1.0 |
| presence_penalty | 重复惩罚 | 0 |
### 参数模板
为不同场景预设参数：
```yaml
# 精确任务
precise:
temperature: 0.1
top_p: 0.9
# 创意任务
creative:
temperature: 0.9
top_p: 1.0
# 代码生成
coding:
temperature: 0.2
max_tokens: 8000
```
## 应用技能
### 在 API 测试中使用
1. 打开 **API 测试** 面板
2. 点击 **选择技能**
3. 选择要使用的技能
4. 输入用户消息
5. 发送请求
### 通过 API 调用
```bash
curl http://127.0.0.1:9090/v1/chat/completions \
-H "Content-Type: application/json" \
-H "Authorization: Bearer your-api-key" \
-d '{
"model": "claude-sonnet-4-20250514",
"skill": "代码解释器",
"messages": [
{"role": "user", "content": "解释这段代码: function add(a, b) { return a + b; }"}
]
}'
```
### 技能链
组合多个技能形成工作流：
```yaml
name: "代码审查流程"
steps:
- skill: "代码分析"
- skill: "安全检查"
- skill: "性能评估"
- skill: "改进建议"
```
## 内置技能
### 代码相关
| 技能 | 说明 |
|------|------|
| 代码解释 | 解释代码功能 |
| 代码审查 | 审查代码质量 |
| 代码重构 | 提供重构建议 |
| Bug 修复 | 分析和修复 bug |
### 写作相关
| 技能 | 说明 |
|------|------|
| 文档撰写 | 撰写技术文档 |
| 邮件回复 | 生成邮件回复 |
| 内容总结 | 总结长文内容 |
### 翻译相关
| 技能 | 说明 |
|------|------|
| 通用翻译 | 中英互译 |
| 技术翻译 | 技术文档翻译 |
## 技能管理
### 编辑技能
1. 点击技能的 **编辑** 按钮
2. 修改配置
3. 保存更改
### 删除技能
1. 点击 **删除** 按钮
2. 确认删除
### 导入导出
- **导出**: 将技能导出为 `.yaml` 文件
- **导入**: 从文件导入技能
docs/content/02.user-guide/12.settings.md
+141
View File
@@ -0,0 +1,141 @@
---
title: 设置
description: 应用设置和偏好管理
navigation:
icon: i-heroicons-cog-6-tooth
---
# 设置
设置页面用于配置 ProxyCast 的各项参数和偏好。
## 通用设置
### 应用行为
| 选项 | 说明 |
|------|------|
| 开机自启动 | 系统启动时自动运行 ProxyCast |
| 启动时运行服务 | 应用启动时自动启动 API Server |
| 最小化到托盘 | 关闭窗口时最小化到系统托盘 |
| 显示托盘图标 | 在系统托盘显示图标 |
### 更新设置
| 选项 | 说明 |
|------|------|
| 自动检查更新 | 定期检查新版本 |
| 自动下载更新 | 有新版本时自动下载 |
| 更新通知 | 有更新时显示通知 |
## 认证目录
### 默认凭证路径
ProxyCast 默认扫描以下路径：
| Provider | 默认路径 |
|----------|----------|
| Kiro | `~/.kiro/credentials.json` |
| Gemini CLI | `~/.config/gemini-cli/oauth_creds.json` |
| Qwen | `~/.config/qwen/credentials.json` |
### 自定义路径
添加自定义凭证扫描路径：
1. 进入 **设置** > **认证目录**
2. 点击 **添加路径**
3. 选择目录或文件
4. 指定 Provider 类型
### 路径配置
```yaml
auth_dirs:
- path: "~/.kiro"
provider: kiro
pattern: "credentials*.json"
- path: "/custom/path"
provider: gemini
pattern: "*.json"
```
## 偏好管理
### 主题设置
| 选项 | 说明 |
|------|------|
| 浅色模式 | 使用浅色主题 |
| 深色模式 | 使用深色主题 |
| 跟随系统 | 跟随系统主题设置 |
### 语言设置
支持的语言：
- 简体中文
- English
### 通知设置
| 选项 | 说明 |
|------|------|
| 服务状态通知 | 服务启动/停止时通知 |
| 错误通知 | 发生错误时通知 |
| 凭证过期通知 | 凭证即将过期时通知 |
## 数据管理
### 数据存储位置
ProxyCast 数据存储在：
| 平台 | 路径 |
|------|------|
| macOS | `~/Library/Application Support/ProxyCast` |
| Windows | `%APPDATA%\ProxyCast` |
### 清除数据
| 选项 | 说明 |
|------|------|
| 清除日志 | 删除所有请求日志 |
| 清除统计 | 重置统计数据 |
| 清除缓存 | 清除应用缓存 |
| 重置设置 | 恢复默认设置 |
::alert{type="warning"}
清除数据操作不可恢复，请谨慎操作。
::
## 高级设置
### 日志级别
| 级别 | 说明 |
|------|------|
| Error | 仅记录错误 |
| Warn | 记录警告和错误 |
| Info | 记录一般信息 |
| Debug | 记录调试信息 |
| Trace | 记录所有信息 |
### 代理设置
配置网络代理：
| 选项 | 说明 |
|------|------|
| HTTP 代理 | HTTP 代理地址 |
| HTTPS 代理 | HTTPS 代理地址 |
| 不代理地址 | 不使用代理的地址列表 |
### 性能设置
| 选项 | 默认值 | 说明 |
|------|--------|------|
| 最大并发请求 | 10 | 同时处理的最大请求数 |
| 请求队列大小 | 100 | 等待队列的最大长度 |
| 日志保留天数 | 30 | 日志文件保留时间 |
docs/content/02.user-guide/2.monitoring.md
+103
View File
@@ -0,0 +1,103 @@
---
title: 监控中心
description: 请求统计和性能监控
navigation:
icon: i-heroicons-eye
---
# 监控中心
监控中心提供详细的请求统计、性能指标和日志查看功能。
## 监控界面
### 概览面板
显示关键指标的实时数据：
- **请求总数**: 今日/本周/本月请求量
- **成功率**: 请求成功百分比
- **平均延迟**: 响应时间统计
- **活跃凭证**: 当前可用凭证数量
### 图表展示
- **请求趋势图**: 按时间显示请求量变化
- **延迟分布图**: 响应时间分布
- **Provider 使用占比**: 各 Provider 请求比例
## 请求统计
### 按 Provider 统计
| Provider | 请求数 | 成功率 | 平均延迟 |
|----------|--------|--------|----------|
| Kiro Claude | 1,234 | 99.2% | 1.2s |
| Gemini CLI | 567 | 98.5% | 0.8s |
| Qwen | 890 | 99.0% | 1.0s |
### 按模型统计
查看每个模型的使用情况：
- 请求次数
- Token 消耗
- 平均响应时间
## Token 使用追踪
### 使用量统计
| 指标 | 说明 |
|------|------|
| 输入 Token | 请求消息的 Token 数 |
| 输出 Token | 响应消息的 Token 数 |
| 总计 Token | 输入 + 输出 |
### 按时间段查看
- 今日使用量
- 本周使用量
- 本月使用量
- 自定义时间范围
## 请求日志
### 日志列表
每条日志包含：
| 字段 | 说明 |
|------|------|
| 时间 | 请求时间戳 |
| 模型 | 请求的模型名称 |
| Provider | 实际使用的 Provider |
| 状态 | 成功/失败 |
| 延迟 | 响应时间 |
| Token | Token 使用量 |
### 日志过滤
支持按以下条件过滤：
- 时间范围
- Provider
- 模型
- 状态（成功/失败）
### 日志详情
点击日志条目查看详细信息：
- 完整请求内容
- 完整响应内容
- 错误信息（如有）
- 请求头信息
## 导出数据
支持导出统计数据：
- CSV 格式
- JSON 格式
- 自定义时间范围
docs/content/02.user-guide/3.credential-pool.md
+130
View File
@@ -0,0 +1,130 @@
---
title: 凭证池
description: 管理多个 AI 服务凭证
navigation:
icon: i-heroicons-key
---
# 凭证池
凭证池用于管理多个 AI 服务凭证，支持负载均衡和故障转移。
## 池管理界面
### 凭证列表
显示所有已添加的凭证：
| 字段 | 说明 |
|------|------|
| 名称 | 凭证标识名称 |
| Provider | 凭证类型 |
| 状态 | 有效/过期/错误 |
| 优先级 | 负载均衡优先级 |
| 操作 | 编辑/删除/测试 |
### 状态指示
- 🟢 **有效**: 凭证可正常使用
- 🟡 **即将过期**: Token 即将过期，需要刷新
- 🔴 **已过期**: Token 已过期
- ⚪ **未验证**: 尚未验证凭证有效性
## 添加凭证
### 自动检测
ProxyCast 会自动检测以下位置的凭证：
```
~/.kiro/credentials.json # Kiro Claude
~/.config/gemini-cli/oauth_creds.json # Gemini CLI
~/.config/qwen/credentials.json # Qwen
```
点击 **刷新凭证** 重新扫描。
### 从文件加载
1. 点击 **添加凭证**
2. 选择 **从文件加载**
3. 选择凭证文件
4. 确认 Provider 类型
### 手动输入
1. 点击 **添加凭证**
2. 选择 **手动输入**
3. 选择 Provider 类型
4. 填写凭证信息：
**OAuth 类型 (Kiro/Gemini/Qwen):**
- Access Token
- Refresh Token
- 过期时间
**API Key 类型 (OpenAI/Claude Custom):**
- API Key
- Base URL（可选）
## 负载均衡配置
### 策略选择
| 策略 | 说明 |
|------|------|
| 轮询 (Round Robin) | 依次使用每个凭证 |
| 优先级 (Priority) | 按优先级顺序使用 |
| 随机 (Random) | 随机选择凭证 |
| 最少使用 (Least Used) | 优先使用请求数最少的凭证 |
### 优先级设置
为每个凭证设置优先级（1-100）：
- 数值越小优先级越高
- 相同优先级按策略选择
- 优先级为 0 表示禁用
### 健康检查
启用健康检查后：
- 定期验证凭证有效性
- 自动跳过失效凭证
- 凭证恢复后自动重新启用
配置选项：
| 选项 | 默认值 | 说明 |
|------|--------|------|
| 检查间隔 | 60s | 健康检查频率 |
| 失败阈值 | 3 | 连续失败次数后标记为不健康 |
| 恢复阈值 | 1 | 成功次数后恢复健康状态 |
## 凭证操作
### 测试凭证
点击 **测试** 按钮验证凭证：
1. 发送测试请求
2. 显示测试结果
3. 更新凭证状态
### 刷新 Token
对于 OAuth 凭证：
- 自动刷新：Token 过期前自动刷新
- 手动刷新：点击 **刷新** 按钮
### 删除凭证
1. 点击 **删除** 按钮
2. 确认删除操作
3. 凭证从池中移除
::alert{type="warning"}
删除凭证不会删除本地凭证文件，只是从 ProxyCast 中移除。
::
docs/content/02.user-guide/4.smart-routing.md
+142
View File
@@ -0,0 +1,142 @@
---
title: 智能路由
description: 配置请求路由规则
navigation:
icon: i-heroicons-arrows-right-left
---
# 智能路由
智能路由允许你根据模型名称将请求定向到特定的 Provider。
## 模型映射
### 映射规则
将请求中的模型名称映射到实际的 Provider 和模型：
| 请求模型 | 目标 Provider | 目标模型 |
|----------|---------------|----------|
| `gpt-4` | Kiro Claude | `claude-sonnet-4-20250514` |
| `gpt-3.5-turbo` | Gemini CLI | `gemini-2.0-flash` |
| `claude-*` | Kiro Claude | 保持原样 |
### 配置映射
1. 进入 **智能路由** 页面
2. 点击 **添加规则**
3. 配置映射：
```yaml
# 示例配置
routes:
- pattern: "gpt-4*"
provider: kiro-claude
model: claude-sonnet-4-20250514
- pattern: "gpt-3.5*"
provider: gemini-cli
model: gemini-2.0-flash
```
## 规则语法
### 模式匹配
| 模式 | 说明 | 示例 |
|------|------|------|
| `exact` | 精确匹配 | `gpt-4` 只匹配 `gpt-4` |
| `prefix*` | 前缀匹配 | `gpt-4*` 匹配 `gpt-4`, `gpt-4-turbo` |
| `*suffix` | 后缀匹配 | `*-turbo` 匹配 `gpt-4-turbo` |
| `*contains*` | 包含匹配 | `*claude*` 匹配任何包含 claude 的模型 |
### 规则字段
| 字段 | 必填 | 说明 |
|------|------|------|
| pattern | ✅ | 模型名称匹配模式 |
| provider | ✅ | 目标 Provider |
| model | ❌ | 目标模型（不填则保持原样） |
| priority | ❌ | 规则优先级（默认 100） |
| enabled | ❌ | 是否启用（默认 true） |
## 优先级排序
### 规则优先级
- 数值越小优先级越高
- 相同优先级按添加顺序
- 第一个匹配的规则生效
### 示例
```yaml
routes:
# 优先级 10：精确匹配优先
- pattern: "gpt-4-turbo"
provider: openai-custom
priority: 10
# 优先级 50：前缀匹配
- pattern: "gpt-4*"
provider: kiro-claude
priority: 50
# 优先级 100：默认规则
- pattern: "*"
provider: gemini-cli
priority: 100
```
## 默认回退
### 无规则匹配时
当请求的模型不匹配任何规则时：
1. 使用默认 Provider
2. 保持原始模型名称
3. 如果默认 Provider 不支持该模型，返回错误
### 配置默认 Provider
```yaml
default:
provider: kiro-claude
fallback: true # 启用回退
```
## Provider 选择
### 可用 Provider
| Provider | 标识 | 说明 |
|----------|------|------|
| Kiro Claude | `kiro-claude` | Kiro IDE 的 Claude |
| Gemini CLI | `gemini-cli` | Google Gemini |
| Qwen | `qwen` | 通义千问 |
| OpenAI Custom | `openai-custom` | 自定义 OpenAI |
| Claude Custom | `claude-custom` | 自定义 Claude |
### 多 Provider 负载均衡
同一规则可以指定多个 Provider：
```yaml
routes:
- pattern: "gpt-4*"
providers:
- kiro-claude
- claude-custom
strategy: round-robin
```
## 测试路由
### 路由测试工具
1. 输入模型名称
2. 点击 **测试路由**
3. 查看匹配结果：
- 匹配的规则
- 目标 Provider
- 目标模型
docs/content/02.user-guide/5.resilience.md
+145
View File
@@ -0,0 +1,145 @@
---
title: 容错配置
description: 重试、超时和故障转移设置
navigation:
icon: i-heroicons-shield-check
---
# 容错配置
容错配置帮助你的应用优雅地处理 API 故障，确保服务稳定性。
## 重试机制
### 重试配置
| 选项 | 默认值 | 说明 |
|------|--------|------|
| 最大重试次数 | 3 | 失败后重试的最大次数 |
| 初始延迟 | 1s | 首次重试前的等待时间 |
| 最大延迟 | 30s | 重试延迟的上限 |
| 退避倍数 | 2 | 每次重试延迟的增长倍数 |
### 退避策略
```
第1次重试: 1s
第2次重试: 2s
第3次重试: 4s
...
```
### 可重试错误
以下错误会触发重试：
- 网络超时
- 连接失败
- 5xx 服务器错误
- 429 速率限制
不重试的错误：
- 4xx 客户端错误（除 429）
- 认证失败
- 无效请求
## 超时设置
### 超时配置
| 选项 | 默认值 | 说明 |
|------|--------|------|
| 连接超时 | 10s | 建立连接的超时时间 |
| 请求超时 | 120s | 整个请求的超时时间 |
| 流式超时 | 300s | 流式响应的超时时间 |
### 按 Provider 配置
可以为不同 Provider 设置不同的超时：
```yaml
timeouts:
default:
connect: 10s
request: 120s
kiro-claude:
request: 180s # Claude 响应较慢
gemini-cli:
request: 60s # Gemini 响应较快
```
## 故障转移
### 自动故障转移
当主 Provider 失败时，自动切换到备用 Provider：
1. 主 Provider 请求失败
2. 检查是否有可用的备用 Provider
3. 使用备用 Provider 重试请求
4. 记录故障转移事件
### 配置故障转移
```yaml
failover:
enabled: true
providers:
- kiro-claude # 主 Provider
- claude-custom # 备用 Provider 1
- gemini-cli # 备用 Provider 2
maxAttempts: 3 # 最大尝试 Provider 数
```
### 故障转移条件
| 条件 | 说明 |
|------|------|
| 连接失败 | 无法连接到 Provider |
| 认证失败 | Token 过期或无效 |
| 速率限制 | 达到 Provider 限制 |
| 服务不可用 | Provider 返回 503 |
## 熔断器
### 熔断器状态
| 状态 | 说明 |
|------|------|
| 关闭 | 正常工作，请求通过 |
| 打开 | 熔断激活，请求直接失败 |
| 半开 | 尝试恢复，允许部分请求 |
### 熔断配置
| 选项 | 默认值 | 说明 |
|------|--------|------|
| 失败阈值 | 5 | 触发熔断的连续失败次数 |
| 恢复时间 | 30s | 熔断后尝试恢复的等待时间 |
| 半开请求数 | 3 | 半开状态允许的测试请求数 |
### 熔断流程
```
正常 → 连续失败5次 → 熔断打开
熔断打开 → 等待30s → 半开状态
半开状态 → 3次成功 → 恢复正常
半开状态 → 1次失败 → 重新熔断
```
## 监控告警
### 告警条件
- 错误率超过阈值
- 延迟超过阈值
- 熔断器打开
- 所有 Provider 不可用
### 告警通知
当前支持：
- 应用内通知
- 系统通知（macOS/Windows）
docs/content/02.user-guide/6.config-management.md
+154
View File
@@ -0,0 +1,154 @@
---
title: 配置管理
description: 导出和导入配置
navigation:
icon: i-heroicons-document-duplicate
---
# 配置管理
配置管理功能允许你导出、导入和分享 ProxyCast 配置。
## YAML 导出
### 导出内容
导出的 YAML 文件包含：
- Provider 配置
- 路由规则
- 容错设置
- API Server 配置
- 通用设置
### 导出步骤
1. 进入 **设置** > **配置管理**
2. 点击 **导出配置**
3. 选择保存位置
4. 配置保存为 `.yaml` 文件
### 导出格式
```yaml
version: "1.0"
providers:
- name: kiro-claude
type: kiro
enabled: true
priority: 1
- name: gemini-cli
type: gemini
enabled: true
priority: 2
routes:
- pattern: "gpt-4*"
provider: kiro-claude
model: claude-sonnet-4-20250514
resilience:
retry:
maxAttempts: 3
initialDelay: 1s
timeout:
request: 120s
server:
host: "127.0.0.1"
port: 9090
```
### 敏感信息处理
::alert{type="warning"}
导出的配置**不包含**凭证信息（Token、API Key）。导入后需要重新配置凭证。
::
## 导入配置
### 导入步骤
1. 进入 **设置** > **配置管理**
2. 点击 **导入配置**
3. 选择 `.yaml` 配置文件
4. 预览导入内容
5. 确认导入
### 冲突解决
当导入的配置与现有配置冲突时：
| 选项 | 说明 |
|------|------|
| 覆盖 | 用导入的配置替换现有配置 |
| 跳过 | 保留现有配置，跳过冲突项 |
| 合并 | 合并两个配置（仅适用于列表类型） |
### 验证导入
导入前会验证：
- YAML 语法正确性
- 配置版本兼容性
- 必填字段完整性
## .env 格式导出
### 用途
导出为 `.env` 格式，方便在其他工具中使用：
- 脚本调用
- Docker 环境
- CI/CD 配置
### 导出内容
```bash
# ProxyCast API Configuration
PROXYCAST_API_BASE=http://127.0.0.1:9090/v1
PROXYCAST_API_KEY=your-api-key
# OpenAI Compatible
OPENAI_API_BASE=http://127.0.0.1:9090/v1
OPENAI_API_KEY=your-api-key
# Claude Compatible
ANTHROPIC_API_BASE=http://127.0.0.1:9090
ANTHROPIC_API_KEY=your-api-key
```
### 导出步骤
1. 进入 **设置** > **配置管理**
2. 点击 **导出 .env**
3. 选择保存位置
## 配置备份
### 自动备份
ProxyCast 会自动备份配置：
- 每次修改后自动保存
- 保留最近 10 个版本
- 备份位置：`~/.proxycast/backups/`
### 恢复备份
1. 进入 **设置** > **配置管理**
2. 点击 **备份历史**
3. 选择要恢复的版本
4. 点击 **恢复**
## 配置同步
### 跨设备同步
通过导出/导入实现跨设备配置同步：
1. 在设备 A 导出配置
2. 将配置文件传输到设备 B
3. 在设备 B 导入配置
4. 重新配置凭证
docs/content/02.user-guide/7.config-switch.md
+152
View File
@@ -0,0 +1,152 @@
---
title: 配置切换
description: 快速切换 AI 客户端配置
navigation:
icon: i-heroicons-arrows-up-down
---
# 配置切换
配置切换功能让你可以一键在不同的 AI 客户端配置之间切换。
## 功能目的
当你需要在不同场景使用不同的 AI 服务时：
- 开发时使用 Kiro Claude
- 测试时使用 Gemini CLI
- 生产时使用自定义 OpenAI
配置切换让你无需手动修改配置，一键完成切换。
## 预设配置
### 内置配置档案
| 档案 | 说明 |
|------|------|
| Claude Code | 适用于 Claude Code 客户端 |
| Codex | 适用于 OpenAI Codex |
| Gemini CLI | 适用于 Gemini CLI |
### 配置内容
每个档案包含：
- 默认 Provider
- 路由规则
- 模型映射
- API 端点配置
## 创建配置档案
### 新建档案
1. 进入 **配置切换** 页面
2. 点击 **新建档案**
3. 输入档案名称
4. 配置以下内容：
```yaml
name: "我的配置"
description: "自定义配置档案"
provider: kiro-claude
routes:
- pattern: "*"
provider: kiro-claude
settings:
timeout: 120s
retry: 3
```
### 从当前配置创建
1. 配置好当前设置
2. 点击 **保存为档案**
3. 输入档案名称
4. 档案保存成功
## 切换配置
### 一键切换
1. 进入 **配置切换** 页面
2. 查看可用档案列表
3. 点击目标档案的 **应用** 按钮
4. 配置立即生效
### 快捷切换
使用标签页快速切换：
- **Claude Code** 标签
- **Codex** 标签
- **Gemini CLI** 标签
点击标签即可切换到对应配置。
## 设置活动配置
### 标记当前配置
当前使用的配置会显示 **当前使用中** 标记。
### 切换活动配置
1. 选择目标档案
2. 点击 **设为活动**
3. 该档案成为当前活动配置
## 档案管理
### 编辑档案
1. 点击档案的 **编辑** 按钮
2. 修改配置内容
3. 点击 **保存**
### 删除档案
1. 点击档案的 **删除** 按钮
2. 确认删除操作
::alert{type="warning"}
内置档案无法删除，但可以修改。
::
### 导出档案
单独导出某个档案：
1. 点击档案的 **导出** 按钮
2. 选择保存位置
3. 档案保存为 `.yaml` 文件
### 导入档案
1. 点击 **导入档案**
2. 选择 `.yaml` 文件
3. 档案添加到列表
## 使用场景
### 场景 1: 开发/测试切换
```
开发环境: 使用 Kiro Claude（免费额度）
测试环境: 使用 Gemini CLI（快速响应）
```
### 场景 2: 模型切换
```
代码生成: Claude Sonnet（高质量）
快速问答: Gemini Flash（低延迟）
```
### 场景 3: 团队协作
```
团队成员 A: 使用个人 Kiro 账户
团队成员 B: 使用共享 API Key
```
docs/content/02.user-guide/8.api-server.md
+167
View File
@@ -0,0 +1,167 @@
---
title: API Server
description: 配置和管理 API 服务
navigation:
icon: i-heroicons-server
---
# API Server
API Server 是 ProxyCast 的核心组件，提供 OpenAI/Claude 兼容的 API 端点。
## 服务器配置
### 基本配置
| 选项 | 默认值 | 说明 |
|------|--------|------|
| 主机地址 | `127.0.0.1` | 监听地址 |
| 端口 | `9090` | 监听端口 |
| API Key | 自动生成 | 访问密钥 |
### 配置步骤
1. 进入 **设置** > **API Server**
2. 修改配置选项
3. 点击 **保存**
4. 重启服务生效
### 监听地址
| 地址 | 说明 |
|------|------|
| `127.0.0.1` | 仅本机访问 |
| `0.0.0.0` | 允许局域网访问 |
::alert{type="warning"}
使用 `0.0.0.0` 时请确保配置了 API Key 认证。
::
## API 端点
### OpenAI 兼容端点
| 端点 | 方法 | 说明 |
|------|------|------|
| `/v1/chat/completions` | POST | 聊天补全 |
| `/v1/models` | GET | 模型列表 |
| `/v1/embeddings` | POST | 文本嵌入 |
### Claude 兼容端点
| 端点 | 方法 | 说明 |
|------|------|------|
| `/v1/messages` | POST | 消息 API |
| `/v1/messages/count_tokens` | POST | Token 计数 |
## 请求日志
### 日志查看
1. 进入 **监控中心**
2. 查看 **请求日志** 标签
3. 实时显示所有请求
### 日志内容
每条日志包含：
- 时间戳
- 请求方法和路径
- 请求模型
- 响应状态
- 响应时间
- Token 使用量
### 日志过滤
支持按以下条件过滤：
- 时间范围
- 状态码
- 模型名称
- Provider
## 访问控制
### API Key 认证
启用 API Key 认证：
1. 进入 **设置** > **API Server**
2. 开启 **启用认证**
3. 设置或生成 API Key
4. 保存配置
### 请求认证
请求时需要携带 API Key：
**OpenAI 格式:**
```bash
curl http://127.0.0.1:9090/v1/chat/completions \
-H "Authorization: Bearer your-api-key" \
-H "Content-Type: application/json" \
-d '{"model": "gpt-4", "messages": [...]}'
```
**Claude 格式:**
```bash
curl http://127.0.0.1:9090/v1/messages \
-H "x-api-key: your-api-key" \
-H "anthropic-version: 2023-06-01" \
-H "Content-Type: application/json" \
-d '{"model": "claude-3-sonnet", "messages": [...]}'
```
### 多 API Key
支持配置多个 API Key：
```yaml
auth:
keys:
- name: "开发环境"
key: "dev-key-xxx"
- name: "生产环境"
key: "prod-key-xxx"
```
## CORS 配置
### 跨域设置
| 选项 | 默认值 | 说明 |
|------|--------|------|
| 允许来源 | `*` | 允许的请求来源 |
| 允许方法 | `GET,POST,OPTIONS` | 允许的 HTTP 方法 |
| 允许头部 | `*` | 允许的请求头 |
### 配置示例
```yaml
cors:
origins:
- "http://localhost:3000"
- "https://myapp.com"
methods:
- GET
- POST
headers:
- Authorization
- Content-Type
```
## 服务管理
### 启动/停止
- **启动**: 点击仪表盘的 **启动服务** 按钮
- **停止**: 点击 **停止服务** 按钮
- **重启**: 点击 **重启服务** 按钮
### 开机自启
1. 进入 **设置** > **通用**
2. 开启 **开机自动启动**
3. 开启 **启动时自动运行服务**
docs/content/02.user-guide/9.mcp.md
+185
View File
@@ -0,0 +1,185 @@
---
title: MCP 服务器
description: Model Context Protocol 集成
navigation:
icon: i-heroicons-puzzle-piece
---
# MCP 服务器
MCP (Model Context Protocol) 是一种标准协议，允许 AI 模型与外部工具和数据源交互。
## MCP 概念
### 什么是 MCP
MCP 定义了 AI 模型与外部系统交互的标准方式：
- **工具调用**: AI 可以调用外部工具执行操作
- **资源访问**: AI 可以读取外部数据源
- **上下文扩展**: 为 AI 提供额外的上下文信息
### 集成优势
- 扩展 AI 能力，执行实际操作
- 访问实时数据和外部服务
- 标准化的工具接口
## 服务器配置
### 添加 MCP 服务器
1. 进入 **MCP** 页面
2. 点击 **添加服务器**
3. 配置服务器信息：
| 字段 | 说明 |
|------|------|
| 名称 | 服务器标识名称 |
| 命令 | 启动命令 |
| 参数 | 命令参数 |
| 环境变量 | 环境变量配置 |
### 配置示例
```json
{
"mcpServers": {
"filesystem": {
"command": "npx",
"args": ["-y", "@modelcontextprotocol/server-filesystem", "/path/to/dir"],
"env": {}
},
"github": {
"command": "npx",
"args": ["-y", "@modelcontextprotocol/server-github"],
"env": {
"GITHUB_TOKEN": "your-token"
}
}
}
}
```
### 连接设置
| 选项 | 说明 |
|------|------|
| 自动启动 | 应用启动时自动连接 |
| 重连间隔 | 断开后重连的等待时间 |
| 超时时间 | 连接超时设置 |
## 工具调用
### 可用工具
连接 MCP 服务器后，可以查看提供的工具：
1. 进入 **MCP** 页面
2. 选择已连接的服务器
3. 查看 **工具列表**
### 工具信息
每个工具显示：
- 工具名称
- 功能描述
- 输入参数
- 返回类型
### 调用示例
通过 API 调用 MCP 工具：
```bash
curl http://127.0.0.1:9090/v1/chat/completions \
-H "Content-Type: application/json" \
-H "Authorization: Bearer your-api-key" \
-d '{
"model": "claude-sonnet-4-20250514",
"messages": [
{"role": "user", "content": "读取 /tmp/test.txt 文件内容"}
],
"tools": [
{
"type": "function",
"function": {
"name": "read_file",
"description": "读取文件内容",
"parameters": {
"type": "object",
"properties": {
"path": {"type": "string"}
}
}
}
}
]
}'
```
## 常用 MCP 服务器
### 文件系统
```json
{
"filesystem": {
"command": "npx",
"args": ["-y", "@modelcontextprotocol/server-filesystem", "/allowed/path"]
}
}
```
### GitHub
```json
{
"github": {
"command": "npx",
"args": ["-y", "@modelcontextprotocol/server-github"],
"env": {
"GITHUB_TOKEN": "ghp_xxx"
}
}
}
```
### 数据库
```json
{
"postgres": {
"command": "npx",
"args": ["-y", "@modelcontextprotocol/server-postgres"],
"env": {
"DATABASE_URL": "postgresql://..."
}
}
}
```
## 服务器管理
### 启动/停止
- **启动**: 点击服务器的 **启动** 按钮
- **停止**: 点击 **停止** 按钮
- **重启**: 点击 **重启** 按钮
### 状态监控
| 状态 | 说明 |
|------|------|
| 🟢 已连接 | 服务器正常运行 |
| 🔴 已断开 | 服务器未连接 |
| 🟡 连接中 | 正在建立连接 |
### 日志查看
查看 MCP 服务器的运行日志：
1. 选择服务器
2. 点击 **查看日志**
3. 实时显示服务器输出
docs/content/03.providers/1.overview.md
+120
View File
@@ -0,0 +1,120 @@
---
title: Provider 概述
description: 支持的 AI 服务提供商
navigation:
icon: i-heroicons-squares-2x2
---
# Provider 概述
ProxyCast 支持多种 AI 服务提供商（Provider），每种 Provider 有不同的认证方式和特点。
## Provider 类型
### OAuth 类型
通过 OAuth 协议认证，支持自动刷新 Token：
| Provider | 说明 |
|----------|------|
| Kiro Claude | AWS Kiro IDE 的 Claude 凭证 |
| Gemini CLI | Google Gemini CLI 凭证 |
| Qwen | 阿里云通义千问凭证 |
### API Key 类型
使用 API Key 认证，需要手动配置：
| Provider | 说明 |
|----------|------|
| OpenAI Custom | 自定义 OpenAI 兼容服务 |
| Claude Custom | 自定义 Claude 兼容服务 |
## 选择指南
### 根据使用场景选择
| 场景 | 推荐 Provider |
|------|---------------|
| 已有 Kiro 订阅 | Kiro Claude |
| 已有 Google AI 订阅 | Gemini CLI |
| 已有阿里云订阅 | Qwen |
| 有 OpenAI API Key | OpenAI Custom |
| 有 Anthropic API Key | Claude Custom |
### 根据模型需求选择
| 模型系列 | Provider |
|----------|----------|
| Claude 系列 | Kiro Claude, Claude Custom |
| Gemini 系列 | Gemini CLI |
| Qwen 系列 | Qwen |
| GPT 系列 | OpenAI Custom |
## Provider 特性对比
| 特性 | Kiro | Gemini | Qwen | OpenAI Custom | Claude Custom |
|------|------|--------|------|---------------|---------------|
| 自动刷新 Token | ✅ | ✅ | ✅ | ❌ | ❌ |
| 流式响应 | ✅ | ✅ | ✅ | ✅ | ✅ |
| 工具调用 | ✅ | ✅ | ✅ | ✅ | ✅ |
| 视觉能力 | ✅ | ✅ | ✅ | ✅ | ✅ |
| 自定义 Base URL | ❌ | ❌ | ❌ | ✅ | ✅ |
## 配置流程
### OAuth Provider
1. 确保已安装对应的 AI 客户端
2. 在客户端中完成登录
3. ProxyCast 自动检测凭证文件
4. 在凭证池中确认凭证状态
### API Key Provider
1. 获取 API Key
2. 在 ProxyCast 中添加凭证
3. 配置 Base URL（如需要）
4. 测试凭证有效性
## 多 Provider 配置
### 负载均衡
配置多个 Provider 实现负载均衡：
```yaml
providers:
- name: kiro-1
type: kiro
priority: 1
- name: kiro-2
type: kiro
priority: 2
- name: gemini-backup
type: gemini
priority: 10
```
### 故障转移
主 Provider 失败时自动切换：
```yaml
failover:
enabled: true
order:
- kiro-claude
- claude-custom
- gemini-cli
```
## 下一步
选择你要配置的 Provider：
- [Kiro Claude](/providers/kiro-claude)
- [Gemini CLI](/providers/gemini-cli)
- [Qwen](/providers/qwen)
- [OpenAI Custom](/providers/openai-custom)
- [Claude Custom](/providers/claude-custom)
docs/content/03.providers/2.kiro-claude.md
+116
View File
@@ -0,0 +1,116 @@
---
title: Kiro Claude
description: 配置 Kiro IDE 的 Claude 凭证
navigation:
icon: i-heroicons-cpu-chip
---
# Kiro Claude
Kiro Claude 是 AWS Kiro IDE 提供的 Claude AI 服务凭证。
## 凭证位置
### 默认路径
Kiro 凭证文件位于：
| 平台 | 路径 |
|------|------|
| macOS | `~/.kiro/credentials.json` |
| Windows | `%USERPROFILE%\.kiro\credentials.json` |
### 凭证格式
```json
{
"accessToken": "eyJ...",
"refreshToken": "eyJ...",
"expiresAt": "2024-01-01T00:00:00Z"
}
```
## 自动刷新机制
### Token 生命周期
- Access Token 有效期：约 1 小时
- Refresh Token 有效期：约 30 天
### 自动刷新
ProxyCast 会自动处理 Token 刷新：
1. 检测 Access Token 即将过期
2. 使用 Refresh Token 获取新 Token
3. 更新本地凭证文件
4. 继续处理请求
### 刷新失败处理
如果刷新失败：
1. 标记凭证为"已过期"
2. 尝试使用其他可用凭证
3. 通知用户重新登录 Kiro
## 配置步骤
### 自动检测
1. 确保已安装 Kiro IDE
2. 在 Kiro 中完成登录
3. 启动 ProxyCast
4. 凭证自动出现在凭证池中
### 手动添加
如果自动检测失败：
1. 进入 **凭证池** 页面
2. 点击 **添加凭证**
3. 选择 **Kiro Claude**
4. 选择凭证文件或手动输入
## 支持的模型
| 模型 | 说明 |
|------|------|
| claude-sonnet-4-20250514 | Claude Sonnet 4 |
| claude-3-5-sonnet-20241022 | Claude 3.5 Sonnet |
| claude-3-5-haiku-20241022 | Claude 3.5 Haiku |
## 使用限制
### 额度限制
Kiro 订阅有使用额度限制，具体取决于订阅计划。
### 并发限制
建议单个凭证的并发请求数不超过 5。
## 故障排除
### 凭证未检测到
1. 确认 Kiro 已安装并登录
2. 检查凭证文件是否存在
3. 点击 **刷新凭证** 重新扫描
### Token 过期
1. 打开 Kiro IDE
2. 确认登录状态
3. 如需要，重新登录
4. 在 ProxyCast 中刷新凭证
### 请求失败
常见错误：
| 错误 | 原因 | 解决方案 |
|------|------|----------|
| 401 Unauthorized | Token 无效 | 刷新凭证或重新登录 |
| 429 Too Many Requests | 超出限制 | 等待或使用其他凭证 |
| 503 Service Unavailable | 服务不可用 | 稍后重试 |
docs/content/03.providers/3.gemini-cli.md
+143
View File
@@ -0,0 +1,143 @@
---
title: Gemini CLI
description: 配置 Google Gemini CLI 凭证
navigation:
icon: i-heroicons-sparkles
---
# Gemini CLI
Gemini CLI 是 Google 提供的命令行 AI 工具，使用 OAuth 认证。
## 凭证位置
### 默认路径
Gemini CLI 凭证文件位于：
| 平台 | 路径 |
|------|------|
| macOS | `~/.config/gemini-cli/oauth_creds.json` |
| Windows | `%USERPROFILE%\.config\gemini-cli\oauth_creds.json` |
| Linux | `~/.config/gemini-cli/oauth_creds.json` |
### 凭证格式
```json
{
"client_id": "...",
"client_secret": "...",
"refresh_token": "...",
"token_uri": "https://oauth2.googleapis.com/token"
}
```
## 项目设置
### Google Cloud 项目
Gemini CLI 需要关联 Google Cloud 项目：
1. 访问 [Google Cloud Console](https://console.cloud.google.com)
2. 创建或选择项目
3. 启用 Gemini API
4. 配置 OAuth 同意屏幕
### 配置项目 ID
在 ProxyCast 中配置项目：
```yaml
gemini:
project_id: "your-project-id"
location: "us-central1"
```
## 自动刷新机制
### Token 刷新
ProxyCast 自动处理 OAuth Token 刷新：
1. 使用 Refresh Token 获取 Access Token
2. Access Token 过期前自动刷新
3. 无需用户干预
### 刷新失败
如果刷新失败：
1. 检查网络连接
2. 确认 Google 账户状态
3. 重新运行 `gemini auth login`
## 配置步骤
### 安装 Gemini CLI
```bash
# 使用 npm 安装
npm install -g @anthropic-ai/gemini-cli
# 或使用 pip
pip install gemini-cli
```
### 登录认证
```bash
gemini auth login
```
按提示完成 OAuth 认证流程。
### 在 ProxyCast 中配置
1. 完成 Gemini CLI 登录
2. 启动 ProxyCast
3. 凭证自动出现在凭证池中
## 支持的模型
| 模型 | 说明 |
|------|------|
| gemini-2.0-flash | Gemini 2.0 Flash |
| gemini-1.5-pro | Gemini 1.5 Pro |
| gemini-1.5-flash | Gemini 1.5 Flash |
## 使用限制
### 免费额度
Google 提供一定的免费使用额度，超出后需要付费。
### 速率限制
| 限制类型 | 限制值 |
|----------|--------|
| 每分钟请求数 | 60 |
| 每日请求数 | 1500 |
## 故障排除
### 凭证未检测到
1. 确认已运行 `gemini auth login`
2. 检查凭证文件是否存在
3. 确认文件权限正确
### 认证失败
```bash
# 重新登录
gemini auth logout
gemini auth login
```
### 项目配置错误
确认 Google Cloud 项目：
1. 已启用 Gemini API
2. 有足够的配额
3. 账单设置正确
docs/content/03.providers/4.qwen.md
+144
View File
@@ -0,0 +1,144 @@
---
title: Qwen (通义千问)
description: 配置阿里云通义千问凭证
navigation:
icon: i-heroicons-language
---
# Qwen (通义千问)
Qwen 是阿里云提供的大语言模型服务。
## 凭证位置
### 默认路径
Qwen 凭证文件位于：
| 平台 | 路径 |
|------|------|
| macOS | `~/.config/qwen/credentials.json` |
| Windows | `%USERPROFILE%\.config\qwen\credentials.json` |
| Linux | `~/.config/qwen/credentials.json` |
### 凭证格式
```json
{
"access_token": "...",
"refresh_token": "...",
"expires_at": "2024-01-01T00:00:00Z"
}
```
## 认证设置
### 获取凭证
1. 访问 [阿里云控制台](https://www.aliyun.com)
2. 开通通义千问服务
3. 获取 API 凭证
### 使用阿里云 CLI
```bash
# 安装阿里云 CLI
pip install aliyun-cli
# 配置凭证
aliyun configure
```
### 手动配置
在 ProxyCast 中手动添加：
1. 进入 **凭证池** 页面
2. 点击 **添加凭证**
3. 选择 **Qwen**
4. 输入凭证信息
## 自动刷新
ProxyCast 支持 Qwen Token 的自动刷新：
1. 检测 Token 即将过期
2. 使用 Refresh Token 获取新 Token
3. 更新凭证文件
## 支持的模型
| 模型 | 说明 |
|------|------|
| qwen-turbo | 通义千问 Turbo |
| qwen-plus | 通义千问 Plus |
| qwen-max | 通义千问 Max |
| qwen-long | 通义千问 Long（长文本） |
## 配置选项
### 区域设置
```yaml
qwen:
region: "cn-hangzhou"
endpoint: "https://dashscope.aliyuncs.com"
```
### 模型映射
将 OpenAI 模型名映射到 Qwen：
```yaml
routes:
- pattern: "gpt-4*"
provider: qwen
model: qwen-max
- pattern: "gpt-3.5*"
provider: qwen
model: qwen-turbo
```
## 使用限制
### 并发限制
| 模型 | 并发数 |
|------|--------|
| qwen-turbo | 10 |
| qwen-plus | 5 |
| qwen-max | 3 |
### Token 限制
| 模型 | 最大 Token |
|------|-----------|
| qwen-turbo | 8K |
| qwen-plus | 32K |
| qwen-max | 32K |
| qwen-long | 1M |
## 故障排除
### 凭证无效
1. 检查阿里云账户状态
2. 确认服务已开通
3. 重新获取凭证
### 请求失败
| 错误码 | 原因 | 解决方案 |
|--------|------|----------|
| InvalidApiKey | API Key 无效 | 检查凭证配置 |
| QuotaExhausted | 配额用尽 | 充值或等待重置 |
| RateLimitExceeded | 超出速率限制 | 降低请求频率 |
### 网络问题
如果在中国大陆以外使用，可能需要配置代理：
```yaml
qwen:
proxy: "http://proxy.example.com:8080"
```
docs/content/03.providers/5.openai-custom.md
+139
View File
@@ -0,0 +1,139 @@
---
title: OpenAI Custom
description: 配置自定义 OpenAI 兼容服务
navigation:
icon: i-heroicons-cube
---
# OpenAI Custom
OpenAI Custom 允许你配置任何 OpenAI 兼容的 API 服务。
## 适用场景
- 使用 OpenAI 官方 API
- 使用 Azure OpenAI
- 使用其他 OpenAI 兼容服务（如 Groq、Together AI）
- 使用本地部署的模型（如 Ollama、vLLM）
## API Key 配置
### 获取 API Key
**OpenAI 官方:**
1. 访问 [OpenAI Platform](https://platform.openai.com)
2. 进入 API Keys 页面
3. 创建新的 API Key
**Azure OpenAI:**
1. 访问 Azure Portal
2. 创建 Azure OpenAI 资源
3. 获取 API Key 和端点
### 在 ProxyCast 中配置
1. 进入 **凭证池** 页面
2. 点击 **添加凭证**
3. 选择 **OpenAI Custom**
4. 填写配置信息：
| 字段 | 说明 |
|------|------|
| 名称 | 凭证标识名称 |
| API Key | OpenAI API Key |
| Base URL | API 端点（可选） |
## Base URL 设置
### 默认端点
不填写 Base URL 时，使用 OpenAI 官方端点：
```
https://api.openai.com/v1
```
### 自定义端点
| 服务 | Base URL |
|------|----------|
| Azure OpenAI | `https://{resource}.openai.azure.com/openai/deployments/{deployment}` |
| Groq | `https://api.groq.com/openai/v1` |
| Together AI | `https://api.together.xyz/v1` |
| Ollama | `http://localhost:11434/v1` |
### 配置示例
```yaml
providers:
- name: openai-official
type: openai-custom
api_key: "sk-..."
# 使用默认 Base URL
- name: azure-openai
type: openai-custom
api_key: "..."
base_url: "https://myresource.openai.azure.com/openai/deployments/gpt-4"
- name: ollama-local
type: openai-custom
api_key: "ollama" # Ollama 不需要真实 key
base_url: "http://localhost:11434/v1"
```
## 支持的模型
取决于你使用的服务，常见模型：
| 服务 | 模型 |
|------|------|
| OpenAI | gpt-4, gpt-4-turbo, gpt-3.5-turbo |
| Azure | 取决于部署 |
| Groq | llama-3.1-70b, mixtral-8x7b |
| Ollama | llama3, mistral, codellama |
## 高级配置
### 请求头
添加自定义请求头：
```yaml
openai-custom:
headers:
X-Custom-Header: "value"
```
### Azure 特殊配置
Azure OpenAI 需要额外配置：
```yaml
azure-openai:
api_key: "..."
base_url: "https://..."
api_version: "2024-02-15-preview"
headers:
api-key: "..." # Azure 使用 api-key 头
```
## 故障排除
### API Key 无效
1. 确认 API Key 正确
2. 检查 Key 是否过期
3. 确认账户有足够余额
### 连接失败
1. 检查 Base URL 是否正确
2. 确认网络可以访问端点
3. 检查是否需要代理
### 模型不存在
1. 确认模型名称正确
2. 检查账户是否有该模型的访问权限
3. Azure 用户确认部署名称
docs/content/03.providers/6.claude-custom.md
+172
View File
@@ -0,0 +1,172 @@
---
title: Claude Custom
description: 配置自定义 Claude 兼容服务
navigation:
icon: i-heroicons-beaker
---
# Claude Custom
Claude Custom 允许你配置 Anthropic 官方 API 或其他 Claude 兼容服务。
## 适用场景
- 使用 Anthropic 官方 API
- 使用 AWS Bedrock Claude
- 使用其他 Claude 兼容服务
## API Key 配置
### 获取 API Key
**Anthropic 官方:**
1. 访问 [Anthropic Console](https://console.anthropic.com)
2. 进入 API Keys 页面
3. 创建新的 API Key
**AWS Bedrock:**
1. 访问 AWS Console
2. 配置 Bedrock 访问权限
3. 获取 AWS 凭证
### 在 ProxyCast 中配置
1. 进入 **凭证池** 页面
2. 点击 **添加凭证**
3. 选择 **Claude Custom**
4. 填写配置信息：
| 字段 | 说明 |
|------|------|
| 名称 | 凭证标识名称 |
| API Key | Anthropic API Key |
| Base URL | API 端点（可选） |
## Base URL 设置
### 默认端点
不填写 Base URL 时，使用 Anthropic 官方端点：
```
https://api.anthropic.com
```
### 自定义端点
| 服务 | Base URL |
|------|----------|
| Anthropic 官方 | `https://api.anthropic.com` |
| AWS Bedrock | 使用 AWS SDK |
| 代理服务 | 自定义 URL |
### 配置示例
```yaml
providers:
- name: anthropic-official
type: claude-custom
api_key: "sk-ant-..."
# 使用默认 Base URL
- name: claude-proxy
type: claude-custom
api_key: "..."
base_url: "https://my-proxy.example.com"
```
## 支持的模型
| 模型 | 说明 |
|------|------|
| claude-sonnet-4-20250514 | Claude Sonnet 4 |
| claude-3-5-sonnet-20241022 | Claude 3.5 Sonnet |
| claude-3-5-haiku-20241022 | Claude 3.5 Haiku |
| claude-3-opus-20240229 | Claude 3 Opus |
## API 版本
### 版本配置
Anthropic API 需要指定版本：
```yaml
claude-custom:
api_version: "2023-06-01"
```
### 请求头
Claude API 使用特定的请求头：
```
x-api-key: your-api-key
anthropic-version: 2023-06-01
```
## AWS Bedrock 配置
### 使用 AWS 凭证
```yaml
bedrock-claude:
type: claude-custom
aws_region: "us-east-1"
aws_access_key: "..."
aws_secret_key: "..."
model_id: "anthropic.claude-3-sonnet-20240229-v1:0"
```
### IAM 角色
推荐使用 IAM 角色而非 Access Key：
1. 配置 IAM 角色
2. 授予 Bedrock 访问权限
3. ProxyCast 自动使用角色凭证
## 高级配置
### 自定义请求头
```yaml
claude-custom:
headers:
X-Custom-Header: "value"
```
### 超时设置
```yaml
claude-custom:
timeout:
connect: 10s
request: 180s # Claude 响应可能较慢
```
## 故障排除
### API Key 无效
1. 确认 API Key 正确
2. 检查 Key 是否过期
3. 确认账户状态正常
### 模型访问被拒
1. 确认账户有该模型的访问权限
2. 某些模型需要申请访问
3. 检查使用限制
### 速率限制
| 错误 | 解决方案 |
|------|----------|
| 429 Too Many Requests | 降低请求频率 |
| rate_limit_error | 等待后重试 |
### Bedrock 问题
1. 确认 AWS 凭证正确
2. 检查 IAM 权限
3. 确认区域支持 Claude
docs/content/04.api-reference/1.overview.md
+88
View File
@@ -0,0 +1,88 @@
---
title: API 概述
description: ProxyCast API 端点和认证
navigation:
icon: i-heroicons-code-bracket
---
# API 概述
ProxyCast 提供 OpenAI 和 Claude 兼容的 API 端点。
## 支持的端点
### OpenAI 兼容
| 端点 | 方法 | 说明 |
|------|------|------|
| `/v1/chat/completions` | POST | 聊天补全 |
| `/v1/models` | GET | 模型列表 |
| `/v1/embeddings` | POST | 文本嵌入 |
### Claude 兼容
| 端点 | 方法 | 说明 |
|------|------|------|
| `/v1/messages` | POST | 消息 API |
| `/v1/messages/count_tokens` | POST | Token 计数 |
## 认证方式
### OpenAI 格式
使用 `Authorization` 头：
```bash
curl http://127.0.0.1:9090/v1/chat/completions \
-H "Authorization: Bearer your-api-key" \
-H "Content-Type: application/json" \
-d '...'
```
### Claude 格式
使用 `x-api-key` 头：
```bash
curl http://127.0.0.1:9090/v1/messages \
-H "x-api-key: your-api-key" \
-H "anthropic-version: 2023-06-01" \
-H "Content-Type: application/json" \
-d '...'
```
## 基础 URL
默认地址：`http://127.0.0.1:9090`
可在设置中修改主机和端口。
## 错误响应
### 错误格式
```json
{
"error": {
"message": "错误描述",
"type": "error_type",
"code": "error_code"
}
}
```
### 常见错误码
| 状态码 | 说明 |
|--------|------|
| 400 | 请求格式错误 |
| 401 | 认证失败 |
| 404 | 端点不存在 |
| 429 | 速率限制 |
| 500 | 服务器错误 |
| 503 | 服务不可用 |
## 下一步
- [OpenAI API](/api-reference/openai-api) - OpenAI 兼容端点详情
- [Claude API](/api-reference/claude-api) - Claude 兼容端点详情
docs/content/04.api-reference/2.openai-api.md
+233
View File
@@ -0,0 +1,233 @@
---
title: OpenAI API
description: OpenAI 兼容 API 端点
navigation:
icon: i-heroicons-chat-bubble-left-right
---
# OpenAI API
ProxyCast 提供完整的 OpenAI Chat Completions API 兼容。
## /v1/chat/completions
### 请求
```bash
POST /v1/chat/completions
Content-Type: application/json
Authorization: Bearer your-api-key
```
### 请求体
```json
{
"model": "claude-sonnet-4-20250514",
"messages": [
{"role": "system", "content": "You are a helpful assistant."},
{"role": "user", "content": "Hello!"}
],
"temperature": 0.7,
"max_tokens": 1024,
"stream": false
}
```
### 参数说明
| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| model | string | ✅ | 模型名称 |
| messages | array | ✅ | 消息列表 |
| temperature | number | ❌ | 温度 (0-2) |
| max_tokens | integer | ❌ | 最大输出 Token |
| stream | boolean | ❌ | 是否流式响应 |
| top_p | number | ❌ | 采样参数 |
| presence_penalty | number | ❌ | 存在惩罚 |
| frequency_penalty | number | ❌ | 频率惩罚 |
| stop | array | ❌ | 停止序列 |
| tools | array | ❌ | 工具定义 |
| tool_choice | string/object | ❌ | 工具选择策略 |
### 消息格式
```json
{
"role": "user",
"content": "Hello!"
}
```
支持的角色：`system`, `user`, `assistant`, `tool`
### 响应
```json
{
"id": "chatcmpl-xxx",
"object": "chat.completion",
"created": 1234567890,
"model": "claude-sonnet-4-20250514",
"choices": [
{
"index": 0,
"message": {
"role": "assistant",
"content": "Hello! How can I help you today?"
},
"finish_reason": "stop"
}
],
"usage": {
"prompt_tokens": 10,
"completion_tokens": 20,
"total_tokens": 30
}
}
```
### 流式响应
设置 `stream: true` 启用流式响应：
```bash
curl http://127.0.0.1:9090/v1/chat/completions \
-H "Authorization: Bearer your-api-key" \
-H "Content-Type: application/json" \
-d '{
"model": "claude-sonnet-4-20250514",
"messages": [{"role": "user", "content": "Hello!"}],
"stream": true
}'
```
响应格式（SSE）：
```
data: {"id":"chatcmpl-xxx","choices":[{"delta":{"content":"Hello"}}]}
data: {"id":"chatcmpl-xxx","choices":[{"delta":{"content":"!"}}]}
data: [DONE]
```
## /v1/models
### 请求
```bash
GET /v1/models
Authorization: Bearer your-api-key
```
### 响应
```json
{
"object": "list",
"data": [
{
"id": "claude-sonnet-4-20250514",
"object": "model",
"created": 1234567890,
"owned_by": "anthropic"
},
{
"id": "gemini-2.0-flash",
"object": "model",
"created": 1234567890,
"owned_by": "google"
}
]
}
```
## 工具调用
### 定义工具
```json
{
"model": "claude-sonnet-4-20250514",
"messages": [{"role": "user", "content": "What's the weather in Tokyo?"}],
"tools": [
{
"type": "function",
"function": {
"name": "get_weather",
"description": "Get weather information",
"parameters": {
"type": "object",
"properties": {
"location": {"type": "string"}
},
"required": ["location"]
}
}
}
]
}
```
### 工具调用响应
```json
{
"choices": [
{
"message": {
"role": "assistant",
"tool_calls": [
{
"id": "call_xxx",
"type": "function",
"function": {
"name": "get_weather",
"arguments": "{\"location\":\"Tokyo\"}"
}
}
]
}
}
]
}
```
## 示例代码
### Python
```python
import openai
client = openai.OpenAI(
base_url="http://127.0.0.1:9090/v1",
api_key="your-api-key"
)
response = client.chat.completions.create(
model="claude-sonnet-4-20250514",
messages=[{"role": "user", "content": "Hello!"}]
)
print(response.choices[0].message.content)
```
### Node.js
```javascript
import OpenAI from 'openai';
const client = new OpenAI({
baseURL: 'http://127.0.0.1:9090/v1',
apiKey: 'your-api-key'
});
const response = await client.chat.completions.create({
model: 'claude-sonnet-4-20250514',
messages: [{ role: 'user', content: 'Hello!' }]
});
console.log(response.choices[0].message.content);
```
docs/content/04.api-reference/3.claude-api.md
+233
View File
@@ -0,0 +1,233 @@
---
title: Claude API
description: Claude 兼容 API 端点
navigation:
icon: i-heroicons-chat-bubble-bottom-center-text
---
# Claude API
ProxyCast 提供 Anthropic Claude Messages API 兼容。
## /v1/messages
### 请求
```bash
POST /v1/messages
Content-Type: application/json
x-api-key: your-api-key
anthropic-version: 2023-06-01
```
### 请求体
```json
{
"model": "claude-sonnet-4-20250514",
"max_tokens": 1024,
"messages": [
{"role": "user", "content": "Hello!"}
]
}
```
### 参数说明
| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| model | string | ✅ | 模型名称 |
| max_tokens | integer | ✅ | 最大输出 Token |
| messages | array | ✅ | 消息列表 |
| system | string | ❌ | 系统提示词 |
| temperature | number | ❌ | 温度 (0-1) |
| top_p | number | ❌ | 采样参数 |
| top_k | integer | ❌ | Top-K 采样 |
| stream | boolean | ❌ | 是否流式响应 |
| stop_sequences | array | ❌ | 停止序列 |
| tools | array | ❌ | 工具定义 |
| tool_choice | object | ❌ | 工具选择策略 |
### 消息格式
```json
{
"role": "user",
"content": "Hello!"
}
```
或带图片：
```json
{
"role": "user",
"content": [
{"type": "text", "text": "What's in this image?"},
{"type": "image", "source": {"type": "base64", "media_type": "image/png", "data": "..."}}
]
}
```
### 响应
```json
{
"id": "msg_xxx",
"type": "message",
"role": "assistant",
"content": [
{"type": "text", "text": "Hello! How can I help you today?"}
],
"model": "claude-sonnet-4-20250514",
"stop_reason": "end_turn",
"usage": {
"input_tokens": 10,
"output_tokens": 20
}
}
```
### 流式响应
设置 `stream: true` 启用流式响应：
```bash
curl http://127.0.0.1:9090/v1/messages \
-H "x-api-key: your-api-key" \
-H "anthropic-version: 2023-06-01" \
-H "Content-Type: application/json" \
-d '{
"model": "claude-sonnet-4-20250514",
"max_tokens": 1024,
"messages": [{"role": "user", "content": "Hello!"}],
"stream": true
}'
```
响应格式（SSE）：
```
event: message_start
data: {"type":"message_start","message":{"id":"msg_xxx"}}
event: content_block_start
data: {"type":"content_block_start","index":0,"content_block":{"type":"text","text":""}}
event: content_block_delta
data: {"type":"content_block_delta","index":0,"delta":{"type":"text_delta","text":"Hello"}}
event: message_stop
data: {"type":"message_stop"}
```
## /v1/messages/count_tokens
### 请求
```bash
POST /v1/messages/count_tokens
Content-Type: application/json
x-api-key: your-api-key
anthropic-version: 2023-06-01
```
### 请求体
```json
{
"model": "claude-sonnet-4-20250514",
"messages": [
{"role": "user", "content": "Hello!"}
]
}
```
### 响应
```json
{
"input_tokens": 10
}
```
## 工具调用
### 定义工具
```json
{
"model": "claude-sonnet-4-20250514",
"max_tokens": 1024,
"messages": [{"role": "user", "content": "What's the weather in Tokyo?"}],
"tools": [
{
"name": "get_weather",
"description": "Get weather information",
"input_schema": {
"type": "object",
"properties": {
"location": {"type": "string"}
},
"required": ["location"]
}
}
]
}
```
### 工具调用响应
```json
{
"content": [
{
"type": "tool_use",
"id": "toolu_xxx",
"name": "get_weather",
"input": {"location": "Tokyo"}
}
],
"stop_reason": "tool_use"
}
```
## 示例代码
### Python
```python
import anthropic
client = anthropic.Anthropic(
base_url="http://127.0.0.1:9090",
api_key="your-api-key"
)
message = client.messages.create(
model="claude-sonnet-4-20250514",
max_tokens=1024,
messages=[{"role": "user", "content": "Hello!"}]
)
print(message.content[0].text)
```
### Node.js
```javascript
import Anthropic from '@anthropic-ai/sdk';
const client = new Anthropic({
baseURL: 'http://127.0.0.1:9090',
apiKey: 'your-api-key'
});
const message = await client.messages.create({
model: 'claude-sonnet-4-20250514',
max_tokens: 1024,
messages: [{ role: 'user', content: 'Hello!' }]
});
console.log(message.content[0].text);
```
docs/content/05.troubleshooting/1.common-issues.md
+144
View File
@@ -0,0 +1,144 @@
---
title: 常见问题
description: 常见问题汇总和解决方案
navigation:
icon: i-heroicons-question-mark-circle
---
# 常见问题
本页汇总了 ProxyCast 使用中的常见问题和解决方案。
## 启动问题
### 应用无法启动
**症状**: 双击应用图标后无反应
**解决方案**:
1. **macOS**: 右键点击应用，选择"打开"
2. **Windows**: 以管理员身份运行
3. 检查系统日志查看错误信息
### 端口被占用
**症状**: 服务启动失败，提示端口已被使用
**解决方案**:
```bash
# 查找占用端口的进程
# macOS/Linux
lsof -i :9090
# Windows
netstat -ano | findstr :9090
```
或在设置中更改端口号。
## 凭证问题
### 凭证未检测到
**症状**: 凭证池为空，未显示任何凭证
**解决方案**:
1. 确认 AI 客户端已安装并登录
2. 检查凭证文件是否存在
3. 点击"刷新凭证"重新扫描
4. 手动添加凭证
详见 [凭证错误](/troubleshooting/credential-errors)
### Token 过期
**症状**: 请求返回 401 错误
**解决方案**:
1. 打开对应的 AI 客户端
2. 确认登录状态
3. 在 ProxyCast 中刷新凭证
## 连接问题
### 无法连接到 Provider
**症状**: 请求超时或连接失败
**解决方案**:
1. 检查网络连接
2. 确认 Provider 服务正常
3. 检查代理设置
详见 [连接问题](/troubleshooting/connection-issues)
### SSL 证书错误
**症状**: 提示证书验证失败
**解决方案**:
1. 检查系统时间是否正确
2. 更新系统根证书
3. 检查代理是否拦截 HTTPS
## API 问题
### 请求返回错误
**常见错误码**:
| 错误码 | 原因 | 解决方案 |
|--------|------|----------|
| 400 | 请求格式错误 | 检查请求参数 |
| 401 | 认证失败 | 检查 API Key |
| 404 | 端点不存在 | 检查 URL |
| 429 | 速率限制 | 降低请求频率 |
| 500 | 服务器错误 | 查看日志 |
### 流式响应中断
**症状**: 流式响应突然停止
**解决方案**:
1. 检查网络稳定性
2. 增加超时时间
3. 检查 Provider 状态
## 性能问题
### 响应缓慢
**可能原因**:
1. Provider 响应慢
2. 网络延迟高
3. 请求内容过长
**解决方案**:
1. 切换到更快的 Provider
2. 使用更快的模型
3. 减少请求内容长度
### 内存占用高
**解决方案**:
1. 清除请求日志
2. 减少日志保留天数
3. 重启应用
## 获取帮助
如果以上方案无法解决问题：
1. 查看应用日志
2. 在 GitHub 提交 Issue
3. 提供详细的错误信息和复现步骤
docs/content/05.troubleshooting/2.credential-errors.md
+146
View File
@@ -0,0 +1,146 @@
---
title: 凭证错误
description: OAuth Token 问题诊断
navigation:
icon: i-heroicons-key
---
# 凭证错误
本页帮助你诊断和解决凭证相关的问题。
## 诊断步骤
### 1. 检查凭证文件
确认凭证文件存在：
```bash
# Kiro
ls -la ~/.kiro/credentials.json
# Gemini CLI
ls -la ~/.config/gemini-cli/oauth_creds.json
# Qwen
ls -la ~/.config/qwen/credentials.json
```
### 2. 验证文件格式
检查 JSON 格式是否正确：
```bash
# 验证 JSON 格式
cat ~/.kiro/credentials.json | python -m json.tool
```
### 3. 检查 Token 有效性
在 ProxyCast 中：
1. 进入凭证池
2. 点击凭证的"测试"按钮
3. 查看测试结果
## 常见错误
### Token 已过期
**症状**: 凭证状态显示"已过期"
**原因**:
- Access Token 超过有效期
- Refresh Token 也已过期
**解决方案**:
1. 打开对应的 AI 客户端
2. 重新登录
3. 在 ProxyCast 中刷新凭证
### Token 无效
**症状**: 测试凭证返回 401 错误
**原因**:
- Token 被撤销
- 账户状态异常
**解决方案**:
1. 检查 AI 客户端账户状态
2. 重新登录获取新 Token
3. 删除旧凭证，重新添加
### 刷新失败
**症状**: 自动刷新 Token 失败
**原因**:
- Refresh Token 过期
- 网络问题
- 服务端问题
**解决方案**:
1. 检查网络连接
2. 手动刷新凭证
3. 如仍失败，重新登录客户端
## Provider 特定问题
### Kiro Claude
**凭证位置**: `~/.kiro/credentials.json`
**常见问题**:
1. **未安装 Kiro**: 安装 Kiro IDE
2. **未登录**: 在 Kiro 中完成登录
3. **订阅过期**: 检查 Kiro 订阅状态
### Gemini CLI
**凭证位置**: `~/.config/gemini-cli/oauth_creds.json`
**常见问题**:
1. **未安装 CLI**: 安装 Gemini CLI
2. **未认证**: 运行 `gemini auth login`
3. **项目配额用尽**: 检查 Google Cloud 配额
### Qwen
**凭证位置**: `~/.config/qwen/credentials.json`
**常见问题**:
1. **账户未开通**: 开通阿里云通义千问服务
2. **配额用尽**: 检查阿里云账户余额
3. **区域限制**: 确认服务区域设置
## 手动修复
### 重置凭证
1. 删除凭证文件
2. 重新登录 AI 客户端
3. 在 ProxyCast 中刷新凭证
### 手动添加凭证
如果自动检测失败：
1. 从 AI 客户端获取 Token
2. 在 ProxyCast 中手动添加
3. 测试凭证有效性
## 日志查看
查看详细错误信息：
1. 进入设置 > 高级
2. 设置日志级别为 Debug
3. 重现问题
4. 查看日志文件
docs/content/05.troubleshooting/3.connection-issues.md
+176
View File
@@ -0,0 +1,176 @@
---
title: 连接问题
description: 网络和代理故障排除
navigation:
icon: i-heroicons-signal
---
# 连接问题
本页帮助你诊断和解决网络连接相关的问题。
## 诊断步骤
### 1. 检查网络连接
```bash
# 测试网络连通性
ping api.anthropic.com
ping api.openai.com
```
### 2. 检查 DNS 解析
```bash
# 测试 DNS 解析
nslookup api.anthropic.com
```
### 3. 测试 HTTPS 连接
```bash
# 测试 HTTPS 连接
curl -I https://api.anthropic.com
```
## 常见问题
### 连接超时
**症状**: 请求长时间无响应后超时
**可能原因**:
- 网络不稳定
- 防火墙阻止
- Provider 服务不可用
**解决方案**:
1. 检查网络连接
2. 检查防火墙设置
3. 尝试使用代理
4. 增加超时时间
### DNS 解析失败
**症状**: 无法解析域名
**解决方案**:
1. 检查 DNS 设置
2. 尝试使用公共 DNS（如 8.8.8.8）
3. 清除 DNS 缓存
```bash
# macOS
sudo dscacheutil -flushcache
# Windows
ipconfig /flushdns
```
### SSL/TLS 错误
**症状**: 证书验证失败
**可能原因**:
- 系统时间不正确
- 根证书过期
- 代理拦截 HTTPS
**解决方案**:
1. 同步系统时间
2. 更新系统证书
3. 检查代理设置
## 代理配置
### 设置代理
在 ProxyCast 设置中配置代理：
1. 进入 **设置** > **高级**
2. 配置代理设置：
| 选项 | 说明 |
|------|------|
| HTTP 代理 | HTTP 代理地址 |
| HTTPS 代理 | HTTPS 代理地址 |
| 不代理地址 | 排除的地址列表 |
### 代理格式
```
http://proxy.example.com:8080
http://user:password@proxy.example.com:8080
socks5://proxy.example.com:1080
```
### 环境变量
也可以通过环境变量设置：
```bash
export HTTP_PROXY=http://proxy.example.com:8080
export HTTPS_PROXY=http://proxy.example.com:8080
export NO_PROXY=localhost,127.0.0.1
```
## Provider 特定问题
### Anthropic API
**端点**: `https://api.anthropic.com`
**常见问题**:
- 某些地区可能需要代理
- 检查 API 状态页面
### Google Gemini
**端点**: `https://generativelanguage.googleapis.com`
**常见问题**:
- 需要 Google Cloud 项目
- 检查 API 是否启用
### 阿里云 Qwen
**端点**: `https://dashscope.aliyuncs.com`
**常见问题**:
- 海外访问可能需要代理
- 检查区域设置
## 防火墙设置
### 允许的端口
确保防火墙允许以下端口：
| 端口 | 用途 |
|------|------|
| 443 | HTTPS 请求 |
| 9090 | ProxyCast API（默认） |
### macOS 防火墙
1. 系统偏好设置 > 安全性与隐私
2. 防火墙 > 防火墙选项
3. 允许 ProxyCast 接收传入连接
### Windows 防火墙
1. 控制面板 > Windows Defender 防火墙
2. 允许应用通过防火墙
3. 添加 ProxyCast
## 调试模式
启用详细日志：
1. 进入 **设置** > **高级**
2. 设置日志级别为 **Debug**
3. 重现问题
4. 查看网络请求日志
docs/content/06.development/1.architecture.md
+229
View File
@@ -0,0 +1,229 @@
---
title: 架构说明
description: ProxyCast 技术架构
navigation:
icon: i-heroicons-cube-transparent
---
# 架构说明
ProxyCast 是基于 Tauri 2.0 构建的跨平台桌面应用。
## 技术栈
| 层级 | 技术 |
|------|------|
| 前端 | React + TypeScript + Tailwind CSS |
| 后端 | Rust + Tauri 2.0 |
| 构建 | Vite |
| 包管理 | pnpm |
## Tauri 前后端通信
### 架构图
```
┌─────────────────────────────────────────────────────────┐
│ Frontend (React) │
│ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │
│ │ Dashboard │ │ Settings │ │ Monitoring │ │
│ └──────┬──────┘ └──────┬──────┘ └──────┬──────┘ │
│ │ │ │ │
│ └────────────────┼────────────────┘ │
│ │ │
│ ┌─────▼─────┐ │
│ │ Tauri │ │
│ │ Commands │ │
│ └─────┬─────┘ │
└──────────────────────────┼──────────────────────────────┘
│ IPC
┌──────────────────────────┼──────────────────────────────┐
│ ┌─────▼─────┐ │
│ │ Command │ │
│ │ Handler │ │
│ └─────┬─────┘ │
│ │ │
│ ┌───────────────────────┼───────────────────────┐ │
│ │ │ │ │
│ ▼ ▼ ▼ │
│ ┌─────────┐ ┌─────────┐ ┌─────────┐ │
│ │Provider │ │Credential│ │ Router │ │
│ │ Manager │ │ Pool │ │ │ │
│ └────┬────┘ └────┬────┘ └────┬────┘ │
│ │ │ │ │
│ └──────────────────┼──────────────────────┘ │
│ │ │
│ ┌─────▼─────┐ │
│ │ API Server│ │
│ │ (Axum) │ │
│ └───────────┘ │
│ Backend (Rust) │
└───────────────────────────────────────────────────────┘
```
### 通信方式
前端通过 Tauri Commands 调用后端：
```typescript
// 前端调用
import { invoke } from '@tauri-apps/api/core';
const result = await invoke('get_credentials');
```
```rust
// 后端处理
#[tauri::command]
async fn get_credentials() -> Result<Vec<Credential>, String> {
// 处理逻辑
}
```
## Rust 后端模块
### 模块结构
```
src-tauri/src/
├── main.rs # 入口
├── lib.rs # 库导出
├── commands/ # Tauri 命令
│ ├── mod.rs
│ ├── config_cmd.rs
│ ├── credential_cmd.rs
│ └── server_cmd.rs
├── credential/ # 凭证管理
│ ├── mod.rs
│ ├── kiro.rs
│ ├── gemini.rs
│ └── qwen.rs
├── provider/ # Provider 实现
│ ├── mod.rs
│ ├── anthropic.rs
│ ├── openai.rs
│ └── gemini.rs
├── router/ # 请求路由
│ ├── mod.rs
│ └── rules.rs
├── converter/ # 协议转换
│ ├── mod.rs
│ ├── openai_to_claude.rs
│ └── claude_to_openai.rs
├── server/ # API Server
│ ├── mod.rs
│ ├── handlers.rs
│ └── middleware.rs
└── config/ # 配置管理
├── mod.rs
└── yaml.rs
```
### 核心模块
#### Credential 模块
负责凭证的加载、刷新和管理：
```rust
pub struct CredentialManager {
credentials: Vec<Credential>,
refresh_scheduler: RefreshScheduler,
}
impl CredentialManager {
pub async fn load_credentials(&mut self) -> Result<()>;
pub async fn refresh_token(&mut self, id: &str) -> Result<()>;
pub fn get_available(&self) -> Vec<&Credential>;
}
```
#### Provider 模块
实现不同 AI 服务的调用：
```rust
#[async_trait]
pub trait Provider: Send + Sync {
async fn chat_completion(&self, request: ChatRequest) -> Result<ChatResponse>;
async fn stream_completion(&self, request: ChatRequest) -> Result<impl Stream<Item = StreamChunk>>;
}
```
#### Router 模块
根据规则路由请求：
```rust
pub struct Router {
rules: Vec<RoutingRule>,
default_provider: String,
}
impl Router {
pub fn route(&self, model: &str) -> RoutingResult;
}
```
#### Converter 模块
在不同 API 格式之间转换：
```rust
pub fn openai_to_claude(request: OpenAIRequest) -> ClaudeRequest;
pub fn claude_to_openai(response: ClaudeResponse) -> OpenAIResponse;
```
## 请求处理流程
```
1. 客户端请求 → API Server (Axum)
│
2. 认证检查 ────────┤
│
3. 路由匹配 ────────┤ Router
│
4. 凭证选择 ────────┤ Credential Pool
│
5. 协议转换 ────────┤ Converter
│
6. Provider 调用 ───┤ Provider
│
7. 响应转换 ────────┤ Converter
│
8. 返回响应 ────────┘
```
## 数据流
### 请求流程
1. 前端发起 API 请求
2. Axum 服务器接收请求
3. 中间件进行认证和日志
4. Router 根据模型名称选择 Provider
5. Credential Pool 选择可用凭证
6. Converter 转换请求格式
7. Provider 调用实际 AI 服务
8. Converter 转换响应格式
9. 返回响应给客户端
### 事件流程
```
后端事件 → Tauri Event → 前端监听 → UI 更新
```
```rust
// 后端发送事件
app.emit("credential-updated", payload)?;
```
```typescript
// 前端监听
import { listen } from '@tauri-apps/api/event';
await listen('credential-updated', (event) => {
// 更新 UI
});
```
docs/content/06.development/2.contributing.md
+200
View File
@@ -0,0 +1,200 @@
---
title: 贡献指南
description: 如何为 ProxyCast 做贡献
navigation:
icon: i-heroicons-heart
---
# 贡献指南
感谢你对 ProxyCast 的关注！本指南帮助你开始贡献。
## 开发环境设置
### 前置要求
| 工具 | 版本 |
|------|------|
| Node.js | >= 18 |
| pnpm | >= 8 |
| Rust | >= 1.70 |
| Tauri CLI | >= 2.0 |
### 安装依赖
```bash
# 克隆仓库
git clone https://github.com/aiclientproxy/proxycast.git
cd proxycast
# 安装前端依赖
pnpm install
# 安装 Tauri CLI
cargo install tauri-cli
```
### 开发模式
```bash
# 启动开发服务器
pnpm tauri dev
```
### 构建
```bash
# 构建发布版本
pnpm tauri build
```
## 代码规范
### TypeScript/React
- 使用 ESLint 和 Prettier
- 遵循 React Hooks 规范
- 组件使用函数式写法
```bash
# 检查代码
pnpm lint
# 格式化代码
pnpm format
```
### Rust
- 使用 rustfmt 格式化
- 使用 clippy 检查
- 遵循 Rust API Guidelines
```bash
# 格式化
cargo fmt
# 检查
cargo clippy
```
### 提交规范
使用 Conventional Commits：
```
feat: 添加新功能
fix: 修复 bug
docs: 更新文档
style: 代码格式调整
refactor: 代码重构
test: 添加测试
chore: 构建/工具变更
```
示例：
```
feat(credential): 添加 Qwen 凭证支持
fix(router): 修复路由规则匹配问题
docs: 更新安装指南
```
## PR 流程
### 1. Fork 仓库
在 GitHub 上 Fork 项目到你的账户。
### 2. 创建分支
```bash
git checkout -b feature/your-feature
```
### 3. 开发和测试
- 编写代码
- 添加测试
- 确保所有测试通过
### 4. 提交代码
```bash
git add .
git commit -m "feat: your feature description"
git push origin feature/your-feature
```
### 5. 创建 PR
1. 在 GitHub 上创建 Pull Request
2. 填写 PR 描述
3. 等待 Review
### PR 检查清单
- [ ] 代码通过 lint 检查
- [ ] 添加了必要的测试
- [ ] 更新了相关文档
- [ ] 提交信息符合规范
## 项目结构
```
proxycast/
├── src/ # 前端源码
│ ├── components/ # React 组件
│ ├── pages/ # 页面组件
│ ├── hooks/ # 自定义 Hooks
│ ├── lib/ # 工具函数
│ └── styles/ # 样式文件
├── src-tauri/ # Rust 后端
│ ├── src/ # 源码
│ ├── Cargo.toml # 依赖配置
│ └── tauri.conf.json # Tauri 配置
├── docs/ # 文档
└── public/ # 静态资源
```
## 测试
### 前端测试
```bash
# 运行测试
pnpm test
# 运行测试并生成覆盖率
pnpm test:coverage
```
### 后端测试
```bash
cd src-tauri
cargo test
```
## 问题反馈
### 报告 Bug
1. 搜索是否已有相同问题
2. 创建新 Issue
3. 提供详细信息：
- 操作系统和版本
- ProxyCast 版本
- 复现步骤
- 错误日志
### 功能建议
1. 创建 Feature Request Issue
2. 描述功能需求
3. 说明使用场景
## 社区
- GitHub Issues: 问题反馈
- GitHub Discussions: 讨论交流
docs/content/06.development/3.building.md
+254
View File
@@ -0,0 +1,254 @@
---
title: 构建指南
description: 本地开发和构建发布
navigation:
icon: i-heroicons-wrench-screwdriver
---
# 构建指南
本指南介绍如何在本地开发和构建 ProxyCast。
## 本地开发
### 环境准备
1. **安装 Node.js**
```bash
# 使用 nvm 安装
nvm install 18
nvm use 18
```
2. **安装 pnpm**
```bash
npm install -g pnpm
```
3. **安装 Rust**
```bash
# macOS/Linux
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
# Windows
# 下载并运行 rustup-init.exe
```
4. **安装 Tauri 依赖**
**macOS:**
```bash
xcode-select --install
```
**Windows:**
- 安装 Visual Studio Build Tools
- 安装 WebView2
**Linux:**
```bash
sudo apt install libwebkit2gtk-4.1-dev build-essential curl wget file libssl-dev libayatana-appindicator3-dev librsvg2-dev
```
### 启动开发
```bash
# 安装依赖
pnpm install
# 启动开发模式
pnpm tauri dev
```
开发模式特性：
- 前端热重载
- Rust 代码变更自动重新编译
- 开发者工具可用
### 开发配置
#### 前端配置
`vite.config.ts`:
```typescript
export default defineConfig({
plugins: [react()],
server: {
port: 1420,
strictPort: true,
},
});
```
#### Tauri 配置
`src-tauri/tauri.conf.json`:
```json
{
"build": {
"devPath": "http://localhost:1420",
"distDir": "../dist"
}
}
```
## 构建发布
### 构建命令
```bash
# 构建当前平台
pnpm tauri build
# 构建 debug 版本
pnpm tauri build --debug
```
### 构建产物
| 平台 | 产物位置 |
|------|----------|
| macOS | `src-tauri/target/release/bundle/dmg/` |
| Windows | `src-tauri/target/release/bundle/msi/` |
| Linux | `src-tauri/target/release/bundle/deb/` |
### 跨平台构建
#### macOS 构建
```bash
# 构建 Apple Silicon
pnpm tauri build --target aarch64-apple-darwin
# 构建 Intel
pnpm tauri build --target x86_64-apple-darwin
# 构建 Universal
pnpm tauri build --target universal-apple-darwin
```
#### Windows 构建
```bash
# 构建 64 位
pnpm tauri build --target x86_64-pc-windows-msvc
```
#### Linux 构建
```bash
# 构建 deb 包
pnpm tauri build --target x86_64-unknown-linux-gnu
```
## 版本管理
### 更新版本号
1. 更新 `package.json`:
```json
{
"version": "1.0.1"
}
```
2. 更新 `src-tauri/Cargo.toml`:
```toml
[package]
version = "1.0.1"
```
3. 更新 `src-tauri/tauri.conf.json`:
```json
{
"version": "1.0.1"
}
```
### 创建发布
```bash
# 创建 tag
git tag v1.0.1
git push origin v1.0.1
```
## CI/CD
### GitHub Actions
项目使用 GitHub Actions 自动构建：
- Push 到 main 分支触发构建
- 创建 tag 触发发布
### 构建矩阵
| 平台 | 架构 | Runner |
|------|------|--------|
| macOS | arm64 | macos-latest |
| macOS | x64 | macos-13 |
| Windows | x64 | windows-latest |
| Linux | x64 | ubuntu-latest |
## 调试
### 前端调试
开发模式下按 `F12` 打开开发者工具。
### 后端调试
```bash
# 启用 Rust 日志
RUST_LOG=debug pnpm tauri dev
```
### 日志位置
| 平台 | 路径 |
|------|------|
| macOS | `~/Library/Logs/ProxyCast/` |
| Windows | `%APPDATA%\ProxyCast\logs\` |
| Linux | `~/.local/share/proxycast/logs/` |
## 常见问题
### 构建失败
1. 确保所有依赖已安装
2. 清理构建缓存：
```bash
# 清理前端
rm -rf node_modules dist
pnpm install
# 清理 Rust
cd src-tauri
cargo clean
```
### 签名问题
macOS 构建需要代码签名：
```bash
# 设置签名身份
export APPLE_SIGNING_IDENTITY="Developer ID Application: ..."
```
Windows 构建可选签名：
```bash
# 设置签名证书
export TAURI_SIGNING_PRIVATE_KEY="..."
```
docs/content/07.legal/1.disclaimer.md
+57
View File
@@ -0,0 +1,57 @@
---
title: 免责声明
description: 使用条款和法律声明
navigation:
icon: i-heroicons-scale
---
# 免责声明
## 使用目的
ProxyCast 是一款开源工具，其设计初衷是帮助用户**充分利用已订阅的 AI 服务 Token**，在更多场景中发挥其价值。
::alert{type="warning"}
**重要提示**: 本工具仅限于个人合法使用，严禁用于任何非法盈利目的。
::
## 合法使用范围
本工具的合法使用场景包括但不限于：
- ✅ 个人学习和研究
- ✅ 个人开发项目中使用已订阅的 AI 服务
- ✅ 在不同开发工具间复用个人订阅额度
- ✅ 提高个人工作效率
## 禁止行为
以下行为严格禁止：
- ❌ 将本工具用于商业盈利目的
- ❌ 转售或分享他人的 AI 服务凭证
- ❌ 违反 AI 服务提供商的服务条款
- ❌ 任何形式的非法活动
## 责任声明
1. **用户责任**: 用户应确保其使用行为符合所在地区的法律法规，以及相关 AI 服务提供商的服务条款。
2. **风险自担**: 使用本工具所产生的任何后果由用户自行承担，包括但不限于账户封禁、服务终止等。
3. **无担保**: 本工具按"现状"提供，不提供任何明示或暗示的担保。
4. **免责**: 开发者不对因使用本工具而导致的任何直接或间接损失承担责任。
## 服务条款遵守
使用本工具时，请务必遵守以下服务提供商的使用条款：
- [Anthropic 使用政策](https://www.anthropic.com/policies)
- [Google AI 服务条款](https://policies.google.com/terms)
- [阿里云服务条款](https://terms.alibabacloud.com/)
- [OpenAI 使用政策](https://openai.com/policies)
## 联系我们
如对本声明有任何疑问，请通过 GitHub Issues 联系我们。
docs/content/index.md
+137
View File
@@ -0,0 +1,137 @@
---
title: ProxyCast
description: 把你的 AI 客户端额度用到任何地方
navigation: false
layout: page
---
::hero
---
announcement:
title: 🎉 ProxyCast v1.0 发布
icon: i-heroicons-megaphone
to: /introduction/overview
actions:
- label: 快速开始
icon: i-heroicons-rocket-launch
to: /introduction/quickstart
color: primary
- label: GitHub
icon: i-simple-icons-github
to: https://github.com/aiclientproxy/proxycast
target: _blank
color: neutral
---
#title
ProxyCast
#description
把你的 AI 客户端额度用到任何地方。一款基于 Tauri 的桌面应用，将 Kiro、Gemini CLI、Qwen 等 AI 客户端凭证转换为标准 OpenAI/Claude 兼容 API。
::
::alert{type="warning"}
**免责声明**: 本工具仅限于个人合法使用，严禁用于非法盈利目的。初衷是帮助用户充分利用已订阅的 AI 服务 Token。[查看完整声明](/legal/disclaimer)
::
::card-group
::card
---
title: 凭证池管理
icon: i-heroicons-key
to: /user-guide/credential-pool
---
支持多种 AI 客户端凭证的统一管理，包括 Kiro、Gemini CLI、Qwen、Claude Code 等。
::
::card
---
title: 智能路由
icon: i-heroicons-arrows-right-left
to: /user-guide/smart-routing
---
基于负载均衡、优先级、健康检查的智能请求路由策略。
::
::card
---
title: 容错配置
icon: i-heroicons-shield-check
to: /user-guide/resilience
---
内置熔断器、重试机制、超时控制，确保服务稳定性。
::
::card
---
title: 配置切换
icon: i-heroicons-cog-6-tooth
to: /user-guide/config-switch
---
一键切换 Claude Code、Codex、Gemini CLI 等客户端配置。
::
::
::section
#title
核心特性
#description
ProxyCast 提供完整的 AI 客户端代理解决方案
::card-group
::card
---
title: 仪表盘
icon: i-heroicons-chart-bar
to: /user-guide/dashboard
---
实时监控请求统计、凭证状态、系统健康度。
::
::card
---
title: 监控中心
icon: i-heroicons-eye
to: /user-guide/monitoring
---
详细的请求日志、性能指标、错误追踪。
::
::card
---
title: API Server
icon: i-heroicons-server
to: /user-guide/api-server
---
OpenAI/Claude 兼容的 API 服务端点。
::
::card
---
title: MCP 支持
icon: i-heroicons-puzzle-piece
to: /user-guide/mcp
---
Model Context Protocol 集成支持。
::
::card
---
title: Prompts 管理
icon: i-heroicons-document-text
to: /user-guide/prompts
---
系统提示词模板管理与复用。
::
::card
---
title: Skills 技能
icon: i-heroicons-sparkles
to: /user-guide/skills
---
可扩展的技能模块系统。
::
::
::
docs/nuxt.config.ts
+15
View File
@@ -0,0 +1,15 @@
export default {
extends: ["docus"],
app: {
baseURL: "/proxycast/",
},
image: {
provider: "none",
},
robots: {
robotsTxt: false,
},
llms: {
domain: "https://proxycast.local",
},
};
docs/package.json
+14
View File
@@ -0,0 +1,14 @@
{
"name": "proxycast-docs",
"scripts": {
"dev": "nuxt dev --extends docus",
"build": "nuxt build --extends docus",
"generate": "nuxt generate --extends docus"
},
"dependencies": {
"docus": "latest",
"better-sqlite3": "^12.2.0",
"nuxt": "^4.2.1",
"mermaid": "^11.4.0"
}
}