项目概述
本项目为 AI 智能体全栈项目。
后端基于 Python、FastAPI、LangChain、LangGraph 构建智能 Agent 服务；前端使用 Vue3 开发。
技术栈：Python3.12+、Pydantic、mypy、ruff、pytest、FastAPI、LangChain、LangGraph、Vue3、Pinia。
所有代码修改、新增逻辑必须严格遵循本文档命令、代码规范与开发流程。
目录规范
src/langchain/：LangChain、LangGraph 核心业务逻辑prompts/：所有提示词模板，禁止业务代码内硬编码长提示词src/utils/：通用工具函数，新增函数必须配套单元测试tests/：单元测试目录，tests/graph/专门存放 LangGraph 测试用例src/router/：FastAPI 路由定义src/service/：业务逻辑层src/schema/：Pydantic 数据模型
常用命令
npm run dev：启动 Vue3 前端开发服务uvicorn main:app --reload：启动 FastAPI 后端热更新服务pytest tests/：执行全部后端单元测试pytest tests/graph/：仅运行 LangGraph 智能体模块测试docker-compose up -d：后台启动向量库、Redis 等依赖服务git pull && git checkout -b feature/xxx：拉取最新代码并新建功能分支
代码规范
- Python：统一使用 Python3.12+，开启 mypy 严格类型校验，数据模型全部使用 Pydantic 定义
- LangGraph：严格拆分状态、节点、边逻辑；节点优先纯函数写法，禁止使用全局变量存储会话状态，所有会话数据统一托管在 Graph State
- LangChain：所有封装逻辑统一放在
src/langchain/，提示词全部抽离至prompts/目录 - FastAPI：严格遵循路由、业务、模型分层架构，工具函数统一归入
src/utils/ - Vue3：统一使用
<script setup>语法，全局状态优先使用 Pinia 管理 - Git 提交：采用 feat/fix/refactor/docs 规范前缀，禁止一次性大批量提交代码
开发工作流
- Python 代码修改完成后，执行静态类型检查：
mypy src/ - 前端代码修改完成后，执行类型校验：
npm run type-check - 代码提交前统一格式化纠错：后端
ruff check --fix .、前端npm run format - 本地运行对应模块 pytest 测试，新增逻辑必须补充对应测试用例
- 提交 PR 时，附带改动说明、接口出入参示例、关键业务截图
- PR 合并前，确保 CI 流水线（类型检查、代码规范、单元测试）全部通过
AI 强制约束
- 新增业务逻辑时，同步设计并编写 pytest 单元测试
- 修改 LangGraph 逻辑优先更新 State 定义，不允许只改节点不更新状态
- 禁止私自引入第三方依赖，如需新增库必须先说明用途
- 代码修改完成后，主动告知需执行的校验、测试命令