lsdefine--genericagent/README.md

<!-- WEHUB_ZH_README -->
> [!NOTE]
> 本文档由 WeHub 基于上游 README 翻译整理，属于社区翻译，非官方中文文档。  
> [English](./README.en.md) · [原始项目](https://github.com/lsdefine/GenericAgent) · [上游 README](https://github.com/lsdefine/GenericAgent/blob/HEAD/README.md)  
> 原作者、版权与许可证归属以原始项目及本仓库 LICENSE 文件为准。

<div align="center">

<img src="assets/images/bar.jpg" width="880" alt="GenericAgent Banner"/>

# GenericAgent

**极简、可自我进化的自主智能体框架**

*约 3K 行种子代码 · 9 个原子工具 · 约 100 行的 Agent Loop*

<p>

  <a href="https://gaagent.ai"><img src="https://img.shields.io/badge/Official_Website-gaagent.ai-00A67E?style=flat-square" alt="Official Website"/></a>
  <a href="https://arxiv.org/abs/2604.17091"><img src="https://img.shields.io/badge/Technical_Report-PDF-EA4335?style=flat-square&logo=adobeacrobatreader&logoColor=white" alt="Technical Report"/></a>
  <a href="https://github.com/JinyiHan99/GA-Technical-Report"><img src="https://img.shields.io/badge/Code_%26_Data-Reproduction-181717?style=flat-square&logo=github" alt="Reproduction Repo"/></a>
  <a href="https://datawhalechina.github.io/hello-generic-agent/"><img src="https://img.shields.io/badge/Tutorial-Datawhale-blue?style=flat-square" alt="Tutorial"/></a>
  <a href="https://fudankw.cn/sophub"><img src="https://img.shields.io/badge/Skill_Hub-Sophub-purple?style=flat-square" alt="Sophub"/></a>
</p>

<p>
  <a href="https://trendshift.io/repositories/25944" target="_blank"><img src="https://trendshift.io/api/badge/repositories/25944" alt="Trendshift" style="width: 250px; height: 55px;" width="250" height="55"/></a>
</p>

**[English](#-english) · [中文](#-中文)**

</div>

> 📌 **官方渠道：** 仅 GitHub + https://gaagent.ai。DintalClaw 是唯一授权商业合作伙伴；其他均非关联方。

---

<a id="-english"></a>

## 🌟 概览

**GenericAgent** 是一个极简、可自我进化的自主智能体（Autonomous Agent）框架。其核心仅 **约 3K 行代码**。通过 **9 个原子工具 + 约 100 行的 Agent Loop**，它赋予任意 LLM 对本地计算机的系统级控制能力——覆盖浏览器、终端、文件系统、键盘/鼠标输入、屏幕视觉以及移动设备（ADB）。

> 设计理念 —— **不预加载技能，而是让它们进化。**

每当 GenericAgent 完成一项新任务，它会自动将执行路径凝结为可复用的 **Skill（技能）**。使用越久，积累的技能越多——最终形成一棵完全由 3K 行种子代码生长而来的个人技能树。

> 🤖 **自举证明（Self-Bootstrap Proof）** —— 本仓库中的一切，从安装 Git、运行 `git init`，到每一条 commit message，均由 GenericAgent 自主完成。作者从未打开过终端。

### 📑 目录

- [核心特性](#-key-features)
- [演示展示](#-demo-showcase)
- [快速开始](#-quick-start)
- [使用方式](#-usage)
- [解锁高级能力](#-unlocking-advanced-capabilities)
- [架构](#-architecture)
- [自我进化机制](#-self-evolution-mechanism)
- [对比](#-comparison)
- [评测](#-evaluation)
- [路线图与动态](#-roadmap--news)
- [社区与支持](#-community--support)
- [许可证](#-license)

---

## 📋 核心特性

| 特性 | 说明 |
| :--- | :--- |
| 🧬 **自我进化** | 自动将每项任务凝结为 Skill。能力随使用不断增长，形成你的个人技能树。 |
| 🪶 **极简架构** | 核心代码约 3K 行。Agent Loop 约 100 行。无复杂依赖，零部署开销。 |
| ⚡ **强执行力** | **TMWebdriver** 注入真实浏览器（保留登录会话）。9 个原子工具直接控制系统。 |
| 🔌 **高兼容性** | 支持 Claude / Gemini / Kimi / MiniMax 及其他主流模型。跨平台。 |
| 💰 **Token 高效** | 上下文窗口 <30K —— 仅为其他智能体消耗的 200K–1M 的一小部分。更少噪声、更少幻觉、更高成功率、更低成本。 |

---

## 🎯 演示展示

<table>
  <tr>
    <td align="center" width="50%"><b>🛡️ 真实浏览器 CAPTCHA 通关</b></td>
    <td align="center" width="50%"><b>🌐 自主网页探索</b></td>
  </tr>
  <tr>
    <td><img src="assets/demo/discord_hcaptcha_real_browser.gif" width="100%" alt="Discord hCaptcha passed in real browser"></td>
    <td><img src="assets/demo/autonomous_explore.png" width="100%" alt="Web Exploration"></td>
  </tr>
  <tr>
    <td><sub>配置 Discord 机器人时，任务中途弹出 hCaptcha <i>"Are you human?"</i> 验证 —— GA 的真实浏览器会话通过验证，任务继续。参见 <a href="#browser-realness-of-ga-web-tools">Browser Realness</a>。</sub></td>
    <td><sub>自主浏览并定期汇总网页内容。</sub></td>
  </tr>
  <tr>
    <td align="center"><b>🧋 外卖点单</b></td>
    <td align="center"><b>📈 量化选股</b></td>
  </tr>
  <tr>
    <td><img src="assets/demo/order_tea.gif" width="100%" alt="Order Tea"></td>
    <td><img src="assets/demo/selectstock.gif" width="100%" alt="Stock Selection"></td>
  </tr>
  <tr>
    <td><sub><i>"Order me a milk tea"</i> —— 导航外卖应用、选择商品、完成结账。</sub></td>
    <td><sub><i>"Find GEM stocks with EXPMA golden cross, turnover &gt; 5%"</i> —— 量化筛选。</sub></td>
  </tr>
  <tr>
    <td align="center"><b>💰 记账查账</b></td>
    <td align="center"><b>💬 批量发消息</b></td>
  </tr>
  <tr>
    <td><img src="assets/demo/alipay_expense.png" width="100%" alt="Alipay Expense"></td>
    <td align="center"><img src="assets/demo/wechat_batch.png" width="65%" alt="WeChat Batch"></td>
  </tr>
  <tr>
    <td><sub><i>"Find expenses over ¥2K in the last 3 months"</i> —— 通过 ADB 驱动支付宝。</sub></td>
    <td><sub>批量发送微信消息，完全驱动微信客户端。</sub></td>
  </tr>
</table>

---

## 🚀 快速开始

> ⚠️ **Python 版本**：请使用 **Python 3.11 或 3.12**。**不要**使用 Python 3.14 —— 它与 `pywebview` 及少数其他 GA 依赖不兼容。
>
> 📖 详细安装指南：**[installation.md](docs/installation.md)** · **[installation_zh.md（中文）](docs/installation_zh.md)**

### 面向 LLM 智能体

获取安装指南并按步骤操作：

```bash
curl -fsSL https://raw.githubusercontent.com/lsdefine/GenericAgent/refs/heads/main/docs/installation.md
```

### 面向人类用户

#### 方法 1 — 克隆并安装 *（推荐）*

```bash
git clone https://github.com/lsdefine/GenericAgent.git && cd GenericAgent
uv venv && uv pip install -e ".[ui]"
cp mykey_template_en.py mykey.py   # fill in your LLM API key
```

依赖刻意分层：智能体核心仅需 `requests`，另加四个轻量包（`beautifulsoup4`、`bottle`、`simple-websocket-server`、`aiohttp`）用于 TMWebdriver 本地服务。`[ui]` 额外依赖会拉取前端库（Streamlit、用于 TUI 的 `prompt_toolkit`/`rich`，……）—— 若需捆绑 UI 请安装，也可完全跳过并以无头模式驱动智能体。无需 Playwright、LangChain，也无需下载浏览器二进制文件。

然后启动：

```bash
python frontends/tui_v3.py   # Terminal UI (recommended)
python launch.pyw            # Streamlit web UI
```

#### 方法 2 — 一行安装 *（便捷）*

会搭建一个自包含目录，内含隔离的 Python 环境、Git 和可直接运行的包。脚本位于 [`assets/`](assets/)，如需可先阅读。

**Windows PowerShell**

```powershell
powershell -ExecutionPolicy Bypass -c "$env:GLOBAL=1; irm https://raw.githubusercontent.com/lsdefine/GenericAgent/main/assets/ga_install.ps1 | iex"
```

**Linux / macOS**

```bash
GLOBAL=1 bash -c "$(curl -fsSL https://raw.githubusercontent.com/lsdefine/GenericAgent/main/assets/ga_install.sh)"
```

> 💡 GenericAgent 通过 **智能体自身** 来扩展环境 —— 不要预先安装一切。参见下方 [解锁高级能力](#-unlocking-advanced-capabilities)。

---

## 💻 使用方式

### 前端

#### 终端 UI *（推荐）*

基于 `prompt_toolkit` + `rich` 构建的轻量、以滚动回显为先的终端界面。支持多会话并发与实时流式输出。

```bash
python frontends/tui_v3.py
```

<details>
<summary><b>⚠️ Windows TUI 故障排查</b></summary>

Windows 上的 TUI 渲染可能因终端与字体而异而不稳定。常见原因：

1. `prompt_toolkit` / `rich` 不是最新版本 — 请先使用 `pip install -U prompt_toolkit rich`。
2. PowerShell / cmd 自带的终端对 Unicode 与快捷键支持较差。**在 Windows 上更推荐使用 Git Bash**，表现要好得多。
3. 如果显示仍然有问题，可以让 GA 自行修复：
   > *"我在 Windows 的 PowerShell / cmd / Git Bash 中使用 `frontends/tui_v3.py` 的体验非常差 — 存在大量不兼容。请参考 Claude Code 针对 Windows 终端的最佳实践，修复所有字体与渲染不兼容问题。"*

</details>

#### Streamlit UI

```bash
python launch.pyw
```

### Bot Interface (IM)

GenericAgent 还支持 Telegram、Discord、Lark 等 IM 前端。

| Platform | Command |
| :--- | :--- |
| Telegram | `python frontends/tgapp.py` |
| Discord | `python frontends/dcapp.py` |
| Lark / Feishu | `python frontends/fsapp.py` |

> 也支持微信、QQ、企业微信和钉钉 — 见下方中文章节。
> 详细配置请直接询问 GenericAgent 本身。

---

## 🔓 解锁高级能力

在 GA 中，高级能力通过**向智能体下达指令**来解锁，而非阅读文档或安装额外组件。下面每条指令都会让 GA 读取其预装的 SOP（标准作业程序，Standard Operating Procedure；经实战检验、存于其记忆中的 playbook），安装缺失项、适配你的操作系统，并将结果持久化到自身记忆中。

| Capability | Just tell GA |
| :--- | :--- |
| 🌐 Web automation | *"Set up your web automation capability."* — GA 会引导你完成唯一的手动步骤：将捆绑的 Chrome 扩展拖入 `chrome://extensions`。 |
| 🔤 OCR | *"Set up your OCR capability with rapidocr and save it to memory."* |
| 👁️ Vision | *"Set up your vision capability from the template in memory/."* — GA 会复制模板、接入你现有的 LLM 密钥并自行测试。 |
| 🖱️ Computer use | *"Probe this system and set up your computer-use capability."* |

> 💡 **关于语言**：预装 SOP 以中文撰写 — GA 可原生阅读，因此不会阻碍你使用。若你希望知识库为英文，只需说：
> *"Read your pre-installed SOPs and rewrite them in English (keep code, paths and error strings verbatim)."*
>
> 🌍 **关于平台**：SOP 在 Windows 上打磨成熟，但跨平台适配本身也是 GA 的任务 — 在 macOS/Linux 上，GA 会自行替换为对应平台的等价能力（窗口枚举、输入控制、截图等）。遵循同样的自进化原则。

---

## 🧠 架构

GenericAgent 通过**分层记忆 × 极简工具集 × 自主执行循环**完成复杂任务，并在执行过程中持续积累经验。

### 1️⃣ 分层记忆系统

> *记忆在任务执行全程不断结晶，使智能体能够随时间建立稳定、高效的工作模式。*

| Layer | Name | Description |
| :---: | :--- | :--- |
| **L0** | Meta Rules | 核心行为规则与系统约束 |
| **L1** | Insight Index | 用于快速路由与召回的极简记忆索引 |
| **L2** | Global Facts | 长期运行中积累的稳定知识 |
| **L3** | Task Skills / SOPs | 完成特定任务类型的可复用工作流 |
| **L4** | Session Archive | 从已完成会话中提炼并归档的任务记录，用于长程回忆 |

### 2️⃣ 自主执行循环

> *感知环境状态 → 任务推理 → 执行工具 → 将经验写入记忆 → 循环*

整个核心循环仅约 **~100 行代码**（[`agent_loop.py`](agent_loop.py)）。

### 3️⃣ 极简工具集

> *GenericAgent 仅提供 **9 个原子工具**，构成与外部世界交互的基础能力。*

| Tool | Function |
| :--- | :--- |
| `code_run` | 执行任意代码（Python / PowerShell） |
| `file_read` | 读取文件 |
| `file_write` | 写入 / 创建 / 覆盖文件 |
| `file_patch` | 修补 / 修改文件 |
| `web_scan` | 感知网页内容 |
| `web_execute_js` | 控制浏览器行为 |
| `ask_user` | 人在回路（Human-in-the-loop）确认 |
| `update_working_checkpoint` | *（memory）* 短期工作记事本 |
| `start_long_term_update` | *（memory）* 提炼长期记忆 |

### 4️⃣ 能力扩展

> *能够动态创建新工具。*

通过 `code_run`，GenericAgent 可在运行时动态安装 Python 包、编写新脚本、调用外部 API 或控制硬件 — 将临时能力结晶为永久工具。

<div align="center">
  <img src="assets/images/workflow.jpg" alt="GenericAgent Workflow" width="420"/>
  <br/><em>GenericAgent 工作流示意图</em>
</div>

---

## 🧬 自进化机制

这正是 GenericAgent 与其他智能体框架的根本区别。

```text
[New Task]
   │
   ▼
[Autonomous Exploration]   ─►  install deps · write scripts · debug · verify
   │
   ▼
[Crystallize into Skill]   ─►  write to memory layer
   │
   ▼
[Direct Recall on Next Similar Task]
```

| What you say | First time | Every time after |
| :--- | :--- | :--- |
| *"Read my WeChat messages"* | 安装依赖 → 逆向数据库 → 编写读取脚本 → 保存 Skill | **一行调用** |
| *"Give me a morning digest of Hacker News"* | 编写爬虫 → 构建摘要 → 安排每日运行 → 保存 Skill | **一行调用** |
| *"Monitor stocks and alert me"* | 安装 `mootdx` → 构建选股流程 → 配置 cron → 保存 Skill | **一行启动** |
| *"Send this file via Gmail"* | 配置 OAuth → 编写发送脚本 → 保存 Skill | **即可使用** |

几周之后，你的智能体实例将拥有一棵世界上独一无二的技能树 — 全部从 3K 行种子代码生长而来。

---

## 📊 对比

| Feature | **GenericAgent** | OpenClaw | Claude Code |
| :--- | :---: | :---: | :---: |
| **Codebase** | ~3K lines | ~530,000 lines | Open-sourced (large) |
| **Deployment** | `pip install` + API Key | Multi-service orchestration | CLI + subscription |
| **Browser Control** | Real browser (session preserved) | Sandbox / headless browser | Via MCP plugin |
| **OS Control** | Mouse/kbd, vision, ADB | Multi-agent delegation | File + terminal |
| **Self-Evolution** | Autonomous skill growth | Plugin ecosystem | Stateless between sessions |
| **Out of the Box** | Few core files + starter skills | Hundreds of modules | Rich CLI toolset |

---

## 📈 评测

> 📂 完整评测数据集与结果：[**JinyiHan99/GA-Technical-Report**](https://github.com/JinyiHan99/GA-Technical-Report/tree/main)

我们从 **五个维度** 评测 GenericAgent：

| # | Dimension | Question | Benchmarks |
| :---: | :--- | :--- | :--- |
| 1 | **Task Completion & Token Efficiency** | GA 能否比主流智能体更便宜地完成困难任务？ | SOP-Bench, Lifelong AgentBench, RealFin-Benchmark |
| 2 | **Tool-Use Efficiency** | 极简原子工具集能否以更低开销解决专用工具集所能解决的问题？ | Tool Efficiency Benchmark (11 simple + 5 long-horizon) |
| 3 | **Memory System Effectiveness** | 凝练的分层记忆能否优于完整/冗余记忆与基于嵌入的检索器？ | SOP-Bench (dangerous goods), LoCoMo, 20-skill stress test |
| 4 | **Self-Evolution Capability** | 智能体能否在无人工干预的情况下将经验提炼为可复用的 SOP 与代码？ | 9-round LangChain longitudinal study, 8-task cross-task web benchmark |
| 5 | **Web Browsing Capability** | 密度驱动设计能否在开放互联网上经受考验？ | WebCanvas, BrowseComp-ZH, Custom Tasks (22) |

各维度的基线包括 **Claude Code**、**OpenAI CodeX** 和 **OpenClaw**，在 *Claude Sonnet 4.6*、*Claude Opus 4.6*、*GPT-5.4* 与 *MiniMax M2.7* 骨干模型下评测。

<table>
  <tr>
    <td align="center" width="50%">
      <img src="assets/images/result_radar.png" width="100%" alt="Tool-use efficiency radar"/><br/>
      <sub><b>工具使用效率雷达图。</b> GA 在 token、请求与工具调用轴上占主导，同时在四个任务维度上保持质量。</sub>
    </td>
    <td align="center" width="50%">
      <img src="assets/images/result_convergence.png" width="100%" alt="Cross-task self-evolution convergence"/><br/>
      <sub><b>跨任务自进化。</b> GA 第二、第三次运行在八个网页任务上收敛至稳定的低成本区间，而 OpenClaw 未出现此类收敛。</sub>
    </td>
  </tr>
</table>

### GA Web Tools 的浏览器真实性（TMWebdriver）

GA Web Tools 由 **TMWebdriver** 驱动 —— 本地 WebSocket 服务器加 Chrome 扩展 —— 在**真实、持久的 Chrome/Chromium 会话**中运行，而非一次性无头沙箱，从而保留 cookies、登录状态、扩展、GPU/WebGL 行为以及正常的浏览器会话指纹。

| 检测服务 / 信号 | 普通无头自动化 | GA Web Tools | 备注 |
| :--- | :---: | :---: | :--- |
| SannySoft 无头测试 | 常被检测到 | ✅ 56/56 通过 | `bot.sannysoft.com` |
| bot.incolumitas.com | 常在 webdriver / CDP 检查中失败 | ✅ 36/36 通过 | `WEBDRIVER`、`SELENIUM_DRIVER`、`webDriverAdvanced` 均正常 |
| BrowserScan 机器人检测 | 常显示异常 | ✅ 正常 | `browserscan.net` |
| Device & Browser Info 机器人测试 | 多项机器人标记 | ✅ 人类 / `isBot=false` | `deviceandbrowserinfo.com` |
| FingerprintJS 机器人检测演示 | 常被检测到 | ✅ 通过 | 演示流程完成，无机器人判定 |
| reCAPTCHA v3 演示 | 低机器人相似度分数 | ✅ 0.9 人类相似度分数 | 基于分数的风险信号；0.9 高于典型生产环境阈值 |

对于 reCAPTCHA v3，`0.9` 并非「复选框已解决」的结果；它是风险模型返回的高置信度人类相似度分数，通常足以在生产流程中避免额外验证挑战。

---

## 📅 路线图与最新动态

- **2026-05-23** — 🆕 **TUI v3 发布**（`frontends/tui_v3.py`）。基于块的滚动回溯、正确的调整大小重排、用于跨终端一致性的每终端配色方案，以及与 v2 的功能对等。
- **2026-05-18** — 🆕 **Morphling 模式**。项目级技能吸收 —— 从任意外部仓库提取目标与测试，再按组件决定：调用、重写或丢弃。详见 `memory/morphling_sop.md`。
- **2026-05-17** — 🆕 **Goal Hive 模式**。多 Worker 协作式 Goal 模式 —— 由 BBS 协调的 master/workers 并行运行长期目标。详见 `memory/goal_hive_sop.md`。
- **2026-05-15** — 🖥️ **桌面 GUI 发布**。一行安装即可交付开箱即用的桌面应用（`frontends/GenericAgent.exe`）。开发者通过 `python launch.pyw` 启动。
- **2026-05-14** — 🆕 **Conductor 子 Agent 编排**。生成、监督并自动清理并行子 Agent；一等委托原语，补充 `/btw` 侧问题。
- **2026-05-12** — 🆕 **TUI v2 发布**（`frontends/tuiapp_v2.py`）。精炼的 Textual 前端，支持图片粘贴折叠、文件粘贴、块删除、Ctrl+C 复制、历史导航，以及 `/llm` / `/export` / `/continue` 选择器。
- **2026-05-08** — 🆕 **Goal 模式**（`reflect/goal_mode.py`）。时间预算驱动的自主循环 ——「在 N 小时内持续优化 X」，不会提前交付。
- **2026-04-21** — 📄 [**arXiv 技术报告**](https://arxiv.org/abs/2604.17091) — *GenericAgent: A Token-Efficient Self-Evolving LLM Agent via Contextual Information Density Maximization*。
- **2026-04-11** — 引入 **L4 会话归档记忆**与调度器 cron 集成。
- **2026-03-23** — 支持个人微信作为机器人前端。
- **2026-03-10** — [发布百万级 Skill 库](https://mp.weixin.qq.com/s/q2gQ7YvWoiAcwxzaiwpuiQ?scene=1&click_id=7) *(Chinese)*.
- **2026-03-08** — [发布「Dintal Claw」—— 由 GenericAgent 驱动的政务机器人](https://mp.weixin.qq.com/s/eiEhwo-j6S-WpLxgBnNxBg) *(Chinese)*.
- **2026-03-01** — [获机器之心（Jiqizhixin）报道](https://mp.weixin.qq.com/s/uVWpTTF5I1yzAENV_qm7yg) *(Chinese)*.
- **2026-01-16** — GenericAgent **V1.0** 公开发布。

---

## ⭐ 社区与支持

如果本项目对你有帮助，欢迎点个 **Star！** 🙏

### 🚩 友情链接

感谢 **LinuxDo** 社区的支持！

[![LinuxDo](https://img.shields.io/badge/Community-LinuxDo-blue?style=for-the-badge)](https://linux.do/)

**社区 GUI** *(独立开源项目)*：

- [chilishark27/ga-manager](https://github.com/chilishark27/ga-manager)
- [wangjc683/galley](https://github.com/wangjc683/galley) — 开箱即用的本地 Agent 工作台，捆绑 GA 运行时（CPython 3.11 + 依赖），原生 GUI/CLI，多会话 + Project 编排，本地优先。
- [FroStorM/A3Agent](https://github.com/FroStorM/A3Agent/tree/workbench)
- [Fwind43/GenericAgent-Admin](https://github.com/Fwind43/GenericAgent-Admin) — Go + React 桌面管理面板：服务生命周期管理、原生聊天、Goal 模式、BBS 团队看板、文件编辑器、模型配置向导、TMWebDriver 监控、自更新，以及 Windows 托盘/桌面宠物集成。

---

## 📄 许可

基于 **MIT License** 分发。完整文本见 [`LICENSE`](LICENSE)。

> *免责声明：GenericAgent 官方渠道为本 GitHub 仓库与 https://gaagent.ai.；DintalClaw 是目前唯一官方授权商业合作伙伴；任何其他使用 GenericAgent 名称的第三方网站、组织或个人，除非在此明确列出，否则均非官方。*

---

<a id="-中文"></a>

## 🌟 项目简介

**GenericAgent** 是一个极简、可自我进化的自主 Agent 框架。核心仅 **~3K 行代码**，通过 **9 个原子工具 + ~100 行 Agent Loop**，赋予任意 LLM 对本地计算机的系统级控制能力，覆盖浏览器、终端、文件系统、键鼠输入、屏幕视觉及移动设备（ADB）。

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

每解决一个新任务，GenericAgent 就将执行路径自动固化为 Skill，供后续直接调用。使用时间越长，沉淀的技能越多，形成一棵完全属于你、从 3K 行种子代码生长出来的专属技能树。

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

### 📑 目录

- [核心特性](#-核心特性)
- [实例展示](#-实例展示)
- [快速开始](#-快速开始)
- [使用方式](#-使用方式)
- [架构设计](#-架构设计)
- [自我进化机制](#-自我进化机制)
- [与同类产品对比](#-与同类产品对比)
- [评测](#-评测)
- [路线图与最新动态](#-路线图与最新动态)
- [社区与支持](#-社区与支持)
- [许可](#-许可)

---

## 📋 核心特性

| 特性 | 说明 |
| :--- | :--- |
| 🧬 **自我进化** | 每次任务自动沉淀 Skill，能力随使用持续增长，形成专属技能树 |
| 🪶 **极简架构** | ~3K 行核心代码，Agent Loop 约百行，无复杂依赖，部署零负担 |
| ⚡ **强执行力** | 注入真实浏览器（保留登录态），9 个原子工具直接接管系统 |
| 🔌 **高兼容性** | 支持 Claude / Gemini / Kimi / MiniMax 等主流模型，跨平台运行 |
| 💰 **极致省 Token** | 上下文窗口不到 30K，是其他 Agent（200K–1M）的零头；噪声更少、幻觉更低、成功率更高，成本低一个数量级 |

---

## 🎯 实例展示

<table>
  <tr>
    <td align="center" width="50%"><b>🧋 外卖下单</b></td>
    <td align="center" width="50%"><b>📈 量化选股</b></td>
  </tr>
  <tr>
    <td><img src="assets/demo/order_tea.gif" width="100%" alt="外卖下单"></td>
    <td><img src="assets/demo/selectstock.gif" width="100%" alt="量化选股"></td>
  </tr>
  <tr>
    <td><sub><i>"Order me a milk tea"</i> — 自动导航外卖 App，选品并完成结账</sub></td>
    <td><sub><i>"Find GEM stocks with EXPMA golden cross, turnover &gt; 5%"</i> — 量化条件筛股</sub></td>
  </tr>
  <tr>
    <td align="center"><b>🌐 自主网页探索</b></td>
    <td align="center"><b>💰 支出追踪</b></td>
  </tr>
  <tr>
    <td><img src="assets/demo/autonomous_explore.png" width="100%" alt="网页探索"></td>
    <td><img src="assets/demo/alipay_expense.png" width="100%" alt="支付宝支出"></td>
  </tr>
  <tr>
    <td><sub>自主浏览并定时汇总网页信息</sub></td>
    <td><sub><i>"查找近 3 个月超 ¥2K 的支出"</i> — 通过 ADB 驱动支付宝</sub></td>
  </tr>
  <tr>
    <td align="center" colspan="2"><b>💬 批量消息</b></td>
  </tr>
  <tr>
    <td colspan="2" align="center"><img src="assets/demo/wechat_batch.png" width="50%" alt="微信批量"></td>
  </tr>
  <tr>
    <td colspan="2"><sub>批量发送微信消息，完整驱动微信客户端</sub></td>
  </tr>
</table>

---

## 🚀 快速开始

> ⚠️ **Python 版本：** 推荐使用 **Python 3.11 或 3.12**。**请不要使用 Python 3.14**，与 `pywebview` 及部分依赖不兼容。
>
> 📖 详细安装指南：**[installation_zh.md（中文）](docs/installation_zh.md)** · **[installation.md (English)](docs/installation.md)**

### 给 LLM Agent 看的

获取安装指南并照做：

```bash
curl -fsSL https://raw.githubusercontent.com/lsdefine/GenericAgent/refs/heads/main/docs/installation_zh.md
```

### 给人类用户看的

#### 方法一 — 一键安装 *（推荐）*

一键安装会自动准备独立 Python 环境、Git、项目文件和桌面端，不污染系统环境。

**Windows PowerShell**

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

**Linux / macOS**

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

安装完成后启动：

- **Windows** — 双击 `frontends/GenericAgent.exe`
- **Linux / macOS** — 在安装目录运行 `python launch.pyw`

#### 方法二 — Python 安装 *（开发者）*

```bash
git clone https://github.com/lsdefine/GenericAgent.git
cd GenericAgent
uv venv
uv pip install -e ".[ui]"          # 核心 + UI 依赖
cp mykey_template.py mykey.py      # 填入你的 LLM API Key
python launch.pyw
```

> 💡 GenericAgent 更推荐由 **Agent 在使用中自举环境**，而不是预先手动装完整依赖。

📖 完整引导流程见 [`docs/GETTING_STARTED.md`](docs/GETTING_STARTED.md)
📖 新手图文版：[飞书文档](https://my.feishu.cn/wiki/CGrDw0T76iNFuskmwxdcWrpinPb)
📘 完整入门教程（Datawhale 出品）：[Hello GenericAgent](https://datawhalechina.github.io/hello-generic-agent/) · [GitHub](https://github.com/datawhalechina/hello-generic-agent)

---

## 💻 使用方式

### 前端启动

#### 桌面端

一键安装自带桌面端（Windows），双击：

```text
frontends/GenericAgent.exe
```

#### 终端 UI

基于 [Textual](https://github.com/Textualize/textual) 的轻量键盘驱动界面。支持多会话并发、实时流式输出，有终端就能跑。

```bash
python frontends/tuiapp_v2.py
```

<details>
<summary><b>⚠️ Windows 上 TUI 显示异常的排查思路</b></summary>

1. `textual` 版本太旧，先 `pip install -U textual`；
2. PowerShell / cmd 自带终端对 Unicode 和键位的支持比较糟糕，**Windows 上推荐用 Git Bash**，体验明显更稳；
3. 仍然显示异常时，可以让 GA 自己修一遍，参考 Prompt：
   > *"我在 Windows 的 PowerShell / cmd / Git Bash 中使用 `frontends/tuiapp_v2.py` 体验非常差，出现了一堆不兼容问题。请参考 Claude Code 在 Windows 终端的最佳配置，把所有字体和显示不兼容的问题修一遍。"*

</details>

#### Streamlit UI

```bash
python launch.pyw
```

### Bot 接口（IM）

GenericAgent 支持 Telegram、Discord、微信、QQ、飞书 / Lark、企业微信、钉钉等 IM 前端。

| 平台 | 启动命令 |
| :--- | :--- |
| Telegram | `python frontends/tgapp.py` |
| Discord | `python frontends/dcapp.py` |
| 微信 | `python frontends/wechatapp.py` |
| QQ | `python frontends/qqapp.py` |
| 飞书 / Lark | `python frontends/fsapp.py` |
| 企业微信 | `python frontends/wecomapp.py` |
| 钉钉 | `python frontends/dingtalkapp.py` |

> 详细配置直接问 GenericAgent。

---

## 🧠 架构设计

GenericAgent 通过 **分层记忆 × 最小工具集 × 自主执行循环** 完成复杂任务，并在执行过程中持续积累经验。

### 1️⃣ 分层记忆系统

> *记忆在任务执行过程中持续沉淀，使 Agent 逐步形成稳定且高效的工作方式。*

| 层级 | 名称 | 说明 |
| :---: | :--- | :--- |
| **L0** | 元规则（Meta Rules） | Agent 的基础行为规则和系统约束 |
| **L1** | 记忆索引（Insight Index） | 极简索引层，用于快速路由与召回 |
| **L2** | 全局事实（Global Facts） | 在长期运行过程中积累的稳定知识 |
| **L3** | 任务 Skills / SOPs | 完成特定任务类型的可复用流程 |
| **L4** | 会话归档（Session Archive） | 从已完成任务中提炼出的归档记录，用于长程召回 |

### 2️⃣ 自主执行循环

> *感知环境状态 → 任务推理 → 调用工具执行 → 经验写入记忆 → 循环*

整个核心循环仅 **约百行代码**（[`agent_loop.py`](agent_loop.py)）。

### 3️⃣ 最小工具集

> *GenericAgent 仅提供 **9 个原子工具**，构成与外部世界交互的基础能力。*

| 工具 | 功能 |
| :--- | :--- |
| `code_run` | 执行任意代码（Python / PowerShell） |
| `file_read` | 读取文件 |
| `file_write` | 写入 / 创建 / 覆盖文件 |
| `file_patch` | 修改文件 |
| `web_scan` | 感知网页内容 |
| `web_execute_js` | 控制浏览器行为 |
| `ask_user` | 人机协作确认 |
| `update_working_checkpoint` | *（记忆）* 短期工作记事板 |
| `start_long_term_update` | *（记忆）* 提炼长期记忆 |

### 4️⃣ 能力扩展机制

> *具备动态创建新工具的能力。*

通过 `code_run`，GenericAgent 可在运行时动态安装 Python 包、编写新脚本、调用外部 API 或控制硬件，将临时能力固化为永久工具。

<div align="center">
  <img src="assets/images/workflow.jpg" alt="GenericAgent 工作流程" width="420"/>
  <br/><em>GenericAgent 工作流程图</em>
</div>

---

## 🧬 自我进化机制

这是 GenericAgent 区别于其他 Agent 框架的根本所在。

```text
[遇到新任务]
    │
    ▼
[自主摸索]   ─►  安装依赖 · 编写脚本 · 调试验证
    │
    ▼
[执行路径固化为 Skill]   ─►  写入记忆层
    │
    ▼
[下次同类任务直接调用]
```

| 你说的一句话 | 第一次做了什么 | 之后每次 |
| :--- | :--- | :--- |
| *"监控股票并提醒我"* | 安装 `mootdx` → 构建选股流程 → 配置定时任务 → 保存 Skill | **一句话启动** |
| *"用 Gmail 发这个文件"* | 配置 OAuth → 编写发送脚本 → 保存 Skill | **直接可用** |

用几周后，你的 Agent 实例将拥有一套任何人都没有的专属技能树，全部从 3K 行种子代码中生长而来。

---

## 📊 与同类产品对比

| 特性 | **GenericAgent** | OpenClaw | Claude Code |
| :--- | :---: | :---: | :---: |
| **代码量** | ~3K 行 | ~530,000 行 | 已开源（体量大） |
| **部署方式** | `pip install` + API Key | 多服务编排 | CLI + 订阅 |
| **浏览器控制** | 注入真实浏览器（保留登录态） | 沙箱 / 无头浏览器 | 通过 MCP 插件 |
| **OS 控制** | 键鼠、视觉、ADB | 多 Agent 委派 | 文件 + 终端 |
| **自我进化** | 自主生长 Skill 和工具 | 插件生态 | 会话间无状态 |
| **出厂配置** | 几个核心文件 + 少量初始 Skills | 数百模块 | 丰富 CLI 工具集 |

---

## 📈 评测

> 📂 完整的评测数据集以及评测结果见：[**JinyiHan99/GA-Technical-Report**](https://github.com/JinyiHan99/GA-Technical-Report/tree/main)

我们从 **五大维度** 评测 GenericAgent：

| # | 维度 | 核心问题 | 使用的基准 |
| :---: | :--- | :--- | :--- |
| 1 | **任务完成度与 Token 效率** | GA 能否以更低成本完成高难度任务？ | SOP-Bench、Lifelong AgentBench、RealFin-Benchmark |
| 2 | **工具使用效率** | 最小原子工具集能否以更低开销替代专用工具集？ | Tool Efficiency Benchmark |
| 3 | **记忆系统有效性** | 精简分层记忆能否超越冗余记忆和基于 Embedding 的检索器？ | SOP-Bench、LoCoMo、20-skill 压力测试 |
| 4 | **自我进化能力** | Agent 能否在无人干预下将经验提炼为可复用的 SOP 与代码？ | 9 轮 LangChain 纵向研究、8 任务跨任务 Web 基准 |
| 5 | **网页浏览能力** | 信息密度驱动设计能否适应开放网页？ | WebCanvas、BrowseComp-ZH、自定义任务 |

以上维度的基线包括 **Claude Code**、**OpenAI CodeX** 和 **OpenClaw**，分别在 *Claude Sonnet 4.6*、*Claude Opus 4.6*、*GPT-5.4* 和 *MiniMax M2.7* 底座上进行评测。

<table>
  <tr>
    <td align="center" width="50%">
      <img src="assets/images/result_radar.png" width="100%" alt="工具使用效率雷达图"/><br/>
      <sub><b>工具使用效率雷达图。</b>GA 在 Token、请求数和工具调用轴上全面领先，同时在四个任务维度上保持质量。</sub>
    </td>
    <td align="center" width="50%">
      <img src="assets/images/result_convergence.png" width="100%" alt="跨任务自我进化收敛曲线"/><br/>
      <sub><b>跨任务自我进化。</b>GA 的第二轮和第三轮执行在 8 个 Web 任务上收敛至稳定的低成本区间。</sub>
    </td>
  </tr>
</table>

### GA Web 工具的浏览器真实性

GA Web 工具运行在**真实、持久化的 Chrome/Chromium 会话**中，而不是一次性的 headless 沙箱，因此可以保留 Cookie、登录态、扩展、GPU/WebGL 行为以及正常浏览器会话指纹。

| 检测服务 / 信号 | 普通 Headless 自动化 | GA Web 工具 | 说明 |
| :--- | :---: | :---: | :--- |
| SannySoft headless test | 常被识别 | ✅ 56/56 通过 | `bot.sannysoft.com` |
| bot.incolumitas.com | 常在 webdriver / CDP 项异常 | ✅ 36/36 通过 | `WEBDRIVER`、`SELENIUM_DRIVER`、`webDriverAdvanced` 全部 OK |
| BrowserScan bot detection | 常显示异常 | ✅ Normal | `browserscan.net` |
| Device & Browser Info bot test | 多个 bot 标记 | ✅ Human / `isBot=false` | `deviceandbrowserinfo.com` |
| FingerprintJS bot detection demo | 常被识别 | ✅ 通过 | Demo 流程完成，未给出 bot 判定 |
| reCAPTCHA v3 demo | 低分 / bot-like | ✅ 0.9 真人相似分 | v3 是基于分数的风险信号；0.9 高于常见生产阈值 |

对于 reCAPTCHA v3，`0.9` 不是“点过验证码”的结果，而是风控模型返回的高置信真人相似分，通常足以通过生产环境中的常见阈值，避免进入更严格挑战。

---

## 📅 路线图与最新动态

- **2026-05-23** — 🆕 **TUI v3 正式发布**（`frontends/tui_v3.py`）。基于块的滚屏回看 + 正确的 resize 重排，每终端独立配色保证跨终端一致，并与 v2 达成功能对齐。
- **2026-05-18** — 🆕 **Morphling 模式**。项目级能力吞噬 —— 从任意外部仓库抽取目标与测例后，对每个核心组件分别决定调用、重写或舍弃。详见 `memory/morphling_sop.md`。
- **2026-05-17** — 🆕 **Goal Hive 模式**。多 worker 协作版 Goal —— Master/Worker 通过 BBS 协同推进长程目标。详见 `memory/goal_hive_sop.md`。
- **2026-05-15** — 🖥️ **桌面 GUI 发布**。一键安装会自带可直接运行的桌面端（`frontends/GenericAgent.exe`），开发者也可用 `python launch.pyw` 启动。
- **2026-05-14** — 🆕 **Conductor 子 Agent 编排**。派发、监督、自动清理并行子 Agent；与 `/btw` 旁路子 Agent 互补，提供一等公民级的任务委派原语。
- **2026-05-12** — 🆕 **TUI v2 正式发布**（`frontends/tuiapp_v2.py`）。重做视觉风格的 Textual 前端，支持图片粘贴折叠、文件粘贴、块删除、Ctrl+C 复制、历史导航，以及 `/llm` / `/export` / `/continue` 选择器。
- **2026-05-08** — 🆕 **Goal 模式**（`reflect/goal_mode.py`）。时间预算驱动的自驱循环 —— "持续优化 X N 小时"，预算没到不准提前交付。
- **2026-04-21** — 📄 [**技术报告已发布至 arXiv**](https://arxiv.org/abs/2604.17091) — *GenericAgent: A Token-Efficient Self-Evolving LLM Agent via Contextual Information Density Maximization*。
- **2026-04-11** — 引入 **L4 会话归档记忆**，并接入 scheduler cron 调度。
- **2026-03-23** — 支持个人微信接入作为 Bot 前端。
- **2026-03-10** — [发布百万级 Skill 库](https://mp.weixin.qq.com/s/q2gQ7YvWoiAcwxzaiwpuiQ?scene=1&click_id=7)。
- **2026-03-08** — [发布以 GenericAgent 为核心的"政务龙虾" Dintal Claw](https://mp.weixin.qq.com/s/eiEhwo-j6S-WpLxgBnNxBg)。
- **2026-03-01** — [被机器之心报道](https://mp.weixin.qq.com/s/uVWpTTF5I1yzAENV_qm7yg)。
- **2026-01-16** — GenericAgent **V1.0** 公开版本发布。

---

## ⭐ 社区与支持

如果这个项目对你有帮助，欢迎点一个 **Star!** 🙏

也欢迎加入 **GenericAgent 体验交流群**，一起交流、反馈、共建 👏

<div align="center">
  <table>
    <tr>
      <td align="center"><strong>微信群 21</strong><br/><img src="assets/images/wechat_group21.jpg" alt="微信群 21 二维码" width="240"/></td>
    </tr>
  </table>
</div>

### 🚩 友情链接

感谢 **LinuxDo** 社区的支持！

[![LinuxDo](https://img.shields.io/badge/社区-LinuxDo-blue?style=for-the-badge)](https://linux.do/)

**社区 GUI 客户端** *（独立开源项目）*：

- [chilishark27/ga-manager](https://github.com/chilishark27/ga-manager)
- [wangjc683/galley](https://github.com/wangjc683/galley) —— 开箱即用的本地 Agent 工作台，自带 GA 内核（内置 CPython 3.11 + 运行依赖），GUI/CLI 双原生、多 session + Project 编排、本地优先。
- [FroStorM/A3Agent](https://github.com/FroStorM/A3Agent/tree/workbench)
- [Fwind43/GenericAgent-Admin](https://github.com/Fwind43/GenericAgent-Admin) —— Go + React 桌面管理面板：服务生命周期管理、原生 Chat、Goal 模式、BBS 团队看板、文件编辑器、模型配置向导、TMWebDriver 监控、自更新，以及 Windows 托盘/桌面宠物集成。

---

## 📄 许可

基于 **MIT License** 发布，详见 [`LICENSE`](LICENSE)。

> *声明：GenericAgent 官方渠道为本 GitHub 仓库和 https://gaagent.ai。DintalClaw 是目前唯一官方授权的商业合作方；除非在此处明确列出，其他使用 GenericAgent 名义的第三方网站、机构、组织或个人均非官方。*

---

## 📈 Star 历史

<div align="center">

<a href="https://star-history.com/#lsdefine/GenericAgent&Date">
  <picture>
    <source media="(prefers-color-scheme: dark)" srcset="https://api.star-history.com/svg?repos=lsdefine/GenericAgent&type=Date&theme=dark" />
    <source media="(prefers-color-scheme: light)" srcset="https://api.star-history.com/svg?repos=lsdefine/GenericAgent&type=Date" />
    <img alt="Star 历史图表" src="https://api.star-history.com/svg?repos=lsdefine/GenericAgent&type=Date" />
  </picture>
</a>

<br/><br/>
</div>