专题栏说明-平芜编程栈

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 生成一点，就立刻返回一点。

这就是聊天中常见的“打字机效果”。

四、推荐学习路线

顺序	文档	新手重点
1	`1. 配置环境、创建导航栏.md`	明白项目怎么跑起来，前后端怎么分工
2	`2.登录模块.md`	明白用户如何登录，Token 如何保持状态
3	`3. 编辑资料、编辑角色模块.md`	明白表单、图片、文件上传和角色 CRUD
4	`4. 流式布局.md`	明白首页、个人空间、搜索和无限滚动
5	`5. 文字聊天.md`	明白大模型聊天、SSE、历史记录和记忆
6	`6. 语音模块.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 报错；
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

十二、统一接口调试模板

以后调试任意接口时，都按这个顺序看：

1. 请求 URL 是否正确 2. 请求方法 GET / POST 是否正确 3. 请求头是否包含 Authorization 4. Content-Type 是否符合接口要求 5. 请求参数名是否和后端一致 6. 后端是否进入对应 View 7. 后端返回状态码是多少 8. Response 内容是否符合前端预期 9. 前端是否正确读取字段 10. 页面状态是否正确更新

十三、统一自测方法

每完成一个模块，都做这 5 件事：

正常流程测试：按预期操作一次；
空值测试：不填必填项试一次；
未登录测试：退出登录后访问受保护接口；
权限测试：尝试操作不属于自己的资源；
刷新测试：刷新页面后状态是否正确恢复。