# GenericAgent 新手上手指南

## 🎯 什么是 GenericAgent?

GenericAgent 是一个极简、可自我进化的自主 Agent 框架。它的核心只有 **~3,300 行代码**,通过 **7 个原子工具 + 92 行 Agent Loop**,就能赋予任意 LLM 对你本地计算机的系统级控制能力。

**它能做什么?**
- 控制浏览器(保留登录态)
- 执行终端命令
- 读写文件系统
- 模拟键盘鼠标
- 控制移动设备(ADB)
- 屏幕视觉识别

**最特别的是什么?**

GenericAgent 不预设技能,而是**靠进化获得能力**。每解决一个新任务,它就会自动将执行路径固化为 Skill,供后续直接调用。使用时间越长,沉淀的技能越多,最终形成一棵完全属于你的专属技能树。

> 🤖 **自举实证**: 本项目的所有 Git 操作,从 `git init` 到每一条 commit message,都是 GenericAgent 自主完成的。作者全程未打开过一次终端。

---

## 🚀 5 分钟快速开始

### 第一步:安装部署

**方法一:标准安装(推荐开发者)**

```bash
# 1. 克隆仓库
git clone https://github.com/lsdefine/GenericAgent.git
cd GenericAgent

# 2. 安装最小依赖
pip install streamlit pywebview

# 3. 配置 API Key
cp mykey_template.py mykey.py
```

**方法二:Windows 便携版(推荐新手)**

1. [下载便携版](http://kw.fudan.edu.cn/resources/PC-Agent-Portable.zip) (19MB)
2. 解压到任意目录
3. 双击运行即可

**方法三:Android(Termux)**

```bash
cd /sdcard/ga
python agentmain.py
```

### 第二步:配置 API Key

编辑 `mykey.py` 文件,填入你的 LLM API Key:

```python
# 示例:使用 Claude
api_key = "sk-ant-xxx"  # 你的 Anthropic API Key
model = "claude-3-5-sonnet-20241022"

# 或使用其他模型
# api_key = "your_openai_key"
# model = "gpt-4"
```

支持的模型:
- Claude (Anthropic)
- GPT-4 / GPT-3.5 (OpenAI)
- Gemini (Google)
- Kimi (Moonshot)
- 其他兼容 OpenAI API 的模型

### 第三步:启动界面

```bash
python launch.pyw
```

启动后会出现一个桌面悬浮窗,你可以直接在里面输入任务指令。

---

## 💡 基础使用

### 你的第一个任务

启动后,试试这些简单的任务:

**文件操作:**
```
"帮我在桌面创建一个 hello.txt 文件,内容是 Hello World"
```

**网页浏览:**
```
"打开百度,搜索今天的天气"
```

**代码执行:**
```
"用 Python 计算 1 到 100 的和"
```

### 理解 Agent 的工作方式

GenericAgent 的工作流程:

```
你的指令 → Agent 理解任务 → 调用工具执行 → 返回结果 → 沉淀经验
```

**核心循环(92 行代码):**
1. **感知**: 读取当前环境状态
2. **推理**: 分析任务,制定执行计划
3. **执行**: 调用工具完成操作
4. **记忆**: 将成功的执行路径写入记忆层
5. **循环**: 继续下一步,直到任务完成

---

## 🧬 进阶:Skill 系统

### 什么是 Skill?

Skill 是 GenericAgent 自动沉淀的任务执行模板。当你第一次完成某个任务时,Agent 会将整个执行流程固化为一个 Skill,下次遇到类似任务就能直接调用。

**举个例子:**

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

### 如何使用 Skill?

Skill 会自动保存在 `memory/` 目录下。你不需要手动管理,Agent 会在需要时自动调用。

**查看已有的 Skill:**
```bash
ls memory/*.md
```

**手动触发 Skill:**
```
"使用之前保存的股票监控 Skill"
```

### 培养你的专属 Agent

使用时间越长,你的 Agent 积累的 Skill 越多:

- **第 1 周**: 基础文件操作、简单网页浏览
- **第 1 个月**: 自动化工作流、数据处理脚本
- **第 3 个月**: 复杂的多步骤任务、跨平台操作
- **第 6 个月**: 一套任何人都没有的专属技能树

---

## 🎮 实用玩法

### 浏览器自动化

GenericAgent 注入真实浏览器,保留你的登录态:

```
"打开淘宝,搜索 iPhone 15,按价格排序"
"登录我的 Gmail,查看未读邮件"
"在美团上帮我点一杯奶茶"
```

**可用工具:**
- `web_scan`: 读取网页内容
- `web_execute_js`: 执行 JavaScript 控制页面

### 文件和代码处理

```
"分析这个 Python 项目的代码结构"
"把这个 CSV 文件转换成 Excel"
"批量重命名这个文件夹里的图片"
```

**可用工具:**
- `file_read`: 读取文件
- `file_write`: 写入文件
- `file_patch`: 精确修改文件
- `code_run`: 执行代码

### 移动设备控制(ADB)

通过 ADB 控制 Android 设备:

```
"打开支付宝,查看我的账单"
"在微信上给张三发消息"
"截取手机屏幕并保存"
```

### 定时任务

```
"每天早上 8 点提醒我查看邮件"
"每小时检查一次股票价格"
"每周一生成上周的工作总结"
```

---

## 🤖 接入聊天平台(可选)

### 为什么要接入 Bot?

将 GenericAgent 接入聊天平台后,你可以:
- 随时随地通过手机控制你的电脑
- 多人协作使用同一个 Agent
- 接收 Agent 的主动通知和提醒

### 支持的平台

- **QQ Bot**: WebSocket 长连接,无需公网 webhook
- **飞书(Lark)**: 支持富文本、图片、文件、音频
- **企业微信(WeCom)**: 企业内部使用
- **钉钉(DingTalk)**: 企业协作
- **Telegram**: 国际用户

### 快速配置指南

**以 QQ Bot 为例:**

1. 在 [QQ 开放平台](https://q.qq.com) 创建机器人
2. 获取 AppID 和 AppSecret
3. 在 `mykey.py` 中配置:

```python
qq_app_id = "YOUR_APP_ID"
qq_app_secret = "YOUR_APP_SECRET"
qq_allowed_users = ["YOUR_USER_OPENID"]  # 或 ['*'] 公开访问
```

4. 启动 Bot:

```bash
pip install qq-botpy
python qqapp.py
# 或与桌面窗口一起启动
python launch.pyw --qq
```

**其他平台配置详见:**
- 飞书: [assets/SETUP_FEISHU.md](assets/SETUP_FEISHU.md)
- 企业微信: `python launch.pyw --wecom`
- 钉钉: `python launch.pyw --dingtalk`
- Telegram: `python tgapp.py`

---

## 📚 记忆系统详解

### 三层记忆架构

GenericAgent 的记忆系统分为三层:

**L0 — 元规则(Meta Rules)**
- Agent 的基础行为规则
- 系统约束和安全边界
- 不可修改的核心逻辑

**L2 — 全局事实(Global Facts)**
- 长期运行中积累的稳定知识
- 环境配置、用户偏好
- 存储在 `memory/global_mem.txt`

**L3 — 任务 Skills(SOPs)**
- 完成特定任务的操作流程
- 自动沉淀的执行模板
- 存储在 `memory/*.md`

### 如何查看和管理记忆

**查看全局记忆:**
```bash
cat memory/global_mem.txt
```

**查看所有 Skills:**
```bash
ls memory/*.md
```

**手动编辑记忆:**
```bash
# 不建议新手操作,Agent 会自动管理
vim memory/global_mem.txt
```

---

## 🔧 常见问题

### 安装问题

**Q: pip install 失败怎么办?**

A: 尝试使用国内镜像源:
```bash
pip install -i https://pypi.tuna.tsinghua.edu.cn/simple streamlit pywebview
```

**Q: Windows 上启动失败?**

A: 建议使用便携版,或检查 Python 版本(需要 3.8+)

### 使用问题

**Q: Agent 执行任务失败?**

A: 检查:
1. API Key 是否正确配置
2. 网络连接是否正常
3. 查看 `temp/` 目录下的日志文件

**Q: 如何让 Agent 停止当前任务?**

A: 在界面中输入 "停止" 或 "取消"

**Q: Agent 的回复太慢?**

A: 可以尝试:
1. 切换到更快的模型(如 GPT-3.5)
2. 减少任务的复杂度
3. 检查网络延迟

### 进阶问题

**Q: 如何自定义 Agent 的行为?**

A: 编辑 `memory/global_mem.txt`,添加你的偏好设置

**Q: 如何备份我的 Skills?**

A: 直接复制 `memory/` 目录即可

**Q: 可以同时运行多个 Agent 实例吗?**

A: 可以,但需要使用不同的工作目录

---

## 💪 最佳实践

### 新手建议

1. **从简单任务开始**: 先尝试文件操作、网页浏览等基础任务
2. **观察 Agent 的执行过程**: 理解它是如何调用工具的
3. **让 Agent 自己探索**: 不要过度干预,让它自主学习
4. **定期查看 Skills**: 了解 Agent 积累了哪些能力

### 进阶技巧

1. **组合使用多个工具**: 让 Agent 完成复杂的多步骤任务
2. **利用记忆系统**: 在 `global_mem.txt` 中记录常用的配置和偏好
3. **编写自定义脚本**: 通过 `code_run` 扩展 Agent 的能力
4. **接入多个聊天平台**: 实现跨平台的统一控制

### 安全注意事项

1. **不要在公共环境运行**: Agent 有系统级权限,注意安全
2. **谨慎授权**: 使用 Bot 时,设置 `allowed_users` 白名单
3. **定期备份**: 重要的 Skills 和配置要及时备份
4. **监控执行日志**: 定期检查 `temp/` 目录下的日志

---

## 🌟 社区和支持

### 获取帮助

- **GitHub Issues**: [提交问题](https://github.com/lsdefine/GenericAgent/issues)
- **微信交流群**: 扫描下方二维码加入

<div align="center">
<img src="assets/images/wechat_group.jpg" width="280"/>
</div>

### 贡献指南

欢迎贡献代码、文档或 Skills!

1. Fork 本仓库
2. 创建你的特性分支
3. 提交你的改动
4. 发起 Pull Request

---

## 📖 延伸阅读

- [完整 README](README.md) - 项目详细介绍
- [新用户欢迎文档](WELCOME_NEW_USER.md) - 详细的引导流程
- [快速开始指南](QUICK_START.pdf) - PDF 版本的快速入门
- [飞书配置指南](assets/SETUP_FEISHU.md) - 飞书 Bot 详细配置

---

**🎉 现在,开始你的 GenericAgent 之旅吧!**

记住: GenericAgent 不是一个预设好的工具,而是一个会随着你的使用不断进化的伙伴。使用时间越长,它就越懂你,越强大。