GenericAgent 怎么安装？本地自主 Agent 使用教程

安装最容易卡住的场景，是电脑里已经有 Python，于是直接在现有环境里跑命令，结果 pywebview 报错、桌面端白屏，才发现版本是 3.14。GenericAgent 可以在本地建立可编辑的自主 Agent 环境；它不是 PyPI 上直接安装的普通应用，也不该混进你日常项目的 Python 环境。

先把版本和目录卡死

官方项目声明的 Python 范围是 >=3.10,<3.14，安装文档更推荐 3.11 或 3.12。准备 Git、uv、一个模型 API Key，以及不存放重要资料的独立目录。若只能使用 Python 3.14，先停在这里；强行继续通常会把依赖错误拖到界面启动阶段，排查成本更高。

用源码路径完成一次干净安装

1. 克隆仓库。在准备好的父目录执行下面两行。若 Git 访问失败，先解决网络或代理问题，不要改用来历不明的压缩包。

   git clone https://github.com/lsdefine/GenericAgent.git
   cd GenericAgent

2. 建立隔离环境。明确指定 3.12，能避免系统默认版本悄悄变化。

   uv venv --python 3.12
   source .venv/bin/activate

   Windows PowerShell 的激活命令是 .venv\Scripts\Activate.ps1。若执行策略拦截脚本，不要关闭整机安全策略，改用当前终端的临时授权或直接让 uv 在环境中运行。

3. 安装核心与界面依赖。

   uv pip install -e ".[ui]"

   -e 保留源码可编辑状态，[ui] 加入 Streamlit、桌面和终端界面所需组件。若 Linux 缺少 GTK 或 WebKit，桌面依赖可能失败；无桌面服务器应改走 TUI，不必硬装图形栈。

Key 只放进本地配置

复制模板后再编辑，不要把示例值当成真实密钥：

cp mykey_template.py mykey.py

按模板注释选择 OpenAI 兼容接口或 Anthropic Claude 原生接口。配置向导也可以用 python assets/configure_mykey.py 启动。失败时先核对服务商的接口地址、模型名和余额；把完整 Key 粘到聊天记录或终端截图里，会让一次配置问题变成凭证泄露。

先验证内核，再打开界面

安装完成不等于可用。先确认模块能导入，并记下当前提交：

python -c "import agent_loop; print('OK')"
git rev-parse --short HEAD

看到 OK 后，可选择桌面入口 python launch.pyw，或运行 python frontends/tui_v3.py。若桌面窗口没有出现，先看终端报错；Windows 上还要检查本机回环连接是否被防火墙拦截。只盯着白屏反复重启，无法区分是界面、端口还是依赖问题。

把第一次任务缩到足够小

首次启动后，不要直接下达“接管电脑”这类宽泛指令。可以先让它读取测试目录里的两个文本文件，生成摘要并保存到新文件。成功标准包括：只访问指定目录、没有覆盖原文件、结果能人工复核。若连这个任务都越界或卡住，就先修权限与提示词，不要继续开放浏览器登录态和键鼠控制。

• Python 显示 3.11 或 3.12；
• agent_loop 导入成功；
• mykey.py 已配置但未进入版本库；
• 至少一个前端能启动；
• 测试任务在隔离目录内完成且可复核。

这五项都成立，才算得到一个可继续训练工作流的本地 GenericAgent，而不只是装好了一堆包。