Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
367 lines (268 loc) · 8.99 KB

CONTRIBUTING.md

File metadata and controls

367 lines (268 loc) · 8.99 KB

贡献指南 / Contributing Guide

感谢你对 AutoGLM-GUI 的关注！我们欢迎各种形式的贡献，无论是修复 bug、添加新功能、改进文档还是提出建议。

📋 目录

🎯 贡献类型

我们欢迎以下类型的贡献：

🐛 修复 Bug

  • 在 Issues 中查找标记为 bug 的问题
  • 如果发现新的 bug，请先创建 Issue 描述问题

✨ 添加新功能

  • 查找标记为 enhancement 或 feature 的 Issue
  • 对于较大的功能，建议先创建 Issue 讨论设计方案

📖 改进文档

  • 修复文档中的错误或不清晰的地方
  • 添加使用示例和最佳实践
  • 翻译文档到其他语言

🧪 添加测试

  • 为现有功能添加单元测试
  • 改进测试覆盖率
  • 添加集成测试

🎨 UI/UX 改进

  • 优化界面交互体验
  • 修复前端样式问题
  • 提升可访问性

🚀 快速开始

前置要求

确保你的环境中已安装：

  • Python 3.10+
  • Node.js 18+ 和 pnpm
  • uv（Python 包管理器）- 安装教程
  • ADB (Android Debug Bridge) - 需要添加到系统 PATH

安装 uv

# macOS/Linux
curl -LsSf https://astral.sh/uv/install.sh | sh

# Windows
powershell -c "irm https://astral.sh/uv/install.ps1 | iex"

克隆仓库

git clone https://github.com/suyiiyii/AutoGLM-GUI.git
cd AutoGLM-GUI

🏷️ 认领任务

查找任务

  1. 浏览 Issues 页面
  2. 查找带有以下标签的 Issue：
    • good first issue - 适合新手的任务
    • help wanted - 需要社区帮助的任务
    • bug - Bug 修复
    • enhancement - 功能增强

认领流程

在你想要处理的 Issue 下评论：

/assign me

或者：

I'd like to work on this

维护者会将 Issue 分配给你，并提供必要的指导。

注意事项

  • 如果一个 Issue 已经有人认领（已分配给某人），请不要重复认领
  • 如果你认领后 7 天内没有进展，Issue 可能会被重新开放
  • 遇到困难时，及时在 Issue 中提问，我们很乐意帮助

💻 本地开发

1. 安装依赖

后端依赖：

# 在项目根目录
uv sync

前端依赖：

cd frontend
pnpm install

2. 启动开发服务器

启动后端（支持热重载）：

# 在项目根目录
uv run autoglm-gui --base-url http://localhost:8080/v1 --reload

注意：需要一个 OpenAI 兼容的 API 端点。测试时可以使用智谱 BigModel 或自建服务。

启动前端（热重载）：

cd frontend
pnpm dev

前端开发服务器会在 http://localhost:3000 启动，并自动代理 API 请求到后端。

3. 运行 Linting

提交代码前，请运行 linting 检查：

# 在项目根目录
uv run python scripts/lint.py

这会检查：

  • Python 代码格式（使用 ruff）
  • TypeScript/React 代码格式（使用 ESLint）

4. 构建项目

构建前端：

uv run python scripts/build.py

构建完整包（包括打包为 wheel）：

uv run python scripts/build.py --pack

📁 代码结构

项目目录速览

AutoGLM-GUI/
├── AutoGLM_GUI/              # 后端 FastAPI 应用
│   ├── api/                  # API 路由模块
│   │   ├── __init__.py       # 应用工厂
│   │   ├── agents.py         # Agent 生命周期管理
│   │   ├── devices.py        # 设备管理
│   │   └── control.py        # 设备控制
│   ├── device_manager.py     # 设备发现单例
│   ├── phone_agent_manager.py # Agent 生命周期单例
│   ├── scrcpy_stream.py      # 视频流管理
│   ├── config_manager.py     # 配置管理
│   ├── logger.py             # 日志系统
│   └── adb_plus/             # ADB 扩展工具
│
├── frontend/                 # React 前端
│   ├── src/
│   │   ├── routes/           # 页面路由
│   │   │   ├── chat.tsx      # 主聊天界面
│   │   │   └── workflows.tsx # 工作流管理
│   │   ├── components/       # React 组件
│   │   │   ├── ScrcpyPlayer.tsx  # 视频播放器
│   │   │   ├── ChatKitPanel.tsx  # 聊天面板
│   │   │   └── DevicePanel.tsx   # 设备面板
│   │   └── api.ts            # API 客户端
│   └── package.json
│
├── scripts/                  # 构建和工具脚本
│   ├── build.py              # 前端构建脚本
│   ├── lint.py               # 代码检查
│   └── build_electron.py     # Electron 打包
│
├── CLAUDE.md                 # AI 辅助开发文档（项目技术细节）
├── README.md                 # 用户文档
└── pyproject.toml            # Python 项目配置

关键入口文件

  • 后端入口: AutoGLM_GUI/__main__.py - CLI 入口点
  • API 应用: AutoGLM_GUI/api/__init__.py - FastAPI 应用工厂
  • 前端入口: frontend/src/main.tsx - React 应用入口
  • 路由配置: frontend/src/routes/__root.tsx - 根布局和路由

技术栈

后端：

  • FastAPI + Uvicorn (Web 框架)
  • Socket.IO (实时通信)
  • ADB (Android 设备控制)
  • scrcpy (屏幕流)
  • loguru (日志)

前端：

  • React 19 + TypeScript
  • TanStack Router (路由)
  • Tailwind CSS 4 (样式)
  • Radix UI (组件库)
  • Socket.IO Client (实时通信)

📝 提交规范

我们遵循 Conventional Commits 规范：

Commit 格式

<类型>(<范围>): <简短描述>

[可选的详细描述]

[可选的脚注]

类型 (Type)

  • feat: 新功能
  • fix: Bug 修复
  • docs: 文档变更
  • style: 代码格式调整（不影响功能）
  • refactor: 重构（既不是新功能也不是 bug 修复）
  • perf: 性能优化
  • test: 添加或修改测试
  • chore: 构建过程或辅助工具的变动

范围 (Scope)

可选，指明改动的模块：

  • api - 后端 API
  • frontend - 前端
  • device - 设备管理
  • agent - Agent 相关
  • ui - 用户界面
  • build - 构建系统
  • docs - 文档

示例

feat(api): add layered agent support
fix(frontend): fix video stream coordinate transformation
docs: update installation guide for Windows users
refactor(device): simplify device discovery logic

🔍 Pull Request 要求

提交前检查清单

  • 代码通过 linting 检查 (uv run python scripts/lint.py)
  • 对于新功能，添加了相应的文档说明
  • 对于 UI 改动，提供了截图或录屏
  • Commit 信息遵循规范格式
  • PR 描述清晰说明了改动内容和原因

PR 标题格式

PR 标题应该简洁明了，建议格式：

<类型>: <简短描述>

例如：

  • feat: add WiFi device pairing support
  • fix: resolve video stream crash on device disconnect
  • docs: improve quick start guide

PR 描述模板

提交 PR 时，请使用以下模板：

## 改动说明

<!-- 简要描述这个 PR 做了什么 -->

## 相关 Issue

<!-- 关联的 Issue 编号，如 Closes #123 -->

## 改动类型

- [ ] Bug 修复
- [ ] 新功能
- [ ] 文档更新
- [ ] 代码重构
- [ ] 性能优化
- [ ] 其他（请说明）

## 测试说明

<!-- 如何测试这些改动？ -->

## 截图/录屏

<!-- 对于 UI 改动，请提供截图或录屏 -->

## 其他说明

<!-- 其他需要说明的内容 -->

Code Review

提交 PR 后：

  1. 维护者会审查你的代码
  2. 可能会提出改进建议
  3. 请及时回复评论并根据反馈调整代码
  4. 所有讨论解决后，PR 会被合并

🤝 行为准则

我们的承诺

为了营造一个开放和友好的环境，我们承诺：

  • 尊重不同的观点和经验
  • 优雅地接受建设性批评
  • 关注对社区最有利的事情
  • 对其他社区成员表示同理心

不可接受的行为

以下行为被视为不可接受：

  • 使用性别化的语言或图像，以及不受欢迎的性关注
  • 骚扰性评论、侮辱性/贬损性评论，以及人身或政治攻击
  • 公开或私下骚扰
  • 未经明确许可，发布他人的私人信息
  • 其他在专业环境中可能被认为不适当的行为

🎉 感谢贡献

感谢你花时间为 AutoGLM-GUI 做出贡献！你的努力让这个项目变得更好。

有任何问题？欢迎：

提示：更多技术细节请参考 CLAUDE.md，这是一份面向 AI 辅助开发的技术文档，包含了完整的架构说明。