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