GitHub Star Helper

智能的 GitHub 星标仓库管理和分析助手。

让你的 GitHub stars 不再沉睡。通过语义搜索、AI 对话和趋势分析，将星标仓库转化为个人技术知识库——发现隐藏的宝藏，分析技术趋势，生成学习路径，让收藏的项目真正为你所用。

核心使用场景

界面预览

首页 🏠

快速了解你的 GitHub 星标概况——总项目数、语言分布、最近收藏。

搜索页 🔍

混合搜索：结合全文检索和语义理解，精准找到你需要的项目。

聊天页 💬

AI 对话助手：自然语言查询，智能意图识别，流式响应。

网络可视化 🕸️

项目关系图谱：基于相似度的力导向图，发现项目间的关联。

趋势分析 📈

技术成长轨迹：Star 时间线、语言演变、分类趋势的可视化分析。

快速开始

Docker 部署（推荐）

最快速的方式是使用 Docker。详细部署指南请查看 DEPLOYMENT.md。

一键启动：

# 克隆项目
git clone git@github.com:Dustyposa/startship.git
cd startship

# 构建并启动所有服务
docker compose up -d

# 查看服务状态
docker compose ps

# 停止服务
docker compose down

访问地址：

前端：http://localhost:3001
后端 API：http://localhost:8889

本地开发

环境要求：

Python 3.13+
Node.js 18+（前端）
Ollama（可选，用于语义搜索）

安装步骤：

安装 Python 依赖

# 使用 uv（推荐）
uv pip install -e .

# 或使用 pip
pip install -r requirements.txt

安装前端依赖

cd frontend
npm install

配置环境变量

cp .env.example .env
# 编辑 .env 文件，设置必要的配置

（可选）安装 Ollama 用于语义搜索

# 安装 Ollama
curl -fsSL https://ollama.com/install.sh | sh

# 拉取 bge-m3 嵌入模型（推荐，准确率更高）
ollama pull bge-m3
ollama serve

启动服务

# 启动后端（在项目根目录）
uvicorn src.api.app:app --reload --host 0.0.0.0 --port 8889

# 启动前端（在 frontend 目录）
npm run dev -- --port 3001

访问应用

核心功能

🔍 智能搜索

混合搜索引擎 - 全文检索 + 语义向量搜索，精准定位目标项目
- bge-m3 嵌入模型（1024维向量，支持中英文）
- FTS5 权重 0.3 + 语义搜索权重 0.7
- 搜索准确率从 4% 提升到 96%
- 支持概念理解、同义词识别、跨语言搜索
点击翻页 - 每页 30 个仓库，支持页码跳转
多维度过滤 - 按语言、活跃度、项目类型、所有者类型快速筛选
- 🟢 活跃维护（7天内有提交）
- 🆕 新项目（6个月内创建）
- 🏢 组织 / 👤 个人
- 排除归档项目
语言分布可视化 - 仓库卡片展示 Top 3 编程语言分布
查询扩展 - AI 自动理解意图，扩展相关关键词

💬 AI 对话助手

基于你的星标仓库 - 所有对话和分析都围绕你的收藏展开
智能意图识别 - 自动区分查询、统计、推荐等不同意图
流式响应 - SSE 实时返回，流畅的对话体验
上下文记忆 - 多轮对话，理解你的连续需求

📝 笔记与标签

个人笔记 - 为每个仓库添加学习笔记和使用心得
自定义标签 - 用标签组织项目，建立个人分类体系
收藏夹管理 - 创建收藏夹，按主题或项目分组收藏

🔄 智能数据同步

增量同步 - 每日自动同步新增的星标仓库
README 抓取 - 同步时自动获取完整 README 内容
GraphQL API - 使用 GitHub GraphQL API 提高效率
全量校验 - 每周完整校验，检测仓库更新和变化
软删除保护 - 取消星标时保留笔记和标签，可随时恢复
变更检测 - 自动检测 star 数、fork 数、描述等 8 个字段的变化
后台定时任务 - 凌晨 2 点增量同步，周日凌晨 3 点全量校验
手动触发 - 支持手动增量/全量同步和 AI 重新分析

📊 趋势与洞察

Star 时间线 - 追溯收藏历史，发现技术兴趣演变
语言分布 - 了解技术栈构成，把握技能方向
关系图谱 - 项目相似度网络，发现关联宝藏

🕸️ 知识图谱

智能关系发现 - 自动发现项目间的关系网络
- 作者关系 - 同一作者/组织的项目
- 技术生态 - 相同语言或技术栈的项目
- 收藏分组 - 同一收藏夹的项目
关系权重计算 - 基于多维度的关系强度评分
相关项目推荐 - 基于图谱关系发现相关项目
图谱可视化 - 交互式网络图谱展示项目关系

🚀 一键初始化

从 GitHub 星标仓库一键导入
使用 GitHub 官方字段：活跃度、归档状态、可见性、所有者类型
可选 LLM 深度分析，自动分类标签
可选向量嵌入，启用语义搜索

技术架构

后端

框架: FastAPI - 高性能异步 Python Web 框架
数据库: SQLite + FTS5 全文搜索
向量: ChromaDB - 语义搜索存储
嵌入: Ollama bge-m3 - 本地向量化
AI: OpenAI GPT - 意图识别与对话生成

前端

框架: Vue 3 + TypeScript
状态: Pinia
样式: Tailwind CSS
图表: ECharts - 网络可视化和趋势分析

部署

容器化: Docker + Docker Compose
前端服务: nginx (生产环境)
开发服务: Vite (本地开发)

项目结构

Docker 部署文件

docker-compose.yml - Docker 编排配置
Dockerfile.backend - 后端 Docker 镜像
Dockerfile.frontend - 前端 Docker 镜像（多阶段构建 + nginx）
docker-nginx.conf - nginx 配置（含 API 代理）
DEPLOYMENT.md - 详细部署指南

目录结构

startship/
├── src/                          # 后端源代码
│   ├── api/                      # API 层
│   │   ├── app.py                # FastAPI 应用
│   │   └── routes/               # API 路由
│   │       ├── chat.py           # 聊天接口（含意图识别）
│   │       ├── search.py         # 搜索接口
│   │       ├── init.py           # 初始化接口
│   │       ├── trends.py         # 趋势分析接口
│   │       ├── network.py        # 网络可视化接口
│   │       └── graph.py          # 知识图谱接口
│   ├── config.py                 # 配置管理
│   ├── data/                     # 数据模型
│   ├── db/                       # 数据库层
│   │   ├── base.py               # 数据库抽象
│   │   └── sqlite.py             # SQLite 实现
│   ├── github/                   # GitHub API
│   │   ├── models.py             # GitHub 数据模型
│   │   └── graphql.py            # GraphQL API（已替代 REST API）
│   ├── llm/                      # LLM 抽象层
│   │   ├── base.py               # LLM 抽象接口
│   │   └── openai.py             # OpenAI 实现
│   ├── services/                 # 业务逻辑
│   │   ├── intent.py             # 意图识别
│   │   ├── search.py             # 搜索服务
│   │   ├── chat.py               # 聊天服务
│   │   ├── stats.py              # 统计服务
│   │   ├── hybrid_search.py      # 混合搜索
│   │   ├── init.py               # 初始化服务
│   │   ├── sync.py               # 同步服务
│   │   ├── scheduler.py          # 定时任务调度器
│   │   ├── network.py            # 网络分析服务
│   │   ├── graph/                # 知识图谱服务
│   │   │   └── edges.py          # 关系边发现服务
│   │   ├── trend_analysis.py     # 趋势分析服务
│   │   ├── recommendation.py     # 推荐服务
│   │   ├── context.py            # 对话上下文
│   │   └── query_expander.py     # 查询扩展
│   └── vector/                   # 向量搜索
│       ├── embeddings.py         # Ollama 嵌入
│       └── semantic.py           # 语义搜索 (ChromaDB)
├── frontend/                     # 前端 (Vue 3)
│   └── src/
│       ├── views/                # 页面组件
│       │   ├── HomeView.vue      # 首页
│       │   ├── InitView.vue      # 初始化页
│       │   ├── SearchView.vue    # 搜索页
│       │   ├── ChatView.vue      # 聊天页
│       │   ├── NetworkView.vue   # 网络可视化页
│       │   ├── TrendView.vue     # 趋势分析页
│       │   ├── RepoDetailView.vue # 仓库详情页
│       │   ├── CollectionsView.vue # 收藏页
│       │   ├── TechProfileView.vue # 技术画像页
│       │   └── SyncHistoryView.vue # 同步历史页
│       ├── components/           # 可复用组件
│       │   ├── LanguageBarChart.vue  # 语言分布指示器
│       │   ├── PieChart.vue          # 饼图组件
│       │   └── SyncStatus.vue        # 同步状态组件
│       ├── composables/          # 组合式函数
│       ├── router/               # 路由配置
│       ├── stores/               # Pinia 状态管理
│       └── types/                # TypeScript 类型
├── tests/                        # 测试套件
│   └── unit/                     # 单元测试
├── data/                         # 数据目录
│   └── github_stars.db           # SQLite 数据库
├── assets/                       # 资源文件
│   └── *.png                     # 界面截图
├── product_plan.md               # 产品计划（详细架构设计）
├── pyproject.toml                # Python 项目配置
└── README.md                     # 项目说明

开发指南

本地开发

启动后端开发服务器

uvicorn src.api.app:app --reload --host 0.0.0.0 --port 8889

启动前端开发服务器

cd frontend
npm run dev -- --port 3001

运行测试

# 运行所有测试（单元 + 集成）
pytest

# 只运行单元测试
pytest tests/unit/

# 只运行集成测试
pytest tests/integration/

# 运行特定测试文件
pytest tests/unit/test_sync_service.py -v

# 查看覆盖率
pytest --cov=src tests/

代码格式化

# Python
black src/
ruff check src/ --fix

# TypeScript
cd frontend
npm run lint
npm run format

扩展功能

添加新的意图类型
- 在 src/services/intent.py 中添加新的 IntentResult 类型
- 在 src/api/routes/chat.py 的 chat_stream 中添加处理逻辑
调整混合搜索权重
- 修改 src/services/hybrid_search.py 中的 fts_weight 和 semantic_weight
自定义嵌入模型
- 修改 src/vector/embeddings.py 使用不同的 Ollama 模型或其他嵌入服务

配置说明

环境变量

创建 .env 文件并配置以下变量：

# GitHub
GITHUB_TOKEN=ghp_xxx  # GitHub 个人访问令牌（提高 API 限制，同步功能必需）

# OpenAI
OPENAI_API_KEY=sk-xxx  # OpenAI API 密钥（用于 LLM）
OPENAI_BASE_URL=https://api.openai.com/v1  # 可选：自定义 API 端点

# Ollama（用于语义搜索，可选）
OLLAMA_BASE_URL=http://localhost:11434  # Ollama 服务地址
OLLAMA_EMBEDDING_MODEL=bge-m3          # 嵌入模型名称（默认：bge-m3）
OLLAMA_TIMEOUT=30                      # 请求超时（秒）

# 数据库
DB_TYPE=sqlite  # 数据库类型
SQLITE_PATH=data/github_stars.db  # SQLite 数据库路径

# 向量存储（用于语义搜索，可选）
CHROMADB_PATH=data/chromadb  # ChromaDB 持久化路径

生产部署

详细的 Docker 部署指南、环境变量配置、故障排查等内容，请查看 DEPLOYMENT.md。

快速命令：

# Docker 部署（推荐）
docker compose up -d --build

# 查看 Docker 日志
docker compose logs -f backend
docker compose logs -f frontend

# 停止服务
docker compose down

API 接口

REST API

初始化

GET /api/init/status - 获取初始化状态
POST /api/init/start - 开始初始化（从 GitHub stars）

聊天

POST /api/chat - 发送聊天消息（非流式）
POST /api/chat/stream - 流式聊天（带意图识别）
- SSE 事件类型: intent, content, search_results, done
GET /api/chat/{session_id} - 获取对话历史
DELETE /api/chat/{session_id} - 删除对话

搜索

GET /api/search - 搜索仓库（支持多维度过滤）
- 参数: q, languages, is_active, is_new, owner_type, exclude_archived
GET /api/repo/{name_with_owner} - 获取单个仓库详情

用户数据

GET /api/user/notes - 获取所有笔记
POST /api/user/notes - 创建/更新笔记
DELETE /api/user/notes/{name_with_owner} - 删除笔记
GET /api/user/tags - 获取所有标签
POST /api/user/tags - 创建/更新标签
DELETE /api/user/tags/{id} - 删除标签
GET /api/user/collections - 获取收藏夹列表
POST /api/user/collections - 创建收藏夹
PUT /api/user/collections/{id} - 更新收藏夹
DELETE /api/user/collections/{id} - 删除收藏夹

同步

GET /api/sync/status - 获取同步状态（最后同步时间、仓库数量、待更新数）
POST /api/sync/manual - 手动触发同步
- 参数: full_sync (bool) - 是否全量同步
- 参数: reanalyze (bool) - 是否重新分析所有仓库
GET /api/sync/history - 获取同步历史记录
- 参数: limit - 返回记录数
POST /api/sync/repo/{name}/reanalyze - 重新分析单个仓库（AI）

知识图谱

POST /api/graph/rebuild - 重建知识图谱（发现所有关系）
GET /api/graph/nodes/{repo}/edges - 获取指定仓库的关系边
- 参数: edge_types - 过滤边类型（author,ecosystem,collection）
- 参数: limit - 返回边数量限制
GET /api/graph/nodes/{repo}/related - 获取相关仓库推荐
- 参数: limit - 返回相关仓库数量限制
GET /api/graph/status - 获取图谱计算状态

系统

GET / - 根路径
GET /health - 健康检查
GET /stats - 获取服务统计

交互式文档

访问 http://localhost:8889/docs 查看 Swagger UI 文档

故障排除

常见问题

Ollama 连接失败
- 确保 Ollama 服务正在运行: ollama serve
- 验证嵌入模型已安装: ollama list
- 检查 OLLAMA_BASE_URL 配置是否正确
ChromaDB 初始化错误
- 确保有写入权限到 data/chromadb 目录
- 如果出现持久化错误，尝试删除 data/chromadb 重新初始化
GitHub API 限制
- 配置 GITHUB_TOKEN 提高请求限制
- 使用 max_repos 参数限制初始化数量
语义搜索不工作
- 确保初始化时启用了 enable_semantic
- 检查 Ollama 服务可访问性
- 查看后端日志获取详细错误信息
前端无法连接后端
- 检查后端是否运行在 http://localhost:8889
- 验证 CORS 配置
- 查看浏览器控制台错误信息

产品计划

项目愿景

构建面向个人开发者的 GitHub 星标仓库智能管理工具，让收藏的项目真正成为个人技术知识库。

技术路线图

✅ 第一阶段：核心功能（已完成）

基础架构: FastAPI + Vue 3 + SQLite 全栈应用
数据导入: 从 GitHub API 一键导入星标仓库
智能搜索: 全文检索 + 语义向量搜索 🤖
AI 对话: 基于意图识别的智能问答 🤖
RAG 增强: 检索增强生成，基于仓库内容回答 🤖
数据可视化: 网络图谱、趋势分析

✅ 第二阶段：知识管理（已完成）

点击翻页: 每页 30 个仓库，支持页码跳转
多维度筛选: 使用 GitHub 官方字段（活跃度、归档、所有者类型）
笔记功能: 为仓库添加个人笔记
标签系统: 自定义标签组织项目
收藏夹管理: 创建收藏夹分组收藏
语言分布可视化: Top 3 语言分布指示器
README 抓取: 同步时自动获取完整 README 内容
GraphQL API: 使用 GitHub GraphQL API 提高效率
Docker 部署: 一键部署方案 ✅

📋 第三阶段：智能增强（规划中）

缓存优化: Redis 缓存提升性能
深度分析: README 解析和代码分析 🤖
协作功能: 多用户支持和团队协作
可观测性: 日志、监控、告警系统

🤖 标记表示该功能依赖 LLM 服务

贡献指南

Fork 项目
创建功能分支
提交更改
推送到分支
创建 Pull Request

许可证

MIT License

联系方式

如有问题或建议，请创建 Issue 或联系项目维护者。

Name		Name	Last commit message	Last commit date
Latest commit History 133 Commits
assets		assets
docs		docs
frontend		frontend
src		src
static		static
tests		tests
.env.example		.env.example
.gitignore		.gitignore
CHANGELOG.md		CHANGELOG.md
CLAUDE.md		CLAUDE.md
DEPLOYMENT.md		DEPLOYMENT.md
Dockerfile.backend		Dockerfile.backend
Dockerfile.frontend		Dockerfile.frontend
LICENSE		LICENSE
README.md		README.md
docker-compose.yml		docker-compose.yml
docker-nginx.conf		docker-nginx.conf
findings.md		findings.md
integration_test_plan.md		integration_test_plan.md
package-lock.json		package-lock.json
progress.md		progress.md
pyproject.toml		pyproject.toml
requirements.docker.txt		requirements.docker.txt
requirements.txt		requirements.txt
task_plan.md		task_plan.md
unit_test_plan.md		unit_test_plan.md
uv.lock		uv.lock

License

Dustyposa/startship

Folders and files

Latest commit

History

Repository files navigation

GitHub Star Helper

最近更新

核心使用场景

界面预览

首页 🏠

搜索页 🔍

聊天页 💬

网络可视化 🕸️

趋势分析 📈

快速开始

Docker 部署（推荐）

本地开发

核心功能

🔍 智能搜索

💬 AI 对话助手

📝 笔记与标签

🔄 智能数据同步

📊 趋势与洞察

🕸️ 知识图谱

🚀 一键初始化

技术架构

后端

前端

部署

项目结构

Docker 部署文件

目录结构

开发指南

本地开发

扩展功能

配置说明

环境变量

生产部署

API 接口

REST API

初始化

聊天

搜索

用户数据

同步

知识图谱

系统

交互式文档

故障排除

常见问题

产品计划

项目愿景

技术路线图

✅ 第一阶段：核心功能（已完成）

✅ 第二阶段：知识管理（已完成）

📋 第三阶段：智能增强（规划中）

贡献指南

许可证

联系方式

About

Resources

License

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

Packages