跳到主要内容

Local Development

无论在什么平台上本地运行 MushroomAgent，以下事情是关键。

基线检查清单​

# 1. 检查 Python 版本
python3 --version          # 需 3.11+

# 2. 安装 uv（如未安装）
curl -LsSf https://astral.sh/uv/install.sh | sh

# 3. 克隆仓库并同步依赖
git clone <repo-url>
cd MushroomAgent
uv sync
source .venv/bin/activate

# 4. 初始化配置
mushroom-agent init

# 5. 在 ~/.mushroom_agent/config.yaml 中填写 API 密钥
#    llm.api_key: "sk-..."

# 6. 启动 agent
mushroom-agent start

# 7. 打开 http://127.0.0.1:7860/web

分平台常见问题​

Linux​

  • 端口被占用：如果 7860 端口被占用，使用 --port 9000
  • 缺少编译工具：uv sync 可能需要 python3-dev 或 build-essential
  • 文件权限：确保 ~/.mushroom_agent/ 目录可写

macOS​

  • 系统 Python 版本旧：macOS 内置 Python 3.9，通过 brew install python@3.12 安装新版
  • SSL 证书：遇到 SSL 错误请运行 /Applications/Python\ 3.12/Install\ Certificates.command
  • 路径问题：brew 安装的 Python 可能在 /opt/homebrew/bin/python3

Windows（原生）​

  • 路径分隔符：配置中使用正斜杠或转义反斜杠
  • 不支持 ~：使用绝对路径如 C:\Users\you\.mushroom_agent
  • 终端：推荐 PowerShell 或 Git Bash，避免 cmd.exe
  • 符号链接：部分 Python 包需要符号链接支持，在 Windows 设置中启用开发者模式

如果 mushroom-agent start 报错​

如果启动失败且怀疑是本地配置残留或损坏，可以重置后重新初始化：

rm -rf ~/.mushroom_agent
mushroom-agent init
mushroom-agent start

验证​

启动后，浏览器访问 http://127.0.0.1:7860/web 应能加载 UI。在聊天界面发送 "你好" — 几秒内应得到回复。如不正常，检查：

  • config.yaml 中 llm.api_key 是否有效
  • llm.base_url 是否对应正确的提供商
  • 防火墙是否拦截了 7860 端口