113 lines
4.4 KiB
Markdown
113 lines
4.4 KiB
Markdown
|
||
# 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 优先级：** 显示 "暂无简介"。
|
||
|