Skip to content

Commit 04b478e

Browse files
iblogciblogc
committed
✨ feat(web): 增强静态站筛选排序功能与重写项目文档
- 【新功能】 - 静态页面新增高级筛选功能，支持按语言和AI标签筛选。 - 静态页面新增排序功能，支持按最新更新、Star数量和字母顺序排序。 - 引入数据统计仪表盘，展示总项目数、平均Star数和热门技术栈。 - 优化了Star数量的显示，增加了SVG图标。 - 增加了骨架屏加载效果，提升用户体验。 - 【文档】 - 全面重写 `README.md`，提供更详细的项目介绍、功能特性、快速开始指南。 - 详细说明了环境变量配置、Obsidian同步、GitHub Pages部署和本地运行方法。 - 新增配置项详解表格，清晰列出所有变量及其说明。 - 增加了文件说明部分，帮助用户理解项目结构。 - 【重构】 - 重构了前端JavaScript逻辑，统一处理搜索、筛选和排序，提升代码可维护性。 - 优化了多语言文本更新机制，确保UI元素能正确切换语言。 - 调整了页面布局和CSS变量，为新功能提供支持。 - 改进了模态框（Modal）的显示内容和标签。
1 parent 4d1d881 commit 04b478e

File tree

2 files changed

+582
-70
lines changed

2 files changed

+582
-70
lines changed

‎README.md‎

Lines changed: 146 additions & 14 deletions
Original file line numberDiff line numberDiff line change
@@ -1,20 +1,152 @@
1-
对我来说，GitHub 的 Star 列表基本就是个“黑洞”：收藏时一时爽，想用时根本找不到。GitHub 自带的搜索体验确实一言难尽，最近干脆写了个自动化脚本，每天获取 Star 仓库信息进行整理同步。
1+
# GitHub Stars Index
22

3-
项目名称：[GithubStarsIndex](https://github.com/iblogc/GithubStarsIndex )
3+
> 自动抓取 GitHub Stars，生成 AI 摘要，便于检索。
44
5-
主要功能：
6-
- 🤖 AI 自动摘要：调用 LLM (GPT-4o-mini 等) 深度阅读 README，自动提炼中英文摘要和关键词标签。
7-
- ⏭️ 增量同步：每天定时触发，自动对比 stars.json 数据状态。只对新增项目消耗 Token，省钱又高效。
8-
- 📝 Obsidian 适配：这是我的核心需求。工具会自动推送 `_zh.md` 和 `_en.md` 到指定的 GitHub 仓库。配合 Obsidian Git 插件，笔记库可以定时自动拉取，实现 Stars 摘要在笔记软件里的无缝集成。
9-
- 🌐 交互式静态站：自动生成一套带前端搜索功能的个性化 HTML 页面，部署在 GitHub Pages 上，支持极速搜索，手机端翻阅非常方便。
5+
## 目录
106

11-
工作流程：
12-
![](https://i.imgur.com/agpXbOU.png)
7+
- [功能特性](#功能特性)
8+
- [快速开始](#快速开始)
9+
- [配置项详解](#配置项详解-环境变量--env)
10+
- [Obsidian 同步（可选）](#obsidian-同步可选)
11+
- [本地运行](#本地运行)
1312

14-
项目地址：https://github.com/iblogc/GithubStarsIndex
15-
在线 Demo：https://iblogc.github.io/GithubStarsIndex
13+
---
1614

17-
生成的 MD 效果预览：
18-
![](https://i.imgur.com/qqnUh7h.png)
15+
## 功能特性
1916

20-
初衷是解决自己的收藏癖焦虑，如果正好也能帮到你，欢迎点个 Star 或者提 PR 交流。
17+
- 🤖 自动抓取 GitHub 账号 Star 的全部仓库
18+
- 📝 为每个仓库读取 README，调用 AI 生成内容摘要和技术标签
19+
- ⚡️ **高效率**：支持**并发调用** AI 接口，大幅提升处理大量新项目时的速度
20+
- 🗃️ **数据驱动**：所有信息存储为 `data/stars.json`，支持二次开发
21+
- 🎨 **模版驱动**：使用 Jinja2 模版生成 Markdown 和 HTML 静态页面
22+
- ⏭️ 增量更新，已处理项目状态保存在 JSON 中，避免重复消耗 API
23+
- ⏰ GitHub Actions **定时自动运行**，cron 表达式自由配置
24+
- 🔄 可选：自动将生成的 `stars_zh.md` & `stars_en.md` **推送到 Obsidian Vault 仓库**
25+
- 🌐 可选：自动同步到 **GitHub Pages** 分支，支持多语言 (ZH/EN) 切换与前端交互搜索
26+
- 💻 支持任意 **OpenAI 格式兼容接口**（OpenAI / Azure / 本地 Ollama 等）
27+
28+
---
29+
30+
## 快速开始
31+
32+
### 第一步：Fork 本仓库
33+
34+
点击右上角 **Fork**，将本仓库复制到你自己的账号下。
35+
36+
### 第二步：配置环境 (二选一)
37+
38+
本项目通过环境变量驱动，**配置优先级：GitHub Secrets > .env 文件**。
39+
40+
#### 方案 A：使用 GitHub 环境变量 (推荐，适合持续运行)
41+
42+
进入仓库的 **Settings → Secrets and variables → Actions** 进行配置：
43+
44+
**🔐 必填项 (Required Secrets/Variables)**
45+
- `GH_USERNAME`: 要抓取 Stars 的 GitHub 用户名。
46+
- `AI_API_KEY`: 你的 AI 接口 API Key。
47+
48+
**📋 可选项 (Optional Variables)**
49+
以下参数有内置默认值，通常无需配置：
50+
- `AI_BASE_URL`: AI 接口地址 (默认使用 OpenAI 官方地址)。
51+
- `AI_MODEL`: 模型名称 (默认 `gpt-4o-mini`)。
52+
- `OUTPUT_FILENAME`: 生成文件的基准名 (默认 `stars`)。
53+
- `VAULT_SYNC_PATH`: Vault 里的存放目录 (默认 `GitHub-Stars/`)。
54+
- `PAGES_SYNC_ENABLED`: 是否同步到 Pages (默认 `true`)。
55+
56+
> [!TIP]
57+
> **关于 GitHub API 限制**：
58+
> - **线上运行 (Actions)**：工作流会自动注入 `GITHUB_TOKEN`，额度高达 1,000次/小时，抓取全量 Stars 无压力。
59+
> - **本地运行**：若不配置 `GH_TOKEN`，API 限制为 60次/小时。若 Stars 较多，建议在 `.env` 中填入 `GH_TOKEN` 以提升额度至 5,000次/小时。
60+
61+
#### 方案 B：使用 .env 文件 (适合本地开发)
62+
63+
1. 在仓库根目录，复制 `.env.example` 并重命名为 `.env`。
64+
2. 在 `.env` 中填入必填项。
65+
66+
---
67+
68+
### 第三步：自定义定时频率
69+
70+
编辑 `.github/workflows/sync.yml`，修改 `cron` 表达式：
71+
72+
```yaml
73+
schedule:
74+
- cron: "0 2 * * 1" # 示例：每周一凌晨 2 点运行
75+
```
76+
77+
### 第四步：手动触发首次运行
78+
79+
进入 **Actions → 🌟 GitHub Stars Index同步 → Run workflow**，点击运行。
80+
81+
---
82+
83+
## 配置项详解
84+
85+
| 变量名 | 类型 | 说明 | 默认值 |
86+
| -------------------- | ---- | -------------------------- | --------------------------- |
87+
| `GH_USERNAME` | 必填 | 要同步的 GitHub 用户名 | - |
88+
| `AI_API_KEY` | 必填 | AI 接口 Key | - |
89+
| `AI_BASE_URL` | 可选 | OpenAI 兼容接口地址 | `https://api.openai.com/v1` |
90+
| `AI_MODEL` | 可选 | 使用的 AI 模型 | `gpt-4o-mini` |
91+
| `OUTPUT_FILENAME` | 可选 | 生成 MD/HTML 的文件名基准 | `stars` |
92+
| `VAULT_SYNC_ENABLED` | 可选 | 是否开启 Obsidian 同步 | `false` |
93+
| `VAULT_REPO` | 选填 | Vault 仓库 (`owner/repo`) | - |
94+
| `VAULT_SYNC_PATH` | 可选 | Vault 同步的目录路径 | `GitHub-Stars/` |
95+
| `PAGES_SYNC_ENABLED` | 可选 | 是否开启 GitHub Pages 部署 | `true` |
96+
| `MAX_CONCURRENCY` | 可选 | AI 并发处理数 (建议 1-10) | `1` |
97+
| `GH_TOKEN` | 选填 | 本地运行时提升 API 额度 | - |
98+
99+
---
100+
101+
## Obsidian 同步（可选）
102+
103+
1. **设置 Token**: 创建一个具有 **Contents: Write** 权限的 [Fine-grained PAT](https://github.com/settings/personal-access-tokens) 存入 Secret `VAULT_PAT`。
104+
2. **配置仓库**: 设置 `VAULT_SYNC_ENABLED=true` 和 `VAULT_REPO=用户名/仓库名`。
105+
3. **设置路径**: 设置 `VAULT_SYNC_PATH`，文件将自动同步到该目录下（自动补全 `_zh.md` / `_en.md`）。
106+
107+
---
108+
109+
## GitHub Pages 部署（可选）
110+
111+
本项目自动生成支持多语言、支持实时搜索的静态网页：
112+
113+
1. 确保 `PAGES_SYNC_ENABLED=true`。
114+
2. 运行一次 Action 后，进入 **Settings -> Pages**。
115+
3. **Branch** 选择 `gh-pages`，目录选择 `/(root)`，保存。
116+
117+
---
118+
119+
## 本地运行
120+
121+
```bash
122+
# 克隆仓库并安装依赖
123+
git clone https://github.com/iblogc/GithubStarsIndex.git
124+
cd GithubStarsIndex
125+
126+
# 安装依赖
127+
pip install -r requirements.txt
128+
129+
# 使用 .env 进行配置
130+
cp .env.example .env
131+
# 编辑 .env 填入 AI_API_KEY 和 GH_USERNAME
132+
133+
# [常规运行] 获取原信息、调用 AI 总结并渲染页面
134+
python scripts/sync_stars.py
135+
136+
# [仅渲染模式] 跳过抓取和 AI 总结，仅依据本地 stars.json 极速重新渲染 HTML/MD
137+
# 适用于前端样式调试、模版修改、多语言翻译调整等场景
138+
python scripts/sync_stars.py --render-only
139+
```
140+
141+
---
142+
143+
## 文件说明
144+
145+
| 文件 | 说明 |
146+
| :--------------------------- | :----------------------------------- |
147+
| `data/stars.json` | **核心数据集**（抓取的全量项目数据） |
148+
| `templates/` | Jinja2 生成模版（Markdown/HTML） |
149+
| `dist/` | 自动生成的本地成品（HTML / MD） |
150+
| `scripts/sync_stars.py` | 核心同步与生成脚本 |
151+
| `.github/workflows/sync.yml` | GitHub Actions 定时工作流 |
152+
| `.env.example` | 配置示例文件 |

0 commit comments

Comments
 (0)