brooksmcmillin/agents

# 多智能体系统 [](https://github.com/brooksmcmillin/agents/actions/workflows/tests.yml) [](https://github.com/brooksmcmillin/agents/actions/workflows/integration.yml) [](https://github.com/brooksmcmillin/agents/actions/workflows/deploy.yml) 一个使用 Claude (Anthropic SDK) 和 Model Context Protocol (MCP) 构建的多智能体系统。该仓库支持多个专业智能体，它们共享用于内容分析、任务管理和持久记忆的通用基础设施。 ## 概述 本项目展示了构建具有外部工具集成的 LLM 驱动智能体的生产级模式。它包括： - **多个智能体** - 13 个交互式 CLI 智能体（聊天机器人、PR、安全、业务、任务、代码分析、事件、红队、日志分析、安全审计、系统管理员、网页分析、网站测试）和 6 个独立服务（代码审查、邮件接收、通知器、编排器、PR 牧羊人、任务队列） - **Web UI** - 现代化的 React 界面，用于通过持久对话与智能体聊天 - **共享 MCP 工具** - 53 个工具，包括网页分析、记忆、RAG 文档搜索、邮件管理、HTTP 客户端、文件系统、Claude Code 和通信 - **热重载** - 无需重启智能体即可编辑工具 - **OAuth 基础设施** - 为真实 API 集成做好准备 - **远程 MCP 支持** - 将工具与智能体分开部署 ## 快速开始 ### 前置条件 - Python 3.12 或更高版本 - `uv` 包管理器 - Anthropic API 密钥 ### 安装 ``` # 安装 uv (如果尚未安装) curl -LsSf https://astral.sh/uv/install.sh | sh # 安装依赖 uv sync # 可选：安装语音界面依赖 # 需要 PortAudio 系统库 (Ubuntu 上使用 sudo apt-get install portaudio19-dev) uv sync --group voice # 配置环境 cp .env.example .env # 编辑 .env 并添加：ANTHROPIC_API_KEY=your_key_here ``` ### 运行智能体 ``` # Chatbot - 具备所有工具的通用助手 uv run bin/run-agent chatbot # PR Agent - 内容策略助手 uv run bin/run-agent pr # Security Researcher - 具有 RAG 的 AI 安全专家 uv run bin/run-agent security # Business Advisor - 变现与策略专家 uv run bin/run-agent business # Task Manager - 交互式任务管理 uv run bin/run-agent tasks # REST API Server - Agent 的 HTTP 访问接口 uv run python -m api # Web UI - 现代化 React Agent 界面 # (需要 npm 和已构建的前端) cd webui/frontend && npm install && npm run build cd ../.. && uv run python -m api # 访问 http://localhost:8080 # Notifier - 发送有关任务的 Slack 通知 uv run python -m agents.notifier.main # MCP server 独立版 uv run python -m mcp_server.server ``` ### 交互命令 一旦智能体运行： - `exit` 或 `quit` - 结束会话 - `stats` - 显示 token 使用统计 - `reload` - 重新连接 MCP 服务器并发现更新的工具 ## 架构 ### 系统概述 ``` User Input → Agent → Claude API → MCP Client → MCP Server → Tools ↑ ↓ └────────────── Tool Results ←──────────────────┘ ``` ### 组件 **1. 智能体** (`agents/`) - 扩展 `agent-framework` 的独立智能体实现 - 每个智能体都有自己的系统提示和行为 - 共享通用的 MCP 工具和基础设施 **2. MCP 服务器** (`mcp_server/`) - 通过 Model Context Protocol 公开工具 - 处理身份验证和工具执行 - 可以在本地 或远程 (HTTP/SSE) 运行 **3. 共享工具** (`shared/`) - 可跨智能体重用的通用代码 - 远程 MCP 客户端实现 - OAuth 辅助工具和实用程序 **4. 包** (`packages/`) - `agent-framework/` - 包含 MCP 工具、基础智能体类和安全工具的共享库 - `chasm/` - 语音接口库 (Deepgram STT + Cartesia TTS) - 可选依赖 ### 智能体循环 ``` while not done: # 1. Call Claude with conversation history + available tools response = await client.messages.create(messages=history, tools=tools) # 2. If Claude wants to use tools, execute them via MCP if response.stop_reason == "tool_use": async with mcp_client.connect(): # Fresh connection (hot reload) results = await mcp_client.call_tool(name, args) history.append(tool_results) # Loop continues - Claude analyzes results # 3. Claude provides final text response else: return response.content ``` **关键特性：** 智能体在每次工具调用时重新连接 MCP 服务器，从而能够在不丢失对话上下文的情况下热重载工具。 ## 可用智能体 ### 交互式 CLI 智能体 通过 `uv run bin/run-agent ` 运行。这些智能体在 `shared/registry.py` 中注册，并可通过 REST API 和 Web UI 访问。 | Agent | Run As | Description | Docs | |-------|--------|-------------|------| | **Chatbot** | `chatbot` | 拥有全部 53 个 MCP 工具的通用助手 | [文档](agents/chatbot/README.md) | | **PR Agent** | `pr` | 内容策略、SEO、社交媒体、Claude Code 编辑 | [文档](agents/pr_agent/README.md) | | **Security Researcher** | `security` | 具有 RAG 知识库的 AI/ML 安全研究 | [文档](agents/security_researcher/README.md) | | **Business Advisor** | `business` | 变现策略、市场分析、GitHub 分析 | [文档](agents/business_advisor/README.md) | | **Task Manager** | `tasks` | 通过远程 MCP 服务器进行任务管理 | [文档](agents/task_manager/README.md) | | **Code Analysis** | `code-analysis` | 针对安全性、逻辑、性能的代码仓库审查 | [文档](agents/code_analysis/README.md) | | **Events** | `events` | 具有偏好学习的本地活动发现 | [文档](agents/events/README.md) | | **Red Team** | `red-team` | 通过 HTTP 工具进行授权渗透测试 | [文档](agents/red_team/README.md) | | **Log Analysis** | `log-analysis` | 日志文件调查，自动标记关键发现 | [文档](agents/log_analysis/README.md) | | **Security Audit** | `security-audit` | 分析来自非 LLM 收集器的 JSON 安全审计报告 | [文档](agents/security_audit/README.md) | | **Sysadmin** | `sysadmin` | 网络发现、端口扫描和系统安全评估 | [文档](agents/system_admin/README.md) | | **Web Analysis** | `web-analysis` | 网站审计，为发现的问题自动创建任务 | [文档](agents/web_analysis/README.md) | | **Website Tester** | `website-tester` | 使用无头 Playwright 浏览器进行自动化网站审计 | [文档](agents/website_tester/README.md) | ### 独立服务 直接运行 — 这些不在智能体注册表中，也不使用 `bin/run-agent`。 | Service | Invocation | Description | Docs | |---------|-----------|-------------|------| | **Email Intake** | `uv run python -m agents.email_intake.main` | 监控收件箱，将任务路由到智能体 | [文档](agents/email_intake/README.md) | | **Notifier** | `uv run python -m agents.notifier.main` | 关于待处理任务的 Slack 通知 | [文档](agents/notifier/README.md) | | **Orchestrator** | `uv run python -m agents.orchestrator.main "task"` | 任务分解和 Claude Code 工作器 | [文档](agents/orchestrator/README.md) | | **PR Shepherd** | `PRShepherd(config).run()` | 轮询 PR，修复 CI，自动合并 | [文档](agents/pr_shepherd/README.md) | | **Task Queue** | `TaskQueueRunner(config).run()` | 批量任务分类和编排器调度 | [文档](agents/task_queue/README.md) | ### REST API 服务器 用于访问所有 13 个交互式智能体的 HTTP/REST 接口： - 无状态单次请求和有状态多轮会话 - 具有 TTL 的自动会话管理 - 每次请求的 token 使用跟踪 **运行：** `uv run python -m api` | **[文档](api/README.md)** ## Web UI 一个现代化的 React Web 界面，用于通过持久对话与智能体进行交互。 **特性：** - 从 13 个交互式智能体中选择（聊天机器人、PR、任务、安全、业务、代码分析、事件、红队、日志分析、安全审计、系统管理员、网页分析、网站测试） - 数据库支持的对话，可在服务器重启后保留 - 创建、重命名、删除和切换对话 - 带有 token 使用跟踪的实时聊天 - 深色模式支持 - 针对桌面和移动端的响应式设计 **设置：** ``` # 安装 Node.js 依赖 cd webui/frontend npm install # 开发模式 (热重载) # 终端 1：Backend uv run python -m api # 终端 2：Frontend npm run dev # 访问 http://localhost:5173 # 生产环境构建 npm run build uv run python -m api # 访问 http://localhost:8080 ``` **要求：** - Node.js 18+ - PostgreSQL 数据库（设置 `DATABASE_URL` 环境变量） 有关详细文档，请参阅 [webui/README.md](webui/README.md)。 ## MCP 工具 MCP 服务器向智能体公开 **53 个工具**，分为 14 个类别： ### 网页分析（2 个工具） - `fetch_web_content` - 获取并读取网页内容作为整洁的 markdown 以供分析 - `analyze_website` - 分析网站的 SEO、基调和参与度指标 ### 记忆（6 个工具） - `save_memory` - 使用键/值/类别/标签/重要性（1-10 级）保存信息 - `get_memories` - 通过类别/标签/重要性过滤检索记忆 - `search_memories` - 按关键字搜索记忆 - `delete_memory` - 按键删除记忆 - `get_memory_stats` - 获取记忆系统统计信息（总数、类别、平均重要性） - `configure_memory_store` - 配置记忆后端（文件或数据库） 记忆在对话之间持久保存（默认：`memories/memories.json`，可选：PostgreSQL）。 ### RAG 文档搜索（6 个工具） *需要 PostgreSQL 数据库和 OpenAI API 密钥用于嵌入* - `add_document` - 将文档添加到知识库以进行语义搜索 - `search_documents` - 通过查询和相似度阈值搜索文档 - `get_document` - 按 ID 检索完整文档 - `list_documents` - 列出知识库中的所有文档 - `delete_document` - 按 ID 删除文档 - `get_rag_stats` - 获取 RAG 系统统计信息（总文档数、块数、数据库大小） ### 邮件管理 - FastMail（9 个工具） *需要 FastMail API 令牌和账户 ID* - `list_mailboxes` - 列出所有邮箱 - `get_emails` - 从邮箱获取带限制的邮件 - `get_email` - 按 ID 获取单个邮件 - `search_emails` - 按查询搜索邮件 - `send_email` - 发送带有收件人/抄送/密送/主题/正文的邮件 - `send_agent_report` - 从智能体向管理员发送报告/通知 - `move_email` - 将邮件移动到不同的邮箱 - `update_email_flags` - 更新邮件标志（已读、已标记） - `delete_email` - 永久删除邮件 ### 通信（1 个工具） - `send_slack_message` - 通过 webhook 发送 Slack 通知 ### 社交媒体（1 个 工具） - `get_social_media_stats` - 获取 Twitter/LinkedIn 统计信息（当前为模拟数据，准备用于 OAuth 集成） ### 内容建议（1 个工具） - `suggest_content_topics` - 生成内容主题创意（当前为模拟数据） **此外：** HTTP Client（7 个工具）、Markdown Files（4 个工具）、Filesystem（6 个工具）、Claude Code（5 个工具）、Twilio SMS（5 个工具）。**总计：** 通过 MCP 向智能体提供 **53 个工具**。有关完整参考，请参阅 [docs/tools.md](docs/tools.md)，有关使用指南，请参阅 [GUIDES.md](docs/GUIDES.md)。 ## 项目结构 ``` agents/ # Agent implementations ├── chatbot/ # General-purpose assistant (interactive) ├── pr_agent/ # Content strategy assistant (interactive) ├── security_researcher/ # AI security research (interactive) ├── business_advisor/ # Business strategy (interactive) ├── task_manager/ # Task management (interactive) ├── code_analysis/ # Repository analysis (interactive) ├── events/ # Local events discovery (interactive) ├── red_team/ # Penetration testing (interactive) ├── log_analysis/ # Log file investigation (interactive) ├── security_audit/ # Security audit report analysis (interactive) ├── system_admin/ # Network and system security assessment (interactive) ├── web_analysis/ # Website auditing with task creation (interactive) ├── website_tester/ # Automated website testing (interactive) ├── email_intake/ # Email inbox monitor (standalone) ├── notifier/ # Slack notifications (standalone) ├── orchestrator/ # Task decomposition + workers (standalone) ├── pr_shepherd/ # CI fix + auto-merge daemon (standalone) └── task_queue/ # Batch task triage pipeline (standalone) api/ # REST API server (FastAPI) webui/ # React frontend mcp_server/ # Shared MCP server and tools infra/ # Infrastructure configs (systemd service files) docs/ # Documentation packages/ # Internal libraries (monorepo) ├── agent-framework/ # Base agent classes, MCP client, and tools └── chasm/ # Voice interface library shared/ # Common utilities bin/ # Executable scripts tests/ # Test suite scripts/ # Utility scripts ``` ## 开发工作流 ### 热重载 - 无需重启即可编辑工具 1. 启动智能体：`uv run bin/run-agent pr` 2. 在 `packages/agent-framework/agent_framework/tools/*.py` 中编辑工具代码 3. 保存更改 4. 下一次工具调用会自动获取更改 5. 如有必要，输入 `reload` 强制重新连接 智能体在每次工具调用时重新连接 MCP 服务器，而不是保持持久连接。这允许在智能体运行时编辑工具，而不会丢失对话上下文。 ### 添加新工具 有关创建和注册 MCP 工具的完整指南，请参阅 [docs/tools.md](docs/tools.md#adding-a-new-tool)。 ### 添加新智能体 1. 创建智能体目录：`mkdir -p agents/your_agent` 2. 创建扩展 `agent-framework` 中 `Agent` 类的 `main.py` 3. 创建带有系统提示和问候语的 `prompts.py` 4. 创建带有版本信息的 `__init__.py` 5. 在 `shared/registry.py` 的 `build_agent_registry()` 中注册为 3 元组 `(AgentClass, kwargs_or_None, "description")` 并运行：`uv run bin/run-agent your-agent` 所有智能体自动有权访问共享的 MCP 工具。 有关详细说明，请参阅 [CLAUDE.md](CLAUDE.md#adding-new-agents)。 ## 功能特性 ### 持久记忆 - 智能体可以在对话之间保存和回忆信息 - 基于类别的组织（偏好、事实、目标、见解） - 基于重要性的优先级排序（1-10 级） - 基于标签的过滤 - 轻松从文件存储迁移到数据库 ### OAuth 支持 - 完整的 OAuth 2.0 实现（授权码流程 + 客户端凭据） - 自动令牌刷新 - 加密令牌存储 (Fernet) - 为 Twitter、LinkedIn 和其他社交媒体 API 做好准备 - 基于文件的存储，具有轻松迁移到数据库/保险库的路径 ### 远程 MCP - 将 MCP 服务器与智能体分开托管 - 多个智能体可以共享一个服务器 - 用于云部署的 HTTP/SSE 传输 - 支持本地 和远程 () 模式 ### 错误处理 - 全面的错误日志记录 - 优雅的故障处理 - 工具错误作为 `is_error` 结果返回给 Claude - 最大迭代限制以防止无限循环 ## 当前状态 vs 生产环境 **目前可用：** - 使用 Claude Sonnet 4.6 的完整智能体循环 - 13 个交互式智能体 + 6 个独立服务 - 53 个 MCP 工具（网页、记忆、RAG、邮件、HTTP 客户端、文件系统、Claude Code、通信） - 真实的网页抓取和内容分析 - 具有语义相似性的 RAG 文档搜索 - FastMail 邮件集成 - 跨对话的持久记忆（文件或数据库后端） - 用于工具开发的热重载 - OAuth 基础设施（准备好用于生产集成） - Token 使用跟踪 - 用于分布式部署的远程 MCP 支持 - 用于通过 HTTP 访问智能体的 REST API 服务器 **面向生产环境：** - 集成真实的社交媒体 API（Twitter、LinkedIn） - 迁移到 PostgreSQL/Redis 用于记忆和令牌 - 添加速率限制 - 添加多用户支持（memory/auth 的 user_id） - 远程部署 MCP 服务器 - 添加监控和指标 ## 配置 ### 环境变量 有关所有可用选项，请参阅 `.env.example`。关键变量： ``` # 必需 ANTHROPIC_API_KEY=your_api_key_here # 可选 - MCP Server MCP_SERVER_URL=https://mcp.brooksmcmillin.com/mcp # For remote MCP # 可选 - Logging LOG_LEVEL=INFO # DEBUG, INFO, WARNING, ERROR # 可选 - 社交媒体 OAuth (准备就绪后) TWITTER_CLIENT_ID=... TWITTER_CLIENT_SECRET=... LINKEDIN_CLIENT_ID=... LINKEDIN_CLIENT_SECRET=... ``` ## 文档 - **[CLAUDE.md](CLAUDE.md)** - Claude Code 的综合项目文档 - **[docs/TESTING.md](docs/TESTING.md)** - 测试和调试指南（记忆工具、日志、常见问题） - **[GUIDES.md](docs/GUIDES.md)** - 功能指南（记忆系统、OAuth、部署、语音接口） - **[REMOTE_MCP.md](docs/REMOTE_MCP.md)** - 远程 MCP 服务器设置和配置 - **[HOT_RELOAD.md](docs/HOT_RELOAD.md)** - 热重载开发工作流 - **智能体 README** - 有关特定智能体的文档，请参阅 `agents/*/README.md` - **代码注释** - 详尽的内联文档 ## 故障排除 ### 智能体问题 ``` # 查看日志 tail -f ~/.agents/logs/agent_$(date +%Y-%m-%d).log # 启用 debug logging # 在 .env 中：LOG_LEVEL=DEBUG # 测试 MCP server 启动 uv run python -m mcp_server.server ``` ### MCP 连接问题 ``` # 测试 MCP server 启动 uv run python -m mcp_server.server # 测试远程 MCP 连接 curl https://mcp.brooksmcmillin.com/mcp/health ``` ### 记忆问题 ``` # 查看 memories cat memories/memories.json | python -m json.tool # 清除所有 memories rm memories/memories.json ``` ## 技术栈 - **Python 3.12+** - **anthropic** - Claude 的官方 Anthropic SDK - **agent-framework** - 基础智能体类和 MCP 客户端（本地包） - **chasm** - 语音接口库（本地包，可选） - **mcp** - Model Context Protocol SDK - **httpx** - 异步 HTTP 客户端 - **authlib** - OAuth 2.0 实现 - **cryptography** - 令牌加密 (Fernet) - **pydantic** - 数据验证和设置 - **python-dotenv** - 环境管理 ### 可选依赖 - **voice** - 通过 `chasm` 的语音接口支持（需要 PortAudio 系统库） - 安装方式：`uv sync --group voice` - 系统要求：`sudo apt-get install portaudio19-dev` (Ubuntu/Debian) ## 代码风格 - 现代 Python 类型（使用 dict/list 而非 typing.Dict/List，使用 `str | None` 而非 Optional[str]） - 所有函数都有类型提示，包括返回类型 - 所有异步 I/O 操作使用 async/await - 全面的文档字符串（Google 风格） - 在返回给用户之前记录错误 - 所有工具结果使用 JSON ## CI/CD 使用 GitHub Actions 进行自动化测试和部署。 ### 工作流 **测试 (`tests.yml`)** - 在每次推送和 PR 时运行 - ✅ 后端测试（带 PostgreSQL 的 pytest） - ✅ 前端测试（vitest） - ✅ 代码检查（ruff、eslint） - ✅ 类型检查（TypeScript） - ✅ 构建验证 **集成 (`integration.yml`)** - 完整的集成测试 - ✅ 数据库集成测试 - ✅ API 端点测试 - 🚧 E2E 测试（Playwright 占位符） **部署 (`deploy.yml`)** - 在标签上构建和发布 - ✅ 生产前端构建 - ✅ 制品上传 - ✅ GitHub releases ### 本地运行检查 ``` # 在本地运行所有 CI 检查 .github/workflows/test-local.sh # 或单独运行： uv run pytest api/test_server.py -v --cov cd webui/frontend && npm test -- --run uv run ruff check . && uv run ruff format --check . ``` 有关详细文档，请参阅 [.github/workflows/README.md](.github/workflows/README.md)。 ## 贡献 要扩展本项目： 1. 遵循现有的代码模式 2. 为所有函数添加类型提示 3. 编写文档字符串（Google 风格） 4. 在推送之前 **在本地运行测试**：`.github/workflows/test-local.sh` 5. 确保您的 PR 通过 CI 6. 更新文档 ## 许可证 这是一个用于教育目的的演示项目。 **使用 Claude Sonnet 4.6 和 Model Context Protocol 构建**

标签：Anthropic, CIS基准, Claude, CVE检测, DevSecOps, DLL 劫持, LLM, MCP, OAuth, PyRIT, Python, RAG, React, REST API, Syscalls, TCP SYN 扫描, Unmanaged PE, Web UI, 上游代理, 代码分析, 任务管理, 凭证管理, 分布式部署, 商业顾问, 多智能体系统, 大语言模型, 开源, 数据展示, 无后门, 检索增强生成, 模型上下文协议, 测试用例, 热重载, 红队, 网络调试, 自动化, 运行时操纵, 逆向工具