AITeachMe

让天下没有难学的知识。

AITeachMe 是一个资料驱动的 AI 学习系统，把课程资料转化为可讲、可问、可测、可追踪的个人学习空间。

AITeachMe 是什么

现代学习最难的地方不是缺资料，而是资料很难转化成持续、可验证、可复用的学习行为。AITeachMe 以 Course 为边界，把上传资料、知识文档、知识图谱、伴读对话、诊断练习和学习画像串成一个闭环。

学习资料
  -> Ingest: 解析为标准 Markdown 与资产
  -> Digest: 生成学习方案、知识文档与知识图谱
  -> Interact: 围绕资料和上下文伴读问答
  -> Examine: 出题、作答、判卷、错因解释
  -> Profile: 沉淀掌握度、薄弱点、复习任务和学习画像

它不是一个简单的 ChatGPT 壳，也不是只做文件摘要的工具。项目目标是让一门课程拥有可持续复用的资料解析结果、教学上下文、诊断反馈和学习记录。

如果说传统学习软件解决的是“资料放在哪里”，AITeachMe 想进一步解决“资料如何被组织、追问、验证并沉淀到下一次学习”。资料进入系统后，不只被摘要，也会成为后续教学、练习、复习和画像可以复用的上下文。

为什么值得关注

当前状态

AITeachMe 当前处于 MVP 到早期产品化阶段，核心链路已经按真实应用边界拆分，但公开展示素材、部署模板和社区协作流程仍在持续完善。

保持关注

如果你想跟进 AITeachMe 的新功能、产品改进和后续发布，欢迎给仓库点一个 Star。

也欢迎扫码加入 AITeachMe 微信群，直接交流产品想法、使用反馈和后续共创计划。

核心能力

端到端架构

flowchart LR
  User[学习者 / 教师] --> Frontend[React Web / Desktop]
  Frontend --> API[FastAPI API]
  API --> Workflows[Workflow 业务层]

  Workflows --> Ingest[Ingest<br/>资料解析]
  Workflows --> Digest[Digest<br/>方案 / 文档 / 图谱]
  Workflows --> Interact[Interact<br/>伴读对话]
  Workflows --> Examine[Examine<br/>诊断练习]
  Workflows --> Profile[Profile<br/>学习画像]

  Ingest --> Store[ContentStore<br/>Local / S3]
  Digest --> KG[Knowledge Graph]
  Interact --> RAG[Local RAG / Search]
  Examine --> Profile
  Profile --> Interact

  Workflows --> Infra[shared.infra<br/>LLM / Embedding / Search / Storage / Observability]
  Infra --> DB[(SQLite / PostgreSQL + pgvector)]

这张图只表达当前主干依赖：API 不直接拼装 AI 能力，业务流程进入 workflows/，共享能力由 shared.infra 提供，知识资产和学习画像围绕课程边界持久化。

产品展示位

这里先只预留产品展示结构，不新增产品截图或演示文件。后续公开发布前建议补齐真实截图、短 GIF 和一段完整课程样例。

使用形态

技术栈

快速启动

环境要求

• Python 3.11+
• Node.js 18+
• Windows 优先支持；Linux/macOS 可按前后端分离方式运行
• 终端和文件读写建议统一使用 UTF-8

后端

cd backend
$env:PYTHONUTF8 = "1"
pip install -e .
uvicorn app.main:app --reload --reload-dir app --port 9020

健康检查：

http://127.0.0.1:9020/api/health

前端

cd frontend
npm install
npm run dev

默认地址：

http://127.0.0.1:5180

开发模式下，Vite 会把 /api 代理到 http://127.0.0.1:9020。

Windows 一键开发入口

.\dev.bat

可通过 .env 或环境变量覆盖端口和 Conda 环境：

AITEACHME_BACKEND_PORT=9020
AITEACHME_FRONTEND_PORT=5180
AITEACHME_CONDA_ENV=<your-conda-env>

最小本地配置

根目录 .env.sample 是本地用户侧变量入口，.env.developer.sample 包含开发、部署、验证码、通知等扩展配置。

APP_MODE=local
AUTH_ENABLED=false
LLM_API_KEY=<model-api-key>
LLM_BASE_URL=https://api.example.com/v1

未启用鉴权的本地模型网关可以不填 LLM_API_KEY。实际模型槽位也可以在设置页或项目 settings override 中配置。

目录结构

AITeachMe/
├── frontend/       # React 前端、Electron/Tauri 桌面端入口
├── backend/        # FastAPI 后端、workflows、models、migrations
├── docs/           # 当前事实源、标准、部署和开发说明
├── infra/          # Docker、Compose、Nginx、部署脚本
├── packaging/      # 打包与发布入口；桌面实现位于 packaging/desktop/
└── scripts/        # 仓库级辅助脚本

后端推荐依赖方向：

api -> workflows -> repositories / shared.infra / models / schemas
shared.infra -> shared.kernel

backend/app/workflows/ 是唯一业务层，承接五大引擎和 support 用例。backend/app/shared/infra/ 只负责 LLM、检索、存储、数据库、workflow runtime、observability 等共享基础设施。

工程原则

• Course first：课程是资料、知识文档、知识图谱、对话、练习和画像的统一边界。
• Workflow native：复杂 AI 流程进入 LangGraph lane，状态、节点、进度和观测都应该可以追踪。
• Evidence first：学习文档和对话尽量回到资料、引用、检索结果和图谱资产，而不是只依赖模型即时发挥。
• Local first：本地模式必须能独立运行；云端能力是扩展，不是使用项目的前置门槛。
• Readable by default：模块 README 和 docs/ 是当前事实源，架构变化必须能被后来者读懂。
• Graceful degradation：可选的外部服务、更新能力和云端能力缺失时，普通本地使用不应被硬阻断。

桌面端与发布

桌面端打包统一从仓库根目录运行：

.\packaging\release.bat

默认生成 Electron local 安装包。Tauri local、remote 包和预绑定本地模型配置都通过显式参数打开，详细说明见 packaging/README.md。

常见入口：

.\packaging\release.bat
.\packaging\release.bat -ImportBundledEnv
.\packaging\release.bat -IncludeTauri
.\packaging\release.bat -IncludeRemote -ApiUrl https://api.example.com

Tauri local 已接入 Tauri v2 updater。没有 GitHub Release、没有更新 manifest 或网络不可达时，更新检查会静默跳过，不影响正常使用。

文档导航

从 docs/README.md 开始阅读。高频入口：

路线图

短期重点：

• 补齐公开 README 的真实截图、演示 GIF、课程样例和英文项目介绍。
• 强化 Ingest 持久化任务队列，减少长解析任务对进程内存状态的依赖。
• 完善 DocGen repair loop，让知识文档生成具备更强的自检和修复闭环。
• 增强 Profile study plan，把画像结果更主动地反馈到复习、练习和伴读建议中。
• 完善云端部署模板、发布流程和社区贡献指引。

中长期方向：

• 更完整的学习档案和认知诊断模型。
• 更强的知识图谱查询、可视化和章节定位能力。
• 更成熟的 .atmx 课程包导入导出和复用流程。
• 面向团队部署的权限、协作和运维能力。
• 更清晰的插件、工具和外部数据源接入边界。

贡献

欢迎围绕以下方向贡献：

• 文件解析质量、OCR、Markdown 规范化和资料预览体验。
• Planner / DocGen / KG 的教学质量、引用依据和质量评估。
• 伴读对话、诊断练习、错因解释和 Profile 学习建议。
• 前端交互、暗色模式、移动端适配和可视化体验。
• 部署、打包、更新、导入导出和文档质量。

开发前建议先阅读：

• CONTRIBUTING.md
• 本地开发
• API 契约与开发流程
• Workflows 结构规则

重要约束：

• Python 使用 3.11+。
• 输入输出文件读写统一使用 UTF-8。
• frontend/src/api/generated/ 由 Orval 生成，不手动修改。
• 架构改动优先同步 docs/ 的当前事实源，以及对应模块目录内 README。
• 文档中不要提交真实密钥、私有部署地址、本机绝对路径或其他敏感信息。

代码量概览

License 与商标

本仓库代码使用 GNU Affero General Public License v3.0 only（AGPL-3.0-only）。

如果你修改本项目并通过网络服务向用户提供访问，需要按照 AGPL-3.0 的要求向这些用户提供相应源码。需要在不触发 AGPL 源码开放义务的场景中使用、集成或托管 AITeachMe，请参考 商业授权说明。

AITeachMe 名称、标识、Logo 和相关品牌资产不随代码许可证授权。商标和品牌使用边界见 TRADEMARKS.md。