MuxueTools

OpenAI Compatible Gemini API Proxy

---

Features

• OpenAI Compatible API - Seamless integration with existing OpenAI applications
• Multi-Key Rotation - Smart load balancing and automatic failover
• Built-in Chat UI - Beautiful Claude-style interface
• Statistics Dashboard - Real-time API usage monitoring
• Multi-language Support - Chinese, English, Japanese
• Stream/Non-stream Output - Configurable response mode
• Session Persistence - Auto-save chat history
• Auto Update Detection - Dual source update (mxln server + GitHub)

---

Quick Start

Download

Get the latest version from Releases

Run

Windows:

.\muxueTools.exe

Linux/macOS:

chmod +x muxueTools
./muxueTools

Ubuntu (via .deb package):

# Install
sudo dpkg -i muxuetools_*.deb
sudo apt-get install -f  # Install dependencies if needed

# Run
muxuetools

# Uninstall
sudo dpkg -r muxuetools

Access

Open browser: http://localhost:8080

---

API Endpoints

Endpoint	Description
POST /v1/chat/completions	OpenAI compatible chat API
GET /v1/models	List available models
GET /health	Health check
GET /api/keys	Manage API Keys
GET /api/config	Configuration management

Quick Test

from openai import OpenAI

client = OpenAI(
    base_url="http://localhost:8080/v1",
    api_key="sk-mxln-proxy-local"  # No key needed for local proxy
)

response = client.chat.completions.create(
    model="gemini-2.0-flash",
    messages=[{"role": "user", "content": "Hello!"}],
    stream=True
)

for chunk in response:
    print(chunk.choices[0].delta.content, end="")

---

Configuration

Config file: config.yaml in the program directory.

server:
  port: 8080
  host: "0.0.0.0"

pool:
  strategy: "round_robin"  # round_robin, random, least_used, weighted
  cooldown_seconds: 60
  max_retries: 3

logging:
  level: "info"  # debug, info, warn, error

update:
  enabled: true
  source: "mxln"  # mxln or github

model_settings:
  stream_output: true  # Enable streaming output
  temperature: 1.0

Desktop Version: Fixed Port

By default, the Desktop version uses port 8080. To change:

1. Via Settings UI: Go to Settings → Security → Server Port, modify and save, then restart the app
2. Via config.yaml: Set server.port to your desired port (e.g., 8888)

Note: If the configured port is in use, the app will automatically fall back to a random available port.

Example for Cursor/third-party integration:

• API Key: Your proxy key from Dashboard
• Base URL: http://127.0.0.1:8080/v1

---

Development

Requirements

• Go 1.22+
• Node.js 18+
• npm or pnpm

Local Development

# 1. Clone repository
git clone https://github.com/muxueliunian/muxueTools.git
cd muxueTools

# 2. Install frontend dependencies
cd web
npm install

# 3. Start frontend dev server
npm run dev

# 4. Start backend (new terminal)
cd ..
go run ./cmd/server

Build

Using Build Scripts (Recommended)

Windows (PowerShell):

# Build all targets
.\scripts\build.ps1 all

# Build server only
.\scripts\build.ps1 server

# Build desktop only
.\scripts\build.ps1 desktop

# Build Windows installer (requires Inno Setup 6)
.\scripts\build.ps1 installer

# Clean build artifacts
.\scripts\build.ps1 clean

Linux/macOS (Bash):

# First time: make script executable
chmod +x scripts/build.sh

# Build all targets
./scripts/build.sh all

# Build server only
./scripts/build.sh server

# Build desktop only (requires GTK3 + WebKit2GTK)
./scripts/build.sh desktop

# Clean build artifacts
./scripts/build.sh clean

Linux Desktop Build Requirements

Desktop build on Linux requires GTK3 and WebKit2GTK dependencies:

# Ubuntu/Debian
sudo apt-get update
sudo apt-get install -y libgtk-3-dev libwebkit2gtk-4.1-dev

# Fedora
sudo dnf install gtk3-devel webkit2gtk4.1-devel

Manual Build

# Frontend build
cd web
npm run build

# Backend build (Windows)
go build -ldflags="-s -w" -o build/muxueTools.exe ./cmd/server

# Backend build (Linux)
CGO_ENABLED=0 go build -ldflags="-s -w" -o build/muxuetools-server ./cmd/server

# Desktop build (Windows)
go build -ldflags="-s -w -H windowsgui" -o build/muxueTools-desktop.exe ./cmd/desktop

# Desktop build (Linux, requires GTK3/WebKit2GTK)
CGO_ENABLED=1 go build -ldflags="-s -w" -o build/muxuetools-desktop ./cmd/desktop

---

Release Process

Version Numbering

Follow Semantic Versioning: MAJOR.MINOR.PATCH

• MAJOR: Incompatible API changes
• MINOR: New features (backward compatible)
• PATCH: Bug fixes (backward compatible)

Release Steps

Step 1: Update Version Numbers

Update the following files:

File	Location
web/package.json	"version": "x.x.x"
cmd/server/main.go	Version = "x.x.x"
cmd/desktop/main.go	Version = "x.x.x"

Step 2: Update CHANGELOG

Add new version changes to CHANGELOG.md.

Step 3: Verify Build

# Frontend build
cd web && npm run build

# Backend build
go build ./...

# Test version
go build -o test.exe ./cmd/server && .\test.exe -version

Step 4: Prepare Release Notes ⭐

Important: Use multi-language (EN/CN/JP) commit messages for better documentation.

See Release Notes Automation Guide for:

• ✅ Auto-generate Release Notes from commit message
• ✅ Multi-language template (Chinese, English, Japanese)
• ✅ "Write once, use everywhere" workflow

Quick workflow:

# Use prepared commit message template
git commit -F .git/COMMIT_EDITMSG_v0.X.0

Step 5: Commit Changes

git add .
git commit -m "chore: bump version to vX.X.X"
git push origin main

Step 6: Create Tag

For recommended workflow (auto-use commit message):

# Create lightweight tag (will use commit message as Release Notes)
git tag vX.X.X

# Push tag
git push origin vX.X.X

Alternative - Annotated tag with separate Release Notes:

# Create annotated tag
git tag -a vX.X.X -F .git/TAG_MSG_vX.X.X

# Push tag
git push origin vX.X.X

Step 7: Automatic Deployment

After pushing the tag, GitHub Actions will automatically:

1. Build frontend and backend
2. Build Windows installer (.exe) and portable (.zip)
3. Build Linux tarball and .deb package
4. Generate latest.json version info
5. Upload to FTP server
6. Create GitHub Release with commit/tag message

Step 8: Verify Release

• Check Releases page
• Verify download links work
• Test auto-update functionality

---

CI/CD Configuration

Automation Flow

Push v* Tag -> Build -> Package -> FTP Upload -> Create Release

Required Secrets

Configure in repo Settings -> Secrets -> Actions:

Secret	Description
FTP_SERVER	FTP server address
FTP_USERNAME_TOOLS	FTP username
FTP_PASSWORD_TOOLS	FTP password

Update Service

The app supports dual-source update checking:

Source	URL
mxln Server	https://mxlnuma.space/muxueTools/update/latest.json
GitHub	GitHub Releases API

---

Project Structure

muxueTools/
├── cmd/
│   ├── server/      # Server entry point
│   └── desktop/     # Desktop app entry point
├── internal/
│   ├── api/         # HTTP handlers
│   ├── config/      # Configuration management
│   ├── gemini/      # Gemini client
│   ├── keypool/     # Key pool management
│   ├── storage/     # Data persistence
│   └── types/       # Type definitions
├── web/             # Vue3 frontend
│   ├── src/
│   │   ├── api/         # API client
│   │   ├── components/  # UI components
│   │   ├── views/       # Pages
│   │   ├── stores/      # Pinia stores
│   │   └── i18n/        # Internationalization
│   └── dist/        # Build output
├── docs/            # Documentation
├── scripts/         # Build scripts
└── .github/
    └── workflows/   # CI/CD config

---

Documentation

See docs/ directory:

• API Documentation
• Architecture
• Development Guide
• Release Notes Automation ⭐
• Task Planning

---

License

MIT License

---

Acknowledgments

• Google Gemini - AI model provider
• Vue.js - Frontend framework
• Naive UI - UI component library
• Gin - Go web framework

---

Made with love by muxueliunian