wehub-resource-sync
299 lines
11 KiB
Markdown
299 lines
11 KiB
Markdown
# 🚀 新手上手指南
|
||
|
||
> 完全没接触过编程也没关系，跟着做就行。Mac / Windows 都适用。
|
||
>
|
||
> 如果你已经有 Python 环境，直接跳到[第 2 步](#2-配置-api-key)。
|
||
|
||
---
|
||
|
||
## 1. 安装 Python
|
||
|
||
### Mac
|
||
|
||
打开「终端」（启动台搜索 "终端" 或 "Terminal"），粘贴这行命令然后回车：
|
||
|
||
```bash
|
||
brew install python
|
||
```
|
||
|
||
如果提示 `brew: command not found`，说明还没装 Homebrew，先粘贴这行：
|
||
|
||
```bash
|
||
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
|
||
```
|
||
|
||
装完后再执行 `brew install python`。
|
||
|
||
### 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
|
||
|
||
### 下载项目
|
||
|
||
最方便的方式是 **一键安装**（自带隔离 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
|
||
```
|
||
|
||
或者手动 clone（开发者）：
|
||
|
||
```bash
|
||
git clone https://github.com/lsdefine/GenericAgent.git
|
||
cd GenericAgent
|
||
uv venv && uv pip install -e ".[ui]"
|
||
```
|
||
|
||
也可以走最朴素的 ZIP：[GitHub 仓库页面](https://github.com/lsdefine/GenericAgent) → 点绿色 **Code** → **Download ZIP** → 解压到喜欢的位置。
|
||
|
||
> 💡 **让 Claude / Codex 等 Agent 帮你装**：把下面这条 curl 丢给它，它会按官方指南替你完成安装：
|
||
> ```bash
|
||
> curl -fsSL https://raw.githubusercontent.com/lsdefine/GenericAgent/refs/heads/main/docs/installation_zh.md
|
||
> ```
|
||
>
|
||
> 📖 平台差异、排障、升级流程见 [`docs/installation_zh.md`](installation_zh.md)。
|
||
|
||
### 创建配置文件
|
||
|
||
进入项目文件夹，把 `mykey_template.py` 复制一份，重命名为 `mykey.py`。
|
||
|
||
用任意文本编辑器打开 `mykey.py`，填入你的 API 信息。**选一种填就行**，不用的配置删掉或留着不管都行。
|
||
|
||
> 💡 也可以运行交互式向导 `python assets/configure_mykey.py`，按提示选择厂商、填入 Key 即可自动生成 `mykey.py`。
|
||
|
||
### 配置示例
|
||
|
||
**推荐首选：Claude 原生协议**：
|
||
|
||
```python
|
||
# 变量名同时含 'native' 和 'claude' → NativeClaudeSession（API 原生工具字段）
|
||
native_claude_config = {
|
||
'name': 'claude', # /llms 显示名 & mixin 引用名
|
||
'apikey': 'sk-xxx', # sk-ant- 走 x-api-key；其它走 Bearer
|
||
'apibase': 'https://api.anthropic.com', # 官方直连；反代渠道填对应地址
|
||
'model': 'claude-opus-4-7', # [1m] 后缀触发 1M 上下文 beta
|
||
# 'fake_cc_system_prompt': True, # CC switch / 反代渠道必须置 True
|
||
}
|
||
```
|
||
|
||
**也支持：OpenAI 原生协议**：
|
||
|
||
```python
|
||
# 变量名同时含 'native' 和 'oai' → NativeOAISession
|
||
native_oai_config = {
|
||
'name': 'gpt', # /llms 显示名 & mixin 引用名
|
||
'apikey': 'sk-xxx',
|
||
'apibase': 'https://api.openai.com/v1', # 自动补 /v1/chat/completions
|
||
'model': 'gpt-5.5',
|
||
}
|
||
```
|
||
|
||
**进阶：Mixin 故障转移**（多 session 自动切换，最稳的玩法）：
|
||
|
||
```python
|
||
# llm_nos 按优先级排列；首项失败按指数退避切下一项
|
||
mixin_config = {
|
||
'llm_nos': ['claude', 'gpt'], # 与上面 native_* 的 name 字段对应
|
||
'max_retries': 10,
|
||
'base_delay': 0.5,
|
||
}
|
||
```
|
||
|
||
> 💡 完整字段说明（`thinking_type` / `reasoning_effort` / `context_win` / `proxy` / Zhipu / MiniMax / Kimi / OpenRouter 等渠道示例）见 `mykey_template.py` 顶部注释。
|
||
|
||
### 关键规则
|
||
|
||
**变量命名决定 Session 类型**（不是模型名决定的）：
|
||
|
||
| 变量名包含 | 触发的 Session | 工具协议 | 适用场景 |
|
||
|-----------|---------------|---------|---------|
|
||
| `native` + `claude` | NativeClaudeSession | API 原生 tool 字段 | **推荐首选** — Claude 原生协议 |
|
||
| `native` + `oai` | NativeOAISession | API 原生 tool 字段 | GPT/o 系列、OAI 兼容渠道 |
|
||
| `mixin` | MixinSession | 多 session 故障转移 | 最稳；要求被引用 session 全为 native |
|
||
| `claude`（不含 `native`） | ClaudeSession | 文本协议工具 | **deprecated**，后续版本可能移除 |
|
||
| `oai`（不含 `native`） | LLMSession | 文本协议工具 | **deprecated**，后续版本可能移除 |
|
||
|
||
**`apibase` 填写规则**（会自动拼接端点路径）：
|
||
|
||
| 你填的内容 | 系统行为 |
|
||
|-----------|---------|
|
||
| `http://host:2001` | 自动补 `/v1/chat/completions` |
|
||
| `http://host:2001/v1` | 自动补 `/chat/completions` |
|
||
| `http://host:2001/v1/chat/completions` | 直接使用，不拼接 |
|
||
|
||
---
|
||
|
||
## 3. 初次启动
|
||
|
||
终端里进入项目文件夹，运行：
|
||
|
||
```bash
|
||
cd 你的解压路径
|
||
python3 agentmain.py
|
||
```
|
||
|
||
这就是**命令行模式**，已经可以用了。你会看到一个输入提示符，直接打字发送任务即可。
|
||
|
||
试试你的第一个任务：
|
||
|
||
```
|
||
帮我在桌面创建一个 hello.txt，内容是 Hello World
|
||
```
|
||
|
||
> 💡 Windows 上如果 `python3` 不识别，换成 `python agentmain.py`。
|
||
|
||
---
|
||
|
||
## 4. 让 Agent 自己装依赖
|
||
|
||
Agent 启动后，只需要一句话，它就会自己搞定所有依赖：
|
||
|
||
```
|
||
请查看你的代码，安装所有用得上的 python 依赖
|
||
```
|
||
|
||
Agent 会自己读代码、找出需要的包、全部装好。
|
||
|
||
> ⚠️ 如果遇到网络问题导致 Agent 无法调用 API，可能需要先手动装一个包：
|
||
> ```bash
|
||
> pip install requests
|
||
> ```
|
||
|
||
### 升级到图形界面
|
||
|
||
依赖装完后，可以选择适合你的前端：
|
||
|
||
| 前端 | 启动命令 | 说明 |
|
||
|------|---------|------|
|
||
| **桌面端** | 双击 `frontends/GenericAgent.exe`（Windows 一键安装自带） | 真原生窗口，零终端依赖 |
|
||
| **TUI v3** | `python frontends/tui_v3.py` | 基于块的滚屏回看、resize 重排、每终端独立配色，跨终端体验一致 |
|
||
| **TUI v2** | `python frontends/tuiapp_v2.py` | Textual 键盘驱动界面，图片粘贴折叠、`/llm`/`/export`/`/continue` 选择器 |
|
||
| **Streamlit / 悬浮窗** | `python launch.pyw` | 浏览器中打开的 Streamlit UI，附带桌面悬浮窗 |
|
||
|
||
> 💡 Windows 下推荐用 **Git Bash** 跑 TUI；PowerShell / cmd 对 Unicode 和键位支持较弱。仍异常时请直接告诉 Agent：「参考 Claude Code 在 Windows 终端的最佳配置帮我把 TUI 修一遍」。
|
||
|
||
### 可选：让 Agent 帮你做的事
|
||
|
||
```
|
||
请帮我建立 git 连接，方便以后更新代码
|
||
```
|
||
|
||
Agent 会自动配好。如果你电脑上没有 Git，它也会帮你下载 portable 版。
|
||
|
||
```
|
||
请帮我在桌面创建一个 launch.pyw 的快捷方式
|
||
```
|
||
|
||
这样以后双击桌面图标就能启动，不用再开终端了。
|
||
|
||
---
|
||
|
||
## 5. 能力解锁
|
||
|
||
环境跑起来之后，你可以逐步解锁更多能力。每一项都只需要**对 Agent 说一句话**：
|
||
|
||
### 基础能力
|
||
|
||
| 能力 | 对 Agent 说 | 说明 |
|
||
|------|-----------|------|
|
||
| **PowerShell 脚本执行** | `帮我解锁当前用户的 PowerShell ps1 执行权限` | Windows 默认禁止运行 .ps1 脚本 |
|
||
| **全局文件搜索** | `安装并配置 Everything 命令行工具进 PATH` | 毫秒级全盘文件搜索 |
|
||
|
||
### 浏览器自动化
|
||
|
||
| 能力 | 对 Agent 说 | 说明 |
|
||
|------|-----------|------|
|
||
| **Web 工具解锁** | `执行 web setup sop，解锁 web 工具` | 注入浏览器插件，使 Agent 能直接操控网页 |
|
||
|
||
解锁后，Agent 可以在**保留你登录态**的真实浏览器中操作：
|
||
|
||
```
|
||
打开淘宝，搜索 iPhone 16，按价格排序
|
||
去 B 站，查看我最近看过的历史视频
|
||
```
|
||
|
||
### 进阶能力
|
||
|
||
| 能力 | 对 Agent 说 | 说明 |
|
||
|------|-----------|------|
|
||
| **OCR** | `用rapidocr配置你的ocr能力并存入记忆` | 让 Agent 能"看到"屏幕文字 |
|
||
| **屏幕视觉** | `仿造你的llmcore，写个调用vision的能力并存入记忆` | 让 Agent 能"看到"屏幕内容 |
|
||
| **移动端控制** | `配置 ADB 环境，准备连接安卓设备` | 通过 USB/WiFi 控制 Android 手机 |
|
||
|
||
### 聊天平台接入（可选）
|
||
|
||
接入后可以随时随地通过手机给电脑上的 Agent 发指令。
|
||
|
||
对 Agent 说：`看你的代码，帮我配置 XX 平台的机器人接入`
|
||
|
||
支持的平台：**微信个人Bot** / QQ / 飞书 / 企业微信 / 钉钉 / Telegram
|
||
|
||
> Agent 会自动读取代码、引导你完成配置。
|
||
|
||
### 高级模式
|
||
|
||
以下模式全部**自文档化**——不用查手册，直接问 Agent 即可：
|
||
|
||
| 模式 | 对 Agent 说 |
|
||
|------|------------|
|
||
| **Reflect（反射）** | `查看你的代码，告诉我你的 reflect 模式怎么启用` |
|
||
| **计划任务** | `查看你的代码，告诉我你的计划任务模式怎么启用` |
|
||
| **Plan（规划）** | `查看你的代码，告诉我你的 plan 模式怎么启用` |
|
||
| **SubAgent（子代理）** | `查看你的代码，告诉我你的 subagent 模式怎么启用` |
|
||
| **自主探索** | `查看你的代码，告诉我你的自主探索模式怎么启用` |
|
||
| **Goal** | `查看你的代码，告诉我 goal 模式怎么启用` |
|
||
| **Goal Hive（多 worker 协作）** | `查看你的代码，告诉我 goal hive 模式怎么启用` |
|
||
| **Conductor（多 subagent 编排）** | `查看你的代码，告诉我 conductor 模式怎么启用` |
|
||
| **Morphling（吞噬外部项目）** | `查看你的代码，告诉我 morphling 模式怎么启用` |
|
||
|
||
> 💡 这就是 GenericAgent 的核心设计理念：**代码即文档**。Agent 能读懂自己的源码，所以任何功能你都可以直接问它。
|
||
|
||
---
|
||
|
||
## 💡 使用越久越强
|
||
|
||
GenericAgent 不预设技能，而是**靠使用进化**。每完成一个新任务，它会自动将执行路径固化为 Skill，下次遇到类似任务直接调用。
|
||
|
||
你不需要管理这些 Skill，Agent 会自动处理。使用时间越长，积累的技能越多，最终形成一棵完全属于你的专属技能树。
|
||
|
||
> 💡 如果你觉得某些重要信息 Agent 没有记住，可以直接告诉它：`把这个记到你的记忆里`，它会主动记忆。
|
||
|
||
**其他 Claw 的 Skill 也可以直接复用：**
|
||
|
||
- 让 Agent 搜索：`帮我找个做 XXX 的 skill` → 完成后 → `加入你的记忆中`
|
||
- 直接指定来源：`访问 XXX 文件夹/URL，按照这个 skill 做 XXX`
|
||
|
||
**保持更新：**
|
||
|
||
对 Agent 说：`git 更新你的代码，然后看看 commit 有什么新功能`
|
||
|
||
> Agent 会自动 pull 最新代码并解读 commit log，告诉你新增了什么能力。
|
||
|
||
> 更多细节请参阅 [README.md](../README.md) 或 [详细版图文教程](https://my.feishu.cn/wiki/CGrDw0T76iNFuskmwxdcWrpinPb)。
|