diff --git a/.github/workflows/deploy-docs.yml b/.github/workflows/deploy-docs.yml new file mode 100644 index 000000000..bafe2fe39 --- /dev/null +++ b/.github/workflows/deploy-docs.yml @@ -0,0 +1,92 @@ +# 部署文档站点到 GitHub Pages +name: Deploy Docs to Pages + +# 触发条件 +on: + # 推送到 main 分支且 docs 目录有变更时触发 + push: + branches: [main] + paths: + - "docs/**" + + # PR 到 main 分支且 docs 目录有变更时触发（仅构建，不部署） + pull_request: + branches: [main] + paths: + - "docs/**" + + # 允许手动触发 + workflow_dispatch: + +# 设置 GitHub Pages 部署所需的权限 +permissions: + contents: read + pages: write + id-token: write + +# 只允许一个并发部署 +concurrency: + group: pages + cancel-in-progress: false + +jobs: + # 构建任务 + build: + runs-on: ubuntu-latest + steps: + - name: Checkout + uses: actions/checkout@v4 + with: + fetch-depth: 0 + + - name: Setup Node.js + uses: actions/setup-node@v4 + with: + node-version: "20" + + - name: Setup pnpm + uses: pnpm/action-setup@v4 + with: + version: 9 + + - name: Get pnpm store directory + shell: bash + run: | + echo "STORE_PATH=$(pnpm store path --silent)" >> $GITHUB_ENV + + - name: Setup pnpm cache + uses: actions/cache@v4 + with: + path: ${{ env.STORE_PATH }} + key: ${{ runner.os }}-pnpm-store-${{ hashFiles('docs/pnpm-lock.yaml') }} + restore-keys: | + ${{ runner.os }}-pnpm-store- + + - name: Setup Pages + uses: actions/configure-pages@v5 + + - name: Install dependencies + run: pnpm install + working-directory: docs + + - name: Build + run: pnpm run generate + working-directory: docs + + - name: Upload artifact + uses: actions/upload-pages-artifact@v3 + with: + path: docs/.output/public + + # 部署任务 + deploy: + environment: + name: github-pages + url: ${{ steps.deployment.outputs.page_url }} + needs: build + if: github.event_name != 'pull_request' + runs-on: ubuntu-latest + steps: + - name: Deploy to GitHub Pages + id: deployment + uses: actions/deploy-pages@v4 diff --git a/docs/app.config.ts b/docs/app.config.ts new file mode 100644 index 000000000..1f52edb61 --- /dev/null +++ b/docs/app.config.ts @@ -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: [], + }, + }, +}; diff --git a/docs/content/01.introduction/1.overview.md b/docs/content/01.introduction/1.overview.md new file mode 100644 index 000000000..04779e1de --- /dev/null +++ b/docs/content/01.introduction/1.overview.md @@ -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 调用 diff --git a/docs/content/01.introduction/2.installation.md b/docs/content/01.introduction/2.installation.md new file mode 100644 index 000000000..34c396457 --- /dev/null +++ b/docs/content/01.introduction/2.installation.md @@ -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。 diff --git a/docs/content/01.introduction/3.quickstart.md b/docs/content/01.introduction/3.quickstart.md new file mode 100644 index 000000000..ea6cce540 --- /dev/null +++ b/docs/content/01.introduction/3.quickstart.md @@ -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) - 配置请求路由规则 diff --git a/docs/content/02.user-guide/1.dashboard.md b/docs/content/02.user-guide/1.dashboard.md new file mode 100644 index 000000000..cc7f04281 --- /dev/null +++ b/docs/content/02.user-guide/1.dashboard.md @@ -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 | 凭证类型 | +| 状态 | 有效/过期/错误 | +| 剩余额度 | 可用额度（如支持） | + +## 快捷操作 + +- **打开设置**: 进入设置页面 +- **查看日志**: 打开请求日志 +- **刷新凭证**: 重新加载凭证文件 diff --git a/docs/content/02.user-guide/10.prompts.md b/docs/content/02.user-guide/10.prompts.md new file mode 100644 index 000000000..653b7dc05 --- /dev/null +++ b/docs/content/02.user-guide/10.prompts.md @@ -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. 确认导入 + +### 分享提示词 + +导出的提示词文件可以分享给他人使用。 diff --git a/docs/content/02.user-guide/11.skills.md b/docs/content/02.user-guide/11.skills.md new file mode 100644 index 000000000..44dfe4378 --- /dev/null +++ b/docs/content/02.user-guide/11.skills.md @@ -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` 文件 +- **导入**: 从文件导入技能 diff --git a/docs/content/02.user-guide/12.settings.md b/docs/content/02.user-guide/12.settings.md new file mode 100644 index 000000000..238a0793a --- /dev/null +++ b/docs/content/02.user-guide/12.settings.md @@ -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 | 日志文件保留时间 | diff --git a/docs/content/02.user-guide/2.monitoring.md b/docs/content/02.user-guide/2.monitoring.md new file mode 100644 index 000000000..3a922c86e --- /dev/null +++ b/docs/content/02.user-guide/2.monitoring.md @@ -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 格式 +- 自定义时间范围 diff --git a/docs/content/02.user-guide/3.credential-pool.md b/docs/content/02.user-guide/3.credential-pool.md new file mode 100644 index 000000000..45f758d9a --- /dev/null +++ b/docs/content/02.user-guide/3.credential-pool.md @@ -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 中移除。 +:: diff --git a/docs/content/02.user-guide/4.smart-routing.md b/docs/content/02.user-guide/4.smart-routing.md new file mode 100644 index 000000000..0ae3d32be --- /dev/null +++ b/docs/content/02.user-guide/4.smart-routing.md @@ -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 + - 目标模型 diff --git a/docs/content/02.user-guide/5.resilience.md b/docs/content/02.user-guide/5.resilience.md new file mode 100644 index 000000000..d264780b7 --- /dev/null +++ b/docs/content/02.user-guide/5.resilience.md @@ -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） diff --git a/docs/content/02.user-guide/6.config-management.md b/docs/content/02.user-guide/6.config-management.md new file mode 100644 index 000000000..6b0023bd3 --- /dev/null +++ b/docs/content/02.user-guide/6.config-management.md @@ -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. 重新配置凭证 diff --git a/docs/content/02.user-guide/7.config-switch.md b/docs/content/02.user-guide/7.config-switch.md new file mode 100644 index 000000000..94c13e56f --- /dev/null +++ b/docs/content/02.user-guide/7.config-switch.md @@ -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 +``` diff --git a/docs/content/02.user-guide/8.api-server.md b/docs/content/02.user-guide/8.api-server.md new file mode 100644 index 000000000..ca041f8d0 --- /dev/null +++ b/docs/content/02.user-guide/8.api-server.md @@ -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. 开启 **启动时自动运行服务** diff --git a/docs/content/02.user-guide/9.mcp.md b/docs/content/02.user-guide/9.mcp.md new file mode 100644 index 000000000..cf3c251aa --- /dev/null +++ b/docs/content/02.user-guide/9.mcp.md @@ -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. 实时显示服务器输出 diff --git a/docs/content/03.providers/1.overview.md b/docs/content/03.providers/1.overview.md new file mode 100644 index 000000000..544aef97a --- /dev/null +++ b/docs/content/03.providers/1.overview.md @@ -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) diff --git a/docs/content/03.providers/2.kiro-claude.md b/docs/content/03.providers/2.kiro-claude.md new file mode 100644 index 000000000..a3f7e9722 --- /dev/null +++ b/docs/content/03.providers/2.kiro-claude.md @@ -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 | 服务不可用 | 稍后重试 | diff --git a/docs/content/03.providers/3.gemini-cli.md b/docs/content/03.providers/3.gemini-cli.md new file mode 100644 index 000000000..658de0d54 --- /dev/null +++ b/docs/content/03.providers/3.gemini-cli.md @@ -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. 账单设置正确 diff --git a/docs/content/03.providers/4.qwen.md b/docs/content/03.providers/4.qwen.md new file mode 100644 index 000000000..72d4fc3a3 --- /dev/null +++ b/docs/content/03.providers/4.qwen.md @@ -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" +``` diff --git a/docs/content/03.providers/5.openai-custom.md b/docs/content/03.providers/5.openai-custom.md new file mode 100644 index 000000000..bbddd9e56 --- /dev/null +++ b/docs/content/03.providers/5.openai-custom.md @@ -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 用户确认部署名称 diff --git a/docs/content/03.providers/6.claude-custom.md b/docs/content/03.providers/6.claude-custom.md new file mode 100644 index 000000000..54b51a608 --- /dev/null +++ b/docs/content/03.providers/6.claude-custom.md @@ -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 diff --git a/docs/content/04.api-reference/1.overview.md b/docs/content/04.api-reference/1.overview.md new file mode 100644 index 000000000..4a2b2a709 --- /dev/null +++ b/docs/content/04.api-reference/1.overview.md @@ -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 兼容端点详情 diff --git a/docs/content/04.api-reference/2.openai-api.md b/docs/content/04.api-reference/2.openai-api.md new file mode 100644 index 000000000..30d35ba91 --- /dev/null +++ b/docs/content/04.api-reference/2.openai-api.md @@ -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); +``` diff --git a/docs/content/04.api-reference/3.claude-api.md b/docs/content/04.api-reference/3.claude-api.md new file mode 100644 index 000000000..cbafe61fb --- /dev/null +++ b/docs/content/04.api-reference/3.claude-api.md @@ -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); +``` diff --git a/docs/content/05.troubleshooting/1.common-issues.md b/docs/content/05.troubleshooting/1.common-issues.md new file mode 100644 index 000000000..c8d3e4b4a --- /dev/null +++ b/docs/content/05.troubleshooting/1.common-issues.md @@ -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. 提供详细的错误信息和复现步骤 diff --git a/docs/content/05.troubleshooting/2.credential-errors.md b/docs/content/05.troubleshooting/2.credential-errors.md new file mode 100644 index 000000000..6eb6b9c10 --- /dev/null +++ b/docs/content/05.troubleshooting/2.credential-errors.md @@ -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. 查看日志文件 diff --git a/docs/content/05.troubleshooting/3.connection-issues.md b/docs/content/05.troubleshooting/3.connection-issues.md new file mode 100644 index 000000000..a702342f5 --- /dev/null +++ b/docs/content/05.troubleshooting/3.connection-issues.md @@ -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. 查看网络请求日志 diff --git a/docs/content/06.development/1.architecture.md b/docs/content/06.development/1.architecture.md new file mode 100644 index 000000000..89cfb2751 --- /dev/null +++ b/docs/content/06.development/1.architecture.md @@ -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, 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, + 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; + async fn stream_completion(&self, request: ChatRequest) -> Result>; +} +``` + +#### Router 模块 + +根据规则路由请求： + +```rust +pub struct Router { + rules: Vec, + 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 +}); +``` diff --git a/docs/content/06.development/2.contributing.md b/docs/content/06.development/2.contributing.md new file mode 100644 index 000000000..625745e00 --- /dev/null +++ b/docs/content/06.development/2.contributing.md @@ -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: 讨论交流 diff --git a/docs/content/06.development/3.building.md b/docs/content/06.development/3.building.md new file mode 100644 index 000000000..d669a4866 --- /dev/null +++ b/docs/content/06.development/3.building.md @@ -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="..." +``` diff --git a/docs/content/07.legal/1.disclaimer.md b/docs/content/07.legal/1.disclaimer.md new file mode 100644 index 000000000..8c375ba5f --- /dev/null +++ b/docs/content/07.legal/1.disclaimer.md @@ -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 联系我们。 diff --git a/docs/content/index.md b/docs/content/index.md new file mode 100644 index 000000000..5025068a7 --- /dev/null +++ b/docs/content/index.md @@ -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 + --- + 可扩展的技能模块系统。 + :: +:: +:: diff --git a/docs/nuxt.config.ts b/docs/nuxt.config.ts new file mode 100644 index 000000000..185fcde2a --- /dev/null +++ b/docs/nuxt.config.ts @@ -0,0 +1,15 @@ +export default { + extends: ["docus"], + app: { + baseURL: "/proxycast/", + }, + image: { + provider: "none", + }, + robots: { + robotsTxt: false, + }, + llms: { + domain: "https://proxycast.local", + }, +}; diff --git a/docs/package.json b/docs/package.json new file mode 100644 index 000000000..de4f564c6 --- /dev/null +++ b/docs/package.json @@ -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" + } +} diff --git a/package.json b/package.json index 20d7f1b57..07a27cf9b 100644 --- a/package.json +++ b/package.json @@ -1,7 +1,7 @@ { "name": "proxycast", "private": true, - "version": "0.10.1", + "version": "0.11.0", "type": "module", "scripts": { "dev": "vite", diff --git a/src-tauri/Cargo.lock b/src-tauri/Cargo.lock index ab69e353a..13dacb8ac 100644 --- a/src-tauri/Cargo.lock +++ b/src-tauri/Cargo.lock @@ -3274,7 +3274,7 @@ dependencies = [ [[package]] name = "proxycast" -version = "0.10.1" +version = "0.11.0" dependencies = [ "anyhow", "async-stream", diff --git a/src-tauri/Cargo.toml b/src-tauri/Cargo.toml index 1fbad480e..1360d73b1 100644 --- a/src-tauri/Cargo.toml +++ b/src-tauri/Cargo.toml @@ -1,6 +1,6 @@ [package] name = "proxycast" -version = "0.10.1" +version = "0.11.0" description = "AI API Proxy Desktop App" authors = ["you"] edition = "2021" diff --git a/src-tauri/tauri.conf.json b/src-tauri/tauri.conf.json index a45bb5a0c..789329258 100644 --- a/src-tauri/tauri.conf.json +++ b/src-tauri/tauri.conf.json @@ -1,7 +1,7 @@ { "$schema": "https://schema.tauri.app/config/2", "productName": "ProxyCast", - "version": "0.10.1", + "version": "0.11.0", "identifier": "com.proxycast.app", "build": { "beforeDevCommand": "npm run dev",