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. 克隆仓库

   git clone https://git.wlens.top/laowang/CodeZen.git
   cd CodeZen
   

2. 创建并激活虚拟环境

   python -m venv venv
   
   # Windows
   .\venv\Scripts\activate
   
   # macOS / Linux
   source venv/bin/activate
   

3. 安装依赖

   pip install -r requirements.txt
   

4. 配置 GitHub Token (关键!) 打开 webapp.py 文件，找到顶部的配置区域，将 GITHUB_TOKEN 变量替换为你自己的 GitHub Personal Access Token。

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

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

   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 优先级： 显示 "暂无简介"。