手把手教你了解并使用Generic Agent：3300行代码打造的自进化AI Agent
2026年1月，复旦大学联合深圳Aquaintelling Technology的A3实验室开源了一个名为Generic Agent（GA）的项目。仅3300行Python代码，配合9个原子工具和一个92行的Agent主循环，就能赋予任何大模型对本地计算机的系统级控制能力——浏览器、终端、文件系统、键鼠输入、屏幕视觉，甚至移动设备。
更令人惊讶的是，这个Agent会”自我进化”：每次完成新任务后，自动将执行路径固化为可复用的技能，使用时间越长，积累的技能树越丰富，执行效率越高。
本文将从零开始，带你全面了解Generic Agent的设计理念、核心架构、安装配置和实战使用。
一、Generic Agent是什么？
Generic Agent是一个极简、可自我进化的自主AI Agent框架。它的核心设计哲学可以用一句话概括：“不预加载技能，而是让技能自我进化。”
传统的Agent框架（如LangChain、AutoGen、CrewAI）通常需要开发者预先定义大量的工具和技能，然后通过复杂的编排逻辑将它们组合起来。Generic Agent反其道而行——它只提供9个最基础的原子工具，其他所有能力都通过Agent自主探索、学习、沉淀获得。
打个比方：传统Agent框架像是给AI一本厚厚的操作手册，而Generic Agent像是给AI一双会学习的手——第一次做新任务时自己摸索，成功后把方法记下来，下次直接用。
二、核心架构：五层记忆 + 九个工具 + 一个循环
2.1 五层分层记忆系统
Generic Agent最核心的设计是五层分层记忆系统（L0-L4），这是它实现极低Token消耗的关键。
| 层级 | 名称 | 说明 | 加载方式 |
|---|---|---|---|
| L0 | Meta Rules | 核心行为规则和系统约束（”我是谁”） | 始终加载 |
| L1 | Insight Index | 最小化路由索引，用于快速召回技能 | 始终加载 |
| L2 | Global Facts | 长期运行积累的稳定知识（”用户是谁”） | 按需加载 |
| L3 | Task Skills | 可复用的工作流和可执行脚本（”我会什么”） | 按需路由 |
| L4 | Session Archive | 已完成会话的蒸馏记录 | 按需召回 |
关键设计亮点：默认只加载L0+L1，这意味着即使Agent积累了1000个技能，对最简单的”你好”请求，起步也只需要约2000 Token，而传统框架可能需要17000 Token起步。这就是Generic Agent声称实现6倍Token节省的核心原因。
2.2 九个原子工具
Generic Agent只提供9个最基础的原子工具，覆盖所有核心操作：
| 工具 | 功能 | 典型用途 |
|---|---|---|
| code_run | 执行任意代码（Python/PowerShell） | 动态安装包、数据处理、自动化脚本 |
| file_read | 读取文件 | 查看配置、读取日志、分析代码 |
| file_write | 写入/创建文件 | 生成脚本、保存结果、创建配置 |
| file_patch | 精确修改文件 | 手术级代码编辑、配置修改 |
| web_scan | 感知网页内容 | 抓取网页、提取信息 |
| web_execute_js | 通过JS控制浏览器 | 点击按钮、填写表单、页面交互 |
| ask_user | 人工确认 | 关键决策前征求用户同意 |
| update_working_checkpoint | 保存工作检查点 | 短期记忆持久化 |
| start_long_term_update | 固化为Skill | 将经验写入长期记忆 |
注意：任何不在上述列表中的能力，都通过code_run在运行时动态创建。比如Agent需要连接数据库，它会自己写一个数据库连接脚本，执行成功后固化为Skill，下次直接调用。
2.3 Agent主循环（92行代码）
Generic Agent的整个认知循环只有92-100行代码，映射为一个8步循环：
- 感知：通过web_scan、file_read、屏幕视觉等收集环境信息
- 理解：LLM推理，分析当前状态和目标
- 行动：调用9个原子工具之一执行操作
- 反馈：获取工具执行结果和环境变化
- 差异分析：隐含在LLM推理中，判断是否达成目标
- 理解更新：保存工作检查点
- 记忆：将成功经验固化为Skill
- 记忆影响：分层记忆自动注入后续推理的上下文
三、安装与配置：从零开始
3.1 环境要求
- Python 3.11 或 3.12（注意：不支持3.14，与pywebview不兼容）
- 操作系统：Windows、macOS、Linux均可
- 至少一个LLM的API Key（支持Claude/GPT/Gemini/Kimi/MiniMax等）
3.2 快速安装（一行命令）
Windows PowerShell：
powershell -ExecutionPolicy Bypass -c "$env:GLOBAL=1; irm http://fudankw.cn:9000/files/ga_install.ps1 | iex"
Linux / macOS：
GLOBAL=1 bash -c "$(curl -fsSL http://fudankw.cn:9000/files/ga_install.sh)"
3.3 开发者安装
如果你更希望了解项目结构，推荐使用开发者安装方式：
- 克隆仓库：
git clone https://github.com/lsdefine/GenericAgent.git - 进入目录：
cd GenericAgent - 创建虚拟环境：
uv venv（推荐使用uv包管理器） - 安装依赖：
uv pip install -e ".[ui]" - 配置API Key：
cp mykey_template.py mykey.py，然后编辑填入你的LLM API配置 - 启动桌面应用：
python launch.pyw - 或启动终端UI：
python frontends/tuiapp_v2.py
3.4 配置API Key详解
Generic Agent本身不提供LLM服务，需要自备API Key。在mykey.py中配置，支持以下模型提供商：
| 提供商 | 推荐模型 | 说明 |
|---|---|---|
| Anthropic | Claude Opus 4.6 / Sonnet 4.6 | 编程能力最强，推荐首选 |
| OpenAI | GPT-5.5 / GPT-5.4 | 生态成熟，兼容性好 |
| Gemini 3.1 Pro | 长上下文优势 | |
| 月之暗面 | Kimi K2.6 | 中文场景优化，性价比高 |
| MiniMax | MiniMax-01 | 有专用PyPI分发包 |
| OpenAI兼容端点 | Ollama / vLLM / LM Studio | 本地模型部署 |
如果你使用国内中转服务，需要设置fake_cc_system_prompt: True，GA会根据变量名自动判断协议格式。
四、多前端支持：不只是桌面应用
Generic Agent提供了丰富的前端适配器，远不止桌面GUI：
| 前端 | 启动命令 | 适用场景 |
|---|---|---|
| 桌面应用（Streamlit） | python launch.pyw | 日常使用，可视化操作 |
| 终端UI（Textual） | python frontends/tuiapp_v2.py | 开发者偏好，轻量快速 |
| Telegram Bot | python frontends/tgapp.py | 移动端远程控制 |
| 微信Bot | python frontends/wechatapp.py | 微信生态集成 |
| 飞书Bot | python frontends/fsapp.py | 企业办公场景 |
| QQ Bot | python frontends/qqapp.py | QQ生态集成 |
| 企业微信 | python frontends/weworkapp.py | 企业微信集成 |
| 钉钉Bot | python frontends/dingtalkapp.py | 钉钉生态集成 |
多个Bot可以同时运行，共享同一个memory/目录，实现跨平台上下文一致。这意味着你在微信上让Agent学到的技能，在Telegram上也能直接使用。
五、实战演示：让Agent帮你点外卖
为了让你直观感受Generic Agent的能力，这里展示一个典型的使用场景。
场景：帮我在美团点一杯奶茶
你只需要对Agent说一句话：”帮我点一杯少糖的杨枝甘露”。接下来Agent会自主完成以下步骤：
- 首次执行（探索模式）：Agent通过web_scan打开美团外卖网页，使用web_execute_js模拟点击和滚动，找到目标商品，填写地址信息，提交订单。整个过程可能需要2-5分钟和多次LLM调用
- 技能固化：订单完成后，Agent自动调用start_long_term_update，将整个操作流程固化为一个名为”点外卖”的Skill，保存到memory/skills/目录下
- 后续执行（技能模式）：下次你说”帮我点一杯咖啡”，Agent直接调用已有的”点外卖”Skill，30秒内完成。无需重新探索
这就是Generic Agent自进化能力的核心价值：第一次慢，之后快。使用时间越长，积累的技能树越丰富，Agent变得越来越”聪明”。
六、更多实战场景
除了点外卖，Generic Agent还能处理大量复杂的实际任务：
| 场景 | 操作流程 | 关键工具 |
|---|---|---|
| 量化选股 | 安装mootdx -> 构建筛选条件 -> 导出结果 | code_run |
| 支付宝记账查询 | 通过ADB操控手机 -> 查询消费记录 -> 筛选金额 | code_run + ADB |
| Gmail发送文件 | 配置OAuth -> 编写发送脚本 -> 保存为Skill | code_run |
| 批量微信消息 | 操控微信客户端 -> 遍历联系人 -> 发送消息 | web_execute_js |
| 股票监控预警 | 安装数据源 -> 构建监控逻辑 -> 配置定时任务 | code_run |
| 网页内容监控 | 定期访问目标网页 -> 提取关键信息 -> 变化时通知 | web_scan + code_run |
| 读取微信聊天记录 | 安装依赖 -> 反编译数据库 -> 编写读取脚本 -> 保存Skill | code_run |
七、与其他Agent框架的对比
2026年的Agent框架百花齐放。Generic Agent在其中占据了一个独特的位置。
| 维度 | Generic Agent | LangGraph | AutoGen | CrewAI | Claude Code |
|---|---|---|---|---|---|
| 核心代码量 | 约3300行 | 大 | 大 | 中等 | 闭源 |
| 设计理念 | 极简+自进化 | 图状态机 | 多Agent对话 | 角色任务团队 | 编码Agent |
| 自进化能力 | 核心特性 | 不支持 | 不支持 | 不支持 | 不支持 |
| 多Agent协作 | 不支持 | 核心优势 | 核心优势 | 核心优势 | 不支持 |
| Token消耗 | 小于30K | 依赖设计 | 依赖设计 | 依赖设计 | 200K-1M |
| 系统控制 | 浏览器/终端/文件/键鼠/ADB | 通过工具 | 通过工具 | 通过工具 | 文件+终端 |
| IM集成 | 微信/QQ/飞书/Telegram等 | 无 | 无 | 无 | 无 |
| 许可证 | MIT开源 | 开源 | 开源 | 开源 | 商业 |
简单来说：如果你需要多Agent协作编排，选LangGraph或CrewAI；如果你需要最强的编程Agent，选Claude Code；如果你需要一个极简、自进化、能控制整个操作系统的通用Agent，选Generic Agent。
八、使用最佳实践
- 从简单任务开始：不要一上来就让Agent做复杂任务。先从”帮我创建一个文件夹”这种简单操作开始，验证基本流程正常
- 善用Skill沉淀：每次Agent成功完成新任务后，确认它正确固化了Skill。可以在memory/skills/目录下查看已学习的技能
- 定期清理记忆：随着使用时间增长，memory/目录会积累大量Skill。定期检查并清理过时或失效的技能（网站改版可能导致技能失效）
- 设置用户白名单：如果使用IM Bot模式，务必设置用户白名单，避免未授权人员控制你的Agent
- 使用中转服务：国内用户推荐使用API中转服务，更便宜也更稳定。记得设置fake_cc_system_prompt: True
- 让Agent自己解决问题：遇到缺少依赖的情况，直接告诉Agent”请帮我安装所有需要的Python依赖”，它会通过code_run自动处理
- 利用ask_user控制关键决策：对于涉及资金、数据删除等高风险操作，Agent会自动调用ask_user征求你的确认
九、已知局限与注意事项
Generic Agent虽然设计精巧，但也有一些需要注意的局限：
- 冷启动慢：首次执行新任务需要2-5分钟和大量LLM调用，因为Agent需要自主探索解决方案
- 技能脆弱性：已固化的Skill可能因外部环境变化而失效（如网站改版、API变更），需要定期维护
- 无内置沙箱：code_run以OS用户权限执行任意代码，存在安全风险。建议在虚拟机或Docker中运行
- 不支持多Agent：设计上为单Agent架构，不适合需要Agent协作的复杂工作流
- 中文生态优先：文档和社区讨论以中文为主，英文资源相对有限
- 模型调优偏向：Kimi和MiniMax效果最佳，使用Claude或Gemini可能需要调整prompt
十、学习资源推荐
| 资源 | 链接 | 说明 |
|---|---|---|
| GitHub仓库 | github.com/lsdefine/GenericAgent | 源码、文档、Issue |
| 技术报告 | arxiv.org/abs/2604.17091 | 学术论文，详细阐述设计理念 |
| Datawhale中文教程 | datawhalechina.github.io/hello-generic-agent/ | 最权威的中文教程，分应用/原理/案例三部分 |
| PyPI分发包 | pypi.org/project/genericagent-minimax | MiniMax模型专用版 |
| 社区Skill库 | GitHub社区 | 百万级技能库，可直接导入 |
十一、写在最后：Agent的未来是”进化”而非”编排”
Generic Agent代表了一种不同于主流Agent框架的设计哲学。当其他框架在追求更多的工具、更复杂的编排、更大的上下文窗口时，Generic Agent选择了另一条路：极简的工具集、高效的记忆分层、自主的技能进化。
这种”少即是多”的思路，在2026年Agent框架日益复杂的背景下，显得尤为珍贵。它提醒我们：Agent的核心价值不在于能调用多少工具，而在于能否从经验中学习、能否用最少的资源做出最聪明的决策。
如果你对AI Agent感兴趣，Generic Agent是一个极好的学习对象——3300行代码，你可以从头到尾读完、理解、修改、扩展。这比研究那些动辄数十万行代码的企业级框架，更能帮你理解Agent的本质。
