AgnesCode 逆向分析报告

报告日期: 2026-07-24 目标版本: v1.0.15 ~ v1.0.23 目标: 分析授权登录机制、AI交互协议，为构建反向代理提供依据

本报告从架构分析、技术栈、授权登录、通信协议、密钥管理五个维度，对 AgnesCode 桌面应用进行逆向分析。重点关注 ACP (Agent Client Protocol) 通信协议和 OAuth2 + Deep Link 认证机制，为后续构建反向代理提供技术参考。

1. 概述与架构

1.1 架构总览

AgnesCode 是一个 Electron 桌面应用，采用 前后端分离架构：

mermaid

graph TB
    subgraph "Electron Shell (Main Process)"
        subgraph "Renderer (React 19 + Vite 7)"
            R1["用户界面<br/>Chat UI / Skill Editor / Artifact Manager"]
        end
        subgraph "Main Process (Node.js)"
            M1["窗口管理 / 系统托盘"]
            M2["文件系统操作"]
            M3["启动/管理 agnesd"]
            M4["Deep Link 处理<br/>agnes://"]
            M5["密钥链存储<br/>Keychain / Credential Manager"]
        end
        subgraph "agnest (Rust 后端)"
            A1["HTTP API 服务器<br/>localhost:随机端口"]
            A2["ACP WebSocket 代理"]
            A3["AI 提供商路由"]
            A4["会话管理 / 文件索引"]
            A5["技能执行引擎"]
        end
    end

    R1 -->|"IPC (contextBridge)"| M1
    M3 -->|"spawn"| A1
    A1 -->|"HTTPS + WebSocket"| M3

    subgraph "外部服务"
        S1["Agnes Auth Server<br/>OAuth 认证"]
        S2["Agnes BFF API<br/>api-agnes-code.agnes-ai.com"]
        S3["AI 提供商<br/>OpenAI / Claude / DeepSeek..."]
    end

    M1 -->|"shell.openExternal"| S1
    R1 -->|"HTTPS Bearer Token"| S2
    A2 -->|"ACP WebSocket"| R1
    A3 -->|"HTTPS API Key"| S3

    style A1 fill:#4a90d9,color:#fff
    style A2 fill:#4a90d9,color:#fff
    style R1 fill:#50b86c,color:#fff
    style M1 fill:#e8a838,color:#fff

1.2 核心组件

组件	技术	用途
Electron Shell	Electron 41 + Vite 7	应用容器，主进程管理
Renderer	React 19 + Radix UI + Tailwind 4	用户界面
agnest	Rust (Rust binary)	本地后端服务器
ACP	Agent Client Protocol	代理与AI交互
goose-sdk	`@aaif/goose-sdk`	ACP 客户端 SDK

2. 技术栈分析

2.1 前端技术栈

Electron: 41.0.0 (2025年最新)
Node.js: >=24.10.0 <24.16.0
包管理器: pnpm@10.30.0
构建工具: Electron Forge + Vite 7
UI 框架: React 19.2.4 + Radix UI + Ant Design 5
状态管理: Zustand 5 + SWR 2
样式: Tailwind CSS 4 + Framer Motion
终端: xterm.js + node-pty
I18n: react-intl (支持多语言)
PDF: pdfjs-dist 6
公式: KaTeX

2.2 后端依赖

@aaif/goose-sdk: 内部 ACP 客户端 SDK (workspace 引用)
@agentclientprotocol/sdk: ACP 协议 SDK v0.19.0
@modelcontextprotocol/sdk: MCP SDK v1.27.0
@mcp-ui/client: MCP UI 客户端 6.1.0
koffi: FFI 库 (用于调用本地二进制)
node-pty: 伪终端 (用于执行命令)

2.3 打包与分发

Windows: NSIS 安装器 (AgnesCode-Setup.exe) + Squirrel 框架 (AgnesCode-Installer.exe)
macOS: DMG 安装器 + ZIP 压缩包
更新: electron-updater 6.8.3 + 自建更新服务器

3. 授权登录机制

3.1 登录流程 (OAuth2 变体)

mermaid

sequenceDiagram
    participant App as Desktop App
    participant Browser as Web Browser
    participant Auth as Agnes Auth Server
    participant Renderer as Renderer (React)

    App->>App: 1. 生成 state (32B hex)
    App->>App: 2. 构造登录 URL
    App->>Browser: 3. shell.openExternal
    Browser->>Auth: 4. 用户登录/授权
    Auth->>Browser: 5. 302 Redirect
    Note over Browser: agnes://auth/callback<br/>?code={auth_code}&state={state}
    Browser->>App: 6. Deep Link 回调<br/>(macOS open-url / Windows custom protocol)
    App->>App: 7. 验证 state 匹配
    App->>Renderer: 8. IPC: auth-deeplink {code, state}
    Renderer->>Auth: 9. POST /api/v1/code/auth/exchange-code
    Auth->>Renderer: 10. {access_token, user_info}
    Renderer->>Renderer: 11. 保存 token<br/>localStorage + Keychain

3.2 关键代码分析

登录 URL 构建 (Oj 函数):

javascript

// main.js 中
function Oj(e) {
    const t = process.env.AGNES_SA_WEB_LOGIN_URL?.trim();
    // 默认值: AGNES_SA_WEB_LOGIN_URL 环境变量
    const r = new URL("/login", t);
    r.searchParams.set("client", "agnes-code");
    r.searchParams.set("redirect_uri", "agnes://auth/callback");
    r.searchParams.set("state", e); // 32字节随机 hex
    return r.toString();
}

IPC 处理:

ipcMain.handle("start-auth-login", ...) - 启动登录流程
ipcMain.on("auth-listener-ready", ...) - 监听器就绪通知
ipcRenderer.send("auth-deeplink", {code, state}) - 发送 auth code 到渲染进程

Deep Link 协议: agnes://auth/callback?code={code}&state={state}

3.3 登录数据流

主进程生成 32 字节随机 state (hex 编码)
构造 URL: {AGNES_SA_WEB_LOGIN_URL}/login?client=agnes-code&redirect_uri=agnes://auth/callback&state={state}
通过 shell.openExternal() 在系统浏览器中打开
用户在浏览器中完成登录
浏览器重定向到 agnes://auth/callback?code={auth_code}&state={state}
操作系统处理 agnes:// 协议 → 唤起 Electron 应用
主进程验证 state 匹配
主进程通过 IPC 将 code 发送到渲染进程
渲染进程通过 ACP 将 code 发送到 agnesd 后端
agnesd 后端与 Agnes Auth Server 交换令牌
令牌存储在系统密钥链中

3.4 注意事项

AGNES_SA_WEB_LOGIN_URL 通过环境变量注入，未在代码中硬编码
该环境变量通常在开发/打包时由 scripts/brand-dev-electron.cjs 脚本设置
生产环境中可能指向 https://auth.ag.ai 或类似地址
支持 AGNES_EXTERNAL_BACKEND 环境变量指向外部后端

4. 后端（agnest）架构

4.1 agnest 进程

二进制名称: agnesd (Linux/macOS) / agnesd.exe (Windows)
语言: Rust (编译为本地二进制)
通信协议: HTTPS (自签名证书) + WebSocket
端口: 随机分配 (通过监听端口 0 获取)
认证: X-Secret-Key 请求头 + 自签名证书指纹验证

4.2 启动流程

javascript

// 环境变量传递给 agnesd:
const env = {
    AGNES_PORT: port.toString(),
    AGNES_SERVER__SECRET_KEY: secretKey,
    AGNES_KEYRING_SERVICE: "com.agnes.code.secrets"  // 或 dev 版本
};
// 启动命令: agnesd agent
// 通信: HTTPS + 自签名证书
// 健康检查: GET /health_check 端点

4.3 API 客户端配置

javascript

// 创建 API 客户端
const client = (baseUrl, secretKey) => {
    return createClient({
        baseUrl,
        headers: {
            "Content-Type": "application/json",
            "X-Secret-Key": secretKey
        }
    });
};

4.4 证书验证

使用自签名证书
通过 stdout 输出 GOOSED_CERT_FINGERPRINT= 行
Electron 主进程解析指纹并添加到允许列表
使用 certificateVerifyProc 和 certificate-error 事件进行验证
支持 sha256/ 格式的指纹

5. AI交互协议（ACP）

5.1 ACP 协议概述

ACP (Agent Client Protocol) 是 AgnesCode 的核心协议，用于：

前端 Renderer 与后端 agnesd 之间的通信
agnesd 与底层 AI 模型提供商之间的路由
工具调用 (MCP) 的编排

5.2 ACP WebSocket 连接

javascript

// WebSocket URL 构建函数
function Vj(baseUrl, token) {
    const r = new URL(baseUrl);
    r.pathname = `${r.pathname.replace(/\/+$/, "")}/acp`;
    r.protocol = r.protocol === "https:" ? "wss:" : "ws:";
    r.searchParams.set("token", token);
    return r.toString();
}
// 示例: wss://127.0.0.1:{port}/acp?token={secretKey}

5.3 路由与代理

ACP 支持多模型路由:

mermaid

graph LR
    subgraph "AgnesCode 应用"
        R["Renderer (React)"]
        A["agnest (Rust)"]
    end
    subgraph "外部服务"
        B["Agnes BFF API<br/>api-agnes-code.agnes-ai.com"]
        AI["AI 模型提供商<br/>Agnes / OpenAI / Claude / DeepSeek"]
    end

    R -->|"ACP WebSocket<br/>JSON-RPC 2.0"| A
    A -->|"HTTPS + LiteLLM"| B
    B -->|"路由"| AI
    AI --> B
    B --> A
    A --> R

    style R fill:#50b86c,color:#fff
    style A fill:#4a90d9,color:#fff
    style B fill:#e8a838,color:#fff

5.4 MCP 集成

支持 MCP (Model Context Protocol) 标准
本地工具: 文件系统、终端、Git 等
外部 MCP 服务器: 浏览器、设计工具、文档等
MCP 传输层: 通过 agnesd 代理

5.5 ACP 协议特性

双向流: 基于 WebSocket 的全双工通信
Token 认证: WebSocket URL 中携带 token 参数
会话管理: 支持多会话并行
工具调用: 支持 MCP 工具链
技能执行: 内置技能引擎

6. 密钥管理

6.1 密钥存储

平台	存储方式	服务名称
macOS	Keychain (钥匙串)	`com.agnes.code.secrets`
macOS (dev)	Keychain	`com.agnes.code.dev.secrets`
Windows	Credential Manager	类似 Keychain 接口
Linux	libsecret / 加密文件	同 Keychain 接口

6.2 密钥用途

AGNES_SERVER__SECRET_KEY: 本地 agnesd API 认证密钥
OAuth Token: 用户登录后的访问令牌
AI Provider API Keys: 各 AI 服务商的 API 密钥

6.3 密钥传递

写入: 通过 AGNES_KEYRING_SERVICE 环境变量指定服务名称
读取: Renderer 通过 IPC get-secret-key 获取
使用: 在 ACP WebSocket 连接中作为 token 参数

7. 反向代理设计要点

7.1 拦截点分析

要实现反向代理，有以下几个关键拦截点：

方案 A: 替换 agnesd 后端

优点: 完全控制所有 API 调用
难点: 需要实现完整的 ACP 协议
      需要处理自签名证书
      需要替换 agnesd 二进制文件

流程:
1. 启动自定义后端替代 agnesd
2. 设置 AGNES_EXTERNAL_BACKEND 环境变量
3. 或修改 AGNES_PORT 指向自定义后端

方案 B: 代理 ACP WebSocket

优点: 只需实现 WebSocket 代理
难点: 需要维持 WebSocket 连接状态
      需要处理 token 认证

流程:
1. 监听本地端口
2. 接收 ACP WebSocket 连接
3. 转发到目标 AI 服务
4. 返回结果

方案 C: 替换环境变量

优点: 最简单
难点: 需要能够在启动前设置环境变量
      需要了解所有环境变量的用途

关键环境变量:
- AGNES_SA_WEB_LOGIN_URL: 登录页面 URL
- AGNES_EXTERNAL_BACKEND: 外部后端 URL
- AGNES_SERVER__SECRET_KEY: 后端密钥
- AGNES_DEFAULT_PROVIDER: 默认 AI 提供商
- AGNES_DEFAULT_MODEL: 默认模型
- AGNES_PREDEFINED_MODELS: 预定义模型列表

7.2 环境变量清单

环境变量	用途	示例值
`AGNES_SA_WEB_LOGIN_URL`	登录页面地址	`https://auth.ag.ai`
`AGNES_EXTERNAL_BACKEND`	外部后端地址	`https://127.0.0.1:3000`
`AGNES_SERVER__SECRET_KEY`	后端通信密钥	随机 32 字节 hex
`AGNES_DEFAULT_PROVIDER`	默认 AI 提供商	`openai`
`AGNES_DEFAULT_MODEL`	默认模型	`gpt-4o`
`AGNES_PREDEFINED_MODELS`	预定义模型列表	JSON 字符串
`AGNES_PORT`	后端监听端口	`3000`
`AGNES_PATH_ROOT`	工作目录	`~/Documents/AgnesCode`
`AGNES_KEYRING_SERVICE`	密钥链服务名	`com.agnes.code.secrets`
`AGNES_INITIAL_THEME`	初始主题	`dark`/`light`
`AGNES_LOCALE`	语言设置	`zh-CN`
`AGNES_VERSION`	版本号	`1.0.17`

7.3 推荐的反向代理方案

推荐方案: 代理 agnesd (类似 Claude Code 的 proxy)

1. 自建一个符合 ACP 协议的后端服务
2. 通过环境变量 AGNES_EXTERNAL_BACKEND 指向自定义后端
3. 自定义后端负责:
   - 处理认证 (可绕过 OAuth 直接使用 API Key)
   - 路由到目标 AI 服务
   - 实现工具调用 (MCP)
   - 提供会话管理

或者更简单的方案:
1. 保留 agnesd 后端
2. 在 agnesd 和 AI API 之间插入代理
3. 通过环境变量配置代理地址

7.4 需要关注的端口

连接	方向	协议
Electron → agnesd	本地	HTTPS (127.0.0.1:随机端口)
Electron → agnesd (WS)	本地	WSS (127.0.0.1:随机端口)
agnesd → AI API	外部	HTTPS
agnesd → Auth Server	外部	HTTPS
Electron → GitHub	外部	HTTPS (更新检查)

8. 更新与分发机制

8.1 更新流程

使用 electron-updater 进行自动更新
更新配置文件: latest.yml (Windows) / latest-mac.yml (macOS)
更新服务器: https://github.com/AgnesAI-Labs/AgnesCode/releases/latest/download/
更新检查: 通过 IPC check-for-updates / download-update / install-update

8.2 文件结构

AgnesCode.app/
├── Contents/
│   ├── Info.plist              # Bundle 配置 (bundleId: com.agnes.code)
│   ├── MacOS/
│   │   └── AgnesCode           # Electron 可执行文件
│   ├── Frameworks/
│   │   ├── AgnesCode Helper.app
│   │   ├── AgnesCode Helper (Renderer).app
│   │   └── AgnesCode Helper (GPU).app
│   └── Resources/
│       ├── app.asar            # 核心应用代码
│       ├── electron.icns       # 应用图标
│       └── bin/                # 本地二进制文件
│           └── agnesd          # Rust 后端

8.3 发布版本

版本	日期	包含资产
1.0.23	2026-07-20	9 个文件
1.0.19	2026-07-15	9 个文件
1.0.17	2026-07-14	10 个文件 (含额外 Intel 包)
1.0.15	2026-07-13	8 个文件

9. 附录：关键文件清单

9.1 下载的安装包

data/
├── 1.0.23/
│   ├── AgnesCode-Setup.exe          (Windows NSIS, 14 MB)
│   ├── AgnesCode-Installer.exe      (Windows Squirrel, 93 KB)
│   ├── AgnesCode.dmg                (macOS Apple Silicon, 544 MB)
│   ├── AgnesCode-intel.dmg          (macOS Intel, 562 MB)
│   ├── AgnesCode.zip                (macOS AS ZIP, 未完整下载)
│   └── AgnesCode-darwin-x64.zip     (macOS Intel ZIP, 1.3 MB)
│
├── 1.0.15/
│   ├── AgnesCode-Setup.exe          (Windows NSIS, 21 MB)
│   ├── AgnesCode-Installer.exe      (Windows, 376 MB)
│   ├── AgnesCode.dmg                (macOS, 540 MB)
│   ├── AgnesCode-intel.dmg          (macOS Intel, 376 KB)
│   └── AgnesCode.zip                (未完整下载)
│
├── 1.0.17/                          (已完整解压分析)
│   ├── AgnesCode.zip                (macOS ZIP, 551 MB - 已解压)
│   ├── extracted_zip/               (解压后的 .app 包)
│   │   └── AgnesCode.app/
│   │       └── Contents/Resources/
│   │           └── app.asar         (核心应用代码)
│   └── extracted_asar/              (app.asar 解压内容)
│       ├── package.json
│       ├── .vite/build/
│       │   ├── main.js              (主进程代码, 1.4 MB)
│       │   └── preload.js           (预加载脚本)
│       └── .vite/renderer/main_window/
│           ├── index.html
│           └── assets/
│               ├── index-BXTNYseC.js (渲染进程代码, 320 KB)
│               └── App-Bm0R8Z-4.js   (应用主代码, 6.4 MB)
│
└── 1.0.19/
    ├── AgnesCode-Setup.exe          (Windows NSIS, 440 MB)
    ├── AgnesCode-Installer.exe      (Windows, 376 MB)
    ├── AgnesCode.dmg                (macOS AS, 540 MB)
    └── AgnesCode.zip                (macOS ZIP, 551 MB)

9.2 关键发现摘要

发现项	详情
应用类型	Electron 41 + Vite 7 + React 19
后端语言	Rust (agnest 二进制)
通信协议	ACP (Agent Client Protocol) over WebSocket
认证方式	OAuth2 变体 + Deep Link (agnes://)
密钥存储	系统密钥链 (Keychain/Credential Manager)
AI 路由	通过 agnest 后端代理到多个 AI 提供商
更新机制	electron-updater + GitHub Releases
代理关键	AGNES_EXTERNAL_BACKEND 环境变量
协议关键	ACP WebSocket + X-Secret-Key 认证
证书	自签名证书 + 指纹验证

注意: 本报告基于对 v1.0.17 版本的静态分析。实际行为可能因版本更新而变化。agnest 后端是闭源的 Rust 二进制文件，其内部实现细节需要通过动态分析或反编译进一步确认。

AgnesCode 逆向分析报告 ​

1. 概述与架构 ​

1.1 架构总览 ​

1.2 核心组件 ​

2. 技术栈分析 ​

2.1 前端技术栈 ​

2.2 后端依赖 ​

2.3 打包与分发 ​

3. 授权登录机制 ​

3.1 登录流程 (OAuth2 变体) ​

3.2 关键代码分析 ​

3.3 登录数据流 ​

3.4 注意事项 ​

4. 后端（agnest）架构 ​

4.1 agnest 进程 ​

4.2 启动流程 ​

4.3 API 客户端配置 ​

4.4 证书验证 ​

5. AI交互协议（ACP） ​

5.1 ACP 协议概述 ​

5.2 ACP WebSocket 连接 ​

5.3 路由与代理 ​

5.4 MCP 集成 ​

5.5 ACP 协议特性 ​

6. 密钥管理 ​

6.1 密钥存储 ​

6.2 密钥用途 ​

6.3 密钥传递 ​

7. 反向代理设计要点 ​

7.1 拦截点分析 ​

方案 A: 替换 agnesd 后端 ​

方案 B: 代理 ACP WebSocket ​

方案 C: 替换环境变量 ​

7.2 环境变量清单 ​

7.3 推荐的反向代理方案 ​

7.4 需要关注的端口 ​

8. 更新与分发机制 ​

8.1 更新流程 ​

8.2 文件结构 ​

8.3 发布版本 ​

9. 附录：关键文件清单 ​

9.1 下载的安装包 ​

9.2 关键发现摘要 ​

AgnesCode 逆向分析报告

1. 概述与架构

1.1 架构总览

1.2 核心组件

2. 技术栈分析

2.1 前端技术栈

2.2 后端依赖

2.3 打包与分发

3. 授权登录机制

3.1 登录流程 (OAuth2 变体)

3.2 关键代码分析

3.3 登录数据流

3.4 注意事项

4. 后端（agnest）架构

4.1 agnest 进程

4.2 启动流程

4.3 API 客户端配置

4.4 证书验证

5. AI交互协议（ACP）

5.1 ACP 协议概述

5.2 ACP WebSocket 连接

5.3 路由与代理

5.4 MCP 集成

5.5 ACP 协议特性

6. 密钥管理

6.1 密钥存储

6.2 密钥用途

6.3 密钥传递

7. 反向代理设计要点

7.1 拦截点分析

方案 A: 替换 agnesd 后端

方案 B: 代理 ACP WebSocket

方案 C: 替换环境变量

7.2 环境变量清单

7.3 推荐的反向代理方案

7.4 需要关注的端口

8. 更新与分发机制

8.1 更新流程

8.2 文件结构

8.3 发布版本

9. 附录：关键文件清单

9.1 下载的安装包

9.2 关键发现摘要