chore: import upstream snapshot with attribution
This commit is contained in:
wehub-resource-sync
@@ -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>
|
||||
Reference in New Issue
Block a user