Skip to content

Commit bc14d0e

Browse files
committed
docs: 重写 README — 去重合并,新增技术栈章节
1 parent d74fdc9 commit bc14d0e

5 files changed

Lines changed: 51 additions & 250 deletions

File tree

‎README.md‎

Lines changed: 38 additions & 228 deletions
Original file line numberDiff line numberDiff line change
@@ -105,6 +105,44 @@
105105

106106
---
107107

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+
108146
## 🚀 快速开始
109147

110148
### 环境要求
@@ -237,231 +275,3 @@ npm run build # 构建验证(TypeScript)
237275
## 📄 许可证
238276

239277
本项目基于 [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) 开源协议发布。

‎client/electron/main.ts‎

Lines changed: 5 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -4,9 +4,6 @@
44
* 创建 BrowserWindow,注册 IPC handler 代理 AI 网关请求。
55
*/
66

7-
// 开发时禁用 Electron 安全警告
8-
process.env.ELECTRON_DISABLE_SECURITY_WARNINGS = 'true';
9-
107
import { app, BrowserWindow, ipcMain, desktopCapturer, Tray, Menu, nativeImage, dialog } from 'electron';
118
import { ScreenCapture } from './screenCapture.js';
129
import type { ScreenCaptureOptions, ScreenshotFrameData } from './screenCapture.js';
@@ -19,6 +16,11 @@ import { logger } from './logger.js';
1916
import { registerAIHandlers } from './aiHandlers.js';
2017
import { initAutoUpdater, checkForUpdate, downloadUpdate, installUpdate, destroyAutoUpdater, setAutoCheckEnabled } from './updater.js';
2118

19+
// 仅开发模式禁用 Electron 安全警告,生产环境保留
20+
if (process.env.NODE_ENV === 'development' || !app.isPackaged) {
21+
process.env.ELECTRON_DISABLE_SECURITY_WARNINGS = 'true';
22+
}
23+
2224
// CommonJS 模式下 __filename 和 __dirname 全局可用,无需额外声明
2325

2426
// ================================================================

0 commit comments

Comments
 (0)