From 6b023b660773de8da6530b2faf709e20726fc3e9 Mon Sep 17 00:00:00 2001 From: Panniantong Date: Tue, 24 Feb 2026 06:24:08 +0100 Subject: [PATCH] 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 --- docs/install.md | 195 ++++++++++++++++++++++++++++++++---------------- 1 file changed, 130 insertions(+), 65 deletions(-) diff --git a/docs/install.md b/docs/install.md index 5982d03..7cc87c1 100644 --- a/docs/install.md +++ b/docs/install.md @@ -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 ``` -That's it. Your Agent will handle the rest. +Your Agent will handle everything. You just answer a few questions. --- ## For AI Agents -You are installing Agent Eyes — a tool that gives you (the Agent) eyes to see the entire internet. -Follow this decision tree exactly. Do not skip steps. +You are installing Agent Eyes — giving yourself eyes to see the entire internet. +Follow this guide step by step. Do not skip steps. -### Step 1: Ask user 3 questions - -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 +### Step 1: Install ```bash pip install git+https://github.com/Panniantong/agent-eyes.git ``` -If fails, try `pip3` or add `--user`. - -### Step 3: Run installer with flags - -Based on answers from Step 1, construct and run ONE command: +If fails: try `pip3`, or add `--user`, or `--break-system-packages`. +Verify: ```bash -agent-eyes install --env= --search= [--proxy=] +agent-eyes version ``` -**Examples:** -- 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 2: Ask environment -### 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 -agent-eyes configure exa-key THE_KEY_USER_PROVIDED +agent-eyes install --env= ``` -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: -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 +#### If user selected: Exa Search -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 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 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: -> - 📖 Read: Web, GitHub, YouTube, Bilibili, RSS, Tweets +> "✅ All done! Here's what I can do now: +> - 📖 Read: Web, GitHub, YouTube, RSS, Tweets, Reddit, Bilibili > - 🔍 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 | |--------|---------| | 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=` | | Add Exa key | `agent-eyes configure exa-key YOUR_KEY` | | 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` | -| Read URL | `agent-eyes read ` | +| Read any URL | `agent-eyes read ` | | Search web | `agent-eyes search "query"` | | Search GitHub | `agent-eyes search-github "query"` | | Search Reddit | `agent-eyes search-reddit "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` |