🛡️ Aegis —— 企业级 AI 智能体平台
多格式文档 RAG · 多智能体协作 · MCP 工具调用 · 事实核查自修正 · HITL 人工审批
Aegis（/ˈiːdʒɪs/，神盾）是一个开箱即用的企业级 AI 智能体应用，围绕「可信回答」与「安全执行」两条主线设计：
- 回答侧：多智能体（Planner → Retriever → Auditor → Answerer）分工协作，每个答案都要经过 Auditor 事实核查，证据不足时如实说明、绝不编造；
- 执行侧：工具调用基于 MCP（Model Context Protocol） 标准化协议，配合**最小权限白名单 + 敏感操作人工审批（HITL）**实现安全隔离。
┌──────────────────────────────────────────────┐
│ 用户 / FastAPI / CLI │
└──────────────────────┬───────────────────────┘
│ 提问
┌──────────────────────▼───────────────────────┐
│ Orchestrator（多智能体编排器） │
│ │
│ ① Planner 规划：拆解子问题 + 工具计划 │
│ ② Retriever 检索：混合检索 + MCP 工具执行 │
│ ③ Answerer 起草：基于证据、带引用 [C1][C2] │
│ ④ Auditor 核查：逐条声明 vs 证据 │
│ └─ revise ─► 带反馈重检/重答（≤3 轮） │
└──────┬──────────────────────────────┬────────┘
│ 语义检索 │ MCP 协议
┌────────────▼───────────┐ ┌───────────▼────────────┐
│ 知识库（RAG） │ │ MCP 工具服务器 │
│ PDF/DOCX/XLSX/PPTX/TXT│ │ calculator / kb_search │
│ → 解析 → 切块 → 向量化 │ │ doc_stats / … │
│ → Chroma + BM25 混合 │ │ 🔒 敏感工具 → HITL 审批 │
└────────────────────────┘ └────────────────────────┘
✨ 核心能力
| 需求 | 实现 |
|---|---|
| 多格式文档知识入库与语义检索 | PDF / Word / Excel / PPT / TXT 解析（含表格、幻灯片、页码定位）；递归切块；向量 + BM25 混合检索（RRF 融合）；本地嵌入免 API Key |
| 多智能体分工协作 | Planner（规划）→ Retriever（检索+工具）→ Answerer（带引用起草）→ Auditor（核查），审计不通过自动带反馈重新检索/作答，最多 N 轮 |
| 基于 MCP 的工具调用标准化与安全隔离 | 基于官方 mcp SDK 实现 MCP 服务器（支持 in-process 与标准 stdio 两种接入）；JSON Schema 参数校验；按智能体最小权限白名单；AST 白名单计算器杜绝注入 |
| Auditor 事实核查与自我修正 | 逐条核对声明 vs 证据（supported/unsupported/contradicted），输出可信度评分与修订意见；证据不足时明确告知、拒绝编造，可自主补充检索 |
| HITL 人工干预 | 敏感工具（发邮件/导出/删除）触发审批单挂起，支持 approve/reject 后恢复执行；三种模式：interactive / auto_approve / auto_deny（默认拒绝，fail-safe） |
🚀 快速开始
# 1. 安装（Python 3.10+）
cd enterprise-rag-agent
pip install -e .
# 2.（可选）配置 LLM —— 默认离线模式无需配置；接入真实模型见下文
cp .env.example .env # 填入 OPENAI 兼容的 API Key（OpenAI/DeepSeek/Ollama 等）
# 3. 一键端到端演示（自动生成 5 种格式样例文档 → 入库 → 问答 → 审批，全部自校验）
aegis demo
# 4. 导入你自己的文档
aegis ingest ./your_docs
# 5. 提问（多智能体流水线）
aegis ask "一线城市出差住宿报销上限是多少？"
# 6. 启动 HTTP 服务（Swagger: http://127.0.0.1:8000/docs）
aegis serve
无需任何 API Key 即可跑通全流程：默认嵌入模型用本地 ONNX（BAAI/bge-small-zh-v1.5，首次自动下载约 95MB），LLM 用内置确定性后端完成端到端验证；接入真实模型只需在 .env 中配置。
接入真实 LLM
支持任意 OpenAI 兼容协议端点：
# OpenAI / DeepSeek / 通义 / 本地 vLLM
AEGIS_LLM_PROVIDER=openai
AEGIS_LLM_BASE_URL=https://api.deepseek.com/v1
AEGIS_LLM_API_KEY=sk-xxxx
AEGIS_LLM_MODEL=deepseek-chat
# 或本地 Ollama（含嵌入，完全离线）
AEGIS_LLM_PROVIDER=ollama
AEGIS_LLM_MODEL=qwen2.5:3b
AEGIS_EMBED_PROVIDER=ollama
AEGIS_EMBED_MODEL=nomic-embed-text
📖 使用文档
| 文档 | 内容 |
|---|---|
| docs/architecture.md | 架构设计、多智能体协作协议、安全模型 |
| docs/deploy.md | 部署、配置、LLM 接入、MCP stdio 模式 |
| docs/verification.md | 端到端自验证报告与验证方法 |
🔌 HTTP API
| 方法 | 路径 | 说明 |
|---|---|---|
| POST | /api/documents/ingest |
上传文档入库（multipart） |
| POST | /api/documents/ingest-path |
按路径批量入库 |
| GET | /api/documents |
文档列表 |
| DELETE | /api/documents/{id} |
删除文档（敏感 → HITL） |
| POST | /api/chat |
提问（多智能体流水线） |
| GET | /api/sessions/{id} |
会话状态 |
| POST | /api/sessions/{id}/resume |
审批后恢复会话 |
| GET | /api/approvals |
审批单列表 |
| POST | /api/approvals/{id}/decide |
批准/拒绝（{"approve": true}） |
| GET | /api/tools · POST /api/tools/call |
MCP 工具目录 / 人工调用工具 |
| GET | /health |
健康检查 |
🧩 MCP 工具
以标准 Model Context Protocol 暴露，可被任何 MCP 客户端接入：
python -m aegis.mcp.server # 标准 stdio 服务
| 工具 | 说明 | 安全等级 |
|---|---|---|
calculator |
AST 白名单安全计算 | ✅ 常规 |
get_current_time |
当前时间 | ✅ 常规 |
kb_search |
知识库语义检索 | ✅ 常规 |
doc_stats |
知识库统计 | ✅ 常规 |
send_email |
模拟发邮件 | 🔒 敏感 → HITL |
export_file |
导出文件（沙箱目录） | 🔒 敏感 → HITL |
delete_document |
删除文档 | 🔒 敏感 → HITL |
🧪 测试与验证
pip install -e ".[dev]"
pytest -q # 单元 + 集成测试（全部离线可跑）
aegis demo # 端到端演示（含 20+ 条自校验断言）
📁 目录结构
enterprise-rag-agent/
├── aegis/
│ ├── llm/ # LLM 抽象层（OpenAI 兼容 / Ollama / 离线确定性）
│ ├── embeddings/ # 嵌入层（fastembed 本地 / OpenAI / Ollama）
│ ├── ingestion/ # 解析（5 格式）→ 切块 → 入库管道
│ ├── retrieval/ # Chroma 向量库 + BM25 混合检索
│ ├── mcp/ # MCP 服务器 / 客户端 / 安全策略
│ ├── agents/ # Planner / Retriever / Answerer / Auditor
│ ├── hitl/ # 人工审批管理器
│ ├── api/ # FastAPI 服务
│ ├── orchestrator.py # 多智能体编排器（状态机 + 挂起恢复）
│ ├── demo.py # 端到端演示
│ └── cli.py # 命令行入口
├── scripts/make_sample_docs.py # 样例文档生成
├── tests/ # pytest 套件
└── docs/ # 架构 / 部署 / 验证文档
⚠️ 安全说明
- 敏感工具默认拒绝（
auto_deny），生产环境建议保持interactive人工审批； export_file仅允许写入数据目录下的exports/沙箱；- 计算器采用 AST 白名单求值，不存在
eval注入面； - 该项目的
send_email为模拟实现，接入真实邮件网关前请自行实现并保持 HITL 审批。
📄 License
MIT
