内容
# BizInsight 智能体：多智能体商业智能系统
> 一个自动化的多智能体系统，用于商业数据分析、洞察生成和报告创建 — 展示了 **多智能体系统**、**MCP（模型上下文协议）** 和 **智能体技能**，来自为期 5 天的 AI 智能体强化课程，合作方为谷歌。
---
## 🏆 Kaggle 杯赛项目 — 商业赛道智能体
### 问题陈述
中小型企业会产生大量的运营数据（销售、支出、库存），但缺乏资源雇佣专职数据分析师。手动分析速度慢、不一致且经常错过关键模式。该项目构建了一个**自主多智能体系统**，该系统可以吸收商业数据，进行结构化分析，生成可行的洞察，并通过自然语言交互生成专业报告。
### 关键概念演示
| 课程概念 | 如何演示 |
|---|---|
| **多智能体系统** （第 1 天） | 4 个专门的 CrewAI 智能体（协调器、数据分析师、洞察生成器、报告编写器）通过结构化委托进行协作 |
| **MCP 服务器** （第 2 天） | 2 个自定义 MCP 服务器（数据访问 + 图表生成）采用发现 → 配置 → 连接模式 |
| **智能体技能** （第 3 天） | 3 个 SKILL.md 文件，采用渐进式披露（元数据 → 正文 → 脚本/引用） |
| **上下文工程** （第 1 天） | AGENTS.md 提供项目级上下文；按需加载技能以防止上下文腐烂 |
| **安全** （第 4 天） | 输入验证、沙盒代码执行、MCP 服务器上的出口治理 |
| **规范驱动开发** （第 5 天） | BDD 规范（Gherkin）、策略服务器（零信任）、上下文卫生（个人识别信息屏蔽） |
---
## 🏗️ 架构概述
```
┌──────────────────────────────────────────────────┐
│ 用户（自然语言） │
│ "分析第二季度销售数据并查找..." │
└────────────────────┬─────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────┐
│ 协调器智能体（路由器） │
│ 路由请求，协调子智能体 │
└──┬──────────────┬───────────────┬───────────────┘
│ │ │
▼ ▼ ▼
┌─────────┐ ┌──────────┐ ┌──────────────┐
│ 数据 │ │ 洞察 │ │ 报告 │
│ 分析师 │ │ 生成器│ │ 编写者 │
│ 智能体 │ │ 智能体 │ │ 智能体 │
└────┬────┘ └────┬─────┘ └──────┬───────┘
│ │ │
│ ┌──────┴──────┐ │
│ │ 智能体 │ │
▼ │ 技能 │ ▼
┌────────────┐ │ （SKILL.md） │ ┌────────────┐
│ MCP │ │ │ │ MCP │
│ 数据 │ ◄───────────┘ │ 图表 │
│ 服务器 │ │ 服务器 │
│ │ │ │
│ • CSV 读取 │ │ • 条形图 │
│ • 过滤 │ │ • 线形图 │
│ • 聚合│ │ • 热力图 │
└────────────┘ └────────────┘
```
### 智能体角色
1. **协调器智能体**：接收用户请求，将请求分解为任务，委派给专业智能体，并综合结果。实现第 1 天的“协调器”模式。
2. **数据分析师智能体**：通过 MCP 连接到数据源，进行统计分析（聚合、趋势检测、异常识别）。使用 `data-analysis` 技能。
3. **洞察生成器智能体**：使用框架（SWOT、帕累托、增长模式）将原始分析转换为与业务相关的洞察。使用 `insight-generation` 技能。
4. **报告编写器智能体**：生成带有嵌入式图表（通过 MCP 图表服务器）的结构化 Markdown 报告。使用 `report-writing` 技能。
### MCP 服务器
1. **数据服务器** (`mcp_servers/data_server/`)：提供读取 CSV 文件、过滤行、计算聚合和检测异常的工具。使用 stdio 传输。
2. **图表服务器** (`mcp_servers/charts_server/`)：提供生成 matplotlib/seaborn 图表（条形图、线形图、饼图、热力图）和保存为文件的工具。使用 stdio 传输。
### 智能体技能（SKILL.md）
1. **数据分析** (`skills/data-analysis/`)：定义如何进行商业数据分析 — 列概况、异常检测使用 IQR、趋势分析、相关性检查。包括用于统计计算的 Python 脚本。
2. **洞察生成** (`skills/insight-generation/`)：定义商业洞察框架 — 什么样的洞察是好的，帕累托分析，同比增长模式，异常叙述。包括参考文档。
3. **报告编写** (`skills/report-writing/`)：定义报告结构 — 执行摘要、方法论、发现、建议。包括 Jinja2 模板和格式化脚本。
---
## 🚀 快速开始
### 前置条件
- Python 3.10+
- Google Gemini API 密钥（或 OpenAI/Anthropic）
### 安装
```bash
# 克隆仓库
git clone https://github.com/yourusername/bizinsight-agent.git
cd bizinsight-agent
# 创建虚拟环境
python -m venv venv
source venv/bin/activate # Linux/Mac
# venv\Scripts\activate # Windows
# 安装依赖
pip install -r requirements.txt
# 配置 API 密钥
cp .env.example .env
# 编辑 .env 并添加您的 API 密钥
```
### 运行演示
```bash
# 使用样本数据运行主管道
python main.py --data data/sample_business_data.csv --query "分析销售趋势并找出表现最佳的类别"
# 运行自定义选项
python main.py --data data/sample_business_data.csv --query "查找第二季度费用异常" --output output/
```
### 手动运行 MCP 服务器（用于调试）
```bash
# 启动数据 MCP 服务器
python -m mcp_servers.data_server.server
# 在另一个终端中，使用 MCP 检查器进行验证
npx @modelcontextprotocol/inspector python -m mcp_servers.data_server.server
```
---
## 📁 项目结构
```
bizinsight-agent/
├── AGENTS.md # 项目级上下文（第 1 天：上下文工程）
├── README.md # 此文件
├── requirements.txt
├── .env.example
├── main.py # 入口点 - 协调整个管道
├── specs/ # BDD 规范（第 5 天：SDD）
│ └── analysis_pipeline.feature # Gherkin 场景（Given/When/Then）
├── policy_server.py # 第 5 天：策略服务器（零信任防护栏）
├── context_resolver.py # 第 5 天：上下文卫生（个人识别信息屏蔽，提示净化）
├── policies.yaml # 第 5 天：策略配置（角色/环境规则）
│
├── crew/ # CrewAI 多智能体系统
│ ├── config/
│ │ ├── agents.yaml # 智能体定义（角色、目标、背景故事）
│ │ └── tasks.yaml # 任务定义（每个智能体执行的操作）
│ ├── agents/ # 智能体实现
│ │ ├── orchestrator.py
│ │ ├── data_analyst.py
│ │ ├── insight_generator.py
│ │ └── report_writer.py
│ └── tasks/ # 任务实现
│ ├── analyze_data.py
│ ├── generate_insights.py
│ └── write_report.py
│
├── mcp_servers/ # MCP 服务器（第 2 天：互操作性）
│ ├── data_server/
│ │ ├── server.py # 数据访问的 MCP 服务器
│ │ └── SKILL.md # 服务器的技能文档
│ └── charts_server/
│ ├── server.py # 图表生成的 MCP 服务器
│ └── SKILL.md
│
├── skills/ # 智能体技能（第 3 天：技能）
│ ├── data-analysis/
│ │ ├── SKILL.md # 分析方法论
│ │ ├── scripts/
│ │ │ └── analyze.py # 统计分析函数
│ │ └── references/
│ │ └── methods.md # 统计方法参考
│ ├── insight-generation/
│ │ ├── SKILL.md # 洞察框架
│ │ └── references/
│ │ └── frameworks.md # 商业分析框架
│ └── report-writing/
│ ├── SKILL.md # 报告结构指南
│ ├── scripts/
│ │ └── format_report.py # 报告格式化实用程序
│ └── assets/
│ └── report_template.md
│
├── data/
│ └── sample_business_data.csv # 演示用的样本数据集
│
├── notebooks/
│ └── demo.ipynb # 交互式 Kaggle 笔记本
│
├── output/ # 生成的报告和图表
│
└── tests/
├── test_mcp_servers.py
├── test_skills.py
├── test_crew.py
└── test_day5.py
```
---
## 📖 概念映射到课程内容
### 第 1 天：具有 Vibe 编码的新 SDLC
| 概念 | 实现 |
|---|---|
| **智能工程** | 项目遵循规范化端 — 正式规范（AGENTS.md）、自动化测试、结构化智能体定义 |
| **工具工程** | MCP 服务器 + 技能形成围绕 LLM 的“工具链” — 工具、内存（上下文）和编排 |
| **上下文工程** | AGENTS.md 提供项目级上下文；技能使用渐进式披露按需加载知识，防止上下文腐烂 |
| **协调器模式** | 协调器智能体异步将任务委派给专业智能体，然后综合结果 |
| **AGENTS.md** | 包含项目约定、编码标准和技能目录 |
### 第 2 天：智能体工具与互操作性
| 概念 | 实现 |
|---|---|
| **MCP 发现** | 数据和图表服务器使用适当的工具模式注册 |
| **MCP 配置** | API 密钥的环境变量，限定项目范围的文件路径 |
| **MCP 连接** | 本地执行使用 stdio 传输；工具通过握手验证 |
| **NxM 问题解决** | 两个智能体连接到同一个 MCP 服务器 — O(N+M) 而不是 O(N*M) |
| **MCP 最佳实践** | 没有硬编码凭证，只读数据访问，限定项目目录范围 |
### 第 3 天：智能体技能
| 概念 | 实现 |
|---|---|
| **SKILL.md 格式** | YAML 前置信息（名称、描述）+ Markdown 指令 |
| **渐进式披露** | 3 个级别：元数据始终加载 → 触发时加载正文 → 按需加载脚本/引用 |
| **技能 vs MCP** | 技能提供“方法论”（如何分析），MCP 提供“访问”（数据访问） |
| **DAG 编排** | 任务流在一个有向无环图中：分析 → 生成洞察 → 编写报告 |
| **评估覆盖率** | 测试验证智能体触发、输出质量和工具轨迹 |
### 第 4 天：安全性和评估
| 概念 | 实现 |
|---|---|
| **沙盒** | 数据服务器将文件访问限制在 `data/` 目录内 |
| **出口治理** | MCP 服务器没有出站网络访问；数据保留在本地 |
| **输入验证** | 所有 MCP 工具输入在执行前都会被验证 |
| **零环境权限** | 每个工具都有最小的所需权限 |
| **可观察性** | 所有智能体操作和工具调用的结构化日志记录 |
### 第 5 天：规范驱动的生产级开发
| 概念 | 实现 |
|---|---|
| **规范驱动开发（SDD）** | `specs/` 中的 BDD 规范使用 Gherkin（Given/When/Then）— 规范是事实的源头 |
| **混合 Markdown + YAML** | SKILL.md 使用 YAML 前置信息进行元数据，使用 Markdown 进行方法论（按 SkCC 研究） |
| **策略服务器** | `policy_server.py` 实现结构化门控 — 基于 YAML 的角色/环境权限 |
| **零信任开发** | 每个工具调用在执行前都会通过策略服务器；没有环境权限 |
| **上下文卫生** | `context_resolver.py` — 个人识别信息屏蔽、`[[VARIABLE]]` 占位符解析、提示净化 |
| **AI 生成的测试覆盖率** | 48+ 个测试覆盖所有 5 天的概念；基于评估的质量门控 |
| **指令存储位置** | 4 个层级：聊天 → `specs/` → `skills/`（SKILL.md）→ `AGENTS.md`（全局） |
---
## 🧪 测试
```bash
# 运行所有测试
pytest tests/ -v
# 测试 MCP 服务器
pytest tests/test_mcp_servers.py -v
# 测试技能加载
pytest tests/test_skills.py -v
# 测试智能体执行
pytest tests/test_crew.py -v
```
---
## 📊 样本输出
当您使用样本数据集运行演示时，系统会生成：
1. **统计分析** — 列概况、趋势检测、异常标志
2. **商业洞察** — 分类发现与商业影响评级
3. **可视化图表** — 趋势线、类别分解、热力图（保存为 PNG）
4. **最终报告** — 结构化 Markdown 文档，包含执行摘要、方法论、发现和建议
---
## 🛠️ 扩展项目
- **添加新的 MCP 服务器**：连接到 Google Sheets、BigQuery 或 Salesforce
- **添加新的技能**：创建特定领域的技能（财务分析、库存优化）
- **添加新的智能体**：扩展为预测智能体或警报智能体
- **部署**：容器化 Docker，部署在 GCP Cloud Run
---
## 📝 许可证
MIT 许可证 — 请随意使用和修改以适应您的项目。
---
## 🙏 致谢
作为 **5 天 AI 智能体强化课程与谷歌**（2026 年 7 月）的杯赛项目构建。
引用课程材料：
- 第 1 天：具有 Vibe 编码的新 SDLC
- 第 2 天：智能体工具与互操作性
- 第 3 天：智能体技能
- 第 4 天：Vibe 编码智能体安全性和评估
- 第 5 天：具有 Vibe 编码的生产级规范驱动开发
