# Proxy Playbook · 反代原理与代码提取

> 纯原理 + 关键代码，不包含完整项目。
> 代码提取自 RainyToken App 的本地反向代理模块，用于研究“把登录态账号变成本地 OpenAI 兼容 API”的实现思路。

## 这是什么

一个 **本地 OpenAI 兼容反向代理** 的核心：

- App 内起一个本地 HTTP 服务（http://127.0.0.1:8787/v1）
- 客户端（任何 OpenAI SDK）把请求发给本地端口
- 代理根据**模型名前缀**路由到不同上游（Trae / WorkBuddy / 通用 Sub2API）
- 从**账号池**里按会话/地区选出可用账号，携带真实登录态请求上游

    OpenAI Client ---> Local Proxy ---> ProviderRouter ---> TraeChatProxy ---> api.trae...
                                            |              WorkBuddyChatProxy ---> copilot.tencent.com
                                            ---> AccountPool ---> Sub2ApiChatProxy ---> 任意 OpenAI 兼容站

## 目录

    README.md
    docs/
      ARCHITECTURE.md          # 整体架构、路由表、请求生命周期
      TRAE_PROTOCOL.md         # Trae CN/INTL 上游协议（llm_utils_chat / SOLO）
      WORKBUDDY_PROTOCOL.md    # WorkBuddy 上游协议（/v2/chat/completions）
      SSE_NORMALIZATION.md     # 私有 SSE 信封 → OpenAI 事件流
    code/
      local_server/            # Ktor 本地服务（接口 + 实现）
      model/                   # 路由/地区/请求/响应/SSE 模型
      routing/                 # 模型前缀 → ProviderKind/Region
      pool/                    # 账号池（轮询、会话粘性、地区匹配）
      upstream/                # Sub2API / Trae / WorkBuddy 上游适配器

## 快速使用

这些 Kotlin 文件是从 Android App 里按原样提取的，不是独立可构建项目。
接入你自己的项目时：

1. 引入依赖：ktor-server-core / ktor-server-cio / ktor-server-content-negotiation / ktor-serialization-kotlinx-json / OkHttp / kotlinx.serialization
2. 用 Hilt/Dagger/Koin 把 KtorLocalProxyServer 注入为单例
3. 实现 CredentialRepository，返回各家的登录态凭据
4. 调用 localProxyServer.start(ProxyServerConfig(apiKey = "xxx"))

## 免责声明

- 仅供学习 / 个人自动化研究
- 上游协议可能随时变化，提取时以对应参考仓库为基准
- 请遵守各家服务条款，账号风险自负