# gitstar

**Repository Path**: atlantisholic/gitstar

## Basic Information

- **Project Name**: gitstar
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 1
- **Forks**: 0
- **Created**: 2026-06-08
- **Last Updated**: 2026-06-14

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# GitStar - GitHub 星标管理系统

## 项目目标

GitStar 是一款基于 Tauri 2.x 构建的跨平台桌面应用，旨在帮助开发者高效管理自己的 GitHub 星标项目。通过本地优先的架构设计，提供流畅的星标浏览、分类整理、标签管理、README 阅读与项目评估体验，并通过发现页探索社区优质开源项目。

## 快速开始

```bash
# 安装依赖
npm install

# 开发模式
npm run tauri dev

# 构建发布版
npm run tauri build
```

### 首次使用

1. 在 GitHub [Developer Settings](https://github.com/settings/developers) 创建 OAuth App
2. 打开应用 → 设置 → 填入 Client ID
3. 使用 Device Flow 登录
4. 点击「同步」拉取星标数据

### 网络代理

GitStar 的所有 GitHub 请求（登录、同步、Trending 等）均通过 Rust 后端发起。默认 **自动代理** 模式会检测并使用本地代理：

1. 环境变量：`HTTPS_PROXY`、`HTTP_PROXY`、`ALL_PROXY` 等
2. Windows 系统代理（Clash / V2Ray 等开启「系统代理」时写入注册表）

可在 **设置 → 网络代理** 中切换为手动指定地址或关闭代理。

| 模式 | 说明 |
|------|------|
| 自动 | 检测到本地代理则使用，否则直连 |
| 手动 | 使用填写的代理地址，如 `http://127.0.0.1:7890` |
| 关闭 | 始终直连，忽略本地代理 |

### 本地调试同步

在不启动 UI 的情况下，用本地数据库中的 token 和代理设置自检同步链路：

```bash
npm run debug:sync
```

该命令会依次验证：登录状态 → GitHub API 原始响应 → 拉取星标 → 写入 SQLite。单元测试覆盖三种星标 JSON 格式：

```bash
cd src-tauri && cargo test parse_
```

## 使用场景

- 单用户使用，主要管理自己的 GitHub 星标项目
- 支持分类、标签、搜索、评估与智能整理
- 通过发现页浏览趋势、新星、优质项目与学习清单

## 技术选型

| 层级 | 技术选型 |
|------|---------|
| 桌面框架 | Tauri 2.x |
| 前端框架 | Vue 3 (Composition API) + TypeScript |
| UI 组件库 | Element Plus |
| 状态管理 | Pinia |
| 路由 | Vue Router |
| 本地数据库 | SQLite（Rust rusqlite） |
| HTTP 请求 | reqwest（Rust 后端调用 GitHub API） |
| Markdown 渲染 | markdown-it + highlight.js（代码高亮） |
| 图表库 | ECharts（数据可视化） |
| 构建工具 | Vite |

## 功能概览

### 1. GitHub 认证与数据同步

- GitHub OAuth 登录（Device Flow）
- **星标全量同步** + **仓库详情同步**（双链路独立调度）
- 同步状态指示器；打开详情读本地缓存，不阻塞 UI

完整说明见 **[docs/SYNC.md](./docs/SYNC.md)**。

### 2. 星标项目管理（核心）

- **列表展示**：卡片 / 列表视图；搜索（`SearchInput` 可清除）、语言 / 分类 / 标签筛选
- **分类 / 标签 / 备注**：侧边栏 CRUD，分类与标签区块可折叠
- **智能分析**：MetaBar 预览分类与标签 → 弹窗勾选 → 追加或覆盖（自动创建缺失项）
- **仓库评估**：活跃度 + 架构师选型五维 + License 说明（见 [docs/REPO_EVAL.md](./docs/REPO_EVAL.md)）
- **README 阅读**：本地缓存 + 代码高亮；详情同步后台更新
- **取消星标 / 回收站 / 下载 ZIP**

智能分类流程见 **[docs/CLASSIFY.md](./docs/CLASSIFY.md)**。

### 3. 搜索、筛选与排序

- 仓库名 / 描述模糊搜索（星标页、发现页）
- 语言、分类、未分类、无标签、近期收藏、长期未更新等筛选
- 排序：Star、Fork、名称、更新、收藏时间、活跃度、选型指数
- Dashboard / 侧边栏跳转星标页时通过 **URL query** 带入筛选（见 [docs/DASHBOARD.md](./docs/DASHBOARD.md)）

### 4. 发现页

单次调用 **`get_discover_feed`** 聚合五个板块：

| 板块 | 数据源 |
|------|--------|
| 热度飙升 | GitHub Trending HTML |
| 新星崛起 | Search API（近 90 天新项目） |
| 优质精选 | Search API（高 Star + 活跃） |
| 猜你喜欢 | Search API × 收藏语言 Top3 |
| Awesome Lists | 内置清单，按语言排序 |

详见 **[docs/DISCOVER.md](./docs/DISCOVER.md)**。

### 5. 仪表盘（行动中心）

- **KPI**：本周新增、未分类、无标签、整理覆盖率（均可点击）
- **待处理**：待分类、长期未更新、疑似重复
- **最近收藏**、**整理健康度**、语言分布、**最近 12 个月**收藏趋势
- **行业排行榜**：语言（TIOBE Top 20）/ 数据库（DB-Engines Top 100）/ 大模型（LLM Stats Top 15）；缓存 + 定时/手动刷新
- 加载时骨架屏 + 动态提示；图表随窗口自适应

详见 **[docs/DASHBOARD.md](./docs/DASHBOARD.md)**。

### 6. 数据导出与备份

- 导出 JSON / CSV；导入 JSON；手动备份 SQLite
- 同步前自动备份（可配置）

### 7. 系统设置

- 主题（亮 / 暗）、星标/详情同步间隔、**行业排行榜刷新间隔**、代理、AI Provider、分类原则、数据清理

### 8. 回收站

- 取消星标保留快照，支持恢复或永久删除

## 文档

| 文档 | 说明 |
|------|------|
| [docs/README.md](./docs/README.md) | **文档索引** |
| [docs/SYNC.md](./docs/SYNC.md) | 双链路同步 |
| [docs/REPO_EVAL.md](./docs/REPO_EVAL.md) | 仓库评估指标 |
| [docs/DASHBOARD.md](./docs/DASHBOARD.md) | 仪表盘逻辑与深链 |
| [docs/DISCOVER.md](./docs/DISCOVER.md) | 发现页抓取规则 |
| [docs/CLASSIFY.md](./docs/CLASSIFY.md) | 智能分类 |
| [ROADMAP.md](./ROADMAP.md) | 产品路线图 |
| [CHANGELOG.md](./CHANGELOG.md) | 版本变更 |

## 产品路线图

后续规划与优先级见 **[ROADMAP.md](./ROADMAP.md)**。

## UI 设计

设计文件位于 `gitstar.pen`（Pencil 格式），暗色主题：

- 背景 `#1A1D23`，卡片 `#2A2D35`，主色 `#4C8BF5`
- 左侧筛选侧边栏 240px
- 核心页面：仪表盘 / 星标 / 发现 / 设置 / 回收站

## 项目结构

```
gitstar/
  src/                          # Vue 前端
    views/                      # Dashboard, Stars, Discover, Settings, Trash
    components/                 # RepoCard, ReadmePanel, MetaBar, SearchInput,
                                # RepoClassifyDialog, DashboardSkeleton, …
    stores/                     # repos, categories
    composables/                # useSync, useDashboardNav, useDownload, …
    router/
    styles/
    types/
  src-tauri/                    # Tauri / Rust 后端
    src/
      github/                   # API、Trending、discover 聚合
      db/                       # SQLite
      commands/                 # Tauri Commands
      classify/                 # 规则 / AI 分类
      dashboard/                # 行业排行榜抓取、缓存、调度
      sync/                     # 详情同步调度
      eval/                     # 仓库评估
  docs/                         # 模块文档（见 docs/README.md）
  gitstar.pen
  README.md
  ROADMAP.md
  CHANGELOG.md
```

## 数据库设计

| 表名 | 说明 |
|------|------|
| `repos` | 星标仓库（含评估深度字段、备注、分类） |
| `categories` | 分类 |
| `tags` | 标签 |
| `repo_tags` | 仓库-标签关联 |
| `readmes` | README 缓存 |
| `sync_meta` | 同步元数据 |
| `settings` | 应用设置（含 `rankings_refresh_interval_hours`、`dashboard_rankings_cache`） |
| `trash_repos` | 回收站快照 |

## 发现页逻辑（摘要）

发现页由 `Discover.vue` 调用 **`get_discover_feed(language?, since)`**；后端读取本地星标统计语言偏好，组合 Trending HTML 与 GitHub Search API，并排除已 Star 项目。

搜索框对所有板块做**本地过滤**（`SearchInput` 支持清除）；语言 / 时间变更会重新请求。Trending 前端最多展示 12 条，Search 类板块各 10 条。

完整抓取原则见 **[docs/DISCOVER.md](./docs/DISCOVER.md)**。