企业官网建设流程全解析

适合前后端/测试等有编程基础的同学，手把手带你走完企业级Agent项目的完整交付流程

前言

经过前面22节课的系统学习，你已经掌握了AI Agent开发的完整技能树：

现在是时候把所有知识串起来了。

一句话定义：综合实战是将前面22节课的所有知识点，通过一个完整的企业级项目从需求分析、架构设计、代码开发、测试评估到部署上线的全流程，进行一次系统性的整合与验证。

今天这一节（第23节）聚焦于需求分析与架构设计——这是整个项目成败的关键。代码可以重构，但架构错了，整个项目都要推倒重来。

一、项目选题：三个实战方向

我们从以下三个实战项目中三选一，每个项目都覆盖了前面22节课的核心知识点：

项目A：智能客服Agent（推荐⭐）

业务场景：为一家中型电商公司构建智能客服系统，处理用户售前咨询、售后问题和工单创建。

为什么推荐：业务逻辑清晰、技术覆盖全面、可落地性强、简历含金量高。

项目B：代码审查Agent

业务场景：为开发团队构建自动化代码审查工具，在PR阶段自动分析代码质量、发现潜在Bug。

项目C：数据分析Agent

业务场景：让业务人员用自然语言查询数据、自动生成SQL、执行分析并输出可视化图表。

二、项目选择与决策

💡建议：如果你时间有限或想快速上手，选择项目A（智能客服）。它是三个项目中最“标准”的Agent应用场景，技术覆盖最全面，也是面试中最常被问到的案例。

决策矩阵：

本文以项目A（智能客服）为主线进行完整实战，项目B和C的架构思路类似，可在理解A的基础上自行迁移。

三、需求分析与功能拆解

3.1 业务需求文档（BRD）

项目名称：智能客服Agent系统（E-commerce Customer Service Agent）

目标用户：电商平台普通消费者（C端）+ 客服管理人员（B端）

核心价值：

• 7×24小时即时响应，解决80%的常见问题
• 自动分流复杂问题到人工客服
• 降低客服人力成本40%以上

3.2 功能需求清单（FRD）

3.3 非功能需求（NFR）

3.4 Agent能力边界定义

这是架构设计中最容易被忽略、但最关键的环节：

Agent应该做什么，不应该做什么？

能力边界的影响：

• 工具设计：你只需要给Agent“只读”或“受控写入”的工具
• 权限模型：Agent不需要拥有写权限，只有受控写入的中间层
• 安全风险：如果有人注入攻击，最多泄露信息而不是删除数据

四、技术选型

4.1 技术栈总览

4.2 为什么选DeepSeek-V4-Flash？

DeepSeek的性价比优势在客服场景中非常明显——每日海量会话，成本差异直接决定项目能否盈利。

五、架构设计

5.1 系统架构图

┌─────────────────────────────────────────────────────────────────────┐ │ 用户层 │ │ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │ │ │ Web/小程序 │ │ APP客户端 │ │ API调用方 │ │ │ └──────┬───────┘ └──────┬───────┘ └──────┬───────┘ │ │ └─────────────────┼─────────────────┘ │ │ ↓ │ │ ┌─────────────────────────────────────────────────────────────┐ │ │ │ API Gateway / Nginx │ │ │ │ （限流 + 认证 + 负载均衡） │ │ │ └─────────────────────────────────────────────────────────────┘ │ │ ↓ │ │ ┌─────────────────────────────────────────────────────────────┐ │ │ │ FastAPI 服务层 │ │ │ │ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │ │ │ │ │ 会话管理 │ │ 意图识别 │ │ 路由分发 │ │ │ │ │ └─────────────┘ └─────────────┘ └─────────────┘ │ │ │ └─────────────────────────────────────────────────────────────┘ │ │ ↓ │ │ ┌─────────────────────────────────────────────────────────────┐ │ │ │ LangGraph Agent 核心编排层 │ │ │ │ ┌──────────────────────────────────────────────────────┐ │ │ │ │ │ Supervisor │ │ │ │ │ │ ┌──────────┐ ┌──────────┐ ┌──────────┐ │ │ │ │ │ │ │ 售前Agent│ │ 售后Agent│ │ 工单Agent│ │ │ │ │ │ │ └────┬─────┘ └────┬─────┘ └────┬─────┘ │ │ │ │ │ │ └──────┬──────┘ │ │ │ │ │ │ │ ↓ ↓ │ │ │ │ │ │ ┌──────────┐ ┌──────────┐ │ │ │ │ │ │ │ RAG引擎 │ │工具执行器│ │ │ │ │ │ │ └──────────┘ └──────────┘ │ │ │ │ │ └──────────────────────────────────────────────────────┘ │ │ │ └─────────────────────────────────────────────────────────────┘ │ │ ↓ │ │ ┌─────────────────────────────────────────────────────────────┐ │ │ │ 基础设施层 │ │ │ │ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐ │ │ │ │ │PostgreSQL│ │ Redis │ │ 向量数据库│ │ 对象存储 │ │ │ │ │ │(检查点) │ │(缓存/队列)│ │ (知识库) │ │ (日志) │ │ │ │ │ └──────────┘ └──────────┘ └──────────┘ └──────────┘ │ │ │ └─────────────────────────────────────────────────────────────┘ │ │ │ │ ┌─────────────────────────────────────────────────────────────┐ │ │ │ 可观测性层 │ │ │ │ ┌──────────┐ ┌──────────┐ ┌──────────┐ │ │ │ │ │LangSmith │ │ LangFuse │ │Prometheus│ │ │ │ │ │(追踪+评估)│ │ (成本监控)│ │ (指标) │ │ │ │ │ └──────────┘ └──────────┘ └──────────┘ │ │ │ └─────────────────────────────────────────────────────────────┘ │ └─────────────────────────────────────────────────────────────────────┘

5.2 Agent工作流设计（LangGraph状态图）

fromtypingimportTypedDict,Literalfromlanggraph.graphimportStateGraph,START,ENDfromlanggraph.checkpoint.memoryimportInMemorySaverclassCustomerServiceState(TypedDict):"""客服Agent全局状态"""messages:list# 对话历史user_id:str# 用户IDintent:str# 意图分类query:str# 当前查询knowledge_context:str# RAG检索结果order_info:dict# 订单信息need_human:bool# 是否需要转人工ticket_created:bool# 是否已创建工单iteration:int# 当前迭代次数defsupervisor_node(state:CustomerServiceState)->dict:"""监督者节点：意图识别与路由分发"""# 1. 识别用户意图（售前/售后/转人工/通用）intent=classify_intent(state["query"])return{"intent":intent}defrouter(state:CustomerServiceState)->Literal["pre_sales","after_sales","human","general"]:"""路由函数：根据意图分发到不同子Agent"""returnstate["intent"]# 构建图graph=StateGraph(CustomerServiceState)graph.add_node("supervisor",supervisor_node)graph.add_node("pre_sales_agent",pre_sales_node)# 售前Agentgraph.add_node("after_sales_agent",after_sales_node)# 售后Agentgraph.add_node("human_agent",human_node)# 转人工Agentgraph.add_node("general_agent",general_node)# 通用Agentgraph.add_node("retriever",retriever_node)# RAG检索节点graph.add_node("tool_executor",tool_executor_node)# 工具执行节点# 定义路由graph.add_edge(START,"supervisor")graph.add_conditional_edges("supervisor",router,{"pre_sales":"pre_sales_agent","after_sales":"after_sales_agent","human":"human_agent","general":"general_agent"})graph.add_edge("pre_sales_agent","retriever")graph.add_edge("after_sales_agent","tool_executor")graph.add_edge("retriever","tool_executor")graph.add_edge("tool_executor",END)graph.add_edge("human_agent",END)graph.add_edge("general_agent",END)checkpointer=InMemorySaver()app=graph.compile(checkpointer=checkpointer)

5.3 数据模型设计

-- 用户表CREATETABLEusers(id UUIDPRIMARYKEYDEFAULTgen_random_uuid(),phoneVARCHAR(20)UNIQUE,emailVARCHAR(255)UNIQUE,created_atTIMESTAMPDEFAULTNOW());-- 会话表CREATETABLEsessions(id UUIDPRIMARYKEYDEFAULTgen_random_uuid(),user_id UUIDREFERENCESusers(id),thread_idVARCHAR(255)UNIQUE,-- LangGraph thread_idstatusVARCHAR(20)DEFAULT'active',created_atTIMESTAMPDEFAULTNOW(),updated_atTIMESTAMPDEFAULTNOW());-- 消息表CREATETABLEmessages(id UUIDPRIMARYKEYDEFAULTgen_random_uuid(),session_id UUIDREFERENCESsessions(id),roleVARCHAR(20),-- user / assistant / toolcontentTEXT,tool_calls JSONB,created_atTIMESTAMPDEFAULTNOW());-- 工单表CREATETABLEtickets(id UUIDPRIMARYKEYDEFAULTgen_random_uuid(),session_id UUIDREFERENCESsessions(id),user_id UUIDREFERENCESusers(id),categoryVARCHAR(50),descriptionTEXT,statusVARCHAR(20)DEFAULT'pending',created_atTIMESTAMPDEFAULTNOW());-- 知识库（向量存储在pgvector）CREATETABLEknowledge_base(id UUIDPRIMARYKEYDEFAULTgen_random_uuid(),contentTEXT,metadata JSONB,embedding vector(1536),-- pgvectorcreated_atTIMESTAMPDEFAULTNOW());-- 创建向量索引CREATEINDEXknowledge_embedding_idxONknowledge_baseUSINGivfflat(embedding vector_cosine_ops)WITH(lists=100);

5.4 工具设计（Tools）

fromlangchain.toolsimporttool# 只读工具（低风险）@tooldefget_product_info(product_name:str)->str:"""查询商品信息，包括价格、库存、规格。仅用于售前咨询。"""# SELECT * FROM products WHERE name LIKE '%{product_name}%'pass@tooldefget_order_status(order_id:str)->str:"""查询订单状态和物流信息。仅用于售后咨询。"""# SELECT status, tracking FROM orders WHERE order_id = '{order_id}'pass# 受控写入工具（中风险，需要确认）@tooldefcreate_return_request(order_id:str,reason:str)->str:"""创建退换货申请。需要用户确认后才能调用。"""# INSERT INTO returns (order_id, reason, status) VALUES ...pass# 高风险操作（需要Human-in-the-Loop）@tooldefescalate_to_human(reason:str)->str:"""将对话转接给人工客服。用于复杂问题。"""# 触发转人工流程pass

5.5 RAG知识库设计

六、项目初始化

6.1 项目目录结构

customer-service-agent/ ├── app/ │ ├── __init__.py │ ├── main.py # FastAPI入口 │ ├── agent/ │ │ ├── __init__.py │ │ ├── graph.py # LangGraph定义 │ │ ├── nodes.py # 各节点实现 │ │ └── state.py # 状态定义 │ ├── tools/ │ │ ├── __init__.py │ │ ├── product.py # 商品查询工具 │ │ ├── order.py # 订单查询工具 │ │ ├── ticket.py # 工单工具 │ │ └── human.py # 转人工工具 │ ├── rag/ │ │ ├── __init__.py │ │ ├── loader.py # 文档加载器 │ │ ├── splitter.py # 文本分割器 │ │ ├── embedding.py # 向量化 │ │ └── retriever.py # 检索器 │ ├── memory/ │ │ ├── __init__.py │ │ ├── checkpointer.py # 检查点配置 │ │ └── store.py # 长期记忆配置 │ ├── api/ │ │ ├── __init__.py │ │ ├── routes.py # API路由 │ │ └── models.py # Pydantic模型 │ ├── config/ │ │ ├── __init__.py │ │ └── settings.py # 配置管理 │ └── utils/ │ ├── __init__.py │ └── logging.py # 日志配置 ├── tests/ │ ├── unit/ │ └── integration/ ├── deployments/ │ ├── docker-compose.yml │ └── Dockerfile ├── scripts/ │ ├── init_db.py # 数据库初始化 │ └── load_knowledge.py # 知识库加载 ├── requirements.txt ├── .env.example └── README.md

6.2 环境配置

# .env.example# LangChainLANGSMITH_API_KEY=your_langsmith_keyLANGSMITH_TRACING=trueLANGSMITH_PROJECT=cs-agent# 模型LLM_API_KEY=your_deepseek_keyLLM_BASE_URL=https://api.deepseek.comLLM_MODEL=deepseek-v4-flash# 数据库DATABASE_URL=postgresql://agent:pass@localhost:5432/cs_agent# RedisREDIS_URL=redis://localhost:6379/0# 向量数据库VECTOR_STORE_PATH=./chroma_db

6.3 依赖清单

# requirements.txt # Core langchain>=1.0.0 langgraph>=1.0.0 langchain-openai>=1.0.0 langchain-community>=1.0.0 # Web fastapi>=0.115.0 uvicorn[standard]>=0.30.0 pydantic>=2.0.0 # Database asyncpg>=0.29.0 pgvector>=0.2.5 sqlalchemy>=2.0.0 # Vector DB chromadb>=0.5.0 # Async celery>=5.3.0 redis>=5.0.0 # Observability langsmith>=0.1.0 langfuse>=2.0.0 # Utils python-dotenv>=1.0.0 python-multipart>=0.0.9

6.4 核心配置类

# app/config/settings.pyfrompydantic_settingsimportBaseSettingsclassSettings(BaseSettings):"""应用配置"""# LangSmithlangsmith_api_key:strlangsmith_tracing:bool=Truelangsmith_project:str="cs-agent"# LLMllm_api_key:strllm_base_url:str="https://api.deepseek.com"llm_model:str="deepseek-v4-flash"llm_temperature:float=0.3# Embeddingembedding_model:str="text-embedding-3-small"# Databasedatabase_url:str="postgresql://agent:pass@localhost:5432/cs_agent"# Redisredis_url:str="redis://localhost:6379/0"# Vector Storevector_store_path:str="./chroma_db"# Agentmax_iterations:int=10max_tokens_per_session:int=50000cost_budget_per_session:float=0.5# USDclassConfig:env_file=".env"settings=Settings()

七、动手：搭建项目骨架

🚀本节动手任务：完成项目的初始化搭建，为下一节的完整开发做好准备。

任务清单

快速启动脚本

#!/bin/bash# scripts/setup.shecho"🚀 初始化智能客服Agent项目..."# 1. 创建虚拟环境python-mvenv venvsourcevenv/bin/activate# 2. 安装依赖pipinstall-rrequirements.txt# 3. 复制环境配置cp.env.example .envecho"⚠️ 请编辑.env文件，填写API Key"# 4. 启动依赖服务docker-composeup-dpostgres redis# 5. 初始化数据库python scripts/init_db.py# 6. 加载示例知识库python scripts/load_knowledge.py--sampleecho"✅ 项目初始化完成！"echo"启动API服务：uvicorn app.main:app --reload"

八、实战小练习（作业）

练习：完成项目骨架搭建 + 架构文档

第一部分：动手搭建

按照本节的任务清单，完成项目的初始化搭建，确保所有服务能够正常启动。

第二部分：架构文档

撰写一份简短的架构文档（README.md），包含：

1. 项目概述（一句话说明项目是什么）
2. 技术栈（列出所有使用的技术和版本）
3. 系统架构图（可以手绘或用工具绘制）
4. 核心流程说明（用户请求的完整处理链路）
5. 部署说明（如何启动、如何配置）

第三部分：扩展思考

请思考以下问题并写出你的答案：

1. 如果客服Agent每天要处理10万次会话，架构中哪个环节最可能成为瓶颈？
2. 如果用户恶意攻击（如高频请求、注入攻击），你的架构如何防御？
3. 如果大模型API突然不可用，系统应该如何降级？

提交物：

1. 项目Git仓库地址（或本地目录截图）
2. README.md（架构文档）
3. 扩展思考的答案

结语

今天这节课，我们完成了综合实战项目的第一阶段——需求分析与架构设计：

第23节核心价值：“一个清晰、完整的架构设计，比草率的代码实现重要100倍。”好的架构能让后续开发事半功倍，糟糕的架构会让你在代码中迷失方向。

下节课（第24节，最后一节），我们将进入综合实战（下）——完成全部代码开发、集成测试、部署上线与项目交付！

如果觉得有帮助，欢迎点赞、收藏、评论三连！我们最后一节课见！

📌 本文是《AI Agent开发实战》课程第23节的完整内容，系列文章持续更新中，关注我不迷路！