AgnesCode 远程 API 协议分析报告

协议端点: Renderer (React) ↔ Agnes API Server (HTTPS)
通信方式: HTTPS REST API
报告日期: 2026-07-25
分析版本: v1.0.17

---

1. 接口地址

1.1 基础 URL

环境	URL	来源
生产环境 (BFF)	https://api-agnes-code.agnes-ai.com/v1	.env 文件
生产环境 (API)	https://api.agnes-ai.com	renderer 代码
测试环境	https://api-agnes-code-test.agnes-dev.com/v1	.env 注释
登录页	https://app.agnes-ai.com/	.env 文件
文档站	https://agnescode.agnes-ai.com	.env 文件

注意: AGNES_API_URL 可在构建时通过环境变量注入, 生产环境通过 .env 文件配置。

1.2 认证方式

// 请求头
Authorization: Bearer {access_token}
X-User-Language: {locale}   // 例如: "zh-Hans", "en"
X-App-Id: 1                 // 应用 ID
X-Platform: 1               // 平台 ID

---

2. 认证 API

2.1 交换授权码 (Code Exchange)

端点: POST {AGNES_API_URL}/api/v1/code/auth/exchange-code

请求:

{
    "code": "auth_code_from_oauth",
    "redirect_uri": "agnes://auth/callback",
    "state": "32_byte_hex_state",
    "client_id": "agnes-code"
}

成功响应:

{
    "code": 0,
    "data": {
        "access_token": "jwt_or_opaque_token",
        "user_info": {
            "id": "user_id",
            "name": "User Name",
            "email": "user@example.com"
        }
    }
}

错误响应:

{
    "code": 1001,
    "message": "Invalid code or state",
    "data": null
}

错误码: 成功时 code === 0 或 code === "000000"

2.2 Token 存储

// 登录成功后
localStorage.setItem("token", access_token);
localStorage.setItem("userinfo", JSON.stringify(user_info));
window.dispatchEvent(new CustomEvent('agnes:userinfo-updated'));

// 同步到密钥链
await window.electron.setSetting('AGNES_AI_API_KEY', token);

2.3 Token 刷新

当前代码中未发现自动刷新机制。当 API 返回 401 时, 自动清除 token 并触发登出:

let debounce = false;
function handle401(response) {
    if (!response || response.status !== 401 || debounce) return;
    debounce = true;
    localStorage.removeItem("token");
    localStorage.removeItem("userinfo");
    setTimeout(() => { debounce = false; }, 2000);
}

---

3. 订阅/信用 API

3.1 查询信用余额

端点: GET {AGNES_API_URL}/api/v2/subscription/credits-balance

请求头:

Authorization: Bearer {token}
X-User-Language: {locale}

成功响应:

{
    "code": 0,
    "data": {
        "level_name": "free",
        "total_balance": 1000,
        "time_sensitive_balance": 500,
        "permanent_balance": 500
    }
}

3.2 查询信用交易记录

端点: POST {AGNES_API_URL}/api/v1/subscription/credits-transactions

请求头:

Authorization: Bearer {token}
X-User-Language: {locale}
Content-Type: application/json

请求体:

{
    "page": 1,
    "page_size": 20,
    "filter": 0
}

成功响应:

{
    "code": 0,
    "data": {
        "list": [
            {
                "description": "Chat with GPT-5.5",
                "created_at": "2026-07-25T12:00:00Z",
                "amount": 5,
                "direction": 2,
                "platform": "agnes"
            }
        ],
        "pagination": {
            "page": 1,
            "page_size": 20,
            "total": 50
        }
    }
}

---

4. 模型 API

4.1 获取模型列表

端点: GET {AGNES_API_URL}/v1/models

请求头:

Authorization: Bearer {token}
X-App-Id: 1
X-Platform: 1

响应: 模型列表 (包含 id, name, provider, capabilities 等)

---

5. 通用响应格式

5.1 成功响应

{
    "code": 0,
    "message": "success",
    "data": { ... }
}

5.2 错误响应

{
    "code": 1001,
    "message": "Error description",
    "data": null
}

5.3 HTTP 状态码

状态码	含义	处理方式
200	成功	正常处理
401	未授权	清除 token, 跳转登录
4xx	客户端错误	显示错误信息
5xx	服务器错误	显示错误信息

---

6. 错误处理逻辑

async function handleResponse(response) {
    const text = await response.text();
    let data;
    try {
        data = JSON.parse(text);
    } catch {
        throw new Error(`Server error (${response.status})`);
    }

    // 检查业务状态码
    if (data.code !== 0 && data.code !== "000000") {
        throw new Error(data.message || `Login failed (${response.status})`);
    }

    // 检查 401
    if (response.status === 401) {
        handle401(response);
        throw new Error("Session expired");
    }

    return data.data;
}

---

7. 预定义模型列表

从 .env 文件提取的预定义模型 (当远程 API 不可用时使用):

模型名称	提供商	显示名
agnes-2.5-flash	agnes	Agnes 2.5 Flash
agnes-2.0-flash-test	agnes	Agnes 2.0 Flash
openai/gpt-5.5	agnes	GPT-5.5
anthropic/claude-fable-5	agnes	Claude Fable 5
google/gemini-3.5-flash	agnes	Gemini 3.5 flash
deepseek/deepseek-v4-pro	agnes	DeepSeek V4 Pro
z-ai/glm-5.2	agnes	GLM 5.2

所有模型通过 agnes 提供商统一路由, 实际由 agnesd 后端代理到对应 AI 服务。

---

8. 架构图

┌──────────┐     HTTPS (Bearer Token)     ┌──────────────────┐
│ Renderer │──────────────────────────────►│  Agnes API Server │
│  (React) │◄──────────────────────────────│  (Cloud)          │
└──────────┘                               └────────┬─────────┘
                                                     │
                                                     ▼
                                            ┌──────────────────┐
                                            │  BFF (Backend)    │
                                            │  /api/v1/code/*   │
                                            │  /api/v2/*        │
                                            │  /v1/models       │
                                            └──────────────────┘