AgentTalk / AITalk 项目新手复习导读
一、这套笔记适合谁
这套文档是为第一次系统学习 Django + Vue + AI 应用开发的新手整理的项目复习资料。
如果你只会一点点 Python、JavaScript，甚至还不太熟悉前后端分离，也可以按下面的阅读顺序慢慢看。阅读时不要求一次全部理解，建议每看完一节都回到项目代码里对照文件位置。
++这份笔记是我自己的笔记结合AI生成的一份用来自己复习用的文档，放到博客方便复习。++
项目地址：https://github.com/lionlnuc/AgentTalk
二、先用一句话理解这个项目
AgentTalk 是一个 AI 角色聊天网站。
用户可以：
- 注册、登录账号；
- 修改头像、用户名、简介；
- 创建自己的 AI 角色；
- 在首页浏览别人创建的角色；
- 点击角色开始聊天；
- 让 AI 以文字或语音回复；
- 让 AI 记住一部分长期对话信息；
- 让 AI 使用工具、查询知识库。
可以把它想象成：
一个类似"角色广场 + AI 聊天室 + 语音助手"的综合项目。
三、新手必须先理解的 10 个概念
3.1 前端是什么
前端就是用户能看到、能点击、能输入的页面。
本项目前端使用 Vue 3。
它负责：
- 显示登录页、首页、个人空间、聊天框；
- 接收用户输入；
- 调用后端 API；
- 把后端返回的数据展示出来。
3.2 后端是什么
后端就是运行在服务器上的程序。
本项目后端使用 Django。
它负责：
- 保存用户、角色、聊天记录；
- 校验用户是否登录；
- 接收图片、音频文件；
- 调用大模型、语音识别、语音合成；
- 给前端返回 JSON 或流式数据。
3.3 数据库是什么
数据库用于长期保存数据。
例如：
- 用户账号；
- 用户头像；
- AI 角色；
- 好友关系；
- 聊天记录；
- 系统提示词。
如果不保存到数据库，刷新页面或重启服务后数据就会丢失。
3.4 API 是什么
API 可以理解成前端和后端之间约定好的"窗口"。
例如：
text
POST /api/user/account/login/意思是：前端把用户名和密码交给这个接口，后端检查后告诉前端是否登录成功。
3.5 GET 和 POST 有什么区别
| 方法 | 用途 | 例子 |
|---|---|---|
| GET | 获取数据 | 获取首页角色列表 |
| POST | 提交或修改数据 | 登录、注册、创建角色 |
3.6 JSON 是什么
JSON 是前后端常用的数据格式。
json
{
"result": "success",
"username": "alice"
}前端和后端都能方便地读取这种结构。
3.7 Token 是什么
Token 可以理解成"临时通行证"。
用户登录后，后端发给前端一个 Token。之后前端访问需要登录的接口时，就带上这个 Token，后端看到 Token 合法，就知道"你是谁"。
3.8 组件是什么
Vue 中的组件就是页面的一小块。
例如：
- 导航栏是一个组件；
- 用户菜单是一个组件；
- 角色卡片是一个组件；
- 聊天输入框是一个组件。
把页面拆成组件，可以让代码更清晰。
3.9 路由是什么
路由就是 URL 和页面之间的对应关系。
例如：
text
/ → 首页
/friend/ → 好友页面
/user/profile/ → 编辑资料页面3.10 流式输出是什么
普通输出：AI 想完所有内容后一次性返回。
流式输出：AI 生成一点，就立刻返回一点。
这就是聊天中常见的"打字机效果"。
四、推荐学习路线
| 顺序 | 文档 | 新手重点 |
|---|---|---|
| 1 | 1. 配置环境、创建导航栏.md |
明白项目怎么跑起来，前后端怎么分工 |
| 2 | 2.登录模块.md |
明白用户如何登录，Token 如何保持状态 |
| 3 | 3. 编辑资料、编辑角色模块.md |
明白表单、图片、文件上传和角色 CRUD |
| 4 | 4. 流式布局.md |
明白首页、个人空间、搜索和无限滚动 |
| 5 | 5. 文字聊天.md |
明白大模型聊天、SSE、历史记录和记忆 |
| 6 | 6. 语音模块.md |
明白语音输入、识别、合成和播放 |
五、项目目录用新手语言解释
text
AgentTalk/
├── backend/ # 后端，负责数据库、API、大模型调用
├── frontend/ # 前端，负责页面、按钮、表单、聊天框
├── AITalk笔记/ # 你现在看的复习笔记
├── deploy/ # 部署相关脚本和配置
└── README.md # 项目说明5.1 backend 目录
text
backend/
├── manage.py # Django 命令入口，例如运行服务、迁移数据库
├── db.sqlite3 # 开发环境数据库
├── backend/settings.py # 后端总配置
├── backend/urls.py # 后端总路由
├── web/models/ # 数据库表定义
├── web/views/ # API 逻辑
├── web/urls.py # API 路由表
├── media/ # 用户上传的头像、背景图
└── static/ # 前端打包后的静态文件5.2 frontend 目录
text
frontend/
├── package.json # 前端依赖和脚本
├── vite.config.js # Vite 打包配置
├── src/main.js # 前端入口
├── src/router/index.js # 前端路由表
├── src/stores/user.js # 用户登录状态
├── src/components/ # 公共组件
└── src/views/ # 页面组件六、完整功能流程总览
6.1 登录流程
text
用户输入用户名密码
↓
前端调用登录 API
↓
后端校验用户名密码
↓
后端返回 access token，并把 refresh token 写入 Cookie
↓
前端保存用户信息
↓
导航栏显示用户头像6.2 创建角色流程
text
用户填写角色名、人设、头像、背景图
↓
前端把图片裁剪成 Base64
↓
Base64 转 File
↓
FormData 上传给后端
↓
后端保存角色和图片路径
↓
个人空间显示新角色6.3 文字聊天流程
text
用户点击角色卡片
↓
后端创建或获取 Friend 关系
↓
打开聊天框
↓
用户发送文字
↓
后端拼接系统提示词、历史消息、长期记忆
↓
调用大模型
↓
SSE 一段一段返回文本
↓
前端实时显示6.4 语音聊天流程
text
用户说话
↓
前端 VAD 检测到一段人声
↓
音频上传到 ASR 接口
↓
后端把语音转成文字
↓
文字继续走聊天流程
↓
后端把 AI 回复转成语音
↓
前端边接收边播放七、学习时怎么看代码
建议每次看一个模块时按这个顺序：
- 先看文档中的"本节目标"；
- 看"业务流程图"；
- 找后端模型
models； - 找后端视图
views； - 找后端路由
urls.py； - 找前端页面
views； - 找前端组件
components； - 打开浏览器测试功能；
- 如果报错，先看终端和浏览器控制台。
八、常见调试位置
8.1 浏览器控制台
按 F12 打开开发者工具。
重点看：
Console：前端 JS 报错；Network：API 请求是否成功；Application：Cookie、LocalStorage 等。
8.2 Django 终端
运行后端的窗口会显示：
- 请求路径；
- HTTP 状态码；
- Python 报错堆栈。
8.3 常见状态码
| 状态码 | 含义 | 常见原因 |
|---|---|---|
| 200 | 成功 | 请求正常 |
| 400 | 请求参数错误 | 少传字段、字段为空 |
| 401 | 未认证 | Token 缺失或过期 |
| 403 | 无权限 | 登录了但不能操作该资源 |
| 404 | 找不到路径 | 路由写错 |
| 500 | 后端报错 | Python 代码异常 |
九、新手复习问题
- 前端和后端分别负责什么？
- 为什么登录后需要 Token？
Access Token和Refresh Token有什么区别？- 图片上传为什么要用
FormData？ - Vue 组件为什么要拆分？
- Django 的
models、views、urls分别是什么？ - 什么是 SSE？为什么聊天要用流式输出？
- 为什么语音模块既有 ASR 又有 TTS？
- 什么是 RAG？为什么大模型需要知识库？
- 项目中
Friend模型为什么很重要？
十、阅读建议
不要试图一次完全记住所有内容。推荐方式：
- 第一次：只理解功能流程；
- 第二次：看前后端文件位置；
- 第三次：理解关键代码；
- 第四次：自己尝试改一个小功能；
- 第五次：整理自己的问题和报错。
真正掌握项目不是靠背代码，而是靠理解：
用户操作发生后，数据从哪里来，到哪里去，中间经过了哪些处理。
十一、统一问题排查总表
11.1 后端启动类问题
| 现象 | 优先检查 | 常见原因 | 解决方向 |
|---|---|---|---|
python manage.py runserver 报错 |
终端完整报错 | 依赖缺失、配置错误、迁移未执行 | pip install、检查 settings.py、执行 migrate |
| 数据库表不存在 | Django traceback | 没有迁移数据库 | python manage.py makemigrations 和 python manage.py migrate |
| 接口 500 | Django 终端 | Python 异常 | 看 traceback 最后一段，定位文件和行号 |
| 接口 404 | 浏览器 Network | URL 路径写错或 urls.py 未注册 |
对照前端请求路径和后端路由 |
11.2 前端页面类问题
| 现象 | 优先检查 | 常见原因 | 解决方向 |
|---|---|---|---|
| 页面白屏 | Console | 组件导入失败、JS 报错、静态资源 404 | 看第一条红色错误 |
| 点击路由没反应 | router 配置 | name 写错、路径写错 |
对照 router/index.js |
| 刷新页面 404 | Django 路由 | 缺少 SPA 兜底路由 | 配置返回 index.html 的兜底规则 |
| 样式不生效 | Elements / Network | Tailwind 未编译、CSS 未加载 | 检查 class、打包资源路径 |
11.3 登录认证类问题
| 现象 | 优先检查 | 常见原因 | 解决方向 |
|---|---|---|---|
| 登录成功但仍显示未登录 | Pinia store | 没保存用户信息 | 检查登录成功后的 store 更新 |
| 请求一直 401 | Request Headers | 没带 Authorization 或 token 过期 |
检查 Axios 请求拦截器 |
| refresh 失败 | Cookies | Cookie 未写入或过期 | 检查 withCredentials 和 Cookie 配置 |
| 退出后仍显示头像 | store 状态 | 没清空用户状态 | logout 时清空 token 和 userInfo |
11.4 文件上传类问题
| 现象 | 优先检查 | 常见原因 | 解决方向 |
|---|---|---|---|
| 后端拿不到图片 | Network Payload | 没用 FormData 或字段名不一致 |
检查 request.FILES.get('photo') |
| 图片显示 404 | 图片 URL | MEDIA_URL 或 MEDIA_ROOT 配置错误 |
检查媒体文件路由 |
| 更新图片后旧图还在 | media 目录 | 没删除旧文件 | 更新前删除旧文件 |
| Croppie 不显示 | Console | 容器未渲染、组件重复初始化 | 使用 nextTick，卸载时 destroy |
11.5 列表和搜索类问题
| 现象 | 优先检查 | 常见原因 | 解决方向 |
|---|---|---|---|
| 无限滚动重复请求 | Network | 没有 isLoading 锁 |
请求开始和结束维护 loading 状态 |
| 搜索结果混乱 | 组件状态 | 没清空旧列表 | query 改变后重置列表和计数 |
| 搜索无结果但数据库有 | 后端查询 | 字段名或查询条件错 | 检查 Q 查询和参数名 |
| 删除按钮触发打开聊天 | 点击事件 | 事件冒泡 | 使用 @click.stop |
11.6 聊天和大模型类问题
| 现象 | 优先检查 | 常见原因 | 解决方向 |
|---|---|---|---|
| 没有流式效果 | Response | 后端不是 SSE 格式 | 检查 text/event-stream 和 yield |
JSON.parse 报错 |
SSE 数据 | 把 [DONE] 当 JSON 解析 |
先判断 [DONE] 再解析 |
| AI 没上下文 | 后端 prompt | 没拼接历史或记忆 | 检查系统提示词、短期历史、长期记忆 |
| 工具调用不生效 | LangGraph 配置 | 工具没绑定或 docstring 不清楚 | 检查 bind_tools 和 ToolNode |
| RAG 查不到内容 | 向量库 | 文档没入库或 embedding 不一致 | 重新构建向量库 |
11.7 语音类问题
| 现象 | 优先检查 | 常见原因 | 解决方向 |
|---|---|---|---|
| 麦克风无法使用 | 浏览器权限 | 非 HTTPS、权限被拒绝 | 使用 localhost 或 HTTPS，允许麦克风 |
| VAD 加载失败 | Network | 模型路径错误 | 检查 public/vad 静态资源 |
| ASR 结果为空 | 音频格式 | PCM 格式或采样率错误 | 检查 Float32 转 PCM16 |
| 有文字没声音 | SSE 数据 | 没收到 audio 或播放失败 | 检查 base64、MediaSource、自动播放限制 |
| 新旧回复混在一起 | processId | 没打断旧流和旧音频 | 每轮对话更新 processId 并 stopAudio |
十二、统一接口调试模板
以后调试任意接口时，都按这个顺序看：
text
1. 请求 URL 是否正确
2. 请求方法 GET / POST 是否正确
3. 请求头是否包含 Authorization
4. Content-Type 是否符合接口要求
5. 请求参数名是否和后端一致
6. 后端是否进入对应 View
7. 后端返回状态码是多少
8. Response 内容是否符合前端预期
9. 前端是否正确读取字段
10. 页面状态是否正确更新十三、统一自测方法
每完成一个模块，都做这 5 件事：
- 正常流程测试：按预期操作一次；
- 空值测试：不填必填项试一次；
- 未登录测试：退出登录后访问受保护接口；
- 权限测试：尝试操作不属于自己的资源；
- 刷新测试：刷新页面后状态是否正确恢复。