# guage-erp-agent **Repository Path**: yangdechao_admin/guage-erp-agent ## Basic Information - **Project Name**: guage-erp-agent - **Description**: 以 DeepAgent + LangGraph + MCP 协议为核心的摩托车零部件采购智能助手。采用方案 C（混合式）组织：一个主仓 guage-erp-agent 收拢整套 ERP-AI 系统，独立拆出通用工具仓 guage-mcp-datetime-tool，为 Gitee 开源做好准备。 - **Primary Language**: Unknown - **License**: Not specified - **Default Branch**: master - **Homepage**: None - **GVP Project**: No ## Statistics - **Stars**: 0 - **Forks**: 0 - **Created**: 2026-09-30 - **Last Updated**: 2026-10-02 ## Categories & Tags **Categories**: Uncategorized **Tags**: None ## README # guage-erp-agent — ERP 智能采购 AI Agent 与 MCP 工具生态 > 以 **DeepAgent + LangGraph + MCP 协议** 为核心的摩托车零部件采购智能助手。 > 采用 **方案 C（混合式）** 组织：一个主仓 `guage-erp-agent` 收拢整套 ERP-AI 系统，独立拆出通用工具仓 `guage-mcp-datetime-tool`，为 Gitee 开源做好准备。 --- ## 一、仓库定位本仓库是一套**可本地一键部署、全 Docker 化**的 ERP-AI 智能体系统，包含 4 层能力： | 层次 | 模块 | 说明 | |------|------|------| | **对话层** | `guage-chat-web` + `guage-chat-server` | 用户对话前端 + 后端 API（SSE 流式 + HITL） | | **Agent 核心** | `src/agent` | DeepAgent + LangGraph 状态机、9 中间件、32 工具 | | **ERP 桥接** | `guage-erp-mcp-server` + `guage-erp-mock-server` | MCP 网关（23 个 ERP 工具）对接本地模拟 ERP | | **调试平台** | `guage-mcp-inspector-web` + `guage-mcp-inspector-server` | MCP 可视化调试（支持 Stdio/SSE/HTTP，配置持久化） | **独立仓库**：`guage-mcp-datetime-tool`（通用时间工具 MCP，可单独开源复用）。 --- ## 二、系统架构 ```mermaid flowchart TB subgraph 主仓["guage-erp-agent（主仓）"] subgraph UI["对话前端 guage-chat-web (:3000)"] ChatUI["Next.js 对话界面
SSE 流式 + HITL 审批"] end subgraph API["后端 guage-chat-server (:8000)"] Fast["FastAPI
chat / history / agent_loader"] Store["MongoDB 持久化
Saver + Store"] end subgraph Agent["Agent 核心 src/agent"] Core["DeepAgent + LangGraph
9 中间件 · 32 工具"] end subgraph MCP["ERP MCP 网关 guage-erp-mcp-server (:9000)"] Mcp["FastMCP + SSE
suppliers(5) parts(5) orders(7) inventory(6)"] end subgraph ERP["本地模拟 ERP guage-erp-mock-server (:8081)"] Spring["Spring Boot + Swagger
MySQL(erp)"] end subgraph Ins["调试平台"] InsW["inspector-web (:3001)"] InsS["inspector-server (:8010)
配置持久化 MySQL(guage_mcp)"] end end subgraph 独立仓["guage-mcp-datetime-tool（独立仓）"] DT["时间工具 MCP (:9200)
get_current_time / convert_timezone / ... 共 8 工具"] end ChatUI -->|HTTP/SSE| Fast Fast --> Core Core -->|MCP| Mcp Mcp -->|HTTP REST| Spring Fast --> Store InsW --> InsS InsS -->|Stdio/SSE/HTTP| Mcp InsS --> DT ``` --- ## 三、目录结构（方案 C） ``` guage-erp-agent/ # 主仓 ├── guage-chat-web/ # 对话主前端 ├── guage-chat-server/ # 对话后端 API（原 src/chat_server） ├── guage-erp-mcp-server/ # ERP MCP 网关（原 src/erp_mcp_server） ├── guage-mcp-inspector-web/ # MCP 可视化调试前端 ├── guage-mcp-inspector-server/ # MCP 调试后端，配置持久化 ├── guage-erp-mock-server/ # 本地模拟 ERP（Spring Boot） ├── src/ # 共享核心 │ ├── agent/ # Agent 核心（backends/middlewares/tools/subagents/memory） │ ├── skills/ # 技能文件 │ └── download/ # 生成文件下载目录 ├── docker-compose.yml # 主仓服务编排（MCP + 后端 + 模拟 ERP） ├── Dockerfile # Python 后端镜像（guage-erp-agent） ├── .env / .env.example # 环境变量 ├── README.md # 本文件 └── docs/ # 部署文档 ``` --- ## 四、模块速览 | 模块 | 技术栈 | 端口 | 职责 | |------|--------|------|------| | `guage-chat-web` | Next.js + React + Tailwind | 3000 | 对话界面、SSE 流式、HITL 审批、历史管理 | | `guage-chat-server` | FastAPI + Uvicorn | 8000 | SSE 流式 API、会话 CRUD、Agent 装载 | | `guage-erp-mcp-server` | FastMCP + SSE | 9000 | 23 个 ERP 工具（供应商/零部件/订单/库存） | | `guage-erp-mock-server` | Spring Boot + Swagger + MySQL | 8081 | 本地模拟 ERP，替代远程 ERP 供 MCP 调用 | | `guage-mcp-inspector-web` | Next.js（薄代理） | 3001 | MCP 调试界面，连接 Stdio/SSE/HTTP | | `guage-mcp-inspector-server` | FastAPI + MySQL | 8010 | MCP 配置持久化、测试执行 | | `guage-mcp-datetime-tool`（独立仓） | Python + MCP SDK | 9200 | 8 个时间/时区工具，独立开源 | --- ## 五、Docker 一键部署（推荐） ### 1. 准备外部基础组件（一次即可） ```bash # 创建共享网络 docker network create erp-net # MongoDB（对话持久化） docker run -d --name erp-mongodb --network erp-net -p 27017:27017 mongo:8.0 # MySQL（模拟 ERP + 调试平台持久化） docker run -d --name mysql-erp --network erp-net -p 3306:3306 \ -e MYSQL_ROOT_PASSWORD=root -e MYSQL_DATABASE=erp \ mysql:8.0 # 沙箱容器（代码执行） docker run -d --name erp-sandbox -w /workspace python:3.11-slim sleep infinity # 初始化 MySQL 业务库 docker exec mysql-erp mysql -uroot -proot \ -e "CREATE DATABASE IF NOT EXISTS erp CHARACTER SET utf8mb4;" ``` ### 2. 主仓编排 ```bash cd guage-erp-agent docker compose up -d --build ``` compose 会拉起 3 个服务： - `guage-erp-mcp-server`（:9000） - `guage-chat-server`（:8000） - `guage-erp-mock-server`（:8081） ### 3. 调试平台与时间工具（独立容器） ```bash # inspector 前端 docker run -d --name guage-mcp-inspector-web --network erp-net -p 3001:3001 guage-mcp-inspector-web:latest # inspector 后端 docker run -d --name guage-mcp-inspector-server --network erp-net -p 8010:8000 \ -e MYSQL_HOST=mysql-erp -e MYSQL_DATABASE=guage_mcp guage-mcp-inspector-server:latest # 时间工具（独立仓） docker run -d --name guage-mcp-datetime-tool --network erp-net -p 9200:9200 guage-mcp-datetime-tool:latest ``` > 各子模块的 Dockerfile 见对应目录；构建上下文与网络配置详见 `docs/`。 --- ## 六、本地开发启动 ```bash # 1. 准备：确保 MongoDB / MySQL / Docker 沙箱已就绪（见上） # 2. MCP Server（:9000） cd guage-erp-mcp-server python -m erp_mcp_server.server_main # 3. 后端 API（:8000） cd ..\guage-chat-server $env:PYTHONPATH="D:\git-workspace\guage-erp-agent" # 需能 import src.agent python -m chat_server.web_main # 4. 对话前端（:3000） cd guage-chat-web && npm install && npm run dev # 5. 调试前端（:3001） cd guage-mcp-inspector-web && npm install && npm run dev ``` > **启动顺序**：MongoDB → 沙箱 → MCP(:9000) → 后端(:8000) → 前端(:3000)。MCP 必须先于后端，因为 Agent 初始化要连接 MCP 加载 ERP 工具。 --- ## 七、环境变量（.env） | 变量 | 默认值 | 说明 | |------|--------|------| | `LLM_MODEL` | `deepseek-chat` | 模型（需支持工具调用） | | `LLM_BASE_URL` | `https://api.deepseek.com` | LLM 网关 | | `LLM_API_KEY` | `sk-...` | LLM API Key | | `MONGODB_URI` | `mongodb://localhost:27017` | 对话持久化 | | `MONGODB_DB_NAME` | `erp_agent` | 会话库名 | | `ERP_BASE_URL` | `http://guage-erp-mock-server:8081` | 容器内服务名；本地用 `http://localhost:8081` | | `MCP_SERVER_URL` | `http://localhost:9000` | MCP 网关地址 | | `SANDBOX_IMAGE` | `python:3.11-slim` | 沙箱镜像 | --- ## 八、开源说明（Gitee）本仓库采用 **方案 C 混合式** 组织，便于开源维护： - **主仓** `guage-erp-agent`：整套 ERP-AI 系统，含 6 个子模块 + 主仓编排。 - **独立仓** `guage-mcp-datetime-tool`：通用时间工具，与 ERP 解耦，单独开源复用。 - MCP 调试平台（inspector-web + inspector-server）打磨成熟后，也可再拆独立仓。 > 子模块间通过 Docker 网络（`erp-net`）与端口解耦，均可独立构建、独立演进。 --- ## 九、API 端点（对话后端） | 方法 | 路径 | 说明 | |------|------|------| | POST | `/api/chat/stream` | SSE 流式对话 | | POST | `/api/chat/{thread_id}/resume` | 中断恢复 | | GET | `/api/chat/{thread_id}/state` | 中断状态 | | GET | `/api/chat/{thread_id}/history` | 消息历史 | | GET | `/api/history/{user_id}` | 会话列表 | | DELETE | `/api/history/{thread_id}` | 删除会话 | | GET | `/api/download/{filename}` | 下载生成文件 | | GET | `/health` | 健康检查 | --- ## 十、相关文档 | 文档 | 说明 | |------|------| | [docs/guage-erp-agent-部署手册.md](docs/guage-erp-agent-部署手册.md) | 本地启动 + Docker 部署完整手册 | | [guage-chat-web/README.md](guage-chat-web/README.md) | 对话前端 | | [guage-mcp-inspector-server/README.md](guage-mcp-inspector-server/README.md) | MCP 调试后端 | | [guage-mcp-inspector-web/README.md](guage-mcp-inspector-web/README.md) | MCP 调试前端 | | [guage-erp-mock-server/README.md](guage-erp-mock-server/README.md) | 本地模拟 ERP |