# 🔍 WCG - Watch Commits for Git

[![Python Version](https://img.shields.io/badge/python-3.12%2B-blue.svg)](https://www.python.org/downloads/)
[![License](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)

**WCG** 是一个自动化的 GitHub 提交监控和汇总工具，使用 LLM 技术智能分析和总结代码变更。

## ✨ 功能特性

- 🤖 **智能汇总**：使用 LLM（OpenAI 兼容 API）自动生成中文提交汇总
- 📊 **分类整理**：按照新增、修改、删除等类型分类展示
- 🔗 **PR 关联**：自动关联 Pull Request 并提供文件变更链接
- ⏰ **定时执行**：每天定时（默认 10:00）自动处理前 24 小时的提交
- 📢 **Webhook 通知**：支持多种 Webhook 格式（通用、Slack、Discord、飞书）
- 💾 **本地存储**：按日期保存汇总内容到本地
- 🌐 **Web 配置界面**：提供友好的 Web UI 管理配置
- 📦 **易于部署**：使用 `uv` 打包，可发布到 PyPI

## 📦 安装

### 从 PyPI 安装

```bash
pip install wcg
```

### 从源码安装

```bash
# 克隆仓库
git clone https://github.com/wZuck/WCG.git
cd WCG

# 使用 uv 安装
uv pip install -e .
```

## 🚀 快速开始

### 1. 配置

复制示例配置文件：

```bash
mkdir -p config
cp config/config.example.yaml config/config.yaml
```

编辑 `config/config.yaml`，填入你的配置信息：

```yaml
llm:
  api_url: "https://api.openai.com/v1"
  api_key: "your-api-key-here"
  model: "gpt-3.5-turbo"

github_token: "your-github-token-here"

repositories:
  - name: "owner/repository"
    branch: "main"
    webhook_url: "https://your-webhook-url.com"

schedule_time: "10:00"
timezone: "Asia/Shanghai"  # UTC+8 中国标准时间
summary_dir: "summaries"
```

**注意**：`schedule_time` 使用配置的时区（默认 `Asia/Shanghai` UTC+8）。如果服务器时间不准确，可以设置 `timezone` 为目标时区，程序会自动按照该时区执行。

### 2. 使用 Web 界面配置（推荐）

启动 Web 配置服务器：

```bash
wcg-web
```

访问 http://localhost:5000 在浏览器中配置。

### 3. 运行

#### 启动定时任务

```bash
wcg start
```

#### 立即运行一次（测试）

```bash
wcg run-once
```

#### 使用自定义配置文件

```bash
wcg start --config /path/to/config.yaml
```

#### 设置日志级别

```bash
wcg start --log-level DEBUG
```

## 📖 使用说明

### 命令行工具

WCG 提供两个命令行工具：

1. **wcg** - 主程序，用于启动定时任务
   - `wcg start` - 启动定时调度器
   - `wcg run-once` - 立即执行一次（用于测试）

2. **wcg-web** - Web 配置界面
   - 启动后访问 http://localhost:5000 进行配置管理

### 配置说明

#### LLM 配置

- **api_url**: LLM API 地址（支持 OpenAI 兼容的接口）
- **api_key**: API 密钥
- **model**: 使用的模型名称

#### GitHub 配置

- **github_token**: GitHub Personal Access Token
  - 需要 `repo` 权限来访问私有仓库
  - 公开仓库也需要 token 来避免 API 限制

#### 仓库配置

每个仓库配置包括：
- **name**: 仓库名称（格式：`owner/repo`）
- **branch**: 要监控的分支
- **webhook_url**: 接收汇总的 Webhook 地址

#### 其他配置

- **schedule_time**: 定时执行时间（24 小时制，格式：`HH:MM`）
- **timezone**: 时区设置（默认：`Asia/Shanghai` UTC+8）
  - 使用标准 IANA 时区名称，如 `Asia/Shanghai`、`America/New_York` 等
  - 如果服务器时间不准确，可设置此项来指定目标时区
  - 程序会按照指定时区在 `schedule_time` 执行任务
- **summary_dir**: 本地保存汇总的目录

### 输出格式

生成的汇总采用 Markdown 格式，包含：

- 📝 **标题**：仓库名称和分支
- 🆕 **新增功能**：新增的文件和功能
- 🔧 **代码修改**：修改的文件和内容
- 🗑️ **删除内容**：删除的文件
- 🔗 **PR 链接**：相关 Pull Request 的链接

### Webhook 支持

WCG 支持多种 Webhook 格式：

- **通用格式**：标准 JSON payload
- **Slack**：适配 Slack 的消息格式
- **Discord**：适配 Discord 的嵌入消息
- **飞书（Lark）**：适配飞书的消息卡片

### 本地存储

汇总文件按以下结构保存：

```
summaries/
├── 2024-01/
│   ├── 01/
│   │   └── owner-repo-main.md
│   ├── 02/
│   │   └── owner-repo-main.md
```

## 🔧 开发

### 环境设置

```bash
# 安装开发依赖
uv pip install -e ".[dev]"

# 运行测试
pytest

# 代码格式化
ruff format .

# 代码检查
ruff check .
```

### 项目结构

```
WCG/
├── src/wcg/
│   ├── __init__.py          # 包初始化
│   ├── cli.py               # 命令行界面
│   ├── config.py            # 配置管理
│   ├── github_client.py     # GitHub API 客户端
│   ├── summarizer.py        # LLM 汇总器
│   ├── notifier.py          # Webhook 通知
│   ├── storage.py           # 本地存储
│   ├── scheduler.py         # 定时调度器
│   ├── web.py               # Web 界面
│   └── templates/
│       └── index.html       # Web UI 模板
├── config/
│   └── config.example.yaml  # 配置示例
├── summaries/               # 汇总输出目录
├── tests/                   # 测试文件
├── pyproject.toml          # 项目配置
└── README.md               # 本文件
```

## 📝 许可证

MIT License

## 🤝 贡献

欢迎提交 Issue 和 Pull Request！

## 📮 联系

如有问题或建议，请提交 [Issue](https://github.com/wZuck/WCG/issues)。
