chore: import upstream snapshot with attribution
This commit is contained in:
wehub-resource-sync
@@ -0,0 +1,298 @@
|
||||
# 🚀 新手上手指南
|
||||
|
||||
> 完全没接触过编程也没关系，跟着做就行。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)。
|
||||
@@ -0,0 +1,301 @@
|
||||
# 飞书 Agent 配置指南
|
||||
|
||||
> 让你的个人电脑变成飞书机器人的大脑，随时随地通过飞书对话控制你的电脑。
|
||||
|
||||
---
|
||||
|
||||
## 📋 目录
|
||||
|
||||
1. [前置条件](#前置条件)
|
||||
2. [方案选择](#方案选择)
|
||||
3. [企业用户配置](#企业用户配置)
|
||||
4. [个人用户配置](#个人用户配置)
|
||||
5. [项目配置](#项目配置)
|
||||
6. [运行与测试](#运行与测试)
|
||||
7. [常见问题](#常见问题)
|
||||
|
||||
---
|
||||
|
||||
## 前置条件
|
||||
|
||||
### 必需环境
|
||||
|
||||
- Python 3.8+
|
||||
- 本项目完整代码
|
||||
- LLM API 密钥（Claude/OpenAI 等，已在 `llmcore/mykeys` 中配置）
|
||||
|
||||
### 安装依赖
|
||||
|
||||
```bash
|
||||
pip install lark-oapi
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 方案选择
|
||||
|
||||
| 你的情况 | 推荐方案 | 预计耗时 |
|
||||
| ------------------ | -------------------------- | --------- |
|
||||
| 公司已有飞书企业版 | [企业用户配置](#企业用户配置) | 5-10分钟 |
|
||||
| 个人用户/学习测试 | [个人用户配置](#个人用户配置) | 10-15分钟 |
|
||||
|
||||
---
|
||||
|
||||
## 企业用户配置
|
||||
|
||||
> 适用于：你的公司使用飞书，你有权限创建应用或联系管理员审批
|
||||
|
||||
### 步骤 1：创建应用
|
||||
|
||||
1. 访问 [飞书开放平台](https://open.feishu.cn/)
|
||||
2. 登录你的企业飞书账号
|
||||
3. 点击右上角「创建应用」→「企业自建应用」
|
||||
4. 填写应用信息：
|
||||
- 应用名称：`我的Agent助手`（可自定义）
|
||||
- 应用描述：`个人AI助手`
|
||||
- 应用图标：可选
|
||||
|
||||
### 步骤 2：添加机器人能力
|
||||
|
||||
1. 进入应用详情页
|
||||
2. 左侧菜单选择「添加应用能力」
|
||||
3. 找到「机器人」，点击「添加」
|
||||
4. 配置机器人信息（可保持默认）
|
||||
|
||||
### 步骤 3：配置权限
|
||||
|
||||
1. 左侧菜单「权限管理」→「API 权限」
|
||||
2. 搜索并开通以下权限：
|
||||
- `im:message` - 获取与发送单聊、群组消息
|
||||
- `im:message:send_as_bot` - 以应用身份发送消息
|
||||
- `contact:user.id:readonly` - 获取用户 ID
|
||||
|
||||
### 步骤 4：获取凭证
|
||||
|
||||
1. 左侧菜单「凭证与基础信息」
|
||||
2. 记录以下信息：
|
||||
- **App ID**：`cli_xxxxxxxx`
|
||||
- **App Secret**：`xxxxxxxxxxxxxxxx`
|
||||
|
||||
### 步骤 5：发布应用
|
||||
|
||||
1. 左侧菜单「版本管理与发布」
|
||||
2. 点击「创建版本」
|
||||
3. 填写版本信息，提交审核
|
||||
4. **联系企业管理员审批**（或自己是管理员直接审批）
|
||||
|
||||
### 步骤 6：获取你的 Open ID
|
||||
|
||||
1. 应用审批通过后，在飞书中搜索你的机器人
|
||||
2. 给机器人发送任意消息
|
||||
3. 运行以下代码获取你的 Open ID：
|
||||
|
||||
```python
|
||||
# 临时运行一次，获取 open_id
|
||||
import lark_oapi as lark
|
||||
from lark_oapi.api.im.v1 import *
|
||||
|
||||
client = lark.Client.builder().app_id("你的APP_ID").app_secret("你的APP_SECRET").build()
|
||||
|
||||
# 监听消息，打印发送者的 open_id
|
||||
def handle(data):
|
||||
print(f"你的 Open ID: {data.event.sender.sender_id.open_id}")
|
||||
|
||||
# ... 或者查看 frontends/fsapp.py 运行时的日志输出
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 个人用户配置
|
||||
|
||||
> 适用于：没有企业飞书账号，想个人测试使用
|
||||
|
||||
### 步骤 1：创建测试企业
|
||||
|
||||
1. 访问 [飞书开放平台](https://open.feishu.cn/)
|
||||
2. 使用个人手机号注册/登录
|
||||
3. 点击右上角头像 →「创建测试企业」
|
||||
4. 填写企业名称（如：`我的测试工作区`）
|
||||
5. 创建完成后，你就是这个测试企业的**管理员**
|
||||
|
||||
### 步骤 2：创建应用
|
||||
|
||||
> 与企业用户步骤相同
|
||||
|
||||
1. 点击「创建应用」→「企业自建应用」
|
||||
2. 填写应用信息
|
||||
|
||||
### 步骤 3：添加机器人能力
|
||||
|
||||
1. 进入应用详情页
|
||||
2. 「添加应用能力」→「机器人」→「添加」
|
||||
|
||||
### 步骤 4：配置权限
|
||||
|
||||
1. 「权限管理」→「API 权限」
|
||||
2. 开通权限：
|
||||
- `im:message`
|
||||
- `im:message:send_as_bot`
|
||||
- `contact:user.id:readonly`
|
||||
|
||||
### 步骤 5：获取凭证
|
||||
|
||||
1. 「凭证与基础信息」
|
||||
2. 复制 **App ID** 和 **App Secret**
|
||||
|
||||
### 步骤 6：发布应用（测试企业可自审批）
|
||||
|
||||
1. 「版本管理与发布」→「创建版本」
|
||||
2. 提交后，进入 [飞书管理后台](https://feishu.cn/admin)
|
||||
3. 「工作台」→「应用审核」→ 通过你的应用
|
||||
|
||||
### 步骤 7：在飞书客户端使用
|
||||
|
||||
1. 下载 [飞书客户端](https://www.feishu.cn/download)
|
||||
2. 登录你的测试企业账号
|
||||
3. 搜索你创建的机器人名称
|
||||
4. 开始对话！
|
||||
|
||||
---
|
||||
|
||||
## 项目配置
|
||||
|
||||
### 配置飞书凭证
|
||||
|
||||
编辑项目根目录的 `mykey.py`，添加：
|
||||
|
||||
```python
|
||||
# 飞书应用凭证
|
||||
fs_app_id = "cli_xxxxxxxxxxxxxxxx" # 替换为你的 App ID
|
||||
fs_app_secret = "xxxxxxxxxxxxxxxx" # 替换为你的 App Secret
|
||||
|
||||
# 允许使用的用户 Open ID 列表（可选，留空则允许所有人）
|
||||
fs_allowed_users = [
|
||||
"ou_xxxxxxxxxxxxxxxxxxxxxxxx", # 你的 Open ID
|
||||
]
|
||||
```
|
||||
|
||||
### 确认 LLM 配置
|
||||
|
||||
确保 `llmcore/mykeys` 中已配置 LLM API 密钥：
|
||||
|
||||
```python
|
||||
# 示例：Claude API
|
||||
claude_config = {
|
||||
'apikey': 'sk-ant-xxxxx',
|
||||
'apibase': 'https://api.anthropic.com',
|
||||
'model': 'claude-sonnet-4-20250514'
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 运行与测试
|
||||
|
||||
### 启动服务
|
||||
|
||||
```bash
|
||||
cd /path/to/pc-agent-loop
|
||||
python frontends/fsapp.py
|
||||
```
|
||||
|
||||
### 预期输出
|
||||
|
||||
```
|
||||
==================================================
|
||||
飞书 Agent 已启动（长连接模式）
|
||||
App ID: cli_xxxxxxxxxxxxxxxx
|
||||
等待消息...
|
||||
==================================================
|
||||
```
|
||||
|
||||
### 测试对话
|
||||
|
||||
1. 打开飞书客户端
|
||||
2. 找到你的机器人
|
||||
3. 发送：`你好`
|
||||
4. 等待回复（首次可能需要几秒）
|
||||
|
||||
---
|
||||
|
||||
## 可用命令
|
||||
|
||||
在与机器人对话时，可以使用以下特殊命令：
|
||||
|
||||
| 命令 | 说明 |
|
||||
| ---- | ---- |
|
||||
| `/new` | 开始新对话，清除当前上下文 |
|
||||
| `/stop` | 中止当前正在执行的任务 |
|
||||
| `/restore <关键词>` | 恢复之前的对话上下文（根据关键词搜索历史记录） |
|
||||
|
||||
### 命令示例
|
||||
|
||||
```
|
||||
/new # 清空对话，重新开始
|
||||
/stop # 停止正在运行的任务
|
||||
/restore 昨天的任务 # 恢复包含"昨天的任务"关键词的历史对话
|
||||
```
|
||||
|
||||
### 消息显示说明
|
||||
|
||||
- ⏳ 表示任务正在执行中
|
||||
- 消息会实时更新，无需等待完成
|
||||
- 超长回复会自动分段发送
|
||||
|
||||
---
|
||||
|
||||
## 常见问题
|
||||
|
||||
### Q: 提示「应用未发布」或「无权限」
|
||||
|
||||
**A:** 确保应用已发布且管理员已审批。测试企业用户需要在管理后台手动审批。
|
||||
|
||||
### Q: 发送消息后没有回复
|
||||
|
||||
**A:** 检查：
|
||||
|
||||
1. `frontends/fsapp.py` 是否在运行
|
||||
2. 终端是否有错误日志
|
||||
3. LLM API 密钥是否配置正确
|
||||
|
||||
### Q: 提示「invalid app_id」
|
||||
|
||||
**A:** 检查 `mykey.py` 中的 `fs_app_id` 是否正确复制（包含 `cli_` 前缀）
|
||||
|
||||
### Q: 如何获取自己的 Open ID？
|
||||
|
||||
**A:** 运行 `frontends/fsapp.py` 后给机器人发消息，查看终端日志中的 `open_id`
|
||||
|
||||
### Q: 能否多人同时使用？
|
||||
|
||||
**A:** 不能。一个应用只能有一个长连接，连接到一台电脑。每个人需要创建自己的应用。
|
||||
|
||||
---
|
||||
|
||||
## 架构说明
|
||||
|
||||
```
|
||||
你的飞书 ←→ 飞书云 ←→ 长连接 ←→ frontends/fsapp.py ←→ Agent ←→ 你的电脑
|
||||
↑
|
||||
运行在你电脑上
|
||||
```
|
||||
|
||||
- 消息通过飞书云转发到你电脑上运行的 `frontends/fsapp.py`
|
||||
- Agent 处理请求后，通过飞书 API 回复消息
|
||||
- **你的电脑必须保持运行** `frontends/fsapp.py` 才能响应消息
|
||||
|
||||
---
|
||||
|
||||
## 下一步
|
||||
|
||||
- 自定义 Agent 行为：编辑 `assets/sys_prompt.txt`
|
||||
- 添加新工具：编辑 `assets/tools_schema.json`
|
||||
- 查看日志：运行时观察终端输出
|
||||
|
||||
---
|
||||
|
||||
*文档版本：v1.1 | 更新日期：2026-03-07*
|
||||
|
||||
**v1.1 更新内容：**
|
||||
- 新增「可用命令」章节（/new, /stop, /restore）
|
||||
- 新增消息显示说明（⏳ 进行中标记、实时更新等）
|
||||
@@ -0,0 +1,323 @@
|
||||
# Installation Guide
|
||||
|
||||
This is the detailed installation guide for **GenericAgent**.
|
||||
|
||||
Two audiences:
|
||||
|
||||
- **[For Humans](#for-humans)** — you are installing GA for yourself.
|
||||
- **[For LLM Agents](#for-llm-agents)** — you are a coding agent such as Claude Code, or Codex installing GA for a human user. Read that section first so you do not guess.
|
||||
|
||||
> The shortest install commands live in the main [README](../README.md#-quick-start). This guide adds platform notes, key setup, verification, troubleshooting, and agent-safe rules.
|
||||
|
||||
---
|
||||
|
||||
## For Humans
|
||||
|
||||
### Prerequisites
|
||||
|
||||
| Requirement | Notes |
|
||||
|---|---|
|
||||
| **OS** | Windows 10/11, macOS 12+, or a modern Linux distribution. |
|
||||
| **Python** | Use **Python 3.11 or 3.12**. **Do not use Python 3.14** — it is incompatible with `pywebview` and a few GA dependencies. The one-line installer ships an isolated Python environment, so manual Python setup is usually unnecessary. |
|
||||
| **Git** | Recommended for updates and self-evolution. |
|
||||
| **LLM API key** | GA speaks two native protocols: **OpenAI-compatible** APIs and **Anthropic Claude native** APIs. GPT-family models, Claude, Kimi, MiniMax, DeepSeek, GLM, Qwen, Gemini through OAI-compatible gateways, and similar providers can be configured through `mykey.py`. |
|
||||
|
||||
### Method 1: One-line install (recommended)
|
||||
|
||||
This is the easiest path. It prepares an isolated runtime, downloads GenericAgent, installs the core dependencies, and gives you a ready-to-run local project tree.
|
||||
|
||||
**Windows PowerShell**
|
||||
|
||||
```powershell
|
||||
powershell -ExecutionPolicy Bypass -c "$env:GLOBAL=1; irm http://fudankw.cn:9000/files/ga_install.ps1 | iex"
|
||||
```
|
||||
|
||||
**Linux / macOS**
|
||||
|
||||
```bash
|
||||
GLOBAL=1 bash -c "$(curl -fsSL http://fudankw.cn:9000/files/ga_install.sh)"
|
||||
```
|
||||
|
||||
After installation, launch the desktop app from:
|
||||
|
||||
```text
|
||||
frontends/GenericAgent.exe
|
||||
```
|
||||
|
||||
Or run from the project directory:
|
||||
|
||||
```bash
|
||||
python launch.pyw
|
||||
```
|
||||
|
||||
> GenericAgent is meant to grow its environment through the Agent itself, not by pre-installing every possible package. Start small, then let GA install task-specific tools when it actually needs them.
|
||||
|
||||
#### Custom install location
|
||||
|
||||
```bash
|
||||
INSTALL_DIR="$HOME/work/GenericAgent" GLOBAL=1 bash -c "$(curl -fsSL http://fudankw.cn:9000/files/ga_install.sh)"
|
||||
```
|
||||
|
||||
```powershell
|
||||
$env:INSTALL_DIR="C:\dev\GenericAgent"; powershell -ExecutionPolicy Bypass -c "$env:GLOBAL=1; irm http://fudankw.cn:9000/files/ga_install.ps1 | iex"
|
||||
```
|
||||
|
||||
#### Force reinstall
|
||||
|
||||
Use this only when you know you want to refresh the installed files. Back up `mykey.py`, `memory/`, `skills/`, and any local work first.
|
||||
|
||||
```bash
|
||||
FORCE=1 GLOBAL=1 bash -c "$(curl -fsSL http://fudankw.cn:9000/files/ga_install.sh)"
|
||||
```
|
||||
|
||||
### Method 2: Python install (for developers)
|
||||
|
||||
Use this when you want a normal editable checkout.
|
||||
|
||||
```bash
|
||||
git clone https://github.com/lsdefine/GenericAgent.git
|
||||
cd GenericAgent
|
||||
uv venv
|
||||
uv pip install -e ".[ui]" # Core + UI dependencies
|
||||
cp mykey_template.py mykey.py # Fill in your LLM API key
|
||||
python launch.pyw
|
||||
```
|
||||
|
||||
Full guide: [GETTING_STARTED.md](GETTING_STARTED.md)
|
||||
|
||||
### Configure your LLM key
|
||||
|
||||
1. Open the installed `GenericAgent` directory.
|
||||
2. If `mykey.py` does not exist, copy it from `mykey_template.py`.
|
||||
3. Fill in one provider. Do **not** paste example keys as real keys.
|
||||
4. If you are unsure about the fields, read the comments in `mykey_template.py` first.
|
||||
|
||||
GA supports:
|
||||
|
||||
- **OpenAI-compatible** endpoints — Chat Completions / Responses shaped APIs.
|
||||
- **Anthropic Claude native** — Claude Messages API.
|
||||
|
||||
Optional helper:
|
||||
|
||||
```bash
|
||||
python assets/configure_mykey.py
|
||||
```
|
||||
|
||||
### Frontends
|
||||
|
||||
#### Desktop App
|
||||
|
||||
For one-line installs on Windows, double-click:
|
||||
|
||||
```text
|
||||
frontends/GenericAgent.exe
|
||||
```
|
||||
|
||||
#### Terminal UI
|
||||
|
||||
A lightweight keyboard-driven interface built on [Textual](https://github.com/Textualize/textual). It supports multiple concurrent sessions and real-time streaming.
|
||||
|
||||
```bash
|
||||
python frontends/tuiapp_v2.py
|
||||
```
|
||||
|
||||
#### Streamlit UI
|
||||
|
||||
```bash
|
||||
python launch.pyw
|
||||
```
|
||||
|
||||
### Verify the install
|
||||
|
||||
From the GenericAgent directory:
|
||||
|
||||
```bash
|
||||
python -c "import agent_loop; print('OK')"
|
||||
git rev-parse --short HEAD
|
||||
```
|
||||
|
||||
Then launch at least one frontend:
|
||||
|
||||
```bash
|
||||
python launch.pyw
|
||||
# or
|
||||
python frontends/tuiapp_v2.py
|
||||
```
|
||||
|
||||
### Common gotchas
|
||||
|
||||
#### Python 3.14 is not supported
|
||||
|
||||
If your system `python --version` reports 3.14, do not use it for GA. Use the one-line installer, or create a Python 3.11 / 3.12 environment with `uv`.
|
||||
|
||||
#### `ga` command conflict
|
||||
|
||||
Some systems already use `ga` for another tool. Check first:
|
||||
|
||||
```bash
|
||||
type ga
|
||||
```
|
||||
|
||||
If it resolves to something unexpected, do not rely on the shortcut. Run GA from the install directory with `python launch.pyw` or `python frontends/tuiapp_v2.py`.
|
||||
|
||||
#### Windows TUI rendering issues
|
||||
|
||||
TUI rendering on Windows depends on terminal, font, and `textual` version.
|
||||
|
||||
1. Upgrade Textual first: `pip install -U textual`.
|
||||
2. Prefer **Git Bash on Windows** over classic PowerShell / cmd when Unicode or key bindings look broken.
|
||||
3. If it still looks wrong, ask GA itself to repair the terminal compatibility. Example prompt:
|
||||
> *"My experience using `frontends/tuiapp_v2.py` in PowerShell / cmd / Git Bash on Windows is very poor — lots of incompatibility. Please refer to Claude Code's best practices for the Windows terminal and fix all font and rendering incompatibilities."*
|
||||
|
||||
#### `pywebview` install fails on Linux
|
||||
|
||||
Desktop mode depends on GTK / WebKit packages. On Debian / Ubuntu:
|
||||
|
||||
```bash
|
||||
sudo apt install libgtk-3-dev libwebkit2gtk-4.1-dev
|
||||
pip install pywebview
|
||||
```
|
||||
|
||||
On headless servers, prefer the TUI or run Streamlit in browser mode instead of desktop mode.
|
||||
|
||||
### Update an existing install
|
||||
|
||||
Do not delete a working GA directory just to update it. It may contain the user's `mykey.py`, memory, skills, and local work.
|
||||
|
||||
```bash
|
||||
cd ~/GenericAgent
|
||||
git fetch
|
||||
git pull
|
||||
uv pip install -e ".[ui]"
|
||||
```
|
||||
|
||||
If `git pull` reports conflicts:
|
||||
|
||||
- For `mykey.py`, `memory/`, `skills/`, `temp/`, and user-created artifacts: prefer the local copy.
|
||||
- For core code such as `agent*.py`, `frontends/*`, `reflect/*`, and `tools/*`: usually prefer upstream unless the user says otherwise.
|
||||
- Resolve explicitly, then `git add` and commit the merge.
|
||||
|
||||
---
|
||||
|
||||
## For LLM Agents
|
||||
|
||||
> **IMPORTANT: fetch this file with `curl`, not a summarized web reader.** Summaries often drop flags, command quoting, and safety rules.
|
||||
>
|
||||
> ```bash
|
||||
> curl -fsSL https://raw.githubusercontent.com/lsdefine/GenericAgent/refs/heads/main/docs/installation.md
|
||||
> ```
|
||||
|
||||
You are installing **GenericAgent** for a human user. Be direct, verify each step, and avoid destructive cleanup unless the user explicitly authorizes it.
|
||||
|
||||
### Step 0: Inspect before acting
|
||||
|
||||
Check:
|
||||
|
||||
1. OS: `uname -a`, `$env:OS`, or `python -c "import platform; print(platform.system())"`.
|
||||
2. Existing install: `~/GenericAgent/launch.pyw`, `%USERPROFILE%\GenericAgent\launch.pyw`, or a `.git` directory.
|
||||
3. Python version: must be 3.11 or 3.12 if you use the developer path.
|
||||
4. Git availability: `git --version`.
|
||||
5. API key readiness: ask the user if no key is available. Never invent one.
|
||||
|
||||
### Step 1: Choose the install path
|
||||
|
||||
Default to the one-line installer unless the user already has a checkout.
|
||||
|
||||
**Windows PowerShell**
|
||||
|
||||
```powershell
|
||||
powershell -ExecutionPolicy Bypass -c "$env:GLOBAL=1; irm http://fudankw.cn:9000/files/ga_install.ps1 | iex"
|
||||
```
|
||||
|
||||
**Linux / macOS**
|
||||
|
||||
```bash
|
||||
GLOBAL=1 bash -c "$(curl -fsSL http://fudankw.cn:9000/files/ga_install.sh)"
|
||||
```
|
||||
|
||||
If the user explicitly wants a developer checkout:
|
||||
|
||||
```bash
|
||||
git clone https://github.com/lsdefine/GenericAgent.git
|
||||
cd GenericAgent
|
||||
uv venv
|
||||
uv pip install -e ".[ui]"
|
||||
cp mykey_template.py mykey.py
|
||||
```
|
||||
|
||||
### Step 2: Configure keys safely
|
||||
|
||||
- Read `mykey_template.py` before editing `mykey.py`.
|
||||
- Configure only keys the user actually provides.
|
||||
- Never print the full key back to the user.
|
||||
- If the user is unsure, run `python assets/configure_mykey.py` or ask which provider they want to use.
|
||||
|
||||
Suggested question:
|
||||
|
||||
> Which LLM should GenericAgent use? GA supports OpenAI-compatible endpoints and Anthropic Claude native APIs. Which provider do you want to configure, and do you already have an API key?
|
||||
|
||||
### Step 3: Verify setup
|
||||
|
||||
Run:
|
||||
|
||||
```bash
|
||||
cd ~/GenericAgent
|
||||
python -c "import agent_loop; print('OK')"
|
||||
git rev-parse --short HEAD
|
||||
```
|
||||
|
||||
Then verify one frontend:
|
||||
|
||||
```bash
|
||||
python launch.pyw
|
||||
# or, for terminal-only environments:
|
||||
python frontends/tuiapp_v2.py
|
||||
```
|
||||
|
||||
### Step 4: Verification and Next Steps
|
||||
|
||||
Read this document again and think through whether you have done everything correctly:
|
||||
|
||||
- You inspected the OS, existing install, Python version, Git, and key readiness before acting.
|
||||
- You used the correct GA install command for this English guide, including `GLOBAL=1` where shown.
|
||||
- You configured only real user-provided keys and did not reveal secrets.
|
||||
- You verified import, Git commit hash, and at least one frontend.
|
||||
|
||||
#### Say 'Congratulations! 🎉' to the user
|
||||
|
||||
Say to user: Congratulations! 🎉 You have successfully set up GenericAgent! Double-click `frontends/GenericAgent.exe` on Windows, or run `python frontends/tuiapp_v2.py` in your terminal to start using it.
|
||||
|
||||
#### Report the concrete result
|
||||
|
||||
Tell the user:
|
||||
|
||||
1. Install path.
|
||||
2. Git commit hash.
|
||||
3. Which frontend you verified.
|
||||
4. Whether `mykey.py` is configured, without revealing secrets.
|
||||
5. Recommended next reading: [Hello GenericAgent](https://datawhalechina.github.io/hello-generic-agent/) and [GETTING_STARTED.md](GETTING_STARTED.md).
|
||||
|
||||
#### Ask for a Star ⭐
|
||||
|
||||
After everything is set up and working, you may ask:
|
||||
|
||||
> If you found this helpful, would you like to star the GenericAgent repository? It helps the project grow! ⭐
|
||||
|
||||
Only open or run anything related to starring the repository if the user explicitly agrees.
|
||||
|
||||
### Never do these
|
||||
|
||||
- Do **not** run `pip install genericagent`; GA is not a PyPI package.
|
||||
- Do **not** delete `~/GenericAgent` or `%USERPROFILE%\GenericAgent` for a "clean install" without explicit user approval.
|
||||
- Do **not** fabricate API keys or treat sample keys as real.
|
||||
- Do **not** assume `ga` is a valid shell command; check first.
|
||||
- Do **not** rely on `ga update`; use `git fetch`, `git pull`, and reinstall dependencies as shown above.
|
||||
|
||||
---
|
||||
|
||||
## References
|
||||
|
||||
- Main README: [README.md](../README.md)
|
||||
- Getting started: [GETTING_STARTED.md](GETTING_STARTED.md)
|
||||
- Datawhale tutorial: <https://datawhalechina.github.io/hello-generic-agent/>
|
||||
- Technical report: <https://arxiv.org/abs/2604.17091>
|
||||
@@ -0,0 +1,324 @@
|
||||
# 安装指南（中文）
|
||||
|
||||
这是 **GenericAgent** 的详细安装指南。
|
||||
|
||||
两类读者：
|
||||
|
||||
- **[面向用户（For Humans）](#面向用户-for-humans)** —— 你自己安装 GA。
|
||||
- **[面向 LLM Agent（For LLM Agents）](#面向-llm-agent-for-llm-agents)** —— 你是 Claude Code、Codex 等编程 Agent，需要替人类用户安装 GA。请先读这一段，避免靠猜。
|
||||
|
||||
> 最短安装命令见主 [README](../README.md#-快速开始)。这份文档补充平台差异、Key 配置、验证、排障，以及 Agent 自动安装时的安全规则。
|
||||
|
||||
---
|
||||
|
||||
## 面向用户（For Humans）
|
||||
|
||||
### 准备工作
|
||||
|
||||
| 要求 | 说明 |
|
||||
|---|---|
|
||||
| **操作系统** | Windows 10/11、macOS 12+，或任意现代 Linux。 |
|
||||
| **Python** | 推荐 **Python 3.11 或 3.12**。**不要使用 Python 3.14**，它与 `pywebview` 及部分 GA 依赖不兼容。方法一的一键脚本会准备隔离运行环境，通常不需要手动装 Python。 |
|
||||
| **Git** | 推荐安装，方便升级和自我进化。 |
|
||||
| **LLM API Key** | GA 原生支持两类协议：**OpenAI 兼容接口** 和 **Anthropic Claude 原生接口**。GPT 系列、Claude、Kimi、MiniMax、DeepSeek、GLM、Qwen、通过 OAI 兼容网关接入的 Gemini 等，都可以在 `mykey.py` 中配置。 |
|
||||
|
||||
### 方法一：一键安装（推荐）
|
||||
|
||||
这是最省心的路径。脚本会准备隔离环境、下载 GenericAgent、安装核心依赖，并得到一个可以直接运行的本地项目目录。
|
||||
|
||||
**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 用户可双击：
|
||||
|
||||
```text
|
||||
frontends/GenericAgent.exe
|
||||
```
|
||||
|
||||
也可以进入项目目录运行：
|
||||
|
||||
```bash
|
||||
python launch.pyw
|
||||
```
|
||||
|
||||
> GenericAgent 更推荐由 Agent 在使用中自举环境，而不是预先手动装完整依赖。先把最小系统跑起来，需要什么工具再让 GA 自己安装。
|
||||
|
||||
#### 自定义安装路径
|
||||
|
||||
```bash
|
||||
INSTALL_DIR="$HOME/work/GenericAgent" bash -c "$(curl -fsSL http://fudankw.cn:9000/files/ga_install.sh)"
|
||||
```
|
||||
|
||||
```powershell
|
||||
$env:INSTALL_DIR="C:\dev\GenericAgent"; powershell -ExecutionPolicy Bypass -c "irm http://fudankw.cn:9000/files/ga_install.ps1 | iex"
|
||||
```
|
||||
|
||||
#### 强制重新安装
|
||||
|
||||
仅在明确想刷新已安装文件时使用。请先备份 `mykey.py`、`memory/`、`skills/` 和本地工作成果。
|
||||
|
||||
```bash
|
||||
FORCE=1 bash -c "$(curl -fsSL http://fudankw.cn:9000/files/ga_install.sh)"
|
||||
```
|
||||
|
||||
### 方法二：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
|
||||
```
|
||||
|
||||
完整引导流程见 [GETTING_STARTED.md](GETTING_STARTED.md)。
|
||||
|
||||
### 配置 LLM Key
|
||||
|
||||
1. 打开已安装的 `GenericAgent` 目录。
|
||||
2. 如果没有 `mykey.py`，从 `mykey_template.py` 复制一份。
|
||||
3. 填入一个真实可用的模型服务商配置。**不要**把示例 Key 当真。
|
||||
4. 不确定字段含义时，先读 `mykey_template.py` 里的注释。
|
||||
|
||||
GA 支持：
|
||||
|
||||
- **OpenAI 兼容接口** —— Chat Completions / Responses 形态的接口。
|
||||
- **Anthropic Claude 原生接口** —— Claude Messages API。
|
||||
|
||||
可选配置向导：
|
||||
|
||||
```bash
|
||||
python assets/configure_mykey.py
|
||||
```
|
||||
|
||||
### 前端启动方式
|
||||
|
||||
#### 桌面端
|
||||
|
||||
一键安装自带桌面端，双击：
|
||||
|
||||
```text
|
||||
frontends/GenericAgent.exe
|
||||
```
|
||||
|
||||
#### 终端 UI
|
||||
|
||||
基于 [Textual](https://github.com/Textualize/textual) 的轻量键盘驱动界面。支持多会话并发、实时流式输出，有终端就能跑。
|
||||
|
||||
```bash
|
||||
python frontends/tuiapp_v2.py
|
||||
```
|
||||
|
||||
#### Streamlit UI
|
||||
|
||||
```bash
|
||||
python launch.pyw
|
||||
```
|
||||
|
||||
### 验证安装
|
||||
|
||||
在 GenericAgent 目录下运行：
|
||||
|
||||
```bash
|
||||
python -c "import agent_loop; print('OK')"
|
||||
git rev-parse --short HEAD
|
||||
```
|
||||
|
||||
然后至少启动一个前端：
|
||||
|
||||
```bash
|
||||
python launch.pyw
|
||||
# 或
|
||||
python frontends/tuiapp_v2.py
|
||||
```
|
||||
|
||||
### 常见坑
|
||||
|
||||
#### 不支持 Python 3.14
|
||||
|
||||
如果系统 `python --version` 显示 3.14，不要用它跑 GA。请走一键安装，或用 `uv` 创建 Python 3.11 / 3.12 环境。
|
||||
|
||||
#### `ga` 命令冲突
|
||||
|
||||
有些系统已经把 `ga` 分配给其他工具。先检查：
|
||||
|
||||
```bash
|
||||
type ga
|
||||
```
|
||||
|
||||
如果解析到意料之外的位置，就不要依赖这个快捷命令。请进入安装目录运行 `python launch.pyw` 或 `python frontends/tuiapp_v2.py`。
|
||||
|
||||
#### Windows 上 TUI 显示异常
|
||||
|
||||
TUI 在 Windows 上依赖终端、字体和 `textual` 版本。
|
||||
|
||||
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 终端的最佳配置，把所有字体和显示不兼容的问题修一遍。"*
|
||||
|
||||
#### Linux 上 `pywebview` 安装失败
|
||||
|
||||
桌面模式依赖 GTK / WebKit。Debian / Ubuntu：
|
||||
|
||||
```bash
|
||||
sudo apt install libgtk-3-dev libwebkit2gtk-4.1-dev
|
||||
pip install pywebview
|
||||
```
|
||||
|
||||
无头服务器建议使用 TUI，或用浏览器方式运行 Streamlit，不要强行启桌面模式。
|
||||
|
||||
### 升级已有安装
|
||||
|
||||
不要为了升级而删除一个可用的 GA 目录。里面可能有用户的 `mykey.py`、记忆、技能和本地成果。
|
||||
|
||||
```bash
|
||||
cd ~/GenericAgent
|
||||
git fetch
|
||||
git pull
|
||||
uv pip install -e ".[ui]"
|
||||
```
|
||||
|
||||
如果 `git pull` 报冲突：
|
||||
|
||||
- `mykey.py`、`memory/`、`skills/`、`temp/` 和用户成果：本地优先。
|
||||
- `agent*.py`、`frontends/*`、`reflect/*`、`tools/*` 等核心代码：通常 upstream 优先，除非用户另有说明。
|
||||
- 明确解决冲突后，再 `git add` 并提交合并。
|
||||
|
||||
---
|
||||
|
||||
## 面向 LLM Agent（For LLM Agents）
|
||||
|
||||
> **重要：用 `curl` 获取本文，不要依赖会摘要网页的读取器。** 摘要常会丢掉环境变量、命令引号和安全规则。
|
||||
>
|
||||
> ```bash
|
||||
> curl -fsSL https://raw.githubusercontent.com/lsdefine/GenericAgent/refs/heads/main/docs/installation.md
|
||||
> ```
|
||||
|
||||
你正在替人类用户安装 **GenericAgent**。请直接执行、逐步验证；除非用户明确授权，不要做破坏性清理。
|
||||
|
||||
### 第 0 步：先探测再行动
|
||||
|
||||
检查：
|
||||
|
||||
1. 操作系统：`uname -a`、`$env:OS`，或 `python -c "import platform; print(platform.system())"`。
|
||||
2. 是否已安装：`~/GenericAgent/launch.pyw`、`%USERPROFILE%\GenericAgent\launch.pyw`，或 `.git` 目录。
|
||||
3. Python 版本：开发者路径必须使用 3.11 或 3.12。
|
||||
4. Git 是否可用：`git --version`。
|
||||
5. API Key 是否准备好：没有就问用户，绝不要伪造。
|
||||
|
||||
### 第 1 步：选择安装路径
|
||||
|
||||
除非用户已经有源码目录，否则默认走一键安装。
|
||||
|
||||
**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
|
||||
```
|
||||
|
||||
如果用户明确要开发者源码安装：
|
||||
|
||||
```bash
|
||||
git clone https://github.com/lsdefine/GenericAgent.git
|
||||
cd GenericAgent
|
||||
uv venv
|
||||
uv pip install -e ".[ui]"
|
||||
cp mykey_template.py mykey.py
|
||||
```
|
||||
|
||||
### 第 2 步：安全配置 Key
|
||||
|
||||
- 编辑 `mykey.py` 前先读 `mykey_template.py`。
|
||||
- 只配置用户真实提供的 Key。
|
||||
- 不要把完整 Key 打印回给用户。
|
||||
- 用户不确定时，运行 `python assets/configure_mykey.py`，或询问要使用哪家模型服务商。
|
||||
|
||||
建议提问：
|
||||
|
||||
> 你希望 GenericAgent 使用哪个 LLM？GA 支持 OpenAI 兼容接口和 Anthropic Claude 原生接口。你想配置哪家服务商，API Key 准备好了吗？
|
||||
|
||||
### 第 3 步：验证安装
|
||||
|
||||
运行：
|
||||
|
||||
```bash
|
||||
cd ~/GenericAgent
|
||||
python -c "import agent_loop; print('OK')"
|
||||
git rev-parse --short HEAD
|
||||
```
|
||||
|
||||
然后验证至少一个前端：
|
||||
|
||||
```bash
|
||||
python launch.pyw
|
||||
# 或，无桌面环境时：
|
||||
python frontends/tuiapp_v2.py
|
||||
```
|
||||
|
||||
### 第 4 步：验证与下一步
|
||||
|
||||
重新读一遍本文，并思考你是否已经正确完成所有步骤：
|
||||
|
||||
- 行动前检查了操作系统、已有安装、Python 版本、Git 和 Key 准备情况。
|
||||
- 使用了本文中文默认安装命令；不要擅自混入英文版的 `GLOBAL=1` 默认脚本。
|
||||
- 只配置了用户真实提供的 Key，且没有泄露密钥。
|
||||
- 已验证 import、Git commit hash，并至少验证了一个前端。
|
||||
|
||||
#### 对用户说 “Congratulations! 🎉”
|
||||
|
||||
对用户说：Congratulations! 🎉 你已经成功安装 GenericAgent！Windows 下可双击 `frontends/GenericAgent.exe`，或在终端运行 `python frontends/tuiapp_v2.py` 开始使用。
|
||||
|
||||
#### 回报具体结果
|
||||
|
||||
告诉用户：
|
||||
|
||||
1. 安装路径。
|
||||
2. Git commit hash。
|
||||
3. 已验证哪个前端。
|
||||
4. `mykey.py` 是否已配置，但不要泄露密钥。
|
||||
5. 下一步阅读：[Hello GenericAgent](https://datawhalechina.github.io/hello-generic-agent/) 和 [GETTING_STARTED.md](GETTING_STARTED.md)。
|
||||
|
||||
#### 请求 Star ⭐
|
||||
|
||||
确认安装可用后，可以询问：
|
||||
|
||||
> 如果你觉得 GenericAgent 有帮助，愿意给仓库点一个 Star 吗？这会帮助项目成长！⭐
|
||||
|
||||
只有在用户明确同意后，才可以打开或执行任何与 Star 仓库相关的操作。
|
||||
|
||||
### 绝对不要做
|
||||
|
||||
- 不要运行 `pip install genericagent`；GA 不是 PyPI 包。
|
||||
- 未经明确授权，不要删除 `~/GenericAgent` 或 `%USERPROFILE%\GenericAgent` 做“干净安装”。
|
||||
- 不要伪造 API Key，也不要把示例 Key 当真。
|
||||
- 不要假设 `ga` 命令一定可用；先检查。
|
||||
- 不要依赖 `ga update`；按上面的 `git fetch`、`git pull` 和重装依赖流程做。
|
||||
|
||||
---
|
||||
|
||||
## 参考资料
|
||||
|
||||
- 主 README：[README.md](../README.md)
|
||||
- Getting Started：[GETTING_STARTED.md](GETTING_STARTED.md)
|
||||
- Datawhale 教程：<https://datawhalechina.github.io/hello-generic-agent/>
|
||||
- 技术报告：<https://arxiv.org/abs/2604.17091>
|
||||
- English installation guide: [installation.md](installation.md)
|
||||
@@ -0,0 +1,85 @@
|
||||
# GenericAgent 桌面版安装指南
|
||||
|
||||
## 📦 安装步骤
|
||||
|
||||
### 第一步：打开安装包
|
||||
|
||||
双击下载的 `GenericAgent_x.x.x_aarch64.dmg` 文件，会弹出一个安装窗口。
|
||||
|
||||
将左边的 **GenericAgent** 图标拖到右边的 **Applications** 文件夹图标上，等待拷贝完成。
|
||||
|
||||
拷贝完成后，可以右键点击桌面上的 DMG 图标，选择「推出」来关闭安装包。
|
||||
|
||||
---
|
||||
|
||||
### 第二步：首次打开前的准备（重要）
|
||||
|
||||
由于本应用暂未通过 Apple 官方签名认证，macOS 会阻止首次打开。这是正常的安全提示，不代表应用有问题。
|
||||
|
||||
请按以下步骤解除限制：
|
||||
|
||||
#### 1. 打开「终端」应用
|
||||
|
||||
不知道终端是什么？别担心，它就是一个可以输入命令的工具。打开方式：
|
||||
|
||||
- 按下键盘上的 `Command(⌘) + 空格键`，会弹出搜索框（Spotlight）
|
||||
- 输入 `终端` 或 `Terminal`，按回车键打开
|
||||
|
||||
你会看到一个黑色或白色的文字窗口，里面有一个闪烁的光标，这就是终端。
|
||||
|
||||
#### 2. 输入解除限制的命令
|
||||
|
||||
在终端窗口中，复制粘贴以下这行命令（整行复制，一个字都不要漏��：
|
||||
|
||||
```
|
||||
xattr -cr /Applications/GenericAgent.app
|
||||
```
|
||||
|
||||
粘贴方法：在终端窗口里按 `Command(⌘) + V`
|
||||
|
||||
然后按 `回车键(Enter)` 执行。
|
||||
|
||||
> 如果终端要求输入密码，输入你的 Mac 开机密码（输入时不会显示任何字符，这是正常的），然后按回车。
|
||||
|
||||
执行完毕后，终端不会有任何提示，这代表成功了。
|
||||
|
||||
#### 3. 打开 GenericAgent
|
||||
|
||||
现在可以正常打开应用了：
|
||||
|
||||
- 打开 Finder → 侧边栏点击「应用程序」
|
||||
- 找到 **GenericAgent**，双击打开
|
||||
|
||||
首次打开可能还会弹出一个确认框，点击「打开」即可。之后就不会再弹出了。
|
||||
|
||||
---
|
||||
|
||||
## ❓ 常见问题
|
||||
|
||||
### Q: 提示「GenericAgent 已损坏，无法打开」怎么办？
|
||||
|
||||
这不是真的损坏，是 macOS 的安全机制。请回到第二步，确保在终端中执行了 `xattr -cr` 命令。
|
||||
|
||||
### Q: 提示「无法打开，因为无法验证开发者」怎么办？
|
||||
|
||||
方法一（推荐）：执行第二步的终端命令。
|
||||
|
||||
方法二：右键点击 GenericAgent.app → 选择「打开」→ 在弹出的对话框中点击「打开」。
|
||||
|
||||
### Q: 我的 Mac 是 Intel 芯片的，能用吗？
|
||||
|
||||
当前版本仅支持 Apple Silicon（M1/M2/M3/M4）芯片的 Mac。如果你的 Mac 是 2020 年之前购买的，大概率是 Intel 芯片，暂时无法使用本安装包。
|
||||
|
||||
查看方法：点击左上角 → 「关于本机」，如果芯片一栏显示 Apple M1/M2/M3/M4，就可以使用。
|
||||
|
||||
### Q: 终端命令执行后没有任何反应？
|
||||
|
||||
没有反应就是成功了。Unix/macOS 的设计哲学是「没有消息就是好消息」。
|
||||
|
||||
---
|
||||
|
||||
## 🔧 系统要求
|
||||
|
||||
- macOS 12 (Monterey) 或更高版本
|
||||
- Apple Silicon 芯片（M1/M2/M3/M4）
|
||||
- 约 50MB 可用磁盘空间
|
||||
Reference in New Issue
Block a user