- Twitter _read_jina now detects unusable X.com responses (JS-required pages)
and shows a friendly error instead of garbage HTML
- CLI read command now shows user-friendly messages for invalid URLs
and connection errors instead of raw HTTP exception traces
Before: everything under tier 0 showed ✅ with vague descriptions
After: each channel shows its actual capability and limitations
Changes:
- GitHub: 'Public repos only. Set github_token for private repos'
- Twitter: shows 'Full access' vs 'Read-only' depending on birdx
- Bilibili: ⚠️ warning on servers about potential IP blocks
- XiaoHongShu: friendly message when no cookie (was showing Jina 451)
- Doctor format: tier 0 items now show detailed status messages, not just ✅
- README: platform table updated to match reality (removed exaggerated claims)
- README: doctor example updated to show new honest format
Bug 1: Reddit 403 due to short User-Agent in proxy test
Root cause: configure proxy test used 'Mozilla/5.0' (too short, Reddit rejects)
Fix: use full UA string matching the channel implementation
Bug 2: Reddit URL parsing broke on trailing slashes
Root cause: url.rstrip('/') + '.json' mangled URLs with query params
Fix: properly parse URL, clean path, reconstruct json URL
Bug 3: Reddit 403 without proxy showed raw HTTP error
Root cause: no error handling for 403/429 responses
Fix: friendly message suggesting proxy setup + Exa search alternative
Bug 4: XiaoHongShu without cookie showed Jina Reader 451 error
Root cause: fallback to Jina Reader which can't access XHS (legal block)
Fix: show clear message about needing cookies with setup instructions
Bug 5: Empty search query caused raw 422 API error
Root cause: no input validation before API call
Fix: check for empty query, show friendly message
All 36 unit tests passing.
Bug 1: search-github/search-twitter silently returned empty
Root cause: result printing code was inside except block (never reached on success)
Fix: moved result display code outside try/except
Bug 2: Bilibili returned empty content when server IP is blocked
Root cause: API returns code -404 but code treated it as success with empty data
Fix: check API response code, show friendly message with proxy setup hint
Also: GitHub search results now correctly show stars/forks/language from extra dict
All found through real-usage E2E testing (not just install/config testing).
Changes:
1. browser-cookie3 now in default deps (no separate pip install)
2. install --env=auto now auto-imports cookies on local computers
3. install auto-detects EXA_API_KEY from environment variables
4. install.md cut from 100 lines to 60 lines — two steps not five
Before: pip install → agent-eyes install → 'want search?' → 'want cookies?' → configure each
After: pip install → agent-eyes install (does everything automatically) → only ask about what's missing
Docker clean-room test: all passing, 0 bugs.
Major change: README now opens with a complete platform table showing:
- ALL 9 supported platforms
- What each can do (read/search/post/reply/like/collect)
- Configuration difficulty (零配置/免费Key/Cookie/代理)
- Which open-source tool powers each one
Key additions:
- Twitter: not just read — can post tweets and reply (via birdx)
- XiaoHongShu: full operations — post, comment, like, collect, search
- Sorted by importance: Web → Twitter → XHS → Search → GitHub → YouTube → Bilibili → RSS → Reddit
Round 1: Problem-solution structure, showcase underlying tools
Round 2: Too verbose - 4 'can't do' examples is repetitive, tightened
Round 3: Compact doctor output, restored quick-reference table,
cut code examples to essentials
Round 4: Opening paragraph tighter - one sentence for all pain points
Key: README doesn't say 'we can read URLs' (every tool does that).
It says 'here are the best open-source tools for each platform,
we glued them together so you install once and get everything.'
Core insight from Neo: 'reading a URL is not a feature — every AI tool does that'
New approach: introduce each underlying project and what makes it special:
- Jina Reader (9.8K⭐): any URL → clean Markdown, handles JS rendering
- yt-dlp (148K⭐): subtitles from 1800+ video sites, not just YouTube
- Exa: neural semantic search, not keyword matching
- birdx: Twitter without expensive API Key, just browser cookies
- feedparser (2.3K⭐): universal RSS/Atom parser
Framing: 'We find the best wheel for each job, then attach them all to your Agent'
Chinese README polished 3 rounds:
- Round 1: direct translation
- Round 2: too dry, too many tables, too technical
- Round 3: conversational tone, scenario-driven, collapsible details
Key improvements:
- Opens with WHY not WHAT ('你的Agent很聪明，但是看不见')
- Install section explains WHERE to paste for newbies
- Features shown as bullet list not tables (better visual scan)
- Architecture hidden in collapsible section (most users don't care)
- 'Why Agent Eyes' section explains positioning clearly
- English version at docs/README_en.md
1. Install command: git+... requires git (many envs don't have it)
→ Changed to zip URL: pip install .../archive/main.zip
2. yt-dlp not in dependencies (shows warning in doctor)
→ Added yt-dlp to required dependencies
3. search-twitter/reddit shows raw 401 error without Exa key
→ Now shows friendly 'Exa API key not configured' message
Key improvements:
- twitter-cookies now accepts BOTH formats:
1. Full cookie header string from Cookie-Editor export
2. Two separate values (auth_token ct0)
Automatically detects which format was pasted.
- New docs/cookie-export.md guide for server users
Recommends Cookie-Editor Chrome extension (one-click export)
Fallback: manual F12 → Network → Cookie header
- Install guide now has two clear paths:
Path A (local): --from-browser chrome (one command, all cookies)
Path B (server): Cookie-Editor extension export (30 sec per site)
- Better error messages with accepted format examples
New: agent-eyes configure --from-browser chrome
- Extracts Twitter, XiaoHongShu, Bilibili cookies in ONE command
- No F12, no manual copying, no extension needed
- Supports: chrome, firefox, edge, brave, opera
- Uses browser-cookie3 (optional dependency: pip install agent-eyes[cookies])
Install guide now 3x shorter:
1. pip install + agent-eyes install (auto-detect env)
2. agent-eyes configure --from-browser chrome (one-click all cookies)
3. agent-eyes configure exa-key KEY (one API key)
4. Done
User actions reduced from 4 trips to 2:
- Before: go to exa.ai + F12 Twitter + F12 XHS + go to webshare.io
- After: go to exa.ai + say 'yes' to auto-import cookies
- Recommend Cookie-Editor browser extension as easiest cookie export method
- Step 1 is now literally ONE command (install + auto-detect combined)
- Only ONE question after install: 'want search? here's a free key'
- Additional channels are 'just ask anytime', not a menu to read through
- YouTube cookies only mentioned if user actually needs age-restricted content
- Cut guide from 100 lines to ~90 lines, much more scannable
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.
Major install flow polish:
- Channels organized by setup difficulty:
🟢 Zero-config (Web, GitHub, RSS) — works immediately
🔵 Cookie-based (Twitter, YouTube, Bilibili, XiaoHongShu) — free, ~2min
🟡 Free API key (Exa Search) — one key, 30 seconds
🟠 Proxy-based (Reddit, Bilibili on server) — $1/month
- Every channel explains: what it does, what's needed, what you miss without it
- Server vs local affects which channels need proxy
New: XiaoHongShu channel (cookie-based, falls back to Jina Reader)
New configure commands: twitter-cookies, xhs-cookie, youtube-cookies
Each command auto-tests after saving.
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
New commands:
- agent-eyes install --env=<local|server> --search=<yes|no> [--proxy=URL] [--exa-key=KEY]
One-shot installer with explicit flags. No ambiguity.
- agent-eyes configure <key> <value>
Set exa-key/proxy/github-token/groq-key with auto-testing.
e.g. 'agent-eyes configure exa-key xxx' → saves + tests API
Rewrote install.md as strict decision tree:
1. Ask 3 questions → get flags
2. pip install
3. Run ONE install command with flags
4. Configure keys with configure command (auto-tests each)
5. Verify with doctor
Inspired by oh-my-opencode's deterministic installer pattern.
Install guide now asks: local computer or server?
- Server users get proactive guidance on Reddit/Bilibili proxy (/mo Webshare)
- Bilibili channel now supports proxy config (bilibili_proxy)
- Updated step numbering in install guide
Users just paste one line to their AI Agent:
'Install Agent Eyes: https://raw.githubusercontent.com/Panniantong/agent-eyes/main/docs/install.md'
The Agent reads the guide, installs, configures, and reports back.
Inspired by oh-my-opencode's installation flow.
Also updated README: new tagline, architecture diagram reflects
pure-glue design, updated credits.
scripts/sync-upstream.sh checks for changes in x-reader's fetchers/
and shows which reader files have upstream updates. Handles import
path differences (x_reader.fetchers → agent_eyes.readers) automatically.
- CLI now suppresses loguru INFO logs by default (use -v/--verbose to show)
- Fixed birdx output parser to correctly extract author, url, date, text
- birdx search now uses plain text output (--json returns empty arrays)
Bugs found during fresh pip install testing:
- readers/*.py still referenced agent_eyes.fetchers → fixed to agent_eyes.readers
- reader.py passed 'author'/'metadata' to UnifiedContent which doesn't have those → use 'extra' field
- RSS URL detection missed domains containing 'rss' (e.g. hnrss.org)
