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

release: v0.68.0

Browse Source 
## Features
- 版本升级至 0.68.0

## Fixes
- 修复 EmptyState 组件标题排版问题
- 修复"开始生成"按钮文字换行问题
- 修复加载历史对话失败问题
  - 修复 parse_message_content 保留 ContentPart 结构
  - 修复 convert_agent_message 添加 reasoning_content 处理
  - 修复 WorkspaceType::from_str 命名冲突，重命名为 parse

## Code Quality
- 修复所有 clippy 警告
  - 修复 manual_flatten 警告
  - 修复 ptr_arg 警告（使用 &Path 替代 &PathBuf）
  - 修复 manual_clamp 警告
  - 修复 match_single_binding 警告
- 所有测试通过 (174 passed)
This commit is contained in:
coso
2026-02-16 20:58:55 +08:00
parent ec9db9f0f6
commit 7851c34bed
71 changed files with 1715 additions and 4914 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/content/01.introduction/1.overview.md
+31 -48
View File
@@ -1,73 +1,56 @@
---
title: 概述
description: ProxyCast 项目介绍和核心价值
description: 了解 ProxyCast 如何支持从灵感到发布的完整创作流程
navigation:
icon: i-heroicons-home
---
# ProxyCast 概述
ProxyCast 是一款基于 Tauri 2.0 的跨平台桌面应用，让你可以**把 AI 客户端的订阅额度用到任何地方**。
ProxyCast 是一款创作类 AI Agent 桌面应用。
它把对话、内容生成、图片创作、项目管理、资源沉淀放到同一个工作台里。
::alert{type="warning"}
**免责声明**: 本工具仅限于个人合法使用，严禁用于非法盈利目的。初衷是帮助用户充分利用已订阅的 AI 服务 Token。[查看完整声明](/legal/disclaimer)
**免责声明**: 请在合法合规前提下使用本产品。[查看完整声明](/legal/disclaimer)
::
## 核心价值
## 你可以用它做什么
你是否有以下困扰？
### 九大创作主题
- 订阅了 Kiro、Claude Code 等 AI 编程助手，但只能在特定 IDE 中使用
- 想在其他工具（如 Cursor、Continue、自定义脚本）中使用已有的 AI 额度
- 需要管理多个 AI 服务的凭证，频繁切换很麻烦
- 通用对话
- 社媒内容
- 图文海报
- 歌词曲谱
- 知识探索
- 计划规划
- 办公文档
- 短视频
- 小说创作
ProxyCast 解决这些问题：将你的 AI 客户端凭证转换为标准的 OpenAI/Claude 兼容 API，让任何支持 OpenAI 接口的工具都能使用你的订阅额度。
### 创作全流程
## 支持的 Provider
1. 用 Agent 把想法变成清晰方向
2. 生成文案、脚本或结构化草稿
3. 按需要生成图片并继续迭代
4. 把结果沉淀到项目和资源库，方便长期复用
| 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 使用追踪
- 详细的请求日志
- AI 对话与创作在同一处完成
- 项目隔离上下文，避免内容串线
- 资源按文档/图片/语音/视频分类管理
- 支持参考图参与图片生成与编辑链路
## 使用场景
1. **IDE 集成**: 在 Cursor、Continue 等编辑器中使用 Kiro/Claude Code 额度
2. **脚本调用**: 在 Python/Node.js 脚本中调用 AI API
3. **多账户管理**: 统一管理多个 AI 服务账户
4. **团队共享**: 通过配置导出分享 Provider 设置
1. **自媒体创作**：每天稳定产出选题、文案、配图
2. **短视频团队**：快速完成脚本与分镜草稿
3. **小说连载**：持续积累设定、章节与角色信息
4. **品牌运营**：统一管理活动素材与历史版本
## 下一步
- [安装指南](/introduction/installation) - 下载并安装 ProxyCast
- [快速开始](/introduction/quickstart) - 5 分钟内完成首次 API 调用
- [快速开始](/introduction/quickstart) - 3 步完成首次创作
- [首页与工作台](/user-guide/dashboard) - 熟悉核心入口
docs/content/01.introduction/2.installation.md
+6 -6
View File
@@ -1,6 +1,6 @@
---
title: 安装指南
description: 下载并安装 ProxyCast
description: 下载、安装并验证 ProxyCast 可正常启动
navigation:
icon: i-heroicons-arrow-down-tray
---
@@ -16,7 +16,7 @@ navigation:
## 下载
从 GitHub Tags 下载最新版本：
从 GitHub Releases/Tags 下载最新版本安装包：
[下载 ProxyCast](https://github.com/aiclientproxy/proxycast/tags)
@@ -49,9 +49,9 @@ navigation:
启动 ProxyCast 后，你应该看到：
1. 系统托盘图标出现
2. 主窗口显示仪表盘
3. 服务状态显示"已停止"（首次启动）
1. 主窗口正常打开
2. 左侧出现主要入口（AI Agent、项目、资源、图片生成等）
3. 可以进入设置页并看到版本信息
## 常见安装问题
@@ -68,4 +68,4 @@ xattr -cr /Applications/ProxyCast.app
## 下一步
安装完成后，继续阅读 [快速开始](/introduction/quickstart) 配置你的第一个 Provider。
安装完成后，继续阅读 [快速开始](/introduction/quickstart)，用 3 步完成第一次创作。
docs/content/01.introduction/3.quickstart.md
+32 -84
View File
@@ -1,116 +1,64 @@
---
title: 快速开始
description: 5 分钟内完成首次 API 调用
description: 3 步完成首次创作并沉淀到项目资源库
navigation:
icon: i-heroicons-rocket-launch
---
# 快速开始
本指南帮助你在 5 分钟内完成 ProxyCast 的基本配置和首次 API 调用。
本指南帮助你在几分钟内完成第一次完整创作流程。
## 前置准备
确保你已经：
- [x] 安装了 ProxyCast
- [x] 拥有至少一个 AI 客户端的有效订阅（Kiro、Gemini CLI、Qwen 等）
- [x] 可以正常打开应用主界面
## 步骤 1: 启动 ProxyCast
## 步骤 1：选择创作主题与项目
1. 启动 ProxyCast 应用
2. 主窗口会显示仪表盘界面
1. 启动 ProxyCast，进入 AI Agent 或项目入口
2. 选择你的主题方向（如社媒、短视频、小说）
3. 新建项目，作为本次创作的工作空间
## 步骤 2: 加载凭证
## 步骤 2：输入需求并生成内容
ProxyCast 会自动检测本地的 AI 客户端凭证文件。
1. 用一句话描述你的目标
2. 让 Agent 先给结构，再生成首稿
3. 如需视觉内容，进入图片生成功能继续产出与迭代
### 凭证文件位置
## 步骤 3：沉淀到资源库
| Provider | 凭证路径 |
|----------|----------|
| Kiro Claude | `~/.kiro/credentials.json` |
| Gemini CLI | `~/.config/gemini-cli/oauth_creds.json` |
| Qwen | `~/.config/qwen/credentials.json` |
1. 将文档、图片等结果保存到当前项目资源库
2. 在资源页按分类查看（文档/图片/语音/视频）
3. 下次创作直接复用历史素材和上下文
### 手动添加凭证
## 一个最小创作示例
如果自动检测未找到凭证：
1. 主题：`短视频`
2. 输入：`做一条 30 秒“高效晨间复盘”口播内容`
3. 产出：
- 3 个开场钩子
- 1 版结构化口播稿
- 1 组配图提示词或参考图改写结果
1. 进入 **凭证池** 页面
2. 点击 **添加凭证**
3. 选择 Provider 类型
4. 输入凭证信息或选择凭证文件
## 常见问题
## 步骤 3: 启动 API Server
### 我可以只用对话，不做图片吗？
1. 在仪表盘点击 **启动服务**
2. 服务状态变为"运行中"
3. 记下 API 地址（默认 `http://127.0.0.1:8999`）
可以。你可以只用 AI Agent 完成文本创作和项目沉淀。
## 步骤 4: 测试 API
### 我可以直接改图吗？
### 使用内置测试面板
可以。上传参考图后，若所选模型支持编辑接口，会自动走编辑链路。
1. 在仪表盘找到 **API 测试** 区域
2. 输入测试消息
3. 点击发送，查看响应
### 我还需要 API 接入能力怎么办？
### 使用 curl 测试
**OpenAI 格式:**
```bash
curl http://127.0.0.1:8999/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:8999/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:8999/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:8999/v1",
"apiKey": "your-api-key"
}]
}
```
可以继续阅读 [API Server](/user-guide/api-server) 和 [API 参考](/api-reference/overview)。
## 下一步
- [仪表盘](/user-guide/dashboard) - 了解仪表盘功能
- [凭证池](/user-guide/credential-pool) - 管理多个凭证
- [智能路由](/user-guide/smart-routing) - 配置请求路由规则
- [首页与工作台](/user-guide/dashboard) - 理解核心导航
- [资源库](/user-guide/resources) - 管理创作资产
- [图片生成与编辑](/user-guide/image-generation) - 深入图片链路
docs/content/02.user-guide/1.dashboard.md
+38 -55
View File
@@ -1,75 +1,58 @@
---
title: 仪表盘
description: 监控和控制代理服务
title: 首页与工作台
description: 首页与创作工作台总览
navigation:
icon: i-heroicons-chart-bar
---
# 仪表盘
# 首页与工作台
仪表盘是 ProxyCast 的主界面，提供服务状态监控和快速操作入口。
首页是你进入 ProxyCast 后的主入口。
建议把它理解为“创作操作台”，而不是单一功能面板。
## 服务状态
## 左侧核心入口
仪表盘顶部显示当前服务状态：
- **AI Agent**：对话、任务推进、内容初稿
- **项目**：按创作目标管理长期内容
- **资源**：统一查看文档、图片、语音、视频
- **图片生成**：生成图片、参考图编辑、结果回流资源库
- **设置**：调整主题、模块开关、连接与高级选项
| 状态 | 说明 |
|------|------|
| 🟢 运行中 | API Server 正在运行，可以接收请求 |
| 🔴 已停止 | API Server 未启动 |
| 🟡 启动中 | 服务正在初始化 |
## 推荐工作方式
## 控制按钮
1. 先在项目中选择一个创作主题
2. 在 AI Agent 中完成结构和首稿
3. 需要视觉时进入图片生成
4. 回到资源库统一管理结果
- **启动服务**: 启动 API Server
- **停止服务**: 停止 API Server
- **重启服务**: 重新启动服务
## 创作主题
## API 信息
当前支持的主题包括：
服务运行时显示：
- 通用对话
- 社媒内容
- 图文海报
- 歌词曲谱
- 知识探索
- 计划规划
- 办公文档
- 短视频
- 小说创作
- **API 地址**: 本地 API 端点（如 `http://127.0.0.1:8999`）
- **API Key**: 当前配置的访问密钥
- **复制按钮**: 一键复制 API 地址或 Key
## 常见操作
## API 测试面板
### 新建一个创作项目
内置的 API 测试工具：
1. 进入项目页
2. 选择主题并创建项目
3. 开始持续沉淀对话与素材
1. **消息输入**: 输入测试消息
2. **模型选择**: 选择要使用的模型
3. **发送请求**: 点击发送测试请求
4. **响应显示**: 查看 AI 响应结果
### 从资源继续创作
### 测试示例
1. 在资源页选中历史文档或图片
2. 跳转到 AI Agent 继续改写或扩展
3. 将新结果再次沉淀回资源库
```
用户: 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
+29 -129
View File
@@ -1,150 +1,50 @@
---
title: Prompts 管理
description: 提示词存储和管理
title: 提示词模板
description: 管理可复用提示词，提升稳定产出效率
navigation:
icon: i-heroicons-document-text
---
# Prompts 管理
# 提示词模板
Prompts 功能帮助你存储、组织和复用常用的提示词模板。
提示词模板用于把“经常重复的表达方式”沉淀下来，减少每次从零开始。
## 提示词存储
## 模板结构建议
### 创建提示词
每个模板建议包含：
1. 进入 **Prompts** 页面
2. 点击 **新建提示词**
3. 填写提示词信息：
- 名称（便于检索）
- 使用场景（何时用）
- 模板正文（可复用）
- 变量占位（可选）
| 字段 | 说明 |
|------|------|
| 名称 | 提示词标识名称 |
| 描述 | 提示词用途说明 |
| 内容 | 提示词正文 |
| 标签 | 分类标签 |
## 示例：短视频口播模板
### 提示词示例
```yaml
name: "代码审查"
description: "审查代码质量和最佳实践"
content: |
请审查以下代码，关注：
1. 代码质量和可读性
2. 潜在的 bug 和安全问题
3. 性能优化建议
4. 最佳实践遵循情况
请提供具体的改进建议。
tags:
- 代码
- 审查
```text
你是一名内容策划。
请基于主题「{{topic}}」生成一段 {{duration}} 秒口播稿，要求：
1. 开头 3 秒有抓力
2. 中段给出 3 个关键点
3. 结尾有明确行动引导
语气风格：{{tone}}
```
## 组织方式
## 推荐组织方式
### 文件夹分类
- 按主题分类：社媒、短视频、小说、办公
- 按阶段分类：灵感、初稿、润色、发布
- 统一标签：例如 `#高频`、`#可复用`
创建文件夹组织提示词：
## 使用建议
- 📁 代码相关
- 代码审查
- 代码重构
- 单元测试
- 📁 写作相关
- 文档撰写
- 邮件回复
- 📁 翻译相关
- 中英翻译
- 技术翻译
### 一次只优化一个模板
### 标签系统
避免同时改太多模板，难以判断效果。
使用标签快速筛选：
### 模板要留“可变空间”
- `#代码` - 代码相关提示词
- `#写作` - 写作相关提示词
- `#常用` - 常用提示词
把固定规则写清楚，把创意部分留给变量。
### 搜索功能
### 和项目结合
支持按以下条件搜索：
- 名称
- 描述
- 内容
- 标签
## 注入请求
### 系统提示词
将提示词作为系统消息注入：
```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
+35 -151
View File
@@ -1,171 +1,55 @@
---
title: Skills 技能
description: 可扩展的技能模块系统
title: 技能工作流
description: 把常见任务封装成可复用的 AI 技能
navigation:
icon: i-heroicons-sparkles
---
# Skills 技能
# 技能工作流
Skills 是预定义的 AI 交互模式，封装了特定任务的提示词、参数和工具配置。
技能可以理解为“可复用的任务卡片”：
## 技能定义
- 预设目标
- 预设风格
- 预设步骤
### 什么是技能
这样每次执行同类任务时，不必重复手工组织提示。
技能是一个完整的 AI 交互配置包，包含：
## 技能适合做什么
- 系统提示词
- 参数配置
- 工具绑定
- 输出格式
- 固定流程写作（如周报、复盘、活动文案）
- 固定结构产出（如短视频脚本、小说章节骨架）
- 固定标准检查（如发布前检查清单）
### 技能示例
## 技能卡建议字段
- 名称：明确任务类型
- 描述：写清输入与输出
- 系统指令：定义角色与规则
- 参数：控制风格与长度
- 输出格式：约束结果结构
## 示例：活动文案技能
```yaml
name: "代码解释器"
description: "解释代码功能和逻辑"
name: "活动文案生成"
description: "根据主题生成活动预热文案与发布文案"
system_prompt: |
你是一个代码解释专家。请详细解释用户提供的代码：
1. 代码的整体功能
2. 关键逻辑的解释
3. 使用的设计模式
4. 潜在的改进点
parameters:
temperature: 0.3
max_tokens: 2000
output_format: markdown
你是一名品牌内容策划，输出要简洁、有行动感。
output_format: "markdown"
```
## 创建技能
## 组合为流程
### 新建技能
你可以把多个技能串成流程，例如：
1. 进入 **Skills** 页面
2. 点击 **新建技能**
3. 配置技能信息
1. 选题拆解
2. 初稿生成
3. 风格统一
4. 发布前检查
### 配置选项
## 团队使用建议
| 字段 | 说明 |
|------|------|
| 名称 | 技能标识名称 |
| 描述 | 技能用途说明 |
| 系统提示词 | 技能的核心提示词 |
| 参数 | 模型参数配置 |
| 工具 | 绑定的 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:8999/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` 文件
- **导入**: 从文件导入技能
1. 共享高频技能模板
2. 每个技能指定维护人
3. 定期清理低使用技能，保持列表可维护
docs/content/02.user-guide/12.settings.md
+34 -115
View File
@@ -1,141 +1,60 @@
---
title: 设置
description: 应用设置和偏好管理
description: 管理应用偏好、导航模块和进阶系统选项
navigation:
icon: i-heroicons-cog-6-tooth
---
# 设置
设置页面用于配置 ProxyCast 的各项参数和偏好。
设置页用于管理你的创作体验与系统行为。
## 通用设置
## 通用
### 应用行为
常见选项：
| 选项 | 说明 |
|------|------|
| 开机自启动 | 系统启动时自动运行 ProxyCast |
| 启动时运行服务 | 应用启动时自动启动 API Server |
| 最小化到托盘 | 关闭窗口时最小化到系统托盘 |
| 显示托盘图标 | 在系统托盘显示图标 |
- 主题模式（浅色 / 深色 / 跟随系统）
- 语言选择
- 启动行为（开机自启动、最小化到托盘）
- 声音反馈开关
### 更新设置
## 创作与导航偏好
| 选项 | 说明 |
|------|------|
| 自动检查更新 | 定期检查新版本 |
| 自动下载更新 | 有新版本时自动下载 |
| 更新通知 | 有更新时显示通知 |
你可以按使用习惯定制入口：
## 认证目录
- 启用或停用创作主题（如社媒、短视频、小说）
- 启用或停用导航模块（如 AI Agent、项目、图片生成、终端、工具、插件）
### 默认凭证路径
这样可以让侧边栏更聚焦，减少干扰。
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"
```
## 建议配置
## 偏好管理
### 个人创作者
### 主题设置
- 保留：AI Agent、项目、资源、图片生成
- 关闭：暂时不用的高级模块
- 目的：让工作台聚焦在“日常产出”
| 选项 | 说明 |
|------|------|
| 浅色模式 | 使用浅色主题 |
| 深色模式 | 使用深色主题 |
| 跟随系统 | 跟随系统主题设置 |
### 团队协作
### 语言设置
支持的语言：
- 简体中文
- 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/13.plugins.md
+26 -38
View File
@@ -1,35 +1,28 @@
---
title: 插件中心
description: 安装和管理扩展插件，按需扩展创作能力
navigation:
icon: i-heroicons-puzzle-piece
---
# 插件中心
::alert{type="info"}
📢 本文档已迁移至开放平台。请访问 [开放平台 - 插件中心](/open-platform/plugins) 获取最新内容。
📢 插件属于进阶能力。若你只做日常创作，可先跳过本页。
::
ProxyCast 支持通过插件扩展功能。插件中心提供插件的安装、管理和配置。
插件中心用于扩展 ProxyCast 的能力，例如新增工具、接入外部流程、扩展特定场景工作流。
## 访问插件中心
点击左侧导航栏的「插件中心」进入插件管理页面。
## 功能概览
## 你能做什么
### 推荐插件
插件中心会显示推荐的插件列表，点击「一键安装」即可快速安装。
### 已安装插件
显示所有已安装的插件，包括：
- 插件名称和版本
- 安装来源（本地/URL/GitHub）
- 启用/禁用状态
- 卸载按钮
### 已加载插件
显示当前运行中的插件状态：
- 执行次数
- 错误次数
- 最后执行时间
- 浏览推荐插件并一键安装
- 通过本地文件或 URL 安装插件包
- 管理启用状态与卸载
- 查看插件加载与执行状态
## 安装插件
@@ -56,22 +49,19 @@ ProxyCast 支持通过插件扩展功能。插件中心提供插件的安装、
3. 选择本地的 `.zip` 文件
4. 点击「安装」
## 使用插件
## 使用建议
安装完成后，插件会根据类型出现在不同位置：
### 从小处开始
### 工具类插件
先安装 1 到 2 个高频插件，观察是否真正提升你的创作效率，再决定是否扩展更多插件。
工具类插件会出现在「工具箱」页面：
### 明确用途
1. 点击左侧导航栏的「工具」
2. 在工具列表中找到已安装的插件
3. 点击「打开工具」使用
每个插件都应对应明确目的，例如：
### 其他类型插件
- **Hook 插件**: 自动在请求/响应时执行
- **侧边栏插件**: 出现在主侧边栏（规划中）
- 扩展素材处理
- 增加内容生成模板
- 对接外部工作流
## 管理插件
@@ -87,13 +77,11 @@ ProxyCast 支持通过插件扩展功能。插件中心提供插件的安装、
卸载会删除插件文件和配置，但不会删除插件产生的数据。
## 二进制组件
## 进阶阅读
部分功能需要安装额外的二进制组件：
- **aster-server**: AI Agent 框架，提供 Agent 对话能力
在「二进制组件」区域可以查看和管理这些组件。
- [开放平台 - 总览](/open-platform/overview)
- [开放平台 - 插件中心](/open-platform/plugins)
- [开放平台 - 插件开发](/open-platform/plugin-development)
## 常见问题
docs/content/02.user-guide/14.resources.md
+65
View File
@@ -0,0 +1,65 @@
---
title: 资源库
description: 管理项目中的文档、图片、语音和视频素材
navigation:
icon: i-heroicons-folder-open
---
# 资源库
资源库是 ProxyCast 的创作资产中心。
它和项目绑定，用来长期沉淀你的创作结果。
## 资源分类
资源页支持按分类查看：
- 全部
- 文档
- 图片
- 语音
- 视频
当你只想找图或找文档时，直接切换分类即可。
## 常见操作
### 新建与上传
1. 选择左侧资源库（项目）
2. 新建文件夹或新建文档
3. 上传本地文件到当前目录
### 搜索与排序
- 支持按名称、描述、标签搜索
- 支持按更新时间、创建时间、名称排序
### 重命名与删除
在资源列表的操作菜单中，可对资源进行重命名、删除等操作。
## 资源与创作联动
### 从图片生成回流资源库
在图片生成页选择目标资源库后，成功生成的图片可自动写入当前项目。
### 从资源继续对话创作
在资源页选中素材后，可继续进入 AI Agent 进行改写、扩写或二次创作。
## 常见问题
### 为什么看不到某些图片？
先确认：
1. 当前选择的是否是正确资源库（项目）
2. 是否切到了“图片”分类
3. 文件后缀或 MIME 类型是否被识别为图片
### 为什么资源数量和预期不一致？
常见原因是“分类过滤”或“项目切换”导致显示范围变化。
建议先切换到“全部”分类再确认总量。
docs/content/02.user-guide/15.image-generation.md
+60
View File
@@ -0,0 +1,60 @@
---
title: 图片生成与编辑
description: 通过文本与参考图完成图片生成、编辑与资产沉淀
navigation:
icon: i-heroicons-photo
---
# 图片生成与编辑
图片生成页用于完成从“文字描述”到“可用图片素材”的全过程。
## 基本流程
1. 选择模型与参数（尺寸、比例、数量）
2. 输入提示词
3. 可选上传参考图
4. 生成后选图并沉淀到资源库
## 参考图与编辑
### 上传参考图
可上传参考图作为创作输入，帮助模型更贴近目标风格或构图。
### 编辑链路
当模型支持图片编辑接口时，系统会优先尝试编辑端点；
若不可用，会自动回退到可用生成端点，尽量保障出图成功率。
## 历史记录
历史区域会保存你的生成记录，支持：
- 查看单张或批次结果
- 重新选择目标图继续迭代
- 将历史结果补录到资源库
## 与资源库联动
### 目标资源库
生成前可指定目标资源库（项目），用于自动沉淀图片资产。
### 补录历史
如果历史图片尚未入库，可使用“补录历史到资源库”进行批量回填。
## 实用建议
### 先定方向再出图
先在 AI Agent 里明确画面目标，再进入图片生成功能，会减少无效尝试。
### 一次只改一个变量
每轮仅调整一个维度（提示词、比例、参考图），更容易稳定收敛到理想结果。
### 把可用版本及时入库
选中可用图片后尽快入库，方便后续在资源页检索和复用。
docs/content/02.user-guide/2.monitoring.md
+34 -76
View File
@@ -1,103 +1,61 @@
---
title: 监控中心
description: 请求统计和性能监控
title: 创作数据与监控
description: 查看创作产出趋势、调用状态与问题定位信息
navigation:
icon: i-heroicons-eye
---
# 监控中心
# 创作数据与监控
监控中心提供详细的请求统计、性能指标和日志查看功能。
监控页帮助你回答三个问题：
## 监控界面
1. 最近创作是否稳定
2. 哪些任务成功率更高
3. 出现异常时该从哪里排查
### 概览面板
## 你能看到什么
显示关键指标的实时数据：
### 概览指标
- **请求总数**: 今日/本周/本月请求量
- **成功率**: 请求成功百分比
- **平均延迟**: 响应时间统计
- **活跃凭证**: 当前可用凭证数量
常见指标包括：
### 图表展示
- 请求总量与成功率
- 平均响应耗时
- 活跃连接数量
- 近期错误趋势
- **请求趋势图**: 按时间显示请求量变化
- **延迟分布图**: 响应时间分布
- **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 消耗
- 平均响应时间
1. 找到失败时间点
2. 查看模型与请求参数
3. 对照错误信息定位问题（超时、认证、限流等）
## Token 使用追踪
## 对创作者最有用的用法
### 使用量统计
### 判断工作流是否健康
| 指标 | 说明 |
|------|------|
| 输入 Token | 请求消息的 Token 数 |
| 输出 Token | 响应消息的 Token 数 |
| 总计 Token | 输入 + 输出 |
如果成功率持续下降，建议先减少并发任务，确认连接状态后再恢复批量生成。
### 按时间段查看
### 对比不同创作任务
- 今日使用量
- 本周使用量
- 本月使用量
- 自定义时间范围
同样是生成任务，不同主题的耗时差异可能很大。通过趋势图可以更快选择稳定方案。
## 请求日志
### 复盘高峰时段
### 日志列表
高峰期（例如集中出图）出现波动时，可根据日志回看是否需要拆分任务批次。
每条日志包含：
## 数据导出
| 字段 | 说明 |
|------|------|
| 时间 | 请求时间戳 |
| 模型 | 请求的模型名称 |
| Provider | 实际使用的 Provider |
| 状态 | 成功/失败 |
| 延迟 | 响应时间 |
| Token | Token 使用量 |
### 日志过滤
支持按以下条件过滤：
- 时间范围
- Provider
- 模型
- 状态（成功/失败）
### 日志详情
点击日志条目查看详细信息：
- 完整请求内容
- 完整响应内容
- 错误信息（如有）
- 请求头信息
## 导出数据
支持导出统计数据：
- CSV 格式
- JSON 格式
- 自定义时间范围
如果你需要做团队复盘，可导出统计数据用于周报或复盘记录。
docs/content/02.user-guide/3.credential-pool.md
+31 -106
View File
@@ -1,130 +1,55 @@
---
title: 凭证池
description: 管理多个 AI 服务凭证
title: 模型连接与账号
description: 管理模型连接方式与多账号状态（进阶）
navigation:
icon: i-heroicons-key
---
# 凭证池
# 模型连接与账号
凭证池用于管理多个 AI 服务凭证，支持负载均衡和故障转移。
::alert{type="info"}
这是进阶页。普通创作者可直接使用默认连接能力，按需再回来配置。
::
## 池管理界面
该页面用于管理模型连接与账号状态，适合以下场景：
### 凭证列表
- 你有多个账号需要统一管理
- 你需要手动添加 API Key
- 你希望在连接异常时快速排查
显示所有已添加的凭证：
| 字段 | 说明 |
|------|------|
| 名称 | 凭证标识名称 |
| 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. 保存后执行连接测试
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（可选）
保留 1 到 2 个稳定账号即可，优先保证可用性。
## 负载均衡配置
### 高强度创作
### 策略选择
如果你需要长时间连续生成，可配置多个账号做冗余，降低单点失败影响。
| 策略 | 说明 |
|------|------|
| 轮询 (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 中移除。
::
1. 不在聊天记录或公开文档里粘贴密钥
2. 定期清理失效连接
3. 导出配置时确认敏感信息不会被带出
docs/content/02.user-guide/4.configuration-example.md
+63 -326
View File
@@ -1,342 +1,79 @@
---
title: 完整配置示例
description: ProxyCast 完整 YAML 配置示例
title: 进阶配置示例
description: 按创作场景选择配置思路（示例）
navigation:
icon: i-heroicons-document-text
---
# 完整配置示例
# 进阶配置示例
本文档提供 ProxyCast 的完整 YAML 配置示例，包含所有新增功能。
::alert{type="info"}
本页示例用于说明配置思路，不要求你逐字段照抄。具体字段以应用设置界面为准。
::
## 基础配置
## 示例 1：个人创作者（推荐起步）
目标：少配置、快开始。
```yaml
# 服务器配置
server:
profile: "solo-creator"
navigation:
enabled:
- agent
- projects
- resources
- image-gen
themes:
enabled:
- social-media
- video
- novel
```
适用：自媒体、短视频、小说日更。
## 示例 2：团队协作
目标：统一入口和主题，降低沟通成本。
```yaml
profile: "team-content"
navigation:
enabled:
- agent
- projects
- resources
- tools
themes:
enabled:
- social-media
- poster
- document
resource:
naming: "project-date-version"
```
适用：品牌运营、活动策划、小团队协作。
## 示例 3：进阶接入
目标：在保留创作工作台的同时开放 API 给外部工具。
```yaml
profile: "creator-plus-api"
api_server:
enabled: true
host: "127.0.0.1"
port: 8999
api_key: "your-api-key"
# TLS/HTTPS 配置
tls:
enable: false
cert_path: "/path/to/cert.pem"
key_path: "/path/to/key.pem"
# 注意：当前版本暂不支持 TLS。启用后服务将无法启动，请使用反向代理做 TLS 终止。
# 全局代理 URL（支持 socks5/http/https）
proxy_url: "socks5://127.0.0.1:1080"
# 认证目录（存储 OAuth Token 文件）
auth_dir: "~/.proxycast/auth"
```
## 远程管理配置
```yaml
# 远程管理 API 配置
remote_management:
# 是否允许远程访问（非 localhost）
allow_remote: false
# 管理 API 密钥（为空时禁用管理 API）
secret_key: "your-secret-key"
# 是否禁用控制面板
disable_control_panel: false
```
## 配额超限配置
```yaml
# 配额超限自动切换策略
quota_exceeded:
# 是否自动切换到下一个凭证
switch_project: true
# 是否尝试使用预览模型
switch_preview_model: true
# 冷却时间（秒）
cooldown_seconds: 300
```
## Amp CLI 集成配置
```yaml
# Amp CLI 配置
ampcode:
# 上游 URL
upstream_url: "https://ampcode.com"
# 是否限制管理端点只能从 localhost 访问
restrict_management_to_localhost: false
# 模型映射列表
model_mappings:
- from: "claude-opus-4.5"
to: "claude-sonnet-4"
- from: "gpt-5"
to: "gemini-2.5-pro"
- from: "claude-3-opus-20240229"
to: "claude-3-5-sonnet-20241022"
```
## 凭证池配置
### OAuth Provider
```yaml
credential_pool:
# Kiro OAuth 凭证
kiro:
- id: "kiro-main"
token_file: "kiro/main-token.json"
disabled: false
proxy_url: "socks5://proxy1:1080" # 可选：单独代理
- id: "kiro-backup"
token_file: "kiro/backup-token.json"
disabled: false
# Gemini OAuth 凭证
gemini:
- id: "gemini-main"
token_file: "gemini/oauth_creds.json"
disabled: false
# Qwen OAuth 凭证
qwen:
- id: "qwen-main"
token_file: "qwen/oauth_creds.json"
disabled: false
# Codex OAuth 凭证
codex:
- id: "codex-main"
token_file: "codex/oauth.json"
proxy_url: "http://proxy2:8080"
```
### iFlow Provider
```yaml
credential_pool:
# iFlow 凭证（支持 OAuth 和 Cookie）
iflow:
# OAuth 模式
- id: "iflow-oauth"
token_file: "iflow/oauth.json"
auth_type: "oauth"
disabled: false
# Cookie 模式
- id: "iflow-cookie"
auth_type: "cookie"
cookies: "session_id=abc123; auth_token=xyz789"
disabled: false
```
### API Key Provider
```yaml
credential_pool:
# OpenAI API Key
openai:
- id: "openai-main"
api_key: "sk-xxx..."
base_url: "https://api.openai.com/v1"
disabled: false
proxy_url: "http://proxy:8080"
# Claude API Key
claude:
- id: "claude-main"
api_key: "sk-ant-xxx..."
base_url: "https://api.anthropic.com"
disabled: false
```
### Gemini API Key 多账号
```yaml
credential_pool:
# Gemini API Key 多账号负载均衡
gemini_api_keys:
- id: "gemini-key-1"
api_key: "AIzaSy...01"
base_url: "https://generativelanguage.googleapis.com"
proxy_url: "socks5://proxy1:1080"
excluded_models:
- "gemini-2.5-pro" # 排除特定模型
- "gemini-2.5-*" # 通配符前缀匹配
- "*-preview" # 通配符后缀匹配
disabled: false
- id: "gemini-key-2"
api_key: "AIzaSy...02"
disabled: false
```
### Vertex AI Provider
```yaml
credential_pool:
# Vertex AI 凭证
vertex_api_keys:
- id: "vertex-main"
api_key: "vk-123..."
base_url: "https://example.com/api"
proxy_url: "socks5://proxy:1080"
# 模型别名映射
models:
- name: "gemini-2.0-flash"
alias: "vertex-flash"
- name: "gemini-1.5-pro"
alias: "vertex-pro"
disabled: false
```
## 路由配置
```yaml
# 路由配置
auth: "api-key"
routing:
# 默认 Provider
default_provider: "kiro"
# 路由规则
rules:
- pattern: "claude-*"
provider: "kiro"
priority: 1
- pattern: "gemini-*"
provider: "gemini"
priority: 2
- pattern: "gpt-*"
provider: "openai"
priority: 3
# 模型别名
model_aliases:
"claude-latest": "claude-sonnet-4-5-20250514"
"gemini-latest": "gemini-2.5-pro"
# 排除列表
exclusions:
kiro:
- "claude-3-opus-*"
gemini:
- "gemini-1.0-*"
fallback: true
```
## 重试配置
适用：有脚本联动、自动化流程需求的用户。
```yaml
# 重试配置
retry:
max_retries: 3
base_delay_ms: 1000
max_delay_ms: 30000
auto_switch_provider: true
```
## 调整顺序建议
## 日志配置
```yaml
# 日志配置
logging:
enabled: true
level: "info"
retention_days: 7
include_request_body: false
```
## 参数注入配置
```yaml
# 参数注入配置
injection:
enabled: true
rules:
- id: "thinking-budget"
pattern: "gemini-2.5-*"
parameters:
generationConfig:
thinkingConfig:
thinkingBudget: 32768
mode: "default" # default: 仅在参数缺失时设置
priority: 1
enabled: true
- id: "reasoning-effort"
pattern: "gpt-*"
parameters:
reasoning:
effort: "high"
mode: "override" # override: 总是覆盖
priority: 2
enabled: true
```
## 完整配置示例
以下是一个完整的配置文件示例：
```yaml
# ProxyCast 完整配置示例
server:
host: "127.0.0.1"
port: 8999
api_key: "your-api-key"
tls:
enable: false
cert_path: ""
key_path: ""
proxy_url: ""
auth_dir: "~/.proxycast/auth"
remote_management:
allow_remote: false
secret_key: ""
disable_control_panel: false
quota_exceeded:
switch_project: true
switch_preview_model: true
cooldown_seconds: 300
ampcode:
upstream_url: ""
restrict_management_to_localhost: false
model_mappings: []
credential_pool:
kiro:
- id: "kiro-main"
token_file: "kiro/main-token.json"
disabled: false
gemini: []
qwen: []
openai: []
claude: []
gemini_api_keys: []
vertex_api_keys: []
codex: []
iflow: []
routing:
default_provider: "kiro"
rules: []
model_aliases: {}
exclusions: {}
retry:
max_retries: 3
base_delay_ms: 1000
max_delay_ms: 30000
auto_switch_provider: true
logging:
enabled: true
level: "info"
retention_days: 7
include_request_body: false
injection:
enabled: false
rules: []
```
1. 先确认导航与主题
2. 再确认连接与稳定性
3. 最后再做 API 与自动化扩展
docs/content/02.user-guide/4.smart-routing.md
+38 -114
View File
@@ -1,142 +1,66 @@
---
title: 智能路由
description: 配置请求路由规则
title: 模型分发规则
description: 按任务类型将请求分发到不同模型（进阶）
navigation:
icon: i-heroicons-arrows-right-left
---
# 智能路由
# 模型分发规则
智能路由允许你根据模型名称将请求定向到特定的 Provider。
::alert{type="info"}
这是进阶能力。只有在“多模型并行使用”时才需要配置。
::
## 模型映射
分发规则用于把不同任务自动交给更合适的模型。
### 映射规则
## 什么时候需要它
将请求中的模型名称映射到实际的 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
- pattern: "video-script-*"
provider: "primary"
model: "high-quality-model"
priority: 10
# 优先级 50：前缀匹配
- pattern: "gpt-4*"
provider: kiro-claude
priority: 50
# 优先级 100：默认规则
- pattern: "quick-*"
provider: "fast-lane"
model: "fast-model"
priority: 20
- pattern: "*"
provider: gemini-cli
provider: "fallback"
priority: 100
```
## 默认回退
## 配置建议
### 无规则匹配时
1. 先只配 2 到 3 条关键规则
2. 给兜底规则留最后优先级
3. 每次改完都做一次路由测试
当请求的模型不匹配任何规则时：
## 常见误区
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
+39 -116
View File
@@ -1,145 +1,68 @@
---
title: 容错配置
description: 重试、超时和故障转移设置
title: 稳定性与容错
description: 在高强度创作下保持调用稳定（进阶）
navigation:
icon: i-heroicons-shield-check
---
# 容错配置
# 稳定性与容错
容错配置帮助你的应用优雅地处理 API 故障，确保服务稳定性。
::alert{type="info"}
这是进阶能力。只有在你频繁遇到超时、失败、波动时才需要细调。
::
## 重试机制
稳定性配置的核心目标是：
### 重试配置
- 少失败
- 失败后可恢复
- 出错时可定位
| 选项 | 默认值 | 说明 |
|------|--------|------|
| 最大重试次数 | 3 | 失败后重试的最大次数 |
| 初始延迟 | 1s | 首次重试前的等待时间 |
| 最大延迟 | 30s | 重试延迟的上限 |
| 退避倍数 | 2 | 每次重试延迟的增长倍数 |
## 三个关键参数
### 退避策略
### 重试
```
第1次重试: 1s
第2次重试: 2s
第3次重试: 4s
...
```
用于处理偶发失败。
### 可重试错误
建议：
以下错误会触发重试：
- 最大重试次数：2 到 3 次
- 首次重试延迟：1 秒左右
- 使用递增退避，避免短时间反复打满请求
- 网络超时
- 连接失败
- 5xx 服务器错误
- 429 速率限制
### 超时
不重试的错误：
用于避免单次请求长时间卡住。
- 4xx 客户端错误（除 429）
- 认证失败
- 无效请求
建议：
## 超时设置
- 普通文本任务：较短超时
- 长文或复杂任务：适当放宽
- 图片任务：通常需要更长超时
### 超时配置
### 故障回退
| 选项 | 默认值 | 说明 |
|------|--------|------|
| 连接超时 | 10s | 建立连接的超时时间 |
| 请求超时 | 120s | 整个请求的超时时间 |
| 流式超时 | 300s | 流式响应的超时时间 |
主连接失败后自动走备用连接，减少中断。
### 按 Provider 配置
## 推荐调参顺序
可以为不同 Provider 设置不同的超时：
1. 先调超时
2. 再调重试
3. 最后配置回退策略
```yaml
timeouts:
default:
connect: 10s
request: 120s
kiro-claude:
request: 180s # Claude 响应较慢
gemini-cli:
request: 60s # Gemini 响应较快
```
## 诊断建议
## 故障转移
### 连续失败
### 自动故障转移
优先检查：
当主 Provider 失败时，自动切换到备用 Provider：
1. 连接状态是否可用
2. 当前模型是否可调用
3. 是否触发限流
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
+35 -145
View File
@@ -1,173 +1,63 @@
---
title: 配置管理
description: 导出和导入配置
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: 8999
```
### 敏感信息处理
- 主题与导航偏好
- 部分连接与路由策略
- 稳定性相关参数
::alert{type="warning"}
导出的配置**不包含**凭证信息（Token、API Key）。导入后需要重新配置凭证。
导出文件通常不包含敏感凭证信息。导入后需重新检查连接状态。
::
## 导入配置
### 导入步骤
1. 在设置页选择导入
2. 预览配置差异
3. 选择覆盖或合并策略
4. 导入后做一次连接与功能自检
1. 进入 **设置** > **配置管理**
2. 点击 **导入配置**
3. 选择 `.yaml` 配置文件
4. 预览导入内容
5. 确认导入
## 备份建议
### 冲突解决
### 个人用户
当导入的配置与现有配置冲突时：
至少保留最近 2 到 3 份配置备份。
| 选项 | 说明 |
|------|------|
| 覆盖 | 用导入的配置替换现有配置 |
| 跳过 | 保留现有配置，跳过冲突项 |
| 合并 | 合并两个配置（仅适用于列表类型） |
### 团队用户
### 验证导入
建议按版本管理配置文件，例如：
导入前会验证：
- `team-config-v1.yaml`
- `team-config-v1.1.yaml`
- YAML 语法正确性
- 配置版本兼容性
- 必填字段完整性
## 跨设备迁移清单
## .env 格式导出
1. 导出配置文件
2. 在新设备导入配置
3. 重新校验连接状态
4. 检查主题、导航、资源路径是否符合预期
5. 进行一次完整创作演练
### 用途
## 什么时候需要重置
导出为 `.env` 格式，方便在其他工具中使用：
当你长期调参后“越调越乱”，最稳妥的方式是：
- 脚本调用
- Docker 环境
- CI/CD 配置
### 导出内容
```bash
# ProxyCast API Configuration
PROXYCAST_API_BASE=http://127.0.0.1:8999/v1
PROXYCAST_API_KEY=your-api-key
# OpenAI Compatible
OPENAI_API_BASE=http://127.0.0.1:8999/v1
OPENAI_API_KEY=your-api-key
# Claude Compatible
ANTHROPIC_API_BASE=http://127.0.0.1:8999
ANTHROPIC_API_KEY=your-api-key
```
### 导出步骤
1. 进入 **设置** > **配置管理**
2. 点击 **导出 .env**
3. 选择保存位置
## 配置备份
### 自动备份
ProxyCast 会自动备份配置：
- 每次修改后自动保存
- 保留最近 10 个版本
- 备份位置：`~/.proxycast/backups/`
### 恢复备份
1. 进入 **设置** > **配置管理**
2. 点击 **备份历史**
3. 选择要恢复的版本
4. 点击 **恢复**
## 完整备份与恢复（生产建议）
仅导出配置无法覆盖数据库与凭证文件。生产环境建议定期备份以下路径：
- 配置文件：macOS `~/Library/Application Support/proxycast/config.yaml`；Linux `~/.config/proxycast/config.yaml`；Windows `%APPDATA%\\proxycast\\config.yaml`
- 凭证副本目录：macOS `~/Library/Application Support/proxycast/credentials/`；Linux `~/.local/share/proxycast/credentials/`；Windows `%APPDATA%\\proxycast\\credentials\\`
- 数据库与日志：`~/.proxycast/`（含 `proxycast.db`、`logs/`、`request_logs/`、`auth/`）
```bash
# 示例：备份数据库与日志目录
cp -a ~/.proxycast ~/.proxycast.backup-$(date +%Y%m%d%H%M%S)
```
恢复时将备份内容替换回原路径，并确保应用已退出。
## 旧版本迁移说明
如果检测到旧版 `~/.proxycast/config.json`，当前版本会阻止启动并提示手动迁移。请先导出旧配置或重新导入 YAML 配置，再启动应用。
## 配置同步
### 跨设备同步
通过导出/导入实现跨设备配置同步：
1. 在设备 A 导出配置
2. 将配置文件传输到设备 B
3. 在设备 B 导入配置
4. 重新配置凭证
1. 先备份当前配置
2. 恢复到基础配置
3. 只按必要场景逐项开启进阶能力
docs/content/02.user-guide/7.config-switch.md
+29 -131
View File
@@ -1,152 +1,50 @@
---
title: 配置切换
description: 快速切换 AI 客户端配置
title: 工作模式切换
description: 在不同创作场景间快速切换配置
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. 该档案成为当前活动配置
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
```
1. 档案数量控制在 3 个以内
2. 一个档案只服务一个明确场景
3. 变更档案后记录用途，避免后续混乱
docs/content/02.user-guide/8.api-server.md
+25 -140
View File
@@ -1,167 +1,52 @@
---
title: API Server
description: 配置和管理 API 服务
title: 本地 API 接入
description: 将 ProxyCast 能力暴露给外部工具（进阶）
navigation:
icon: i-heroicons-server
---
# API Server
# 本地 API 接入
API Server 是 ProxyCast 的核心组件，提供 OpenAI/Claude 兼容的 API 端点。
## 服务器配置
### 基本配置
| 选项 | 默认值 | 说明 |
|------|--------|------|
| 主机地址 | `127.0.0.1` | 监听地址 |
| 端口 | `8999` | 监听端口 |
| API Key | 自动生成 | 访问密钥 |
### 配置步骤
1. 进入 **设置** > **API Server**
2. 修改配置选项
3. 点击 **保存**
4. 重启服务生效
### 监听地址
| 地址 | 说明 |
|------|------|
| `127.0.0.1` | 仅本机访问 |
| `localhost` | 仅本机访问 |
::alert{type="warning"}
当前版本仅支持本地监听（127.0.0.1/localhost/::1），不支持对外开放。
::alert{type="info"}
这是进阶能力。普通创作者可以不配置，直接在应用内完成创作。
::
## API 端点
当你希望把 ProxyCast 接入脚本、自动化工具或第三方客户端时，可启用本地 API。
### OpenAI 兼容端点
## 核心说明
| 端点 | 方法 | 说明 |
|------|------|------|
| `/v1/chat/completions` | POST | 聊天补全 |
| `/v1/models` | GET | 模型列表 |
| `/v1/embeddings` | POST | 文本嵌入 |
- 服务默认在本地地址运行
- 通过 API Key 控制访问
- 支持常见兼容接口形态
### Claude 兼容端点
## 快速配置
| 端点 | 方法 | 说明 |
|------|------|------|
| `/v1/messages` | POST | 消息 API |
| `/v1/messages/count_tokens` | POST | Token 计数 |
## 请求日志
### 日志查看
1. 进入 **监控中心**
2. 查看 **请求日志** 标签
3. 实时显示所有请求
### 日志内容
每条日志包含：
- 时间戳
- 请求方法和路径
- 请求模型
- 响应状态
- 响应时间
- Token 使用量
### 日志过滤
支持按以下条件过滤：
- 时间范围
- 状态码
- 模型名称
- Provider
## 访问控制
### API Key 认证
启用 API Key 认证：
1. 进入 **设置** > **API Server**
2. 开启 **启用认证**
1. 进入设置中的 API Server
2. 开启服务并确认端口
3. 设置或生成 API Key
4. 保存配置
4. 使用一条测试请求验证连通性
### 请求认证
## 最小测试示例
请求时需要携带 API Key：
**OpenAI 格式:**
```bash
curl http://127.0.0.1:8999/v1/chat/completions \
-H "Authorization: Bearer your-api-key" \
-H "Content-Type: application/json" \
-d '{"model": "gpt-4", "messages": [...]}'
-d '{"model":"your-model","messages":[{"role":"user","content":"你好"}]}'
```
**Claude 格式:**
```bash
curl http://127.0.0.1:8999/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
1. 只在本机环境使用
2. 不要把 API Key 提交到代码仓库
3. 定期更换密钥并清理无效连接
支持配置多个 API Key：
## 常见问题
```yaml
auth:
keys:
- name: "开发环境"
key: "dev-key-xxx"
- name: "生产环境"
key: "prod-key-xxx"
```
### 启动后无法访问
## CORS 配置
先确认端口未被占用，再检查本地防火墙策略。
### 跨域设置
### 请求总是 401
| 选项 | 默认值 | 说明 |
|------|--------|------|
| 允许来源 | `*` | 允许的请求来源 |
| 允许方法 | `GET,POST,OPTIONS` | 允许的 HTTP 方法 |
| 允许头部 | `*` | 允许的请求头 |
### 配置示例
```yaml
cors:
origins:
- "http://localhost:3000"
- "https://myapp.com"
methods:
- GET
- POST
headers:
- Authorization
- Content-Type
```
## 服务管理
### 启动/停止
- **启动**: 点击仪表盘的 **启动服务** 按钮
- **停止**: 点击 **停止服务** 按钮
- **重启**: 点击 **重启服务** 按钮
### 开机自启
1. 进入 **设置** > **通用**
2. 开启 **开机自动启动**
3. 开启 **启动时自动运行服务**
通常是 API Key 填写错误或请求头格式不正确。
docs/content/02.user-guide/9.mcp.md
+27 -159
View File
@@ -1,185 +1,53 @@
---
title: MCP 服务器
description: Model Context Protocol 集成
title: MCP 工具扩展
description: 让 AI 调用外部工具与资源（进阶）
navigation:
icon: i-heroicons-puzzle-piece
---
# MCP 服务器
# MCP 工具扩展
MCP (Model Context Protocol) 是一种标准协议，允许 AI 模型与外部工具和数据源交互。
MCP 可以让 AI 不只“回答问题”，还可以调用外部工具完成动作。
## MCP 概念
::alert{type="info"}
这是进阶能力。建议先熟悉基础创作流程，再接入 MCP。
::
### 什么是 MCP
## 适合的场景
MCP 定义了 AI 模型与外部系统交互的标准方式：
- 让 AI 读取指定目录素材
- 连接外部知识源或服务
- 把重复操作做成可调用工具
- **工具调用**: AI 可以调用外部工具执行操作
- **资源访问**: AI 可以读取外部数据源
- **上下文扩展**: 为 AI 提供额外的上下文信息
## 基本使用流程
### 集成优势
1. 添加 MCP 服务器配置
2. 启动并确认连接状态
3. 在工具列表里验证可用工具
4. 在实际任务里小范围试跑
- 扩展 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"
}
"args": ["-y", "@modelcontextprotocol/server-filesystem", "/path/to/workspace"]
}
}
}
```
### 连接设置
## 安全边界建议
| 选项 | 说明 |
|------|------|
| 自动启动 | 应用启动时自动连接 |
| 重连间隔 | 断开后重连的等待时间 |
| 超时时间 | 连接超时设置 |
1. 只授权必要目录和资源
2. 敏感环境变量不要硬编码在公开配置里
3. 新工具先在测试项目验证
## 工具调用
## 排错顺序
### 可用工具
连接 MCP 服务器后，可以查看提供的工具：
1. 进入 **MCP** 页面
2. 选择已连接的服务器
3. 查看 **工具列表**
### 工具信息
每个工具显示：
- 工具名称
- 功能描述
- 输入参数
- 返回类型
### 调用示例
通过 API 调用 MCP 工具：
```bash
curl http://127.0.0.1:8999/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. 实时显示服务器输出
1. 看连接状态是否正常
2. 看工具是否成功注册
3. 看调用参数是否符合工具定义
4. 看服务器日志定位具体错误
docs/content/03.providers/1.overview.md
+32 -98
View File
@@ -1,134 +1,68 @@
---
title: Provider 概述
description: 支持的 AI 服务提供商
title: 模型连接概览
description: 了解不同连接方式，并按你的创作目标选择
navigation:
icon: i-heroicons-squares-2x2
---
# Provider 概述
# 模型连接概览
ProxyCast 支持多种 AI 服务提供商（Provider），每种 Provider 有不同的认证方式和特点。
::alert{type="info"}
本章节属于进阶内容。普通创作者可先使用默认连接，只有在需要多账号或精细控制时再深入配置。
::
## Provider 类型
ProxyCast 支持多种模型连接方式，你可以按自己的使用习惯选择。
### OAuth 类型
## 两类连接方式
通过 OAuth 协议认证，支持自动刷新 Token：
### 自动连接（推荐）
| Provider | 说明 |
|----------|------|
| Kiro Claude | AWS Kiro IDE 的 Claude 凭证 |
| Gemini CLI | Google Gemini CLI 凭证 |
| Qwen | 阿里云通义千问凭证 |
| Codex | OpenAI Codex OAuth 凭证 |
| iFlow | iFlow OAuth 凭证（也支持 Cookie） |
适合希望“少配置、快开始”的用户：
### API Key 类型
- 登录对应客户端后自动识别
- 日常创作可直接使用
使用 API Key 认证，需要手动配置：
### 手动连接
| Provider | 说明 |
|----------|------|
| OpenAI Custom | 自定义 OpenAI 兼容服务 |
| Claude Custom | 自定义 Claude 兼容服务 |
| Gemini API Key | Gemini API Key 多账号负载均衡 |
| Vertex AI | Google Cloud Vertex AI 服务 |
适合有明确工程需求的用户：
## 选择指南
- 手动填写 API Key
- 自定义 Base URL
- 多账号并行管理
### 根据使用场景选择
## 如何选择
| 场景 | 推荐 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 | Codex | iFlow | Gemini API Key | Vertex AI |
|------|------|--------|------|-------|-------|----------------|-----------|
| 自动刷新 Token | ✅ | ✅ | ✅ | ✅ | ✅ | ❌ | ❌ |
| 流式响应 | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
| 工具调用 | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
| 视觉能力 | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
| 自定义 Base URL | ❌ | ❌ | ❌ | ❌ | ❌ | ✅ | ✅ |
| 多账号负载均衡 | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
| 模型排除 | ❌ | ❌ | ❌ | ❌ | ❌ | ✅ | ❌ |
| 模型别名 | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ✅ |
| Per-Key 代理 | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
- 长文与定稿使用质量优先模型
- 快速草稿与批量任务使用速度优先模型
- 图片任务使用视觉能力更强的模型
## 配置流程
### 追求高可用
### 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
```
1. 先完成一个主连接并测试可用
2. 再按场景增加备用连接
3. 每次新增连接后做一次小任务验证
## 下一步
选择你要配置的 Provider：
按你的连接类型进入对应页面：
### OAuth Provider
- [Kiro Claude](/providers/kiro-claude)
- [Gemini CLI](/providers/gemini-cli)
- [Qwen](/providers/qwen)
- [Codex](/providers/codex)
- [iFlow](/providers/iflow)
### API Key Provider
- [OpenAI Custom](/providers/openai-custom)
- [Claude Custom](/providers/claude-custom)
- [Gemini API Key](/providers/gemini-api-key)
docs/content/03.providers/10.vertex-ai.md
+4
View File
@@ -7,6 +7,10 @@ navigation:
# Vertex AI Provider
::alert{type="info"}
本页属于进阶连接配置。若你已能正常创作，可先跳过。
::
使用 API Key 访问 Google Cloud Vertex AI 服务，支持模型别名映射。
## 概述
docs/content/03.providers/2.kiro-claude.md
+4
View File
@@ -7,6 +7,10 @@ navigation:
# Kiro Claude
::alert{type="info"}
本页属于进阶连接配置。若你已能正常创作，可先跳过。
::
Kiro Claude 是 AWS Kiro IDE 提供的 Claude AI 服务凭证。
## 凭证位置
docs/content/03.providers/3.gemini-cli.md
+4
View File
@@ -7,6 +7,10 @@ navigation:
# Gemini CLI
::alert{type="info"}
本页属于进阶连接配置。若你已能正常创作，可先跳过。
::
Gemini CLI 是 Google 提供的命令行 AI 工具，使用 OAuth 认证。
## 凭证位置
docs/content/03.providers/4.qwen.md
+4
View File
@@ -7,6 +7,10 @@ navigation:
# Qwen (通义千问)
::alert{type="info"}
本页属于进阶连接配置。若你已能正常创作，可先跳过。
::
Qwen 是阿里云提供的大语言模型服务。
## 凭证位置
docs/content/03.providers/5.openai-custom.md
+4
View File
@@ -7,6 +7,10 @@ navigation:
# OpenAI Custom
::alert{type="info"}
本页属于进阶连接配置。若你已能正常创作，可先跳过。
::
OpenAI Custom 允许你配置任何 OpenAI 兼容的 API 服务。
## 适用场景
docs/content/03.providers/6.claude-custom.md
+4
View File
@@ -7,6 +7,10 @@ navigation:
# Claude Custom
::alert{type="info"}
本页属于进阶连接配置。若你已能正常创作，可先跳过。
::
Claude Custom 允许你配置 Anthropic 官方 API 或其他 Claude 兼容服务。
## 适用场景
docs/content/03.providers/7.codex.md
+4
View File
@@ -7,6 +7,10 @@ navigation:
# Codex Provider
::alert{type="info"}
本页属于进阶连接配置。若你已能正常创作，可先跳过。
::
通过 OAuth 认证使用 OpenAI Codex 服务。
## 概述
docs/content/03.providers/8.iflow.md
+4
View File
@@ -7,6 +7,10 @@ navigation:
# iFlow Provider
::alert{type="info"}
本页属于进阶连接配置。若你已能正常创作，可先跳过。
::
iFlow Provider 支持两种认证方式：OAuth 和 Cookie。
## 概述
docs/content/03.providers/9.gemini-api-key.md
+4
View File
@@ -7,6 +7,10 @@ navigation:
# Gemini API Key Provider
::alert{type="info"}
本页属于进阶连接配置。若你已能正常创作，可先跳过。
::
使用 API Key 访问 Google Gemini 服务，支持多账号负载均衡和模型排除。
## 概述
docs/content/04.api-reference/1.overview.md
+29 -81
View File
@@ -1,107 +1,55 @@
---
title: API 概述
description: ProxyCast API 端点和认证
title: API 概览
description: 面向进阶用户的本地接口能力说明
navigation:
icon: i-heroicons-code-bracket
---
# API 概述
# API 概览
ProxyCast 提供 OpenAI 和 Claude 兼容的 API 端点。
::alert{type="info"}
本章节面向进阶用户与开发者。普通创作者可直接在应用内使用，无需 API 接入。
::
## 支持的端点
当你需要把 ProxyCast 接入脚本、自动化流程或第三方工具时，可使用本地 API。
### OpenAI 兼容
## 常见端点类型
| 端点 | 方法 | 说明 |
|------|------|------|
| `/v1/chat/completions` | POST | 聊天补全 |
| `/v1/models` | GET | 模型列表 |
| `/v1/embeddings` | POST | 文本嵌入 |
### 通用对话端点
### Claude 兼容
用于文本生成、对话续写等任务。
| 端点 | 方法 | 说明 |
|------|------|------|
| `/v1/messages` | POST | 消息 API |
| `/v1/messages/count_tokens` | POST | Token 计数 |
### 模型与管理端点
### Amp CLI 路由
用于读取模型列表、状态信息和部分管理能力。
| 端点 | 方法 | 说明 |
|------|------|------|
| `/api/provider/{provider}/v1/chat/completions` | POST | Amp 聊天补全 |
| `/api/provider/{provider}/v1/messages` | POST | Amp 消息 API |
| `/api/auth/*` | ANY | Amp 认证代理 |
| `/api/user/*` | ANY | Amp 用户代理 |
### 扩展端点
### 管理 API
| 端点 | 方法 | 说明 |
|------|------|------|
| `/v0/management/status` | GET | 服务器状态 |
| `/v0/management/credentials` | GET/POST/DELETE | 凭证管理 |
| `/v0/management/config` | GET/PUT | 配置管理 |
用于特定平台或集成场景。
## 认证方式
### OpenAI 格式
- `Authorization: Bearer <api-key>`
- 或使用兼容格式的密钥头
使用 `Authorization` 头：
请确保 API Key 仅在可信环境使用。
```bash
curl http://127.0.0.1:8999/v1/chat/completions \
-H "Authorization: Bearer your-api-key" \
-H "Content-Type: application/json" \
-d '...'
```
## 默认地址
### Claude 格式
默认本地地址：`http://127.0.0.1:8999`
使用 `x-api-key` 头：
通常建议保持本地监听，不对公网暴露。
```bash
curl http://127.0.0.1:8999/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:8999`
可在设置中修改主机和端口。
## 错误响应
### 错误格式
```json
{
"error": {
"message": "错误描述",
"type": "error_type",
"code": "error_code"
}
}
```
### 常见错误码
| 状态码 | 说明 |
|--------|------|
| 400 | 请求格式错误 |
| 401 | 认证失败 |
| 404 | 端点不存在 |
| 429 | 速率限制 |
| 500 | 服务器错误 |
| 503 | 服务不可用 |
- `401`：密钥错误或请求头格式错误
- `404`：端点路径错误
- `429`：请求频率过高
- `5xx`：服务端异常或上游波动
## 下一步
- [OpenAI API](/api-reference/openai-api) - OpenAI 兼容端点详情
- [Claude API](/api-reference/claude-api) - Claude 兼容端点详情
- [管理 API](/api-reference/management-api) - 远程管理端点详情
- [Amp CLI API](/api-reference/amp-cli-api) - Amp CLI 集成端点详情
- [OpenAI API](/api-reference/openai-api)
- [Claude API](/api-reference/claude-api)
- [管理 API](/api-reference/management-api)
- [Amp CLI API](/api-reference/amp-cli-api)
docs/content/04.api-reference/2.openai-api.md
+4
View File
@@ -7,6 +7,10 @@ navigation:
# OpenAI API
::alert{type="info"}
本页是开发者进阶文档。普通创作者可直接在应用内使用，无需 API 调用。
::
ProxyCast 提供完整的 OpenAI Chat Completions API 兼容。
## /v1/chat/completions
docs/content/04.api-reference/3.claude-api.md
+4
View File
@@ -7,6 +7,10 @@ navigation:
# Claude API
::alert{type="info"}
本页是开发者进阶文档。普通创作者可直接在应用内使用，无需 API 调用。
::
ProxyCast 提供 Anthropic Claude Messages API 兼容。
## /v1/messages
docs/content/04.api-reference/4.management-api.md
+4
View File
@@ -7,6 +7,10 @@ navigation:
# 管理 API
::alert{type="info"}
本页是开发者进阶文档，主要用于自动化管理与运维集成。
::
ProxyCast 提供远程管理 API，用于配置和监控服务。
## 认证
docs/content/04.api-reference/5.amp-cli-api.md
+4
View File
@@ -7,6 +7,10 @@ navigation:
# Amp CLI API
::alert{type="info"}
本页是开发者进阶文档。若你不涉及 Amp CLI 集成，可跳过。
::
ProxyCast 提供 Amp CLI 兼容的路由端点，支持将 Amp CLI 请求路由到本地 OAuth 凭证。
## 概述
docs/content/05.troubleshooting/1.common-issues.md
+64 -101
View File
@@ -1,144 +1,107 @@
---
title: 常见问题
description: 常见问题汇总和解决方案
description: 按症状快速定位问题并恢复创作
navigation:
icon: i-heroicons-question-mark-circle
---
# 常见问题
本页汇总了 ProxyCast 使用中的常见问题和解决方案。
本页给你一个最快排查顺序：
## 启动问题
1. 看页面提示
2. 看当前项目与资源选择是否正确
3. 看连接状态与网络
4. 再进入详细排查页
### 应用无法启动
## 启动后看不到内容
**症状**: 双击应用图标后无反应
### 症状
**解决方案**:
- 页面空白或内容未刷新
- 明明生成过，但当前列表看不到
1. **macOS**: 右键点击应用，选择"打开"
2. **Windows**: 以管理员身份运行
3. 检查系统日志查看错误信息
### 先检查
### 端口被占用
1. 是否选错了项目
2. 是否切到了筛选分类（例如只看图片）
3. 是否处于搜索过滤状态
**症状**: 服务启动失败，提示端口已被使用
### 处理建议
**解决方案**:
- 先切回“全部”分类
- 清空搜索词
- 刷新当前页面再确认
```bash
# 查找占用端口的进程
# macOS/Linux
lsof -i :8999
## 图片没显示或数量不对
# Windows
netstat -ano | findstr :8999
```
### 症状
或在设置中更改端口号。
- 资源页看不到已生成图片
- 图片数量和预期不一致
## 凭证问题
### 先检查
### 凭证未检测到
1. 当前资源库（项目）是否正确
2. 是否选在“图片”分类
3. 图片是否已入库（自动或手动补录）
**症状**: 凭证池为空，未显示任何凭证
### 处理建议
**解决方案**:
- 回到图片生成页确认目标资源库
- 对历史结果执行“补录到资源库”
- 回资源页切换“全部”核对总量
1. 确认 AI 客户端已安装并登录
2. 检查凭证文件是否存在
3. 点击"刷新凭证"重新扫描
4. 手动添加凭证
## 生成失败或超时
详见 [凭证错误](/troubleshooting/credential-errors)
### 症状
### Token 过期
- 请求长时间无响应
- 返回超时或失败提示
**症状**: 请求返回 401 错误
### 处理建议
**解决方案**:
1. 降低同一时间的并发任务数
2. 缩短单次输入长度或拆成批次
3. 稍后重试，观察是否为瞬时波动
4. 必要时切换备用连接
1. 打开对应的 AI 客户端
2. 确认登录状态
3. 在 ProxyCast 中刷新凭证
## 认证或权限错误
## 连接问题
### 常见提示
### 无法连接到 Provider
- `401`：认证失败
- `403`：权限不足
**症状**: 请求超时或连接失败
### 处理建议
**解决方案**:
1. 重新确认连接状态
2. 刷新或重建对应连接
3. 再做一次小请求测试
1. 检查网络连接
2. 确认 Provider 服务正常
3. 检查代理设置
详见 [连接鉴权问题](/troubleshooting/credential-errors)。
详见 [连接问题](/troubleshooting/connection-issues)
## 网络连接不稳定
### SSL 证书错误
### 常见提示
**症状**: 提示证书验证失败
- 网络超时
- DNS 解析失败
- TLS/证书错误
**解决方案**:
### 处理建议
1. 检查系统时间是否正确
2. 更新系统根证书
3. 检查代理是否拦截 HTTPS
1. 检查本机网络
2. 检查代理配置是否正确
3. 避开高峰时段进行批量任务
## API 问题
详见 [网络与连接问题](/troubleshooting/connection-issues)。
### 请求返回错误
## 仍然无法解决
**常见错误码**:
请整理以下信息后反馈：
| 错误码 | 原因 | 解决方案 |
|--------|------|----------|
| 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. 提供详细的错误信息和复现步骤
1. 问题发生时间
2. 页面截图与错误文案
3. 复现步骤（尽量 3 步内）
4. 当前版本号
docs/content/05.troubleshooting/2.credential-errors.md
+33 -118
View File
@@ -1,146 +1,61 @@
---
title: 凭证错误
description: OAuth Token 问题诊断
title: 连接鉴权问题
description: 处理连接失效、认证失败与账号状态异常
navigation:
icon: i-heroicons-key
---
# 凭证错误
# 连接鉴权问题
本页帮助你诊断和解决凭证相关的问题。
本页用于处理“能打开应用，但调用失败”的问题。
## 诊断步骤
## 快速判断
### 1. 检查凭证文件
如果你看到以下报错，通常属于连接鉴权问题：
确认凭证文件存在：
- `401` 认证失败
- `403` 权限不足
- 连接状态显示已失效
```bash
# Kiro
ls -la ~/.kiro/credentials.json
## 3 步排查
# Gemini CLI
ls -la ~/.config/gemini-cli/oauth_creds.json
### 第 1 步：检查连接状态
# Qwen
ls -la ~/.config/qwen/credentials.json
```
在连接管理页面确认当前连接是否可用。
### 2. 验证文件格式
### 第 2 步：刷新或重建连接
检查 JSON 格式是否正确：
- 先尝试刷新
- 刷新失败则重新登录或重新添加连接
```bash
# 验证 JSON 格式
cat ~/.kiro/credentials.json | python -m json.tool
```
### 第 3 步：做最小测试
### 3. 检查 Token 有效性
使用一条简短请求验证是否恢复。
在 ProxyCast 中：
## 常见场景
1. 进入凭证池
2. 点击凭证的"测试"按钮
3. 查看测试结果
### 场景 1：昨天还能用，今天突然失败
## 常见错误
高概率是连接过期或上游状态变化。建议先重建该连接。
### Token 已过期
### 场景 2：部分模型可用，部分模型失败
**症状**: 凭证状态显示"已过期"
可能是模型权限差异或连接配置不匹配。先换一个已知可用模型测试。
**原因**:
- Access Token 超过有效期
- Refresh Token 也已过期
### 场景 3：导入配置后无法调用
**解决方案**:
导入通常不包含敏感凭证信息，需要重新校验连接。
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. 查看日志文件
1. 保留一个备用连接
2. 关键活动前做一次连通性测试
3. 定期清理长期失效连接
docs/content/05.troubleshooting/3.connection-issues.md
+42 -146
View File
@@ -1,176 +1,72 @@
---
title: 连接问题
description: 网络和代理故障排除
title: 网络与连接问题
description: 处理超时、DNS、证书和代理相关问题
navigation:
icon: i-heroicons-signal
---
# 连接问题
# 网络与连接问题
本页帮助你诊断和解决网络连接相关的问题。
当你频繁遇到超时、连接失败或证书错误时，按下面顺序排查。
## 诊断步骤
## 排查顺序
### 1. 检查网络连接
1. 本机网络是否正常
2. 代理是否配置正确
3. 请求是否过于集中
4. 是否为上游短时波动
```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. 增加超时时间
1. 先减少并发
2. 拆分任务批次
3. 适当增加超时
4. 稍后重试
### DNS 解析失败
**症状**: 无法解析域名
处理建议：
**解决方案**:
1. 切换网络后重试
2. 检查系统 DNS 设置
3. 清理 DNS 缓存后重试
1. 检查 DNS 设置
2. 尝试使用公共 DNS（如 8.8.8.8）
3. 清除 DNS 缓存
### 证书错误
```bash
# macOS
sudo dscacheutil -flushcache
处理建议：
# Windows
ipconfig /flushdns
```
1. 校准系统时间
2. 检查网络代理是否拦截 HTTPS
3. 更换网络环境复测
### SSL/TLS 错误
## 代理相关
**症状**: 证书验证失败
如果你使用代理，请重点检查：
**可能原因**:
- 系统时间不正确
- 根证书过期
- 代理拦截 HTTPS
1. 代理地址格式是否正确
2. 账号密码是否有效
3. 排除列表是否包含本地地址
**解决方案**:
常见格式示例：
1. 同步系统时间
2. 更新系统证书
3. 检查代理设置
- `http://proxy.example.com:8080`
- `http://user:password@proxy.example.com:8080`
- `socks5://proxy.example.com:1080`
## 代理配置
## 什么时候判断是上游问题
### 设置代理
满足以下特征时，通常是上游波动：
在 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 请求 |
| 8999 | ProxyCast API（默认） |
### macOS 防火墙
1. 系统偏好设置 > 安全性与隐私
2. 防火墙 > 防火墙选项
3. 允许 ProxyCast 接收传入连接
### Windows 防火墙
1. 控制面板 > Windows Defender 防火墙
2. 允许应用通过防火墙
3. 添加 ProxyCast
## 调试模式
启用详细日志：
1. 进入 **设置** > **高级**
2. 设置日志级别为 **Debug**
3. 重现问题
4. 查看网络请求日志
1. 记录失败时间段
2. 保存错误提示和关键日志
3. 先切换备用连接保障创作不中断
docs/content/06.development/5.plugin-development.md
+12 -244
View File
@@ -1,249 +1,17 @@
# 插件开发指南
---
title: 插件开发（迁移说明）
description: 本章节已迁移至开放平台文档
navigation:
icon: i-heroicons-arrow-top-right-on-square
---
# 插件开发（迁移说明）
::alert{type="info"}
📢 本文档已迁移至开放平台。请访问 [开放平台 - 插件开发](/open-platform/plugin-development) 获取最新内容。
插件开发文档已迁移，请阅读：[开放平台 - 插件开发指南](/open-platform/plugin-development)。
::
本文档描述 ProxyCast 插件系统的规范和开发指南，为插件市场做准备。
迁移后，开发者文档与用户文档分层更清晰：
## 插件类型
ProxyCast 支持两种类型的插件：
### 1. 脚本插件 (Script Plugin)
纯 JavaScript/TypeScript 插件，通过 Hook 机制扩展功能。
```json
{
"plugin_type": "script",
"entry": "main.js",
"hooks": ["on_request", "on_response"]
}
```
### 2. 二进制插件 (Binary Plugin)
独立的可执行文件，通过 CLI 接口与 ProxyCast 通信。适合需要系统级操作的工具。
```json
{
"plugin_type": "binary",
"entry": "my-tool-cli",
"binary": {
"binary_name": "my-tool-cli",
"github_owner": "your-org",
"github_repo": "your-repo",
"platform_binaries": {
"macos-arm64": "my-tool-aarch64-apple-darwin",
"macos-x64": "my-tool-x86_64-apple-darwin",
"linux-x64": "my-tool-x86_64-unknown-linux-gnu",
"linux-arm64": "my-tool-aarch64-unknown-linux-gnu",
"windows-x64": "my-tool-x86_64-pc-windows-msvc.exe"
},
"checksum_file": "checksums.txt"
}
}
```
## 插件包结构
插件以 ZIP 包形式分发，包含以下文件：
```
my-plugin.zip
├── plugin.json # 插件元数据（必需）
└── config.json # 默认配置（可选）
```
### plugin.json 规范
```json
{
"name": "my-plugin",
"version": "1.0.0",
"description": "插件描述",
"author": "作者名",
"homepage": "https://github.com/org/repo",
"license": "MIT",
"plugin_type": "binary",
"entry": "my-tool-cli",
"hooks": [],
"min_proxycast_version": "1.0.0",
"binary": { ... },
"ui": {
"surfaces": ["tools"],
"icon": "Cpu",
"title": "我的工具",
"default_width": 800,
"default_height": 600
}
}
```
#### 字段说明
| 字段 | 类型 | 必需 | 说明 |
|------|------|------|------|
| `name` | string | ✅ | 插件唯一标识符，小写字母和连字符 |
| `version` | string | ✅ | 语义化版本号 (semver) |
| `description` | string | ✅ | 插件描述 |
| `author` | string | ❌ | 作者名称 |
| `homepage` | string | ❌ | 项目主页 URL |
| `license` | string | ❌ | 开源许可证 |
| `plugin_type` | string | ✅ | `script` 或 `binary` |
| `entry` | string | ✅ | 入口文件/二进制名称 |
| `hooks` | array | ❌ | 注册的 Hook 列表 |
| `min_proxycast_version` | string | ❌ | 最低 ProxyCast 版本要求 |
| `binary` | object | ❌ | 二进制插件配置 |
| `ui` | object | ❌ | UI 配置 |
## UI 展示位置 (Surfaces)
插件可以在以下位置显示 UI：
| Surface | 说明 | 入口位置 |
|---------|------|----------|
| `tools` | 工具箱 | 导航栏「工具」页面 |
| `sidebar` | 侧边栏 | 主侧边栏（规划中） |
| `settings` | 设置页 | 设置页扩展区域（规划中） |
### 示例：工具类插件
```json
{
"ui": {
"surfaces": ["tools"],
"icon": "Cpu",
"title": "机器码管理工具"
}
}
```
安装后，插件会出现在「工具箱」页面，用户点击即可打开。
## 图标规范
使用 [Lucide Icons](https://lucide.dev/icons/) 图标名称：
```json
{
"ui": {
"icon": "Cpu"
}
}
```
常用图标：
- `Cpu` - 系统/硬件工具
- `Globe` - 网络工具
- `Database` - 数据工具
- `Shield` - 安全工具
- `Wrench` - 通用工具
- `Terminal` - 命令行工具
## 二进制插件 CLI 接口规范
二进制插件通过 CLI 与 ProxyCast 通信，必须遵循以下规范：
### 输出格式
所有输出必须是 JSON 格式：
```bash
# 成功
$ my-tool-cli get
{"machine_id": "550e8400-e29b-41d4-a716-446655440000"}
# 错误
$ my-tool-cli invalid-command
{"error": "未知命令: invalid-command"}
```
### 退出码
- `0` - 成功
- `1` - 错误
### 命令结构
```bash
my-tool-cli <command> [arguments]
```
建议实现 `help` 命令：
```bash
$ my-tool-cli help
MachineIdTool CLI v1.0.0
用法: my-tool-cli <命令> [参数]
命令:
get 获取当前值
set <value> 设置新值
help 显示帮助
```
## 插件安装流程
1. **下载插件包** - 从 URL 或本地文件获取 ZIP
2. **解压验证** - 解压并验证 plugin.json
3. **下载二进制** - 如果是二进制插件，根据当前平台下载对应二进制
4. **校验完整性** - 验证 checksum
5. **注册插件** - 将插件信息写入数据库
6. **加载插件** - 启用插件功能
## 插件发布
### GitHub Release 发布
推荐通过 GitHub Release 发布插件：
1. 创建 `plugin/` 目录，包含 `plugin.json` 和 `config.json`
2. 在 GitHub Actions 中打包 ZIP
3. 上传到 Release Assets
```yaml
- name: Package plugin
run: |
mkdir -p plugin-package
cp plugin/plugin.json plugin-package/
cp plugin/config.json plugin-package/
cd plugin-package
zip -j ../release/my-plugin.zip plugin.json config.json
```
### 插件市场（规划中）
未来将支持：
- 插件市场浏览和搜索
- 一键安装
- 自动更新
- 评分和评论
## 推荐插件
ProxyCast 内置推荐插件列表，在「工具箱」和「插件中心」显示未安装的推荐插件。
要将插件添加到推荐列表，请提交 PR 修改：
- `src/components/tools/ToolsPage.tsx` - `recommendedPlugins`
- `src/components/plugins/PluginManager.tsx` - `recommendedPlugins`
## 示例插件
参考 [MachineIdTool](https://github.com/aiclientproxy/MachineIdTool) 作为二进制插件的完整示例。
## 开发调试
### 本地安装测试
1. 打包插件 ZIP
2. 在「插件中心」点击「安装插件」
3. 选择本地 ZIP 文件安装
### 日志调试
插件执行日志保存在：
- macOS: `~/Library/Application Support/proxycast/logs/`
- Windows: `%APPDATA%/proxycast/logs/`
- Linux: `~/.local/share/proxycast/logs/`
- 开放平台：插件规范、接入流程、生态能力
- 用户指南：插件安装与使用
docs/content/08.open-platform/1.overview.md
+26 -48
View File
@@ -1,63 +1,41 @@
# 开放平台概述
---
title: 开放平台概览
description: 面向开发者与生态合作方的扩展能力
navigation:
icon: i-heroicons-cube-transparent
---
ProxyCast 开放平台为开发者和服务商提供扩展能力，包括插件系统和中转商生态合作方案。
# 开放平台概览
开放平台面向开发者与生态合作方，用于扩展 ProxyCast 的能力边界。
::alert{type="info"}
如果你是普通创作者，可先跳过本章节。
::
## 平台能力
### 🔌 插件系统
### 插件系统
通过插件扩展 ProxyCast 功能：
- **脚本插件** - JavaScript/TypeScript 插件，通过 Hook 机制扩展
- **二进制插件** - 独立可执行文件，适合系统级操作
- **工具插件** - 在工具箱中显示的独立工具
用于扩展工具、工作流和界面能力。
[了解更多 →](/open-platform/plugins)
### 🔗 ProxyCast Connect
### Connect 能力
中转商生态合作方案，实现一键配置：
- **一键配置** - 用户点击链接即可完成配置
- **品牌展示** - 中转商在 ProxyCast 内有专属展示位
- **统计回调** - 追踪推广效果
用于外部平台与 ProxyCast 的配置联动与生态集成。
[了解更多 →](/open-platform/connect)
## 核心价值
## 谁适合阅读
| 角色 | 价值 |
|------|------|
| **开发者** | 扩展功能、定制工具、集成服务 |
| **中转商** | 用户转化率提升、品牌曝光、差异化竞争 |
| **用户** | 一键配置、开箱即用、统一管理 |
| **ProxyCast** | 生态繁荣、用户增长 |
- 需要开发自定义插件的团队
- 需要对接外部系统的开发者
- 需要建设生态能力的合作方
## 快速开始
## 快速入口
<div class="grid grid-cols-1 md:grid-cols-2 gap-4 my-6">
<a href="/open-platform/plugins" class="block p-4 border border-gray-200 dark:border-gray-700 rounded-lg hover:border-primary-500 transition-colors">
<h3 class="font-semibold mb-2">🔌 开发插件</h3>
<p class="text-sm text-gray-600 dark:text-gray-400">创建自定义插件扩展 ProxyCast 功能</p>
</a>
<a href="/open-platform/connect" class="block p-4 border border-gray-200 dark:border-gray-700 rounded-lg hover:border-primary-500 transition-colors">
<h3 class="font-semibold mb-2">🔗 接入 Connect</h3>
<p class="text-sm text-gray-600 dark:text-gray-400">中转商接入一键配置功能</p>
</a>
<a href="/open-platform/plugin-development" class="block p-4 border border-gray-200 dark:border-gray-700 rounded-lg hover:border-primary-500 transition-colors">
<h3 class="font-semibold mb-2">📖 插件开发指南</h3>
<p class="text-sm text-gray-600 dark:text-gray-400">详细的插件开发文档和规范</p>
</a>
<a href="/open-platform/connect-integration" class="block p-4 border border-gray-200 dark:border-gray-700 rounded-lg hover:border-primary-500 transition-colors">
<h3 class="font-semibold mb-2">📖 Connect 接入指南</h3>
<p class="text-sm text-gray-600 dark:text-gray-400">中转商接入的详细步骤</p>
</a>
</div>
## 相关仓库
| 仓库 | 说明 |
|------|------|
| [proxycast](https://github.com/aiclientproxy/proxycast) | ProxyCast 主项目 |
| [connect](https://github.com/aiclientproxy/connect) | 中转商注册仓库 |
| [MachineIdTool](https://github.com/aiclientproxy/MachineIdTool) | 插件示例项目 |
- [插件中心](/open-platform/plugins)
- [插件开发指南](/open-platform/plugin-development)
- [Connect 接入](/open-platform/connect)
- [Connect 集成说明](/open-platform/connect-integration)
docs/content/08.open-platform/2.plugins.md
+27 -101
View File
@@ -1,112 +1,38 @@
# 插件中心
---
title: 开放平台 - 插件中心
description: 面向开发者的插件安装、管理与发布能力
navigation:
icon: i-heroicons-puzzle-piece
---
ProxyCast 支持通过插件扩展功能。插件中心提供插件的安装、管理和配置。
# 开放平台 - 插件中心
## 访问插件中心
::alert{type="info"}
本页面向开发者与高级用户。普通创作者可使用用户指南中的插件页。
::
点击左侧导航栏的「插件中心」进入插件管理页面。
ProxyCast 支持通过插件扩展能力，适用于自定义工具、自动化流程和生态集成。
## 功能概览
## 你可以做什么
### 推荐插件
- 安装推荐插件或第三方插件包
- 管理插件启用状态与版本
- 查看插件加载与执行状态
- 在工具入口中使用插件能力
插件中心会显示推荐的插件列表，点击「一键安装」即可快速安装。
## 安装方式
### 已安装插件
1. 推荐插件一键安装
2. 通过 URL 安装 ZIP 包
3. 通过本地文件安装 ZIP 包
显示所有已安装的插件，包括：
- 插件名称和版本
- 安装来源（本地/URL/GitHub）
- 启用/禁用状态
- 卸载按钮
## 管理建议
### 已加载插件
1. 先安装高频插件，再逐步扩展
2. 每次新增插件后做一次功能验证
3. 定期清理长期不用的插件
显示当前运行中的插件状态：
- 执行次数
- 错误次数
- 最后执行时间
## 下一步
## 安装插件
### 方式一：推荐插件一键安装
1. 在「推荐插件」区域找到想要的插件
2. 点击「一键安装」
3. 等待下载和安装完成
### 方式二：从 URL 安装
1. 点击「安装插件」按钮
2. 输入插件 ZIP 包的下载 URL
3. 点击「安装」
支持的 URL 格式：
- GitHub Release: `https://github.com/org/repo/releases/latest/download/plugin.zip`
- 直接下载链接: `https://example.com/plugin.zip`
### 方式三：从本地文件安装
1. 点击「安装插件」按钮
2. 点击「选择文件」
3. 选择本地的 `.zip` 文件
4. 点击「安装」
## 使用插件
安装完成后，插件会根据类型出现在不同位置：
### 工具类插件
工具类插件会出现在「工具箱」页面：
1. 点击左侧导航栏的「工具」
2. 在工具列表中找到已安装的插件
3. 点击「打开工具」使用
### 其他类型插件
- **Hook 插件**: 自动在请求/响应时执行
- **侧边栏插件**: 出现在主侧边栏（规划中）
## 管理插件
### 启用/禁用
在已加载插件列表中，点击电源图标可以启用或禁用插件。
### 卸载
1. 在「已安装插件包」列表中找到要卸载的插件
2. 点击红色的删除按钮
3. 确认卸载
卸载会删除插件文件和配置，但不会删除插件产生的数据。
## 二进制组件
部分功能需要安装额外的二进制组件：
- **aster-server**: AI Agent 框架，提供 Agent 对话能力
在「二进制组件」区域可以查看和管理这些组件。
## 常见问题
### 插件安装失败
1. 检查网络连接
2. 确认 URL 正确且可访问
3. 检查 ZIP 包格式是否正确
### 插件无法加载
1. 检查 ProxyCast 版本是否满足插件要求
2. 查看日志了解详细错误信息
3. 尝试重新安装插件
### 二进制插件权限问题
部分二进制插件需要管理员权限：
- **Windows**: 以管理员身份运行 ProxyCast
- **macOS/Linux**: 插件会提示需要的权限
- [插件开发指南](/open-platform/plugin-development)
- [开放平台概览](/open-platform/overview)
docs/content/08.open-platform/3.plugin-development.md
+30 -205
View File
@@ -1,219 +1,44 @@
# 插件开发指南
---
title: 开放平台 - 插件开发指南
description: 开发 ProxyCast 插件的规范与最佳实践
navigation:
icon: i-heroicons-code-bracket-square
---
本文档描述 ProxyCast 插件系统的规范和开发指南。
# 开放平台 - 插件开发指南
::alert{type="info"}
本页面向开发者。若你不开发插件，可跳过。
::
本文档说明插件类型、打包方式和开发建议，帮助你把能力稳定接入 ProxyCast。
## 插件类型
ProxyCast 支持两种类型的插件：
### 脚本插件
### 1. 脚本插件 (Script Plugin)
基于 JavaScript/TypeScript，通过 Hook 扩展行为。
纯 JavaScript/TypeScript 插件，通过 Hook 机制扩展功能。
### 二进制插件
```json
{
"plugin_type": "script",
"entry": "main.js",
"hooks": ["on_request", "on_response"]
}
```
通过独立可执行文件提供系统级能力，适合重计算或本地工具集成。
### 2. 二进制插件 (Binary Plugin)
## 基础结构
独立的可执行文件，通过 CLI 接口与 ProxyCast 通信。适合需要系统级操作的工具。
插件以 ZIP 分发，至少包含：
```json
{
"plugin_type": "binary",
"entry": "my-tool-cli",
"binary": {
"binary_name": "my-tool-cli",
"github_owner": "your-org",
"github_repo": "your-repo",
"platform_binaries": {
"macos-arm64": "my-tool-aarch64-apple-darwin",
"macos-x64": "my-tool-x86_64-apple-darwin",
"linux-x64": "my-tool-x86_64-unknown-linux-gnu",
"linux-arm64": "my-tool-aarch64-unknown-linux-gnu",
"windows-x64": "my-tool-x86_64-pc-windows-msvc.exe"
},
"checksum_file": "checksums.txt"
}
}
```
- `plugin.json`：元数据与入口定义
- 可选配置文件与资源文件
## 插件包结构
## 开发建议
插件以 ZIP 包形式分发，包含以下文件：
1. 先做最小可用版本
2. 明确输入输出协议
3. 做异常与超时处理
4. 提供清晰的版本兼容说明
```
my-plugin.zip
├── plugin.json # 插件元数据（必需）
└── config.json # 默认配置（可选）
```
## 发布建议
### plugin.json 规范
```json
{
"name": "my-plugin",
"version": "1.0.0",
"description": "插件描述",
"author": "作者名",
"homepage": "https://github.com/org/repo",
"license": "MIT",
"plugin_type": "binary",
"entry": "my-tool-cli",
"hooks": [],
"min_proxycast_version": "1.0.0",
"binary": { ... },
"ui": {
"surfaces": ["tools"],
"icon": "Cpu",
"title": "我的工具",
"default_width": 800,
"default_height": 600
}
}
```
### 字段说明
| 字段 | 类型 | 必需 | 说明 |
|------|------|------|------|
| `name` | string | ✅ | 插件唯一标识符，小写字母和连字符 |
| `version` | string | ✅ | 语义化版本号 (semver) |
| `description` | string | ✅ | 插件描述 |
| `author` | string | ❌ | 作者名称 |
| `homepage` | string | ❌ | 项目主页 URL |
| `license` | string | ❌ | 开源许可证 |
| `plugin_type` | string | ✅ | `script` 或 `binary` |
| `entry` | string | ✅ | 入口文件/二进制名称 |
| `hooks` | array | ❌ | 注册的 Hook 列表 |
| `min_proxycast_version` | string | ❌ | 最低 ProxyCast 版本要求 |
| `binary` | object | ❌ | 二进制插件配置 |
| `ui` | object | ❌ | UI 配置 |
## UI 展示位置 (Surfaces)
插件可以在以下位置显示 UI：
| Surface | 说明 | 入口位置 |
|---------|------|----------|
| `tools` | 工具箱 | 导航栏「工具」页面 |
| `sidebar` | 侧边栏 | 主侧边栏（规划中） |
| `settings` | 设置页 | 设置页扩展区域（规划中） |
### 示例：工具类插件
```json
{
"ui": {
"surfaces": ["tools"],
"icon": "Cpu",
"title": "机器码管理工具"
}
}
```
## 图标规范
使用 [Lucide Icons](https://lucide.dev/icons/) 图标名称：
常用图标：
- `Cpu` - 系统/硬件工具
- `Globe` - 网络工具
- `Database` - 数据工具
- `Shield` - 安全工具
- `Wrench` - 通用工具
- `Terminal` - 命令行工具
## 二进制插件 CLI 接口规范
二进制插件通过 CLI 与 ProxyCast 通信，必须遵循以下规范：
### 输出格式
所有输出必须是 JSON 格式：
```bash
# 成功
$ my-tool-cli get
{"machine_id": "550e8400-e29b-41d4-a716-446655440000"}
# 错误
$ my-tool-cli invalid-command
{"error": "未知命令: invalid-command"}
```
### 退出码
- `0` - 成功
- `1` - 错误
### 命令结构
```bash
my-tool-cli <command> [arguments]
```
建议实现 `help` 命令：
```bash
$ my-tool-cli help
MachineIdTool CLI v1.0.0
用法: my-tool-cli <命令> [参数]
命令:
get 获取当前值
set <value> 设置新值
help 显示帮助
```
## 插件安装流程
1. **下载插件包** - 从 URL 或本地文件获取 ZIP
2. **解压验证** - 解压并验证 plugin.json
3. **下载二进制** - 如果是二进制插件，根据当前平台下载对应二进制
4. **校验完整性** - 验证 checksum
5. **注册插件** - 将插件信息写入数据库
6. **加载插件** - 启用插件功能
## 插件发布
### GitHub Release 发布
推荐通过 GitHub Release 发布插件：
1. 创建 `plugin/` 目录，包含 `plugin.json` 和 `config.json`
2. 在 GitHub Actions 中打包 ZIP
3. 上传到 Release Assets
```yaml
- name: Package plugin
run: |
mkdir -p plugin-package
cp plugin/plugin.json plugin-package/
cp plugin/config.json plugin-package/
cd plugin-package
zip -j ../release/my-plugin.zip plugin.json config.json
```
## 开发调试
### 本地安装测试
1. 打包插件 ZIP
2. 在「插件中心」点击「安装插件」
3. 选择本地 ZIP 文件安装
### 日志调试
插件执行日志保存在：
- macOS: `~/Library/Application Support/proxycast/logs/`
- Windows: `%APPDATA%/proxycast/logs/`
- Linux: `~/.local/share/proxycast/logs/`
## 示例插件
参考 [MachineIdTool](https://github.com/aiclientproxy/MachineIdTool) 作为二进制插件的完整示例。
1. 版本号语义化管理
2. 发布前做跨平台验证
3. 提供回滚策略与变更日志
docs/content/08.open-platform/4.connect.md
+28 -152
View File
@@ -1,169 +1,45 @@
# ProxyCast Connect
---
title: 开放平台 - Connect
description: 面向服务提供方的一键配置接入能力
navigation:
icon: i-heroicons-link
---
ProxyCast Connect 是一套中转商生态合作方案，通过 Deep Link 协议实现一键配置功能。
# 开放平台 - Connect
::alert{type="info"}
本页面向生态合作方与平台接入方。普通创作者可跳过。
::
Connect 通过 Deep Link 提供“一键配置”能力，帮助外部平台将配置快速带入 ProxyCast。
## 核心价值
| 角色 | 价值 |
|------|------|
| **中转商** | 用户转化率提升、品牌曝光、差异化竞争 |
| **用户** | 一键配置、开箱即用、统一管理多个中转 |
| **ProxyCast** | 用户增长、生态繁荣、市场占有率 |
- 用户：减少手动配置步骤
- 服务提供方：降低接入门槛
- 平台：提升配置成功率
## 工作原理
## 一键配置流程
### 一键配置流程
1. 用户在外部平台点击一键配置
2. 浏览器打开 `proxycast://` 链接
3. ProxyCast 弹出确认
4. 用户确认后完成导入
1. 用户在中转商后台点击「一键配置 ProxyCast」
2. 浏览器打开 `proxycast://connect?relay=xxx&key=sk-xxx` 链接
3. ProxyCast 自动打开，显示确认弹窗
4. 用户确认后，API Key 自动添加到 ProxyCast
5. 配置完成，可以立即使用
## 基础协议
### Deep Link 协议
```
```text
proxycast://connect?relay={relay_id}&key={api_key}&name={key_name}&ref={ref_code}
```
| 参数 | 必填 | 说明 |
|------|------|------|
| `relay` | ✅ | 中转商 ID（需在 ProxyCast 注册） |
| `relay` | ✅ | 服务方唯一标识 |
| `key` | ✅ | API Key |
| `name` | ❌ | Key 名称（默认使用中转商名称） |
| `ref` | ❌ | 推广码（用于统计） |
### 示例
```
# 基础用法
proxycast://connect?relay=openrouter&key=sk-or-v1-xxxx
# 带名称
proxycast://connect?relay=siliconflow&key=sk-xxxx&name=硅基流动-主账号
# 带推广码
proxycast://connect?relay=myrelay&key=sk-xxxx&ref=promo2024
```
## 中转商注册
ProxyCast 是开源软件，中转商通过 **GitHub PR** 方式注册，无需网站注册。
### 注册仓库
```
https://github.com/aiclientproxy/connect
```
### 注册流程
1. **Fork 仓库** - Fork [aiclientproxy/connect](https://github.com/aiclientproxy/connect)
2. **创建配置文件** - 在 `providers/` 目录下创建 `{your-id}.json`
3. **提交 PR** - 提交 Pull Request 到主仓库
4. **自动化检查** - GitHub Actions 自动验证配置
5. **社区审核** - 维护者审核并合并 PR
6. **自动发布** - 合并后自动构建 registry.json
### 配置文件格式
```json
{
"id": "myrelay",
"name": "我的中转站",
"description": "稳定、便宜、快速的 AI API 中转服务",
"branding": {
"logo": "https://myrelay.com/logo.png",
"color": "#6366f1"
},
"links": {
"homepage": "https://myrelay.com",
"register": "https://myrelay.com/register",
"recharge": "https://myrelay.com/recharge",
"docs": "https://docs.myrelay.com",
"status": "https://status.myrelay.com"
},
"api": {
"base_url": "https://api.myrelay.com/v1",
"protocol": "openai",
"auth_header": "Authorization",
"auth_prefix": "Bearer "
},
"contact": {
"email": "support@myrelay.com",
"telegram": "@myrelay"
},
"features": {
"streaming": true,
"models_endpoint": true
},
"webhook": {
"callback_url": "https://api.myrelay.com/proxycast/callback",
"secret": "whsec_xxxxxxxxxxxxxxxx"
}
}
```
### 字段说明
| 字段 | 必填 | 说明 |
|------|------|------|
| `id` | ✅ | 唯一标识，小写字母、数字、连字符 |
| `name` | ✅ | 显示名称 |
| `description` | ✅ | 简短描述，≤100 字 |
| `branding.logo` | ✅ | Logo URL，256x256 PNG |
| `branding.color` | ❌ | 主题色，默认 `#6366f1` |
| `links.homepage` | ✅ | 官网地址 |
| `api.base_url` | ✅ | API 地址（必须 HTTPS） |
| `api.protocol` | ✅ | 协议：`openai` 或 `anthropic` |
| `contact.email` | ✅ | 联系邮箱 |
| `webhook.callback_url` | ❌ | 统计回调地址 |
| `webhook.secret` | ❌ | 回调签名密钥 |
### 审核标准
PR 合并前需满足：
- JSON Schema 验证通过
- 文件名与 `id` 字段一致
- Logo 图片可访问（256x256 PNG）
- API 地址使用 HTTPS
- 官网可访问
- 联系方式有效
## 品牌展示
注册成功后，中转商会在 ProxyCast 内获得品牌展示：
- **扩展市场** - 在中转服务分类中展示
- **已安装页面** - 显示品牌信息、快捷链接
- **API Key 管理** - 统一管理该中转商的所有 Key
## 安全设计
### Deep Link 安全
| 风险 | 防护措施 |
|------|---------|
| 恶意链接 | relay_id 必须在注册表中存在 |
| Key 泄露 | 确认弹窗显示脱敏 Key，用户确认后才添加 |
| 钓鱼攻击 | 显示中转商完整信息，用户可核实 |
### 确认弹窗
所有通过 Deep Link 添加的 Key 必须经过用户确认，显示：
- 中转商名称和 Logo
- 脱敏后的 API Key
- Key 名称（如果有）
- 安全提示
| `name` | ❌ | 显示名称 |
| `ref` | ❌ | 推广或渠道标记 |
## 下一步
- [Connect 接入指南](/open-platform/connect-integration) - 详细的接入步骤
- [统计回调](/open-platform/connect-webhook) - 配置统计回调追踪推广效果
- [Connect 接入指南](/open-platform/connect-integration)
- [统计回调（Webhook）](/open-platform/connect-webhook)
docs/content/08.open-platform/5.connect-integration.md
+33 -217
View File
@@ -1,229 +1,45 @@
# Connect 接入指南
---
title: 开放平台 - Connect 接入指南
description: 外部服务接入 Connect 的实施步骤与字段规范
navigation:
icon: i-heroicons-wrench-screwdriver
---
本文档详细介绍中转商如何接入 ProxyCast Connect，实现一键配置功能。
# 开放平台 - Connect 接入指南
## 接入流程
::alert{type="info"}
本页面向生态合作方技术团队。
::
### Step 1: Fork 仓库
本文档说明如何把你的服务接入 Connect，并完成一键配置联动。
Fork [aiclientproxy/connect](https://github.com/aiclientproxy/connect) 仓库到你的 GitHub 账号。
## 接入步骤
### Step 2: 创建配置文件
1. 准备服务方元数据
2. 按规范生成配置文件
3. 提交审核或接入申请
4. 联调 Deep Link
5. 灰度发布并观察回调数据
在 `providers/` 目录下创建 `{your-id}.json` 文件：
## 配置文件建议
```json
{
"id": "myrelay",
"name": "我的中转站",
"description": "稳定、便宜、快速的 AI API 中转服务",
"branding": {
"logo": "https://myrelay.com/logo.png",
"color": "#6366f1"
},
"links": {
"homepage": "https://myrelay.com",
"register": "https://myrelay.com/register",
"recharge": "https://myrelay.com/recharge",
"docs": "https://docs.myrelay.com",
"status": "https://status.myrelay.com"
},
"api": {
"base_url": "https://api.myrelay.com/v1",
"protocol": "openai",
"auth_header": "Authorization",
"auth_prefix": "Bearer "
},
"contact": {
"email": "support@myrelay.com",
"telegram": "@myrelay"
},
"features": {
"streaming": true,
"models_endpoint": true
},
"webhook": {
"callback_url": "https://api.myrelay.com/proxycast/callback",
"secret": "whsec_xxxxxxxxxxxxxxxx"
}
}
```
建议包含：
### Step 3: 提交 PR
- 唯一标识与展示信息
- 官网与文档链接
- API 基础信息
- 回调地址（可选）
提交 Pull Request 到主仓库，填写 PR 模板说明你的中转服务。
## 联调重点
### Step 4: 等待审核
1. Deep Link 参数完整性
2. 用户确认流程体验
3. 异常输入的兜底处理
4. 回调状态与业务统计一致性
GitHub Actions 会自动验证配置文件，维护者会在 1-3 个工作日内审核。
## 上线前检查
### Step 5: 合并上线
PR 合并后，registry.json 会自动构建，ProxyCast 客户端会自动同步。
## 配置字段说明
### 必填字段
| 字段 | 说明 | 示例 |
|------|------|------|
| `id` | 唯一标识，小写字母、数字、连字符 | `myrelay` |
| `name` | 显示名称 | `我的中转站` |
| `description` | 简短描述，≤100 字 | `稳定、便宜、快速的 AI API 中转服务` |
| `branding.logo` | Logo URL，256x256 PNG | `https://myrelay.com/logo.png` |
| `links.homepage` | 官网地址 | `https://myrelay.com` |
| `api.base_url` | API 地址（必须 HTTPS） | `https://api.myrelay.com/v1` |
| `api.protocol` | 协议类型 | `openai` 或 `anthropic` |
| `contact.email` | 联系邮箱 | `support@myrelay.com` |
### 可选字段
| 字段 | 说明 | 默认值 |
|------|------|--------|
| `branding.color` | 主题色 | `#6366f1` |
| `links.register` | 注册页面 | - |
| `links.recharge` | 充值页面 | - |
| `links.docs` | 文档地址 | - |
| `links.status` | 状态页面 | - |
| `api.auth_header` | 认证头 | `Authorization` |
| `api.auth_prefix` | 认证前缀 | `Bearer ` |
| `contact.telegram` | Telegram 联系方式 | - |
| `contact.discord` | Discord 联系方式 | - |
| `features.streaming` | 是否支持流式响应 | `true` |
| `features.models_endpoint` | 是否提供 /models 端点 | `false` |
| `webhook.callback_url` | 统计回调地址 | - |
| `webhook.secret` | 回调签名密钥 | - |
## 集成方式
### 方式一：直接链接
最简单的方式，在用户后台放置链接：
```html
<a href="proxycast://connect?relay=myrelay&key=USER_API_KEY">
一键配置 ProxyCast
</a>
```
### 方式二：JavaScript SDK
提供更好的用户体验：
```html
<script src="https://proxycast.dev/sdk/connect.js"></script>
<button onclick="ProxyCast.connect({ relay: 'myrelay', key: userApiKey })">
一键配置 ProxyCast
</button>
```
SDK 功能：
- 自动检测 ProxyCast 是否安装
- 未安装时显示下载引导
- 支持回调函数
```javascript
ProxyCast.connect({
relay: 'myrelay',
key: userApiKey,
name: '我的Key',
onSuccess: () => {
showToast('配置成功！');
},
onNotInstalled: () => {
showDownloadModal();
}
});
```
### 方式三：配置文件下载
生成 `.proxycast` 配置文件供用户下载：
```javascript
function downloadConfig(apiKey) {
const config = {
relay: 'myrelay',
key: apiKey,
name: '我的Key'
};
const blob = new Blob([JSON.stringify(config)], { type: 'application/json' });
const url = URL.createObjectURL(blob);
const a = document.createElement('a');
a.href = url;
a.download = 'myrelay.proxycast';
a.click();
}
```
用户双击 `.proxycast` 文件，ProxyCast 自动打开并导入配置。
## Deep Link 参数
```
proxycast://connect?relay={relay_id}&key={api_key}&name={key_name}&ref={ref_code}
```
| 参数 | 必填 | 说明 |
|------|------|------|
| `relay` | ✅ | 中转商 ID（需在 ProxyCast 注册） |
| `key` | ✅ | API Key |
| `name` | ❌ | Key 名称（默认使用中转商名称） |
| `ref` | ❌ | 推广码（用于统计） |
### 示例
```
# 基础用法
proxycast://connect?relay=openrouter&key=sk-or-v1-xxxx
# 带名称
proxycast://connect?relay=siliconflow&key=sk-xxxx&name=硅基流动-主账号
# 带推广码
proxycast://connect?relay=myrelay&key=sk-xxxx&ref=promo2024
```
## 品牌素材要求
| 素材 | 规格 | 说明 |
|------|------|------|
| Logo | 256x256 PNG | 透明背景，正方形 |
| 主题色 | HEX 色值 | 用于 UI 强调色 |
| 简介 | ≤50 字 | 一句话描述 |
| 详细描述 | ≤200 字 | 详细介绍 |
## API 要求
中转商的 API 需要满足：
| 要求 | 说明 |
|------|------|
| 协议兼容 | OpenAI 或 Anthropic 协议 |
| HTTPS | 必须使用 HTTPS |
| 模型列表 | 提供 `/models` 端点（可选） |
| 稳定性 | 99% 以上可用性 |
## 审核标准
PR 合并前需满足：
- JSON Schema 验证通过
- 文件名与 `id` 字段一致
- Logo 图片可访问（256x256 PNG）
- API 地址使用 HTTPS
- 官网可访问
- 联系方式有效
## 下一步
- [统计回调](/open-platform/connect-webhook) - 配置 Webhook 追踪推广效果
1. 参数合法性校验
2. 失效 Key 的处理策略
3. 安全与速率限制策略
4. 版本兼容说明
docs/content/08.open-platform/6.connect-webhook.md
+36 -176
View File
@@ -1,198 +1,58 @@
# 统计回调（Webhook）
---
title: 开放平台 - 统计回调（Webhook）
description: Connect 回调事件格式与接入建议
navigation:
icon: i-heroicons-arrow-path-rounded-square
---
ProxyCast Connect 提供统计回调机制，让中转商追踪推广效果。
# 开放平台 - 统计回调（Webhook）
## 回调流程
::alert{type="info"}
本页面向生态合作方技术团队。
::
```
用户点击一键配置
│
▼
ProxyCast 打开，显示确认弹窗
│
├─── 用户取消 ───▶ 发送回调: status=cancelled
│
└─── 用户确认 ───▶ Key 添加成功
│
▼
发送回调: status=success
│
▼
中转商收到回调，更新统计
```
Webhook 用于回传配置行为结果，帮助你统计接入效果。
## 配置回调
## 回调时机
在 `providers/{id}.json` 中添加 webhook 配置：
常见状态：
```json
{
"id": "myrelay",
"name": "我的中转站",
"webhook": {
"callback_url": "https://api.myrelay.com/proxycast/callback"
}
}
```
- `success`：用户确认并配置成功
- `cancelled`：用户取消
- `error`：执行失败
| 字段 | 必填 | 说明 |
|------|------|------|
| `webhook.callback_url` | ✅ | 回调地址（必须 HTTPS） |
## 回调请求格式
ProxyCast 向中转商发送 POST 请求：
## 请求示例
```http
POST https://api.myrelay.com/proxycast/callback
POST https://your-domain.com/proxycast/callback
Content-Type: application/json
User-Agent: ProxyCast/1.2.0
{
"event": "connect",
"status": "success",
"relay_id": "myrelay",
"ref": "promo2024",
"key_prefix": "sk-xxxx",
"timestamp": "2026-01-05T12:00:00Z",
"client": {
"version": "1.2.0",
"platform": "macos"
}
"relay_id": "your-relay",
"ref": "campaign-2026",
"timestamp": "2026-02-16T10:00:00Z"
}
```
## 回调字段说明
## 字段建议
| 字段 | 说明 |
|------|------|
| `event` | 事件类型：`connect` |
| `status` | 状态：`success`（成功）、`cancelled`（用户取消）、`error`（失败） |
| `relay_id` | 中转商 ID |
| `ref` | 推广码（如果有） |
| `key_prefix` | Key 前缀（脱敏，仅前 7 位） |
| `timestamp` | 事件时间（ISO 8601 格式） |
| `client.version` | ProxyCast 版本 |
| `client.platform` | 平台：`macos`、`windows`、`linux` |
| `error_code` | 错误码（仅 status=error 时） |
| `error_message` | 错误信息（仅 status=error 时） |
- `event`：事件类型
- `status`：状态值
- `relay_id`：服务方标识
- `ref`：渠道标记
- `timestamp`：事件时间
## 请求验证
## 安全建议
由于 ProxyCast 是开源软件，不使用签名验证。中转商应通过以下方式验证请求：
1. 仅接受 HTTPS 回调
2. 校验来源与参数完整性
3. 对回调做幂等处理
4. 记录失败重试日志
1. **检查 key_prefix** - 验证该 Key 前缀是否为自己下发的 Key
2. **检查 relay_id** - 确认是自己的中转商 ID
3. **检查 User-Agent** - 确认包含 `ProxyCast`
## 监控建议
### Express 示例
```javascript
app.post('/proxycast/callback', async (req, res) => {
const { relay_id, key_prefix, status, ref } = req.body;
const userAgent = req.headers['user-agent'] || '';
// 验证 User-Agent
if (!userAgent.includes('ProxyCast')) {
return res.status(403).json({ error: 'Invalid User-Agent' });
}
// 验证 relay_id
if (relay_id !== 'myrelay') {
return res.status(403).json({ error: 'Invalid relay_id' });
}
// 验证 key_prefix 是否为自己下发的 Key
const isValidKey = await db.apiKeys.exists({
key: { $regex: `^${key_prefix}` }
});
if (!isValidKey) {
return res.status(403).json({ error: 'Unknown key_prefix' });
}
// 处理回调
if (status === 'success') {
await db.stats.increment({
relay_id,
ref: ref || 'direct',
date: new Date().toISOString().split('T')[0]
});
}
res.json({ received: true });
});
```
## 重试机制
| 重试次数 | 间隔 | 说明 |
|----------|------|------|
| 第 1 次 | 立即 | 首次发送 |
| 第 2 次 | 1 分钟 | 首次失败后 |
| 第 3 次 | 5 分钟 | 第二次失败后 |
| 第 4 次 | 30 分钟 | 第三次失败后 |
| 放弃 | - | 超过 4 次不再重试 |
成功响应：HTTP 2xx 状态码
## 统计数据示例
基于回调数据，中转商可以构建统计面板：
```
┌─────────────────────────────────────────────────────────────┐
│ ProxyCast Connect 统计 2026-01-05 │
├─────────────────────────────────────────────────────────────┤
│ │
│ 今日概览 │
│ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐ │
│ │ 128 │ │ 115 │ │ 13 │ │ 89.8% │ │
│ │ 点击次数 │ │ 成功配置 │ │ 用户取消 │ │ 转化率 │ │
│ └──────────┘ └──────────┘ └──────────┘ └──────────┘ │
│ │
│ 推广码效果 │
│ ┌─────────────────────────────────────────────────────┐ │
│ │ 推广码 点击 成功 取消 转化率 │ │
│ ├─────────────────────────────────────────────────────┤ │
│ │ promo2024 56 52 4 92.9% │ │
│ │ twitter 38 33 5 86.8% │ │
│ │ (无推广码) 34 30 4 88.2% │ │
│ └─────────────────────────────────────────────────────┘ │
│ │
└─────────────────────────────────────────────────────────────┘
```
## 隐私保护
回调数据遵循最小化原则：
| 数据 | 是否发送 | 说明 |
|------|----------|------|
| 完整 API Key | ❌ | 仅发送前 7 位前缀 |
| 用户 ID | ❌ | 不发送任何用户标识 |
| 设备 ID | ❌ | 不发送设备标识 |
| IP 地址 | ❌ | 不发送用户 IP |
| 推广码 | ✅ | 用于统计推广效果 |
| 平台信息 | ✅ | 仅操作系统类型 |
## 错误码
当 `status=error` 时，会包含错误信息：
| 错误码 | 说明 |
|--------|------|
| `invalid_relay` | 中转商 ID 无效 |
| `invalid_key` | API Key 格式无效 |
| `relay_not_found` | 中转商未注册 |
| `network_error` | 网络错误 |
| `internal_error` | 内部错误 |
## 最佳实践
1. **验证 key_prefix** - 检查是否为自己下发的 Key
2. **幂等处理** - 同一事件可能重复发送
3. **快速响应** - 在 5 秒内返回响应
4. **异步处理** - 复杂逻辑放到后台队列
1. 统计成功率与取消率
2. 跟踪错误类型占比
3. 区分渠道来源效果
docs/content/index.md
+36 -133
View File
@@ -1,149 +1,52 @@
---
title: ProxyCast - 把你的 AI 客户端额度用到任何地方
description: 一款基于 Tauri 的桌面应用，将 Kiro、Gemini CLI、Qwen 等 AI 客户端凭证转换为标准 OpenAI/Claude 兼容 API
title: ProxyCast 文档中心
description: 创作类 AI Agent 平台文档，从灵感到发布的一站式指南
navigation: false
---
<div class="max-w-4xl mx-auto">
# ProxyCast 文档中心
<div class="text-center py-8">
<h1 class="text-5xl font-bold text-primary-600 mb-4">ProxyCast</h1>
<p class="text-3xl font-semibold text-gray-700 dark:text-gray-300 mb-2">把你的 AI 客户端额度用到任何地方</p>
<p class="text-xl text-gray-600 dark:text-gray-400 mb-4">一款基于 Tauri 的桌面应用，将 Kiro、Gemini CLI、Qwen 等 AI 客户端凭证转换为标准 OpenAI/Claude 兼容 API</p>
<p class="text-base text-gray-500 dark:text-gray-500 mb-10">凭证池管理 • 智能路由 • 协议转换 • 容错机制</p>
<div class="flex gap-4 justify-center flex-wrap">
<a href="/introduction/quickstart" class="inline-block px-8 py-3 bg-primary-600 text-white font-medium rounded-lg hover:bg-primary-700 transition-colors">快速开始</a>
<a href="https://github.com/aiclientproxy/proxycast" target="_blank" class="inline-block px-8 py-3 border-2 border-gray-300 dark:border-gray-600 font-medium rounded-lg hover:bg-gray-50 dark:hover:bg-gray-800 transition-colors">GitHub</a>
</div>
</div>
ProxyCast 是创作类 AI Agent 平台。
你可以在同一个工作台里完成对话、创作、图片生成、项目沉淀与资源复用。
<div class="text-center py-3 px-4 mb-6 bg-yellow-50 dark:bg-yellow-900/20 border border-yellow-200 dark:border-yellow-800 rounded-lg">
<p class="text-yellow-800 dark:text-yellow-200">
<strong>⚠️ 免责声明:</strong> 本工具仅限于个人合法使用，严禁用于非法盈利目的。初衷是帮助用户充分利用已订阅的 AI 服务 Token。
<a href="/legal/disclaimer" class="text-primary-600 hover:underline ml-1">查看完整声明</a>
</p>
</div>
## 从这里开始
## ✨ 核心特性
1. [概述](/introduction/overview)：先了解平台能帮你完成什么
2. [安装指南](/introduction/installation)：安装到本地桌面
3. [快速开始](/introduction/quickstart)：3 步走完首次创作
<div class="grid grid-cols-1 md:grid-cols-2 gap-6 my-8">
<div class="p-6 border border-gray-200 dark:border-gray-700 rounded-lg">
<h3 class="text-xl font-semibold mb-3">🔑 凭证池管理</h3>
<p class="text-gray-600 dark:text-gray-400">支持多种 AI 客户端凭证的统一管理，包括 Kiro、Gemini CLI、Qwen、Claude Code 等，自动检测和刷新 OAuth Token。</p>
</div>
<div class="p-6 border border-gray-200 dark:border-gray-700 rounded-lg">
<h3 class="text-xl font-semibold mb-3">🔀 智能路由</h3>
<p class="text-gray-600 dark:text-gray-400">基于模型名称的请求路由，支持负载均衡、优先级配置、健康检查和自动故障转移。</p>
</div>
<div class="p-6 border border-gray-200 dark:border-gray-700 rounded-lg">
<h3 class="text-xl font-semibold mb-3">🛡️ 容错配置</h3>
<p class="text-gray-600 dark:text-gray-400">内置熔断器、重试机制、超时控制，确保服务稳定性，优雅处理 API 故障。</p>
</div>
<div class="p-6 border border-gray-200 dark:border-gray-700 rounded-lg">
<h3 class="text-xl font-semibold mb-3">⚡ 配置切换</h3>
<p class="text-gray-600 dark:text-gray-400">一键切换 Claude Code、Codex、Gemini CLI 等客户端配置，快速适应不同使用场景。</p>
</div>
<div class="p-6 border border-gray-200 dark:border-gray-700 rounded-lg">
<h3 class="text-xl font-semibold mb-3">📊 监控统计</h3>
<p class="text-gray-600 dark:text-gray-400">实时监控请求统计、Token 使用追踪、详细的请求日志和性能指标。</p>
</div>
<div class="p-6 border border-gray-200 dark:border-gray-700 rounded-lg">
<h3 class="text-xl font-semibold mb-3">🔌 API 兼容</h3>
<p class="text-gray-600 dark:text-gray-400">完整支持 OpenAI Chat Completions API 和 Claude Messages API，无缝集成现有工具。</p>
</div>
</div>
## 九大创作主题
## 🎯 支持的 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 兼容服务 |
## 常用功能入口
## 🚀 快速开始
- [首页与工作台](/user-guide/dashboard)
- [资源库](/user-guide/resources)
- [图片生成与编辑](/user-guide/image-generation)
- [设置](/user-guide/settings)
- [插件中心](/user-guide/plugins)
### 1. 下载安装
## 进阶能力（可选）
从 [GitHub Tags](https://github.com/aiclientproxy/proxycast/tags) 下载适合你系统的安装包。
当你需要更深度的模型接入或工程能力时，可继续阅读：
### 2. 加载凭证
- [Provider 概述](/providers/overview)
- [API 参考](/api-reference/overview)
- [开放平台](/open-platform/overview)
- [故障排查](/troubleshooting/common-issues)
ProxyCast 会自动检测本地的 AI 客户端凭证文件：
## 免责声明
```
~/.kiro/credentials.json # Kiro Claude
~/.config/gemini-cli/oauth_creds.json # Gemini CLI
~/.config/qwen/credentials.json # Qwen
```
### 3. 启动服务
点击仪表盘的「启动服务」按钮，API Server 默认运行在 `http://127.0.0.1:8999`。
### 4. 测试 API
```bash
curl http://127.0.0.1:8999/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!"}]
}'
```
## 📖 文档导航
<div class="grid grid-cols-1 md:grid-cols-3 gap-4 my-8">
<a href="/introduction/overview" class="block p-4 border border-gray-200 dark:border-gray-700 rounded-lg hover:border-primary-500 transition-colors">
<h3 class="font-semibold mb-2">📋 概述</h3>
<p class="text-sm text-gray-600 dark:text-gray-400">了解 ProxyCast 的核心功能和价值</p>
</a>
<a href="/introduction/installation" class="block p-4 border border-gray-200 dark:border-gray-700 rounded-lg hover:border-primary-500 transition-colors">
<h3 class="font-semibold mb-2">📥 安装指南</h3>
<p class="text-sm text-gray-600 dark:text-gray-400">下载并安装 ProxyCast</p>
</a>
<a href="/introduction/quickstart" class="block p-4 border border-gray-200 dark:border-gray-700 rounded-lg hover:border-primary-500 transition-colors">
<h3 class="font-semibold mb-2">🚀 快速开始</h3>
<p class="text-sm text-gray-600 dark:text-gray-400">5 分钟内完成首次 API 调用</p>
</a>
<a href="/providers/overview" class="block p-4 border border-gray-200 dark:border-gray-700 rounded-lg hover:border-primary-500 transition-colors">
<h3 class="font-semibold mb-2">🔧 Provider 配置</h3>
<p class="text-sm text-gray-600 dark:text-gray-400">配置各种 AI 服务提供商</p>
</a>
<a href="/api-reference/overview" class="block p-4 border border-gray-200 dark:border-gray-700 rounded-lg hover:border-primary-500 transition-colors">
<h3 class="font-semibold mb-2">📚 API 参考</h3>
<p class="text-sm text-gray-600 dark:text-gray-400">完整的 API 端点文档</p>
</a>
<a href="/troubleshooting/common-issues" class="block p-4 border border-gray-200 dark:border-gray-700 rounded-lg hover:border-primary-500 transition-colors">
<h3 class="font-semibold mb-2">🔍 故障排除</h3>
<p class="text-sm text-gray-600 dark:text-gray-400">常见问题和解决方案</p>
</a>
</div>
## 🌐 开放平台
<div class="grid grid-cols-1 md:grid-cols-2 gap-4 my-8">
<a href="/open-platform/overview" class="block p-4 border border-gray-200 dark:border-gray-700 rounded-lg hover:border-primary-500 transition-colors">
<h3 class="font-semibold mb-2">🔌 插件系统</h3>
<p class="text-sm text-gray-600 dark:text-gray-400">通过插件扩展 ProxyCast 功能，支持工具类、Hook 类等多种插件类型</p>
</a>
<a href="/open-platform/connect" class="block p-4 border border-gray-200 dark:border-gray-700 rounded-lg hover:border-primary-500 transition-colors">
<h3 class="font-semibold mb-2">🔗 ProxyCast Connect</h3>
<p class="text-sm text-gray-600 dark:text-gray-400">中转商生态合作方案，一键配置 API Key，提升用户转化率</p>
</a>
</div>
## 🤝 社区与支持
- **GitHub Issues**: [报告问题](https://github.com/aiclientproxy/proxycast/issues)
- **GitHub Discussions**: [参与讨论](https://github.com/aiclientproxy/proxycast/discussions)
## 📄 开源协议
ProxyCast 采用 [MIT License](https://github.com/aiclientproxy/proxycast/blob/main/LICENSE) 开源。
</div>
请在合法合规前提下使用本产品。
完整说明见 [免责声明](/legal/disclaimer)。