内容
# 📋 企业智能协作门户 — AI 企业智能协作门户
> **系统架构文档 — 由源代码自动生成**
> 创建日期：2026-04-26 | 版本：v3.0（企业版）
---
## 1. 系统概述与可视化流程
**这是什么系统？**
这是一个 **AI 企业智能协作门户**，旨在使用智能工作流自动处理高风险业务流程（会计和人力资源）。它通过 **模型上下文协议（MCP）** 将确定性规则引擎与大型语言模型（LLM）相结合。
### 🔄 系统架构流程
| # | 模块 | 核心逻辑 | 部署 |
|---|--------|------------|------------|
| 1 | **MISA 会计代理** | 2 阶段管道（规则引擎 + LLM） | 端口 8000 |
| 2 | **人力资源工资代理** | SOTA 数学分割 + AI 原因标签 | 端口 8001 |
| 3 | **企业门户** | 统一 UI 仪表盘与监控 | 端口 8501 |
## 🛠 技术栈
该项目采用了最先进的 AI 技术栈，以确保高性能、可扩展性和确定性推理。
- **智能编排**：[LangGraph](https://github.com/langchain-ai/langgraph)（确定性 DAG 与循环工作流）
- **LLM 通信**：[模型上下文协议（MCP）](https://modelcontextprotocol.io/)（Anthropic 工具/资源抽象标准）
- **AI 模型**：Google Gemini 1.5 Pro/Flash（主要），OpenAI GPT-4o-mini（备用），Qwen 2.5 7B（本地/Colab）
- **后端框架**：FastAPI（异步高性能 API）
- **前端界面**：Streamlit（企业仪表盘，Glassmorphism UI）
- **数据工程**：Pandas 与 OpenPyXL（复杂 Excel 转换逻辑）
- **数据库与持久化**：PostgreSQL（Supabase/Docker）与 Cachetools（TTL 缓存）
- **基础设施**：Docker 与 Docker Compose，GitHub Actions（CI/CD 自动同步）
---
## 2. 业务模块（思维导图）
以下图表展示了每个专用代理的内部推理和工具选择逻辑。
### 🏢 MISA 会计代理
- **目标**：将 Workday 日记条目重新分类为 MISA SME 格式。
- **策略**：使用 **子组分割** 按供应商键减少 AI token 成本 90%。
### 🕒 人力资源工资代理
- **目标**：根据越南劳动法计算加班费。
- **策略**：使用 **交集算法** 与 MCP 日历集成。
---
## 3. 项目结构
```
MCP-business-process-agent-/
│
├── start.py # 🚀 入口点 — 协调所有 3 个服务
├── PROJECT_EVALUATION_REPORT.md # 📊 系统性能与指标（英文）
├── run_and_setup.md # 🚀 完整设置与操作指南（英文）
│
├── misa_agent_project/ # === 模块 1：MISA 会计 ===
│ └── backend/
│ ├── main_api.py # FastAPI：阶段 1（规则）与阶段 2（LLM）
│ └── src/graph/builder.py # LangGraph DAG
│
├── hr_payroll_project/ # === 模块 2：人力资源工资 ===
│ └── backend/
│ ├── main_api.py # FastAPI：/api/v2/process-payroll
│ └── src/tools/time_tools.py # SOTA 小时分割逻辑
│
├── mcp_servers/ # === MCP 服务器（微服务） ===
│ ├── misa_mcp_server.py # COA 数据库与系统提示
│ └── calendar_mcp.py # 越南假期上下文
│
├── frontend/ # === 统一 UI 门户 ===
│ └── app.py # Streamlit 多阶段仪表盘
│
└── test/ # === 验证套件 ===
└── ab_test_runner.py # 性能比较框架
```
---
## 4. 性能与成熟度（关键指标）
该系统已针对真实数据集进行了严格测试。有关完整的技术分解，请参见 [PROJECT_EVALUATION_REPORT.md](PROJECT_EVALUATION_REPORT.md)。
| 指标 | MISA 代理 | 工资代理 | 测量 |
| :--- | :--- | :--- | :--- |
| **成功率** | **96.0%** | **100%** | 任务完成，无错误 |
| **效率提升** | **65x** | **SOTA** | 与手动数据录入相比 |
| **可靠性** | **100%** | **100%** | 100 次压力测试请求中无失败 |
| **上下文使用** | **100%** | **100%** | 准确的 MCP 资源检索 |
---
## 5. 快速启动与操作
单个命令即可启动整个生态系统。有关详细的先决条件，请参见 [run_and_setup.md](run_and_setup.md)。
### ⚡ 安装
```bash
conda create -n mcp-business python=3.11 -y
conda activate mcp-business
pip install -r requirements.txt
cp .env.example .env # 填写您的 API 密钥
docker compose up -d # 启动数据库
```
### ⚡ 执行
```bash
python start.py
```
- **访问 UI**：http://localhost:8501
- **API 健康检查**：http://localhost:8000/health
---
## 6. 高级功能
- **多 LLM 备用**：从本地/Colab 模型自动重定向到云 API（Gemini/OpenAI），如果延迟或可用性阈值被突破。
- **子代理路由**：使用 `classifier_mcp` 的智能传入文件分类，确保数据发送到正确的专用管道。
- **确定性数学引擎**：工资计算 100% 数学，确保遵守劳动法规，同时仅使用 AI 进行定性原因标签。
---
*文档版本 3.0 | 由 AI 系统架构师维护 | 2026-04-26*
