# agent_px

**Repository Path**: hephec321/agent_px

## Basic Information

- **Project Name**: agent_px
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-06-24
- **Last Updated**: 2026-06-26

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# AI Agent 全栈培训项目

> 仓库地址：https://gitee.com/hephec321/agent_px.git
> 适用学员：张济琨（中国科学院大学，AI 工程师/全栈开发方向）
> 培训周期：8 节课，建议总学时 27 小时
> 编写日期：2026-06-25

---

## 一、项目简介

本仓库是面向 AI Agent 全栈方向的系统化培训项目，覆盖 **LLM 调用 → LangChain → MCP 协议 → LangGraph → RAG → 全栈整合 → 工程规范 → 综合实战** 完整链路。

包含 4 个可独立运行的子项目与 1 套阶梯式培训材料：

- **4 个实战项目**：`proj01_mcp_agent` / `proj02_vector_databases` / `proj03_langchain_example` / `proj04_langgraph_example`
- **培训材料**：`training/` 目录下 8 节课的笔记、作业、面试题与整体规划

学员完成全部课程后可独立设计并落地「企业知识库智能助手」类 MVP，应对面试冲刺。

---

## 二、仓库目录结构

```
agent_px_zkd/
├── README.md                          # 本文件（项目总览）
├── .gitignore                         # 全仓库忽略规则
│
├── proj01_mcp_agent/                  # 项目 1：MCP 多服务 + LangGraph ReAct Agent
│   ├── backend/                       # FastAPI + FastMCP（weather / write）+ ChatTongyi
│   │   ├── api_server.py
│   │   ├── weather_server.py
│   │   ├── write_server.py
│   │   ├── servers_config.json
│   │   ├── client.py / client_simple.py
│   │   └── README.md
│   └── frontend/                      # Vue 3 + Vite + markdown-it 聊天界面
│       ├── src/components/ChatBox.vue
│       └── README.md
│
├── proj02_vector_databases/           # 项目 2：RAG 知识库问答（Milvus + DashScope）
│   ├── backend/                       # Flask + LangChain + Milvus + 多格式 Loader
│   │   ├── server.py
│   │   ├── api_integration.py
│   │   ├── vector_db_manager.py
│   │   ├── vector_retriever.py
│   │   ├── document_loader.py
│   │   └── README.md
│   └── frontend/                      # Vue 3 拖拽上传 + 引用来源展示
│       ├── src/components/RagChat.vue
│       └── README.md
│
├── proj03_langchain_example/          # 项目 3：LangChain 1.0+ create_agent 单文件示例
│   ├── lanchain_Intelligent_assistant.py
│   ├── requirements.txt
│   ├── .env.example
│   └── README.md
│
├── proj04_langgraph_example/          # 项目 4：LangGraph 多模式脚本案例集
│   ├── langgraph_supervisor_{1,2}.py   # Supervisor 多角色客服
│   ├── langgraph_agent_{1..4}.py       # ReAct / 循环检测 / review 分支
│   ├── langgraph_{3,4,5}.py            # 图结构差异示例
│   ├── requirements.txt
│   ├── .env.example
│   └── README.md
│
└── training/                          # 培训材料
    ├── overall_plan.md                # 8 节课整体计划（学时 / 依赖 / 验收）
    ├── lesson_01_foundation/           # AI Agent 与大模型应用开发基础
    ├── lesson_02_langchain/            # LangChain 核心与 create_agent 工程化
    ├── lesson_03_mcp/                  # MCP 协议与多服务工具生态
    ├── lesson_04_langgraph/            # LangGraph 图式 Agent 架构
    └── lesson_05_rag/                  # RAG 系统与向量数据库
```

> 子项目详细的目录结构、依赖、启动方式、接口契约、常见问题，请参阅各子项目下的 `README.md`。

---

## 三、技术栈总览

| 维度 | 技术 | 应用项目 |
| --- | --- | --- |
| LLM | 通义千问 `qwen-plus`（DashScope，OpenAI 兼容协议） | proj01 / proj02 / proj03 / proj04 |
| Agent 框架 | LangChain 1.0+ `create_agent` + `@tool` | proj03 / proj04 |
| 图式 Agent | LangGraph `StateGraph` / `Supervisor` / `create_react_agent` | proj01 / proj04 |
| 工具协议 | MCP（FastMCP，stdio / SSE）+ `langchain-mcp-adapters` | proj01 |
| 向量库 | Milvus 2.4+ + DashScope `text-embedding-v1` + HuggingFace 降级 | proj02 |
| 后端框架 | FastAPI（lifespan + CORS）/ Flask（蓝图） | proj01 / proj02 |
| 前端框架 | Vue 3（Composition API + `<script setup>`）+ Vite 5 + markdown-it | proj01 / proj02 |
| 工程规范 | `logging` 标准库 / `python-dotenv` / Windows GBK 兼容 / 国内镜像源 | 全部 |

---

## 四、快速开始

### 4.1 克隆仓库

```powershell
git clone https://gitee.com/hephec321/agent_px.git
cd agent_px
```

### 4.2 选择子项目运行

每个子项目独立可运行，进入对应目录参阅其 `README.md`：

| 子项目 | 进入目录 | 启动入口 |
| --- | --- | --- |
| MCP Agent 全栈 | `proj01_mcp_agent/backend` + `proj01_mcp_agent/frontend` | `python api_server.py` + `npm run dev` |
| RAG 知识库 | `proj02_vector_databases/backend` + `proj02_vector_databases/frontend` | `python server.py` + `npm run dev` |
| LangChain 示例 | `proj03_langchain_example` | `python lanchain_Intelligent_assistant.py` |
| LangGraph 案例集 | `proj04_langgraph_example` | `python langgraph_*.py` |

### 4.3 公共环境要求

- **Python**：3.10+（推荐 3.13）
- **Node.js**：18+（推荐 20 LTS）
- **Milvus**：2.4+，监听 `127.0.0.1:19530`（仅 proj02 需要）
- **PowerShell**：建议执行 `chcp 65001` 切换至 UTF-8，避免中文乱码

### 4.4 国内镜像源配置

**pip（清华 / 阿里云二选一）**：

```powershell
python -m pip install --upgrade pip -i https://pypi.tuna.tsinghua.edu.cn/simple
pip install -r requirements.txt -i https://pypi.tuna.tsinghua.edu.cn/simple
```

**npm（淘宝镜像）**：

```powershell
npm config set registry https://registry.npmmirror.com
npm install
```

**HuggingFace（仅 proj02 Embedding 降级时需要）**：

```powershell
$env:HF_ENDPOINT = "https://hf-mirror.com"
```

---

## 五、培训路径

### 5.1 8 节课总览

| 课节 | 主题 | 学时 | 配套项目 |
| --- | --- | --- | --- |
| L01 | AI Agent 与大模型应用开发基础 | 2h | — |
| L02 | LangChain 核心与 create_agent 工程化 | 3h | proj03 |
| L03 | MCP 协议与多服务工具生态 | 3h | proj01 |
| L04 | LangGraph 图式 Agent 架构 | 3h | proj04 + proj01 |
| L05 | RAG 系统与向量数据库 | 4h | proj02 |
| L06 | 全栈整合：FastAPI/Flask + Vue3 | 4h | proj01 + proj02 |
| L07 | 企业级工程规范与生产部署 | 3h | 全部项目 |
| L08 | 综合实战与面试冲刺 | 6h | 全部项目 |

合计 **27 学时**，详见 `training/overall_plan.md`。

### 5.2 推荐学习顺序

```
L01（基础） ──► L02（LangChain） ──► L03（MCP） ──┐
                                                  ├─► L06（全栈）──► L08（实战）
                          L04（Graph） ──────────┤
                          L05（RAG）  ──────────┘
                          L07（规范）贯穿全程
```

### 5.3 每节课学习流程

1. 预习 `notes.md`
2. 课堂运行脚手架 / 子项目源码
3. 完成 `small_assignment.md`
4. 完成 `big_assignment.md`（对照验收点自检）
5. 口述 `interview_questions.md` 答题要点

---

## 六、企业级规范（贯穿全仓库）

### 6.1 编码规范

- **Python I/O**：所有文件读写显式 `encoding="utf-8"`，规避 Windows GBK 编码错误
- **stdout**：Windows 下强制 `sys.stdout.reconfigure(encoding="utf-8")`
- **日志**：统一使用 `logging` 标准库，格式 `时间戳 - 级别 - 模块名 - 消息`，支持 `grep` / `Select-String` / `tee`
- **配置**：API Key / 模型名从 `.env` 加载，**禁止硬编码密钥**（仓库内 `grep -rE "DASHSCOPE_API_KEY\s*=\s*[\"'][^\"']+[\"']" *.py` 无命中）
- **错误处理**：Fail loud 原则——缺 Key / 连接失败时显式报错，不静默吞异常

### 6.2 文档规范

- 每个子项目根目录含 `README.md`，覆盖目录结构 / 依赖 / 启动 / 接口 / 日志 / 常见问题 / 验收
- 培训材料 `notes.md` 引用的 `proj0X_*` 路径真实存在
- 外部链接标注访问日期

### 6.3 安全规范

- `.env` 已加入 `.gitignore`，不提交真实密钥
- 前端 `markdown-it` 显式 `html: false`，防 XSS
- 后端 CORS 在本地联调场景使用 `allow_origins=["*"]`，生产部署需收紧白名单
- 会话隔离通过 `thread_id` + `InMemorySaver` / `MemorySaver` 实现

### 6.4 注释规范

- 公共模块、类、函数含 docstring，说明「为什么」而非「是什么」
- 魔法数字、临时 Hack、Workaround 标注 `// FIXME` / `// HACK` 并附原因
- 禁止注释掉的死代码（通过 Git 管理历史）

---

## 七、PowerShell 使用约定

Windows PowerShell **不支持** `&&` 作为命令分隔符，本仓库所有文档统一使用以下方式：

```powershell
# 方式 1：分号分隔
cd proj01_mcp_agent\backend ; python api_server.py

# 方式 2：分行执行
cd proj01_mcp_agent\backend
python api_server.py
```

---

## 八、验收检查清单

仓库根目录与各子项目均设有验收检查点，主要包括：

- 无硬编码 API Key（`Select-String -Path *.py -Pattern 'DASHSCOPE_API_KEY\s*=\s*["''][^"'']+["'']'` 无命中）
- 日志格式含时间戳与级别
- 无跨项目 `import`（`proj01` 不依赖 `proj02` 等）
- 各子项目 `README.md` 中的「验收检查」逐项可执行
- 培训材料 `big_assignment.md` 验收点可被学员自检

详见 `training/overall_plan.md` 第 10 节「验收检查清单」。

---

## 九、版本控制

- **远程仓库**：https://gitee.com/hephec321/agent_px.git
- **主分支**：`master`
- **提交规范**：遵循 Conventional Commits 中文风格
  - `feat:` 新功能
  - `docs:` 文档变更
  - `fix:` Bug 修复
  - `refactor:` 重构
- **.gitignore**：覆盖 Python / Node.js / IDE / 日志 / 临时文件 / 个人简历隐私文件

---

## 十、外部参考文档

以下核心外部链接在 2026-06-25 经网络可达性验证：

| 链接 | 用途 |
| --- | --- |
| https://python.langchain.com/docs/ | LangChain 官方文档 |
| https://langchain-ai.github.io/langgraph/ | LangGraph 官方文档 |
| https://modelcontextprotocol.io/ | MCP 协议规范 |
| https://milvus.io/docs | Milvus 官方文档 |
| https://help.aliyun.com/zh/dashscope/ | DashScope 文档 |
| https://fastapi.tiangolo.com/ | FastAPI 官方文档 |
| https://vuejs.org/ | Vue 3 官方文档 |

---

**文档版本**：v1.0
**编写日期**：2026-06-25
**适用项目**：本仓库 `agent_px_zkd` 工作目录下的全部子项目与培训材料