Skip to content

engineering-reference.md

Latest commit

 

History

History
542 lines (433 loc) · 15.1 KB

engineering-reference.md

File metadata and controls

542 lines (433 loc) · 15.1 KB
Raw
title 工程化参考手册
description 完整认证流程、AI 通信、模型定价、额度限制、反向代理设计蓝图

AgnesCode 认证 + AI 通信 — 完整工程化参考手册

报告日期: 2026-07-25
验证状态: ✅ 全部端到端验证通过

本手册是 AgnesCode 逆向分析项目的工程化参考，涵盖从认证到 AI 调用的完整技术细节。所有内容均经过实际验证，可作为开发反向代理、ACP 客户端、协议转换层的技术规格书使用。

相关文档:

1. 完整认证流程

1.1 总览

整个认证链路分为三个阶段:

graph LR
    subgraph "Phase 1: 获取 JWT"
        A["用户登录 platform<br/>platform.agnes-ai.com"] --> B["JWT Token"]
    end
    subgraph "Phase 2: 签发 & 交换"
        B -->|"POST /api/v1/user/issue-authorization-code"| C["授权码<br/>(60秒有效)"]
        C -->|"POST /api/v1/code/auth/exchange-code"| D["OAuth Token<br/>(短期)"]
    end
    subgraph "Phase 3: AI 调用"
        D -->|"Bearer Token"| E["AI 模型<br/>chat/completions"]
    end

    style A fill:#e8a838,color:#fff
    style B fill:#4a90d9,color:#fff
    style C fill:#50b86c,color:#fff
    style D fill:#4a90d9,color:#fff
    style E fill:#e74c3c,color:#fff
Loading

1.2 Phase 1: 获取 JWT Token

JWT Token 从 platform.agnes-ai.com 平台获取。用户在浏览器登录 platform 后, 会获得一个 JWT Token。

获取方式: 用户登录 https://platform.agnes-ai.com 后, 浏览器中可以通过以下方式获取:

  • 在 Chrome DevTools → Application → Local Storage → 查找 token
  • 或通过 POST /api/user/login 接口获取

JWT Token 格式:

eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiJjY2U0NDFiZC01...

1.3 Phase 2: 签发授权码 → 交换 OAuth Token

步骤 2a: 签发授权码

请求:

POST https://api.agnes-ai.com/api/v1/user/issue-authorization-code
Authorization: Bearer {JWT_TOKEN}
Content-Type: application/json
Origin: https://app.agnes-ai.com
x-platform: 1
x-user-language: en

请求体:

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

成功响应:

{
    "code": "000000",
    "message": "success",
    "data": {
        "code": "uxvLSipjtX8lo-wG6Adn4cXAzMQ_rh6DY8REOoj0yn0",
        "expires_at": 1785003621
    }
}

步骤 2b: 交换 OAuth Token

请求:

POST https://api-agnes-code.agnes-ai.com/api/v1/code/auth/exchange-code
Content-Type: application/json

请求体:

{
    "code": "上一步获取的授权码",
    "redirect_uri": "agnes://auth/callback",
    "state": "之前使用的 state",
    "client_id": "agnes-code"
}

成功响应:

{
    "code": "000000",
    "message": "success",
    "data": {
        "access_token": "eyJhbGciOiJIUzI1NiIs...",
        "user_info": {
            "id": "00000000-0000-0000-0000-000000000000",
            "username": "testuser",
            "email": "user@example.com",
            "auth_provider": "email",
            "is_active": true
        },
        "newapi_ready": true,
        "newapi_initialized": true
    }
}

1.4 Phase 3: 用 OAuth Token 调用 AI

请求:

POST https://api-agnes-code.agnes-ai.com/v1/chat/completions
Authorization: Bearer {OAUTH_TOKEN}
Content-Type: application/json

请求体 (OpenAI 兼容格式):

{
    "model": "agnes-2.0-flash",
    "messages": [{"role": "user", "content": "你好"}],
    "max_tokens": 1024,
    "temperature": 0.7,
    "stream": false
}

成功响应:

{
    "id": "d09d5a73120e48bdb693ee31312f1334",
    "created": 1785003650,
    "model": "agnes-2.5-flash",
    "object": "chat.completion",
    "choices": [{
        "finish_reason": "stop",
        "index": 0,
        "message": {
            "content": "我是 Agnes-2.5-Flash，由 Sapiens AI 开发的语言模型。",
            "role": "assistant"
        }
    }],
    "usage": {
        "completion_tokens": 21,
        "prompt_tokens": 258,
        "total_tokens": 279
    }
}

2. AI 通信能力

2.1 后端架构

Agnes 的 AI 后端使用 LiteLLM (开源 LLM 代理) 作为统一网关:

graph LR
    subgraph "客户端"
        C["Client / SDK"]
    end
    subgraph "Agnes 后端"
        B["BFF API<br/>api-agnes-code.agnes-ai.com"]
        L["LiteLLM v1.92.0<br/>统一代理网关"]
    end
    subgraph "AI 提供商"
        A1["Agnes 自有模型<br/>sglang-router"]
        A2["OpenAI"]
        A3["Anthropic"]
        A4["DeepSeek"]
        A5["其他"]
    end

    C -->|"HTTPS Bearer Token"| B
    B --> L
    L --> A1
    L --> A2
    L --> A3
    L --> A4
    L --> A5

    style C fill:#50b86c,color:#fff
    style B fill:#4a90d9,color:#fff
    style L fill:#e8a838,color:#fff
Loading

从响应头中可以看到:

x-litellm-version: 1.92.0
x-litellm-model-group: agnes-2.0-flash
x-litellm-model-api-base: https://kw.dykjbj.com:9443/infer/vip-agnes-2-0-flash-sglang-router/v1

2.2 支持的 endpoint 类型

所有模型均支持 openai 格式 (即 OpenAI 兼容的 REST API)。

2.3 流式响应 (SSE)

支持 stream: true 参数, 返回 SSE (Server-Sent Events) 格式:

data: {"id":"...","object":"chat.completion.chunk","created":...,"model":"agnes-2.0-flash","choices":[{"index":0,"delta":{"role":"assistant","content":""}}]}

data: {"id":"...","object":"chat.completion.chunk","created":...,"model":"agnes-2.0-flash","choices":[{"index":0,"delta":{"content":"1"}}]}

data: {"id":"...","object":"chat.completion.chunk","created":...,"model":"agnes-2.0-flash","choices":[{"index":0,"delta":{"content":","}}]}

data: [DONE]

3. 模型清单与定价

3.1 完整模型列表 (从 API 获取)

通过 GET /v1/models 动态获取, 当前共 7 个模型:

模型 ID 提供商 免费/会员 灰度 输入上限 输出上限 描述
agnes-2.0-flash agnes ✅ 免费 - 512K 65K 日常任务和编码, 快速可靠
agnes-2.5-flash agnes ✅ 免费 🧪 灰度 512K 65K 复杂任务, 速度与能力平衡
glm-5.2 zhipu 🔒 会员 - 1M 131K 中文、推理、编码强
deepseek-v4-pro deepseek 🔒 会员 - 1M 393K 编码、数学、深度推理
gemini-3.5-flash google 🔒 会员 - 1M 65K 多模态和长上下文
gpt-5.5 openai 🔒 会员 - 10M 131K 推理和高质量输出
claude-opus-4-8 anthropic 🔒 会员 - 1M 131K 长文分析和写作

3.2 模型获取方式

不要硬编码模型列表! 使用以下 API 动态获取:

GET https://api-agnes-code.agnes-ai.com/v1/models
Authorization: Bearer {OAUTH_TOKEN}
X-App-Id: 1
X-Platform: 1

响应格式:

{
    "data": [
        {
            "id": "agnes-2.0-flash",
            "object": "model",
            "created": 1784206241,
            "owned_by": "agnes",
            "provider": "agrouter",
            "description": "Fast and reliable for everyday tasks and coding.",
            "max_input_tokens": 512000,
            "max_output_tokens": 65536,
            "is_member_only": false,
            "is_gray": false,
            "gray_available": true,
            "model_type": "text",
            "supported_endpoint_types": ["openai"]
        }
    ]
}

3.3 关键字段说明

字段 类型 说明
id string 模型 ID, 用于聊天补全请求
is_member_only boolean true=会员专属, false=免费可用
is_gray boolean true=灰度中, 可能不稳定
gray_available boolean 灰度用户是否可用
max_input_tokens int 最大输入 token 数
max_output_tokens int 最大输出 token 数
model_type string text 或 multimodal
supported_endpoint_types string[] 均为 ["openai"]

4. 额度与速率限制

4.1 当前账号额度

余额: 1200 积分 (免费赠送)

GET https://api-agnes-code.agnes-ai.com/api/v2/subscription/credits-balance
Authorization: Bearer {OAUTH_TOKEN}
X-User-Language: zh-Hans

响应:

{
    "code": "000000",
    "data": {
        "level": 0,
        "level_name": "",
        "total_balance": 1200,
        "time_sensitive_balance": 1200,
        "permanent_balance": 0,
        "daily_free_credits": 0,
        "subscription_credits": 0,
        "effect_quota_balance": 0,
        "daily_effect_quota": 0
    }
}

4.2 交易记录

POST https://api-agnes-code.agnes-ai.com/api/v1/subscription/credits-transactions
Authorization: Bearer {OAUTH_TOKEN}
X-User-Language: zh-Hans

请求体:

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

当前记录: 仅有 1 条 "每日免费赠送" 1200 积分。

4.3 已知信息

项目 值
免费额度 1200 积分 (一次性赠送)
会员模型 需要订阅才能使用
每日免费额度 daily_free_credits: 0 (当前没有)
订阅 current_subscription: null (当前没有订阅)
速率限制 未明确发现, 但 LiteLLM 后端可能有限制

注意: 免费模型 (agnes-2.0-flash, agnes-2.5-flash) 即使没有会员也可以使用, 消耗积分。会员模型需要订阅。

4.4 消耗估算

从 x-litellm-key-spend: 1144.0353 可以看出, 每次调用会消耗积分。免费额度 1200 积分大概可以调用约 1000 次简单对话 (取决于 token 数)。

5. 流式响应

5.1 请求

{
    "model": "agnes-2.0-flash",
    "messages": [{"role": "user", "content": "Count 1 to 5"}],
    "max_tokens": 50,
    "stream": true
}

5.2 响应格式 (SSE)

data: {"id":"fa5da678...","object":"chat.completion.chunk","created":1785004491,"model":"agnes-2.0-flash","choices":[{"index":0,"delta":{"role":"assistant","content":""}}]}

data: {"id":"fa5da678...","object":"chat.completion.chunk","created":1785004491,"model":"agnes-2.0-flash","choices":[{"index":0,"delta":{"content":"1"}}]}

data: {"id":"fa5da678...","object":"chat.completion.chunk","created":1785004491,"model":"agnes-2.0-flash","choices":[{"index":0,"delta":{"content":","}}]}

data: [DONE]

5.3 响应头关键信息

x-litellm-version: 1.92.0
x-litellm-model-group: agnes-2.0-flash
x-litellm-model-api-base: https://kw.dykjbj.com:9443/infer/vip-agnes-2-0-flash-sglang-router/v1
x-litellm-key-spend: 1144.0353
x-litellm-response-duration-ms: 463.767

6. API 端点速查表

6.1 认证

操作 方法 URL 认证
签发授权码 POST https://api.agnes-ai.com/api/v1/user/issue-authorization-code JWT Token
交换 OAuth Token POST https://api-agnes-code.agnes-ai.com/api/v1/code/auth/exchange-code 授权码

6.2 AI 调用

操作 方法 URL 认证
聊天补全 (非流式) POST https://api-agnes-code.agnes-ai.com/v1/chat/completions Bearer Token
聊天补全 (流式) POST https://api-agnes-code.agnes-ai.com/v1/chat/completions?stream=true Bearer Token
模型列表 GET https://api-agnes-code.agnes-ai.com/v1/models Bearer Token

6.3 用户与订阅

操作 方法 URL 认证
用户信息 GET https://api-agnes-code.agnes-ai.com/api/v1/user/profile Bearer Token
信用余额 GET https://api-agnes-code.agnes-ai.com/api/v2/subscription/credits-balance Bearer Token
交易记录 POST https://api-agnes-code.agnes-ai.com/api/v1/subscription/credits-transactions Bearer Token
订阅套餐 GET https://api-agnes-code.agnes-ai.com/api/v1/subscription/plans Bearer Token

6.4 域名

域名 用途
api.agnes-ai.com 通用 API (签发授权码等)
api-agnes-code.agnes-ai.com BFF API (AI 调用、模型列表、订阅)
app.agnes-ai.com 登录页面
platform.agnes-ai.com 用户平台
platform-backend.agnes-ai.com 平台后端

7. 反向代理设计蓝图

7.1 架构

graph LR
    subgraph "客户端工具"
        C1["Codex"]
        C2["Claude Code"]
        C3["其他 AI 工具"]
    end
    subgraph "反向代理 (中转站)"
        P["反向代理<br/>1. 接收 OpenAI 格式<br/>2. 注入 Bearer Token<br/>3. 转发到 Agnes<br/>4. 返回响应/流式"]
    end
    subgraph "Agnes 后端"
        B["Agnes BFF API<br/>api-agnes-code.agnes-ai.com"]
    end

    C1 --> P
    C2 --> P
    C3 --> P
    P -->|"OpenAI 兼容协议"| B

    style C1 fill:#50b86c,color:#fff
    style C2 fill:#50b86c,color:#fff
    style C3 fill:#50b86c,color:#fff
    style P fill:#e8a838,color:#fff
    style B fill:#4a90d9,color:#fff
Loading

7.2 关键设计要点

要点 说明
协议 输入输出均为 OpenAI 兼容格式
认证 代理需要维护一个有效的 OAuth Token
模型列表 通过 /v1/models 动态获取, 不硬编码
流式 透传 SSE 流
Token 刷新 JWT Token 过期后需要重新签发

7.3 Token 生命周期管理

stateDiagram-v2
    [*] --> JWT_Token: 用户登录 platform
    JWT_Token --> AuthCode: POST issue-authorization-code
    AuthCode --> OAuth_Token: POST exchange-code
    OAuth_Token --> AI_Call: Bearer Token
    AI_Call --> OAuth_Token: Token 仍有效
    OAuth_Token --> Expired: 401 响应
    Expired --> JWT_Token: 重新签发

    note right of AuthCode: 60秒有效期
    note right of OAuth_Token: 短期有效<br/>无自动刷新
Loading

8. 附录: 原始数据

8.1 测试账号信息

字段 值
用户 ID 00000000-0000-0000-0000-000000000000
用户名 testuser
邮箱 user@example.com
认证方式 email
注册时间 2026-07-25
免费额度 1200 积分
订阅 无

8.2 已验证的响应头

x-litellm-version: 1.92.0
x-litellm-model-group: agnes-2.0-flash
x-litellm-model-api-base: https://kw.dykjbj.com:9443/infer/vip-agnes-2-0-flash-sglang-router/v1
x-litellm-key-spend: 1144.0353
x-litellm-response-duration-ms: 463.767

8.3 验证结果

测试项 结果
签发授权码 ✅ 成功
交换 OAuth Token ✅ 成功
免费模型 AI 调用 ✅ 成功 (agnes-2.0-flash, agnes-2.5-flash)
会员模型 AI 调用 ✅ 成功 (gpt-5.5, 返回空内容可能是额度不足)
流式响应 ✅ 成功 (SSE 格式)
模型列表 ✅ 成功
信用额度 ✅ 成功
交易记录 ✅ 成功
用户信息 ✅ 成功