polish: rewrite install guide as clear channel menu + decision tree
Installation flow now: 1. pip install (one command) 2. Ask: local or server? 3. Show FULL channel menu with clear explanations: - What each channel does - What's needed to set it up - What you miss without it - Pre-selected: zero-config channels - Recommended: Exa Search (free) - Optional: Reddit/Bilibili proxy, Twitter Advanced, WeChat, XHS 4. Configure selected channels (one command each, auto-tested) 5. Final health check Key improvements: - User sees ALL options at once with tradeoffs - 'Without it' explanations help users decide - Server users get clear proxy guidance (Reddit + Bilibili share same proxy) - Reddit clarified: search works FREE via Exa, only full reader needs proxy
This commit is contained in:
Panniantong
+130
-65
@@ -9,119 +9,184 @@ Install and configure Agent Eyes by following the instructions here:
|
|||||||
https://raw.githubusercontent.com/Panniantong/agent-eyes/main/docs/install.md
|
https://raw.githubusercontent.com/Panniantong/agent-eyes/main/docs/install.md
|
||||||
```
|
```
|
||||||
|
|
||||||
That's it. Your Agent will handle the rest.
|
Your Agent will handle everything. You just answer a few questions.
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
## For AI Agents
|
## For AI Agents
|
||||||
|
|
||||||
You are installing Agent Eyes — a tool that gives you (the Agent) eyes to see the entire internet.
|
You are installing Agent Eyes — giving yourself eyes to see the entire internet.
|
||||||
Follow this decision tree exactly. Do not skip steps.
|
Follow this guide step by step. Do not skip steps.
|
||||||
|
|
||||||
### Step 1: Ask user 3 questions
|
### Step 1: Install
|
||||||
|
|
||||||
Ask the user these questions to determine install flags:
|
|
||||||
|
|
||||||
**Q1: Are you on a local computer or a server/VPS?**
|
|
||||||
- Local → `--env=local`
|
|
||||||
- Server/VPS → `--env=server`
|
|
||||||
|
|
||||||
**Q2: Do you want web search? (free, recommended)**
|
|
||||||
- Yes → `--search=yes`
|
|
||||||
- No → `--search=no`
|
|
||||||
|
|
||||||
**Q3: (Only if server) Do you have a residential proxy for Reddit/Bilibili?**
|
|
||||||
- Yes → `--proxy=http://user:pass@ip:port` (ask user for the proxy URL)
|
|
||||||
- No / Don't know → omit `--proxy`
|
|
||||||
- Tell user: "Reddit and Bilibili block server IPs. You can get a proxy at https://www.webshare.io for $1/month. Want to set it up later?"
|
|
||||||
|
|
||||||
### Step 2: Install
|
|
||||||
|
|
||||||
```bash
|
```bash
|
||||||
pip install git+https://github.com/Panniantong/agent-eyes.git
|
pip install git+https://github.com/Panniantong/agent-eyes.git
|
||||||
```
|
```
|
||||||
|
|
||||||
If fails, try `pip3` or add `--user`.
|
If fails: try `pip3`, or add `--user`, or `--break-system-packages`.
|
||||||
|
|
||||||
### Step 3: Run installer with flags
|
|
||||||
|
|
||||||
Based on answers from Step 1, construct and run ONE command:
|
|
||||||
|
|
||||||
|
Verify:
|
||||||
```bash
|
```bash
|
||||||
agent-eyes install --env=<local|server> --search=<yes|no> [--proxy=<proxy_url>]
|
agent-eyes version
|
||||||
```
|
```
|
||||||
|
|
||||||
**Examples:**
|
### Step 2: Ask environment
|
||||||
- Local, wants search: `agent-eyes install --env=local --search=yes`
|
|
||||||
- Server, wants search, has proxy: `agent-eyes install --env=server --search=yes --proxy=http://user:pass@ip:port`
|
|
||||||
- Server, wants search, no proxy: `agent-eyes install --env=server --search=yes`
|
|
||||||
- Local, no search: `agent-eyes install --env=local --search=no`
|
|
||||||
|
|
||||||
### Step 4: Configure Exa key (only if --search=yes)
|
Ask the user:
|
||||||
|
|
||||||
The installer will tell you search needs a key. Ask the user:
|
> "You're installing Agent Eyes! First question: are you running on a **local computer** or a **server/VPS**?"
|
||||||
|
|
||||||
> "Web search needs a free API key. Go to https://exa.ai, sign up, copy your API Key, and send it to me."
|
Remember their answer — it affects which channels need extra setup.
|
||||||
|
|
||||||
When user provides the key, run:
|
### Step 3: Show channel menu
|
||||||
|
|
||||||
|
Show the user this menu. Explain each option clearly.
|
||||||
|
|
||||||
|
**Present it like this** (adjust the Bilibili line based on Step 2 answer):
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
> Here are all the channels Agent Eyes supports. I'll help you set up whichever ones you want.
|
||||||
|
>
|
||||||
|
> **Already active — no setup needed ✅**
|
||||||
|
> These work right now, nothing to configure:
|
||||||
|
> - ✅ **Web pages** — read any URL
|
||||||
|
> - ✅ **GitHub** — read repos, issues, PRs + search repos
|
||||||
|
> - ✅ **RSS** — read any RSS/Atom feed
|
||||||
|
> - ✅ **YouTube** — video transcripts via yt-dlp
|
||||||
|
> - ✅ **Twitter basic** — read individual tweets
|
||||||
|
>
|
||||||
|
> **Recommended — free, takes 30 seconds each 🔍**
|
||||||
|
> - 🔍 **Exa Search** (STRONGLY RECOMMENDED)
|
||||||
|
> - What it unlocks: **full web search + Reddit search + Twitter search**
|
||||||
|
> - What you need: one free API key from https://exa.ai (1000 searches/month free)
|
||||||
|
> - Without it: I can read URLs you give me, but can't search the internet for you
|
||||||
|
>
|
||||||
|
> **Optional — easy setup 🔧**
|
||||||
|
> - 🐦 **Twitter Advanced** — search timelines, read threads, deep search
|
||||||
|
> - What you need: export cookies from your browser (free, 2 minutes)
|
||||||
|
> - Without it: I can still search Twitter via Exa and read individual tweets
|
||||||
|
>
|
||||||
|
> - 📺 **Bilibili** [IF LOCAL: "already works ✅"] [IF SERVER: "⚠️ needs proxy — Bilibili blocks server IPs. Proxy costs ~$1/month at webshare.io. Without it, Bilibili won't work from your server."]
|
||||||
|
>
|
||||||
|
> **Optional — more setup 🔨**
|
||||||
|
> - 📖 **Reddit Full Reader** — read complete posts + all comments
|
||||||
|
> - What you need: residential proxy (~$1/month at https://webshare.io)
|
||||||
|
> - Without it: I can still **search** Reddit content via Exa (free!), just can't read full posts with all comments
|
||||||
|
> - [IF SERVER: "Same proxy works for both Reddit and Bilibili"]
|
||||||
|
>
|
||||||
|
> - 💬 **WeChat** — read WeChat public articles
|
||||||
|
> - What you need: install browser component (~150MB download)
|
||||||
|
>
|
||||||
|
> - 📕 **XiaoHongShu** — read XHS notes
|
||||||
|
> - What you need: browser component + scan QR code once to login
|
||||||
|
>
|
||||||
|
> **Which ones would you like me to set up?** (I recommend at least Exa Search)
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
Wait for user to choose. Then proceed to Step 4.
|
||||||
|
|
||||||
|
### Step 4: Run installer
|
||||||
|
|
||||||
```bash
|
```bash
|
||||||
agent-eyes configure exa-key THE_KEY_USER_PROVIDED
|
agent-eyes install --env=<local|server>
|
||||||
```
|
```
|
||||||
|
|
||||||
This automatically tests the key and confirms it works.
|
### Step 5: Configure selected channels
|
||||||
|
|
||||||
### Step 5: Configure proxy (only if --env=server and user wants Reddit/Bilibili)
|
For each channel the user selected, run the corresponding configure command.
|
||||||
|
Each command auto-tests after configuring.
|
||||||
|
|
||||||
If the user wants to set up a proxy (now or later), they need to:
|
#### If user selected: Exa Search
|
||||||
1. Go to https://www.webshare.io and sign up ($1/month for residential proxy)
|
|
||||||
2. Get their proxy URL (format: `http://username:password@ip:port`)
|
|
||||||
3. Send it to you
|
|
||||||
|
|
||||||
Then run:
|
Tell the user:
|
||||||
|
> "Go to https://exa.ai, sign up (free), and send me your API Key."
|
||||||
|
|
||||||
|
When they provide it:
|
||||||
|
```bash
|
||||||
|
agent-eyes configure exa-key THE_KEY
|
||||||
|
```
|
||||||
|
Expected: `✅ exa-key configured! Testing search... ✅ Search works!`
|
||||||
|
|
||||||
|
#### If user selected: Reddit Full Reader and/or Bilibili (on server)
|
||||||
|
|
||||||
|
Tell the user:
|
||||||
|
> "Reddit and Bilibili need a residential proxy. Steps:
|
||||||
|
> 1. Go to https://www.webshare.io
|
||||||
|
> 2. Sign up and get a proxy ($1/month plan is enough)
|
||||||
|
> 3. Copy your proxy address (format: http://username:password@ip:port)
|
||||||
|
> 4. Send it to me"
|
||||||
|
|
||||||
|
When they provide it:
|
||||||
```bash
|
```bash
|
||||||
agent-eyes configure proxy THE_PROXY_URL
|
agent-eyes configure proxy THE_PROXY_URL
|
||||||
```
|
```
|
||||||
|
Expected: `✅ proxy configured! Testing Reddit... ✅ Reddit accessible!`
|
||||||
|
|
||||||
This automatically tests the proxy against Reddit and confirms it works.
|
#### If user selected: Twitter Advanced
|
||||||
|
|
||||||
### Step 6: Final verification
|
Tell the user:
|
||||||
|
> "Twitter Advanced needs cookies from your browser. Steps:
|
||||||
|
> 1. Open https://x.com in Chrome and make sure you're logged in
|
||||||
|
> 2. Press F12 → Application tab → Cookies → https://x.com
|
||||||
|
> 3. Find and copy these two values: **auth_token** and **ct0**
|
||||||
|
> 4. Send them to me"
|
||||||
|
|
||||||
|
When they provide cookies:
|
||||||
|
```bash
|
||||||
|
# birdx cookie setup (if birdx is available)
|
||||||
|
which birdx || pip install birdx
|
||||||
|
# Configure birdx with cookies (method varies by birdx version)
|
||||||
|
```
|
||||||
|
|
||||||
|
#### If user selected: WeChat
|
||||||
|
|
||||||
|
```bash
|
||||||
|
pip install agent-eyes[browser]
|
||||||
|
playwright install chromium
|
||||||
|
```
|
||||||
|
Tell user: "✅ WeChat is ready! Send me any WeChat article URL."
|
||||||
|
|
||||||
|
#### If user selected: XiaoHongShu
|
||||||
|
|
||||||
|
```bash
|
||||||
|
pip install agent-eyes[browser]
|
||||||
|
playwright install chromium
|
||||||
|
```
|
||||||
|
Tell user: "I'll need you to scan a QR code once to log in. Ready?" Then read the guide: read the file at `agent_eyes/guides/setup-xiaohongshu.md` for detailed steps.
|
||||||
|
|
||||||
|
### Step 6: Final check
|
||||||
|
|
||||||
```bash
|
```bash
|
||||||
agent-eyes doctor
|
agent-eyes doctor
|
||||||
```
|
```
|
||||||
|
|
||||||
Report results to the user. Example:
|
Summarize results for the user naturally. Example:
|
||||||
|
|
||||||
> "✅ Agent Eyes is ready! Here's what I can do:
|
> "✅ All done! Here's what I can do now:
|
||||||
> - 📖 Read: Web, GitHub, YouTube, Bilibili, RSS, Tweets
|
> - 📖 Read: Web, GitHub, YouTube, RSS, Tweets, Reddit, Bilibili
|
||||||
> - 🔍 Search: Web, GitHub, Reddit, Twitter
|
> - 🔍 Search: Web, GitHub, Reddit, Twitter
|
||||||
>
|
>
|
||||||
> Try it: ask me to search or read anything!"
|
> Try asking me things like:
|
||||||
|
> - 'Search Reddit for best self-hosted LLM'
|
||||||
|
> - 'Read this GitHub repo: [URL]'
|
||||||
|
> - 'What's trending on Twitter about AI agents?'"
|
||||||
|
|
||||||
### Summary of commands
|
---
|
||||||
|
|
||||||
|
## Quick Reference
|
||||||
|
|
||||||
| Action | Command |
|
| Action | Command |
|
||||||
|--------|---------|
|
|--------|---------|
|
||||||
| Install | `pip install git+https://github.com/Panniantong/agent-eyes.git` |
|
| Install | `pip install git+https://github.com/Panniantong/agent-eyes.git` |
|
||||||
| One-shot setup | `agent-eyes install --env=local --search=yes` |
|
| Setup | `agent-eyes install --env=<local\|server>` |
|
||||||
| Add Exa key | `agent-eyes configure exa-key YOUR_KEY` |
|
| Add Exa key | `agent-eyes configure exa-key YOUR_KEY` |
|
||||||
| Add proxy | `agent-eyes configure proxy http://user:pass@ip:port` |
|
| Add proxy | `agent-eyes configure proxy http://user:pass@ip:port` |
|
||||||
| Add GitHub token | `agent-eyes configure github-token YOUR_TOKEN` |
|
|
||||||
| Health check | `agent-eyes doctor` |
|
| Health check | `agent-eyes doctor` |
|
||||||
| Read URL | `agent-eyes read <url>` |
|
| Read any URL | `agent-eyes read <url>` |
|
||||||
| Search web | `agent-eyes search "query"` |
|
| Search web | `agent-eyes search "query"` |
|
||||||
| Search GitHub | `agent-eyes search-github "query"` |
|
| Search GitHub | `agent-eyes search-github "query"` |
|
||||||
| Search Reddit | `agent-eyes search-reddit "query"` |
|
| Search Reddit | `agent-eyes search-reddit "query"` |
|
||||||
| Search Twitter | `agent-eyes search-twitter "query"` |
|
| Search Twitter | `agent-eyes search-twitter "query"` |
|
||||||
|
|
||||||
### Troubleshooting
|
|
||||||
|
|
||||||
| Problem | Solution |
|
|
||||||
|---------|----------|
|
|
||||||
| `pip: command not found` | Try `pip3` |
|
|
||||||
| `Permission denied` | Add `--user` flag |
|
|
||||||
| `agent-eyes: command not found` | Use `python3 -m agent_eyes.cli` instead |
|
|
||||||
| Search returns "Exa API key not configured" | `agent-eyes configure exa-key YOUR_KEY` |
|
|
||||||
| Reddit returns 403 | `agent-eyes configure proxy http://user:pass@ip:port` |
|
|
||||||
|
|||||||
Reference in New Issue
Block a user