GenericAgent/GETTING_STARTED.md

GenericAgent 新手上手指南

🎯 什么是 GenericAgent?

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

它能做什么?

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

最特别的是什么?

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

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

---

🚀 5 分钟快速开始

第一步:安装部署

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

# 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. 下载便携版 (19MB)
2. 解压到任意目录
3. 双击运行即可

方法三:Android(Termux)

cd /sdcard/ga
python agentmain.py

第二步:配置 API Key

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

# 示例:使用 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 的模型

第三步:启动界面

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:

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 开放平台 创建机器人
2. 获取 AppID 和 AppSecret
3. 在 mykey.py 中配置:

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

4. 启动 Bot:

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

其他平台配置详见:

• 飞书: 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

如何查看和管理记忆

查看全局记忆:

cat memory/global_mem.txt

查看所有 Skills:

ls memory/*.md

手动编辑记忆:

# 不建议新手操作,Agent 会自动管理
vim memory/global_mem.txt

---

🔧 常见问题

安装问题

Q: pip install 失败怎么办?

A: 尝试使用国内镜像源:

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: 提交问题
• 微信交流群: 扫描下方二维码加入

贡献指南

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

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

---

📖 延伸阅读

• 完整 README - 项目详细介绍
• 新用户欢迎文档 - 详细的引导流程
• 快速开始指南 - PDF 版本的快速入门
• 飞书配置指南 - 飞书 Bot 详细配置

---

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

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