MD 分类：AI与Agent 更新：2026/5/12

GenericAgent 架构分析

1. 项目定位

GenericAgent 是一个 极简、可自我进化的自主 Agent 框架。核心仅约 3000 行代码，通过 9 个原子工具 + 约 100 行 Agent Loop，赋予任意 LLM 对本地计算机的系统级控制能力。

设计哲学：不预设技能，靠进化获得能力。

每解决一个新任务，GenericAgent 将执行路径自动固化为 Skill，供后续直接调用。使用时间越长，沉淀的技能越多，形成完全属于用户的专属技能树。

自举实证 — 该仓库的一切，从安装 Git、git init 到每一条 commit message，均由 GenericAgent 自主完成。作者全程未打开过一次终端。

2. 技术栈

层次	技术选型
语言	Python（纯 Python，无重依赖）
LLM 接入	OpenAI 兼容 API / Claude API / 混合模式
浏览器控制	CDP（Chrome DevTools Protocol）注入真实浏览器
终端 UI	Textual（`tuiapp.py`）
桌面 UI	Qt / Streamlit
IM 接入	微信 / QQ / 飞书 / 企业微信 / 钉钉
移动控制	ADB（Android Debug Bridge）
包管理	`pip install`，`pyproject.toml`

3. 系统架构

graph TB
    subgraph Frontends["前端层 Frontends"]
        TUI["tuiapp.py<br/>终端 UI"]
        Qt["qtapp.py<br/>Qt 桌面"]
        ST["stapp2.py<br/>Streamlit"]
        WX["微信 Bot"]
        QQ["QQ Bot"]
        FS["飞书 Bot"]
        ACP["ACP Bridge<br/>Codeg 集成"]
    end

    subgraph Core["核心层 Core"]
        GA["ga.py<br/>GenericAgentHandler<br/>工具调度 + 记忆管理"]
        AL["agent_loop.py<br/>Agent Runner Loop<br/>约 100 行主循环"]
        AM["agentmain.py<br/>会话管理 + 启动"]
        LC["llmcore.py<br/>LLM 抽象层<br/>多后端统一接口"]
    end

    subgraph Tools["原子工具层"]
        CR["code_run<br/>执行任意代码"]
        FR["file_read"]
        FW["file_write"]
        FP["file_patch"]
        WS["web_scan<br/>感知网页"]
        WJ["web_execute_js<br/>控制浏览器"]
        AU["ask_user<br/>人机确认"]
        UWC["update_working_checkpoint"]
        SLT["start_long_term_update"]
    end

    subgraph Memory["记忆层 Memory"]
        GM["global_mem_insight.txt<br/>全局记忆洞察"]
        SK["skill_search/<br/>技能库"]
        SOP["*.sop.md<br/>标准操作流程"]
        L4["L4_raw_sessions/<br/>原始会话"]
    end

    subgraph Reflect["进化层 Reflect"]
        AUTO["autonomous.py<br/>自主执行"]
        SCH["scheduler.py<br/>定时调度"]
        GM_R["goal_mode.py<br/>目标模式"]
        WORK["agent_team_worker.py<br/>多 Agent 协作"]
    end

    subgraph External["外部能力"]
        Browser["Chrome 浏览器<br/>CDP 注入"]
        Terminal["系统终端"]
        FS_EXT["文件系统"]
        ADB_EXT["Android 设备"]
        API["外部 API"]
    end

    Frontends --> AM
    AM --> AL
    AL --> GA
    GA --> LC
    GA --> Tools
    Tools --> External
    GA --> Memory
    AM --> Reflect
    LC --> |"OpenAI / Claude / Mixed"| LLM["LLM API"]

4. 核心模块深度分析

4.1 Agent Loop（`agent_loop.py`）— 心脏

这是整个框架最核心的文件，仅约 100 行代码实现了一个完整的 ReAct 循环。

关键设计：

agent_runner_loop(client, system_prompt, user_input, handler, tools_schema, max_turns=40):
    while turn < max_turns:
        response = client.chat(messages, tools)
        if no tool_calls → 结束
        for each tool_call:
            outcome = handler.dispatch(tool_name, args)
            if outcome.should_exit → 结束
        messages.append(tool_results)

设计亮点：

每 10 轮重置工具描述：避免上下文过大导致模型性能下降
生成器模式：yield 流式输出，前端可实时展示进度
StepOutcome 抽象：统一工具返回格式（next_prompt + should_exit）
极简 dispatch：通过 do_{tool_name} 命名约定自动路由到 Handler 方法

4.2 GenericAgentHandler（`ga.py`）— 肌肉

Handler 是工具执行的实现层，承担三大职责：

工具执行：do_code_run、do_file_read、do_web_scan 等 9 个原子工具
记忆管理：工作记忆（working_checkpoint）+ 长期记忆（global_mem_insight）
回调机制：tool_before_callback → dispatch → tool_after_callback → turn_end_callback

记忆注入机制：

每次对话开始时，从 memory/global_mem_insight.txt 读取全局记忆
结合 assets/insight_fixed_structure.txt 的结构模板注入 System Prompt
工作记忆 key_info 跨会话持久化

4.3 LLM Core（`llmcore.py`）— 神经系统

统一的 LLM 抽象层，支持多种后端：

类	用途
`LLMSession`	OpenAI 兼容 API
`ClaudeSession`	Claude API（原生 tool_use）
`MixinSession`	混合模式（多个后端）
`NativeToolClient`	原生工具调用
`resolve_client`	自动解析配置选择后端

关键设计：

流式输出（streaming）贯穿全链路
_thinking_prompt() 处理 thinking 模型的特殊 prompt 格式
Tool result 统一转换为 Claude/OpenAI 兼容格式

4.4 记忆系统（`memory/`）— 长期记忆

memory/
├── global_mem_insight.txt          # 全局记忆洞察（自动维护）
├── global_mem_insight_template.txt # 洞察生成模板
├── skill_search/                   # 技能库
│   └── *.py                        # 固化的技能脚本
├── autonomous_operation_sop/       # 自主操作 SOP
├── *.sop.md                        # 各类标准操作流程
├── L4_raw_sessions/                # 原始会话存档
├── keychain.py                     # 密钥管理
├── adb_ui.py                       # Android UI 操作
├── ui_detect.py                    # UI 元素检测
└── ocr_utils.py                    # OCR 工具

进化路径：

Agent 遇到新任务 → 自主摸索执行
执行成功 → 将路径固化为 Skill（Python 脚本）
Skill 写入 memory/skill_search/
下次同类任务 → 直接调用已有 Skill
定期生成 global_mem_insight.txt 更新全局记忆

4.5 反思与进化（`reflect/`）— 大脑皮层

reflect/
├── autonomous.py           # 自主执行模式
├── scheduler.py            # 定时任务调度
├── goal_mode.py            # 目标驱动模式
└── agent_team_worker.py    # 多 Agent 协作 Worker

这是 GenericAgent 区别于其他 Agent 框架的核心差异层：

autonomous.py：Agent 可以自主规划和执行复杂任务
scheduler.py：支持定时/周期性任务
goal_mode.py：目标驱动的反思工作流
agent_team_worker.py：多 Agent 并行协作

5. 数据流

flowchart LR
    User["用户输入"] --> FE["前端<br/>(TUI/Qt/IM)"]
    FE --> AM["agentmain.py<br/>会话管理"]
    AM --> AL["agent_loop.py<br/>ReAct 循环"]

    AL --> |"messages + tools"| LLM["LLM API"]
    LLM --> |"response + tool_calls"| AL

    AL --> |"dispatch"| Handler["ga.py<br/>Handler"]
    Handler --> |"do_code_run"| Code["执行代码"]
    Handler --> |"do_file_*"| FS["文件系统"]
    Handler --> |"do_web_*"| Browser["浏览器 CDP"]
    Handler --> |"do_ask_user"| User

    Handler --> |"turn_end"| Memory["记忆系统"]
    Memory --> |"global_mem_insight"| AL

    subgraph 进化循环
        Handler --> |"固化 Skill"| Skill["skill_search/"]
        Skill --> |"下次直接调用"| Handler
    end

6. 请求链路（以”帮我点外卖”为例）

sequenceDiagram
    participant U as 用户
    participant FE as 前端
    participant AL as Agent Loop
    participant LLM as LLM
    participant H as Handler
    participant B as 浏览器

    U->>FE: "帮我点一杯奶茶"
    FE->>AL: 转发请求 + 注入记忆
    AL->>LLM: system_prompt + user_input + tools_schema

    loop ReAct 循环
        LLM->>AL: tool_call: web_scan(外卖APP)
        AL->>H: dispatch("web_scan")
        H->>B: CDP 注入截取页面
        B-->>H: 页面 DOM / 截图
        H-->>AL: StepOutcome(页面内容)
        AL->>LLM: tool_result

        LLM->>AL: tool_call: web_execute_js(点击奶茶)
        AL->>H: dispatch("web_execute_js")
        H->>B: CDP 执行 JS
        B-->>H: 操作结果
        H-->>AL: StepOutcome

        LLM->>AL: tool_call: ask_user(确认口味)
        AL->>H: dispatch("ask_user")
        H->>U: "要大杯还是中杯？"
        U-->>H: "大杯"
        H-->>AL: StepOutcome

        LLM->>AL: tool_call: web_execute_js(提交订单)
        AL->>H: dispatch("web_execute_js")
        H->>B: CDP 执行结账
        B-->>H: 订单确认
    end

    AL->>FE: 完成响应
    AL->>H: turn_end → 固化 Skill

7. 核心设计思想

7.1 极简主义（3K 行种子）

整个框架的核心代码仅约 3000 行，这是刻意为之：

9 个原子工具覆盖所有系统能力（代码执行 + 文件 + 浏览器 + 键鼠 + 视觉 + 移动）
通过 code_run 可动态扩展任何能力，无需预设
Agent Loop 约 100 行，无任何框架依赖

为什么这样做：越少的预设代码，越少的约束，越多的自由度。Agent 的能力上限不由框架决定，而由 LLM 决定。

7.2 自进化而非预编程

传统 Agent 框架（如 LangChain）预设了大量工具和 Chain，GenericAgent 反其道而行：

初始状态几乎是空白的
每解决一个问题，就产生一个 Skill
Skill 是真正的 Python 脚本，不是抽象的”Chain”
用得越久，Agent 越强——完全个性化的技能树

为什么这样做：预编程的工具永远无法覆盖所有场景，而 Agent 自己摸索出的方案往往更精准。

7.3 浏览器注入而非沙箱

不同于 Playwright/Puppeteer 的 headless 浏览器方案：

GenericAgent 通过 CDP 注入真实浏览器
保留用户登录态、Cookie、扩展
可以操作用户已登录的外卖、支付宝等应用

为什么这样做：真实场景需要真实登录态，沙箱浏览器无法做到。

7.4 记忆即进化

记忆系统分为多层：

工作记忆（working_checkpoint）：当前会话的关键信息
全局记忆洞察（global_mem_insight.txt）：跨会话的经验总结
技能库（skill_search/）：固化的执行方案
SOP 文档（*.sop.md）：标准操作流程

为什么这样做：无状态的 Agent 每次都从零开始，有记忆的 Agent 能站在自己的肩膀上。

8. Tradeoff

决策	收益	代价
极简代码量	易理解、易修改、低门槛	复杂场景需要 Agent 自己摸索
真实浏览器注入	保留登录态、真实环境	依赖 Chrome、CDP 稳定性
自进化 Skill	越用越强、个性化	初始阶段能力弱、需要”养”
纯 Python 无框架	零依赖、部署简单	缺少类型安全、工程化不足
单文件核心	极易理解	不适合大型团队协作
`code_run` 万能扩展	无限可能	安全风险、执行不可控

9. 可复用模式

9.1 ReAct 循环的极简实现

# 约 100 行实现完整的 ReAct 循环
while turn < max_turns:
    response = client.chat(messages, tools)
    if not response.tool_calls:
        break  # 无工具调用 → 结束
    for tc in response.tool_calls:
        outcome = handler.dispatch(tc.name, tc.args)
        if outcome.should_exit:
            break
    messages.append(tool_results)

9.2 命名约定路由

# 不需要注册表，通过命名约定自动路由
def dispatch(self, tool_name, args, response):
    method_name = f"do_{tool_name}"
    if hasattr(self, method_name):
        return getattr(self, method_name)(args, response)

9.3 Skill 固化模式

执行任务 → 记录执行路径 → 生成 Python 脚本 → 存入 skill 目录 → 下次直接调用

9.4 记忆注入 System Prompt

# 每次对话开始时注入记忆
system_prompt += get_global_memory()  # 从文件读取
# 包含：工作目录、全局洞察、技能列表、SOP 文档

10. 值得学习的重点

极简即力量：3000 行代码实现一个完整的自主 Agent，证明了 LLM 时代框架应该尽可能薄
自进化设计：不预设能力，让 Agent 自己学习和固化能力，这是一个深刻的设计哲学
真实环境交互：CDP 注入真实浏览器 + ADB 控制手机，比沙箱方案更实用
记忆驱动的个性化：每个用户的 Agent 最终会发展出完全不同的技能树
生成器模式的流式处理：yield 贯穿全链路，实现流式输出和实时反馈
回调钩子机制：tool_before_callback / tool_after_callback / turn_end_callback 提供了优雅的扩展点
code_run 作为万能扩展点：任何新能力都可以通过执行代码获得，无需修改框架

关联知识

ReAct Pattern — Agent Loop 的理论基础
Tool Use — LLM 工具调用机制
Chrome DevTools Protocol — 浏览器注入的技术基础
Agent Memory System — 记忆系统设计
Self-Evolving AI — 自进化 AI 的设计范式
LLM Agent Framework — Agent 框架对比（LangChain / AutoGPT / GenericAgent）
Streamlit — 桌面 UI 方案
Textual — 终端 UI 框架
ADB — Android 调试桥
Skill Tree — 技能树概念