GenericAgent：仅 3K 行代码，让 AI 真正"住进"你的电脑，而且越用越聪明

读完这篇文章，你会明白：为什么一个只有 3000 行代码的项目，能让 AI 自主帮你点外卖、选股票、发微信、查账单——并且越用越懂你。

---

写在前面

你有没有过这样的体验：

• 让 AI 帮你点杯奶茶，它说"我无法访问外卖平台"
• 让 AI 帮你查查支付宝最近的大额支出，它说"我无法访问你的账户"
• 让 AI 帮你给微信好友群发消息，它说"我没有权限操作微信"

每次得到的回答都是——“对不起，我做不到。”

GenericAgent 就是来终结这一切的。

它不是一个聊天机器人，而是一个能真正操作你电脑和手机的 AI Agent。它能打开你的浏览器（带着你的登录状态），帮你下单；能通过 USB 连接你的安卓手机，帮你查账单；能在你的电脑上写代码、装软件、管理文件——就像一个坐在电脑前的真人助手。

更厉害的是：它会学习。第一次帮做某件事时可能需要摸索，但第二次就能直接调用之前的经验。用得越久，它越懂你。

听起来很复杂？但它的核心代码只有 3000 行。

怎么做到的？往下看。

---

一、GenericAgent 是什么？一句话解释

GenericAgent = 一个极简的"AI 驱动框架" + 9 个基础工具 + 自我进化能力

打个比方：

你可以把 GenericAgent 想象成一个刚入职的实习生。

公司只给了他 9 样工具：一台电脑（执行代码）、一个文件柜（读写文件）、一个浏览器（上网）、一部手机（操控安卓）、一支笔（记笔记）……外加一个"遇到不懂的就问老板"的特权。

刚来的时候，他什么都不会。但每完成一次任务，他就会把经验记在笔记本上。下次再遇到类似的任务，他直接翻笔记本就行。

三个月后，这个实习生已经积累了一套只有你们公司才有的工作方法论。

这就是 GenericAgent 的核心哲学：不预设技能，靠进化获得能力。

---

二、它到底能做什么？真实案例

不要只听我说，看看它实际能做到什么：

🧋 场景一：“帮我点一杯奶茶”

你对它说：“帮我点一杯奶茶。”

它就会：

1. 打开你电脑上的浏览器（注意：是你的真实浏览器，淘宝/美团都是已登录状态）
2. 自动导航到外卖页面
3. 搜索奶茶、选择商品、确认下单
4. 整个过程完全自主，你只需要说一句话

这不是演示视频里的特效，而是 GenericAgent 的日常操作。

📈 场景二：“帮我筛选创业板金叉股票”

你说：“找出创业板 EXPMA 金叉、换手率大于 5% 的股票。”

它会：

1. 第一次：自己安装量化分析库（比如 mootdx），写选股脚本，跑数据，把整个流程固化为一个"Skill"
2. 第二次：你说同样的话，它直接调用之前保存的 Skill，几秒钟出结果

这就是"自我进化"——第一次是学习，之后是肌肉记忆。

💰 场景三：“查一下支付宝近三个月超过 2000 元的支出”

它通过 ADB（Android Debug Bridge）连接你的手机，然后：

1. 打开支付宝 App
2. 导航到账单页面
3. 筛选金额和日期
4. 汇总结果告诉你

你的手机插着 USB 线连着电脑，AI 就像你的手一样在手机上滑动、点击。

💬 场景四：批量发微信消息

需要在微信上给 20 个人发同样的通知？

它直接驱动你电脑上的微信客户端，一个一个聊天窗口打开，粘贴消息，发送。全程不需要你动一下鼠标。

🌐 场景五：定时网页监控

“每天早上 8 点帮我看看这几个网站有没有更新，汇总成一段话发给我。”

它配置好定时任务，到点自动打开网页、提取关键信息、生成摘要。你早上起来直接看结果就行。

---

三、为什么它这么强？拆解核心架构

很多人可能会问：3000 行代码能干这么多事？是不是在吹牛？

不是。秘密在于它的架构设计。让我用最通俗的语言解释。

3.1 只有 9 个工具，但能组合出无限可能

GenericAgent 只给 AI 提供了 9 个最基础的工具：

#	工具名	通俗解释	比喻
1	code_run	执行任意代码（Python/PowerShell）	实习生的电脑，什么软件都能装
2	file_read	读取文件	打开文件柜看资料
3	file_write	写入/创建文件	往文件柜里放新资料
4	file_patch	精确修改文件的某一部分	用涂改液改文件上的某一行
5	web_scan	"看"网页上有什么内容	实习生的眼睛
6	web_execute_js	在网页上执行操作（点击、输入等）	实习生的手在网页上操作
7	ask_user	遇到不确定的事，问你	"老板，这个确认一下？
8	update_working_checkpoint	记短期便签（防遗忘）	手边的便利贴
9	start_long_term_update	把重要经验写入长期记忆	记进工作手册

你可能会想：就这？9 个工具能干什么？

关键在于第 1 个工具——code_run。这个工具可以执行任意代码。也就是说：

• 需要安装一个新的 Python 包？→ code_run 执行 pip install
• 需要写一个自动化脚本？→ code_run 创建脚本文件
• 需要调用某个 API？→ code_run 写请求代码
• 需要控制硬件？→ code_run 调用系统命令

code_run 是图灵完备的，理论上能做任何计算机能做的事。 其余 8 个工具是为了让 AI 更方便地与文件系统、浏览器和用户交互，避免所有操作都绕道写代码。

这就像给实习生一台电脑——只要有电脑，他什么都能学、什么都能做。其他工具只是让他做事更方便的"快捷方式"。

3.2 分层记忆：为什么它不会"健忘"

大多数 AI Agent 都有一个致命问题：上一轮对话做的事，下一轮就忘了。 你昨天教它的东西，今天它完全没印象。

GenericAgent 用了一套 5 层记忆系统来解决这个问题：

L0  元规则        →  "我是一个助手，我不能做坏事"（基本行为准则）
L1  记忆索引      →  "我的技能目录在第二页，文件搜索方法在第五页"（目录）
L2  全局事实      →  "用户的电脑是 Windows，常用编辑器是 VSCode"（常识）
L3  任务技能/SOP  →  "选股的完整流程是：装mootdx → 拉数据 → 计算 → 筛选"（方法论）
L4  会话归档      →  "上周二帮用户做过一次报表，用的是 pandas 方案"（历史）

用一个生活化的比喻：

• L0 就像你的道德观——“我是好人，不能骗人”
• L1 就像你书架上的目录卡片——“想找菜谱？去第三层左边”
• L2 就像你的常识——“我家住在北京，上班坐地铁”
• L3 就像你的技能证书——“我会做红烧肉，步骤是……”
• L4 就像你的日记本——“2024年3月15日，我做了一份红烧肉，味道不错”

最关键的是：L1 只是索引，不是全部内容。每次执行任务时，Agent 只加载需要的部分到上下文中，不会把所有记忆都塞进去。

这就是为什么 GenericAgent 的上下文窗口只有不到 30K Token，而其他 Agent 要用 200K 到 100 万 Token。

💡 通俗理解 Token 消耗：你可以把上下文窗口想象成 AI 的"工作台"。工作台越大，桌上堆的东西越多，找东西就越慢，还容易拿错。GenericAgent 的做法是：工作台很小，但有一个高效的档案柜（记忆系统），需要什么拿什么，用完放回去。

3.3 核心循环：整个 Agent Loop 只有约 100 行代码

GenericAgent 的核心执行逻辑只有大约 100 行代码（在 agent_loop.py 中），它的运转方式非常简洁：

循环开始：
  ① 感知当前环境（文件系统有什么、浏览器在什么页面、上一步做了什么）
  ② 思考下一步该做什么（LLM 推理）
  ③ 调用工具执行（9 个原子工具中的一个或多个）
  ④ 把这一步的经验写入记忆
  ⑤ 检查：任务完成了吗？完成了就停止，没完成回到第①步

就这么简单。没有复杂的编排引擎，没有多 Agent 协商，没有繁琐的状态机。

为什么这么简单还能完成复杂任务？因为复杂度不在框架里，而在 LLM 的推理能力里。框架只需要提供"手"和"眼"，"大脑"的工作交给 LLM。

3.4 浏览器控制：为什么它能操作你的真实账号

这是一个很多人关心的问题，也是 GenericAgent 的一大亮点。

大多数 Agent 框架（比如 OpenClaw）使用的是无头浏览器（headless browser）或沙箱环境。什么意思呢？就是在一个虚拟的、干净的浏览器里操作。问题在于：你没有登录态。想操作淘宝？先登录。想查 Gmail？先登录。每次都要重新来。

GenericAgent 的做法完全不同：它通过一个浏览器插件（Chrome Extension），注入你正在使用的真实浏览器。

这意味着：

• ✅ 你在淘宝上已经登录了？Agent 直接就能用
• ✅ 你的 GitHub 已经登录了？Agent 直接就能操作
• ✅ 你的 B 站有会员？Agent 看的视频也是会员画质

不是模拟一个浏览器，而是直接控制你的浏览器。 这就像——别的框架给 AI 配了一台新电脑，而 GenericAgent 让 AI 直接用你的电脑。

---

四、自我进化：它最与众不同的地方

这是 GenericAgent 和所有其他 Agent 框架最大的区别。

4.1 什么是自我进化？

用一个表格说清楚：

你说的指令	第一次做	第二次做	第三次做
“帮我监控股票”	安装量化库 → 写选股代码 → 测试 → 配置定时任务 → 保存 Skill	直接调用 Skill	直接调用 Skill
“用 Gmail 发文件”	配置 OAuth → 写发送脚本 → 保存 Skill	直接调用 Skill	直接调用 Skill
“每周生成一份周报”	摸索数据来源 → 写模板 → 保存 Skill	直接调用 Skill	直接调用 Skill

第一次是"学习"，之后是"条件反射"。

4.2 技能是怎么保存的？

当 GenericAgent 第一次完成一个复杂任务后，它会自动：

1. 提炼出关键步骤（不是把整个对话保存，而是提取方法论）
2. 写成一个 SOP（Standard Operating Procedure，标准操作流程）文件
3. 存入 memory/ 目录（这就是 L3 层记忆）
4. 在 L1 索引中登记：“如果用户说 XXX，调用 memory/xxx_sop.md”

下次你提到类似的任务，Agent 先查索引，找到对应的 SOP，然后按照 SOP 执行。

4.3 这意味着什么？

用几周后，你的 Agent 实例将拥有一套任何人都没有的专属技能树。

你的 Agent 擅长做量化分析，你朋友的 Agent 擅长做文案排版。因为你们交给它的任务不同，它进化的方向就不同。

这就像养了一只宠物——你训练它做什么，它就擅长什么。每只宠物都是独一无二的。

---

五、跟其他 Agent 框架比，好在哪里？

我把 GenericAgent 和当前最主流的几个 Agent 框架做了对比：

对比项	GenericAgent	OpenClaw	Claude Code
代码量	~3K 行	~530,000 行	大型开源项目
部署难度	pip install + 填 API Key	需要编排多个服务	CLI + 订阅制
浏览器控制	注入真实浏览器，保留登录态	无头浏览器/沙箱	通过 MCP 插件间接控制
能控制手机吗	能（ADB）	不能	不能
能操作键鼠吗	能	间接（多Agent委派）	不能
会记住经验吗	会，自动沉淀 Skill	靠插件生态	不会，会话间无状态
Token 消耗	~30K	200K~1M	中等
出厂自带什么	几个核心文件 + 少量初始 Skills	数百个预装模块	丰富的 CLI 工具集
开源协议	MIT	各有不同	开源

关键差异解读

1. “真浏览器” vs “假浏览器”

GenericAgent 操作的是你正在用的 Chrome/Edge，不是另起一个干净的浏览器。这就像——你要让助手帮你发一封邮件，OpenClaw 的做法是"先给助手注册一个新邮箱"，而 GenericAgent 的做法是"让助手直接坐在你的电脑前用你的邮箱"。

2. “有记忆” vs “无记忆”

Claude Code 每次开一个新的对话，之前做的事情全忘了。GenericAgent 会把经验保存下来，下次直接用。这就像——一个每次见面都要重新自我介绍的同事 vs 一个跟你合作了三年的老搭档。

3. “3K 行” vs “53 万行”

代码量少意味着什么？

• ✅ 部署简单：不依赖一堆服务，不会因为某个组件挂了而整体崩溃
• ✅ 容易理解：你想了解它是怎么工作的，花一天时间就能读完所有代码
• ✅ 方便定制：想改什么直接改，不用担心牵一发动全身

---

六、评测数据：不只是自说自话

GenericAgent 的技术报告（已发布在 arXiv 上）从五个维度进行了严格评测：

#	评测维度	通俗解释	对比的基线
1	任务完成度 & Token 效率	花更少的钱，做同样难的事	Claude Code、OpenAI CodeX、OpenClaw
2	工具使用效率	9 个简单工具 vs 一堆专用工具，哪个更好用？	同上
3	记忆系统有效性	精简分层记忆 vs 暴力塞入所有历史，哪个更准？	含 Embedding 检索器的方案
4	自我进化能力	做完一次后，第二次真的变快了吗？	9 轮纵向实验
5	网页浏览能力	在真实的网页上能准确找到信息吗？	WebCanvas 等基准

关键发现：

• 🏆 工具使用效率：GenericAgent 在 Token 消耗、API 请求次数、工具调用次数上全面领先，同时任务完成质量不降
• 🏆 跨任务自我进化：在 8 个不同的 Web 任务上，GenericAgent 的第二轮执行成本大幅下降，第三轮趋于稳定——证明"进化"是真实有效的

💡 简单来说就是：花更少的钱，做同样甚至更好的事，而且越做越便宜。

---

七、怎么上手？手把手教你

方法一：一键安装（推荐给非程序员）

Windows 用户，打开 PowerShell，粘贴这行命令：

powershell -ExecutionPolicy Bypass -c "irm http://fudankw.cn:9000/files/ga_install.ps1 | iex"

Mac / Linux 用户：

curl -fsSL http://fudankw.cn:9000/files/ga_install.sh | bash

它会自动帮你：

• 准备一个独立的 Python 环境（不污染你系统里的 Python）
• 下载 GenericAgent 项目文件
• 安装桌面端 GUI

安装完成后，双击 frontends/GenericAgent.exe（Windows）就能启动。

方法二：手动安装（推荐给开发者）

# 1. 克隆项目
git clone https://github.com/lsdefine/GenericAgent.git
cd GenericAgent

# 2. 创建虚拟环境
uv venv

# 3. 安装依赖
uv pip install -e ".[ui]"

# 4. 配置 API Key（复制模板，填入你的密钥）
cp mykey_template.py mykey.py
# 用编辑器打开 mykey.py，填入你的 LLM API Key

# 5. 启动！
python launch.pyw

⚠️ Python 版本推荐用 3.11 或 3.12，不要用 3.14（有些依赖不兼容）。

配置 API Key 的小贴士

mykey.py 里怎么填？核心规则很简单：

# 如果你的 API 是 OpenAI 兼容格式（大多数国内中转站都是这种）：
oai_config = {
    'apikey': 'sk-你的密钥',
    'apibase': 'http://你的API地址:端口',
    'model': '模型名称',
}

# 如果你用的是 Claude API：
claude_config = {
    'apikey': 'sk-ant-你的密钥',
    'apibase': 'https://你的API地址:端口',
    'model': 'claude-sonnet-4-20250514',
}

# 如果你用的是 MiniMax：
oai_minimax_config = {
    'apikey': 'eyJh...',
    'apibase': 'https://api.minimax.io/v1',
    'model': 'MiniMax-M2.7',
}

规则就是看变量名：名字里含 oai 就走 OpenAI 格式，含 claude 就走 Claude 格式。填哪个用哪个，不用的删掉或留着不管都行。

第一次启动后试试这些

帮我在桌面创建一个 hello.txt，内容是 Hello World

请查看你的代码，安装所有用得上的 python 依赖

帮我解锁当前用户的 PowerShell ps1 执行权限     （Windows 用户）

执行 web setup sop，解锁 web 工具               （解锁浏览器控制）

用rapidocr配置你的ocr能力并存入记忆             （让 AI 能"看到"屏幕文字）

全部只需要对话，不需要你手动操作任何东西。

---

八、多种使用方式，总有一款适合你

🖥️ 桌面端 GUI（最推荐）

双击 frontends/GenericAgent.exe，会出现一个桌面悬浮窗，直接在里面打字发指令就行。

⌨️ 终端 TUI（程序员最爱）

python frontends/tuiapp_v2.py

一个基于 Textual 的终端界面，支持多会话并发、实时流式输出、历史导航。有终端就能跑，不需要 GUI 环境。

💬 IM Bot（随时随地控制）

GenericAgent 支持接入主流聊天平台，你在手机上发消息，电脑上的 Agent 就会执行：

平台	怎么启动
微信	python frontends/wechatapp.py
QQ	python frontends/qqapp.py
Telegram	python frontends/tgapp.py
飞书	python frontends/fsapp.py
企业微信	python frontends/wecomapp.py
钉钉	python frontends/dingtalkapp.py

想象一下：你在地铁上用微信给 Agent 发一句"帮我把桌面上的报告发到我的邮箱"，等你到公司，报告已经在邮箱里了。

🐾 桌面宠物（最有趣）

GenericAgent 还有一个桌面宠物模式！Agent 以一个可爱的小形象（恐龙、小猫、线条小人等多种皮肤可选）驻留在你的桌面上。你随时可以跟它互动。

---

九、进阶玩法

定时任务

查看你的代码，告诉我你的计划任务模式怎么启用

配置好后，你可以让 Agent 定时执行任务，比如"每天早上 9 点帮我看看天气预报并总结"。

自主探索模式

查看你的代码，告诉我你的自主探索模式怎么启用

Agent 会自己上网浏览、探索信息、定时汇总。适合监控类任务。

子 Agent 编排

查看你的代码，告诉我你的 subagent 模式怎么启用

可以派生出多个子 Agent 并行处理不同的任务。

反射模式

agentmain --reflect your_script.py

Agent 会监控你的脚本运行状态，出现异常时自动介入处理。

💡 所有高级模式都不需要查文档——直接问 Agent 自己就行。这就是"代码即文档"的理念：Agent 能读懂自己的源码，任何功能你都可以直接问它。

---

十、社区和生态

GenericAgent 已经有了非常活跃的社区：

• 📘 Datawhale 官方教程：Hello Generic Agent —— 手把手教你从零开始
• 📖 飞书图文教程：新手引导
• 🔧 Skill Hub（百万级技能库）：Sophub —— 别人沉淀的技能你也可以直接用
• 🏛️ 政务应用：“政务龙虾” DintalClaw —— GenericAgent 在政务领域的落地案例
• 📰 机器之心报道：被国内顶级 AI 媒体报道
• 💬 微信交流群：已经到第 18 个群了，活跃度非常高

社区还自发开发了多个 GUI 客户端：

• ga-manager
• galley

---

十一、我的个人思考

研究完 GenericAgent 之后，我有三点很深的感触：

1. 少即是多

3000 行代码能做的事情，53 万行代码的框架也能做。但 3000 行代码带来的可维护性、可理解性、可定制性，是 53 万行永远比不了的。

好的架构不是"功能越来越多"，而是"用越来越少代码做越来越多的事"。

2. 信息密度 > 信息量

GenericAgent 的上下文不到 30K Token，却能做到比 200K~1M Token 的框架更好的效果。为什么？因为它不往"工作台"上堆垃圾，而是有一个高效的"档案柜"（分层记忆系统），需要什么拿什么。

这给我们的启发是：与其给 AI 更大的窗口，不如给 AI 更好的记忆力。

3. 进化 > 预设

大多数框架的思路是"出厂预装尽可能多的功能"。GenericAgent 的思路是"出厂只装最基础的，剩下的在使用中自己长出来"。

前者的问题在于：预装的功能你未必用得到，真正需要的功能又未必预装了。后者则保证了——Agent 擅长的永远是你真正需要的。

---

总结

最后用一张表总结 GenericAgent 的核心亮点：

亮点	一句话
🧬 自我进化	每次任务自动沉淀 Skill，越用越聪明，形成你的专属技能树
🪶 极简架构	3000 行核心代码，好部署、好理解、好定制
⚡ 真实控制	注入你的真实浏览器 + 键鼠操控 + ADB 手机控制
💰 极致省钱	上下文不到 30K Token，成本比别人低一个数量级
🔌 广泛兼容	支持 Claude/Gemini/Kimi/MiniMax 等多模型，Windows/Mac/Linux 跨平台
💬 随时随地	微信/QQ/飞书/钉钉/Telegram 都能接入，手机发指令电脑执行

项目地址： https://github.com/lsdefine/GenericAgent

技术报告： https://arxiv.org/abs/2604.17091

新手教程： Datawhale Hello GenericAgent

如果觉得有帮助，给项目点个 Star ⭐，也欢迎在评论区交流你的使用体验！

---

免责声明：本文基于 GenericAgent 开源项目（MIT License）撰写，旨在技术分享与交流。