Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
224 lines (162 loc) · 8.75 KB

CONTRIBUTING.md

File metadata and controls

224 lines (162 loc) · 8.75 KB

Contributing / 贡献指南

Thank you for your interest in contributing to Metapi! / 感谢您对 Metapi 项目的贡献！

Metapi is a meta-aggregation layer for AI API platforms (New API, One API, OneHub, etc.), providing unified proxy, intelligent routing, and centralized management.

Metapi 是 AI API 聚合平台（New API、One API、OneHub 等）的元聚合层，提供统一代理、智能路由和集中管理。

Before You Start / 开始之前

Local Development Setup / 本地开发环境设置

Prerequisites / 前置要求

  • Node.js 20+ / Node.js 20 或更高版本
  • npm or compatible package manager / npm 或兼容的包管理器

Setup Steps / 设置步骤

  1. Fork and clone the repository / Fork 并克隆仓库
git clone https://github.com/YOUR_USERNAME/metapi.git
cd metapi
  1. Install dependencies / 安装依赖
npm install
  1. Create environment file / 创建环境文件
# Windows PowerShell
Copy-Item .env.example .env

# Linux/macOS/Git Bash
cp .env.example .env

Edit .env and set your tokens / 编辑 .env 并设置您的令牌:

AUTH_TOKEN=your-dev-admin-token
PROXY_TOKEN=your-dev-proxy-token
  1. Initialize database / 初始化数据库
npm run db:migrate
  1. Start development server / 启动开发服务器
npm run dev

The app will be available at http://localhost:4000 (backend) and http://localhost:5173 (frontend).

应用将在 http://localhost:4000（后端）和 http://localhost:5173（前端）可用。

Development Commands / 开发命令

Web Application / Web 应用

npm run dev              # Start backend + frontend with hot reload / 启动后端 + 前端热更新
npm run dev:server       # Start backend only / 仅启动后端
npm run build            # Build all (web + server + desktop) / 构建全部
npm run build:web        # Build frontend only / 仅构建前端
npm run build:server     # Build backend only / 仅构建后端

Desktop Application / 桌面应用

npm run dev:desktop              # Start desktop app in dev mode / 开发模式启动桌面应用
npm run build:desktop            # Build desktop app / 构建桌面应用
npm run dist:desktop             # Package desktop app / 打包桌面应用
npm run dist:desktop:mac:intel   # Package for macOS Intel / 打包 macOS Intel 版本

Documentation / 文档

npm run docs:dev         # Start VitePress dev server / 启动 VitePress 开发服务器
npm run docs:build       # Build documentation / 构建文档
npm run docs:preview     # Preview built docs / 预览构建的文档

Testing / 测试

npm test                 # Run all tests / 运行所有测试
npm run test:watch       # Run tests in watch mode / 监听模式运行测试
npm run smoke:db         # Database smoke test (SQLite) / 数据库冒烟测试（SQLite）
npm run smoke:db:mysql   # MySQL smoke test / MySQL 冒烟测试
npm run smoke:db:postgres # PostgreSQL smoke test / PostgreSQL 冒烟测试

Database / 数据库

npm run db:generate      # Generate Drizzle migration files / 生成 Drizzle 迁移文件
npm run db:migrate       # Run database migrations / 运行数据库迁移
npm run schema:generate  # Generate schema artifacts / 生成 schema 构件

Project Structure / 项目结构

metapi/
├── src/
│   ├── server/          # Backend (Fastify) / 后端（Fastify）
│   │   ├── routes/      # API routes / API 路由
│   │   ├── services/    # Business logic / 业务逻辑
│   │   ├── db/          # Database & ORM / 数据库与 ORM
│   │   └── middleware/  # Middleware / 中间件
│   ├── web/             # Frontend (React + Vite) / 前端（React + Vite）
│   └── desktop/         # Electron desktop app / Electron 桌面应用
├── docs/                # VitePress documentation / VitePress 文档
├── drizzle/             # Database migrations / 数据库迁移
└── scripts/             # Build & dev scripts / 构建与开发脚本

Pull Request Guidelines / Pull Request 指南

Before Submitting / 提交之前

  1. Keep PRs focused and small / 保持 PR 专注且小巧

    • One feature or fix per PR / 每个 PR 一个功能或修复
    • Split large changes into multiple PRs / 将大型更改拆分为多个 PR

  2. Write tests / 编写测试

    • Add tests for new features / 为新功能添加测试
    • Update tests for behavior changes / 为行为变更更新测试
    • Ensure all tests pass: npm test / 确保所有测试通过：npm test

  3. Update documentation / 更新文档

    • Update README if adding user-facing features / 如果添加面向用户的功能，请更新 README
    • Update docs/ for configuration or API changes / 配置或 API 更改请更新 docs/
    • Add JSDoc comments for new functions / 为新函数添加 JSDoc 注释

  4. Run checks / 运行检查

    • Documentation changes: npm run docs:build / 文档更改：npm run docs:build
    • Code changes: npm test && npm run build / 代码更改：npm test && npm run build
    • Database changes: npm run smoke:db / 数据库更改：npm run smoke:db
    • Architecture / repo drift changes: npm run repo:drift-check / 架构与仓库漂移检查：npm run repo:drift-check

  5. Follow code style / 遵循代码风格

    • Use TypeScript for type safety / 使用 TypeScript 确保类型安全
    • Follow existing code patterns / 遵循现有代码模式
    • Follow repo-level engineering rules in AGENTS.md / 遵循仓库根目录 AGENTS.md 中的工程规则
    • Keep functions small and focused / 保持函数小而专注

Commit Messages / 提交信息

Use conventional commit format / 使用约定式提交格式:

<type>: <description>

[optional body]

Types / 类型:

  • feat: New feature / 新功能
  • fix: Bug fix / 错误修复
  • docs: Documentation / 文档
  • refactor: Code refactoring / 代码重构
  • test: Tests / 测试
  • chore: Build/tooling / 构建/工具

Examples / 示例:

feat: add AnyRouter platform adapter
fix: handle empty model list in dashboard
docs: update Docker deployment guide
refactor: extract route selection logic
test: add tests for checkin reward parser
chore: upgrade Vite to 6.0

What Not to Commit / 不要提交的内容

  • Runtime data: data/, tmp/ / 运行时数据：data/、tmp/
  • Environment files: .env (only .env.example is tracked) / 环境文件：.env（仅跟踪 .env.example）
  • Build artifacts: dist/, node_modules/ / 构建产物：dist/、node_modules/
  • IDE-specific files (unless beneficial to all contributors) / IDE 特定文件（除非对所有贡献者有益）

Platform Adapters / 平台适配器

If you're adding support for a new AI API platform / 如果您要添加对新 AI API 平台的支持:

  1. Create adapter in src/server/services/platforms/ / 在 src/server/services/platforms/ 中创建适配器
  2. Implement required interfaces: login, balance, models, proxy / 实现必需接口：登录、余额、模型、代理
  3. Add platform tests / 添加平台测试
  4. Update documentation with platform details / 更新文档说明平台详情

Windows Development Notes / Windows 开发注意事项

  • Use restart.bat to restart dev server (clears port locks) / 使用 restart.bat 重启开发服务器（清除端口锁定）
  • Use PowerShell Copy-Item instead of cp / 使用 PowerShell 的 Copy-Item 而不是 cp
  • If Node.js upgrade breaks scripts, run npm install again / 如果 Node.js 升级导致脚本损坏，请重新运行 npm install

Getting Help / 获取帮助

License / 许可证

By contributing, you agree that your contributions will be licensed under the MIT License.

通过贡献，您同意您的贡献将根据 MIT 许可证 授权。