🛡️ 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