GenericAgent 源码深度分析：3K 行自我进化的自主 Agent 框架

> 来源: GitHub - lsdefine/GenericAgent | arXiv 论文 2604.17091 | HuggingFace

> 日期: 2026-05-08

> 作者: lsdefine | 许可: MIT | 版本: V1.0 (2026-01-16)

> 语言: Python | Star: ~8.3K | arXiv: 2026-04-21

一句话版本

GenericAgent 是一个只有 3K 行代码的 AI Agent——它不预设任何技能，每帮你做一次新任务就把执行路径固化为"技能"，用越久能力越强，而且比同类模型省 6 倍的 token。

它和别的 Agent 有什么不同？

架构总览

┌─ 用户 ─────────────────────────────────────┐
│  IM前端 / TUI / Qt / Streamlit / DesktopPet │
└────────────────────┬───────────────────────┘
                     │
┌────────────────────▼───────────────────────┐
│          agentmain.py (GenericAgent 主循环)    │
│  ┌─ 任务队列 ──┐  ┌─ 9 原子工具(ga.py) ──┐  │
│  │ run() 线程  │ → │ code_run/file_*     │  │
│  │ 分派器     │   │ web_scan/execute_js  │  │
│  └────────────┘   │ ask_user/update_*    │  │
│                   │ start_long_term_*    │  │
│                   └──────────────────────┘  │
│  ┌─ agent_runner_loop (~150 行) ─────────┐  │
│  │  调用模型 → 解析工具调用 → 执行工具    │  │
│  │  → 回传结果 → 循环直到任务完成        │  │
│  └────────────────────────────────────────┘  │
│  ┌─ llmcore.py (~1000 行) ─────────────────┐  │
│  │  Claude / OpenAI / Gemini / Kimi / ...  │  │
│  │  MixinSession 多模型混合                │  │
│  │  自动上下文压缩（每5轮）                │  │
│  └──────────────────────────────────────────┘  │
└────────────────────────────────────────────────┘
                     │
┌────────────────────▼───────────────────────┐
│   四层记忆系统 (L0-L4)                      │
│  L0: 行为规则 (sys_prompt + 记忆管理 SOP)   │
│  L1: 极简索引 (≤30 行，高频技能→文件名)     │
│  L2: 全局事实 (路径/配置/凭证)              │
│  L3: 技能/SOP (memory/*.md, *.py)          │
│  L4: 历史会话 (L4_raw_sessions/)            │
└────────────────────────────────────────────┘

核心源码分析

一、Agent 执行循环 (`agent_loop.py`, ~150 行)

这是整个框架的"心脏"——极简且优雅：

def agent_runner_loop(client, system_prompt, user_input, handler, tools_schema, max_turns=40):
    messages = [
        {"role": "system", "content": system_prompt},
        {"role": "user", "content": user_input}
    ]
    
    while turn < handler.max_turns:
        # 1. 调用 LLM
        response = yield from client.chat(messages=messages, tools=tools_schema)
        
        # 2. 解析工具调用（或无工具回答）
        tool_calls = parse_tool_calls(response)
        
        # 3. 逐个执行工具
        for tc in tool_calls:
            outcome = yield from handler.dispatch(tool_name, args, response)
            if outcome.should_exit: break
            if not outcome.next_prompt: break  # 当前任务完成
        
        # 4. 构建下一轮的 prompt（包含工具结果）
        next_prompt = handler.turn_end_callback(...)
        messages = [{"role": "user", "content": next_prompt, "tool_results": tool_results}]
    
    return exit_reason

关键设计特点：

• 生成器架构：用 yield from 实现异步流程，运行时逐步产出输出
• 每 10 轮重置工具描述：client.last_tools = '' 防止上下文膨胀导致模型性能下降
• history 由 LLM 客户端维护：每轮只传最新消息，tool_results 携带之前结果

二、9 个原子工具 (`ga.py`, ~700 行)

GenericAgent 只预设了 9 个工具，这是它的全部初始能力：

关键设计：工具函数名带 do_ 前缀（如 do_code_run），BaseHandler.dispatch() 自动映射 code_run → do_code_run。

三、自我进化机制

这是 GenericAgent 最与众不同的设计：

新任务 → 9 原子工具探索执行 → 成功完成
    ↓
start_long_term_update() 触发固化流程
    ↓
系统提示 Agent 读取 memory_management_sop.md
    ↓
Agent 自主判断：
  - 这是环境事实？→ 写入 L2 (global_mem.txt)，同步 L1
  - 这是任务 SOP？→ 写入 L3 (memory/*_sop.md)，L1 加索引行
  - 没有可记忆的？→ 跳过
    ↓
未来类似任务 → 从 L1 索引快速定位 → 直接复用餐

示例（来自 README）：

使用几周后，你的 Agent 就拥有一个世界上独一无二的技能树。

四、四层记忆系统

L0 — 元规则 (系统提示 + memory_management_sop.md)

四条不可违背的公理：

1. 行动验证原则：只有成功的工具调用才能进记忆，"No Execution, No Memory"

2. 神圣不可删改性：已验证的数据不能丢弃

3. 禁止易变状态：不存时间戳/PID/临时路径

4. 最小充分指针：上层只留最短定位标识

L1 — 全局索引 (global_mem_insight.txt)

• ≤30 行硬约束（<1K tokens）
• 两层映射：高频场景 key→value + 低频仅关键词
• RULES 段：红线规则 + 高频犯错点

L2 — 事实库 (global_mem.txt)

环境特异性事实：路径、配置、凭证、ID 等

L3 — 技能/SOP 库 (memory/*.md, *.py)

随使用自然增长的技能集合。目前已包含：

• autonomous_operation_sop / memory_management_sop / plan_sop / verify_sop
• web_setup_sop / tmwebdriver_sop / vision_sop
• procmem_scanner_sop / supervisor_sop / subagent.md
• 工具脚本：adb_ui.py / ui_detect.py / ocr_utils.py / keychain.py
• 内置 skill_search 引擎

L4 — 历史会话存档 (L4_raw_sessions/)

scheduler 反射自动收集，可持续定位过往上下文。

五、LLM 客户端 (`llmcore.py`, ~1000 行)

支持模型：

• Claude (Anthropic Messages API) — NativeClaudeSession
• OpenAI/Gemini (Chat Completions API) — NativeOAISession
• MixinSession — 多模型混合（按规则分配不同子任务）

Token 节省机制：

每 5 轮压缩：
  <thinking>长内容 → <thinking>截断版...
  <tool_use>长参数 → <tool_use>截断版...
  <history>块 → <history>[...]
  
每 10 轮重置：
  client.last_tools = ''  // 清除工具描述缓存

热重载：修改 mykey.py 自动检测并重载。

六、浏览器控制 (TMWebDriver.py)

通过 Chrome DevTools Protocol (CDP) 和自定义 Chrome 扩展实现完整浏览器控制：

• Cookiejar 持久化（保留登录态）
• 页面简化提取（simphtml.py：过滤边栏、浮动元素、导航）
• JS 注入执行
• 禁用确认对话框 / 屏蔽 _blank 新窗口

七、前端多样性

GenericAgent 拥有异常丰富的前端支持：

技术亮点

1. 自我进化的实践性

GenericAgent 的自我进化不是概念空谈——它有完整的闭环：

• 固化时机：任务完成后自动触发 start_long_term_update
• 判断依据：memory_management_sop.md 中的信息分类决策树
• 写入粒度：最小化文件修改（patch 优先于 overwrite）
• 禁忌：不存未验证信息、不存易变状态、不存常识

2. 极致省 Token

6x 的 token 节省来源于三个层级的压缩：

1. 上下文压缩：每 5 轮智能截断历史

2. 记忆层级：L1 索引 ≤30 行，搜索不盲搜

3. 工具描述重置：防止模型被过大的 tools_schema 影响思考

3. 自我举证的勇气

README 的一句话很值得玩味：

> 🤖 Self-Bootstrap Proof — Everything in this repository, from installing Git and running git init to every commit message, was completed autonomously by GenericAgent. The author never opened a terminal once.

翻译：整个仓库（包括装 Git、git init、每一条 commit message）都是 GenericAgent 自己完成的——作者一次终端都没打开过。

这是对"自我进化"概念强有力的（尽管难以独立验证的）背书。

4. 四层记忆设计

L0-L4 的层级设计借鉴了人类记忆系统：

• L0 类似"本能"（系统规则）
• L1 类似"索引"（知道去哪找）
• L2 类似"事实"（世界知识）
• L3 类似"程序性记忆"（知道怎么做）
• L4 类似"情景记忆"（过去的事）

安全问题

与你的关联

GenericAgent 和你的 OpenClaw 体系有一些有趣的对比点：

值得借鉴的点：

1. 四层记忆系统的设计思路（特别是 L1 ≤30 行和 L0 公理）可以直接参考

2. 记忆的"行动验证原则" —— 只有验证过的信息才存入

3. 自动上下文压缩机制

4. 前端多样性（Desktop Pet 这种趣味设计）

评分

一句话再总结

> "GenericAgent 用 3K 行代码 + 9 个原子工具证明：Agent 不需要预设技能，一个好的四层记忆系统 + 自动进化机制就够了。用越久越聪明，而且每个用户的 Agent 都是独一无二的。"

报告生成时间: 2026-05-08 11:13 UTC

分析基于 lsdefine/GenericAgent main branch 源码 + arXiv 论文