mirror of
https://github.com/aiclientproxy/proxycast.git
synced 2026-09-24 23:10:56 +08:00
chore: bump version to v0.12.0
- 迁移 Vertex AI 和 Amp CLI 到凭证池页面 - 删除高级 Provider 导航和相关功能 - 支持编辑 API Key 凭证的 api_key 和 base_url - 修复凭证卡片标签排版问题 - 移除硬编码的 OAuth 凭证，改为环境变量
This commit is contained in:
coso
@@ -26,6 +26,23 @@ ProxyCast 提供 OpenAI 和 Claude 兼容的 API 端点。
|
||||
| `/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 格式
|
||||
@@ -86,3 +103,5 @@ curl http://127.0.0.1:9090/v1/messages \
|
||||
|
||||
- [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 集成端点详情
|
||||
|
||||
@@ -0,0 +1,316 @@
|
||||
---
|
||||
title: 管理 API
|
||||
description: ProxyCast 远程管理 API 端点
|
||||
navigation:
|
||||
icon: i-heroicons-cog-6-tooth
|
||||
---
|
||||
|
||||
# 管理 API
|
||||
|
||||
ProxyCast 提供远程管理 API，用于配置和监控服务。
|
||||
|
||||
## 认证
|
||||
|
||||
所有管理 API 请求需要在 `Authorization` 头中提供密钥：
|
||||
|
||||
```bash
|
||||
Authorization: Bearer your-secret-key
|
||||
```
|
||||
|
||||
## 访问控制
|
||||
|
||||
管理 API 的访问受以下配置控制：
|
||||
|
||||
| 配置项 | 说明 |
|
||||
|--------|------|
|
||||
| `secret_key` | 管理密钥，为空时禁用所有管理端点（返回 404） |
|
||||
| `allow_remote` | 是否允许远程访问，为 false 时仅允许 localhost |
|
||||
|
||||
## /v0/management/status
|
||||
|
||||
获取服务器状态信息。
|
||||
|
||||
### 请求
|
||||
|
||||
```bash
|
||||
GET /v0/management/status
|
||||
Authorization: Bearer your-secret-key
|
||||
```
|
||||
|
||||
### 响应
|
||||
|
||||
```json
|
||||
{
|
||||
"status": "running",
|
||||
"version": "1.0.0",
|
||||
"uptime_seconds": 3600,
|
||||
"tls_enabled": false,
|
||||
"active_credentials": 5,
|
||||
"total_requests": 1234,
|
||||
"providers": {
|
||||
"kiro": {
|
||||
"enabled": true,
|
||||
"credentials_count": 2
|
||||
},
|
||||
"gemini": {
|
||||
"enabled": true,
|
||||
"credentials_count": 1
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## /v0/management/credentials
|
||||
|
||||
### 获取凭证列表
|
||||
|
||||
```bash
|
||||
GET /v0/management/credentials
|
||||
Authorization: Bearer your-secret-key
|
||||
```
|
||||
|
||||
### 响应
|
||||
|
||||
```json
|
||||
{
|
||||
"credentials": [
|
||||
{
|
||||
"id": "kiro-main",
|
||||
"provider": "kiro",
|
||||
"type": "oauth",
|
||||
"status": "valid",
|
||||
"expires_at": "2025-01-01T00:00:00Z",
|
||||
"disabled": false
|
||||
},
|
||||
{
|
||||
"id": "gemini-key-1",
|
||||
"provider": "gemini_api_key",
|
||||
"type": "api_key",
|
||||
"status": "valid",
|
||||
"disabled": false,
|
||||
"excluded_models": ["gemini-2.5-pro"]
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
### 添加凭证
|
||||
|
||||
```bash
|
||||
POST /v0/management/credentials
|
||||
Authorization: Bearer your-secret-key
|
||||
Content-Type: application/json
|
||||
```
|
||||
|
||||
#### 添加 OAuth 凭证
|
||||
|
||||
```json
|
||||
{
|
||||
"provider": "kiro",
|
||||
"id": "kiro-new",
|
||||
"token_file": "kiro/new-token.json"
|
||||
}
|
||||
```
|
||||
|
||||
#### 添加 API Key 凭证
|
||||
|
||||
```json
|
||||
{
|
||||
"provider": "openai",
|
||||
"id": "openai-new",
|
||||
"api_key": "sk-xxx...",
|
||||
"base_url": "https://api.openai.com/v1"
|
||||
}
|
||||
```
|
||||
|
||||
#### 添加 Gemini API Key
|
||||
|
||||
```json
|
||||
{
|
||||
"provider": "gemini_api_key",
|
||||
"id": "gemini-key-new",
|
||||
"api_key": "AIzaSy...",
|
||||
"base_url": "https://generativelanguage.googleapis.com",
|
||||
"excluded_models": ["gemini-2.5-pro", "*-preview"]
|
||||
}
|
||||
```
|
||||
|
||||
### 响应
|
||||
|
||||
```json
|
||||
{
|
||||
"success": true,
|
||||
"credential_id": "kiro-new"
|
||||
}
|
||||
```
|
||||
|
||||
### 删除凭证
|
||||
|
||||
```bash
|
||||
DELETE /v0/management/credentials/{credential_id}
|
||||
Authorization: Bearer your-secret-key
|
||||
```
|
||||
|
||||
### 响应
|
||||
|
||||
```json
|
||||
{
|
||||
"success": true
|
||||
}
|
||||
```
|
||||
|
||||
## /v0/management/config
|
||||
|
||||
### 获取配置
|
||||
|
||||
```bash
|
||||
GET /v0/management/config
|
||||
Authorization: Bearer your-secret-key
|
||||
```
|
||||
|
||||
### 响应
|
||||
|
||||
```json
|
||||
{
|
||||
"server": {
|
||||
"host": "127.0.0.1",
|
||||
"port": 8999,
|
||||
"tls": {
|
||||
"enable": false
|
||||
}
|
||||
},
|
||||
"routing": {
|
||||
"default_provider": "kiro"
|
||||
},
|
||||
"quota_exceeded": {
|
||||
"switch_project": true,
|
||||
"switch_preview_model": true,
|
||||
"cooldown_seconds": 300
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### 更新配置
|
||||
|
||||
```bash
|
||||
PUT /v0/management/config
|
||||
Authorization: Bearer your-secret-key
|
||||
Content-Type: application/json
|
||||
```
|
||||
|
||||
```json
|
||||
{
|
||||
"routing": {
|
||||
"default_provider": "gemini"
|
||||
},
|
||||
"quota_exceeded": {
|
||||
"cooldown_seconds": 600
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### 响应
|
||||
|
||||
```json
|
||||
{
|
||||
"success": true,
|
||||
"restart_required": false
|
||||
}
|
||||
```
|
||||
|
||||
> **注意**: 某些配置更改（如 TLS、端口）需要重启服务器才能生效。
|
||||
|
||||
## 错误响应
|
||||
|
||||
### 401 Unauthorized
|
||||
|
||||
密钥无效或缺失：
|
||||
|
||||
```json
|
||||
{
|
||||
"error": {
|
||||
"message": "Invalid or missing secret key",
|
||||
"type": "authentication_error",
|
||||
"code": "invalid_api_key"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### 403 Forbidden
|
||||
|
||||
远程访问被禁止：
|
||||
|
||||
```json
|
||||
{
|
||||
"error": {
|
||||
"message": "Remote access not allowed",
|
||||
"type": "permission_error",
|
||||
"code": "remote_access_denied"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### 404 Not Found
|
||||
|
||||
管理 API 已禁用（secret_key 为空）：
|
||||
|
||||
```json
|
||||
{
|
||||
"error": {
|
||||
"message": "Management API is disabled",
|
||||
"type": "not_found_error",
|
||||
"code": "endpoint_not_found"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## 示例代码
|
||||
|
||||
### cURL
|
||||
|
||||
```bash
|
||||
# 获取状态
|
||||
curl http://127.0.0.1:8999/v0/management/status \
|
||||
-H "Authorization: Bearer your-secret-key"
|
||||
|
||||
# 获取凭证列表
|
||||
curl http://127.0.0.1:8999/v0/management/credentials \
|
||||
-H "Authorization: Bearer your-secret-key"
|
||||
|
||||
# 添加凭证
|
||||
curl http://127.0.0.1:8999/v0/management/credentials \
|
||||
-H "Authorization: Bearer your-secret-key" \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{"provider": "openai", "id": "openai-new", "api_key": "sk-xxx"}'
|
||||
```
|
||||
|
||||
### Python
|
||||
|
||||
```python
|
||||
import requests
|
||||
|
||||
BASE_URL = "http://127.0.0.1:8999"
|
||||
SECRET_KEY = "your-secret-key"
|
||||
|
||||
headers = {
|
||||
"Authorization": f"Bearer {SECRET_KEY}",
|
||||
"Content-Type": "application/json"
|
||||
}
|
||||
|
||||
# 获取状态
|
||||
response = requests.get(f"{BASE_URL}/v0/management/status", headers=headers)
|
||||
print(response.json())
|
||||
|
||||
# 添加凭证
|
||||
credential = {
|
||||
"provider": "openai",
|
||||
"id": "openai-new",
|
||||
"api_key": "sk-xxx"
|
||||
}
|
||||
response = requests.post(
|
||||
f"{BASE_URL}/v0/management/credentials",
|
||||
headers=headers,
|
||||
json=credential
|
||||
)
|
||||
print(response.json())
|
||||
```
|
||||
@@ -0,0 +1,244 @@
|
||||
---
|
||||
title: Amp CLI API
|
||||
description: Amp CLI 集成路由端点
|
||||
navigation:
|
||||
icon: i-heroicons-command-line
|
||||
---
|
||||
|
||||
# Amp CLI API
|
||||
|
||||
ProxyCast 提供 Amp CLI 兼容的路由端点，支持将 Amp CLI 请求路由到本地 OAuth 凭证。
|
||||
|
||||
## 概述
|
||||
|
||||
Amp CLI 集成允许你：
|
||||
- 使用本地 OAuth 凭证处理 Amp CLI 请求
|
||||
- 将不可用的模型映射到可用的替代模型
|
||||
- 代理 Amp 的认证和账户管理功能
|
||||
|
||||
## Provider 路由
|
||||
|
||||
### /api/provider/{provider}/v1/chat/completions
|
||||
|
||||
处理 Amp CLI 的 OpenAI 格式聊天请求。
|
||||
|
||||
```bash
|
||||
POST /api/provider/{provider}/v1/chat/completions
|
||||
Content-Type: application/json
|
||||
Authorization: Bearer your-api-key
|
||||
```
|
||||
|
||||
#### 支持的 Provider
|
||||
|
||||
| Provider | 说明 |
|
||||
|----------|------|
|
||||
| `anthropic` | Claude 模型 |
|
||||
| `openai` | GPT 模型 |
|
||||
| `google` | Gemini 模型 |
|
||||
|
||||
#### 请求示例
|
||||
|
||||
```bash
|
||||
curl http://127.0.0.1:8999/api/provider/anthropic/v1/chat/completions \
|
||||
-H "Authorization: Bearer your-api-key" \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{
|
||||
"model": "claude-sonnet-4",
|
||||
"messages": [{"role": "user", "content": "Hello!"}],
|
||||
"stream": true
|
||||
}'
|
||||
```
|
||||
|
||||
### /api/provider/{provider}/v1/messages
|
||||
|
||||
处理 Amp CLI 的 Anthropic Messages 格式请求。
|
||||
|
||||
```bash
|
||||
POST /api/provider/{provider}/v1/messages
|
||||
Content-Type: application/json
|
||||
x-api-key: your-api-key
|
||||
anthropic-version: 2023-06-01
|
||||
```
|
||||
|
||||
#### 请求示例
|
||||
|
||||
```bash
|
||||
curl http://127.0.0.1:8999/api/provider/anthropic/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",
|
||||
"max_tokens": 1024,
|
||||
"messages": [{"role": "user", "content": "Hello!"}]
|
||||
}'
|
||||
```
|
||||
|
||||
## 模型映射
|
||||
|
||||
当 Amp CLI 请求的模型不可用时，ProxyCast 可以自动映射到可用的替代模型。
|
||||
|
||||
### 配置
|
||||
|
||||
```yaml
|
||||
ampcode:
|
||||
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"
|
||||
```
|
||||
|
||||
### 映射行为
|
||||
|
||||
1. 收到请求时检查模型名称
|
||||
2. 如果模型在映射列表中，替换为目标模型
|
||||
3. 使用替换后的模型名称路由请求
|
||||
4. 响应中保留原始请求的模型名称
|
||||
|
||||
## 管理端点代理
|
||||
|
||||
ProxyCast 可以代理 Amp 的认证和账户管理端点到上游服务器。
|
||||
|
||||
### /api/auth/*
|
||||
|
||||
代理认证相关请求。
|
||||
|
||||
```bash
|
||||
# 登录
|
||||
POST /api/auth/login
|
||||
|
||||
# 刷新 Token
|
||||
POST /api/auth/refresh
|
||||
|
||||
# 登出
|
||||
POST /api/auth/logout
|
||||
```
|
||||
|
||||
### /api/user/*
|
||||
|
||||
代理用户账户相关请求。
|
||||
|
||||
```bash
|
||||
# 获取用户信息
|
||||
GET /api/user/profile
|
||||
|
||||
# 获取使用统计
|
||||
GET /api/user/usage
|
||||
```
|
||||
|
||||
### 配置
|
||||
|
||||
```yaml
|
||||
ampcode:
|
||||
upstream_url: "https://ampcode.com"
|
||||
restrict_management_to_localhost: false
|
||||
```
|
||||
|
||||
| 配置项 | 说明 |
|
||||
|--------|------|
|
||||
| `upstream_url` | Amp 上游服务器 URL |
|
||||
| `restrict_management_to_localhost` | 是否限制管理端点只能从 localhost 访问 |
|
||||
|
||||
## 使用场景
|
||||
|
||||
### 场景 1：使用本地 OAuth 凭证
|
||||
|
||||
你有 Kiro 的 Claude 订阅，想用 Amp CLI 但不想额外付费：
|
||||
|
||||
1. 配置 ProxyCast 加载 Kiro OAuth 凭证
|
||||
2. 在 Amp CLI 中配置 ProxyCast 作为 API 端点
|
||||
3. Amp CLI 请求通过 ProxyCast 路由到 Kiro 凭证
|
||||
|
||||
### 场景 2：模型替换
|
||||
|
||||
Amp CLI 请求 Claude Opus 4.5，但你只有 Sonnet 4 的访问权限：
|
||||
|
||||
```yaml
|
||||
ampcode:
|
||||
model_mappings:
|
||||
- from: "claude-opus-4.5"
|
||||
to: "claude-sonnet-4"
|
||||
```
|
||||
|
||||
### 场景 3：多 Provider 负载均衡
|
||||
|
||||
配置多个凭证，ProxyCast 自动在它们之间负载均衡：
|
||||
|
||||
```yaml
|
||||
credential_pool:
|
||||
kiro:
|
||||
- id: "kiro-1"
|
||||
token_file: "kiro/token-1.json"
|
||||
- id: "kiro-2"
|
||||
token_file: "kiro/token-2.json"
|
||||
```
|
||||
|
||||
## Amp CLI 配置
|
||||
|
||||
在 Amp CLI 中配置 ProxyCast：
|
||||
|
||||
```bash
|
||||
# 设置 API 端点
|
||||
amp config set api.base_url http://127.0.0.1:8999/api/provider
|
||||
|
||||
# 设置 API Key
|
||||
amp config set api.key your-proxycast-api-key
|
||||
```
|
||||
|
||||
或在配置文件中：
|
||||
|
||||
```yaml
|
||||
# ~/.amp/config.yaml
|
||||
api:
|
||||
base_url: http://127.0.0.1:8999/api/provider
|
||||
key: your-proxycast-api-key
|
||||
```
|
||||
|
||||
## 错误处理
|
||||
|
||||
### 模型不可用
|
||||
|
||||
当请求的模型不可用且没有配置映射时：
|
||||
|
||||
```json
|
||||
{
|
||||
"error": {
|
||||
"message": "Model 'claude-opus-4.5' is not available",
|
||||
"type": "invalid_request_error",
|
||||
"code": "model_not_found"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### 上游连接失败
|
||||
|
||||
当无法连接到 Amp 上游服务器时：
|
||||
|
||||
```json
|
||||
{
|
||||
"error": {
|
||||
"message": "Failed to connect to upstream server",
|
||||
"type": "upstream_error",
|
||||
"code": "connection_failed"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### 凭证耗尽
|
||||
|
||||
当所有凭证都不可用时：
|
||||
|
||||
```json
|
||||
{
|
||||
"error": {
|
||||
"message": "All credentials exhausted",
|
||||
"type": "service_unavailable",
|
||||
"code": "no_credentials_available"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
响应头会包含 `Retry-After` 指示何时可以重试。
|
||||
Reference in New Issue
Block a user