项目简介
ProcurePilot 是一个面向企业采购场景的智能助手,用来完成采购查询、供应商比价、分析报告和采购订单操作。
它的核心设计是:不让大模型直接碰数据库。
- Python 业务层负责确定性的规则和数据,是唯一权威来源
- MCP 把业务能力包装成受控工具,每次调用都绑定调用者身份和权限
- Agent 只负责理解需求、规划步骤和编排工具
- 订单写操作必须经过人工审批(HITL),审批授权一次性、限时,并且绑定具体参数
项目仍在开发中:M0–M10 的源码和非 live 自动化测试已完成,OpenSandbox 真实容器验收和生产认证还没有做。
核心特性
- 🧭 主 / 子 Agent 分工:主 Agent 只做路由、委派和汇总;分析类请求交给
procurement-analyst,下单、改单、撤单交给procurement-order - 🔍 证据优先的比价分析:每个推荐候选都必须能追溯到真实的
supplier_id和quotation_id,并与报价查询结果逐字段核对,查不到证据就返回明确的失败,而不是编造结论 - ✋ 人在回路的下单流程:缺字段时中断,请用户补充;关键写操作中断,等人审批;审批通过后才真正执行
- 🔐 最小权限工具:分析 Agent 只拿到 6 个只读查询工具,订单 Agent 拿到 8 个订单工具;身份、角色、
trace_id从可信上下文注入,不由模型传参 - 📦 沙箱隔离执行:每个请求都有独立的 OpenSandbox,Agent 的文件、命令和 Skill 脚本都在沙箱里跑,不回退到宿主机
- 💾 状态分库持久化:业务库和 Agent 状态库分开;Checkpoint、Store、恢复元数据和脱敏展示历史各用各的表
- 🌊 流式交互:FastAPI + SSE 只输出 7 类事件(
token、tool_start、tool_args、tool_result、tool_end、interrupt、done),中断后可以通过 HTTP 恢复 - 🛑 运行护栏:单次运行默认最多 50 次模型调用、200 次工具调用,超限就停止
请求处理流程
graph TD
U([用户 / Vue 工作台]) -->|POST /api/chat/stream| API[FastAPI<br/>可信身份 + SSE]
API --> CTX[ProcurementContext<br/>用户 / 租户 / 角色]
CTX --> MAIN[主 Agent<br/>路由 · 委派 · 汇总]
MAIN -->|分析 / 比价 / 报告| ANA[procurement-analyst<br/>6 个只读工具]
MAIN -->|下单 / 改单 / 撤单| ORD[procurement-order<br/>8 个订单工具]
ANA --> MCP[MCP Server<br/>受控业务工具]
ORD --> MCP
MCP --> BIZ[Python 业务层<br/>规则 + Repository]
BIZ --> DB[(MySQL 业务库)]
ANA --> SB[OpenSandbox<br/>图表 · 报告 · Skill]
ORD -->|缺字段| INT1{{interrupt:补充信息}}
ORD -->|写操作| INT2{{interrupt:人工审批}}
INT1 -->|POST /resume| ORD
INT2 -->|批准后执行| ORD
MAIN -.-> CK[(Agent 状态库<br/>Checkpoint / Store / 历史)]
style MAIN fill:#f0e1ff
style ANA fill:#fff4e1
style ORD fill:#e1f5ff
style INT1 fill:#ffe8e8
style INT2 fill:#ffe8e8系统架构
从上到下分为五层:
- Vue 3 工作台:会话回放、流式聊天、工具调用过程展示,以及补充信息卡片和审批卡片
- FastAPI / SSE 接口:流式聊天、中断恢复、会话历史查询和删除
- Agent 编排:DeepAgents 主 Agent + 两个子 Agent,挂载上下文注入、调用次数限制等中间件
- MCP 工具层:供应商、物料、库存、订单四组工具,统一做身份绑定和错误映射
- 业务与基础设施:纯 Python 领域模型和服务、SQLAlchemy + MySQL 持久化、OpenSandbox 执行环境
技术栈
| 类别 | 技术 |
|---|---|
| Agent 编排 | DeepAgents 0.4.12、LangGraph(主 / 子 Agent、中间件、interrupt) |
| 工具协议 | MCP(Streamable HTTP) |
| 业务层 | Python 3.11、Pydantic、领域模型 + Repository / UnitOfWork |
| 持久化 | MySQL、SQLAlchemy(async)、Alembic、langgraph-checkpoint-mysql |
| 执行隔离 | OpenSandbox(镜像锁定 sha256 摘要,非 root) |
| 后端 API | FastAPI + SSE |
| 前端 | Vue 3 + TypeScript + Pinia + Vite |
| 质量 | pytest(200+ 用例)、ruff、mypy、Vitest |
运行方式
项目需要 Python 3.11、MySQL(业务库和 Agent 状态库分开),真实沙箱还需要 Docker 和 OpenSandbox Server。完整的安装和启动步骤见 GitHub 仓库的 README。