|
105 | 105 |
|
106 | 106 | --- |
107 | 107 |
|
| 108 | +## 🛠️ 技术栈 |
| 109 | + |
| 110 | +### 前端客户端 |
| 111 | + |
| 112 | +| 类别 | 技术 | |
| 113 | +|------|------| |
| 114 | +| UI 框架 | React 18 + TypeScript | |
| 115 | +| 构建工具 | Vite | |
| 116 | +| 桌面端 | Electron + electron-builder | |
| 117 | +| 样式方案 | Tailwind CSS | |
| 118 | +| 状态管理 | Zustand + TanStack Query | |
| 119 | +| 本地存储 | Dexie.js (IndexedDB) | |
| 120 | +| 富文本编辑器 | TipTap (ProseMirror) | |
| 121 | +| 路由 | React Router | |
| 122 | +| 动效 | Framer Motion + CSS 动画 | |
| 123 | +| 测试 | Vitest + Testing Library | |
| 124 | +| 代码检查 | Oxlint | |
| 125 | + |
| 126 | +### 后端服务 |
| 127 | + |
| 128 | +| 服务 | 技术 | 说明 | |
| 129 | +|------|------|------| |
| 130 | +| AI 网关 | Python + FastAPI + LangChain | AI 增强服务网关 | |
| 131 | +| 同步服务 | Go + Gin | 数据同步 API | |
| 132 | +| 数据库 | PostgreSQL | 主数据存储 | |
| 133 | +| 缓存 | Redis | 会话 / 缓存 / 限流 | |
| 134 | + |
| 135 | +### 基础设施 |
| 136 | + |
| 137 | +| 类别 | 技术 | |
| 138 | +|------|------| |
| 139 | +| 容器化 | Docker + docker-compose | |
| 140 | +| 反向代理 | Nginx | |
| 141 | +| AI 模型 | 通义千问 (Qwen) / DeepSeek / 智谱 GLM | |
| 142 | +| 自动更新 | electron-updater | |
| 143 | + |
| 144 | +--- |
| 145 | + |
108 | 146 | ## 🚀 快速开始 |
109 | 147 |
|
110 | 148 | ### 环境要求 |
@@ -237,231 +275,3 @@ npm run build # 构建验证(TypeScript) |
237 | 275 | ## 📄 许可证 |
238 | 276 |
|
239 | 277 | 本项目基于 [Apache License 2.0](./LICENSE) 开源协议发布。 |
240 | | -<p align="center"> |
241 | | - <h1 align="center">📚 课伴 KeBan</h1> |
242 | | - <p align="center"><strong>你的 AI 智能学习伙伴 — 让每一分钟网课都高效有价值</strong></p> |
243 | | - <p align="center"> |
244 | | - <img src="https://img.shields.io/badge/status-beta-green.svg" alt="Status" /> |
245 | | - <img src="https://img.shields.io/badge/version-v0.6.0-blue.svg" alt="Version" /> |
246 | | - <img src="https://img.shields.io/badge/license-Apache--2.0-blue.svg" alt="License" /> |
247 | | - </p> |
248 | | -</p> |
249 | | - |
250 | | ---- |
251 | | - |
252 | | -## 📝 关于课伴 |
253 | | - |
254 | | -**课伴(KeBan)** 是一款面向学生和自学者的高效学习桌面应用。它围绕网课学习场景,基于费曼学习法、间隔重复等科学方法论,将时间管理、笔记记录、记忆巩固和深度理解整合在一个工具中,帮助你建立科学的学习闭环。 |
255 | | - |
256 | | -**解决的核心痛点:** |
257 | | - |
258 | | -| 痛点 | 课伴方案 | |
259 | | -|------|----------| |
260 | | -| 网课时容易走神、效率低 | 番茄钟双模式强制专注 + 后台不中断计时 | |
261 | | -| 网课内容记不下来 | 网课笔记提取:自动截屏 + AI 视觉识别 + ASR 语音转写 | |
262 | | -| 笔记零散、复习时找不到重点 | 结构化模板 + 标签系统 + 全文搜索 | |
263 | | -| 学完就忘、缺少科学复习节奏 | 间隔重复算法自动安排复习时间 | |
264 | | -| 以为懂了但说不清楚 | 费曼学习法四步引导 + AI 评估反馈 | |
265 | | - |
266 | | -> 💡 **核心理念:本地优先 + AI 增强可选** |
267 | | -> |
268 | | -> 所有核心功能 **离线完整可用**,无需任何网络依赖;联网时可按需开启 AI 辅助,作为增值能力叠加。你的学习数据,始终掌握在自己手中。 |
269 | | -
|
270 | | ---- |
271 | | - |
272 | | -## ✨ 核心功能 |
273 | | - |
274 | | -课伴围绕 **"学 → 记 → 练 → 悟"** 学习闭环,提供五大模块: |
275 | | - |
276 | | -### 🍅 番茄钟 — 时间管理 |
277 | | - |
278 | | -- **三段式计时**:工作 / 短休息 / 长休息自动轮转 |
279 | | -- **双模式切换**:上课模式(45 分钟)与自习模式(25/5 标准节奏) |
280 | | -- **后台不中断**:切换页面计时继续运行 |
281 | | -- **数据洞察**:专注时长统计与趋势分析,量化学习投入 |
282 | | -- **目标设定**:为每次专注设定学习目标,追踪完成情况 |
283 | | - |
284 | | -### 📝 智能笔记 — 知识沉淀 |
285 | | - |
286 | | -- 专业富文本编辑体验,支持多种排版与格式化 |
287 | | -- 多种模板:大纲式、康奈尔笔记法、自由画布等 |
288 | | -- 3 级嵌套文件夹 + 自由标签系统,灵活组织笔记 |
289 | | -- 本地全文搜索,自动保存,数据不丢失 |
290 | | -- 右键菜单 2.0:声明式注册,支持自定义上下文操作 |
291 | | - |
292 | | -### 📹 网课笔记提取 — 智能记录 |
293 | | - |
294 | | -- **屏幕捕获**:自动截取网课窗口关键帧 |
295 | | -- **语音转写**:系统音频采集 + ASR 语音识别 |
296 | | -- **AI 视觉提取**:多模态大模型识别画面中的关键知识点 |
297 | | -- **智能路由**:根据环境自动选择最优提取策略,支持降级方案 |
298 | | -- **异步流水线**:事件驱动架构,不阻塞主界面操作 |
299 | | - |
300 | | -### 🃏 闪卡 — 记忆巩固 |
301 | | - |
302 | | -- 基于间隔重复算法的科学记忆系统(Again / Hard / Good / Easy 四档评分) |
303 | | -- 3 级嵌套牌组:科目 → 章节 → 知识点 |
304 | | -- 复习统计与遗忘曲线可视化 |
305 | | -- 支持 CSV / JSON 批量导入导出 |
306 | | -- 牌组详情与学习会话完整记录 |
307 | | - |
308 | | -### 🧠 费曼学习法 — 深度理解 |
309 | | - |
310 | | -- 四步引导:选概念 → 用自己的话解释 → 识别薄弱点 → 简化重述 |
311 | | -- 自动标记与汇总薄弱知识点 |
312 | | -- 1–5 星理解度评估,直观衡量掌握程度 |
313 | | -- 学习测试与知识巩固追踪 |
314 | | - |
315 | | -### 🤖 AI 增强(联网可选) |
316 | | - |
317 | | -| 能力 | 说明 | |
318 | | -|------|------| |
319 | | -| 笔记智能摘要 | 一键生成课堂笔记摘要与续写润色 | |
320 | | -| AI 自动生成闪卡 | 从笔记内容智能生成记忆卡片 | |
321 | | -| 费曼学习评估 | AI 评估解释质量,给出改进建议 | |
322 | | -| 智能时长推荐 | 根据学习数据推荐最佳番茄钟时长 | |
323 | | -| AI 视觉提取 | 多模态模型识别网课画面中的关键信息 | |
324 | | -| 语音转写 | ASR 自动识别网课语音内容 | |
325 | | -| API Key 自配置 | 用户可在设置中自行配置 AI 服务商密钥 | |
326 | | - |
327 | | -> 基于国产大模型:**通义千问(Qwen)** / **DeepSeek** / **智谱 GLM**,按需选择,灵活切换。 |
328 | | -
|
329 | | -### 📊 仪表盘与成就系统 |
330 | | - |
331 | | -- 学习数据概览:专注时长、笔记数量、闪卡复习进度等核心指标 |
332 | | -- 成就解锁:完成学习里程碑,获得成就徽章激励 |
333 | | -- 每日打卡:学习打卡追踪,培养持续学习习惯 |
334 | | - |
335 | | ---- |
336 | | - |
337 | | -## 🚀 快速开始 |
338 | | - |
339 | | -### 环境要求 |
340 | | - |
341 | | -- **Node.js** 18+ & **npm** 9+ |
342 | | - |
343 | | -### 安装与运行 |
344 | | - |
345 | | -```bash |
346 | | -# 克隆仓库 |
347 | | -git clone https://github.com/Aparencia/KeBan.git |
348 | | -cd KeBan/client |
349 | | - |
350 | | -# 安装依赖并启动开发服务器 |
351 | | -npm install |
352 | | -npm run dev |
353 | | -``` |
354 | | - |
355 | | -开发服务器启动后,在浏览器中访问 `http://localhost:5173` 即可预览。 |
356 | | - |
357 | | -### 构建桌面安装包 |
358 | | - |
359 | | -```bash |
360 | | -cd client |
361 | | -npm run electron:build |
362 | | -``` |
363 | | - |
364 | | -构建产物位于 `client/release/` 目录,格式为 Windows NSIS(`.exe`),支持当前用户安装,无需管理员权限。 |
365 | | - |
366 | | -也可以从 [GitHub Releases](https://github.com/Aparencia/KeBan/releases) 页面直接下载最新安装包。 |
367 | | - |
368 | | ---- |
369 | | - |
370 | | -## 📁 项目结构 |
371 | | - |
372 | | -``` |
373 | | -KeBan/ |
374 | | -├── client/ # 前端客户端(React + Electron 桌面应用) |
375 | | -│ ├── src/features/ # 业务功能模块(番茄钟、笔记、闪卡、费曼、仪表盘) |
376 | | -│ ├── src/lib/ # 核心库(AI、存储、同步、加密、网络、捕获等) |
377 | | -│ ├── src/components/ # 共享 UI 组件(基础组件、布局、主题) |
378 | | -│ ├── src/hooks/ # 自定义 React Hooks |
379 | | -│ └── electron/ # Electron 主进程(含屏幕/音频捕获) |
380 | | -├── server/ # 后端服务(AI 网关 + 数据同步) |
381 | | -│ ├── ai-gateway/ # Python AI 增强网关(含视觉提取、语音转写) |
382 | | -│ └── sync-service/ # Go 数据同步服务 |
383 | | -├── docs/ # 项目文档(phase0 ~ phase6 + 版本迭代文档) |
384 | | -├── scripts/ # 脚本工具 |
385 | | -├── .env.example # 环境变量模板 |
386 | | -└── README.md |
387 | | -``` |
388 | | - |
389 | | -| 目录 | 说明 | |
390 | | -|------|------| |
391 | | -| `client/` | 前端应用与 Electron 桌面端,包含所有 UI 和业务逻辑 | |
392 | | -| `server/` | 后端微服务,包括 AI 增强网关(视觉提取、语音转写)和数据同步服务 | |
393 | | -| `docs/` | 按项目生命周期组织的开发文档(phase0 ~ phase6)及版本迭代文档 | |
394 | | -| `scripts/` | 构建、部署等辅助脚本 | |
395 | | - |
396 | | ---- |
397 | | - |
398 | | -## 🗺️ 路线图 |
399 | | - |
400 | | -| 阶段 | 状态 | 核心交付 | |
401 | | -|------|------|----------| |
402 | | -| **MVP-1 Alpha** | ✅ 已完成 | 纯本地核心版 — 四大模块 + 离线支持 + 本地存储 | |
403 | | -| **MVP-2 Alpha** | ✅ 已完成 | AI 增强 + 云同步 + Electron 桌面端 + 用户认证 | |
404 | | -| **v0.4.0 Beta** | ✅ 已完成 | 网课笔记提取 + ContextMenu 2.0 + AuthGuard + 动效系统 + 反馈面板 | |
405 | | -| **v0.5.0** | ✅ 已完成 | 安全加固 + 效率分析 + 全局命令面板 + 灵感空间 + 上云部署 | |
406 | | -| **v0.6.0** | ✅ 已完成 | 沉浸式计时 + 自动更新 + 音效系统 + 隐私政策 + 品牌视觉升级 | |
407 | | -| **正式上线** | 🎯 规划中 | 生产就绪版 | |
408 | | - |
409 | | -### 🔮 未来方向 |
410 | | - |
411 | | -- **社交协作**:学习小组、闪卡共享、专注排行榜 |
412 | | -- **跨端生态**:移动端 App、浏览器插件 |
413 | | -- **AI 深度增强**:个性化学习路径、知识图谱、智能复习规划 |
414 | | -- **开放平台**:插件系统、第三方模板市场 |
415 | | - |
416 | | ---- |
417 | | - |
418 | | -## 📦 版本管理 |
419 | | - |
420 | | -项目遵循 **SemVer**(语义化版本)规范,格式为 `v{MAJOR}.{MINOR}.{PATCH}`: |
421 | | - |
422 | | -| 组成部分 | 含义 | 示例 | |
423 | | -|----------|------|------| |
424 | | -| `MAJOR` | 不兼容的 API 变更 | `1.0.0` | |
425 | | -| `MINOR` | 向后兼容的功能新增 | `0.5.0` | |
426 | | -| `PATCH` | 向后兼容的缺陷修复 | `0.5.1` | |
427 | | - |
428 | | -发布 Tag 前请确保:`npm run lint` / `npm run test` / `npm run build` 全部通过。 |
429 | | - |
430 | | ---- |
431 | | - |
432 | | -## 👥 贡献指南 |
433 | | - |
434 | | -### 提交规范 |
435 | | - |
436 | | -项目使用 **Conventional Commits** 规范,格式为 `<type>(<scope>): <description>`: |
437 | | - |
438 | | -| 类型 | 说明 | 类型 | 说明 | |
439 | | -|------|------|------|------| |
440 | | -| `feat` | 新功能 | `docs` | 文档变更 | |
441 | | -| `fix` | 缺陷修复 | `style` | 代码格式调整 | |
442 | | -| `refactor` | 重构 | `test` | 测试相关 | |
443 | | -| `perf` | 性能优化 | `chore` | 构建或工具变更 | |
444 | | - |
445 | | -**示例:** |
446 | | - |
447 | | -``` |
448 | | -feat(notes): 添加康奈尔笔记模板 |
449 | | -fix(pomodoro): 修复切换标签页后计时器暂停的问题 |
450 | | -docs: 更新 README 快速开始章节 |
451 | | -``` |
452 | | - |
453 | | -### 代码质量 |
454 | | - |
455 | | -提交前请确保以下检查全部通过: |
456 | | - |
457 | | -```bash |
458 | | -npm run lint # 代码检查(Oxlint) |
459 | | -npm run test # 单元测试(Vitest) |
460 | | -npm run build # 构建验证(TypeScript) |
461 | | -``` |
462 | | - |
463 | | ---- |
464 | | - |
465 | | -## 📄 许可证 |
466 | | - |
467 | | -本项目基于 [Apache License 2.0](./LICENSE) 开源协议发布。 |
0 commit comments