一个面向中文学习者的 AI 英语学习 Agent：从自然对话出发，自动提取语法、词汇与搭配，并串联语法树、个人笔记、音标训练和间隔复习，形成完整学习闭环。
普通 AI 对话很擅长“即时回答”，但有价值的知识往往随着会话结束而流失。IntuLing 关注的不是再做一个聊天框，而是解决三个连续问题：
- 理解：让 AI 根据输入自动选择句子解析、单词拆解或自由对话模式。
- 沉淀：把聊天中的单词、词根词缀、搭配和语法内容保存为结构化资产。
- 复习：通过语法学习进度、个人笔记、音标练习和间隔复习帮助长期掌握。
flowchart LR
A[自然语言输入] --> B[AI 流式对话]
B --> C{学习内容识别}
C --> D[语法知识与笔记]
C --> E[单词 / 词根词缀 / 搭配]
E --> F[个人词库]
D --> G[学习进度]
F --> H[间隔复习]
G --> I[长期知识资产]
H --> I
| 模块 | 已实现能力 |
|---|---|
| AI 对话 | 多会话管理、自动/句子解析/单词拆解模式、SSE 流式响应、Markdown 渲染、学习建议提取 |
| 语法树 | 分阶段课程地图、关卡锁定与解锁、学习会话、进度记录、内置语法课程导入 |
| 学习笔记 | 自动生成课程默认笔记、Markdown 预览、个人内容覆盖与持久化 |
| 单词学习 | 从对话一键收藏、词根词缀与搭配归档、来源去重、搜索筛选、掌握度管理、每日复习队列 |
| 音标训练 | 48 个音标分组、英美音切换、发音方法与常见字母组合、辨音练习、单词音素拆分 |
- 对话即采集入口：AI 回复不止用于阅读，还会生成可接受或忽略的学习建议。
- 内容结构化存储：单词、构词成分、搭配、例句、来源消息和复习记录分别建模。
- 知识与训练联动：词汇详情关联音标拆分，课程内容关联笔记和学习状态。
- 自适应复习节奏：根据“忘记 / 困难 / 掌握”更新掌握度、复习阶段和下次复习时间。
- 响应式学习界面：桌面端侧边栏与移动端底部导航适配五个核心模块。
flowchart TB
subgraph Web[Frontend]
React[React 19 + TypeScript]
Query[TanStack Query]
UI[Tailwind CSS 4]
end
subgraph API[Backend]
FastAPI[FastAPI]
Service[Domain Services]
LangChain[LangChain]
end
subgraph Data[Data Layer]
SQLAlchemy[SQLAlchemy 2]
PostgreSQL[(PostgreSQL)]
Alembic[Alembic]
end
subgraph Model[AI Providers]
DeepSeek[DeepSeek]
OpenAI[OpenAI-compatible API]
end
React --> Query -->|REST / SSE| FastAPI
UI --> React
FastAPI --> Service
Service --> SQLAlchemy --> PostgreSQL
Alembic --> PostgreSQL
Service --> LangChain
LangChain --> DeepSeek
LangChain --> OpenAI
- 前端：React 19、TypeScript 6、Vite 8、React Router、TanStack Query、Tailwind CSS 4、Vitest
- 后端：Python 3.13、FastAPI、Pydantic Settings、SQLAlchemy 2 Async、Alembic、Pytest
- AI：LangChain、DeepSeek、OpenAI-compatible API、SSE 流式传输
- 数据：PostgreSQL、JSONB、异步数据库会话
- 工程化：npm、uv、Ruff、Oxlint、前后端独立测试
IntuLing/
├── frontend/ # React 单页应用
│ └── src/
│ ├── components/ # 通用 UI、布局与 Markdown 组件
│ ├── features/ # chat / grammar / vocabulary / phonetics
│ ├── lib/ # API Client 与工具函数
│ └── providers/ # TanStack Query Provider
├── backend/ # FastAPI 服务
│ ├── content/grammar/ # 可导入的 Markdown 语法课程
│ ├── migrations/ # Alembic 数据库迁移
│ ├── src/intuling_api/
│ │ ├── ai/ # 模型 Provider 适配
│ │ ├── api/routes/ # REST / SSE 接口
│ │ ├── models/ # SQLAlchemy 领域模型
│ │ ├── schemas/ # Pydantic 请求响应模型
│ │ └── services/ # 学习领域逻辑
│ └── tests/ # 后端测试
└── Resource/ # 产品设计与英语学习资料
- Node.js 22+
- Python 3.13+
- uv
- PostgreSQL 16+
npm --prefix frontend install
uv sync --directory backendcreatedb -h 127.0.0.1 -p 5432 -U postgres intuling_devPowerShell：
Copy-Item backend/.env.example backend/.env
Copy-Item frontend/.env.example frontend/.envBash：
cp backend/.env.example backend/.env
cp frontend/.env.example frontend/.env按本地环境修改 backend/.env 中的数据库连接。使用 AI 对话时，还需要配置模型：
AI_PROVIDER="deepseek" # 或 openai
AI_MODEL="deepseek-chat"
AI_API_KEY="your-api-key"
AI_BASE_URL="" # 使用兼容 API 时填写未配置 AI Key 时，语法内容、单词、音标等非生成式接口仍可使用；AI 对话需要有效的模型配置。
npm run migrate:api
npm run import:grammar分别打开两个终端：
npm run dev:apinpm run dev:web| 服务 | 地址 |
|---|---|
| Web 应用 | http://localhost:5173 |
| API 服务 | http://localhost:8000 |
| Swagger 文档 | http://localhost:8000/docs |
# 前端测试 / 构建 / 代码检查
npm run test:web
npm run build:web
npm run lint:web
# 后端测试 / 代码检查
npm run test:api
npm run lint:api当前测试覆盖了聊天模式识别与 SSE 事件、语法课程解析与解锁规则、词汇去重与复习调度、48 音标数据与单词音素分析，以及核心前端页面交互。
- SSE 流式聊天：后端异步生成事件，前端逐块解析并同步更新消息与学习建议。
- Provider 可替换设计：通过统一配置切换 DeepSeek 或 OpenAI-compatible 模型。
- 领域化数据模型：将“聊天记录”和“学习资产”解耦，同时保留来源追踪关系。
- 幂等内容导入：Markdown + Frontmatter 管理语法课程，通过脚本重复导入并更新数据库。
- 异步全栈链路：FastAPI、SQLAlchemy Async 与 asyncpg 构成非阻塞数据访问链路。
- 可测试的复习算法：复习阶段、掌握度、间隔天数和每日配额均由独立服务逻辑驱动。
- 接入语音播放与跟读评分
- 完善用户系统与多端学习数据同步
- 增加学习数据可视化与周报
- 补充 Docker Compose 与在线演示环境
IntuLing — 让每一次 AI 对话都成为可积累、可追踪、可复习的学习过程。