使用说明
经理助理应用程序
一个智能助理应用程序，通过利用LLM功能，通过Google Workspace、Atlassian和Slack API访问组织数据，帮助工程领导者回答有关其组织的问题。
🎯 概述
Manager Assistant应用程序提供跨多个组织数据源的自然语言查询功能，使管理者能够全面了解他们的团队、项目和组织环境。该系统使用MCP（模型上下文协议）服务器架构来提供对组织数据源的安全、基于工具的访问。
主要特点
- 🔍 多源数据集成：谷歌工作区（云搜索、Gmail、谷歌应用）、Atlassian（Jira、Confluence）、Slack、Workday
- 🔐 安全凭据管理：API密钥和令牌的加密存储和管理
- 🤖 LLM灵活性：支持多个LLM提供商，配置切换简单
- ⚡ 上下文管理：大型数据集的智能上下文选择和优化
- 🎯 质量保证：法学硕士作为答案细化的评判评估体系
- 💬 自然语言接口：会话查询处理和响应生成
🏗️ 建筑
该应用程序遵循为可扩展性和安全性而设计的模块化架构：
┌─────────────────────────────────────────────────────────────────┐
│ Manager Assistant Application │
├─────────────────────────────────────────────────────────────────┤
│ Frontend Interface (Web/CLI) │
│ ├─ Query Input & Processing │
│ ├─ Response Display & Interaction │
│ └─ Configuration Management │
├─────────────────────────────────────────────────────────────────┤
│ Core Application Layer │
│ ├─ LLM Integration (Configurable Provider) │
│ ├─ Query Processing & Intent Recognition │
│ ├─ Context Management & Optimization │
│ ├─ Response Generation & Refinement │
│ └─ LLM-as-Judge Evaluation System │
├─────────────────────────────────────────────────────────────────┤
│ Context Management System │
│ ├─ Intelligent Context Selection & Filtering │
│ ├─ Multi-Level Content Summarization │
│ ├─ Context Window Optimization │
│ ├─ Semantic Chunking & Compression │
│ └─ Context Caching & Indexing │
├─────────────────────────────────────────────────────────────────┤
│ MCP Server Layer │
│ ├─ Google Workspace Tools (Cloud Search, Gmail, Apps) │
│ ├─ Atlassian Tools (Jira, Confluence) │
│ ├─ Slack Tools (Messages, Channels, Users) │
│ └─ Tool Orchestration & Response Aggregation │
├─────────────────────────────────────────────────────────────────┤
│ Security & Credential Management │
│ ├─ Encrypted Credential Storage │
│ ├─ OAuth2/API Key Management │
│ ├─ Permission Mapping & Access Control │
│ └─ Audit Logging & Security Monitoring │
├─────────────────────────────────────────────────────────────────┤
│ External APIs │
│ ├─ Google Workspace APIs │
│ ├─ Atlassian Cloud APIs │
│ └─ Slack Web API │
└─────────────────────────────────────────────────────────────────┘
🚀 快速开始
先决条件
- Python 3.11+（必填）
- Node.js 18+（用于前端开发）
- PostgreSQL 13+
- Redis 6+
- OpenTetry兼容的可观察性后端（Jaeger、Prometheus等）
- 访问所需的API（谷歌工作区、Atlassian、Slack）
安装
快速设置（推荐）
# Clone the repository
git clone https://github.com/Maascamp/manager-api.git
cd manager-api
# Run automated setup
./setup.sh
# Update configuration
# Edit .env with your API keys and configuration
# Start development environment
make dev
手动设置
-
克隆存储库
git clone https://github.com/Maascamp/manager-api.git cd manager-api -
设置Python虚拟环境
# Create virtual environment python3 -m venv venv # Activate virtual environment # On macOS/Linux: source venv/bin/activate # On Windows: # venv\Scripts\activate # Upgrade pip pip install --upgrade pip -
安装依赖项
# Python backend (required) pip install -r requirements.txt # Frontend dependencies cd frontend npm install cd .. -
配置环境
cp env.example .env # Edit .env with your configuration -
初始化数据库
python -m alembic upgrade head -
启动应用程序
# Start backend python -m uvicorn src.main:app --host 0.0.0.0 --port 8000 --reload # In another terminal, start frontend cd frontend npm run dev
📋 配置
LLM提供程序设置
在环境变量中配置首选LLM提供程序：
# OpenAI
OPENAI_API_KEY=your_openai_key
OPENAI_MODEL=gpt-4
# Anthropic
ANTHROPIC_API_KEY=your_anthropic_key
ANTHROPIC_MODEL=claude-3-opus
# Google
GOOGLE_API_KEY=your_google_key
GOOGLE_MODEL=gemini-pro
API证书
为每个数据源设置凭据：
# Google Workspace
GOOGLE_CLIENT_ID=your_client_id
GOOGLE_CLIENT_SECRET=your_client_secret
GOOGLE_SERVICE_ACCOUNT_KEY=path_to_service_account.json
# Atlassian
ATLASSIAN_API_TOKEN=your_api_token
ATLASSIAN_BASE_URL=https://your-domain.atlassian.net
# Slack
SLACK_BOT_TOKEN=xoxb-your-bot-token
SLACK_APP_TOKEN=xapp-your-app-token
# OpenTelemetry Configuration (Required)
OTEL_SERVICE_NAME=manager-assistant
OTEL_EXPORTER_JAEGER_ENDPOINT=http://localhost:14268/api/traces
OTEL_EXPORTER_PROMETHEUS_ENDPOINT=http://localhost:9090/metrics
OTEL_LOG_LEVEL=INFO
🔧 发展
项目结构
mgr-api/
├── src/
│ ├── core/ # Core application logic
│ │ ├── llm/ # LLM integration
│ │ ├── context/ # Context management
│ │ └── evaluation/ # LLM-as-judge system
│ ├── mcp_server/ # MCP server implementation
│ │ ├── tools/ # API tool implementations
│ │ └── registry/ # Tool registry
│ ├── security/ # Security and credential management
│ ├── api/ # REST API endpoints
│ └── observability/ # OpenTelemetry instrumentation
├── frontend/ # Web interface
├── cli/ # Command-line interface
├── tests/ # Test suite
├── docs/ # Documentation
└── scripts/ # Utility scripts
前端技术栈
前端采用现代React技术构建：
- 反应18+：最新的React，带有钩子和并发功能
- TypeScript：类型安全和更好的开发人员体验
- 维特：快速构建工具和开发服务器
- 顺风CSS：实用程序优先的CSS样式框架
- 状态：轻量级状态管理
- TanStack查询：数据获取和缓存
- Shadcn/ui：现代、可访问的UI组件
- Radix UI：可访问的组件图元
开发设置
-
安装开发依赖项
# Backend pip install -r requirements-dev.txt # Frontend cd frontend npm install -
运行测试
# Backend tests pytest # Frontend tests cd frontend npm test -
启动开发服务器
# Backend (terminal 1) python manage.py runserver --debug # Frontend (terminal 2) cd frontend npm run dev
添加新数据源
MCP服务器架构使添加新数据源变得容易：
- 创建新的工具类 在
src/mcp_server/tools/ - 实现工具界面 具有身份验证和数据访问功能
- 注册该工具 在工具注册表中
- 更新文档 具有新功能
例子：
class NewDataSourceTool(BaseTool):
def __init__(self, credentials):
self.credentials = credentials
def search(self, query, filters=None):
# Implement data source search
pass
def get_details(self, item_id):
# Implement item detail retrieval
pass
🔒 安全
凭证管理
- 所有凭据都使用AES-256加密
- 凭据存储在具有访问控制的安全保管库中
- 自动凭证轮换和更新
- 所有凭据访问的审核日志记录
数据保护
- 数据最小化：仅访问查询所需的数据
- 可配置的数据保留策略
- 用户同意和数据匿名化选项
- 符合GDPR、SOC 2和行业标准
网络安全
- 所有通信的端到端加密
- VPC和防火墙配置的网络隔离
- API速率限制和DDoS防护
- 实时安全监控和警报
📊 监测和可观察性
开放遥测仪器（必需）
应用程序使用 独家开放遥测 对于所有可观察性需求：
追踪
- 分布式跟踪：跟踪所有API调用、LLM请求和MCP操作
- 自定义跨度：业务逻辑和LLM操作具有自定义跨度
- 上下文传播：跨异步操作维护跟踪上下文
- 出口商：Jaeger、Zipkin或其他与OTel兼容的后端
指标
- 自定义指标：查询性能、LLM令牌使用情况、系统健康状况
- 普罗米修斯出口：指标导出到兼容Prometheus的后端
- 商业米制公约：查询成功率、响应时间、成本跟踪
- 系统度量：CPU、内存、数据库性能
日志记录
- 结构化日志记录：带有OpenTetry相关ID的JSON格式
- 日志相关性：与跟踪和指标链接的日志
- 安全事件：所有业务的审计跟踪
- 性能跟踪：请求/响应时间和错误跟踪
设置OpenTelemetry
-
安装OpenTetry软件包
pip install opentelemetry-api opentelemetry-sdk opentelemetry-instrumentation-fastapi pip install opentelemetry-exporter-jaeger opentelemetry-exporter-prometheus -
配置导出器
# Jaeger for tracing OTEL_EXPORTER_JAEGER_ENDPOINT=http://localhost:14268/api/traces # Prometheus for metrics OTEL_EXPORTER_PROMETHEUS_ENDPOINT=http://localhost:9090/metrics -
启动可观察性后端
# Start Jaeger docker run -d -p 16686:16686 -p 14268:14268 jaegertracing/all-in-one # Start Prometheus docker run -d -p 9090:9090 prom/prometheus
🧪 测试
测试类别
- 单元测试：单个组件测试
- 集成测试：API和服务集成
- 安全测试：渗透测试和漏洞评估
- 性能测试：负载测试和优化
- 端到端测试：完成用户工作流程测试
运行测试
# Run all tests
pytest
# Run specific test categories
pytest tests/unit/
pytest tests/integration/
pytest tests/security/
# Run with coverage
pytest --cov=src --cov-report=html
📚 文档
🤝 贡献
- 分叉存储库
- 创建要素分支(
git checkout -b feature/amazing-feature) - 提交您的更改(
git commit -m 'Add amazing feature') - 推到分支(
git push origin feature/amazing-feature) - 打开拉取请求
开发指南
- 遵循项目中定义的编码标准
- 为新功能编写全面的测试
- 更新文档以了解任何更改
- 确保遵循安全最佳实践
- 尽可能保持向后兼容性
📄 许可证
此项目根据MIT许可证获得许可-请参阅 许可证 文件以获取详细信息。
🆘 支持
- 问题：通过GitHub Issues报告错误和请求功能
- 讨论：在GitHub讨论中加入社区讨论
- 安全：通过以下方式私下报告安全漏洞security@company.com
- 文档：查看docs/目录以获取详细指南
🗺️ 路线图
当前里程碑
- 里程碑1：核心基金会✅
- 里程碑2：谷歌工作区集成🔄
- 里程碑3：Atlassian集成📋
- 里程碑4：Slack集成📋
- 里程碑5：多源情报和上下文管理📋
- 里程碑6：法学硕士作为法官质量体系📋
- 里程碑7：用户界面📋
- 里程碑8：安全和生产准备📋
未来的增强功能
- 其他数据源集成
- 高级分析和报告
- 移动应用程序
- 团队协作功能
- 高级安全功能
状态: 🚧 在开发中
版本: 0.1.0
最后更新: 2024-12-19
