refactor: rewrite GETTING_STARTED, cleanup README, add hub.pyw, remove QUICK_START.pdf

2026-03-27 12:58:13 +08:00
parent ff258dd0a9
commit f6c5011eb0
10 changed files with 536 additions and 528 deletions
--- a/GETTING_STARTED.md
+++ b/GETTING_STARTED.md
@@ -1,409 +1,258 @@
-# GenericAgent 新手上手指南
+# 🚀 新手上手指南

-## 🎯 什么是 GenericAgent?
-
-GenericAgent 是一个极简、可自我进化的自主 Agent 框架。它的核心只有 **~3,300 行代码**,通过 **7 个原子工具 + 92 行 Agent Loop**,就能赋予任意 LLM 对你本地计算机的系统级控制能力。
-
-**它能做什么?**
- 控制浏览器(保留登录态)
- 执行终端命令
- 读写文件系统
- 模拟键盘鼠标
- 控制移动设备(ADB)
- 屏幕视觉识别
-
-**最特别的是什么?**
-
-GenericAgent 不预设技能,而是**靠进化获得能力**。每解决一个新任务,它就会自动将执行路径固化为 Skill,供后续直接调用。使用时间越长,沉淀的技能越多,最终形成一棵完全属于你的专属技能树。
-
-> 🤖 **自举实证**: 本项目的所有 Git 操作,从 `git init` 到每一条 commit message,都是 GenericAgent 自主完成的。作者全程未打开过一次终端。
+> 完全没接触过编程也没关系，跟着做就行。Mac / Windows 都适用。
+>
+> 如果你已经有 Python 环境，直接跳到[第 2 步](#2-配置-api-key)。

 ---

-## 🚀 5 分钟快速开始
+## 1. 安装 Python

-### 第一步:安装部署
+### Mac

-**方法一:标准安装(推荐开发者)**
+打开「终端」（启动台搜索 "终端" 或 "Terminal"），粘贴这行命令然后回车：

 ```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
+brew install python
 ```

-**方法二:Windows 便携版(推荐新手)**
-
-1. [下载便携版](http://kw.fudan.edu.cn/resources/PC-Agent-Portable.zip) (19MB)
-2. 解压到任意目录
-3. 双击运行即可
-
-**方法三:Android(Termux)**
+如果提示 `brew: command not found`，说明还没装 Homebrew，先粘贴这行：

 ```bash
-cd /sdcard/ga
-python agentmain.py
+/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
 ```

-### 第二步:配置 API Key
+装完后再执行 `brew install python`。

-编辑 `mykey.py` 文件,填入你的 LLM API Key:
+### Windows
+
+1. 打开 [python.org/downloads](https://www.python.org/downloads/)，点黄色大按钮下载
+2. 运行安装包，**底部的 "Add Python to PATH" 一定要勾上**
+3. 点 "Install Now"
+
+### 验证
+
+终端 / 命令提示符里输入：
+
+```bash
+python3 --version
+```
+
+看到 `Python 3.x.x` 就 OK。Windows 上也可以试 `python --version`。
+
+> ⚠️ **版本提示**：推荐 **Python 3.11 或 3.12**。不要使用 3.14（与 pywebview 等依赖不兼容）。
+
+---
+
+## 2. 配置 API Key
+
+### 下载项目
+
+1. 打开 [GitHub 仓库页面](https://github.com/lsdefine/GenericAgent)
+2. 点绿色 **Code** 按钮 → **Download ZIP**
+3. 解压到你喜欢的位置
+
+### 创建配置文件
+
+进入项目文件夹，把 `mykey_template.py` 复制一份，重命名为 `mykey.py`。
+
+用任意文本编辑器打开 `mykey.py`，填入你的 API 信息。**选一种填就行**，不用的配置删掉或留着不管都行。
+
+### 配置示例
+
+**最常见的用法：**

 ```python
-# 示例:使用 Claude
-api_key = "sk-ant-xxx"  # 你的 Anthropic API Key
-model = "claude-3-5-sonnet-20241022"
-
-# 或使用其他模型
-# api_key = "your_openai_key"
-# model = "gpt-4"
+# 变量名含 'oai' → 走 OpenAI 兼容格式 (/chat/completions)
+oai_config = {
+    'apikey': 'sk-你的密钥',
+    'apibase': 'http://你的API地址:端口',
+    'model': '模型名称',
+}
 ```

-支持的模型:
- Claude (Anthropic)
- GPT-4 / GPT-3.5 (OpenAI)
- Gemini (Google)
- Kimi (Moonshot)
- 其他兼容 OpenAI API 的模型
+```python
+# 变量名含 'claude'（不含 'native'）→ 走 Claude 兼容格式 (/messages)
+claude_config = {
+    'apikey': 'sk-你的密钥',
+    'apibase': 'http://你的API地址:端口',
+    'model': 'claude-sonnet-4-20250514',
+}
+```

-### 第三步:启动界面
+**使用标准工具调用格式（适合较弱模型）：**
+
+```python
+# 变量名同时含 'native' 和 'claude' → Claude 标准工具调用格式
+native_claude_config = {
+    'apikey': 'sk-ant-你的密钥',
+    'apibase': 'https://api.anthropic.com',
+    'model': 'claude-sonnet-4-20250514',
+}
+```
+
+> 💡 还支持 `native_oai_config`（OpenAI 标准工具调用）、`xai_config`（Grok）、`sider_cookie`（Sider）等，详见 `mykey_template.py` 中的注释。
+
+### 关键规则
+
+**变量命名决定接口格式**（不是模型名决定的）：
+
+| 变量名包含 | 触发的 Session | 适用场景 |
+|-----------|---------------|---------|
+| `oai` | OpenAI 兼容 | 大多数 API 服务、OpenAI 官方 |
+| `claude`（不含 `native`） | Claude 兼容 | Claude API 服务 |
+| `native` + `claude` | Claude 标准工具调用 | 较弱模型推荐，工具调用更规范 |
+| `native` + `oai` | OpenAI 标准工具调用 | 较弱模型推荐，工具调用更规范 |
+
+> 例：用 Claude 模型，但 API 服务提供的是 OpenAI 兼容接口 → 变量名用 `oai_xxx`。
+
+**`apibase` 填写规则**（会自动拼接端点路径）：
+
+| 你填的内容 | 系统行为 |
+|-----------|---------|
+| `http://host:2001` | 自动补 `/v1/chat/completions` |
+| `http://host:2001/v1` | 自动补 `/chat/completions` |
+| `http://host:2001/v1/chat/completions` | 直接使用，不拼接 |
+
+---
+
+## 3. 初次启动
+
+终端里进入项目文件夹，运行：

 ```bash
-python launch.pyw
+cd 你的解压路径
+python3 agentmain.py
 ```

-启动后会出现一个桌面悬浮窗,你可以直接在里面输入任务指令。
+这就是**命令行模式**，已经可以用了。你会看到一个输入提示符，直接打字发送任务即可。
+
+试试你的第一个任务：
+
+```
+帮我在桌面创建一个 hello.txt，内容是 Hello World
+```
+
+> 💡 Windows 上如果 `python3` 不识别，换成 `python agentmain.py`。

 ---

-## 💡 基础使用
+## 4. 让 Agent 自己装依赖

-### 你的第一个任务
-
-启动后,试试这些简单的任务:
-
-**文件操作:**
-```
-"帮我在桌面创建一个 hello.txt 文件,内容是 Hello World"
-```
-
-**网页浏览:**
-```
-"打开百度,搜索今天的天气"
-```
-
-**代码执行:**
-```
-"用 Python 计算 1 到 100 的和"
-```
-
-### 理解 Agent 的工作方式
-
-GenericAgent 的工作流程:
+Agent 启动后，只需要一句话，它就会自己搞定所有依赖：

 ```
-你的指令 → Agent 理解任务 → 调用工具执行 → 返回结果 → 沉淀经验
+请查看你的代码，安装所有用得上的 python 依赖
 ```

-**核心循环(92 行代码):**
-1. **感知**: 读取当前环境状态
-2. **推理**: 分析任务,制定执行计划
-3. **执行**: 调用工具完成操作
-4. **记忆**: 将成功的执行路径写入记忆层
-5. **循环**: 继续下一步,直到任务完成
+Agent 会自己读代码、找出需要的包、全部装好。

---
+> ⚠️ 如果遇到网络问题导致 Agent 无法调用 API，可能需要先手动装一个包：
+> ```bash
+> pip install requests
+> ```

-## 🧬 进阶:Skill 系统
+### 升级到图形界面

-### 什么是 Skill?
+依赖装完后，就可以用 GUI 模式了：

-Skill 是 GenericAgent 自动沉淀的任务执行模板。当你第一次完成某个任务时,Agent 会将整个执行流程固化为一个 Skill,下次遇到类似任务就能直接调用。
-
-**举个例子:**
-
-| 你说的话 | 第一次 Agent 做了什么 | 之后每次 |
-|---------|---------------------|---------|
-| "监控股票并提醒我" | 安装 mootdx → 构建选股流程 → 配置定时任务 → 保存 Skill | **一句话启动** |
-| "用 Gmail 发这个文件" | 配置 OAuth → 编写发送脚本 → 保存 Skill | **直接可用** |
-
-### 如何使用 Skill?
-
-Skill 会自动保存在 `memory/` 目录下。你不需要手动管理,Agent 会在需要时自动调用。
-
-**查看已有的 Skill:**
 ```bash
-ls memory/*.md
+python3 launch.pyw
 ```

-**手动触发 Skill:**
+启动后会出现一个桌面悬浮窗，直接在里面输入任务指令。
+
+### 可选：让 Agent 帮你做的事
+
 ```
-"使用之前保存的股票监控 Skill"
+请帮我建立 git 连接，方便以后更新代码
 ```

-### 培养你的专属 Agent
+Agent 会自动配好。如果你电脑上没有 Git，它也会帮你下载 portable 版。

-使用时间越长,你的 Agent 积累的 Skill 越多:
+```
+请帮我在桌面创建一个 launch.pyw 的快捷方式
+```

- **第 1 周**: 基础文件操作、简单网页浏览
- **第 1 个月**: 自动化工作流、数据处理脚本
- **第 3 个月**: 复杂的多步骤任务、跨平台操作
- **第 6 个月**: 一套任何人都没有的专属技能树
+这样以后双击桌面图标就能启动，不用再开终端了。

 ---

-## 🎮 实用玩法
+## 5. 能力解锁
+
+环境跑起来之后，你可以逐步解锁更多能力。每一项都只需要**对 Agent 说一句话**：
+
+### 基础能力
+
+| 能力 | 对 Agent 说 | 说明 |
+|------|-----------|------|
+| **PowerShell 脚本执行** | `帮我解锁当前用户的 PowerShell ps1 执行权限` | Windows 默认禁止运行 .ps1 脚本 |
+| **全局文件搜索** | `安装并配置 Everything 命令行工具进 PATH` | 毫秒级全盘文件搜索 |

 ### 浏览器自动化

-GenericAgent 注入真实浏览器,保留你的登录态:
+| 能力 | 对 Agent 说 | 说明 |
+|------|-----------|------|
+| **Web 工具解锁** | `执行 web setup sop，解锁 web 工具` | 注入浏览器插件，使 Agent 能直接操控网页 |
+
+解锁后，Agent 可以在**保留你登录态**的真实浏览器中操作：

 ```
-"打开淘宝,搜索 iPhone 15,按价格排序"
-"登录我的 Gmail,查看未读邮件"
-"在美团上帮我点一杯奶茶"
+打开淘宝，搜索 iPhone 16，按价格排序
+去 B 站，查看我最近看过的历史视频
 ```

-**可用工具:**
- `web_scan`: 读取网页内容
- `web_execute_js`: 执行 JavaScript 控制页面
+### 进阶能力

-### 文件和代码处理
+| 能力 | 对 Agent 说 | 说明 |
+|------|-----------|------|
+| **OCR** | `用rapidocr配置你的ocr能力并存入记忆` | 让 Agent 能"看到"屏幕文字 |
+| **屏幕视觉** | `仿造你的llmcore，写个调用vision的能力并存入记忆` | 让 Agent 能"看到"屏幕内容 |
+| **移动端控制** | `配置 ADB 环境，准备连接安卓设备` | 通过 USB/WiFi 控制 Android 手机 |

-```
-"分析这个 Python 项目的代码结构"
-"把这个 CSV 文件转换成 Excel"
-"批量重命名这个文件夹里的图片"
-```
+### 聊天平台接入（可选）

-**可用工具:**
- `file_read`: 读取文件
- `file_write`: 写入文件
- `file_patch`: 精确修改文件
- `code_run`: 执行代码
+接入后可以随时随地通过手机给电脑上的 Agent 发指令。

-### 移动设备控制(ADB)
+对 Agent 说：`看你的代码，帮我配置 XX 平台的机器人接入`

-通过 ADB 控制 Android 设备:
+支持的平台：**微信个人Bot** / QQ / 飞书 / 企业微信 / 钉钉 / Telegram

-```
-"打开支付宝,查看我的账单"
-"在微信上给张三发消息"
-"截取手机屏幕并保存"
-```
+> Agent 会自动读取代码、引导你完成配置。

-### 定时任务
+### 高级模式

-```
-"每天早上 8 点提醒我查看邮件"
-"每小时检查一次股票价格"
-"每周一生成上周的工作总结"
-```
+以下模式全部**自文档化**——不用查手册，直接问 Agent 即可：
+
+| 模式 | 对 Agent 说 |
+|------|------------|
+| **Reflect（反射）** | `查看你的代码，告诉我你的 reflect 模式怎么启用` |
+| **计划任务** | `查看你的代码，告诉我你的计划任务模式怎么启用` |
+| **Plan（规划）** | `查看你的代码，告诉我你的 plan 模式怎么启用` |
+| **SubAgent（子代理）** | `查看你的代码，告诉我你的 subagent 模式怎么启用` |
+| **自主探索** | `查看你的代码，告诉我你的自主探索模式怎么启用` |
+
+> 💡 这就是 GenericAgent 的核心设计理念：**代码即文档**。Agent 能读懂自己的源码，所以任何功能你都可以直接问它。

 ---

-## 🤖 接入聊天平台(可选)
+## 💡 使用越久越强

-### 为什么要接入 Bot?
+GenericAgent 不预设技能，而是**靠使用进化**。每完成一个新任务，它会自动将执行路径固化为 Skill，下次遇到类似任务直接调用。

-将 GenericAgent 接入聊天平台后,你可以:
- 随时随地通过手机控制你的电脑
- 多人协作使用同一个 Agent
- 接收 Agent 的主动通知和提醒
+你不需要管理这些 Skill，Agent 会自动处理。使用时间越长，积累的技能越多，最终形成一棵完全属于你的专属技能树。

-### 支持的平台
+> 💡 如果你觉得某些重要信息 Agent 没有记住，可以直接告诉它：`把这个记到你的记忆里`，它会主动记忆。

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

-### 快速配置指南
+- 让 Agent 搜索：`帮我找个做 XXX 的 skill` → 完成后 → `加入你的记忆中`
+- 直接指定来源：`访问 XXX 文件夹/URL，按照这个 skill 做 XXX`

-**以 QQ Bot 为例:**
+**保持更新：**

-1. 在 [QQ 开放平台](https://q.qq.com) 创建机器人
-2. 获取 AppID 和 AppSecret
-3. 在 `mykey.py` 中配置:
+对 Agent 说：`git 更新你的代码，然后看看 commit 有什么新功能`

-```python
-qq_app_id = "YOUR_APP_ID"
-qq_app_secret = "YOUR_APP_SECRET"
-qq_allowed_users = ["YOUR_USER_OPENID"]  # 或 ['*'] 公开访问
-```
+> Agent 会自动 pull 最新代码并解读 commit log，告诉你新增了什么能力。

-4. 启动 Bot:
-
-```bash
-pip install qq-botpy
-python frontends/qqapp.py
-# 或与桌面窗口一起启动
-python launch.pyw --qq
-```
-
-**其他平台配置详见:**
- 飞书: [assets/SETUP_FEISHU.md](assets/SETUP_FEISHU.md)
- 企业微信: `python launch.pyw --wecom`
- 钉钉: `python launch.pyw --dingtalk`
- Telegram: `python frontends/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 不是一个预设好的工具,而是一个会随着你的使用不断进化的伙伴。使用时间越长,它就越懂你,越强大。
+> 更多细节请参阅 [README.md](README.md) 或 [详细版图文教程](https://my.feishu.cn/wiki/CGrDw0T76iNFuskmwxdcWrpinPb)。