polish: Steve Jobs pass — simplify install to near-zero friction
Key changes: 1. Auto-detect local vs server (SSH/Docker/cloud/headless detection) - User no longer needs to answer 'local or server?' 2. Only ask for ONE thing: Exa API key (the highest-value unlock) 3. Everything else is 'ask later' — user says 'set up Twitter' anytime 4. Install guide cut from 200 lines to 100 lines 5. No more overwhelming channel menu — just show what works + one recommendation Philosophy: default to everything working, only stop when user action is truly needed. The lazy user path: paste one line → Agent installs → 'want search? get free key at exa.ai' → done.
This commit is contained in:
Panniantong
+63
-16
@@ -70,8 +70,8 @@ def main():
|
|||||||
|
|
||||||
# ── install ──
|
# ── install ──
|
||||||
p_install = sub.add_parser("install", help="One-shot installer with flags")
|
p_install = sub.add_parser("install", help="One-shot installer with flags")
|
||||||
p_install.add_argument("--env", choices=["local", "server"], default="local",
|
p_install.add_argument("--env", choices=["local", "server", "auto"], default="auto",
|
||||||
help="Environment: local computer or server/VPS")
|
help="Environment: local, server, or auto-detect")
|
||||||
p_install.add_argument("--search", choices=["yes", "no"], default="yes",
|
p_install.add_argument("--search", choices=["yes", "no"], default="yes",
|
||||||
help="Enable web search (needs free Exa API key)")
|
help="Enable web search (needs free Exa API key)")
|
||||||
p_install.add_argument("--proxy", default="",
|
p_install.add_argument("--proxy", default="",
|
||||||
@@ -132,6 +132,16 @@ def _cmd_install(args):
|
|||||||
print("👁️ Agent Eyes Installer")
|
print("👁️ Agent Eyes Installer")
|
||||||
print("=" * 40)
|
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
|
# Apply flags
|
||||||
if args.exa_key:
|
if args.exa_key:
|
||||||
config.set("exa_api_key", 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")
|
print(f"✅ Proxy configured for Reddit + Bilibili")
|
||||||
|
|
||||||
# Environment-specific advice
|
# Environment-specific advice
|
||||||
if args.env == "server":
|
if env == "server" and not args.proxy:
|
||||||
print(f"📡 Environment: Server/VPS")
|
print()
|
||||||
if not args.proxy:
|
print("💡 Tip: Reddit and Bilibili block server IPs.")
|
||||||
print(f"⚠️ Reddit and Bilibili block server IPs.")
|
print(" Reddit search still works via Exa (free).")
|
||||||
print(f" To unlock: agent-eyes configure proxy http://user:pass@ip:port")
|
print(" For full access: agent-eyes configure proxy http://user:pass@ip:port")
|
||||||
print(f" Recommend: https://www.webshare.io ($1/month)")
|
print(" Cheap option: https://www.webshare.io ($1/month)")
|
||||||
else:
|
|
||||||
print(f"💻 Environment: Local computer")
|
|
||||||
|
|
||||||
# Test zero-config features
|
# Test channels
|
||||||
print()
|
print()
|
||||||
print("Testing channels...")
|
print("Testing channels...")
|
||||||
results = check_all(config)
|
results = check_all(config)
|
||||||
@@ -161,19 +169,58 @@ def _cmd_install(args):
|
|||||||
print(f"✅ {ok}/{total} channels active")
|
print(f"✅ {ok}/{total} channels active")
|
||||||
|
|
||||||
# What's missing
|
# 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()
|
||||||
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(" agent-eyes configure exa-key YOUR_KEY")
|
||||||
print(" (Get free key: https://exa.ai)")
|
print(" Get free key: https://exa.ai")
|
||||||
|
|
||||||
# Final status
|
# Final status
|
||||||
print()
|
print()
|
||||||
print(format_report(results))
|
print(format_report(results))
|
||||||
print()
|
print()
|
||||||
print("✅ Installation complete!")
|
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):
|
def _cmd_configure(args):
|
||||||
|
|||||||
+73
-187
@@ -2,243 +2,129 @@
|
|||||||
|
|
||||||
## For Humans
|
## 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:
|
Install and configure Agent Eyes: https://raw.githubusercontent.com/Panniantong/agent-eyes/main/docs/install.md
|
||||||
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
|
## For AI Agents
|
||||||
|
|
||||||
You are installing Agent Eyes — giving yourself eyes to see the entire internet.
|
Follow these steps exactly. Minimize questions to the user.
|
||||||
Follow this guide step by step. Do not improvise.
|
|
||||||
|
|
||||||
### Step 1: Install
|
### Step 1: Install + auto-detect
|
||||||
|
|
||||||
```bash
|
```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
|
```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
|
### Step 3: Configure Exa (if user provides key)
|
||||||
|
|
||||||
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=<local|server>
|
|
||||||
```
|
|
||||||
|
|
||||||
### 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."
|
|
||||||
|
|
||||||
```bash
|
```bash
|
||||||
agent-eyes configure exa-key THE_KEY
|
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:
|
### Step 4: Configure additional channels (only if user asks)
|
||||||
> "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."
|
|
||||||
|
|
||||||
|
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
|
```bash
|
||||||
agent-eyes configure twitter-cookies AUTH_TOKEN CT0
|
agent-eyes configure twitter-cookies AUTH_TOKEN CT0
|
||||||
```
|
```
|
||||||
|
|
||||||
---
|
**XiaoHongShu:**
|
||||||
|
Ask: "Open xiaohongshu.com in Chrome → F12 → Network → click any request → copy the Cookie header value"
|
||||||
#### YouTube (cookies for age-restricted videos)
|
```bash
|
||||||
|
agent-eyes configure xhs-cookie COOKIE_STRING
|
||||||
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)"
|
|
||||||
|
|
||||||
|
**YouTube (age-restricted only):**
|
||||||
|
Ask: "Which browser do you use?"
|
||||||
```bash
|
```bash
|
||||||
agent-eyes configure youtube-cookies chrome
|
agent-eyes configure youtube-cookies chrome
|
||||||
```
|
```
|
||||||
(replace `chrome` with whatever browser they use — yt-dlp reads cookies directly from the browser)
|
|
||||||
|
|
||||||
---
|
**Bilibili:**
|
||||||
|
- Auto-detected as local → already works, nothing needed
|
||||||
#### Bilibili
|
- Auto-detected as server → needs proxy (same as Reddit, see below)
|
||||||
|
|
||||||
**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."
|
|
||||||
|
|
||||||
|
**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
|
```bash
|
||||||
agent-eyes configure xhs-cookie THE_COOKIE_STRING
|
agent-eyes configure proxy http://user:pass@ip:port
|
||||||
```
|
```
|
||||||
|
|
||||||
---
|
### Step 5: Final status
|
||||||
|
|
||||||
#### 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
|
|
||||||
|
|
||||||
```bash
|
```bash
|
||||||
agent-eyes doctor
|
agent-eyes doctor
|
||||||
```
|
```
|
||||||
|
|
||||||
Summarize what's working for the user. Example:
|
> "✅ All set! Here's what I can do:
|
||||||
|
> [list active channels]
|
||||||
> "✅ All done! Here's what I can do now:
|
|
||||||
>
|
>
|
||||||
> 📖 **Read**: Web, GitHub, YouTube, Bilibili, Twitter, XiaoHongShu, RSS
|
> Try: 'search Reddit for ...' or 'read this URL: ...'"
|
||||||
> 🔍 **Search**: Web, GitHub, Reddit, Twitter
|
|
||||||
>
|
|
||||||
> Try it out — ask me to search or read anything!"
|
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
|
## 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 <channel> <value>` — each command auto-tests.
|
||||||
|
|
||||||
## Quick Reference
|
## Quick Reference
|
||||||
|
|
||||||
| Action | Command |
|
| Command | What it does |
|
||||||
|--------|---------|
|
|---------|-------------|
|
||||||
| Install | `pip install git+https://github.com/Panniantong/agent-eyes.git` |
|
| `agent-eyes doctor` | Show what's working |
|
||||||
| Base setup | `agent-eyes install --env=<local\|server>` |
|
| `agent-eyes configure exa-key KEY` | Unlock web/Reddit/Twitter search |
|
||||||
| Add Exa key | `agent-eyes configure exa-key YOUR_KEY` |
|
| `agent-eyes configure twitter-cookies TOKEN CT0` | Unlock Twitter deep search |
|
||||||
| Add Twitter | `agent-eyes configure twitter-cookies AUTH_TOKEN CT0` |
|
| `agent-eyes configure xhs-cookie COOKIE` | Unlock XiaoHongShu |
|
||||||
| Add YouTube | `agent-eyes configure youtube-cookies chrome` |
|
| `agent-eyes configure youtube-cookies chrome` | Unlock age-restricted YouTube |
|
||||||
| Add XiaoHongShu | `agent-eyes configure xhs-cookie COOKIE_STRING` |
|
| `agent-eyes configure proxy URL` | Unlock Reddit + Bilibili (server) |
|
||||||
| Add proxy | `agent-eyes configure proxy http://user:pass@ip:port` |
|
| `agent-eyes read <url>` | Read any URL |
|
||||||
| Health check | `agent-eyes doctor` |
|
| `agent-eyes search "query"` | Search the web |
|
||||||
| Read URL | `agent-eyes read <url>` |
|
|
||||||
| 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"` |
|
|
||||||
|
|||||||
Reference in New Issue
Block a user