码巢 CodeNest · 开源练手库

找一个真正适合你练手的开源项目 —— 按难度、语言、方向筛选，并带 AI 导读、掌握路径、案例跟读、概念知识图谱与源码 RAG 检索。

---

项目目的

GitHub Trending 只看 star，awesome 列表不更新、也不告诉你「谁适合学、怎么学」。码巢 想解决三件事：

1. 发现：从 GitHub 公开仓库中按 star 区间、语言、技术方向持续抓取，并做难度分级（新手友好 / 进阶 / 硬核）。
2. 理解：为精选项目预生成中文项目导读、掌握路径（L1–L5）、案例跟读与概念知识图谱，降低读大型开源项目的门槛。
3. 深入：在学习页内完成源码浏览、Hybrid RAG 代码检索、图谱节点 Agent 展开与问答，把「看项目」变成可闭环的学习体验。

点击项目卡片可查看简介、标签、star/fork 与学习建议：

---

系统架构

┌─────────────────────────────────────────────────────────────────┐
│  前端 public/                                                    │
│  首页 · 详情抽屉 · 学习页 learn.html（源码/路径/图谱/Agent）      │
└────────────────────────────┬────────────────────────────────────┘
                             │ REST / SSE
┌────────────────────────────▼────────────────────────────────────┐
│  HTTP  routes/api.js                                             │
└────────────────────────────┬────────────────────────────────────┘
                             │
┌────────────────────────────▼────────────────────────────────────┐
│  业务 services/                                                  │
│  sync · classifier · learning · conceptGraph · rag · codeIndex   │
│  graphChat · jobQueue · mirror/zoekt（可选）                      │
└──────┬──────────────────┬──────────────────┬────────────────────┘
       │                  │                  │
┌──────▼──────┐   ┌───────▼───────┐   ┌──────▼──────┐
│ db/ SQLite  │   │ indexing/     │   │ retrieval/  │
│ repos       │   │ chunk·embed   │   │ hybrid·FTS  │
│ learning    │   │ indexer       │   │ vector·zoekt│
│ code_index  │   └───────────────┘   └─────────────┘
└─────────────┘
       │
┌──────▼──────────────────────────────────────────────────────────┐
│  外部：GitHub API · DeepSeek/OpenAI 兼容 LLM · Zoekt（可选）      │
└─────────────────────────────────────────────────────────────────┘

分层原则：routes → services → db，配置集中在 src/config/；异步任务由 jobQueue 串行/重试（索引、代码块索引、学习内容、图谱预热）。

数据流（学习闭环）：

1. sync 抓取仓库元数据 → SQLite repos
2. buildIndex 拉 file_tree + README → project_learning
3. buildCodeIndex 切块 + embedding → code_chunks（Hybrid RAG）
4. generateLearningV2 生成导读 / 掌握路径 / 案例 / 概念图谱 → 缓存
5. 用户打开 /learn/:owner/:name 读库；图谱钻取、Agent 问答走 SSE + RAG

---

功能模块

模块	路径	说明
配置中心	src/config/	唯一读取 .env；分类、难度、精选列表
数据层	src/db/	SQLite：项目、学习、AI 缓存、代码索引、Mirror 状态
抓取同步	services/syncService.js	定时/手动从 GitHub Search API 入库
难度分级	services/classifier.js	star + topic 信号 → 新手/进阶/硬核
学习生成	services/learningService.js	索引、导读、路径、案例、图谱骨架
概念图谱	services/conceptGraphService.js	图谱生成、节点展开、自然语言摘要
Agent 问答	services/graphChatService.js	基于当前图谱范围 + RAG 的流式对话
代码索引	indexing/ + codeIndexService	切块、embedding、重试与 0-chunk 校验
RAG 检索	retrieval/ + ragService.js	FTS + 向量 Hybrid；索引空时采样 fallback
任务队列	services/jobQueue.js	code_index / learning / mirror / zoekt 等后台 job
前端学习页	public/learn.html + learn.js	文件树、代码、图谱 G6、Agent 画布
可选 Zoekt	docker-compose.yml	企业级 BM25 全文（需 Docker）

学习页能力一览

项目导读 — AI 生成的架构说明与推荐入口：

掌握路径 L1–L5 — 从认知 → 环境 → 案例 → 改造 → 独立练习：

源码浏览 — 文件树 + 语法高亮 + 类级 AI 注解：

概念知识图谱 + Agent 画布 — 节点钻取、源码 RAG、范围问答、持续聊天记录：

图谱首次生成时会基于 RAG 构建概念骨架（后台 job，界面有加载态）：

---

快速开始（本地部署）

环境要求

• Node.js 18+（推荐 18 或 20 LTS）
• npm 9+
• （可选）Docker — 启用 Zoekt 全文检索时
• （可选）Git — 启用本地 mirror 克隆时

1. 安装与配置

git clone https://github.com/linyf-B/codenest.git
cd codenest
npm install
cp .env.example .env    # Windows: copy .env.example .env

编辑 .env（切勿提交真实 Key）：

# 建议配置，避免 GitHub API 限流
GITHUB_TOKEN=你的_github_token

# 启用 AI 导读 / 路径 / 图谱（需自行申请 DeepSeek 或 OpenAI 兼容 Key）
AI_ENABLED=true
AI_API_KEY=你的_api_key
AI_BASE_URL=https://api.deepseek.com/v1
AI_MODEL=deepseek-chat

仓库内 .env.example 中 AI Key 默认为空；本地 .env 已在 .gitignore 中忽略。

2. 初始化数据

npm run sync              # 从 GitHub 抓取首批项目（约需数分钟）
npm start                 # http://localhost:4000

3. 为单个项目生成学习内容（可选）

npm run build:learning -- alibaba/spring-ai-alibaba
npm run build:index -- alibaba/spring-ai-alibaba      # 仅代码语义索引
npm run build:codesearch -- owner/repo                # mirror + zoekt + index 全链路

学习页地址：http://localhost:4000/learn/:owner/:name

4. Docker 可选组件（Zoekt）

# .env 中设置 ZOEKT_ENABLED=true、REPO_MIRROR_ENABLED=true
docker compose up -d zoekt

---

扩展方式

1. 增加精选 / 练手项目

• 在 src/config/index.js 的 CURATED_REPOS 追加 full_name 与 category
• 或入库后调用管理接口（需 ADMIN_KEY）：

curl -X POST "http://localhost:4000/api/admin/feature" \
  -H "Content-Type: application/json" \
  -H "x-admin-key: YOUR_ADMIN_KEY" \
  -d '{"fullName":"owner/repo","featured":true}'

2. 调整难度与分类规则

修改 src/services/classifier.js 中的 star 阈值与 topic 加权逻辑。

3. 自定义 AI Prompt / 图谱版本

• Prompt 模板：learningService.js、conceptGraphService.js
• 递增 AI_PROMPT_VERSION 可使 ai_cache 自动失效并重新生成

4. 扩展 RAG / 检索后端

• 轻量模式（默认）：SQLite FTS + 本地 hash 向量 Hybrid
• 增强模式：配置 EMBEDDING_API_KEY + OpenAI 兼容 embedding
• 企业模式：CODE_SEARCH_BACKEND=hybrid + Zoekt + Git Mirror

5. 新增 API

在 src/routes/api.js 注册路由，业务逻辑放入 services/，遵循现有分层。

6. 前端扩展

• 首页：public/index.html + app.js
• 学习页：public/learn.html + learn.js（图谱 G6、Agent SSE）

---

主要 API

方法	路径	说明
GET	/api/meta	站点信息、分类、难度、语言统计
GET	/api/repos	项目列表（分页、筛选、排序）
GET	/api/projects/:owner/:name/index	文件树 + README + 学习状态
GET	/api/projects/:owner/:name/learning	导读、路径、案例、概念图谱
GET	/api/projects/:owner/:name/file?path=	单文件内容（路径自动校正）
POST	/api/projects/:owner/:name/graph/expand/stream	图谱节点展开（SSE）
POST	/api/projects/:owner/:name/graph/chat/stream	Agent 范围问答（SSE）
POST	/api/admin/sync	手动同步（需 ADMIN_KEY）

---

目录结构

codenest/
├── public/                 # 静态前端
├── src/
│   ├── config/             # 配置
│   ├── db/                 # SQLite 访问层
│   ├── services/           # 业务逻辑
│   ├── indexing/           # 代码切块与 embedding
│   ├── retrieval/          # Hybrid 检索
│   ├── routes/api.js       # REST 路由
│   ├── cli/                # 命令行工具
│   ├── app.js
│   └── server.js
├── docs/screenshots/       # README 截图
├── docker-compose.yml      # Zoekt 可选服务
├── .env.example
└── package.json

---

技术栈

• 运行时：Node.js 18+ / Express
• 存储：better-sqlite3（零外部 DB 依赖）
• 调度：node-cron + 内存 job 队列
• 前端：原生 HTML/CSS/JS；highlight.js、AntV G6、marked
• AI：OpenAI 兼容 API（DeepSeek 等）；响应缓存
• 检索：SQLite FTS5 + 向量 / 可选 Zoekt BM25

---

合规说明

数据来自 GitHub 公开 REST API，仅存储仓库公开元数据；展示与跳转均链接回原仓库。使用 AI 功能时请遵守对应模型服务商条款。

---

作者

linyf-B @ GitHub

---

License

MIT