glm5.2proxy

Proxy local em Go para usar contas Z.ai/ZCode Start Plan como uma API OpenAI-compatible. O projeto tem dois modos de uso:

• app desktop Wails com painel React para contas, cotas, fila, logs, porta e API keys;
• servidor headless para rodar apenas a API/proxy.

O app expoe /v1/chat/completions e /v1/models para clientes compativeis com OpenAI, traduz as chamadas para o formato usado pelo ZCode e faz rotacao por conta/modelo quando a cota esgota.

Funcionalidades

• Painel desktop Wails/React em cmd/desktop/frontend.
• Login OAuth ZCode pelo backend.
• Cofre local AES-256-GCM para contas e tokens.
• API keys locais para proteger /v1/*.
• Liga/desliga da API OpenAI-compatible sem fechar o painel.
• Reordenacao de contas e ativacao manual.
• Consulta de cota por conta/modelo.
• Rotacao automatica quando a conta ativa esgota.
• Fila local por conta + modelo para evitar limite de concorrencia upstream.
• Streaming e non-streaming.
• Tools/function calling, system/developer messages e resultados de tools.
• Captcha headless com Chrome/Edge e fallback interativo.
• Logs administrativos no painel e em /api/admin/logs.

Arquitetura

Cliente OpenAI-compatible
  -> http://127.0.0.1:3005/v1
  -> Go HTTP/SSE proxy
  -> Tradutor OpenAI Chat Completions
  -> ZCode/GLM upstream

App desktop Wails
  -> Painel React
  -> Go bindings + /api/admin/*
  -> Contas, OAuth, cota, fila, API keys, logs e settings

O runtime Node antigo nao e mais necessario para o proxy. Node/npm ficam apenas no frontend do app desktop.

Executar

Servidor headless:

go run ./cmd/server

Ou pelo script npm da raiz:

npm start

App desktop em desenvolvimento:

npm run desktop:dev

Porta padrao:

http://127.0.0.1:3005

Build

Validacao recomendada:

go test ./...
go vet ./...
npm run build --prefix .\cmd\desktop\frontend

Resumo rapido

• Quer so a API/proxy? Build do cmd/server.
• Quer o app com interface desktop Wails? Build do app desktop.
• Linux headless/server pode ser compilado a partir do Windows.
• Linux desktop Wails deve ser compilado em ambiente Linux real ou WSL2 com as dependencias graficas instaladas. Nao conte com Windows puro para isso.

Windows

Servidor Windows:

npm run build
.\build\glm5.2proxy-server.exe

App desktop Windows:

npm run desktop:build

Saida principal:

build\bin\glm5.2proxy.exe

Linux server/headless compilado no Windows

Se o objetivo for rodar apenas a API OpenAI-compatible sem interface grafica, este comando gera um binario Linux amd64 diretamente da maquina Windows:

$env:CGO_ENABLED='0'
$env:GOOS='linux'
$env:GOARCH='amd64'
go build -trimpath -ldflags='-s -w' `
  -o build\glm5.2proxy-server-linux-amd64 ./cmd/server
Remove-Item Env:GOOS,Env:GOARCH,Env:CGO_ENABLED -ErrorAction SilentlyContinue

Depois, no Linux:

chmod +x ./glm5.2proxy-server-linux-amd64
./glm5.2proxy-server-linux-amd64

Linux desktop Wails

O app desktop Linux nao deve ser buildado no Windows puro. O caminho correto e buildar em:

• Linux nativo; ou
• WSL2/Ubuntu; ou
• CI Linux.

Exemplo em Ubuntu/WSL2:

sudo apt update
sudo apt install -y build-essential pkg-config libgtk-3-dev libwebkit2gtk-4.1-dev
go test ./...
npm install
npm run desktop:build

Saida esperada do desktop Linux:

build/bin/glm5.2proxy

Se o usuario Linux baixou este repositorio do GitHub, ele ja estara com o codigo mais recente; o que ele precisa fazer por conta propria e apenas o build do binario Linux, caso nao exista release pronta para o sistema dele.

Release Local

Os artefatos gerados ficam em:

build\glm5.2proxy-server.exe
build\glm5.2proxy-server-windows-amd64.exe
build\glm5.2proxy-server-linux-amd64
build\bin\glm5.2proxy.exe
release-dist\glm5.2proxy-windows-desktop-amd64.zip
release-dist\glm5.2proxy-linux-desktop-amd64.tar.gz
release-dist\glm5.2proxy-linux-desktop-amd64.deb
release-dist\glm5.2proxy-windows-server-amd64.zip
release-dist\glm5.2proxy-linux-server-amd64.zip
release-dist\SHA256SUMS.txt

release-dist/, cmd/desktop/frontend/dist/ e node_modules/ sao artefatos locais normalmente ignorados pelo Git. Alguns binarios dentro de build/ podem ser versionados manualmente quando o repositorio publica uma build pronta.

Uso no Windows

1. Extraia glm5.2proxy-windows-desktop-amd64.zip em uma pasta fixa.
2. Execute glm5.2proxy.exe.
3. No painel, adicione uma conta ZCode.
4. Crie uma API key no painel.
5. Configure seu cliente OpenAI-compatible:

Base URL: http://127.0.0.1:3005/v1
Model: glm-5.2 ou glm-5-turbo
API key: chave criada no painel

Dados locais:

C:\Users\<usuario>\.glm5.2proxy

Essa pasta contem contas, tokens e configuracoes locais. Nao envie junto com release ou commit.

Uso no Linux

Se voce esta no Linux e nao existe binario pronto para o seu sistema no repositorio/release, faca assim:

1. Baixe o repositorio atual.
2. Escolha se quer server ou desktop.
3. Para server, compile o cmd/server.
4. Para desktop, compile em Linux/WSL2, nao em Windows puro.
5. Rode o binario gerado e configure a conta/API key pelo painel ou pela API.

Em outras palavras: o repositorio ja contem o codigo novo; o que pode faltar e somente o artefato Linux pronto.

Modelos

Modelo publico	Upstream	Cota diaria observada
glm-5.2	GLM-5.2	3.000.000 tokens
glm-5-turbo	GLM-5-Turbo	2.000.000 tokens

Capacidades:

GET /api/admin/models/capabilities
GET /v1/models

API OpenAI-Compatible

POST /v1/chat/completions
POST /chat/completions
GET  /v1/models

Enquanto nenhuma API key estiver cadastrada, o acesso local pode funcionar sem segredo. Depois da primeira chave, envie:

Authorization: Bearer zkp_...

APIs Administrativas

Contas e fila:

GET    /api/admin/accounts
GET    /api/admin/accounts/{id}
POST   /api/admin/accounts/{id}/activate
PUT    /api/admin/accounts/order
DELETE /api/admin/accounts/{id}
GET    /api/admin/queue

Login:

POST /api/admin/auth/login/start
GET  /api/admin/auth/login/poll?flow_id=...

Settings e API keys:

GET    /api/admin/settings
PATCH  /api/admin/settings
GET    /api/admin/api-keys
POST   /api/admin/api-keys
DELETE /api/admin/api-keys/{id}

Thinking:

GET /api/admin/thinking
PUT /api/admin/thinking
GET    /api/admin/accounts/{id}/thinking
PUT    /api/admin/accounts/{id}/thinking
DELETE /api/admin/accounts/{id}/thinking

Logs:

GET /api/admin/logs?limit=200

Captcha:

GET  /zcode/captcha/config
GET  /zcode/captcha/browser
GET  /zcode/captcha/poll
POST /zcode/captcha/submit
POST /zcode/captcha/test

Documentacao detalhada da API: docs/API.md.

Estrutura

cmd/server                  servidor headless
main.go                     app desktop Wails
cmd/desktop/frontend        painel React do app desktop
internal/accounts           cofre e contas
internal/accountpool        fila e rotacao
internal/api                APIs HTTP/admin/OpenAI-compatible
internal/app                composicao e lifecycle
internal/auth               OAuth ZCode
internal/captcha            bridge, pagina e navegador
internal/config             configuracao
internal/models             modelos e capacidades
internal/openai             traducao de formatos
internal/proxy              transporte e SSE
internal/quota              billing e porcentagens
internal/requestqueue       serializacao por conta/modelo
internal/state              porta, API keys e thinking
internal/upstream           credenciais e model-io fallback
tests                       testes Go

Testes

go test ./...
go vet ./...
npm run build --prefix .\cmd\desktop\frontend