# CodeZen
> 一个专注中文区的 GitHub 项目发现

---

### 📖 关于本项目

`CodeZen` 是一个全栈的 Web 应用，旨在解决“GitHub 上的中文项目信息过载”问题。

它通过一个 **7x24 小时无人值守**的爬虫，自动抓取 GitHub 上**近期**（7天内）、**热门**（>50星）且**包含中文内容**的仓库，并将其以一个美观、可交互的“卡片式”界面呈现。

本应用是**“HTMX 驱动”**的，所有筛选、排序和分页操作均可“无刷新”丝滑完成，提供了现代化的单页应用 (SPA) 体验。

### ✨ 主要功能

* **7x24 自动更新：** 应用启动后，`APScheduler` 后台调度器会自动（每 4 小时）抓取最新项目，无需人工干预。
* **智能中文筛选：** 独有的“智能扫描”逻辑，优先检查项目 `description`，其次扫描 `README_CN.md` 或 `README.md`，确保 100% 收录中文相关项目。
* **多重协同筛选 (100% 自动)：**
    * **语言筛选：** 自动从数据库中 `SELECT DISTINCT` 提取**所有已抓取**的语言，动态生成筛选器。
    * **主题筛选：** 自动**实时统计**数据库中 Top 20 热门 `Topics`，动态生成功能筛选器。
* **协同工作流：** 语言、主题、排序、分页、搜索**五大功能**可以完美协同工作（例如：搜索“AI”项目中，`Python` 语言下，`按热度排序` 的第 2 页）。
* **稳定搜索：** 采用稳定的“回车键”搜索，可（通过 HTMX）无刷新更新结果。
* **现代 UI/UX：**
    * 响应式卡片布局 (`Grid` + `flex-wrap`)。
    * 支持手动切换和系统记忆的“深色/浅色”模式。
    * 清晰的三区卡片视觉划分（标题、内容、元数据）。

### 🛠️ 技术栈

* **后端：** Flask, APScheduler
* **前端：** HTMX, Tailwind CSS, Material Symbols
* **数据库：** SQLite3
* **抓取器：** Python (Requests, Collections)

### 📁 文件结构
```

CodeZen/
├── webapp.py         # 主程序: Flask + APScheduler 调度器
├── scraper.py          # 抓取器: 封装了所有 GitHub API 逻辑
├── templates/
│   ├── index.html      # "外壳"模板 (含页眉, 页脚, 搜索框)
│   └── _projects_partial.html  # "内容"模板 (含筛选器, 卡片, 分页)
└── github_projects.db  # 自动生成的 SQLite 数据库

```
### 🚀 如何运行

1.  **克隆仓库**
    ```bash
    git clone https://git.wlens.top/laowang/CodeZen.git
    cd CodeZen
    ```

2.  **创建并激活虚拟环境**
    ```bash
    python -m venv venv
    
    # Windows
    .\venv\Scripts\activate
    
    # macOS / Linux
    source venv/bin/activate
    ```

3.  **安装依赖**
    ```bash
    pip install -r requirements.txt
    ```
    
4.  **配置 GitHub Token (关键!)**
    打开 `webapp.py` 文件，找到顶部的配置区域，将 `GITHUB_TOKEN` 变量替换为你自己的 GitHub Personal Access Token。

    ```python
    # webapp.py
    GITHUB_TOKEN = 'ghp_YOUR_REAL_GITHUB_TOKEN_HERE' # 替换你的KEY
    SCHEDULE_HOURS = 4 # 自动抓取的间隔时间 (小时)
    ```

5.  **启动应用 (V6.0 自动化版)**
    运行主应用：

    ```bash
    python webapp.py
    ```

    应用启动后，它将**立即**在后台执行第一次抓取（你会在终端看到日志），这可能需要几分钟。抓取完成后，在浏览器中访问 `http://127.0.0.1:5000` 即可看到结果。

    **应用会从此 7x24 自动在后台更新，你无需任何其他操作。**

### 🧠 CodeZen 的“大脑”：收录与展示逻辑

#### 1. "要不要收录？" (抓取逻辑 - `scraper.py`)

一个项目必须通过 3 道“门”才会被收录：

1.  **热度门 (API)：** 7 天内创建 且 > 50 星。
2.  **重复门 (DB)：** `repo_id` 未在数据库中。
3.  **中文门 (智能)：** **(满足一项即可)**
    * **a.** 项目的 `description` (简介) 本身包含中文。
    * **b.** (如果简介不含中文) `README_CN.md` 或 `README.md` 中包含中文。

#### 2. "介绍里怎么写？" (展示逻辑 - `2_webapp.py`)

为了在卡片上提供最有价值的介绍，后端遵循“最佳内容优先”原则：

1.  **第 1 优先级：** 显示中文的 `description` (简介)。
2.  **第 2 优先级：** (如果简介是英文) 显示从 README 提取的中文 `readme_excerpt` (摘要)。
3.  **第 3 优先级：** (如果前两者都没有) 降级显示英文的 `description`。
4.  **第 4 优先级：** 显示 "暂无简介"。