人工智能AI Agent多智能体MCP 服务工具调用浏览器控制【免费下载链接】hiveMulti-Agent Harness for Production AI项目地址https://gitcode.com/gh_mirrors/hive48/hive点击查看免费下载本篇技术指南以 HiveMulti-Agent Harness for Production AI的官方环境搭建文档为主体完整讲解quickstart.sh一键安装流程、Windows/Alpine 多平台适配、LLM 提供商配置、基于 uv workspace 的包结构、Agent 构建与运行工作流以及常见故障的排查方案。读完本文你将能够在本地从零搭建一套可运行的 Hive Agent 开发环境并基于files-tools等 MCP 工具完成 Agent 的初始化、校验、测试与运行。环境需求概览在开始安装之前先确认你的机器满足以下基础条件依据 docs/environment-setup.mdPython 版本最低3.11推荐 3.11 或 3.12官方已在 3.11、3.12、3.13 上完成测试。仓库根目录的 .python-version 也固定为3.11。pip保持最新版本。内存2GB RAM。网络需要能访问 LLM API 的外网连接调用 LLM 时必需。Windows 用户原生方式需要 PowerShell 5.1或使用 WSL 2。注意Hive 没有集中式的config.yaml或 Docker Compose配置分散在环境变量、~/.hive/configuration.json、Agent 级config.py、pyproject.toml与.mcp.json中详见 docs/configuration.md。一键安装quickstart 脚本做了什么Hive 提供了自动化安装脚本运行方式非常简单./quickstart.shWindows 原生环境则运行 PowerShell 版本要求 PowerShell 5.1并建议在 Windows 设置中禁用 App Execution Aliases以免与 Python 路径产生冲突.\quickstart.ps1对照仓库根目录的 quickstart.sh 源码这个交互式向导实际执行了以下步骤检查 Python 版本脚本会按python3.11 → python3.12 → python3.13 → python3 → python的顺序探测优先选用满足 3.11的解释器不满足时直接退出并提示升级见 quickstart.sh。检查/安装 uv若系统没有uv会自动通过curl -LsSf https://astral.sh/uv/install.sh | sh安装并加入 PATHquickstart.sh。检查 Node.js前端 Dashboard 需要 Node.js 20缺失或版本过低时脚本会尝试通过 nvm 自动安装quickstart.sh。安装核心包与工具包在仓库根目录执行uv sync一次性安装framework来自core/与aden_tools来自tools/两个包quickstart.sh。检查系统级工具sqlite3用于 colony 进度跟踪、tesseract用于扫描件 OCR、Chrome/Edge用于 GCU 浏览器自动化、Playwright chromium用于网页抓取缺失时按发行版自动安装quickstart.sh。构建前端 Dashboard若 Node.js 可用会执行npm install npm run build产物输出到core/frontend/dist/quickstart.sh。验证 Python 导入通过scripts/check_requirements.py批量检查framework、aden_tools、litellm三个模块能否正常导入quickstart.sh。交互式配置默认 LLM 提供商详见下一节。初始化加密凭据存储在~/.hive/credentials/下创建凭据目录并生成 Fernet 加密密钥保存到~/.hive/secrets/credential_keyquickstart.sh。安装 hive CLI将仓库根目录的 hive 包装脚本软链到~/.local/bin/hivequickstart.sh。初始化 Queen 默认配置调用framework.agents.queen.queen_profiles.ensure_default_queens()非致命失败可跳过。最终验证检查framework、aden_tools、litellm、MCP 配置、MCP 注册表hive mcp init、凭据存储、前端产物等全部通过后显示 ADEN HIVE — READY 并自动启动 Dashboard。hive CLI 包装脚本安装后你会获得全局可用的hive命令。仓库根目录的 hive 是一个 bash 包装脚本它要求你在项目根目录运行会校验pyproject.toml和core/存在检查.venv已创建然后通过exec uv run hive $把参数转发给真正的 CLI入口为 core/framework/cli.py 中的hiveconsole script见 core/pyproject.toml。Windows 对应的 hive.ps1 还会显式从 Windows 注册表加载用户级环境变量避免 VS Code 集成终端等新会话读不到 API Key 的问题。多平台安装Windows 与 AlpineWindows 原生PowerShell原生 Windows 直接运行.\quickstart.ps1需要注意 PowerShell 5.1 是硬性要求如果遇到 running scripts is disabled on this system 错误可以在当前会话先执行Set-ExecutionPolicy -Scope Process -ExecutionPolicy Bypass该策略仅对当前进程生效无需修改系统全局策略。Windows 通过 WSL 2如果更习惯 Linux 环境也可以使用 WSL安装 WSL 2在 PowerShell 中执行wsl --install打开 WSL 终端克隆仓库后运行./quickstart.sh。Alpine Linux含 Docker 场景在 Alpine Linux例如作为 Docker 容器基础镜像中使用时必须先安装系统依赖并且在运行安装脚本之前创建虚拟环境apk update apk add bash git python3 py3-pip nodejs npm curl build-base python3-dev linux-headers libffi-devPython 3.12 在 Alpine 上必须使用虚拟环境否则会触发 PEP 668 限制推荐用 uv 管理uv venv source .venv/bin/activate # uv 会自动处理 pip/setuptools/wheel无需手动安装然后运行./quickstart.shLLM 提供商配置quickstart.sh会在交互式菜单中帮助你完成默认 LLM 提供商的配置。从源码看它支持三类模式quickstart.sh订阅模式无需购买 API KeyClaude Code 订阅、ZAI Code、OpenAI Codex可触发 OAuth 登录、MiniMax Coding Key、Kimi Code、Hive LLM、AntigravityGoogle/Gemini 订阅。API Key 提供商AnthropicClaude、OpenAIGPT、Google Gemini、Groq、Cerebras、OpenRouter支持粘贴任意 OpenRouter 模型 ID 并自动去openrouter/前缀、DeepSeek。本地模型Ollamaollama list检测本地已拉取的模型无需 API Key。选择后会进行 API Key 的健康检查调用 scripts/check_llm_key.py并把配置写入~/.hive/configuration.json例如{ llm: { provider: anthropic, model: claude-sonnet-4-5-20250929, max_tokens: 8192, api_key_env_var: ANTHROPIC_API_KEY }, created_at: 2026-01-15T12:00:0000:00 }max_tokens默认值 8192 定义于framework.orchestrator.edge的DEFAULT_MAX_TOKENS常量每个 Agent 的RuntimeConfig启动时会读取该文件作为兜底。若主模型不支持视觉脚本还会询问是否配置一个vision_fallback视觉子代理用于给截图类工具返回的图像生成文字描述依据framework.llm.model_catalog的supports_vision标记判断见 core/framework/llm/model_catalog.py。除了 Anthropic框架还通过 LiteLLM 支持 100 提供商OpenRouter、Hive LLM、DeepSeek、Mistral、Together AI、xAI、Perplexity 等。不同提供商的provider/model/api_base写法差异详见 docs/configuration.md 中的示例段落。构建新 Agent 与运行流程环境就绪后就可以借助 Claude Code 或 Codex CLI 配合仓库内置的 Agent 构建技能来开发 Agent 了。1. 一次性安装 Claude Skills / MCP 工具./quickstart.sh该步骤会配置好 MCP 工具与构建 Agent 所需的工作流。2. 在 Cursor IDE 中启用 MCPMCP 工具同样可用于 Cursor打开命令面板CmdShiftP/CtrlShiftP运行MCP: Enable启用 MCP 服务器重启 Cursor让它从.cursor/mcp.json加载 MCP 服务器打开 Agent 聊天窗口确认 MCP 工具已可用。3. 构建 AgentClaude CodeUse the files-tools initialize_and_build_agent tool to scaffold a new agentCodex CLIStart Codex in the repo root and use the configured MCP tools按照交互提示依次完成定义 Agent 的目标goal设计工作流节点nodes用边edges连接节点在exports/下生成 Agent 包。这会产生开发所需的初始 Agent 目录结构。4. 定义 Agent 逻辑claude architecture guidance按提示理解 Agent 架构与文件结构定义目标、成功标准与约束了解节点类型当前为event_loop单类型并在使用工具前完成工具发现与校验。这一步确立构建 Agent 前的核心概念与规则。包结构与 uv Workspace 模式Hive 由三个 Python 包组成仓库的 pyproject.toml 通过[tool.uv.workspace] members [core, tools]声明了一个 uv workspacehive/ ├── .venv/ # 单一 workspace 虚拟环境由 uv sync 创建 ├── core/ # 核心框架运行时、图执行器、LLM 提供商 │ ├── framework/ │ └── pyproject.toml │ ├── tools/ # 工具与 MCP 服务器 │ ├── src/ │ │ └── aden_tools/ # 实际包位置 │ └── pyproject.toml │ ├── exports/ # 用户创建的 Agent 包gitignored │ └── your_agent_name/ # 通过 files-tools 工作流创建 │ └── examples/ └── templates/ # 预置模板 Agent为什么是单一 .venv在仓库根目录执行uv sync时uv 会创建一个位于根目录的单一.venv把core/与tools/两个包以及它们的所有依赖anthropic、litellm、beautifulsoup4、pandas 等统一解析、统一安装。这样带来三个好处单一环境无需在多个虚拟环境之间切换依赖统一core 与 tools 的包版本保持一致避免冲突开发简化只需激活一次即可访问全部能力。需要刷新环境时从仓库根目录重新执行uv sync跨包导入与 MCP 通信core与tools两个包刻意保持独立无交叉导入framework不直接 importaden_tools反之亦然通过 MCP 通信Agent 运行器在运行时通过 MCP 协议加载工具而不是 Python 直接导入测试场景若需要在单个脚本中同时使用两个包推荐用PYTHONPATH指定PYTHONPATHtools/src uv run python your_script.pyMCP 服务器配置仓库根目录的.mcp.json负责把 MCP 服务器注册到各包目录并通过uv run启动保证每个 MCP 服务器运行在正确的项目环境中{ mcpServers: { files-tools: { command: uv, args: [run, files_server.py, --stdio], cwd: tools }, tools: { command: uv, args: [run, mcp_server.py, --stdio], cwd: tools } } }当前仓库中实际存在的是 core/.mcp.json其内容为{ mcpServers: { tools: { command: python, args: [-m, aden_tools.mcp_server, --stdio], cwd: tools } } }其中tools服务器对外提供 Web 搜索、PDF 读取、CSV 处理等集成工具files-tools服务器files_server.py则暴露文件读写能力。更多 MCP 集成的细节可参考 core/MCP_INTEGRATION_GUIDE.md 与 core/MCP_BUILDER_TOOLS_GUIDE.md。为什么需要 PYTHONPATHframework与aden_tools以可编辑模式uv pip install -e安装因此全局可导入、不需要 PYTHONPATH但exports/下的 Agent没有作为包安装必须通过 PYTHONPATH 才能导入。这种设计让exports/中的 Agent 可以独立开发、独立版本控制、并作为独立包部署。开发工作流从搭建到运行完整的日常开发流程如下1. 初始化仅一次./quickstart.sh2. 构建 AgentClaude CodeUse the files-tools initialize_and_build_agent tool Enter goal: Build an agent that processes customer support tickets3. 校验 AgentPYTHONPATHexports uv run python -m your_agent_name validate4. 测试 Agentclaude test workflow5. 运行 Agent# 交互式 Dashboard hive open # 或直接运行 hive run exports/your_agent_name --input {task: ...}Windows 下校验 Agent 的等价写法$env:PYTHONPATHcore;exports python -m support_ticket_agent validate使用 Dummy Agents 进行端到端测试仓库内置了一套 dummy agent 测试套件文档描述位于core/tests/dummy_agents/用于对真实 LLM 提供商做端到端验证。它们不属于 CI——因为会发起真实 API 调用需要手动运行来确认执行器工作正常。运行方式cd core uv run python tests/dummy_agents/run_all.py脚本会自动检测可用的 LLM 凭据并提示你选择提供商你至少需要以下之一ANTHROPIC_API_KEYOPENAI_API_KEYGEMINI_API_KEYKIMI_API_KEYZAI_API_KEY一个 Claude Code、Codex 或 Kimi 订阅需要带实时 LLM 日志、工具调用与节点遍历详情的输出时cd core uv run python tests/dummy_agents/run_all.py --verbose测试覆盖范围Agent测试数覆盖内容echo2单节点生命周期、基础set_outputpipeline4多节点遍历、input_mapping、对话模式branch3条件边、LLM 驱动的路由parallel_merge4Fan-out/fan-in、失败策略retry4重试机制、重试耗尽、ON_FAILURE边feedback_loop3反馈回路、max_node_visitsworker4真实 MCP 工具get_current_time、save_data/load_data典型运行耗时 1–3 分钟取决于提供商延迟。运行单个测试文件也可以直接用 pytest 跑某个 dummy agent 测试cd core uv run pytest tests/dummy_agents/test_echo.py -v注意单独运行 pytest 需要先通过conftest.pyfixture 配置好 LLM 提供商run_all.py脚本会自动处理这一配置。环境变量速查LLM 运行必需export ANTHROPIC_API_KEYsk-ant-... export OPENROUTER_API_KEYyour-openrouter-key # 可选 export HIVE_API_KEYyour-hive-key # 可选quickstart 也支持交互式选择 OpenRouter 与 Hive LLM完整的配置示例见 docs/configuration.md。可选配置# Fernet 加密密钥用于 ~/.hive/credentials 凭据存储 export HIVE_CREDENTIAL_KEYyour-fernet-key # Agent 存储位置默认~/.hive/agents/{agent_name}/ export AGENT_STORAGE_PATH/custom/storage此外还有MOCK_MODE1不调用 LLM、仅做结构校验、BRAVE_SEARCH_API_KEY/EXA_API_KEYWeb 搜索工具等运行时开关详见 docs/configuration.md。故障排查手册externally-managed-environment 错误PEP 668原因Python 3.12 的 macOS/Homebrew、WSL 或部分 Linux 发行版禁止系统级 pip 安装。解决创建并使用虚拟环境# 创建虚拟环境 uv venv # 激活它 source .venv/bin/activate # macOS/Linux # .venv\Scripts\activate # Windows # 然后运行安装 ./quickstart.sh运行 Agent 前始终记得激活 venvsource .venv/bin/activate PYTHONPATHexports uv run python -m your_agent_name demoPowerShell: running scripts is disabled on this system每个会话执行一次Set-ExecutionPolicy -Scope Process -ExecutionPolicy BypassModuleNotFoundError: No module named framework解决从仓库根目录同步工作区依赖uv syncModuleNotFoundError: No module named aden_tools解决同样从仓库根目录执行uv sync或者直接跑安装脚本./quickstart.shModuleNotFoundError: No module named openai._models原因openai包版本过旧0.27.x与litellm不兼容。解决升级 openaiuv pip install --upgrade openai1.0.0No module named your_agent_name原因未在项目根目录运行、缺少 PYTHONPATH或 Agent 尚未创建。解决确保位于/hive/目录并使用PYTHONPATHexports uv run python -m your_agent_name validateAgent 导入失败broken installation症状pip list显示包指向不存在的目录。解决先卸载损坏的包再重新安装# 卸载损坏安装 uv pip uninstall framework tools # 正确重装 ./quickstart.sh相关文档docs/configuration.md全局配置、环境变量、Agent 级配置与 MCP 配置详解docs/getting-started.md构建 Agent 的入门指南docs/tools.md工具含未验证工具的启用方式INCLUDE_UNVERIFIED_TOOLStruedocs/architecture/README.md架构总览与 colony 运行机制docs/key_concepts/colony.md 与 docs/key_concepts/queen.mdcolony 与 Queen 核心概念环境搭建是使用 Hive 的第一步也是后续所有 Agent 开发的基础。如果你在安装过程中遇到问题优先对照上面的故障排查手册逐一核对——绝大多数问题都源于 Python 版本、虚拟环境或依赖同步这三个环节。赞分享人工智能AI Agent多智能体MCP 服务工具调用浏览器控制【免费下载链接】hiveMulti-Agent Harness for Production AI项目地址https://gitcode.com/gh_mirrors/hive48/hive点击查看免费下载相关推荐PR-Agent 开源贡献实战指南从 uv 环境搭建到 PR 合并的完整流程PR Agent 开源贡献实战指南从 uv 环境搭建到 PR 合并的完整流程 PR Agent 是一个开源的多 Git 平台 AI 代码评审工具核心代码位于人工智能AI Agent代码智能体代码评审AI 应用Hive 贡献指南全解读从环境搭建到性能基准的开源 AI Agent 框架协作实战Hive 贡献指南全解读从环境搭建到性能基准的开源 AI Agent 框架协作实战 Hive 是一个面向生产环境的开源多智能体Multi Agent框架人工智能AI Agent多智能体MCP 服务工具调用浏览器控制超实用pnpm workspace配置指南从0到1搭建prompt-optimizer开发环境超实用pnpm workspace配置指南从0到1搭建prompt optimizer开发环境 你还在为多包项目依赖管理头疼吗本地开发时模块引用总是出错构人工智能大模型提示工程AI 应用AI 评测创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考