diff --git a/agent_eyes/cli.py b/agent_eyes/cli.py index f87f454..fe24ccd 100644 --- a/agent_eyes/cli.py +++ b/agent_eyes/cli.py @@ -70,8 +70,8 @@ def main(): # ── install ── p_install = sub.add_parser("install", help="One-shot installer with flags") - p_install.add_argument("--env", choices=["local", "server"], default="local", - help="Environment: local computer or server/VPS") + p_install.add_argument("--env", choices=["local", "server", "auto"], default="auto", + help="Environment: local, server, or auto-detect") p_install.add_argument("--search", choices=["yes", "no"], default="yes", help="Enable web search (needs free Exa API key)") p_install.add_argument("--proxy", default="", @@ -132,6 +132,16 @@ def _cmd_install(args): print("👁️ Agent Eyes Installer") print("=" * 40) + # Auto-detect environment + env = args.env + if env == "auto": + env = _detect_environment() + + if env == "server": + print(f"📡 Environment: Server/VPS (auto-detected)") + else: + print(f"💻 Environment: Local computer (auto-detected)") + # Apply flags if args.exa_key: config.set("exa_api_key", args.exa_key) @@ -143,16 +153,14 @@ def _cmd_install(args): print(f"✅ Proxy configured for Reddit + Bilibili") # Environment-specific advice - if args.env == "server": - print(f"📡 Environment: Server/VPS") - if not args.proxy: - print(f"⚠️ Reddit and Bilibili block server IPs.") - print(f" To unlock: agent-eyes configure proxy http://user:pass@ip:port") - print(f" Recommend: https://www.webshare.io ($1/month)") - else: - print(f"💻 Environment: Local computer") + if env == "server" and not args.proxy: + print() + print("💡 Tip: Reddit and Bilibili block server IPs.") + print(" Reddit search still works via Exa (free).") + print(" For full access: agent-eyes configure proxy http://user:pass@ip:port") + print(" Cheap option: https://www.webshare.io ($1/month)") - # Test zero-config features + # Test channels print() print("Testing channels...") results = check_all(config) @@ -161,19 +169,58 @@ def _cmd_install(args): print(f"✅ {ok}/{total} channels active") # What's missing - if args.search == "yes" and not args.exa_key: + if args.search == "yes" and not args.exa_key and not config.get("exa_api_key"): print() - print("🔍 Search not yet configured. Run:") + print("🔍 Recommended: unlock search with a free Exa API key") print(" agent-eyes configure exa-key YOUR_KEY") - print(" (Get free key: https://exa.ai)") + print(" Get free key: https://exa.ai") # Final status print() print(format_report(results)) print() print("✅ Installation complete!") - if ok < total: - print(f" Run `agent-eyes configure` to unlock remaining channels.") + + +def _detect_environment(): + """Auto-detect if running on local computer or server.""" + import os + + # Check common server indicators + indicators = 0 + + # SSH session + if os.environ.get("SSH_CONNECTION") or os.environ.get("SSH_CLIENT"): + indicators += 2 + + # Docker / container + if os.path.exists("/.dockerenv") or os.path.exists("/run/.containerenv"): + indicators += 2 + + # No display (headless) + if not os.environ.get("DISPLAY") and not os.environ.get("WAYLAND_DISPLAY"): + indicators += 1 + + # Cloud VM identifiers + for cloud_file in ["/sys/hypervisor/uuid", "/sys/class/dmi/id/product_name"]: + if os.path.exists(cloud_file): + try: + content = open(cloud_file).read().lower() + if any(x in content for x in ["amazon", "google", "microsoft", "digitalocean", "linode", "vultr", "hetzner"]): + indicators += 2 + except: + pass + + # systemd-detect-virt + try: + import subprocess + result = subprocess.run(["systemd-detect-virt"], capture_output=True, text=True, timeout=3) + if result.returncode == 0 and result.stdout.strip() != "none": + indicators += 1 + except: + pass + + return "server" if indicators >= 2 else "local" def _cmd_configure(args): diff --git a/docs/install.md b/docs/install.md index 19d39ed..c2c40b5 100644 --- a/docs/install.md +++ b/docs/install.md @@ -2,243 +2,129 @@ ## For Humans -Copy and paste this to your AI Agent (Claude Code, OpenClaw, Cursor, etc.): +Copy this to your AI Agent: ``` -Install and configure Agent Eyes by following the instructions here: -https://raw.githubusercontent.com/Panniantong/agent-eyes/main/docs/install.md +Install and configure Agent Eyes: https://raw.githubusercontent.com/Panniantong/agent-eyes/main/docs/install.md ``` -Your Agent will handle everything. You just answer a few questions. - --- ## For AI Agents -You are installing Agent Eyes — giving yourself eyes to see the entire internet. -Follow this guide step by step. Do not improvise. +Follow these steps exactly. Minimize questions to the user. -### Step 1: Install +### Step 1: Install + auto-detect ```bash -pip install git+https://github.com/Panniantong/agent-eyes.git +pip install git+https://github.com/Panniantong/agent-eyes.git || pip3 install git+https://github.com/Panniantong/agent-eyes.git +agent-eyes doctor ``` -If fails: try `pip3`, or add `--user`, or `--break-system-packages`. +Read the doctor output. It tells you: +- What's already working (zero-config channels) +- What needs a key/cookie/proxy -Verify: +Also auto-detect the environment: ```bash -agent-eyes version +agent-eyes install --env=auto ``` +This command auto-detects local vs server (checks if running in SSH, Docker, or cloud VM). -### Step 2: Detect environment +### Step 2: Show ONE simple summary to user -Ask the user: +Based on doctor output, tell the user what's already working and what ONE thing you recommend: -> "First question: are you running on a **local computer** or a **server/VPS**?" +> "✅ Agent Eyes installed! You already have: web pages, GitHub, RSS, YouTube. +> +> **One recommendation**: get a free Exa API key to unlock web search + Reddit search + Twitter search. +> → Go to https://exa.ai, sign up (free), and send me the API key. +> +> (I can also set up Twitter, Bilibili, XiaoHongShu, and Reddit later — just ask anytime.)" -This determines what works out of the box and what needs extra setup. +**Key principle**: only ask for ONE thing now. Don't overwhelm with choices. -### Step 3: Show channel menu - -Present this menu to the user. Adjust the details based on their environment (local vs server). - -**IMPORTANT**: Make sure the user understands what each tier means and what they get/miss. - ---- - -> **Agent Eyes supports these channels. Let me help you choose what to set up.** -> -> --- -> -> **🟢 Already active — works right now, nothing needed:** -> -> | Channel | What it does | -> |---------|-------------| -> | ✅ Web pages | Read any URL on the internet | -> | ✅ GitHub | Read repos, issues, PRs + search repositories | -> | ✅ RSS | Read any RSS/Atom feed | -> -> These 3 channels are always available. No setup needed. -> -> --- -> -> **🔵 Cookie-based — free, just need to export cookies from your browser (~2 min each):** -> -> | Channel | What it does | Without cookies | -> |---------|-------------|-----------------| -> | 🐦 Twitter/X | Read tweets, search timelines, read threads | Can still read individual tweet URLs (basic mode) | -> | 📺 YouTube | Video transcripts (public + age-restricted) | Public videos work without cookies; age-restricted/member-only videos need cookies | -> | 📺 Bilibili | Video info + subtitles | [LOCAL: works without cookies ✅] [SERVER: ⚠️ blocked — needs proxy, see below] | -> | 📕 XiaoHongShu | Read XHS notes + comments | Falls back to basic web reading (less content) | -> -> **How to export cookies**: open the site in Chrome → F12 → Application → Cookies → copy the values. I'll walk you through it for each one you choose. -> -> --- -> -> **🟡 Free API key — one key unlocks 3 search capabilities (~30 seconds):** -> -> | Channel | What it unlocks | -> |---------|----------------| -> | 🔍 Exa Search (RECOMMENDED) | **Web search + Reddit search + Twitter search** — one free key powers all three | -> -> Without Exa: I can read URLs you give me, but I cannot search the internet for you. -> With Exa: I can find information across the entire web, Reddit, and Twitter. -> -> Free tier: 1000 searches/month at https://exa.ai — more than enough for most users. -> -> --- -> -> **🟠 Proxy-based — needed only on servers, $1/month shared across channels:** -> -> | Channel | Why proxy needed | Without proxy | -> |---------|-----------------|---------------| -> | 📖 Reddit | Reddit blocks server IPs | **Reddit search still works via Exa (free!)** — you just can't read full posts with all comments | -> | 📺 Bilibili | Bilibili blocks server IPs | Won't work from server | -> -> [ONLY SHOW THIS SECTION IF USER SAID "SERVER"] -> [IF LOCAL: Skip this section — Reddit and Bilibili work directly on local computers] -> -> One proxy works for both. Recommend: https://www.webshare.io ($1/month residential proxy). -> Same proxy also works for Bilibili cookies-based access. -> -> --- -> -> **Which channels do you want me to set up?** -> (I recommend: **Exa Search** for sure, plus any cookie-based channels you actually use) - ---- - -Wait for the user to choose. Then go to Step 4. - -### Step 4: Run base installer - -```bash -agent-eyes install --env= -``` - -### Step 5: Configure each selected channel - -Run the corresponding command for each channel the user chose. -Every configure command auto-tests and gives instant feedback (✅ or ❌). - ---- - -#### Exa Search - -Tell user: "Go to https://exa.ai, sign up (free), copy your API Key, and send it to me." +### Step 3: Configure Exa (if user provides key) ```bash agent-eyes configure exa-key THE_KEY ``` ---- +After success, tell user: -#### Twitter/X +> "✅ Done! I can now search the web, Reddit, and Twitter for you. +> +> Want me to set up any of these too? (just say which ones) +> - 🐦 Twitter deep search (need browser cookies, 2 min) +> - 📕 XiaoHongShu (need browser cookies, 2 min) +> - 📺 Bilibili (need browser cookies, 2 min) +> - 📖 Reddit full reader (need $1/month proxy — search already works via Exa!) +> +> Or just say 'all' and I'll walk you through each one." -Tell user: -> "Open https://x.com in Chrome (make sure you're logged in). -> Press F12 → Application → Cookies → https://x.com -> Find these two values: **auth_token** and **ct0** -> Copy both and send them to me." +### Step 4: Configure additional channels (only if user asks) +For each channel the user asks for, use the appropriate command: + +**Twitter:** +Ask: "Open x.com in Chrome → F12 → Application → Cookies → copy **auth_token** and **ct0**" ```bash agent-eyes configure twitter-cookies AUTH_TOKEN CT0 ``` ---- - -#### YouTube (cookies for age-restricted videos) - -Tell user: -> "Most YouTube videos work without any setup. If you want access to age-restricted or member-only videos: -> Which browser do you use? (chrome/firefox/edge/safari)" +**XiaoHongShu:** +Ask: "Open xiaohongshu.com in Chrome → F12 → Network → click any request → copy the Cookie header value" +```bash +agent-eyes configure xhs-cookie COOKIE_STRING +``` +**YouTube (age-restricted only):** +Ask: "Which browser do you use?" ```bash agent-eyes configure youtube-cookies chrome ``` -(replace `chrome` with whatever browser they use — yt-dlp reads cookies directly from the browser) ---- - -#### Bilibili - -**If local**: Already works. No setup needed. - -**If server**: Needs proxy (same proxy as Reddit, see Proxy section below). - -If user also wants cookies for member-only content: -> "Open https://bilibili.com in Chrome (logged in). -> F12 → Application → Cookies → find **SESSDATA** -> Send it to me." - -(For now, Bilibili public API works without cookies. Cookie support is for future member-only content.) - ---- - -#### XiaoHongShu - -Tell user: -> "Open https://www.xiaohongshu.com in Chrome (make sure you're logged in). -> Press F12 → Application → Cookies → https://www.xiaohongshu.com -> Select all cookies, right-click → Copy All -> Or just copy the full cookie string from a network request header. -> Send it to me." +**Bilibili:** +- Auto-detected as local → already works, nothing needed +- Auto-detected as server → needs proxy (same as Reddit, see below) +**Reddit full reader + Bilibili (server only):** +Ask: "Reddit/Bilibili block server IPs. Get a $1/month residential proxy at webshare.io, then send me the proxy address." ```bash -agent-eyes configure xhs-cookie THE_COOKIE_STRING +agent-eyes configure proxy http://user:pass@ip:port ``` ---- - -#### Proxy (Reddit + Bilibili on server) - -Tell user: -> "Reddit and Bilibili block server IPs. You need a residential proxy to access them. -> 1. Go to https://www.webshare.io -> 2. Sign up and get a residential proxy ($1/month is enough) -> 3. Copy your proxy address (format: http://username:password@ip:port) -> 4. Send it to me" - -```bash -agent-eyes configure proxy THE_PROXY_URL -``` - -This configures the proxy for both Reddit and Bilibili at once. - ---- - -### Step 6: Final health check +### Step 5: Final status ```bash agent-eyes doctor ``` -Summarize what's working for the user. Example: - -> "✅ All done! Here's what I can do now: +> "✅ All set! Here's what I can do: +> [list active channels] > -> 📖 **Read**: Web, GitHub, YouTube, Bilibili, Twitter, XiaoHongShu, RSS -> 🔍 **Search**: Web, GitHub, Reddit, Twitter -> -> Try it out — ask me to search or read anything!" +> Try: 'search Reddit for ...' or 'read this URL: ...'" --- +## Configure anything later + +Users can ask their Agent to configure new channels anytime: +- "Help me set up Twitter for Agent Eyes" +- "I got a proxy, configure it for Agent Eyes" +- "Add my XiaoHongShu cookies" + +The Agent runs `agent-eyes configure ` — each command auto-tests. + ## Quick Reference -| Action | Command | -|--------|---------| -| Install | `pip install git+https://github.com/Panniantong/agent-eyes.git` | -| Base setup | `agent-eyes install --env=` | -| Add Exa key | `agent-eyes configure exa-key YOUR_KEY` | -| Add Twitter | `agent-eyes configure twitter-cookies AUTH_TOKEN CT0` | -| Add YouTube | `agent-eyes configure youtube-cookies chrome` | -| Add XiaoHongShu | `agent-eyes configure xhs-cookie COOKIE_STRING` | -| Add proxy | `agent-eyes configure proxy http://user:pass@ip:port` | -| Health check | `agent-eyes doctor` | -| Read 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"` | +| Command | What it does | +|---------|-------------| +| `agent-eyes doctor` | Show what's working | +| `agent-eyes configure exa-key KEY` | Unlock web/Reddit/Twitter search | +| `agent-eyes configure twitter-cookies TOKEN CT0` | Unlock Twitter deep search | +| `agent-eyes configure xhs-cookie COOKIE` | Unlock XiaoHongShu | +| `agent-eyes configure youtube-cookies chrome` | Unlock age-restricted YouTube | +| `agent-eyes configure proxy URL` | Unlock Reddit + Bilibili (server) | +| `agent-eyes read ` | Read any URL | +| `agent-eyes search "query"` | Search the web |